ph-haptics 0.1.0

Host-compiled haptics DSL and no-std, no-alloc scheduling runtime modeling ERM and LRA motors using ph-curves
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

# Architecture: compiler, scheduler, and adapter boundary


## Foundational principle


`ph-haptics` converts declarative haptic patterns into deterministic motor-control commands. Its product boundary contains a host compiler and an embedded-compatible evaluator/scheduler; it ends at the abstract `DriveCommand` returned to consuming firmware.

The embedded runtime is `no_std` and `no_alloc`: it uses only `core` plus `ph-curves` with default features disabled. Host-side `.phh` and profile compilation lives behind the optional `gen` feature. The full claims, non-claims, and proof standard are defined in [`contract.md`](contract.md).

## Layer table


| Layer | Location | Input | Output | Boundary |
|---|---|---|---|---|
| Host compiler | `ph-haptics-gen` via `--features gen` | `.phh`, profiles, curve references | Validated static Rust catalog | May use `std`; never enabled in an embedded dependency |
| Embedded runtime | `ph-haptics` default features | Catalog entry, motor configuration, monotonic clock | `Frame` with `DriveCommand` and next deadline | `core` only; no allocation, parsing, or peripheral access |
| Hardware adapter | Consuming firmware, outside this crate | `DriveCommand` | PWM, GPIO, bus, or motor-driver operations | Board-specific and outside the `ph-haptics` contract |

```mermaid
flowchart LR
  Source[".phh + profiles + curves"] --> Compiler["host compiler"]
  Compiler --> Catalog["static Rust catalog"]
  Catalog --> Runtime["embedded evaluator + scheduler"]
  Clock["monotonic clock"] --> Runtime
  Runtime --> Frame["DriveCommand + next deadline"]
  Frame --> Adapter["firmware-owned hardware adapter"]
```

## Package boundary rules


1. **The crate owns commands and timing.** It validates authored patterns and determines which abstract motor command should be active and when it may next change.
2. **Firmware owns actuation.** GPIO, PWM, bus, HAL, motor-driver, electrical, and board integration code remains outside the library.
3. **Never enable `gen` on embedded dependencies.** Embedded consumers use default-feature `ph-haptics`; compilation remains a host build step.
4. **No device package is required to prove the crate.** Crate correctness is established through generated assets, bare-metal compilation, and deterministic command/deadline traces.
5. **Physical behavior is downstream evidence.** Bench and HIL results may validate consuming firmware, but they are not claims made by `ph-haptics`.

## How the contract is enforced


- `src/lib.rs` forbids unsafe code and denies accidental `std`/`alloc` use.
- Local CI checks formatting, host and generator tests, host clippy, bare-metal check/clippy, the dependency feature graph, catalog compilation, a generate-to-compile roundtrip, and the mock-machine command/deadline traces.
- The dependency guard rejects `std` or `alloc` features in the default bare-metal graph.
- Generator tests enforce parsing, validation, include, expansion, profile, and code-generation behavior.
- Runtime tests enforce command values, deadlines, completion, looping, kicks, ramps, frequency sweeps, and clock rollover.
- The host-side mock machine in [`mock/`](https://github.com/photon-circus/ph-haptics/tree/main/mock) demonstrates the authored-pattern to asserted command-trace path; see [`mock/README.md`](https://github.com/photon-circus/ph-haptics/blob/main/mock/README.md).