forgefirm/docs/COOLING.md

Cooling and airflow

The tube is water-cooled and the enclosure is air-cleared, and both matter while the laser fires: coolant that has stopped circulating will let a tube overheat within a cut, and smoke that is not pulled out spoils the work and fogs the optics. ForgeFIRM runs this as one service — the cooling engine — that owns every piece of thermal hardware and answers one question at a time for whichever controller is running: is it safe to fire right now?

This page explains what the system is made of, how it decides, what you will see when it intervenes, and what you can tune.

• The beam itself is gated in hardware; see Laser safety.
• For how the laser and motion are driven, see Motion and laser drive.

---

1. What the hardware is

The coolant loop is closed: a pump, a radiator with fans, the laser tube, and two thermistors — one upstream of the tube and one downstream of a small inline heater. Pro machines are specified with a thermoelectric cooler (TEC) on the loop; the board cannot tell whether one is fitted (§9). The heater exists for diagnostics, not for warming the machine up: it is how the engine proves the coolant is actually moving (§4).

The airflow path has four independently driven pieces:

Piece	What it does
Exhaust blower	pulls smoke out of the enclosure
Two intake fans	feed clean air in behind it
Air assist (in the head)	blows the cut line clear at the focal point
Purge air (in the head)	keeps the optics clean; on whenever the machine is on

Every fan reports a tachometer, so the engine can tell a commanded duty from an actual airflow, and the panel shows real speeds rather than setpoints.

Coolant temperature is read, not guessed. Both thermistors are converted with the factory's own beta-equation curve, checked against a thermometer. A sensor reading at either rail is treated as open or shorted — not as a temperature.

---

2. One owner, two clients

The cooling engine lives in forgectrl, the machine-services daemon, and it is the only thing that writes fans, pump, TEC and heater. Whichever controller is running — GRBL or cloud — is a client of it, over two channels:

• The controller reports its job state about once a second: idle, running or cooling down, whether the laser is armed, and (in cloud mode) the fan duties the job asks for. The reports are level-triggered, so a lost one simply corrects itself on the next.
• The engine publishes a verdict the controller reads and enforces in its own process: may the laser fire, should the job hold, may it resume.

Two properties of that split are worth understanding, because they explain the machine's behavior in odd situations:

A missing verdict is a bad verdict. If the verdict is absent or more than two seconds old, a controller treats it as fire blocked, hold. The engine going away looks exactly like a fault, never like permission.

Arming requires being seen. The engine only grants fire when it is receiving fresh job reports. A controller about to fire is, by contract, one that is reporting — an armed window the engine cannot see never gets a green light.

If a controller goes silent past five seconds, the engine blocks fire immediately and stands the machine down through the normal cooldown, because a smoke clear is the right physical response to a job that died mid-cut. If the silence happens while the laser is armed, or while the pulse engine still says a program is playing, the engine additionally stops motion and locks the laser latch itself. It also refuses to let exhaust and intake drop below cooldown duty while a program is still running.

If a diagnostic takes the hardware over (§6), the engine suspends its own writes and publishes fire-blocked until the diagnostic finishes.

If the engine itself is provably gone while the laser is armed, the controller writes the factory run duties to the fans once, holds the job, and stands down. That is the single sanctioned exception to single-owner control, and the duties are compiled in so that a lost configuration file cannot take the fans with it.

---

3. What the fans do, and when

The engine runs in phases. Duties are the factory machine's own values.

Phase	Pump	Air assist	Exhaust	Intake	Heater
Idle	on	204	off	off	off
Run (or armed, whatever the reported mode)	on	1023	65535	43278	flow checks only
Cooldown — smoke clear (15 s)	on	run duty	run duty	run duty	off
Cooldown — thermal	on	idle	32768	21639	off
Over-temp / fault hold	on	run duty	forced	forced	off

Notes on the phases:

• The pump runs whenever the machine is on, including at idle. Circulation is cheap; a stagnant loop with a warm tube is not.
• The heater is off at idle by design. An always-on flow heater measurably warms the loop within minutes, eating headroom below the start gate for no benefit while nothing can fire.
• Being armed counts as running. If the laser is armed, the engine forces the run profile and the flow checks regardless of what mode the controller reported — fire never happens without cut airflow and active flow verification.
• Cooldown has two stages: a smoke clear at full run duty, then reduced airflow (the radiator cools the loop measurably) until the upstream coolant temperature is back under the resume gate or the cooldown budget expires.
• The TEC is left off. Its output has no readback, so the machine cannot tell whether one is fitted; driving it blind is not something ForgeFIRM does (see §9).

In GRBL mode the run profile follows your sender's M8/M9 (LightBurn's per-layer Air Assist), OR'd with the armed window. In cloud mode the job's own header carries the duties and the client passes them through, so a print gets the fan profile the service designed for it and a lens hunt stays quiet.

