#Kerfio 3D Printer Workspace Specification

Document purpose: Define the recommended features, architecture, implementation notes, and technical advice for adding a professional 3D Printer workspace to Kerfio.

Target application: Kerfio Digital Fabrication Platform
Frontend: React + TypeScript
Backend service: Python + FastAPI
Main goal: Add a Pronterface-style 3D printer host-control section with modern UI, machine profiles, temperature graphs, G-code sending, calibration tools, file management, job monitoring, and future Klipper/Moonraker support.

#Product Direction

Kerfio should not only control CNC and laser machines; it can become a unified machine-control application for makers, engineers, workshops, and small factories.

The 3D Printer workspace should provide:

• Direct printer connection
• Manual motion control
• Temperature control
• G-code terminal
• Print job management
• Calibration wizards
• SD card management
• Printer profile management
• Basic G-code preview
• Filament/material presets
• Maintenance tools

The first version should focus on Marlin-compatible USB serial printers because this is the most direct implementation path. Later versions can add Klipper/Moonraker, OctoPrint, RepRapFirmware, and networked printer support.

#Main User Workflow

1. Create or select printer profile.
2. Connect over USB serial or network.
3. Home printer.
4. Preheat nozzle/bed.
5. Load filament or run extrusion test.
6. Load G-code file.
7. Preview file metadata.
8. Start print.
9. Monitor temperature and progress.
10. Pause/resume/cancel if needed.
11. Save print history and logs.
12. Run calibration or maintenance tools when needed.

#Printer Profile Manager

Each printer profile should contain:

printer_profile:
  id: string
  name: string
  firmware_family: marlin | klipper_later | reprapfirmware_later | smoothieware_later
  connection_type: usb_serial | tcp_later | moonraker_later | octoprint_later
  bed_size_x_mm: float
  bed_size_y_mm: float
  bed_size_z_mm: float
  origin: front_left | center | custom
  baud_rate: 115200 | 250000 | custom
  serial_port_hint: string | null
  nozzle_count: int
  nozzle_diameter_mm: float
  filament_diameter_mm: 1.75 | 2.85 | custom
  heated_bed: boolean
  heated_chamber: boolean
  auto_bed_leveling: boolean
  probe_type: none | bltouch | inductive | capacitive | load_cell | custom
  start_gcode: string
  end_gcode: string
  notes: string

Profile UI features:

• Add/edit/delete profile
• Duplicate profile
• Auto-detect serial ports
• Auto-detect firmware response
• Save successful connection settings
• Import/export printer profile JSON

#Connection Panel

#Required Features

• Serial port dropdown
• Baud rate dropdown
• Connect/disconnect
• Reset connection
• Firmware info panel
• Printer state
• Last response
• Auto reconnect option
• Connection log

#Backend Serial Design

Use Python pySerial for first version.

Required behavior:

• Open serial port safely.
• Wait for printer startup message.
• Send command line by line.
• Read ok, error, busy, temperature reports, and status lines.
• Maintain command queue.
• Support priority commands such as emergency stop.
• Save log to local database/file.

Possible Python structure:

printer/
  serial_connection.py
  marlin_protocol.py
  command_queue.py
  temperature_parser.py
  sd_card.py
  print_job.py
  calibration.py

#Manual Control Panel

#Movement Controls

Required controls:

• Home all
• Home X
• Home Y
• Home Z
• Jog X+/X-
• Jog Y+/Y-
• Jog Z+/Z-
• Step sizes:
  • 0.1 mm
  • 1 mm
  • 10 mm
  • 100 mm
• Disable motors
• Set current position later
• Baby-step Z

Recommended G-code:

G28        ; home all
G28 X      ; home X
G91        ; relative positioning
G1 X10 F3000
G90        ; absolute positioning
M84        ; disable steppers

#Extruder Controls

Required controls:

• Extrude
• Retract
• Extrusion length
• Extrusion speed
• Load filament macro
• Unload filament macro

Important safety:

• Do not allow cold extrusion unless user explicitly overrides.
• Check hotend target/current temperature before extruding.

Common commands:

M83        ; relative extrusion
G1 E10 F120
G1 E-5 F120

#Temperature Control

#UI Features

• Nozzle temperature card
• Bed temperature card
• Chamber temperature card if supported
• Temperature graph
• Target input
• Set button
• Preheat presets
• Cooldown button
• Temperature auto-report toggle

#Presets

Default presets:

Allow user editing.

#G-code Commands

Common Marlin-style commands:

