# qt-py-haptics: Directory Structure Outline

This repository is organized around four major layers from the implementation plan:
1) Embedded firmware, 2) Host communication, 3) OpenVR driver, 4) Integration/deployment.

## Proposed Hierarchy

```text
qt-py-haptics/
├─ .github/
│  └─ workflows/
├─ build/
├─ docs/
│  ├─ Haptic System Implementation Plan.md
│  └─ Research TXT.txt
├─ firmware/
│  └─ qtpy-samd21/
│     ├─ .cargo/
│     ├─ src/
│     ├─ examples/
│     └─ tests/
├─ hardware/
│  ├─ boards/
│  │  └─ qtpy-samd21/
│  ├─ drivers/
│  │  └─ drv2605l/
│  └─ wiring/
├─ host/
│  ├─ hid-cli/
│  │  └─ src/
│  └─ hid-bridge/
│     └─ src/
├─ openvr-driver/
│  └─ rust-haptic-driver/
│     ├─ bin/
│     │  └─ win64/
│     ├─ resources/
│     │  ├─ input/
│     │  └─ localization/
│     └─ src/
├─ shared/
│  └─ haptics-protocol/
│     └─ src/
├─ tests/
│  ├─ integration/
│  └─ latency/
└─ tools/
   ├─ scripts/
   └─ steamvr/
```

## Folder Purposes

### .github/workflows
CI pipelines (firmware checks, host/unit tests, formatting/linting, release packaging).

### build
Generated artifacts, temporary outputs, and local packaging/staging files.

### docs
Architecture docs, protocol notes, calibration procedures, and implementation plans.

### firmware/qtpy-samd21
Rust `no_std` firmware for ATSAMD21 (USB HID + I2C control of DRV2605L).
- `.cargo/`: target config (`thumbv6m-none-eabi`), linker settings.
- `src/`: main firmware modules (USB task, I2C task, command parser).
- `examples/`: bring-up tools (I2C scan, DRV2605L sanity checks).
- `tests/`: embedded-focused test harness patterns and host-driven firmware tests.

### hardware
Hardware-specific assets.
- `boards/qtpy-samd21/`: pin maps, power notes, bootloader/flash instructions.
- `drivers/drv2605l/`: register map references, effect tuning tables.
- `wiring/`: connection diagrams (QT Py ↔ DRV2605L ↔ actuator).

### host
Host-side utilities and communication libraries.
- `hid-cli/`: command-line utility to send and inspect HID packets.
- `hid-bridge/`: reusable Rust library for HID discovery, packet tx/rx, retries.

### openvr-driver/rust-haptic-driver
SteamVR/OpenVR driver DLL project in Rust.
- `src/`: provider/device interface implementation and event handling.
- `resources/input/`: input profile JSON for haptic component bindings.
- `resources/localization/`: localized strings used by SteamVR UI.
- `bin/win64/`: built DLL placement and deploy-ready runtime layout.

### shared/haptics-protocol
Single source of truth for the HID packet schema, command IDs, and encoding helpers used by firmware + host + driver.

### tests
Cross-layer validation.
- `integration/`: end-to-end tests (OpenVR event → HID → firmware behavior).
- `latency/`: timing and jitter benchmarks for haptic response.

### tools
Operational scripts and deployment helpers.
- `scripts/`: utility scripts (format, flash, smoke test, packaging).
- `steamvr/`: driver registration templates and helper assets for `vrpathreg`.

## Notes

- Keep protocol definitions centralized in `shared/haptics-protocol` to avoid drift.
- Keep deployment-facing assets (`manifest`, input profile, localization) under `openvr-driver/rust-haptic-driver/resources`.
- Place generated binaries and temporary build output in `build/` and avoid committing transient files.