cnc-router/PROJECT-PLAN.md

# CNC Router Project Plan — Research → Prototype → Production

> **Repository:** git.paraskeva.net/nearxos/cnc-router
> **Last Updated:** 2026-06-22
> **Status:** Research Phase (∼60% complete); Prototype Phase (∼5% complete)

---

## 1. Executive Summary

This project designs and builds a **rail-free, multi-belt/cable-driven suspended CNC router** for semi-professional woodworking and DIY sheet-goods fabrication. Unlike traditional gantry routers that require massive frames, expensive linear rails, and a dedicated workshop footprint, this machine uses a **surface-riding sled** controlled by 4 or 8 tensioned belts anchored to a lightweight perimeter frame, achieving a large work area (up to 4′×8′/1.2 m×2.4 m) from a highly portable and cost-effective package.

**Why this matters:** Existing solutions force a painful trade-off:
- **Gordix / Maslow 4 / Cubiio X** are portable but either closed-source, mechanically limited (4-belt yaw problems), or extremely expensive per m².
- **Traditional gantry CNCs** offer rigidity and accuracy but require thousands of dollars in frame and rails, plus dedicated floor space.

**Our approach:** Combine the best of both worlds — the portability and workspace flexibility of Gordix/Maslow with the open-source firmware, robust DC servo architecture, and community-validated kinematics of the Maslow 4 ecosystem. The design scales from a $261 1 m×1 m 3D-printable prototype (proof of concept, 4-belt) to a $737 4′×8′ production machine (8-belt Gordix-style with DC geared servos, aluminum sled, and Makita RT0701C).

**Key design decisions:**
- **FluidNC firmware** (open-source ESP32 motion controller) for maximum configurability and custom kinematics
- **8-belt constraint-locked kinematics** for production build (eliminates yaw mathematically without software correction)
- **Custom ESP32-S3 PCB** (v1.0 designed) with 8× TMC2209 stepper drivers, dual UART buses, and Maslow4-compatible pinout
- **Two-phase build:** cheap 1 m×1 m prototype first, then full-scale production sled

---

## 2. Current Status

### 2.1 Completed Research & Design

| Area | Status | Details |
|------|--------|---------|
| **Competitive Analysis** | ✅ Complete | README.md — Gordix, Maslow 4, Cubiio X, Maker Made M2 compared across 15 metrics (kinematics, cost, weight, software, calibration) |
| **Kinematics Simulation** | ✅ Complete | Python simulation of 8-belt Gordix geometry; forward & inverse kinematics validated; workspace heatmap generated (kinematics/, simulate_grid.py, tension_analysis.py) |
| **BOM & Cost Analysis** | ✅ Complete | Two-scale BOM in BOM-Evaluation.md: $261 prototype (1 m×1 m, NEMA 17, 4-belt), $737 production sled (4′×8′, DC servos, 8-belt, Makita router) |
| **PCB v1.0 Schematic** | ✅ Complete | Full netlist in pcb/schematic_netlist.md — ESP32-S3 + 8× TMC2209 + power regulation (24V/5V/3.3V), 4-layer stackup, UART bus topology |
| **FluidNC Machine Config** | ✅ Complete | esp32-s3-pinout.yml — complete machine configuration: dual-motor gantry axes, homing, limits, probe, UART addressing, TMC2209 parameters |
| **Software Pipeline** | ✅ Defined | CAD (Fusion 360/Onshape/Inkscape) → CAM (Kiri:Moto/Estlcam/G-code sender) → FluidNC custom kinematics |

### 2.2 What's Designed but Not Yet Built

| Item | Status | Notes |
|------|--------|-------|
| ESP32-S3 PCB layout (KiCad) | ⬜ Not started | Netlist complete; needs board layout, routing, ERC/DRC |
| Prototype 3D-printed parts | ⬜ Not started | Sled, corner anchors, GT2 spool holders — designed but not printed |
| FluidNC custom kinematics module | ⬜ Not started | The 4-belt/8-belt kinematic transform needs to be coded as a FluidNC custom kinematics module (C++ or via Maslow4 fork) |
| Enclosure / frame design | ⬜ Not started | Plywood perimeter frame for prototype; extrusion or ply for production |
| Dust collection system | ⬜ Not started | Active vacuum nozzle wrapping Makita router body — concept only |

