|
| 1 | +# Faithful timed trajectory |
| 2 | + |
| 3 | +Priority: **070** — later implementation, not v1. |
| 4 | + |
| 5 | +Status: later implementation, not v1. |
| 6 | + |
| 7 | +## Separation |
| 8 | + |
| 9 | +Per `extras/doc/planner_modes.md` this is a **complete distinct implementation**, |
| 10 | +not a `FasNAxis` mode: its own lookahead/block planner, interpolator and |
| 11 | +feeder. Architecturally separate, but code reuse is intended where it |
| 12 | +makes sense — shared conventions (`addQueueEntry` contract, pin setup), |
| 13 | +`SimPort`, the PC test rig, and common helpers factored out rather than |
| 14 | +copied. |
| 15 | + |
| 16 | +## Input / output |
| 17 | + |
| 18 | +- **Input**: a sequence of chunks. Each chunk is `int16_t` delta |
| 19 | + steps per axis and one shared `uint32_t` delta ticks (driver |
| 20 | + ticks, `TICKS_PER_S`, the duration of those steps). |
| 21 | + |
| 22 | + ```c |
| 23 | + bool addDelta(const int16_t steps[N], uint32_t delta_ticks); |
| 24 | + ``` |
| 25 | +
|
| 26 | + There is no absolute waypoint and no time in seconds. A caller |
| 27 | + who sampled a curve a second apart has to turn that into the |
| 28 | + steps that actually occur and the tick count of each piece |
| 29 | + before calling in. One call is one rate: `delta_ticks` is the |
| 30 | + wall time of these steps on every axis, and a speed change is |
| 31 | + the next call. The planner does not invent a ramp across a |
| 32 | + sparse pair of positions. |
| 33 | +
|
| 34 | + `int16_t` is the same step width as `moveTimed`. It caps one |
| 35 | + chunk at 32767 steps on an axis; a longer constant-rate run is |
| 36 | + several calls. `delta_ticks` is `uint32_t`, so one chunk can |
| 37 | + name at most 2^32 − 1 ticks (~268 s at 16 MHz). A chunk that |
| 38 | + long is still one constant rate, not a curve the planner fills |
| 39 | + in. |
| 40 | +
|
| 41 | + All-zero steps and a non-zero `delta_ticks` is a dwell on the |
| 42 | + common clock. A reversal is two chunks; one chunk has one sign |
| 43 | + per axis. |
| 44 | +
|
| 45 | + The 1 ms frame (`moveTimed(Δ, 1 ms)`) is the failure in |
| 46 | + whitepaper §3.3.1 / GitHub #363: 1.5 steps per box alternates |
| 47 | + 1 kHz and 2 kHz. A chunk carries the real duration of its |
| 48 | + steps, and the feeder still emits step-separated periods. |
| 49 | +
|
| 50 | +- **Output**: the same geometry at the requested timing with a |
| 51 | + near-exact step period, using **step-separated** commands: |
| 52 | + - period `τ` from the speed at the point (ticks/step) |
| 53 | + - `τ` short → one command with `steps > 1` at `τ` |
| 54 | + (`steps/duration` **is** the speed) |
| 55 | + - `τ` long → one step plus pauses placed at the right time in the |
| 56 | + interval (not a step at every frame start) |
| 57 | + - track `actual_duration`; the next command adapts (drift) |
| 58 | + - planning covers more than the next millisecond (queue depth) |
| 59 | +
|
| 60 | +## Errors |
| 61 | +
|
| 62 | +A feasibility error can occur **only** with a time-constrained |
| 63 | +trajectory (see `extras/doc/planner_modes.md`): |
| 64 | +
|
| 65 | +- Faster than the AFAP track, or needs a/v the motors cannot do |
| 66 | + smoothly → `TimingNotAchievable` (not `LookaheadTooShort`, not a |
| 67 | + feed-hold). |
| 68 | +- Too slow: stretch by lengthening periods, still hit vertices, still |
| 69 | + G2. |
| 70 | +- Feasibility (§3.3.1): requested duration ≥ `naxis_ref` (a few Δt |
| 71 | + slack); consecutive speeds reachable under `a_max`/`ticks_cfg`; |
| 72 | + issued periods must not hunt by ~2× every millisecond. |
| 73 | +
|
| 74 | +`naxis_ref` is the **duration bound**; smoothness is a second check. |
| 75 | +
|
| 76 | +## Per-block feedrate `F` |
| 77 | +
|
| 78 | +Per-block `F` is a **requested speed**, i.e. timed-world input, and |
| 79 | +therefore belongs to this implementation. In this encoding `F` is the |
| 80 | +chunk itself: the master period is `delta_ticks` over the master's |
| 81 | +`|delta steps|`, in ticks per step, never a value in seconds. The |
| 82 | +block is executed at that rate, and a request the motors cannot |
| 83 | +achieve (faster than the AFAP/`naxis_ref` bound, or needing `a`/`v` |
| 84 | +beyond `ticks_cfg`) is a `TimingNotAchievable` error. There is no |
| 85 | +separate `F`-as-cap variant in the AFAP planner — without a requested |
| 86 | +speed there is simply no `F`. |
| 87 | +
|
| 88 | +Slaves share the chunk's tick sum (G6). A slave is feasible when its |
| 89 | +step count times its period equals `delta_ticks`; the feeder reports |
| 90 | +the quantized `actual_duration` and the next chunk absorbs the drift. |
| 91 | +A too-slow chunk (few steps, large `delta_ticks`) stays legal: one |
| 92 | +step plus pauses, vertices still hit. That is a slow constant rate, |
| 93 | +and it is distinct from a seconds-apart waypoint asking the planner |
| 94 | +to draw the curve in between. |
| 95 | +
|
| 96 | +## Variations |
| 97 | +
|
| 98 | +- **Hard ceiling on `delta_ticks`.** The type still allows a |
| 99 | + one-second constant-rate chunk. A ceiling (queue horizon, a few |
| 100 | + tens of ms) would force resampling even for constant speed. The |
| 101 | + default leaves constant-rate chunks alone and relies on "one call, |
| 102 | + one rate" to keep curves out of the planner. |
| 103 | +- **Reject a ~2× period jump between chunks** as |
| 104 | + `TimingNotAchievable` (the #363 hunt), in addition to the |
| 105 | + AFAP duration bound. |
| 106 | +- **Same `int16_t` step vector as AFAP `addDelta`** |
| 107 | + (`080_delta_steps.md`), so one geometry buffer can feed either |
| 108 | + implementation. Timed adds the tick count; AFAP does not. |
| 109 | +- **Path-level deadline** ("be at `endPath` at this tick") is this |
| 110 | + item. The single-axis form is `080_move_to_eta.md`. |
| 111 | +
|
| 112 | +## References |
| 113 | +
|
| 114 | +- `extras/doc/n_axes_whitepaper.md` §3.2, §3.3, §3.3.1 |
| 115 | +- GitHub issue #363 |
0 commit comments