Skip to content

Commit 6b68e55

Browse files
committed
Rename addLine to addWaypoint and document naxes in Readme
Add an inline FasNAxis usage example plus HORIZON notes, mark the API experimental with timed trajectories still TODO, define AFAP, and point to the library-wide open-items list in extras/todo. Rename FasNAxis::addLine to addWaypoint since it appends an absolute trajectory point, not a line segment.
1 parent 26d2035 commit 6b68e55

11 files changed

Lines changed: 172 additions & 99 deletions

File tree

‎README.md‎

Lines changed: 69 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -93,9 +93,11 @@ The full ESP32 driver comparison (MCPWM/PCNT vs RMT vs I2S Mux) is in
9393
* Command queue can be filled with commands and then started. This allows near
9494
synchronous start of several steppers for multi axis applications.
9595
* **EXPERIMENTAL** multi-axis planner `FasNAxis` (`src/FasNAxis.h`): drives N
96-
stepper queues from one polyline so the axes stay time-synchronized. See the
97-
[n-axis whitepaper](extras/doc/n_axes_whitepaper.md) and the
98-
[naxes example](examples/naxes/README.md).
96+
stepper queues from one polyline so the axes stay time-synchronized. API not
97+
stable yet; timed trajectories are still TODO. See the
98+
[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).
99101

100102
## Quick Start
101103

@@ -130,6 +132,69 @@ void loop() {
130132
More details in [Usage](extras/doc/usage.md) and the
131133
[UsageExample.ino](examples/UsageExample/UsageExample.ino).
132134

135+
## Multi-axis planner (FasNAxis)
136+
137+
> **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.
145+
146+
For coordinated motion, `FasNAxis` drives N stepper queues from one polyline
147+
so the axes stay time-synchronized. The hot path has no float, division, or
148+
64-bit integers. Full example: [examples/naxes](examples/naxes/README.md); the
149+
theory is in the [n-axis whitepaper](extras/doc/n_axes_whitepaper.md).
150+
151+
`FasNAxis` is `FasNAxis<NAXES, HORIZON = 64, Stepper = FastAccelStepper,
152+
Engine = FastAccelStepperEngine>` (`src/FasNAxis.h`). `HORIZON` caps how many
153+
future polyline points are buffered and planned: a small value slows the track
154+
(a speed cap, never an error — see `isSpeedLimitedByLookahead()`), a larger one
155+
smooths the ramp at the cost of RAM.
156+
157+
```cpp
158+
#include "FastAccelStepper.h"
159+
#include "FasNAxis.h" // not pulled in by FastAccelStepper.h
160+
161+
FastAccelStepperEngine engine = FastAccelStepperEngine();
162+
FastAccelStepper* axes[2] = {NULL, NULL};
163+
FasNAxis<2, 32> planner(FasNAxisConfig{}, engine); // 2 axes, HORIZON = 32
164+
165+
void setup() {
166+
engine.init();
167+
axes[0] = engine.stepperConnectToPin(9);
168+
axes[1] = engine.stepperConnectToPin(10);
169+
for (uint8_t i = 0; i < 2; i++) {
170+
axes[i]->setDirectionPin(5 + i);
171+
axes[i]->setSpeedInHz(4000); // steps/s
172+
axes[i]->setAcceleration(2000); // steps/s²
173+
planner.addAxis(i, axes[i]);
174+
}
175+
planner.setLimitsFromSteppers(); // freeze v_max / a_max per axis
176+
177+
int32_t origin[2] = {0, 0};
178+
planner.setCurrentPosition(origin); // open the path at the current position
179+
}
180+
181+
void loop() {
182+
// Append exact-chord target vertices; backpressures when HORIZON is full.
183+
static const int32_t path[][2] = {
184+
{1000, 0}, {1000, 1000}, {0, 1000}, {0, 0}};
185+
static uint8_t wp = 0;
186+
if (wp < 4) {
187+
if (planner.addWaypoint(path[wp])) {
188+
wp++;
189+
}
190+
if (wp == 4) {
191+
planner.endPath(); // last point is rest
192+
}
193+
}
194+
planner.pump(); // plan and feed the committed path into the queues
195+
}
196+
```
197+
133198
## Documentation
134199

135200
| Topic | Document |
@@ -147,6 +212,7 @@ More details in [Usage](extras/doc/usage.md) and the
147212
| Pico PIO program flow | [pico_pio.md](extras/doc/pico_pio.md) |
148213
| SAMD51 design notes | [samd51/CONTEXT.md](extras/doc/samd51/CONTEXT.md) |
149214
| 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) |
150216
| Physical stepper simulation | [physical_stepper_whitepaper.md](extras/doc/physical_stepper_whitepaper.md) |
151217
| Test strategy | [testing.md](extras/doc/testing.md) |
152218
| Troubleshooting | [troubleshooting.md](extras/doc/troubleshooting.md) |

