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.

## Power

The controller drives the tube the way the factory does: every pulse
fires at full power, and the power setting decides how many ticks of
each 710 us period fire. Every power level marks, low levels included,
because no pulse is ever too weak to strike. The raw response is not
linear - 80 % of the pulses deliver about half the light - so the
controller maps your power setting through a measured dose curve: 50 %
commands half the light, not half the pulses. The machine ships with
the bench-measured curve; record your own tube's from the control
panel (GRBL tab, "Dose-curve recorder": download the ladder file, press
Record, run the file from LightBurn on scrap, press the button, Apply
the fit). Grayscale images fade cleanly into the shadows (a low level
becomes sparse full-power pulses), and 254 to 508 DPI rasters hold
their tonal steps.

`$35`, the power floor, is set by the controller from the machine config
(the control panel's GRBL tab, "Laser dose"): do not type it, it is
overwritten at every job.

## 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 **20 %** (any nonzero power marks under the default power
   model; 20 % is a light pass on scrap), turn the layer's **Air Assist**
   on, close the lid, **Frame**, **Start**, and press the white button
   when it lights. Watch the whole job.