Skip to content

Commit c43ac11

Browse files
committed
docs: renumber todo entries and add new roadmap items
Renumber synchronized_start todos to 050_* and cubic_start to 060_cubic_start. Add new roadmap items for timed trajectory (070), delta steps (080), move_to_eta (080), and end path decel (090). Document implemented engine synchronized start in extras/doc/implemented. Update extras/todo/README.md and README.md.
1 parent 6b68e55 commit c43ac11

15 files changed

Lines changed: 429 additions & 104 deletions

‎README.md‎

Lines changed: 20 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -94,10 +94,10 @@ The full ESP32 driver comparison (MCPWM/PCNT vs RMT vs I2S Mux) is in
9494
synchronous start of several steppers for multi axis applications.
9595
* **EXPERIMENTAL** multi-axis planner `FasNAxis` (`src/FasNAxis.h`): drives N
9696
stepper queues from one polyline so the axes stay time-synchronized. API not
97-
stable yet; timed trajectories are still TODO. See the
97+
stable yet. See the
9898
[n-axis whitepaper](extras/doc/n_axes_whitepaper.md), the
99-
[naxes example](examples/naxes/README.md), and the
100-
[todo list](extras/todo/README.md).
99+
[naxes example](examples/naxes/README.md), and
100+
[Future work](#future-work).
101101

102102
## Quick Start
103103

@@ -135,13 +135,9 @@ More details in [Usage](extras/doc/usage.md) and the
135135
## Multi-axis planner (FasNAxis)
136136

137137
> **Experimental.** The `FasNAxis` API is **not stable yet** and may change
138-
> without notice. It is AFAP-only today (AFAP = "as fast as possible": run the
139-
> polyline as fast as the motors and geometry allow, with no requested speed or
140-
> time). A faithful trajectory **with time steps** (requested feedrate / speed
141-
> at each point) is tracked in
142-
> [`extras/todo/timed_trajectory.md`](extras/todo/timed_trajectory.md). The
143-
> library-wide [open items list](extras/todo/README.md) currently holds only
144-
> n-axis entries, but is not limited to them.
138+
> without notice. It runs a polyline as fast as the motors and geometry allow,
139+
> with no requested speed or time. A trajectory that carries its own timing,
140+
> and the rest of the open work, is listed under [Future work](#future-work).
145141
146142
For coordinated motion, `FasNAxis` drives N stepper queues from one polyline
147143
so the axes stay time-synchronized. The hot path has no float, division, or
@@ -212,7 +208,7 @@ void loop() {
212208
| Pico PIO program flow | [pico_pio.md](extras/doc/pico_pio.md) |
213209
| SAMD51 design notes | [samd51/CONTEXT.md](extras/doc/samd51/CONTEXT.md) |
214210
| n-axis whitepaper | [n_axes_whitepaper.md](extras/doc/n_axes_whitepaper.md) |
215-
| Open items (TODO) | [extras/todo/README.md](extras/todo/README.md) |
211+
| Future work | [extras/todo/README.md](extras/todo/README.md) |
216212
| Physical stepper simulation | [physical_stepper_whitepaper.md](extras/doc/physical_stepper_whitepaper.md) |
217213
| Test strategy | [testing.md](extras/doc/testing.md) |
218214
| Troubleshooting | [troubleshooting.md](extras/doc/troubleshooting.md) |
@@ -251,6 +247,19 @@ are defined in `pd_*/pd_config.h` files, which are included by
251247
* TODO / roadmap: [GitHub project](https://github.com/gin66/FastAccelStepper/projects/1)
252248
* Known issues and debugging tips: [troubleshooting.md](extras/doc/troubleshooting.md)
253249

250+
## Future work
251+
252+
Open work is one file per item in
253+
[`extras/todo`](extras/todo/README.md). The filename prefix is the priority,
254+
three digits wide (`050_name.md`). Numbers step by 10, so a new item can take
255+
a free number between two existing ones.
256+
257+
The list is library-wide. It currently covers per-platform synchronized
258+
start, a cubic ramp start, a timed multi-axis trajectory, delta-step input
259+
for `FasNAxis`, a single-axis `moveTo` with an arrival in ticks, and a smooth
260+
stop at the end of a path. The n-axis design is the
261+
[whitepaper](extras/doc/n_axes_whitepaper.md).
262+
254263
## Star History
255264

256265
[![Star History Chart](https://star-history.dera.page/svg?repos=gin66/FastAccelStepper&type=Date)](https://star-history.dera.page/#gin66/FastAccelStepper&Date)

‎extras/doc/implemented/engine_synchronized_start.md‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Engine synchronized start
22

3-
Priority: **P5** — several steppers should begin on one start, not
3+
Priority: **050** — several steppers should begin on one start, not
44
one after another.
55

66
Status: **implemented**. `FasNAxis::pump()` kick-off goes through
@@ -9,12 +9,12 @@ as an engine reference in its constructor. Every platform implements it
99
today as one critical section around a per-stepper
1010
`addQueueEntry(NULL, true)` loop. The per-platform native mechanisms are
1111
tracked in `extras/todo/`:
12-
[AVR](../../todo/avr_synchronized_start.md),
13-
[SAM (Due)](../../todo/sam_synchronized_start.md),
14-
[SAMD51](../../todo/samd51_synchronized_start.md),
15-
[Teensy](../../todo/teensy_synchronized_start.md),
16-
[ESP32](../../todo/esp32_synchronized_start.md),
17-
[Pico](../../todo/pico_synchronized_start.md).
12+
[AVR](../../todo/050_avr_synchronized_start.md),
13+
[SAM (Due)](../../todo/050_sam_synchronized_start.md),
14+
[SAMD51](../../todo/050_samd51_synchronized_start.md),
15+
[Teensy](../../todo/050_teensy_synchronized_start.md),
16+
[ESP32](../../todo/050_esp32_synchronized_start.md),
17+
[Pico](../../todo/050_pico_synchronized_start.md).
1818

1919
## Problem
2020

@@ -60,12 +60,12 @@ The critical-section fallback is in place for every platform. Whether it
6060
is the final mechanism, or a native start primitive should replace it, is
6161
tracked one file per platform in `extras/todo/`:
6262

63-
- [AVR](../../todo/avr_synchronized_start.md)
64-
- [SAM (Due)](../../todo/sam_synchronized_start.md)
65-
- [SAMD51](../../todo/samd51_synchronized_start.md)
66-
- [Teensy](../../todo/teensy_synchronized_start.md)
67-
- [ESP32](../../todo/esp32_synchronized_start.md)
68-
- [Pico](../../todo/pico_synchronized_start.md)
63+
- [AVR](../../todo/050_avr_synchronized_start.md)
64+
- [SAM (Due)](../../todo/050_sam_synchronized_start.md)
65+
- [SAMD51](../../todo/050_samd51_synchronized_start.md)
66+
- [Teensy](../../todo/050_teensy_synchronized_start.md)
67+
- [ESP32](../../todo/050_esp32_synchronized_start.md)
68+
- [Pico](../../todo/050_pico_synchronized_start.md)
6969

7070
## References
7171

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# AVR synchronized start
22

3-
Priority: **P5** — platform-specific part of the engine synchronized start
3+
Priority: **050** — platform-specific part of the engine synchronized start
44
(one item per open platform).
55

66
Status: generic fallback active on AVR

extras/todo/esp32_synchronized_start.md renamed to extras/todo/050_esp32_synchronized_start.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# ESP32 synchronized start
22

3-
Priority: **P5** — platform-specific part of the engine synchronized start
3+
Priority: **050** — platform-specific part of the engine synchronized start
44
(one item per open platform).
55

66
Status: generic fallback active on all ESP32 builds

extras/todo/pico_synchronized_start.md renamed to extras/todo/050_pico_synchronized_start.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Pico synchronized start
22

3-
Priority: **P5** — platform-specific part of the engine synchronized start
3+
Priority: **050** — platform-specific part of the engine synchronized start
44
(one item per open platform).
55

66
Status: generic fallback active on the Pico build
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# SAM synchronized start
22

3-
Priority: **P5** — platform-specific part of the engine synchronized start
3+
Priority: **050** — platform-specific part of the engine synchronized start
44
(one item per open platform).
55

66
Status: generic fallback active on SAM (Due)

extras/todo/samd51_synchronized_start.md renamed to extras/todo/050_samd51_synchronized_start.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# SAMD51 synchronized start
22

3-
Priority: **P5** — platform-specific part of the engine synchronized start
3+
Priority: **050** — platform-specific part of the engine synchronized start
44
(one item per open platform).
55

66
Status: generic fallback active on SAMD51

extras/todo/teensy_synchronized_start.md renamed to extras/todo/050_teensy_synchronized_start.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Teensy synchronized start
22

3-
Priority: **P5** — platform-specific part of the engine synchronized start
3+
Priority: **050** — platform-specific part of the engine synchronized start
44
(one item per open platform).
55

66
Status: generic fallback active on Teensy 4
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Cubic start (`s_h`) overlay
22

3-
Priority: **P6** — later feature, not v1.
3+
Priority: **060** — later feature, not v1.
44

55
Status: later feature, not v1.
66

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
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

Comments
 (0)