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...