---

4. Coolant flow verification

The problem

A pump can stop, an impeller can slip, a line can airlock — and none of it shows up in a temperature reading until the tube is already in trouble. Absolute coolant temperature only tracks a loop that is circulating, and "coolant should warm up while cutting" is not a usable signal either: a light engrave may add no measurable heat at all.

The method

The small heater sits between the two thermistors. Each check runs it at a fixed duty for a fixed window and watches how far the downstream sensor climbs:

• flowing coolant carries that heat away — the downstream sensor rises a little;
• a stagnant loop cooks the sensor — the downstream sensor rises a lot.

The discriminator is the rise, not the difference between sensors, and the operating point is measured rather than assumed:

Parameter	Value	Why
Heater duty	40 %	Below about 40 %, natural convection sheds the heat well enough to mimic flow — dead-pump trials have looked healthier than a working pump. At 40 % heat input outruns convection, and it is the cheapest duty that does.
Window	50 s	Long enough for the bands to separate cleanly.
Fault threshold	14.4 °C rise	Midway between the observed flowing band and the observed stagnant band.
Re-check interval	150 s	A pump that stops mid-job is invisible otherwise.

Each check costs the loop under a degree of heating, and with cut-profile fans running the loop still nets cooler over a long job.

Checks start from a settled loop

Measuring a rise from a baseline captured while the loop is still cooling from earlier heat produces garbage — and it fails in the dangerous direction: it can report flow with the pump stopped. So a check is requested, and starts only once the two sensors agree within 1.5 °C and the downstream reading has stopped drifting.

Stationarity is judged by comparing the mean of the first half of a 15-second window against the second half, not by peak-to-peak spread. On a settled loop, peak-to-peak noise is about 0.5 °C while the split-half difference is about 0.1 °C — any peak-to-peak threshold tight enough to catch real drift would sit below the noise floor and never open the gate.

One bad reading is a suspicion, not a fault

Transients happen: cycling the pump by hand can burp an airlock that clears itself within minutes. So the engine runs a two-step decision:

1. First over-limit check → COOLANT FLOW SUSPECT. A warning, a hold request, and an immediate re-check — no waiting for the normal cadence.
2. The next completed check decides. Over-limit again, with no clean check in between → COOLANT FLOW FAULT. Clean → the suspicion clears and the job continues.

Two more rules close the loopholes:

• A suspicion that cannot resolve escalates. If no verdict can be produced within the confirmation budget (default 480 s), it becomes a fault: a loop that will not settle after a fault-level reading has shown no evidence of health.
• Cleared suspicions still count. Three of them in one job earn an aggregated "check your coolant" warning; the counter resets when cooldown reaches idle.

A clean check from the fault state logs a recovery.

What the verdicts do

Verdict	Effect
OK	Fire permitted.
SUSPECT	Hold requested, cut airflow held; auto-resumes on a clean re-check.
FAULT	Fire gated and the hold stands — for the operator to resolve.
OVERTEMP	Hold with forced cooling airflow; auto-resumes below the resume gate (§5).
FIRE	Motion stopped, latch locked, hold until the next run session (§7).

Practical note: expect a legitimate suspicion on the first checks after manually stopping and starting the pump. That is an airlock, the machinery above absorbs it, and it clears on its own.

---

5. Over-temperature

The engine uses the factory's coolant windows:

• Run ceiling 33 °C — above this, the verdict goes OVERTEMP with a hold request and cooling airflow forced on.
• Resume gate 31 °C — below this, recovery is signaled and the controller resumes automatically.

The upstream sensor gates, because it reads the coolant actually entering the tube.

What you see depends on what the machine was doing. A running cycle takes a feed hold and resumes by itself once the loop recovers — your sender shows the hold state and a warning message. A jog is canceled instead (a jog cannot be held). Fire stays gated for the whole excursion.

---

6. Diagnostics: verifying and calibrating flow

The web panel's Diagnostics tab runs the two cooling tools. Both take the hardware over: the active controller is suspended for the duration, the engine stands aside, and the controller is restored on every exit path — completion, error, or your pressing Abort. The laser stays latched throughout. Progress, both coolant temperatures and a scrolling log stream to the page while it runs.

Both tools run at your configured duty, window and threshold, so the verdict applies to the check the machine actually performs, and both use cut-profile chassis fans — the condition the numbers were characterized under. Any pump-off window aborts immediately if the downstream sensor passes 48 °C.

Flow verify (about 3 minutes) — one check with the pump running and one with it commanded off.

• PASS = your threshold separates the two readings.
• Margins under 1.5 °C add a warning that you should re-calibrate.
• A failure here means the threshold no longer suits the loop, or the loop has a real problem.

Flow calibrate (15–25 minutes) — three trials of each case, alternating, with settle gates between them. It reports both bands and recommends a threshold midway between the highest flowing reading and the lowest stagnant one, with an Apply button that writes it to your settings.