M104 S200   ; set hotend temp, do not wait
M109 S200   ; set hotend temp and wait
M140 S60    ; set bed temp, do not wait
M190 S60    ; set bed temp and wait
M105        ; get temperature
M155 S2     ; auto-report temperature every 2 seconds if firmware supports it
M104 S0     ; hotend off
M140 S0     ; bed off

#G-code Console

A terminal-style console is mandatory.

Features:

• Manual G-code input
• Command history
• Auto-complete common commands
• Save favorite commands
• Macro buttons
• Filter temperature spam
• Clear console
• Export log
• Highlight errors
• Timestamp lines

Recommended frontend:

• xterm.js for terminal-like UX
• Or a custom virtualized log list if you prefer full React control

Example macro list:

#Print Job Manager

#Required Features

• Load G-code file
• Validate file size and extension
• Parse metadata if available
• Show estimated time if provided by slicer
• Show filament usage if available
• Show bed/nozzle temperature from file if detected
• Start print
• Pause
• Resume
• Cancel
• Progress percentage
• Current line
• Elapsed time
• Estimated remaining time
• Current Z height/layer if detectable
• Speed override
• Flow override
• Fan override
• Save job history

#G-code Streaming

The backend should stream G-code line by line and wait for printer acknowledgements.

Do not push the full file blindly to serial. Use a queue:

pending_file_lines -> send_queue -> serial_write -> ack_wait -> progress_update

State machine:

idle
connecting
connected
printing
paused
pausing
cancelling
error
disconnected

#Pause/Resume Strategy

Pause should:

1. Stop sending new file lines.
2. Save current file line index.
3. Retract filament if configured.
4. Lift Z if configured.
5. Park head if configured.
6. Keep temperatures or reduce temperatures based on user setting.

Resume should:

1. Restore temperature if needed.
2. Move back safely.
3. Restore extrusion mode.
4. Continue from saved line.

This requires careful G-code state tracking. For v1, keep pause simple and warn users that complex slicer-specific pause behavior may vary.

#SD Card Management

For Marlin-style printers, add SD features:

• List SD files
• Select file
• Start SD print
• Pause SD print
• Resume SD print
• Stop SD print
• Report SD progress
• Upload file to SD later
• Delete file later

Common commands:

M20       ; list SD card
M23 file.gcode ; select SD file
M24       ; start/resume SD print
M25       ; pause SD print
M27       ; report SD print status
M28 file.gcode ; begin write to SD
M29       ; stop SD write

Note: SD upload over serial can be slow. In v1, prioritize printing from host and listing/starting SD files.

#G-code Preview

#Minimum Preview

• Show bounding box
• Show layer height if available
• Show estimated print area
• Show first layer path
• Show full path as optional heavy mode
• Show temperature commands
• Show filament usage metadata

#Advanced Preview Later

• 3D layer preview
• Layer slider
• Color by feature type
• Color by speed
• Color by extrusion width
• Travel move visibility
• Retraction markers

Recommended frontend:

• Three.js / React Three Fiber
• Web Worker for parsing large G-code files

Recommended backend:

• Python G-code parser for metadata and validation
• Cache parsed preview data

#Calibration Tools

This is where Kerfio can become much better than basic printer hosts.

#Required Calibration Wizards

1. PID autotune
2. E-steps calibration
3. Manual bed leveling assistant
4. Z-offset calibration
5. Flow calibration
6. Retraction test generator
7. Temperature tower generator
8. First-layer test generator
9. Probe offset calibration
10. Belt tension notes/manual guide later

#PID Autotune Wizard

Inputs:

• Hotend or bed
• Target temperature
• Cycles

Commands:

M303 E0 S200 C8
M500

UI:

• Explain steps
• Send command
• Parse returned Kp/Ki/Kd if possible
• Ask user before saving

#E-Steps Calibration Wizard

Workflow:

1. Heat nozzle.
2. Mark filament.
3. Extrude 100 mm.
4. User enters actual extruded length.
5. Kerfio calculates new E-steps.
6. Send new value with M92 E....
7. Save with M500 if user confirms.

Formula:

new_e_steps = current_e_steps * commanded_length / actual_extruded_length

#Bed Leveling Assistant

Manual assistant:

• Move to front-left
• Move to front-right
• Move to rear-right
• Move to rear-left
• Move to center
• Repeat cycle
• Paper test instruction

Auto bed leveling:

• Run G29
• Parse mesh output if available
• Display mesh later

#Z-Offset Wizard

Features:

• Home printer
• Move nozzle to center
• Step Z down/up in 0.01/0.05/0.1 mm
• Save offset
• Test first layer pattern

