1. Purpose of This Document

This document is a teaching and architecture guide for Kerfio. Its goal is to explain the standards, frameworks, protocols, APIs, and practical technologies used when software connects to CNC routers, laser engravers/cutters, and 3D printers. It is written for product and engineering understanding: enough detail to design Kerfio correctly, but still readable as a learning manual.

The central idea is simple: machine software does not really connect to “brands” first. It connects to a controller, firmware, protocol, and machine profile. Brands and models become compatibility presets on top of those deeper technical layers.

2. The Big Picture: Machine-to-Software Stack

Almost every digital fabrication machine can be understood as a stack of layers. Kerfio should model these layers explicitly. This prevents the app from becoming a confused collection of special cases.

3. Why Kerfio Should Think in Controller/Firmware Families

A user may say “I have an Ortur laser”, “I have an Ender 3”, “I have a DIY GRBL CNC”, or “I have a Voron with Klipper”. From software architecture perspective, these are not equal categories. Ortur commonly means a G-code laser controller; Ender 3 commonly means Marlin or Klipper; DIY CNC may mean Grbl, FluidNC, LinuxCNC, Mach, or GRBLHAL; Voron commonly means Klipper + Moonraker. Kerfio should therefore use a two-level model: machine brand/model presets mapped to firmware/controller profiles.

• Brand/model profile: friendly preset: work area, origin, baud rate, homing style, default post-processor, safety limits, common quirks.
• Firmware/controller profile: technical driver: protocol, G-code dialect, status format, command queue rules, connection method, capability detection.
• Machine type profile: CNC, laser, 3D printer, plasma, plotter, hybrid CNC+laser. This decides UI tools, safety warnings, job preparation, and operation settings.

4. Core Connection Types

5. Physical and OS-Level Technologies

Before G-code exists, Kerfio must first find and open a machine connection. This is more practical than theoretical. Most connection failures in machine software happen at this layer: wrong COM port, wrong baud rate, missing driver, another app holding the port, USB sleep, permission errors on Linux/macOS, or a controller that resets when serial opens.

5.1 USB CDC / Virtual COM Port

Many controllers expose themselves as a USB serial device. The operating system presents the board as COMx on Windows, /dev/ttyUSBx or /dev/ttyACMx on Linux, and /dev/cu.* or /dev/tty.* on macOS. The firmware then accepts text commands through that serial port. USB CDC ACM is the class often used for virtual serial behavior; many USB-to-UART chips also appear as serial ports through vendor drivers.

• Windows: COM3, COM4, etc. CH340, FTDI, CP210x, CDC ACM devices may need drivers depending on board and Windows version.
• Linux: /dev/ttyUSB0 for USB-UART bridges; /dev/ttyACM0 for CDC ACM; user may need dialout/uucp group permission.
• macOS: /dev/cu.usbserial*, /dev/cu.usbmodem* are typical for outgoing connections.
• Practical issue: some Arduino-style boards reset when the serial port opens because DTR toggles. Kerfio must wait for the firmware startup banner before sending commands.

5.2 pySerial

For a Python backend, pySerial is the most practical base library for serial communication. It works across Windows, macOS, Linux, and BSD-style systems. Kerfio should use serial.tools.list_ports to enumerate ports, show device descriptions, hardware IDs, serial numbers, and likely controller matches.

from serial.tools import list_ports

for port in list_ports.comports():
    print(port.device, port.description, port.hwid)

5.3 Web Serial API

If Kerfio later provides a pure browser-based version, the Web Serial API can allow Chromium-based browsers to read/write serial devices after explicit user permission. In a Tauri/Electron desktop app with a Python backend, direct backend serial access is usually more powerful and controllable than browser-only Web Serial. Still, Web Serial is useful to understand because it shows how web apps can connect to microcontrollers and printers from JavaScript.

5.4 USB Direct Access with libusb