### 2.3 Repository Structure

```
cnc-router/
├── README.md               # Competitive analysis, design rationale, software strategy
├── BOM-Evaluation.md        # Two-scale BOM with component tables and cost breakdown
├── PROJECT-PLAN.md          # ← THIS FILE — roadmap and phased development plan
├── kinematics/
│   ├── kinematics.py        # 8-belt Gordix forward/inverse kinematics
│   ├── simulate_grid.py     # Workspace grid simulation
│   ├── tension_analysis.py  # Belt tension analysis
│   ├── workspace_heatmap.csv
│   └── workspace_heatmap.png
└── pcb/
    ├── esp32-s3-pinout.yml  # FluidNC machine configuration
    └── schematic_netlist.md # Full schematic netlist, BOM, and stackup
```

---

## 3. Development Phases

### 3.1 Phase 1: Prototype (1 m × 1 m, 4-Belt)

**Goal:** A low-cost, low-risk proof of concept to validate belt-driven suspended kinematics, firmware integration, and basic accuracy — before investing in the full-scale machine.

**Target Budget:** ~$261

**Core Specs:**
- Work area: 1 m × 1 m (with GT2 timing belts, corner anchors)
- Kinematics: 4-belt suspended triangle (simpler, yaw managed in software)
- Motors: 4× NEMA 17 (59 N·cm, 1.8° step)
- Drivers: 4× TMC2209 (UART mode, stealthChop for quiet operation)
- Controller: ESP32 NodeMCU dev board + GRBL Arduino shield (or early FluidNC flash)
- Sled: 3D-printed PLA, dual-mount holes per corner (upgradable to 8-belt)
- Spindle: Bosch Colt / Makita clone (65 mm body, 500 W brushless DC option)
- Z-axis: Mini linear slide with T8 leadscrew + NEMA 17
- Frame: Plywood perimeter + corner brackets

**Phase 1 Deliverables:**

| # | Task | Est. Effort | Dependencies |
|---|------|-------------|-------------|
| P1.1 | Order prototype parts per BOM-Evaluation.md | 1 day | None |
| P1.2 | 3D-print sled, corner anchors, GT2 spools | 3 days | P1.1 (ordered parts) |
| P1.3 | Build plywood frame (1 m × 1 m) | 1 day | P1.2 |
| P1.4 | Assemble electronics (ESP32 + TMC2209s) on breadboard/protoboard | 2 days | P1.1 |
| P1.5 | Flash FluidNC with 4-belt kinematics | 1 day | P1.4 |
| P1.6 | Initial belt tensioning and calibration | 1 day | P1.3, P1.5 |
| P1.7 | Test grid: cut 10 cm squares at 5 positions across workspace | 1 day | P1.6 |
| P1.8 | Measure accuracy; document deviation map | 1 day | P1.7 |
| P1.9 | Gate review — proceed to Phase 2? | — | P1.8 |

**Success Criteria (Phase 1):**
- [ ] All 4 belts remain tensioned across full workspace without slipping
- [ ] Sled reaches all corners of 1 m × 1 m without binding
- [ ] Positional accuracy ≤ 2 mm over 500 mm travel (open-loop)
- [ ] Cuts a 100 mm square within 1 mm squareness
- [ ] No persistent electronics overheating after 30-minute continuous jog

---

### 3.2 Phase 2: Full-Scale (4′ × 8′, 8-Belt Gordix Kinematics)

**Goal:** A production-capable machine with constraint-locked yaw control, DC geared servos for torque and reliability, and a proper spindle for woodworking.

**Target Budget:** ~$737 (excluding frame lumber)

**Core Specs:**
- Work area: 4′ × 8′ (1.2 m × 2.4 m) or optionally 4′ × 4′
- Kinematics: 8-belt Gordix style (twin lines to each of 4 corners → constraint-locked, no yaw)
- Motors: 4× Etom ET-WGM58AE 24 V DC geared servo + planetary gearbox + high-res encoder
- Drivers: Custom ESP32-S3 PCB v1.0 with 8× TMC2209 (UART, 2 buses)
- Sled: 6 mm milled aluminum baseplate (CNC-milled or waterjet)
- Spindle: Makita RT0701C (1.25 HP, variable speed 10,000–30,000 RPM)
- Belts: 2.0 mm Dyneema braided cord (zero-stretch, breaking strength 450 kg)
- Z-axis: Dual linear rails + SFU1204 ball screw + active NEMA 17
- Frame: 2×4 lumber or 80/20 aluminum extrusion perimeter

