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.** The big button, LightBurn's Stop, and opening the
  lid each halt the job. 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.
- 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.
- **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). 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.