Most CNC/laser/3D-printer G-code workflows do not require raw USB access; serial is enough. libusb becomes relevant when the device is not a normal serial port or when a vendor protocol uses USB endpoints directly. Kerfio should avoid raw USB for first implementation unless a target controller family requires it, because permissions and drivers are more complex.

6. G-code Fundamentals

G-code is the most important common language across CNC machines, laser engravers, and 3D printers. It is a line-based command language. Each line, often called a block, may include one or more words. A word is a letter followed by a number or value, such as G1, X10.5, F800, S12000, or M3.

G21         ; use millimeters
G90         ; absolute positioning
G0 X0 Y0    ; rapid move to origin
G1 X50 F800 ; controlled move to X=50 at feed rate 800 mm/min
M3 S1000    ; spindle or laser on, power/speed value depends on firmware
G1 Y50      ; move while tool is active
M5          ; spindle or laser off

6.1 Modal Commands

G-code is modal. This means a command can remain active until changed. For example, after G1 is selected, later lines may omit G1 and only provide new coordinates. After G90 is selected, all coordinates remain absolute until G91 changes the mode. A sender/parser inside Kerfio must understand modal behavior for preview, simulation, safety checks, and job estimation.

G21 G90
G1 X10 Y10 F600
X20       ; still G1, moves to X20 Y10
Y30       ; still G1, moves to X20 Y30
G0 X0 Y0  ; now rapid mode

6.2 G-code Dialects

A G-code dialect is the specific command set and behavior implemented by a firmware/controller. Kerfio should not generate one generic output for all machines. It should generate by selected dialect profile.

7. Streaming G-code Correctly

Sending G-code is not just writing a whole file to a serial port. The sender must respect the controller buffer, wait for acknowledgements, handle asynchronous messages, and allow emergency real-time commands. Poor streaming causes pauses, buffer overflows, lost lines, laser burns, and failed prints.

7.1 Stop-and-Wait Streaming

The simplest method sends one line, waits for ok or error, then sends the next line. It is easy to implement and safe, but slow for high-density engraving or many short line segments.