**Phase 2 Deliverables:**

| # | Task | Est. Effort | Dependencies |
|---|------|-------------|-------------|
| P2.1 | Fabricate custom ESP32-S3 PCB (v1.0 layout in KiCad) | 5 days | PCB schematic (done), Phase 1 learnings |
| P2.2 | Populate and test PCB (solder, reflow, debug) | 2 days | P2.1 |
| P2.3 | Write and integrate 8-belt FluidNC custom kinematics module | 4 days | P2.2, kinematics.py from research |
| P2.4 | Build 4′×8′ perimeter frame | 2 days | Lumber/extrusion ordered |
| P2.5 | Fabricate aluminum sled (waterjet/CNC) | 3 days | Sled CAD model |
| P2.6 | Assemble DC gear servos + planetary gearboxes on spool brackets | 2 days | P2.4 |
| P2.7 | String and tension 8-belt Gordix configuration | 1 day | P2.5, P2.6 |
| P2.8 | Machine calibration routine (self-calibration via Maslow4-style spoofing) | 2 days | P2.3, P2.7 |
| P2.9 | Cut full-sheet test pattern (18 mm plywood, pocket + contour) | 1 day | P2.8 |
| P2.10 | Accuracy measurement and backlash compensation | 1 day | P2.9 |
| P2.11 | Gate review — proceed to Phase 3? | — | P2.10 |

**Success Criteria (Phase 2):**
- [ ] All 8 belts tensioned; sled maintains orientation within ±0.5° across full workspace
- [ ] Positional accuracy ≤ 0.5 mm over 1 m (closed-loop compensation)
- [ ] Makita router produces clean edges in 18 mm plywood at 4 mm/s feed
- [ ] Self-calibration routine completes without manual intervention
- [ ] DC servos handle stall condition without damage (fault/pause)

---

### 3.3 Phase 3: Production Refinement

**Goal:** Polish the design into a reliable, reproducible, documented product — suitable for semi-professional use, kit sales, or open-source publication.

**Phase 3 Deliverables:**

| # | Task | Est. Effort | Dependencies |
|---|------|-------------|-------------|
| P3.1 | PCB v1.1 — fix any issues from v1.0; add ESD protection, fusing | 3 days | Phase 2 PCB testing |
| P3.2 | Design and fab enclosure (electronics box with fan/cooling) | 3 days | P3.1 |
| P3.3 | Dust boot for Makita RT0701C (3D-printable or vacuum-form) | 2 days | Phase 2 dust concept |
| P3.4 | Calibration software GUI (standalone web app or FluidNC plugin) | 5 days | Phase 2 calibration routine |
| P3.5 | Comprehensive documentation: build guide, wiring diagram, BOM links, CAM setup | 5 days | All prior phases |
| P3.6 | Safety features: e-stop circuit, belt guard, spindle interlock | 2 days | P3.1 |
| P3.7 | Long-duration reliability test (10-hour continuous cutting) | 2 days | P3.1–P3.6 |
| P3.8 | Release: tag v1.0, publish repo, create release assets | 1 day | P3.7 |

**Success Criteria (Phase 3):**
- [ ] Electronics enclosure passes thermal test (ambient 25 °C, 4-hour run, no component >70 °C)
- [ ] Dust collection captures ≥90 % of chips at router zone
- [ ] Documentation covers full assembly from raw lumber to first cut
- [ ] 10-hour reliability test with zero mechanical failures
- [ ] Repo tagged v1.0 with release artifacts (PCB Gerbers, 3D-printable STLs, BOM CSV)

---

## 4. Milestones & Dependencies

