Architecture of Laetoly Driver Bridge & GRBL Protocol

System Architecture

The core engineering principle of Laetoly is Physical Decoupling between Cloud/Browser Workspace and Local CAM Computation:

Status: Experimental. This page describes the current internal bridge notes. Endpoint details, thresholds, and hardware compatibility must be verified against the specific Driver and controller build.

• Browser Workspace (Laetoly Web): Runs in the browser at app.laetoly.com. Responsible for 2D design, vector import (SVG/DXF), tool library selection, project cloud sync, and 3D simulation preview.
• Local PC Driver (CAM Engine & Hardware Bridge): A dedicated native daemon running on the user's PC. It executes heavy CAM toolpath generation (toolpath offsets, step-downs, feed calculations), and manages low-latency hardware communication with the CNC router over USB serial or local Wi-Fi.
• CNC Controller: Standard 3-axis desktop CNC machine running GRBL-compatible firmware.

+------------------------------------+
|       Laetoly Web (Browser)        |
|   - 2D Canvas & Vector Import      |
|   - 3D Cut Preview & Simulation    |
|   - Tool Library & Project Sync    |
+-----------------+------------------+
                  | Local Loopback (WebSocket / IPC)
                  v
+-----------------+------------------+
|       Laetoly PC Driver            |
|   - Native CAM Toolpath Engine     |
|   - Post-Processor & G-Code Gen    |
|   - Serial / Wi-Fi Machine Control |
+-----------------+------------------+
                  | USB Serial (115200 Baud) / Wi-Fi
                  v
+-----------------+------------------+
|       GRBL-Compatible CNC Router   |
|   - 3-Axis Stepper Motion (XYZ)    |
|   - Spindle & Safety Limit Switches|
+------------------------------------+

Buffer Management: Character-Counting Protocol

The approved Driver V2 notes describe GRBL or FluidNC controllers with a 128-byte receive ring buffer. To prevent buffer overruns, the Laetoly PC Driver follows the GRBL Character-Counting approach:

1. Maintain an integer counter buffer_available initialized to 128 bytes.
2. For each outgoing command line (including \r\n), subtract its byte length from buffer_available.
3. If buffer_available < line_length, block until an ok or error: response is received from the hardware.
4. When ok is received, restore the length of the oldest completed command to buffer_available.

Real-Time Command Interception

Non-blocking single-byte commands (such as ! for feed hold, ~ for cycle resume, and ? for real-time status queries) are prioritized over the queued G-code stream. The V2 notes specify a 500 ms debounce before a WebSocket drop triggers feed hold and M5; end-to-end response depends on the operating system, connection path, Driver build, and controller, so this page makes no sub-millisecond guarantee.