• If the gap between the bands is under 3 °C it refuses to recommend anything and tells you to raise the heater duty and rerun.

When to calibrate: after replacing coolant, after changing or servicing the pump, if flow verify warns about thin margins, or if you see suspicions that you can trace to nothing real. The shipped default suits the factory loop; a rebuilt one may differ.

---

7. The fire watch

Alongside the flow work, the engine watches for evidence of things going wrong at one-second resolution:

• Emission evidence. The kernel samples the gated output of the hardware AND-gate — actual emission, not a commanded state. Emission seen with no armed window in the recent past stops motion and locks the latch, and keeps doing so while the evidence persists.
• Laser power-good degradation during an armed window is warned once per session.
• Stepper-driver faults appearing during a run are warned, and HV current is ranged for each job in the same log line.
• Lid infrared channels are polled every tick, and every job logs their baseline and peaks.

About the lid IR fire watch specifically: it ships in watch-only mode and logs rather than acts. The reason is honest and worth stating — those sensors are, first of all, a photometer for the lid lamp. A full-power cut raises them only a few counts above the level the lamp sets, a candle burning on the bed raises them about the same amount, and anything that changes the lamp (a camera snapshot, for instance) moves them by tens of counts. A fixed threshold would therefore stop jobs for lighting changes while still missing a small flame. A lamp-aware design is planned; until then the channels are recorded, not acted on, and the fire watch is not a fire alarm. Never leave a running laser unattended.

---

8. Settings

All of these live in the panel's Machine tab, are validated on entry, and can only be changed while the machine is idle. The engine re-reads them at the start of every run, so a change takes effect on your next job.

Setting	Default	What it controls
cool_flow_rise	14.4 °C	Downstream rise that counts as no-flow. Set this from flow calibrate.
cool_flow_heater_pct	40 %	Heater duty during a check. Raising it separates the bands further at the cost of warming the loop more.
cool_flow_check_s	50 s	Length of a check window. 0 disables flow verification entirely.
cool_recheck_s	150 s	How often checks repeat during a job.
cool_confirm_max_s	480 s	How long a suspicion may stay unresolved before it escalates to a fault.
cool_temp_max	33 °C	Run ceiling — above it, hold.
cool_temp_resume	31 °C	Resume gate — below it, continue.
cool_cooldown_s	15 s	Smoke-clear phase at run duty after a job.
cool_cooldown_max_s	300 s	Cap on the thermal cooldown phase.

Two settings are deliberately not on the panel:

• cool_fire_ir_delta — the lid-IR fire gate (§7). It is 0, watch-only, and changing it by hand is not recommended until the watch is lamp-aware.
• GFCOOL_* environment overrides exist for bench work; they win for the lifetime of the process and are not a normal operating path.

---

9. Not implemented yet

Stated plainly so nobody counts on them:

• Low-temperature gates and warm-up. The factory holds a job and warms the coolant when the loop is below roughly 16 °C, and refuses to fire at all near freezing. ForgeFIRM does not yet; a cold-room machine will start cutting at a temperature the factory would have waited out. Two settings — a hard floor and a warm-up gate — are planned.
• TEC control. ForgeFIRM never drives the thermoelectric cooler. Presence cannot be detected (the output has no readback), so this will become a user setting plus a simple hysteresis around the factory's setpoints.
• A fire watch that acts (§7).

---

10. Quick reference: what the machine does when

Situation	Machine response
Idle	Pump on, purge air on, fans at idle, heater off, TEC off.
Job starts (or the laser arms)	Cut airflow, flow check requested once the loop is settled.
Flow check over limit, first time	SUSPECT: warning, hold, immediate re-check.
Second consecutive over limit	FAULT: fire gated, hold stands until you resolve it.
Suspicion unresolved past the budget	Escalates to FAULT.
Three cleared suspicions in one job	Aggregated "check your coolant" warning.
Upstream coolant above 33 °C	OVERTEMP: hold + forced cooling; auto-resume under 31 °C.
Job ends	15 s smoke clear at run duty, then reduced airflow until the loop is under the resume gate.
Controller stops reporting	Fire blocked at once, stand-down through cooldown.
Silence while armed, or a program still playing	Motion stopped and the latch locked by the engine itself.
Verdict file missing or stale	The controller treats it as fire-blocked and holds.
Diagnostic running	Engine suspends its writes and publishes fire-blocked.
Engine gone while armed	Controller writes factory run duties once, holds, stands down.

---

See also

• Motion and laser drive — arming, job phases, both controller modes.
• Laser safety — the hardware chain the beam actually passes through.
• LightBurn setup & operation — M8/M9 and air assist in practice.
• forgectrl/docs/SERVICES.md — the machine-services contract, including the report and verdict channels in full.