send("G1 X10 Y10 F800
")
wait until firmware replies "ok"
send("G1 X11 Y10
")
wait until "ok"

7.2 Character-Counting Streaming

Grbl-style senders often use character-counting streaming. The sender tracks how many characters are inside the controller serial receive buffer. It sends multiple lines until the buffer is nearly full, then removes counts as ok/error responses return. This keeps motion smooth, especially for laser engraving and CNC contour jobs.

7.3 Real-Time Commands

Some firmwares support immediate commands that bypass the normal G-code queue. In Grbl, commands such as status query, feed hold, cycle start, soft reset, and overrides are processed as real-time characters. Kerfio must separate queued G-code from real-time control.

8. Status Reporting and Machine State

A professional sender always maintains a machine state model. It should know whether the machine is idle, running, holding, alarming, homing, probing, paused, disconnected, or erroring. The source of that state differs by firmware.

9. Auto-Detection Strategy for Kerfio

Auto-detection is one of the features that makes an app feel familiar and professional. Kerfio should implement a staged detection system. Do not rely on one command only.

• Stage 1: Port/device discovery. List serial ports and network candidates. Read USB VID/PID, manufacturer, product, serial number, and OS port name.
• Stage 2: Safe open. Open port with selected/common baud rates. Respect DTR/RTS behavior. Wait for startup text.
• Stage 3: Identity query. Try firmware-specific commands such as $I/$G for Grbl, M115 for Marlin, HTTP /server/info for Moonraker, Duet HTTP object model endpoints, etc.
• Stage 4: Capability query. Read settings, limits, laser mode, homing, bed size, axes, tool count, temperatures, endstops.
• Stage 5: User confirmation. Show detected profile and ask user to confirm machine type, work area, origin, and safety settings.

Detection idea:
1. enumerate serial ports
2. for each candidate, try 115200, 250000, 230400, 57600
3. listen for banner
4. send safe identity query:
   - Grbl: $I, $G, $$
   - Marlin: M115, M503, M114
   - Smoothieware: version, M503
5. classify result into firmware profile
6. attach machine-type wizard: CNC / laser / 3D printer

10. CNC Connection Frameworks and Standards

CNC machines are less standardized at the software-control level than 3D printers. Hobby CNC often uses Grbl or GRBLHAL/FluidNC. More advanced or older systems may use LinuxCNC, Mach3/Mach4, PlanetCNC, UCCNC, MASSO, Centroid Acorn, EdingCNC, or industrial controllers. Kerfio should start with open G-code controller families, then later add integrations for professional controller ecosystems where APIs are available.

10.1 Grbl, GrblHAL, and FluidNC for CNC

Grbl is one of the most important open-source CNC controller firmwares for small CNC routers, mills, diode lasers, plotters, and DIY machines. It uses G-code over serial and exposes configuration through $ settings. GrblHAL and FluidNC extend the Grbl-style ecosystem to more powerful microcontrollers and features. FluidNC is especially important for ESP32-based CNC/laser controllers and keeps compatibility with Grbl-style status reports.

10.2 LinuxCNC

LinuxCNC is a full machine-control system, not just a small embedded firmware. It can control mills, lathes, routers, plasma machines, robots, and more. It includes a G-code interpreter, real-time motion system, HAL (Hardware Abstraction Layer), and UI frameworks. For Kerfio, LinuxCNC is not simply “open a serial port and send G-code”. Integration usually means running alongside LinuxCNC, using its Python/NML interfaces, HAL pins, or treating LinuxCNC as the primary controller and Kerfio as a design/job management companion.

• MVP approach: export LinuxCNC-compatible G-code and document usage.
• Intermediate: local plugin/bridge running on the LinuxCNC machine that exposes HTTP/WebSocket to Kerfio.
• Advanced: direct Python/NML/HAL integration for status, jogging, job control, probing, and digital IO.

10.3 Mach3 / Mach4

Mach3 and Mach4 are common Windows CNC control ecosystems. The actual motion is often handled through a motion controller plugin. Mach4 has Lua scripting and API/SDK style extension points. Kerfio should not try to replace Mach control directly in early versions. The practical path is to export Mach-compatible G-code and later provide a bridge/plugin approach for status and job transfer if the business case is strong.

• Export: Mach3/Mach4 post-processor flavor for arcs, units, tool changes, spindle commands.
• Workflow integration: save generated jobs to a watched folder or controller-specific job directory.
• Plugin bridge: possible later through Mach4 scripting/API, but this is more specialized than Grbl-style support.

10.4 Industrial CNC and Fieldbus Concepts

Industrial CNC machines often use vendor ecosystems and closed controllers. Direct control is not usually realistic or safe from a general desktop app. However, Kerfio should understand the vocabulary because it may matter for future professional versions.

11. Laser Connection Frameworks and Standards

Laser machines split into several controller categories. This split is extremely important. A diode laser based on Grbl is very different from a CO₂ laser with a Ruida DSP controller or a fiber galvo marker. Kerfio should copy the market mental model: G-code laser, DSP laser, and Galvo laser classes.

11.1 G-code Lasers

G-code lasers are common in diode laser engravers and many DIY CO₂ conversions. They often use Grbl, FluidNC, Smoothieware, or Marlin. The software sends G-code that moves XY axes and controls laser power with S values and M3/M4/M5 commands.

• M3 constant power: laser/spindle on at commanded S value. Useful for cutting and older controllers.
• M4 dynamic power: power can vary with speed on supported Grbl versions; often better for engraving corners and acceleration areas.
• M5: laser/spindle off. Kerfio must ensure jobs begin and end with a safe laser-off command.
• Laser mode: Grbl 1.1+ supports laser mode through $32=1. Kerfio should detect and warn if a laser job is sent while laser mode is disabled.

G21 G90
M4 S0        ; dynamic laser mode, power initially zero
G0 X10 Y10
G1 X60 S700 F1200
G1 Y60 S700
G1 X10 S700
G1 Y10 S700
M5           ; laser off

11.2 Laser Power Mapping

Laser power is not always the same scale. Some controllers use S0-S1000, some S0-S255, some S0-S1.0, some map to PWM differently, and some use percent in UI but G-code numeric values internally. Kerfio needs a machine profile field for S-value max and power mapping.

11.3 DSP Laser Controllers

DSP laser controllers such as Ruida, Trocen, and TopWisdom are common in CO₂ laser cutters. These are not usually controlled by simple line-by-line G-code streaming. They often use controller-specific job upload and control protocols over USB or Ethernet. LightBurn classifies these separately from G-code lasers, and Kerfio should do the same.

• Do not treat DSP as Grbl. The UI may look similar, but the connection layer is different.
• Job upload model: many DSP workflows upload a complete job to controller memory, then run it.
• Layer-based workflow: colors/layers often map to speed, power, passes, air assist, and cut/engrave mode.
• Machine settings: DSP controllers may expose machine/vendor parameters differently than Grbl $ settings.

11.4 Galvo Laser Controllers

Galvo lasers use mirrors to steer the beam instead of moving a gantry over the whole bed. They are common in fiber laser marking, UV marking, and fast CO₂ marking. They require concepts such as field lens size, calibration grid, hatch fill, wobble, pulse frequency, Q-pulse, jump speed, mark speed, and correction files. Many galvo controllers are proprietary and use vendor SDKs or software such as EZCAD-style ecosystems. Kerfio can support galvo later, but it is a different product module from normal XY gantry laser control.

12. 3D Printer Connection Frameworks and Standards

3D printer control has two common workflows: direct serial streaming to firmware, and network host/API control through systems such as OctoPrint, Moonraker, PrusaLink, Duet Web Control, or vendor cloud/local protocols. Kerfio should support both, but for professional user experience the network-host approach is often more robust for long prints.

12.1 Marlin Serial Printers

Marlin is one of the most common 3D printer firmwares. It accepts G-code over serial, reports temperature and position, can print from SD card, and responds with ok/error messages. Many older desktop printer host tools, including Pronterface-style interfaces, connect directly to Marlin-like serial printers.

• M115: firmware information and capabilities.
• M105: temperature report.
• M104/M109: set hotend temperature; M109 waits.
• M140/M190: set bed temperature; M190 waits.
• M114: report position.
• M119: endstop states.
• M503: report stored settings when enabled.
• SD commands: list/select/start SD print on supported machines.

M115        ; ask firmware identity
M105        ; read temperatures
G28         ; home axes
G1 Z10 F600 ; move Z up
M104 S210   ; set nozzle temp, do not wait
M140 S60    ; set bed temp, do not wait
M109 S210   ; wait for nozzle
M190 S60    ; wait for bed

12.2 Klipper + Moonraker

Klipper is a host-based 3D printer firmware architecture. A general-purpose computer runs the Klipper host, while microcontrollers execute scheduled low-level motion. Moonraker is a Python web server that exposes APIs used by clients such as Mainsail and Fluidd. Kerfio should connect to Klipper primarily through Moonraker HTTP/WebSocket APIs, not by trying to speak raw serial to the microcontroller.

• HTTP API: server info, printer objects, file upload, job start/pause/cancel.
• WebSocket: live status subscriptions and events.
• G-code console: commands can be sent through API endpoints.
• Macros: Klipper users often define custom G-code macros; Kerfio should display and execute allowed macros safely.

12.3 OctoPrint

OctoPrint is a widely used printer host and web interface. It connects to the printer, manages files, starts/stops jobs, reports temperatures, and exposes a REST API. Kerfio can integrate with OctoPrint as a remote printer host instead of opening the printer serial port directly.

• Kerfio role: design/slice/job manager and dashboard that talks to OctoPrint.
• Authentication: API key or app/session integration.
• Operations: upload G-code, select file, start/pause/cancel job, monitor temperatures and progress, send terminal commands.

12.4 RepRapFirmware / Duet

RepRapFirmware is used on Duet controllers and supports a strong “G-code everywhere” philosophy. It also provides an object model that can be queried by clients and HTTP interfaces used by Duet Web Control and third-party applications. Kerfio should treat Duet/RRF as a first-class networked controller family, not only as serial G-code.

12.5 PrusaLink / Prusa Connect

Modern Prusa printers support local and cloud-connected workflows. PrusaLink allows local monitoring, file upload, and print control without internet access on supported models. Kerfio can later integrate with PrusaLink through its web/API layer and should treat Prusa machines as network printer profiles when available.

12.6 Bambu Lab and Closed/Vendor Ecosystems

Bambu Lab printers are important in the market, but their integration story is more vendor-controlled than open Grbl/Marlin/Klipper ecosystems. Bambu provides official integration guidance for sending sliced files through Bambu Connect in some workflows, while many community libraries use MQTT/local or cloud APIs. Kerfio should be careful: support user-friendly export/open-with workflows first, then only implement deeper control where stable and allowed APIs exist.

13. Host Software Patterns Kerfio Should Learn From

14. File Formats Related to Connection and Jobs

Machine connection is not only about live control. The files Kerfio imports, exports, previews, uploads, and streams are part of compatibility. File formats also define user expectations.

15. Coordinate Systems and Origins

Coordinate confusion is one of the biggest causes of machine accidents. CNC, laser, and 3D printer users think about origins differently. Kerfio must make origin, units, machine coordinates, and work coordinates very visible.

16. Safety and Interlocks

Kerfio is not only a sender. It controls machines that can burn, cut, crash, heat, and injure. Safety must be designed into the connection and job flow.

• Never start a laser/spindle/heater silently. Require visible job start confirmation.
• Always send safe shutdown commands at job end or cancellation. Example: M5 for laser/spindle, temperature shutdown for printers when appropriate.
• Implement E-stop guidance. Software stop is not a substitute for physical emergency stop that cuts energy safely.
• Validate machine bounds. Warn if toolpath exceeds travel area or Z limits.
• Detect homing state. Warn when running absolute jobs without homing where controller requires it.
• Handle disconnects safely. On reconnect, do not assume previous state. Ask controller status and warn user.
• Laser-specific: enclosure, goggles, air assist, exhaust, fire watch, material warnings.
• CNC-specific: spindle direction, workholding, tool length, stock zero, dust collection, feed/speed sanity.
• 3D-printer-specific: thermal runaway firmware protection, heater timeout, temperature monitoring, filament runout, enclosure temperature.

17. Kerfio Backend Architecture Recommendation

For your stack, a practical architecture is React/Tauri or Electron UI with a Python service backend. Python is good for serial, HTTP, WebSocket, file parsing, G-code processing, and machine-driver plugins. React is good for the canvas, control panels, dashboards, and live terminal.

18. Normalized Driver Interface

Every machine driver should expose the same high-level methods even if the underlying protocol is different. This lets the UI be stable while the backend handles firmware-specific details.

class MachineDriver:
    def discover(self): ...
    def connect(self, config): ...
    def disconnect(self): ...
    def identify(self): ...
    def get_status(self): ...
    def send_gcode(self, line): ...
    def start_job(self, job): ...
    def pause(self): ...
    def resume(self): ...
    def cancel(self): ...
    def jog(self, axis, distance, feed): ...
    def home(self, axes=None): ...
    def set_work_zero(self, axes=None): ...
    def emergency_stop(self): ...
    def get_capabilities(self): ...

The implementation behind these methods differs. Grbl sends text over serial. Moonraker sends JSON-RPC/HTTP requests. OctoPrint uses REST endpoints. Duet uses HTTP/object model and G-code. A Ruida driver would use a different binary protocol. But the React UI should see one normalized machine state.

19. Machine Profile Schema

Kerfio should store machine profiles in a structured JSON format. This allows built-in presets, user-edited profiles, import/export, and community sharing.

{
  "id": "custom_grbl_laser_500x700",
  "name": "Custom GRBL Diode Laser 500x700",
  "machine_type": "laser",
  "controller_family": "grbl",
  "connection": {
    "transport": "serial",
    "baud_candidates": [115200, 230400],
    "default_baud": 115200
  },
  "workspace": {
    "x_mm": 500,
    "y_mm": 700,
    "z_mm": 0,
    "origin": "front_left",
    "homing_required": true
  },
  "gcode": {
    "dialect": "grbl_laser",
    "units": "mm",
    "line_end": "\n",
    "startup": ["G21", "G90"],
    "shutdown": ["M5"]
  },
  "laser": {
    "s_min": 0,
    "s_max": 1000,
    "preferred_power_mode": "M4",
    "air_assist_command_on": "M8",
    "air_assist_command_off": "M9"
  }
}

20. Practical Driver Priorities for Kerfio

A realistic roadmap should start with broad compatibility and familiar workflows before advanced proprietary ecosystems.

21. Important G-code Commands by Category

22. What Kerfio Must Teach Users in the UI

Because Kerfio targets CNC, laser, and 3D printing together, the UI must teach without becoming annoying. Good machine software guides the user at the moment of risk or confusion.

• Connection wizard: “Your machine appears to be Grbl 1.1 on COM5 at 115200.”
• Controller explanation: “This profile uses G-code over serial. Kerfio will stream one command queue to the controller.”
• Origin explanation: visual diagram of machine origin and job origin.
• Laser power warning: show S-value scale and M3/M4 mode.
• CNC probing explanation: show touch plate thickness, probe direction, expected contact.
• 3D printer temperature flow: explain set temperature vs wait temperature.
• Error helper: translate firmware errors/alarms into human advice.

23. Common Errors and How Kerfio Should Handle Them

24. Glossary

25. Final Kerfio Design Principles

• Profile by controller, not only by brand. Brands are presets; firmware/controller family is the real compatibility layer.
• Normalize state. The UI should not care whether status came from serial, REST, or WebSocket.
• Respect dialects. Never assume all G-code means the same thing everywhere.
• Separate machine type from firmware. Grbl can control CNC or laser; Marlin can be printer or conversion laser; Smoothieware can be multiple machine types.
• Make safety visible. Bounds, origin, laser/spindle/heater state, and homing status must always be obvious.
• Start open, then go proprietary. Grbl/FluidNC/Marlin/Klipper/Duet/OctoPrint give wide coverage before difficult DSP/Galvo/vendor-specific protocols.
• Build a plugin driver system early. Compatibility will grow for years; hardcoded drivers will become a problem.

26. Research References

1. Grbl interface documentation
2. Grbl project repository
3. FluidNC serial protocol
4. Marlin G-code documentation
5. Marlin serial ports documentation
6. Klipper documentation
7. Klipper API server documentation
8. Moonraker documentation
9. OctoPrint REST API
10. RepRap G-code wiki
11. Duet3D G-code dictionary
12. Duet3D RepRapFirmware HTTP requests
13. Duet3D object model documentation
14. LinuxCNC documentation
15. LinuxCNC G-code overview
16. Smoothieware documentation
17. LightBurn laser type/controller explanation
18. LightBurn GRBL configuration notes
19. pySerial documentation
20. Web Serial API specification
21. libusb API reference
22. USB CDC class definitions
23. PrusaLink and Prusa Connect explanation
24. PrusaLink Web OpenAPI repository
25. Bambu Lab third-party integration page