Add comprehensive project plan and development roadmap

This commit is contained in:
2026-06-22 07:07:25 +00:00
parent f26f15db61
commit 326847cab1

397
PROJECT-PLAN.md Normal file
View File

@@ -0,0 +1,397 @@
# 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.2m×2.4m) 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 1m×1m 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 1m×1m 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 (1m×1m, 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 (1m×1m, 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: 1m×1m (with GT2 timing belts, corner anchors)
- Kinematics: 4-belt suspended triangle (simpler, yaw managed in software)
- Motors: 4× NEMA 17 (59N·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 (65mm body, 500W 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 (1m×1m) | 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 10cm 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 1m×1m without binding
- [ ] Positional accuracy ≤ 2mm over 500mm travel (open-loop)
- [ ] Cuts a 100mm square within 1mm 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.2m×2.4m) 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 24V DC geared servo + planetary gearbox + high-res encoder
- Drivers: Custom ESP32-S3 PCB v1.0 with 8× TMC2209 (UART, 2 buses)
- Sled: 6mm milled aluminum baseplate (CNC-milled or waterjet)
- Spindle: Makita RT0701C (1.25HP, variable speed 10,00030,000RPM)
- Belts: 2.0mm Dyneema braided cord (zero-stretch, breaking strength 450kg)
- 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 (18mm 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.5mm over 1m (closed-loop compensation)
- [ ] Makita router produces clean edges in 18mm plywood at 4mm/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.1P3.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 4m 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.8A peak — fine for NEMA 17. If NEMA 23 needed, switch to TMC5160 (external FETs, up to 20A). 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 35 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.2m×2.4m 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 100mm square, measure diagonals | Diag difference ≤ 2mm |
| **Positional accuracy** | Cut grid at 5 positions, measure with calipers | X/Y error ≤ 2mm over 500mm |
| **Repeatability** | Return-to-center test ×10 | ±0.5mm |
| **Electronics thermal** | IR thermometer after 30-min continuous jog | TMC2209 ≤ 70°C, ESP32 ≤ 60°C |
| **Z-axis plunge test** | Plunge 3mm into pine at 5mm/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 | ≥ 8mm/s in 18mm plywood |
| **Closed-loop accuracy** | Cut 500mm line, measure with laser distance meter | ≤ 0.5mm error |
| **Calibration routine** | Run auto-calibration 3 times, compare results | ±0.3mm agreement |
| **Dust test** | Cut 1m pocket in MDF with/without dust boot | Chips in workspace ≤ 10g |
| **Makita RT0701C** | Test all speed settings, 10min 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 | < 100ms stop time |
| **Documentation walkthrough** | Independent builder follows build guide | Complete assembly in 20hours |
---
## 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 6mm timing belts, 10m rolls ($24)
- [ ] 24V 10A 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
- [ ] 24V input with TVS diode + 5A 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 2m×2m clear floor/bench space
- [ ] Build 1m×1m 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: 7days from now.
> **This document should be updated after each phase gate review.