```mermaid
gantt
    title CNC Router Project Timeline
    dateFormat  YYYY-MM-DD
    axisFormat  %b %Y

    section Research (Done)
    Competitive Analysis           :done, 2026-06-01, 14d
    Kinematics Simulation          :done, 2026-06-05, 15d
    PCB Schematic & Netlist        :done, 2026-06-10, 10d
    FluidNC Config YAML            :done, 2026-06-15, 5d

    section Phase 1 — Prototype
    Order Parts                    :p1-1, after research, 2d
    3D Print Sled & Anchors        :p1-2, after p1-1, 5d
    Build Frame 1m×1m             :p1-3, after p1-2, 2d
    Assemble Electronics           :p1-4, after p1-1, 3d
    Flash FluidNC + 4-Belt Kine    :p1-5, after p1-4, 2d
    Calibrate & Test               :p1-6, after p1-5, 5d
    Phase 1 Gate Review            :milestone, after p1-6, 0d

    section Phase 2 — Full-Scale
    PCB Layout in KiCad            :p2-1, after p1-6, 7d
    PCB Fab & Populate             :p2-2, after p2-1, 5d
    Write 8-Belt FluidNC Module    :p2-3, after p2-2, 5d
    Build 4′×8′ Frame             :p2-4, after p2-2, 3d
    Fab Aluminum Sled              :p2-5, after p2-2, 5d
    Assemble DC Servo Drives       :p2-6, after p2-4, 3d
    String 8-Belt Kinematics       :p2-7, after p2-5 p2-6, 2d
    Calibrate & Test Cuts          :p2-8, after p2-7, 5d
    Phase 2 Gate Review            :milestone, after p2-8, 0d

    section Phase 3 — Production
    PCB v1.1 Revisions             :p3-1, after p2-8, 5d
    Enclosure & Dust Boot          :p3-2, after p3-1, 5d
    Calibration GUI                :p3-3, after p2-8, 7d
    Documentation & Safety         :p3-4, after p3-2, 7d
    Reliability Test               :p3-5, after p3-4, 3d
    v1.0 Release                   :milestone, after p3-5, 0d
```

**Critical Path:** Order → Print/Build → Electronics → Firmware → Calibrate → Test

**Key dependency chain:**
1. PCB schematic (done) → KiCad layout (Phase 2) → PCB fab → firmware integration
2. Kinematics simulation (done) → FluidNC custom kinematics module (Phase 2) → calibration
3. Prototype tests (Phase 1) → inform full-scale design decisions (Phase 2)
4. Phase 1 Gate Review → Investment in Phase 2 materials
5. Phase 2 Gate Review → Production refinement investment

---

## 5. Risk Register

| # | Risk | Likelihood | Impact | Mitigation |
|---|------|-----------|--------|------------|
| R1 | **Belt stretch / creep over 4 m span** | Medium | High | Use Dyneema braided cord (zero-stretch) for production; GT2 timing belts only for prototype. Monitor tension with load cells in Phase 3. |
| R2 | **Yaw control insufficient in 4-belt prototype** | High | Medium | Accept software-based yaw correction for Phase 1. The whole point of Phase 1 is to measure how bad yaw is before building 8-belt. If yaw is unacceptable → skip straight to 8-belt prototype. |
| R3 | **TMC2209 current insufficient for NEMA 23 / DC servo replacement** | Low | Medium | TMC2209 handles 2.8 A peak — fine for NEMA 17. If NEMA 23 needed, switch to TMC5160 (external FETs, up to 20 A). PCB v1.0 pinout compatible with both. |
| R4 | **Firmware complexity — custom FluidNC kinematics module** | Medium | High | Starting from Maslow4's existing FluidNC fork. The Maslow4 firmware already implements a 4-belt kinematic transform; our work is adapting it for 8-belt Gordix geometry, not writing from scratch. |
| R5 | **Dust management — router chips affecting belt/sled mechanics** | Medium | Medium | Active vacuum nozzle in Phase 3; sealed bearings on spools; belt path kept below sled plane where possible. Prototype tests will reveal how bad chip accumulation is. |
| R6 | **PCB v1.0 has layout/routing errors** | Medium | Medium | Redesign for v1.1 is budgeted in Phase 3. Produce only 3–5 boards for v1.0; test thoroughly before committing to volume. |
| R7 | **Gordix-style 8-belt geometry has unreachable zones** | Low | High | Kinematics simulation shows full workspace coverage for 1.2 m × 2.4 m with the current anchor offsets. If zones are problematic, adjust anchor positions or accept reduced workspace. |
| R8 | **DC geared servo control via TMC2209 inadequate (no closed-loop position)** | Medium | High | TMC2209 is open-loop step/dir. For Phase 2, we pair TMC2209 with external encoder feedback via ESP32-S3 PCNT (pulse counter) for software-based closed-loop. If this proves unreliable, switch to TMC5160+encoder or dedicated servo drives. |
| R9 | **Cost overrun — BOM estimate out of date** | Medium | Low | All BOM prices verified June 2026 from current AliExpress/Amazon pricing. Buffer of 15% already included in estimates. |
| R10 | **Self-calibration routine fails on asymmetrical belt stretch** | Low | Medium | Develop manual calibration fallback (measure 4 corner distances, input via web UI). Maslow4's calibration algorithm is well-documented and can be adapted. |

