forgefirm/docs/LIGHTBURN.md

LightBurn setup & operation (ForgeFIRM)

Before you cut — safety (read this first)

ForgeFIRM replaces the factory software, not the factory safety rules. The machine contains a Class 4 CO₂ laser emitting invisible 10.6 µm infrared at roughly 45 W. Jobs sent from LightBurn fire the laser.

• Eyes. The enclosure and lid glass are the eye-safety barrier. Never defeat the lid switches or the Pro's remote-interlock plug, and never operate with any cover removed. Direct or reflected 10.6 µm radiation blinds and burns.
• Fumes. Vent the exhaust to the outdoors, always. Laser-cutting fumes are toxic and flammable.
• Materials. Never cut PVC, vinyl, or any chlorinated plastic — they release chlorine gas that corrodes the machine and injures your lungs. Know what your material is before you cut it.
• Fire. Never leave a running job unattended. Small flare-ups are normal with some materials; sustained flame is not. Keep a fire extinguisher (CO₂ preferred) within reach and know how you will open the lid and smother a fire before you start.
• Stop means stop. Opening the lid cancels the job (the beam is cut by the hardware the same instant); LightBurn's Stop aborts it; the big button pauses it. If anything looks wrong, stop first and diagnose second.

The laser fires only inside an operator-armed window:

• Starting a job that fires: press the button. At the first laser-on command of a job the machine unlocks its laser latch, lights the big button white, and pauses the incoming gcode until you press the button (the same press the factory firmware requires). LightBurn simply waits; press the button and the job runs. If nobody presses within laser_button_timeout_s (default 300 s) the job aborts with alarm 3. Stop in LightBurn (soft reset) cancels the wait at any time. Opening the lid (or a Pro's interlock loop) while the button is lit cancels the job the same way — the message names the reason, the latch relocks, and a press with the lid open never arms; the job ends for LightBurn (a clean cancel, no alarm to clear); close the lid and start again.
• One press covers one job — power changes and M5/M3 toggles do not re-prompt. The window relocks when the job ends (program end M2/M30), when the sender connection changes, or after laser_disarm_s (default 60 s) with the spindle off — counting even while a job sits paused in Hold or with the lid open; the next job prompts again. Both timeouts are machine settings (keys in /data/forgefirm.conf, set through the control panel's settings API); the defaults suit normal use.
• S-value scale: $30 defaults to 1000, so set LightBurn's S-max to 1000. 100 % power = S1000. Use M4 (variable/dynamic) mode for cuts and engraves.
• The machine forces the cut fan profile on while armed and continuously verifies coolant flow; a flow fault or over-temperature pauses/blocks firing (messages appear in LightBurn's console).
• The hardware safety chain stands above all of this: lid open, interlock open, or power faults make firing physically impossible regardless of software state.

One-time device setup

Prerequisite: the controller is running on the board (see BRINGUP.md; grblHAL_glowforge on TCP port 23 at your machine's IP address, shown below as <machine-ip>).

1. Laser window → Devices → Create Manually (skip auto-find; it scans serial ports).
2. Device type: grblHAL if your LightBurn version lists it, otherwise GRBL — both speak the right protocol.
3. Connection: Ethernet/TCP. IP address: <machine-ip> (LightBurn uses TCP port 23 for GRBL devices, which is exactly where the controller listens).
4. Name: e.g. Glowforge ForgeFIRM. Work area: X 495 mm, Y 279 mm.
5. Origin: pick the corner where the head sits after parking at home — rear-left as you face the machine (the top-left dot in the selector). This is what keeps jobs un-mirrored: machine +X runs right, +Y runs from the rear rail toward you.
6. Auto-home on startup: NO — LightBurn would issue $H at every connect, and the working homing method runs a multi-minute session. $H itself works and is selected by the homing_mode setting in the machine's web control panel: gfcloud (Glowforge web-service vision homing — the working method; X/Y home to the factory corner, Z to the hall sensor; requires a signed-in Glowforge session), switches (physical limit switches, once installed), or none ($H is rejected). Run $H deliberately from the Console tab when you want a true machine origin.
7. Finish. If a stale device profile already exists, edit its IP instead of creating a new one.
8. Device Settings (wrench icon): S-Value Max = 1000 (matches $30).
9. Optional backup: File → Export Devices → saves a .lbdev you can re-import later (the format is not editable text; export is the way to make one).

Job start mode (important on an unhomed machine)

In the Laser window set Start From: Current Position, and set the Job Origin dot to the same corner as the machine origin (top-left dot). The job then runs into the bed from wherever the head currently sits — absolute machine zero never matters, which is the forgiving mode when you have not homed.

(Absolute Coords also works after a successful $H, or if the head was parked at the home corner when the controller started. After any Stop/alarm the absolute frame is stale until you re-home with $H or restart the controller with the head re-parked.)

Operating basics

• Frame traces the job's bounding box at travel speed — do it before every Start. There are no limit switches: framing is your crash protection.
• Start runs the job. Travels run up to 200 mm/s; anything faster in a layer is clamped by the controller ($110/$111 = 12000 mm/min).
• Pause = grbl feed hold: motion parks within ~0.4 s (0.2 s stream queue + deceleration); Resume continues exactly. The big button does the same: one press while a job runs pauses it (LightBurn shows Hold), the next press resumes it — the factory's pause/resume, on the machine. Two things to know before you pause a cut. Resume where it stopped: there is no backtrack in GRBL mode, so the beam restarts from where the deceleration ended and accelerates away from a standstill — at constant power (M3) that leaves a deeper spot you can see, while M4 scales power with speed and mostly hides it. Don't leave it paused: the armed window has an idle grace (laser_disarm_s, default 60 s) that counts down through a hold, so a job left paused disarms itself and the resume asks for the button again before it can fire.
• Opening the lid (or a Pro's interlock loop) during a job cancels it, as the factory firmware does: the head parks with a controlled deceleration (the hardware cut the beam the instant the lid moved), the console reports the reason, the job ends for LightBurn (the controller resets — position is kept, no alarm), and the head returns on its own to where the job started, lid open or not. Close the lid and start again from LightBurn; the next job asks for the button, which is also what re-arms the machine's hardware button latch. The lid_policy setting on the control panel's GRBL tab can select the stock Grbl behavior instead (Door hold, Resume once closed). At idle, while jogging, or during homing the lid is yours to open and close freely — the controller does nothing there (the hardware blocks the beam anyway), so a lid cycle while loading material never leaves LightBurn waiting.
• Stop = soft reset: motion aborts with a controlled deceleration and grblHAL raises an alarm with position declared lost (the stream queue means up to ~40 mm of in-flight difference). It leaves the head where it stopped — the return to the job start belongs to the lid and interlock policy alone, so Stop never moves the machine on its own. Recovery: unlock ($X in Console or LightBurn's prompt), jog the head clear, and carry on in Current Position mode. Restart the controller with the head re-parked if you want a clean absolute frame.
• Move tab: jogging (set a sane speed, e.g. 6000 mm/min), Get Position, distance buttons.
• Console tab: raw grbl — ? status, $$ settings, $X unlock, $J=G91X10F1200 jog.

Air assist / fans

Each cut/engrave layer has an Air Assist toggle (in the layer's cut settings). Turning it on makes LightBurn emit M8/M9 around that layer, which drives the machine's full cut-profile ventilation: air assist to full, exhaust and intake fans to factory run speeds, then a ~15 s cooldown after the layer before returning to idle. Leave it ON for anything that will eventually involve the beam; expect real fan noise.

Dry runs (motion only, no fire)

Setting a low power value does NOT make a job inert — any laser layer prompts for the arm button and then fires. The motion-only modes are:

• Frame and jogging — never fire.
• A job whose layers emit no laser-on command: turn the layer's Output off in the cut settings, or send gcode that stays in M5.
• A job run with the laser latch left locked (never press the arm button): the job pauses at the white-button prompt and aborts after laser_button_timeout_s — useful only to confirm the prompt itself.

If the white arm prompt appears and you did not intend to fire, press Stop in LightBurn.

A good first job

First a dry run, then a light cut on scrap:

1. Draw a rectangle (~100 × 60 mm) with a circle inside.
2. Double-click the layer color bar (bottom): mode Line, speed 50 mm/s (= 3000 mm/min; check Edit → Settings for your speed units). For the dry run turn the layer's Output off.
3. Park the head where the job's rear-left corner should be (or leave it at home), Frame, watch the perimeter trace, then Start.

Expected behavior: darting travels at up to 200 mm/s, smooth 50 mm/s tracing of the shapes, silky and near-silent motion (factory currents + decay mode), and the head finishing per the job's return setting.

4. For the live pass: put scrap material on the bed (never an empty honeycomb over the fan grill), re-enable the layer's Output, set power to 30 % or more (below ~30 % the tube barely marks), turn the layer's Air Assist on, close the lid, Frame, Start, and press the white button when it lights. Watch the whole job.