[{"data":1,"prerenderedAt":386},["ShallowReactive",2],{"header-article-translation-en-section-none":3,"section-en-engineering":4},null,[5,232],{"id":6,"title":7,"body":8,"category":199,"date":200,"description":201,"difficulty":3,"draft":202,"duration":3,"extension":203,"featured":202,"image":204,"layout":208,"locale":209,"meta":210,"navigation":211,"path":212,"references":213,"related":3,"section":225,"seo":226,"slug":227,"status":228,"stem":229,"tags":3,"translationKey":230,"updated":3,"video":3,"__hash__":231},"content\u002Fen\u002Fengineering\u002Fconnection-recovery-contract.md","Device Connection Conflict Recovery: Proposed Engineering Contract",{"type":9,"value":10,"toc":190},"minimark",[11,20,25,28,44,47,53,57,60,71,74,78,81,111,114,119,123,126,150,153,157,160,178,183,187],[12,13,16],"cnc-warning",{"level":14,"title":15},"warning","Roadmap contract, not a shipped recovery feature",[17,18,19],"p",{},"This page describes the recovery behavior Laetoly should implement. It does not claim that automatic reconnect, position restoration, command replay, or cycle resume is currently available. The operator must follow the machine manufacturer's emergency and recovery procedure first.",[21,22,24],"h2",{"id":23},"the-failure-we-must-contain","The failure we must contain",[17,26,27],{},"A CNC connection drop is not just a networking error. The controller may still be moving, holding, alarmed, or waiting for input while the browser has lost its view of the session. A second process may also be probing the same serial device. The recovery contract must therefore fail closed:",[29,30,31,35,38,41],"ul",{},[32,33,34],"li",{},"one active application owns a controller session;",[32,36,37],{},"an uncertain command is never marked complete from a reconnect alone;",[32,39,40],{},"a reconnect never authorizes motion by itself;",[32,42,43],{},"work coordinates and modal state are re-read before any operator-approved motion.",[17,45,46],{},"Operating systems differ in how they expose serial ownership. “Single owner” is an application invariant, not a claim that every driver rejects every second open in the same way.",[48,49],"figure",{"alt":50,"caption":51,"src":52},"Schematic of Grbl alarm, hold, and recovery states","Schematic: controller state must be observed and acknowledged before a recovery path continues.","\u002Fmedia\u002Fdiagrams\u002Fconnection-recovery\u002Fgrbl-state-machine.svg",[21,54,56],{"id":55},"recovery-state-machine","Recovery state machine",[17,58,59],{},"The proposed state sequence is:",[61,62,68],"pre",{"className":63,"code":65,"language":66,"meta":67},[64],"language-text","Connected\n  -> Link stale\n  -> Motion hold \u002F operator stop\n  -> Port ownership check\n  -> Reconnect without motion\n  -> Query controller state\n  -> Compare session checkpoint\n  -> Manual approval or blocked recovery\n","text","",[69,70,65],"code",{"__ignoreMap":67},[17,72,73],{},"Each transition must produce an observable event in the driver log and a visible state in the UI. A timeout is a blocked state, not a reason to jump to the next step.",[21,75,77],{"id":76},"what-must-be-queried","What must be queried",[17,79,80],{},"After the serial session is reacquired, the driver should query the controller using the protocol supported by the target firmware. For Grbl v1.1, the interface documentation describes:",[29,82,83,89,95,101],{},[32,84,85,88],{},[69,86,87],{},"?"," for a real-time status report;",[32,90,91,94],{},[69,92,93],{},"$G"," for the current parser modal state;",[32,96,97,100],{},[69,98,99],{},"$#"," for stored coordinate parameters, including work coordinate offsets;",[32,102,103,106,107,110],{},[69,104,105],{},"!"," and ",[69,108,109],{},"~"," as real-time hold and resume controls.",[17,112,113],{},"The driver must validate the response shape and firmware identity before using any value. A response timeout, malformed report, changed firmware family, or mismatch with the saved session checkpoint keeps the job blocked.",[48,115],{"alt":116,"caption":117,"src":118},"Schematic of preserving work coordinate offsets through a reconnect","Schematic: work offsets must be re-read; a local copy is not proof of the controller's current state.","\u002Fmedia\u002Fdiagrams\u002Fconnection-recovery\u002Fcoordinate-offsets.svg",[21,120,122],{"id":121},"what-must-not-happen-automatically","What must not happen automatically",[17,124,125],{},"The first implementation must not:",[29,127,128,131,134,137,144,147],{},[32,129,130],{},"replay unknown in-flight commands;",[32,132,133],{},"assume the last acknowledged line equals the controller's physical position;",[32,135,136],{},"send a cycle start immediately after a port opens;",[32,138,139,140,143],{},"use ",[69,141,142],{},"$X"," to bypass an unresolved alarm or safety condition;",[32,145,146],{},"infer that work zero survived from browser state alone;",[32,148,149],{},"let a sample configuration file become the runtime source of truth.",[17,151,152],{},"If the machine moved while the link was unavailable, software cannot reconstruct physical position from a browser timestamp. The safe outcome is a visible checklist and operator inspection.",[21,154,156],{"id":155},"operator-approval-checklist","Operator approval checklist",[17,158,159],{},"Before an approved recovery motion, the UI should require confirmation of:",[161,162,163,166,169,172,175],"ol",{},[32,164,165],{},"the process that owns the serial port;",[32,167,168],{},"controller firmware and current state;",[32,170,171],{},"work coordinate system and offsets;",[32,173,174],{},"tool, stock, clamp, and safe-height clearance;",[32,176,177],{},"whether the operator intends to re-home, re-zero, abandon, or restart the job.",[48,179],{"alt":180,"caption":181,"src":182},"Schematic of checking workholding and clearance before recovery motion","Schematic: physical clearance is an operator check; it cannot be inferred from a reconnect event.","\u002Fmedia\u002Fdiagrams\u002Fconnection-recovery\u002Fworkholding-clearance.svg",[21,184,186],{"id":185},"implementation-boundary","Implementation boundary",[17,188,189],{},"The first milestone should ship the state model, logging, blocked recovery screen, and read-only controller queries. Command replay, resume checkpoints, and any automatic feed override require a separate protocol review and hardware test matrix. Until those exist, the correct engineering behavior is slower recovery with explicit human approval rather than a fast but untrusted resume.",{"title":67,"searchDepth":191,"depth":191,"links":192},2,[193,194,195,196,197,198],{"id":23,"depth":191,"text":24},{"id":55,"depth":191,"text":56},{"id":76,"depth":191,"text":77},{"id":121,"depth":191,"text":122},{"id":155,"depth":191,"text":156},{"id":185,"depth":191,"text":186},"Architecture","2026-09-09","A fail-closed recovery contract for serial ownership, controller state verification, and operator approval after a CNC connection drop.",false,"md",{"src":205,"alt":206,"caption":207},"\u002Fmedia\u002Farticle-covers\u002Fengineering\u002Fconnection-recovery.webp","Conceptual connection between a CNC controller, local driver, and browser workspace","Conceptual architecture illustration; it does not represent a shipped Laetoly UI or hardware topology.","article","en",{},true,"\u002Fen\u002Fengineering\u002Fconnection-recovery-contract",[214,218,222],{"id":215,"title":216,"url":217},"grbl-interface","Grbl v1.1 Interface Basics","https:\u002F\u002Fgithub.com\u002Fgnea\u002Fgrbl\u002Fblob\u002Fmaster\u002Fdoc\u002Fmarkdown\u002Finterface.md",{"id":219,"title":220,"url":221},"grbl-commands","Grbl v1.1 Commands","https:\u002F\u002Fgithub.com\u002Fgnea\u002Fgrbl\u002Fblob\u002Fmaster\u002Fdoc\u002Fmarkdown\u002Fcommands.md",{"id":223,"title":224},"laetoly-driver-bridge-v2","Technical Architecture Spec: Laetoly Driver WebSocket Bridge Protocol V2","engineering",{"title":7,"description":201},"connection-recovery-contract","roadmap","en\u002Fengineering\u002Fconnection-recovery-contract","engineering-connection-recovery-contract","RoYokJBFgfnyEKENfzUyNeXgy-nHS_MHcFtnevpHzBc",{"id":233,"title":234,"body":235,"category":199,"date":366,"description":367,"difficulty":3,"draft":202,"duration":3,"extension":203,"featured":202,"image":3,"layout":208,"locale":209,"meta":368,"navigation":211,"path":369,"references":370,"related":3,"section":225,"seo":380,"slug":381,"status":382,"stem":383,"tags":3,"translationKey":384,"updated":3,"video":3,"__hash__":385},"content\u002Fen\u002Fengineering\u002Fdriver-bridge-architecture.md","Architecture of Laetoly Driver Bridge & GRBL Protocol",{"type":9,"value":236,"toc":361},[237,241,249,258,282,288,292,299,341,345],[21,238,240],{"id":239},"system-architecture","System Architecture",[17,242,243,244,248],{},"The core engineering principle of Laetoly is ",[245,246,247],"strong",{},"Physical Decoupling between Cloud\u002FBrowser Workspace and Local CAM Computation",":",[250,251,252],"blockquote",{},[17,253,254,257],{},[245,255,256],{},"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.",[29,259,260,270,276],{},[32,261,262,265,266,269],{},[245,263,264],{},"Browser Workspace (Laetoly Web)",": Runs in the browser at ",[69,267,268],{},"app.laetoly.com",". Responsible for 2D design, vector import (SVG\u002FDXF), tool library selection, project cloud sync, and 3D simulation preview.",[32,271,272,275],{},[245,273,274],{},"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.",[32,277,278,281],{},[245,279,280],{},"CNC Controller",": Standard 3-axis desktop CNC machine running GRBL-compatible firmware.",[61,283,286],{"className":284,"code":285,"language":66},[64],"+------------------------------------+\n|       Laetoly Web (Browser)        |\n|   - 2D Canvas & Vector Import      |\n|   - 3D Cut Preview & Simulation    |\n|   - Tool Library & Project Sync    |\n+-----------------+------------------+\n                  | Local Loopback (WebSocket \u002F IPC)\n                  v\n+-----------------+------------------+\n|       Laetoly PC Driver            |\n|   - Native CAM Toolpath Engine     |\n|   - Post-Processor & G-Code Gen    |\n|   - Serial \u002F Wi-Fi Machine Control |\n+-----------------+------------------+\n                  | USB Serial (115200 Baud) \u002F Wi-Fi\n                  v\n+-----------------+------------------+\n|       GRBL-Compatible CNC Router   |\n|   - 3-Axis Stepper Motion (XYZ)    |\n|   - Spindle & Safety Limit Switches|\n+------------------------------------+\n",[69,287,285],{"__ignoreMap":67},[21,289,291],{"id":290},"buffer-management-character-counting-protocol","Buffer Management: Character-Counting Protocol",[17,293,294,295,298],{},"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 ",[245,296,297],{},"Character-Counting"," approach:",[161,300,301,308,318,333],{},[32,302,303,304,307],{},"Maintain an integer counter ",[69,305,306],{},"buffer_available"," initialized to 128 bytes.",[32,309,310,311,314,315,317],{},"For each outgoing command line (including ",[69,312,313],{},"\\r\\n","), subtract its byte length from ",[69,316,306],{},".",[32,319,320,321,324,325,328,329,332],{},"If ",[69,322,323],{},"buffer_available \u003C line_length",", block until an ",[69,326,327],{},"ok"," or ",[69,330,331],{},"error:"," response is received from the hardware.",[32,334,335,336,338,339,317],{},"When ",[69,337,327],{}," is received, restore the length of the oldest completed command to ",[69,340,306],{},[21,342,344],{"id":343},"real-time-command-interception","Real-Time Command Interception",[17,346,347,348,350,351,353,354,356,357,360],{},"Non-blocking single-byte commands (such as ",[69,349,105],{}," for feed hold, ",[69,352,109],{}," for cycle resume, and ",[69,355,87],{}," 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 ",[69,358,359],{},"M5","; end-to-end response depends on the operating system, connection path, Driver build, and controller, so this page makes no sub-millisecond guarantee.",{"title":67,"searchDepth":191,"depth":191,"links":362},[363,364,365],{"id":239,"depth":191,"text":240},{"id":290,"depth":191,"text":291},{"id":343,"depth":191,"text":344},"2026-09-08","How Laetoly bridges high-level browser design with local PC CAM computation and hardware serial control.",{},"\u002Fen\u002Fengineering\u002Fdriver-bridge-architecture",[371,374,378],{"id":372,"title":373,"url":217},"grbl-protocol","GRBL v1.1 Interface Basics",{"id":375,"title":376,"url":377},"rfc-6455","The WebSocket Protocol (RFC 6455)","https:\u002F\u002Fdatatracker.ietf.org\u002Fdoc\u002Fhtml\u002Frfc6455",{"id":379,"title":224},"spec-proto-01",{"title":234,"description":367},"driver-bridge-architecture","experimental","en\u002Fengineering\u002Fdriver-bridge-architecture","engineering-driver-architecture","E-O0l_cIvxKpoG_sIlCrxciumPMrJKNjp6R_O03eK9g",1789009347281]