---

## 6. Testing Strategy

### 6.1 Phase 1 Tests

| Test | Method | Pass Criteria |
|------|--------|--------------|
| **Belt tension uniformity** | Measure belt sag at 4 corners with force gauge | All 4 belts within ±10 % tension |
| **Workspace coverage** | Jog sled to 9 grid points; record if reachable | 9/9 points reachable |
| **Squareness** | Cut 100 mm square, measure diagonals | Diag difference ≤ 2 mm |
| **Positional accuracy** | Cut grid at 5 positions, measure with calipers | X/Y error ≤ 2 mm over 500 mm |
| **Repeatability** | Return-to-center test ×10 | ±0.5 mm |
| **Electronics thermal** | IR thermometer after 30-min continuous jog | TMC2209 ≤ 70 °C, ESP32 ≤ 60 °C |
| **Z-axis plunge test** | Plunge 3 mm into pine at 5 mm/s | Clean cut, no Z-binding |

### 6.2 Phase 2 Tests

| Test | Method | Pass Criteria |
|------|--------|--------------|
| **8-belt yaw constraint** | Measure sled rotation with dial indicator during XY move | ≤ 0.5° rotation across full span |
| **DC servo torque test** | Feed rate ramp until stall | ≥ 8 mm/s in 18 mm plywood |
| **Closed-loop accuracy** | Cut 500 mm line, measure with laser distance meter | ≤ 0.5 mm error |
| **Calibration routine** | Run auto-calibration 3 times, compare results | ±0.3 mm agreement |
| **Dust test** | Cut 1 m pocket in MDF with/without dust boot | Chips in workspace ≤ 10 g |
| **Makita RT0701C** | Test all speed settings, 10 min continuous | No overheating, smooth cut |
| **Limit switch test** | Trigger each limit 10× | 100 % reliable stop |

### 6.3 Phase 3 Tests

| Test | Method | Pass Criteria |
|------|--------|--------------|
| **Thermal chamber** | 4-hour cut cycle at 25 °C ambient | Max component temp ≤ 70 °C |
| **Long-duration reliability** | 10-hour continuous cutting (interleaved patterns) | Zero mechanical failures |
| **Safety system** | E-stop + belt guard test | < 100 ms stop time |
| **Documentation walkthrough** | Independent builder follows build guide | Complete assembly in ≤ 20 hours |

---

## 7. Next Actions (DO NOW)

These are the 5 concrete steps to execute immediately:

### 7.1 Order Prototype Parts

**Source the full Phase 1 BOM** from BOM-Evaluation.md ($261 total). Priority items:
- [ ] 4× NEMA 17 steppers ($56)
- [ ] 4× TMC2209 drivers ($28)
- [ ] ESP32 NodeMCU dev board ($6)
- [ ] GRBL CNC Shield or protoboard ($10)
- [ ] 2× GT2 6 mm timing belts, 10 m rolls ($24)
- [ ] 24 V 10 A PSU ($28)
- [ ] Bosch Colt / Makita clone spindle ($45)
- [ ] Mini linear slide Z-axis ($35)
- [ ] Fasteners, bearings, hardware ($15)
- [ ] 3D printer filament (PLA/PETG) for sled + anchors (~$6)