‎examples/naxes/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ The path is fixed and deterministic, so a run is comparable to the next:
1919
cube footprint on a two-axis build).
2020
* **return to origin** — a direct line back to the start position.
2121

22-
The planner runs in **Linear** mode: each `addLine()` target is an exact-chord
22+
The planner runs in **Linear** mode: each `addWaypoint()` target is an exact-chord
2323
vertex, so the realized curve is the polygon through the vertices. The geometry
2424
detector reconstructs that polygon from the `Step`/`Dir` pin traces.
2525

‎examples/naxes/naxes.ino‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -66,8 +66,8 @@ FastAccelStepper* naxes_s[NAXES_HW] = {NULL};
6666
// two-axis build and 48 on the three-axis one.
6767
FasNAxis<NAXES_HW, NAXES_HORIZON> naxes_planner(FasNAxisConfig{}, engine);
6868

69-
// Index of the waypoint currently being commanded. 0 is the first addLine after
70-
// the origin; the run finishes when it reaches total_waypoints().
69+
// Index of the waypoint currently being commanded. 0 is the first addWaypoint
70+
// after the origin; the run finishes when it reaches total_waypoints().
7171
static uint16_t naxes_wp_index = 0;
7272
// The path is fully emitted and the queues have drained.
7373
static bool naxes_done = false;
@@ -108,8 +108,9 @@ static int32_t q_axis(int q, int16_t mag, int16_t rad, bool x_axis) {
108108

109109
// Absolute target (one entry per axis) of the i-th waypoint of the fixed path,
110110
// computed on the fly so the whole curve costs only a few words of RAM. The
111-
// origin (index 0 of the addLine sequence) is established by setCurrentPosition
112-
// in setup(); total_waypoints() counts the addLine targets that follow.
111+
// origin (index 0 of the addWaypoint sequence) is established by
112+
// setCurrentPosition in setup(); total_waypoints() counts the addWaypoint
113+
// targets that follow.
113114
void waypoint_target(uint16_t i, int32_t* t) {
114115
t[0] = 0;
115116
t[1] = 0;
@@ -236,12 +237,12 @@ void setup() {
236237
void loop() {
237238
if (!naxes_done) {
238239
// Feed the next waypoint target, but only when the planner's ring has room.
239-
// addLine() drains as the queues run, so this one target per pass keeps the
240-
// ring from filling.
240+
// addWaypoint() drains as the queues run, so this one target per pass keeps
241+
// the ring from filling.
241242
if (naxes_wp_index < total_waypoints()) {
242243
int32_t t[NAXES_HW] = {0};
243244
waypoint_target(naxes_wp_index, t);
244-
if (naxes_planner.addLine(t)) {
245+
if (naxes_planner.addWaypoint(t)) {
245246
naxes_wp_index++;
246247
if (naxes_wp_index >= total_waypoints()) {
247248
naxes_planner.endPath();

‎examples/naxes/naxes_path.h‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,11 @@
1414
// build this is the "cube" degenerate, still four corners).
1515
// 4. return - a direct line back to the origin, the start of the path.
1616
//
17-
// The geometry is exact-chord (Line mode): each addLine() target is a vertex,
18-
// so the realized curve is the polygon through the vertices. The simavr/PC test
19-
// reconstructs this polygon from the Step/Dir pin traces and checks that the
20-
// realized vertices match NAXES_PATH[] and that the run ends at the origin.
17+
// The geometry is exact-chord (Line mode): each addWaypoint() target is a
18+
// vertex, so the realized curve is the polygon through the vertices. The
19+
// simavr/PC test reconstructs this polygon from the Step/Dir pin traces and
20+
// checks that the realized vertices match NAXES_PATH[] and that the run ends at
21+
// the origin.
2122

2223
// Circle / polygon radius in steps.
2324
#define NAXES_RADIUS 400
@@ -49,7 +50,7 @@
4950
#define NAXES_HEX_Y (NAXES_RADIUS * 866L / 1000)
5051

5152
// The path is built at runtime in naxes.ino from these constants so the same
52-
// constants drive both the commanded addLine() targets and the expected
53+
// constants drive both the commanded addWaypoint() targets and the expected
5354
// reconstruction, keeping the two sides identical.
5455

5556
// The helix is emitted as a table of vertices by the caller; this file only

‎extras/doc/implemented/naxes_example_smoothness.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,9 @@ points land exactly on the helix vertices and the run is underrun-free
2121

2222
After P1 and P2 the simavr run still showed 15 stops, and the excess four
2323
were not ramp or geometry: they sat on helix vertices 63/64 and 127/128.
24-
`FasNAxis`'s block array only grew (`_n_blk++` in `addLine`) and was
24+
`FasNAxis`'s block array only grew (`_n_blk++` in `addWaypoint`) and was
2525
never compacted, so after `HORIZON` points had *ever* been appended
26-
`addLine` back-pressured until the whole buffered plan drained and
26+
`addWaypoint` back-pressured until the whole buffered plan drained and
2727
`pump()` reset the ring. The 155-point path was therefore executed in
2828
chunks of `HORIZON = 64`, each ramping to rest at its end (the entry
2929
into the next chunk re-accelerated from 0). `compact_ring()` now drops
@@ -36,7 +36,7 @@ window of at most `HORIZON` *pending* points as whitepaper §8 describes.
3636
masters keep `P`); the square corners stay legitimate stops. Done.
3737
2. `feeder_command_batching.md` keeps AVR/ESP32 queues from draining at
3838
the application's `pump()` interval. Done.
39-
3. `FasNAxis::addLine()` slides the block ring, so a path longer than
39+
3. `FasNAxis::addWaypoint()` slides the block ring, so a path longer than
4040
`HORIZON` no longer ramps to rest at each ring boundary. Done.
4141
4. Re-run `extras/tests/simavr_based/test_naxes` and tune
4242
`MAX_PATH_STOPS` in `detect_geometry.py` to the legitimate stops

‎extras/doc/n_axes_whitepaper.md‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1156,7 +1156,7 @@ integer `R`, not 500 slices.
11561156

11571157
`HORIZON` (the second template argument, default 64 on MCU)
11581158
is the max number of **n-dim points**, not of steps. One
1159-
10 000-step `addLine` with `HORIZON = 8` still has `R = 10000`
1159+
10 000-step `addWaypoint` with `HORIZON = 8` still has `R = 10000`
11601160
and can reach `P_stop`. A stream of 1-step micro-segments
11611161
cannot: `R ≤ HORIZON`, so `P` stays small. That is the
11621162
lookahead–speed relation. It is **not** a configuration
@@ -1311,7 +1311,7 @@ Tests: F11 dribbles waypoints so `R < P_stop` while the
13111311
path is open — motion continues at the `R`-capped speed,
13121312
`pump()` stays `Running`, `P ≤ R`, cruise only after `R`
13131313
grows. F19 is a small `HORIZON` of micro-segments: same
1314-
cap, `addAxis` succeeds; contrast one long `addLine` with
1314+
cap, `addAxis` succeeds; contrast one long `addWaypoint` with
13151315
the same `HORIZON`, which *can* reach `P_stop`.
13161316

13171317
### 8.8 Reversals of a single axis
@@ -1631,7 +1631,7 @@ class FasNAxis {
16311631
void syncFromSteppers(); // p[] from stepper positions
16321632
void setCurrentPosition(const int32_t p[NAXES]);
16331633

1634-
void addLine(const int32_t p[NAXES]); // absolute positions, steps
1634+
void addWaypoint(const int32_t p[NAXES]); // absolute positions, steps
16351635
bool addDwellTicks(uint32_t ticks); // zero-displacement block; v=0 at both ends
16361636
void endPath(); // decelerate to rest at last p
16371637

@@ -1661,10 +1661,10 @@ zeroed config still means “default slice”, not a zero-duration
16611661
slice). Same for `kappa_stop_q8 == 0` → 320 (diagnostic only).
16621662
`overshoot_max == 0` is Linear-like cap and is legal.
16631663
1664-
`addLine` to the current position (`L = 0`, every `Δ_i = 0`) is a
1664+
`addWaypoint` to the current position (`L = 0`, every `Δ_i = 0`) is a
16651665
dwell of 0 ticks (no-op). `addDwellTicks` appends a
16661666
zero-displacement block: lookahead treats it as a path-stop,
1667-
dwells, then the next `addLine` starts from rest. Calling it
1667+
dwells, then the next `addWaypoint` starts from rest. Calling it
16681668
mid-path is therefore a planned stop-and-wait, not a pause
16691669
command while still moving at speed.
16701670
@@ -1693,7 +1693,7 @@ void setup() {
16931693
path.addAxis(1, y);
16941694
path.syncFromSteppers();
16951695
int32_t a[2] = {10000, 100};
1696-
path.addLine(a);
1696+
path.addWaypoint(a);
16971697
path.endPath();
16981698
}
16991699
@@ -1702,7 +1702,7 @@ void loop() {
17021702
}
17031703
```
17041704

1705-
The first `addLine` is illegal until `syncFromSteppers()` or
1705+
The first `addWaypoint` is illegal until `syncFromSteppers()` or
17061706
`setCurrentPosition()`. FAS positions default to 0, so a machine
17071707
that is not at the origin must sync.
17081708

@@ -1963,7 +1963,7 @@ that violates G1/G2 does not count.
19631963
| F16 | `addAxis` while ramp active | `addAxis` fails; no race with `manageSteppers` | — |
19641964
| F17 | First fill on empty queue | Not underrun; path completes | — |
19651965
| F18 | Linear `(10000, 9000)`, Y 40× slower | Longest is X (DDA master) but Y would exceed `v_max` if X ran at `ticks_x`; Y lengthens `ticks_b`, X scaled down in speed; both axes issue full `\|Δ\|` | XY + v(t) |
1966-
| F19 | `HORIZON` too small to hold `P_stop` as micro-segments | `addAxis` succeeds; `P` never reaches `P_stop`; same `HORIZON` with one long `addLine` *does* coast | v(t) capped |
1966+
| F19 | `HORIZON` too small to hold `P_stop` as micro-segments | `addAxis` succeeds; `P` never reaches `P_stop`; same `HORIZON` with one long `addWaypoint` *does* coast | v(t) capped |
19671967
| F20 | Linear, ~350 waypoints: seeded random, half-circle r=4800 / 190 chords, seeded random; ticks `(4000,8000)` | Globally fastest feasible track (`naxis_ref`): every vertex hit, envelope, `P ≤ R`, master-sense-reversal path-stops on the random walk, cruise through the arc, rebind on the arc (DDA master switches; `P`/`R` stay in path steps) | `test_26_f20.gnuplot` |
19681968

19691969
F7 is the regression sibling of `examples/MoveTimed`. F5 is Linear
@@ -2192,7 +2192,7 @@ After ten chunks are buffered (`R = 8000` at the head, collinear
21922192
so the scan does not stop), `R ≥ P_stop` and the head may coast.
21932193
F11 is that recovery. F19 is the same cap with `HORIZON` too
21942194
small to ever hold 4000 steps of micro-segments: `addAxis`
2195-
succeeds; contrast one 10 000-step `addLine` at the same
2195+
succeeds; contrast one 10 000-step `addWaypoint` at the same
21962196
`HORIZON`, which *can* coast because `R` is steps, not points.
21972197

21982198
A 2-axis first chunk `(800, 400)`, Linear: binder X, `R = 800`

‎extras/tests/pc_based/README_naxes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ F2f–F2h, F3b) are self-contained and compare against `naxis_ref.h`.
4141
| **F13** | `f13_lookahead` | 13 | Queue starve after kick-off: `hasUnderrun()` and `pump()` `Underrun`; pre-starve plot |
4242
| **F14** | `f8_feeder` | 14 | Drift over a 240 000-step move: `|clock_x − clock_y| ≤ 2` |
4343
| **F15** | `f8_feeder` | 15 | Queue room: `queueEntries() ≤ QUEUE_LEN−2`; move completes on `QUEUE_LEN=16` |
44-
| **F16** | `f16_skeleton` | — | `addAxis`/`addLine` legality, config defaults, no-op zero delta, SimPort-backed queries |
44+
| **F16** | `f16_skeleton` | — | `addAxis`/`addWaypoint` legality, config defaults, no-op zero delta, SimPort-backed queries |
4545
| **F17** | `f6_linear_sim` | 17 | First fill on an empty queue is not underrun |
4646
| **F18** | `f7_linear_lookahead` | 18 | `(10000,9000)` with Y 40× slower: X DDA master, Y time-law binds, both issue full `\|Δ\|` |
4747
| **F19** | `f13_lookahead` | 19 | Small `HORIZON` caps P below `P_stop`; same HORIZON with one long block coasts |

0 commit comments

Comments
 (0)