LinuxCNC S-Curve Accelerations

This is a draft for a new TP implementation plan, revised according to my thinking by AI

---

## LinuxCNC S-Curve Trajectory Planner Rewrite

### Architecture Principles

**RT thread (250µs capable):** Only evaluates pre-computed polynomials. No planning, no Ruckig, no kinematics. Just `position = evaluate_polynomial(t)` and send to drives.

**Userspace:** All heavy computation. Ruckig, backward velocity pass, kinematics, blending. Not tied to servo cycle.

**Predictive Handoff:** When replanning is needed (feed override, etc), userspace plans from a predicted future state, not current state. RT continues executing until the handoff time, then seamlessly transitions. This decouples userspace latency from RT determinism.

**Buffer Management:** Track buffer in TIME, not segment count. Short segments and long segments treated appropriately.

---

### Phase 0: Foundation - Port Tormach 9D Architecture

```
├── 0.1 Port dual-layer architecture (userspace planning / RT execution)
├── 0.2 Port atomic state sharing between layers
├── 0.3 Port 9D vector abstractions
├── 0.4 Port lock-free segment queue
├── 0.5 Port lookahead buffer
├── 0.6 Port backward velocity pass (computeLimitingVelocities)
├── 0.7 Verify trapezoidal works through new architecture
├── 0.8 Verify E-stop works
└── 0.9 Test: motion runs, velocity anticipates corners
```

Meeting with Robert Ellenberg on the 28th should clarify what's clean to port vs what needs adaptation.

---

### Phase 1: Move Kinematics to Userspace

```
├── 1.1 Userspace samples path, computes Jacobian
├── 1.2 Joint limit pre-calculation (YangYang)
├── 1.3 Joint limits fed into backward velocity pass
├── 1.4 RT receives joint-space polynomial segments
├── 1.5 Test on non-trivial kinematics (5-axis, etc)
└── 1.6 Verify E-stop works
```

This is the risky phase. State consistency between userspace and RT must be bulletproof.

---

### Phase 2: Ruckig Integration

```
├── 2.1 Add Ruckig to build system
├── 2.2 Backward pass computes v_entry, v_exit per segment
├── 2.3 Forward pass: Ruckig solves each segment with entry/exit constraints
├── 2.4 Output: joint-space polynomials to RT queue
├── 2.5 Scrap sp_scurve.c (current S-curve implementation)
├── 2.6 Test: globally optimal jerk-limited velocity profiles
└── 2.7 Verify E-stop works
```

Ruckig runs in userspace only. Takes ~1ms per solve. RT never waits for it.

---

### Phase 3: Predictive Handoff System

```
├── 3.1 RT continuously publishes execution state (segment ID, time within segment)
├── 3.2 Define buffer time parameters in INI:
│ MIN_BUFFER_TIME_MS = 100 (RT warns if below)
│ TARGET_BUFFER_TIME_MS = 200 (userspace maintains this)
│ MAX_BUFFER_TIME_MS = 500 (userspace pauses if above)
├── 3.3 Define HANDOFF_HORIZON_MS = 50 (how far ahead to plan handoff point)
├── 3.4 Implement TIME-based buffer level tracking
├── 3.5 Adaptive throttling: userspace speeds up if buffer runs thin
├── 3.6 Predictive handoff flow:
│ a) Feed override changes (or other replan trigger)
│ b) Userspace picks T_handoff = now + HANDOFF_HORIZON
│ c) Userspace evaluates current trajectory at T_handoff to get predicted state
│ d) Ruckig plans from predicted state to target with new constraints
│ e) New segments tagged with handoff time, pushed to queue
│ f) RT executes old trajectory until T_handoff, then switches seamlessly
├── 3.7 Test: rapid feed override changes, verify smooth transitions
├── 3.8 Test: userspace delays (artificial), verify RT never starves
└── 3.9 Verify E-stop works
```

Key insight: 100ms feed override latency is invisible to humans. RT starvation is catastrophic. Plan ahead, never make RT wait.

---

### Phase 4: Blending

```
├── 4.1 Blend geometry using Beziers (not arcs)
│ - Works naturally in 9D (arcs are fundamentally 2D)
│ - Faster to evaluate (polynomial vs sin/cos)
│ - Smoother curvature transitions (no curvature discontinuity at entry/exit)
│ - Steadier velocity through corners
├── 4.2 Blend size respects G64 P tolerance (same contract as current LinuxCNC)
├── 4.3 Blend velocity limits feed into backward pass
├── 4.4 Ruckig solves blend segments
├── 4.5 Test: continuous cutting, no velocity bobbing through corners
└── 4.6 Verify E-stop works
```

---

### Phase 5: Hardening

```
├── 5.1 Test with artificial userspace delays (verify RT never blocks)
├── 5.2 Test at 250µs servo period
├── 5.3 Singularity handling (automatic slowdown near singularities, no faults)
├── 5.4 Edge cases: very short segments, reversals, exact stop (G61)
├── 5.5 Spindle sync moves (rigid tap, threading) - automatic fallback to trapezoidal
├── 5.6 Probe moves - automatic fallback to trapezoidal
├── 5.7 HAL pin for manual planner_type selection (user can force trapezoidal via M-code)
├── 5.8 Stress test: worst case G-code with rapid feed override changes
└── 5.9 Final E-stop verification under all conditions
```

Trapezoidal fallback stays for special cases. Some operations need tight timing that S-curve planning would compromise.

---

### Phase 6: Cleanup

```
├── 6.1 Remove dead code from tp.c (old S-curve paths)
├── 6.2 Remove sp_scurve.c, sp_scurve.h entirely
├── 6.3 Update HAL pins:
│ - jerk-cmd outputs
│ - planner status
│ - buffer level (time remaining)
│ - handoff state
├── 6.4 Update documentation
├── 6.5 INI file changes:
│ - JERK_LIMIT per axis
│ - MIN_BUFFER_TIME_MS
│ - TARGET_BUFFER_TIME_MS
│ - MAX_BUFFER_TIME_MS
│ - HANDOFF_HORIZON_MS
│ - Deprecate old parameters
└── 6.6 Backward compatibility: PLANNER_TYPE=0 still works (pure trapezoidal)
```

---

### Summary of Key Design Decisions

| Decision | Rationale |
|

---

|

---

|
| RT only evaluates polynomials | 250µs determinism, no jitter |
| Ruckig in userspace only | Heavy math stays out of RT |
| Predictive Handoff | Decouples userspace latency from RT timing |
| TIME-based buffer | Handles short and long segments correctly |
| Beziers for blending | 9D native, faster, smoother than arcs |
| Trapezoidal fallback | Threading, tapping, probing need it |
| E-stop verified every phase | Can't wait until the end |

Any feedback will be considered, and appreciated, this is obviously a plan far from being set in stone, just a wild idea at the moment...

Sure, we're glad to get all the help we can get, this is just in the idea phase for now, so even just useful input would be nice, YangYang is not on board yet, it is just my idea at the moment, but I am not forcing it down anyone's throat, this has to be scrutinized by who understands more than me, or have different point of view on things, Grotius YangYang Robert ihavenofish, really I welcome all input, it should not be a fight, the correct solution I hope will arise from the collective experience of the community, and who is willing to share it, for the benefit of all.