### 7.2 Design Sled & Anchor 3D-Printable STLs

Create CAD models (Fusion 360 / Onshape) for:
- **Sled body:** PLA/PETG with dual-mount holes per corner (compatible with 8-belt upgrade)
- **Corner anchors:** With manual clamp handles for quick frame attachment
- **GT2 spool holders:** Captive bearing mounts for smooth belt travel
- **Z-axis bracket:** Mount for mini linear slide + spindle clamp
- Export STLs for printing

### 7.3 KiCad PCB Layout (Start in Parallel)

Convert the completed schematic netlist into KiCad:
- [ ] Import ESP32-S3-WROOM-1 footprint
- [ ] Place 8× TMC2209 (QFN-24 package) with decoupling caps
- [ ] Route 4-layer stackup (signal/GND/power/signal)
- [ ] UART1 bus to 4 drivers, UART2 bus to 4 drivers
- [ ] JST XH connectors for motor outputs
- [ ] 24 V input with TVS diode + 5 A fuse
- [ ] MP9942 buck reg + AMS1117-3.3 LDO
- [ ] Limit switch / probe headers
- [ ] Spindle PWM + direction header
- [ ] Run ERC/DRC; order 5 prototype boards from JLCPCB

### 7.4 Write FluidNC Custom Kinematics Module

Starting from the Maslow4 FluidNC fork:
- [ ] Clone `github.com/MaslowCNC/Maslow_4` firmware repo
- [ ] Locate `kinematics/` directory in FluidNC source
- [ ] Implement 4-belt kinematic transform (forward + inverse) in C++
- [ ] Implement 8-belt Gordix kinematic transform
- [ ] Create a custom machine config YAML for each phase
- [ ] Add workspace boundary checking
- [ ] Build and flash to ESP32 dev board
- [ ] Test with serial G-code sender (bCNC or Candle)

### 7.5 Set Up Cutting Area & Safety

- [ ] Allocate 2 m × 2 m clear floor/bench space
- [ ] Build 1 m × 1 m plywood frame as first structural task
- [ ] Prepare dust extraction (shop vac + cyclone)
- [ ] Set up workbench for electronics assembly (soldering station, multimeter, scope)
- [ ] Install hearing protection / dust mask / fire extinguisher in workspace

---

## Appendix A: Software Pipeline

```
CAD (Fusion 360 / Onshape / Inkscape)
    │
    ▼
CAM (Kiri:Moto / Estlcam / OpenBuilds CAM)
    │  Generates standard G-code (.nc or .gcode)
    ▼
G-code Sender (bCNC / Candle / Web Interface)
    │  Streams over USB or Wi-Fi
    ▼
FluidNC (ESP32-S3)
    │  Custom kinematics module:
    │  4-belt: forward(Kartesian X,Y → 4 belt lengths)
    │  8-belt: forward(Kartesian X,Y → 8 belt lengths)
    │  Inverse: belt lengths → X,Y via least-squares (scipy)
    ▼
TMC2209 Stepper Drivers (UART mode)
    │
    ▼
NEMA 17 / DC Geared Servo Motors
    │
    ▼
Belt Spools → Sled → Cutter
```

## Appendix B: Key Reference Links

| Resource | URL |
|----------|-----|
| Maslow 4 firmware | github.com/MaslowCNC/Maslow_4 |
| Maslow 4 boards | github.com/MaslowCNC/Boards |
| Maslow 4 electronics | github.com/MaslowCNC/Electronics |
| Maslow 4 PCB (OSHW Labs) | oshwlab.com/BarbourSmith/maslow4 |
| FluidNC wiki | wiki.fluidnc.com |
| FluidNC config docs | wiki.fluidnc.com/en/config/ |
| FluidNC kinematics docs | wiki.fluidnc.com/en/config/kinematics |
| TMC2209 datasheet | trinamic.com/products/integrated-circuits/tmc2209/ |
| ESP32-S3 datasheet | espressif.com/en/products/socs/esp32-s3 |
| Gordix info | gordix.com |
| Cubiio X | cubiio.com |

---

> **Next milestone:** Parts ordered + first sled STL printed. Estimated: 7 days from now.
> **This document should be updated after each phase gate review.