Firmware commands vary by printer; store profile-specific commands.

#Filament and Material Presets

Fields:

filament_preset:
  id: string
  name: string
  material: PLA | PETG | ABS | TPU | Nylon | ASA | PC | custom
  brand: string | null
  color: string | null
  diameter_mm: float
  nozzle_temp_c: int
  bed_temp_c: int
  chamber_temp_c: int | null
  fan_percent: int
  flow_percent: int
  retraction_mm: float | null
  notes: string

Features:

• Add/edit/delete preset
• Preheat from preset
• Attach preset to print job
• Save successful print notes

#Maintenance Section

Recommended tools:

• Move axes for cleaning
• Load/unload filament
• Cold pull guide
• Nozzle change guide
• Belt check guide
• Lubrication reminder
• Calibration history
• Print hours counter
• Error log
• Firmware settings snapshot

Firmware snapshot:

M503

Save returned settings in job/device history.

#React UI Architecture

#Recommended Libraries

Core:

• React + TypeScript
• Vite
• Zustand for live UI state
• TanStack Query for API data
• React Hook Form + Zod for forms
• Tailwind CSS or CSS Modules
• Radix UI / shadcn/ui for accessible components

Charts:

• Recharts or uPlot for temperature graphs
• For very high-performance charts, prefer uPlot

Console:

• xterm.js

3D preview:

• Three.js / React Three Fiber

File handling:

• Browser File API
• Web Worker for parsing large G-code files

#Component Structure

PrinterWorkspace
  PrinterTopToolbar
  PrinterConnectionPanel
  PrinterStatusCards
  PrinterJogPanel
  PrinterExtruderPanel
  PrinterTemperaturePanel
  PrinterTemperatureChart
  PrinterGcodeConsole
  PrinterJobManager
  PrinterPreviewPanel
  PrinterSdCardPanel
  PrinterCalibrationPanel
  PrinterMaintenancePanel
  PrinterProfileEditor

#UI Layout Recommendation

Suggested layout:

• Left: printer controls and jog panel
• Center: preview / job status
• Right: temperature and profile panels
• Bottom: G-code console
• Top: connection, start/pause/resume/cancel, emergency stop

Emergency stop must always be visible.

#Python Backend Architecture

#Recommended Structure

kerfio_backend/
  app/
    printer/
      profiles.py
      serial_connection.py
      marlin_protocol.py
      command_queue.py
      gcode_streamer.py
      gcode_parser.py
      temperature.py
      sd_card.py
      calibration.py
      maintenance.py
      print_history.py
    api/
      routes_printer.py
      websocket_printer.py
    db/
      models.py
      repositories.py

#API Endpoints

GET    /api/printers
POST   /api/printers
GET    /api/printers/{id}
PUT    /api/printers/{id}
DELETE /api/printers/{id}

GET    /api/printer/ports
POST   /api/printer/connect
POST   /api/printer/disconnect
POST   /api/printer/command
POST   /api/printer/home
POST   /api/printer/jog
POST   /api/printer/extrude
POST   /api/printer/set-temperature
POST   /api/printer/cooldown

POST   /api/printer/upload-gcode
POST   /api/printer/start-print
POST   /api/printer/pause-print
POST   /api/printer/resume-print
POST   /api/printer/cancel-print

GET    /api/printer/sd/files
POST   /api/printer/sd/print

POST   /api/printer/calibration/pid
POST   /api/printer/calibration/esteps
POST   /api/printer/calibration/bed-level
POST   /api/printer/calibration/z-offset

WS     /ws/printer/status
WS     /ws/printer/temperature
WS     /ws/printer/console
WS     /ws/printer/job

#WebSocket Status Messages

{
  "type": "printer_status",
  "state": "printing",
  "x": 120.0,
  "y": 90.0,
  "z": 2.4,
  "e": 342.1,
  "feedrate": 3000,
  "fan_percent": 80
}

{
  "type": "temperature",
  "hotend_current": 199.4,
  "hotend_target": 200,
  "bed_current": 59.7,
  "bed_target": 60,
  "chamber_current": null,
  "timestamp": "2026-05-29T12:00:00Z"
}

{
  "type": "print_progress",
  "percent": 34.2,
  "current_line": 18342,
  "total_lines": 53622,
  "elapsed_sec": 1820,
  "estimated_remaining_sec": 3500,
  "current_layer": 12,
  "current_z": 2.4
}

#Future Klipper/Moonraker Support

Do not build this first, but design the abstraction now.

Create a common interface:

