---
phase: 04-hid-data-pipeline
plan: 01
subsystem: hid
tags: [hidapi, crc8, tlv, threading, atomic, usb, reconnect]

requires:
  - phase: 02-hid-integration
    provides: "HIDAPI vendored + HidDevice RAII wrapper with Open/Close/IsOpen"
provides:
  - "CRC8 + TLV parser for user signature flash (user_signature.h/cpp)"
  - "CalibrationData struct with firmware defaults"
  - "HidDevice background reader thread with StartReading/StopReading"
  - "Lock-free atomic prox_distance and connection state getters"
  - "Feature report send/receive helpers (65-byte buffers)"
  - "Report rate configuration via 'R' command"
  - "16-block user signature read with '#' report filtering"
  - "USB disconnect detection and 5-second reconnect loop"
affects: [05-proximity-algorithm, 06-steamvr-integration]

tech-stack:
  added: [std::thread, std::atomic, std::mutex]
  patterns: [self-contained-reader-thread, atomic-cache-pattern, tlv-crc8-validation]

key-files:
  created:
    - src/hid/user_signature.h
    - src/hid/user_signature.cpp
  modified:
    - src/hid/hid_device.h
    - src/hid/hid_device.cpp
    - CMakeLists.txt

key-decisions:
  - "TLV values parsed as little-endian (ARM native), periodic report prox_distance as big-endian"
  - "CalibrationData protected by mutex; prox_distance and connection state use lock-free atomics"
  - "Reconnect sleep uses 50ms x 100 increments for responsive thread shutdown"

patterns-established:
  - "Self-contained reader thread: all HID I/O inside thread, consumers read atomic cache"
  - "Feature report pattern: 65-byte buffer (report ID 0x00 + 64 data), response via hid_read_timeout"
  - "TLV+CRC8 validation: skip bad entries, use defaults for missing tags"

requirements-completed: [HID-02, HID-03, HID-04, HID-05]

duration: 3min
completed: 2026-03-22
---

# Phase 04 Plan 01: HID Data Pipeline Summary

**Self-contained HID reader thread with TLV+CRC8 calibration parser, 500ms periodic report reading, rate configuration via feature reports, and automatic USB reconnect**

## Performance

- **Duration:** 3 min
- **Started:** 2026-03-22T13:44:00Z
- **Completed:** 2026-03-22T13:47:23Z
- **Tasks:** 2
- **Files modified:** 5

## Accomplishments
- Created CRC8 and TLV parser (user_signature.h/cpp) that extracts calibration parameters from 512-byte user signature flash
- Extended HidDevice with background reader thread that reads periodic '#' reports, extracts prox_distance (bytes 4-5 big-endian), and caches via atomic store
- Implemented full HID command/response protocol: feature report send, rate config, 16-block signature read with interleaved periodic report filtering
- Added USB disconnect detection (hid_read returns -1) with automatic 5-second reconnect loop that re-reads calibration and re-sets report rate

## Task Commits

Each task was committed atomically:

1. **Task 1: Create user_signature.h/cpp with CRC8, TLV parser, and CalibrationData** - `40f9e1f` (feat)
2. **Task 2: Extend HidDevice with reader thread, feature reports, calibration read, rate config, and reconnect** - `4a6180a` (feat)

## Files Created/Modified
- `src/hid/user_signature.h` - CRC8 function, SigTag enum, CalibrationData struct, ParseCalibration declaration
- `src/hid/user_signature.cpp` - CRC8 implementation (poly 0x07, init 0xFF), TLV parser with CRC validation
- `src/hid/hid_device.h` - Extended with reader thread members, atomic state, mutex, new public/private methods
- `src/hid/hid_device.cpp` - Reader thread, feature report helpers, calibration read, rate config, reconnect loop
- `CMakeLists.txt` - Added user_signature.h/cpp to driver target sources

## Decisions Made
- TLV values parsed as little-endian (ARM Cortex-M4 native byte order), only periodic report prox_distance is big-endian
- CalibrationData uses mutex protection (not atomic-safe struct), while prox_distance and connection state use lock-free std::atomic for zero-overhead reads from RunFrame
- Reconnect sleep split into 50ms x 100 increments (not single 5s sleep) so thread responds to stop requests within 50ms

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness
- HidDevice now provides cached prox_distance via GetProxDistance() and calibration via GetCalibration() -- ready for Phase 5 proximity algorithm
- DeviceProvider needs to call StartReading() in Init() and StopReading() in Cleanup() (Phase 4 Plan 2 scope)
- Pipe 'status' command needs extension to expose calibration values (Phase 4 Plan 2 scope)

---
*Phase: 04-hid-data-pipeline*
*Completed: 2026-03-22*