Overview

Comprehensive reference for the PolyPlot controller features: Automatic Tool Changer (ATC), work area & origin calibration, limits handling, laser offset, persistence layer, job control endpoints, and safety / troubleshooting notes.

Quick Navigation

• Tool Change (M6)
• ATC Storage JSON
• Work Area System
• Laser Offset (M150/M151)
• Unified Limits
• UI / HTTP Endpoints
• Dry Run Mode
• Troubleshooting
• Command Reference

Tool Change (M6 Tn)

Aspect	Detail
Command	M6 Tn
Purpose	Change to tool (pen) number n
Motion Type	Controlled system motion (soft-limit safe path)
Failure Handling	Automatic rollback to previous tool
Persistence	Current tool stored in /spiffs/penstate.json

How it Works:

• Validates / loads tool configuration.
• Distinct approach vs precise feedrates; feed overrides disabled for repeatability.
• Planner synchronized before executing; rollback performed on error; modal flag cleared.

ATC JSON Storage (Tool Bank Persistence)

File	Purpose
/spiffs/toolconfig.json	Array of tool objects (autogenerated + calibrated)
/spiffs/penstate.json	Last known active tool (for resume/state continuity)

API: /toolconfig (GET/POST), /toolconfig/status.

JSON Examples

{
  "tools": [
    { "number": 1, "x": -30.2, "y": -100.0, "z": -10.0, "occupied": true },
    { "number": 2, "x": -30.2, "y": -110.0, "z": -10.0, "occupied": false }
  ]
}

{ "currentPen": 1, "timestamp": 1712345678900 }

Work Area and Work Origin

Config Block	Keys
work_area (in FluidNC/data/config.yaml)	min_x, min_y, max_x, max_y, origin_x, origin_y, enabled, move_to_origin

Notes:

• Rounding to 0.1 mm prevents float residue near boundaries.
• Enable/disable soft-limit enforcement via M160 / M161.

Work Area Toggles

Command	Action
M160	Enable work area limits
M161	Disable work area limits

Laser Pointer Offset (M150/M151)

Command	Function
M150	Apply (and optionally set) laser offsets X/Y
M151	Remove laser offsets

Details:

• Config keys: laser_offset_x, laser_offset_y (in config.yaml).
• Applied as internal parser coordinate offset (not a G92), preserving limit integrity.
• Removing clears offset & disables auto-apply until reissued.
• UI notified via internal state broadcast.

New Limits System (Tool + Work Area)

Feature	Description
Centralization	Unified soft-limit enforcement layer
System Motion	Calibration + tool changes route via special path
Safety	Hard limits always authoritative

Mechanics:

• State router: Homing → ToolCalibration → WorkAreaCalibration → Normal.
• During calibration: limit events treated as measurement callbacks (no alarm).
• Outside calibration: soft limits enforced; hard limits alarm.
• Real-time reset: Immediately aborts active calibration (steppers stop, state → Idle).

The minimal job-control UI (/jobcontrol) is intentionally lightweight to avoid SD dependency and reduce resource contention during active jobs.

G-code Dry Run (Check Mode)

Command	Effect
$C	Toggle check (no-motion) parsing mode

Behavior: Planner simulates path & limit checks without energizing motion—ideal for preflight validation.

Troubleshooting (Quick)

Symptom	Action
Float residue near edges	Re-run M156 (rounding normalization)
Tool change fails	Inspect /spiffs/toolconfig.json & occupancy; re-run M155
Soft-limit alarm mid-calibration	Verify you executed M155 / M156, not manual jog
Values not persisted	Check local FS free space & atomic rewrite (temp rename)

Command Reference

Command	Description
M6 T1	Change to tool 1
M150 X-2.5 Y-1.0	Set & apply laser offset
M151	Clear laser offset
M160	Enable work area limits
M161	Disable work area limits
$C	Toggle dry run (check) mode

For calibration commands and procedures, see CALIBRATION.md.

API Endpoints

Job Control

Method	Endpoint	Description
GET	/jobcontrol	Minimal job control page
POST	/job/pause	Pause active job
POST	/job/resume	Resume paused job
POST	/job/stop	Stop current job
GET	/jobstatus	Real-time job status JSON
GET	/jobblocked	Blocking page shown during active job

Tool Configuration (ATC)

Method	Endpoint	Description
GET	/toolconfig	Retrieve tool bank
POST	/toolconfig	Replace entire tool bank
POST	/toolconfig/position	Update single tool position
GET	/toolconfig/status	Real-time tool status

Pen Configuration

Method	Endpoint	Description
GET	/penconfig	Get pen configuration
POST	/penconfig	Update pen configuration
DELETE	/penconfig	Delete specific pen configuration

Work Area & Calibration

Method	Endpoint	Description
GET	/workorigin	Work origin (COFF command bridge)

Pen Change Mode

Method	Endpoint	Description
GET	/penchangemode	Get pen change mode status
POST	/penchangemode	Enable / disable pen change mode

System Control

Method	Endpoint	Description
POST	/restart	Restart MCU (admin)
POST	/command	Execute G-code / system command
POST	/command_silent	Execute silently (no echo)

File Management

Method	Endpoint	Description
GET	/files	List LocalFS (SPIFFS) files
POST	/files	Upload to LocalFS
DELETE	/files	Delete from LocalFS
GET	/upload	List SD card files
POST	/upload	Upload to SD card
DELETE	/upload	Delete from SD card

Enhanced Job Control System

Job Blocking During Motion

• Active jobs redirect new UI sessions to /jobcontrol to minimize interference & FS contention.
• Lightweight UI = reduced resource usage under motion load.

Real-time Job Status

• /jobstatus exposes: state, file, percent complete, pause state.
• Polled by job control UI for live incremental updates.

Safety Features

• Pen change mode gates non-ATC endpoints while active.
• Job blocking prevents mid-cycle interference.
• CORS support allows controlled cross-origin integrations.