class PrinterController:
    async def connect(self): ...
    async def disconnect(self): ...
    async def send_gcode(self, command: str): ...
    async def start_print(self, file_id: str): ...
    async def pause_print(self): ...
    async def resume_print(self): ...
    async def cancel_print(self): ...
    async def get_status(self): ...

Implementations:

• MarlinSerialController
• MoonrakerController later
• OctoPrintController later
• RepRapFirmwareController later

Moonraker/Klipper support should use HTTP/WebSocket API and printer objects instead of raw serial.

#Safety Requirements

Mandatory:

• Emergency stop always visible.
• Confirm before sending M112 emergency stop.
• Confirm before resetting firmware settings.
• Block cold extrusion by default.
• Warn before heating nozzle or bed.
• Warn if print exceeds bed size.
• Warn if G-code has unknown temperature commands.
• Warn if file appears for a different bed size.
• Warn if first move goes below safe Z unexpectedly.
• Do not auto-start after file load.

Recommended:

• Thermal runaway warning if temperature is not rising as expected.
• Connection-loss behavior setting.
• Pause on communication error.
• Log all commands and responses.

#Integration with Kerfio Core

Shared with CNC/Laser:

• Machine profile manager
• Serial connection manager
• G-code sender
• G-code parser
• Console
• Job history
• Safety checklist system
• Macro manager
• Settings manager
• Local database
• WebSocket event bus

Printer-specific:

• Temperature service
• Extruder control
• Filament presets
• Bed leveling
• Print job state
• SD card operations

#Implementation Phases

#Phase 1: Basic Host Control

• Printer profiles
• Serial connection
• Manual jog
• Home commands
• Temperature read/set
• G-code console
• Emergency stop

#Phase 2: Print Job Streaming

• Load G-code
• Parse metadata
• Stream file line by line
• Progress tracking
• Pause/resume/cancel
• Job history

#Phase 3: Calibration Tools

• PID autotune
• E-steps
• Bed leveling assistant
• Z-offset
• First-layer test

#Phase 4: Preview and SD Card

• 2D/3D G-code preview
• SD file list
• SD print
• Temperature graph improvements

#Phase 5: Advanced Integrations

• Klipper/Moonraker
• OctoPrint
• RepRapFirmware
• Multi-printer dashboard
• Camera monitoring
• AI troubleshooting assistant

#Functionality Checklist

#Must-Have v1

• Printer profile manager
• Serial port detection
• Connect/disconnect
• Manual jog
• Home buttons
• Extrude/retract
• Hotend temperature control
• Bed temperature control
• Temperature graph
• G-code console
• Macro buttons
• Load G-code file
• Start print
• Pause/resume/cancel
• Job progress
• Emergency stop
• Log export

#Strongly Recommended v1.5

• SD file list
• SD print
• PID autotune wizard
• E-steps wizard
• Manual bed leveling assistant
• Z-offset wizard
• Filament presets
• Print history

#Future

• Klipper/Moonraker
• OctoPrint
• Multi-printer management
• Full 3D preview
• AI troubleshooting
• Webcam monitoring

#Recommended External References

Useful references for feature comparison and implementation:

• Pronterface / Printrun: https://www.pronterface.com/
• Printrun GitHub: https://github.com/kliment/Printrun
• Marlin G-code index: https://marlinfw.org/meta/gcode/
• Marlin M104 temperature command: https://marlinfw.org/docs/gcode/M104.html
• Marlin G29 bed leveling: https://marlinfw.org/docs/gcode/G029.html
• Klipper API server: https://www.klipper3d.org/API_Server.html
• Moonraker printer objects: https://moonraker.readthedocs.io/en/latest/printer_objects/
• FastAPI WebSockets: https://fastapi.tiangolo.com/advanced/websockets/
• pySerial API: https://pyserial.readthedocs.io/en/latest/pyserial_api.html
• pyserial-asyncio: https://pyserial-asyncio.readthedocs.io/

#Final Technical Recommendation

For the first implementation, build the 3D Printer workspace as a modern Pronterface-style host controller for Marlin USB printers.

Do not build a slicer in v1. Let users import G-code from Cura, PrusaSlicer, OrcaSlicer, Bambu Studio, or SuperSlicer.

The most important backend component is the command queue and serial streaming engine. Build it carefully because CNC, Laser, and 3D Printer sections can all reuse it.

The recommended architecture is:

React handles the interactive UI and preview. Python/FastAPI handles machine communication, G-code streaming, parsing, calibration logic, and persistent data.

This keeps Kerfio clean, scalable, and ready for CNC, Laser, 3D Printer, and future machine types.