forgefirm/docs/MOTION.md

Motion and laser drive

Everything the machine does physically — every step of the gantry, every lens move, every laser pulse — comes out of one stream of bytes played by hardware at a fixed rate. This page explains that stream, why the laser is part of it rather than beside it, and how the two controller modes (GRBL and cloud) feed it.

You do not need any of this to run a job. It is here so that what the machine does makes sense, and so the settings you can change mean something.

• To cut from LightBurn, see LightBurn setup & operation.
• For the safety chain that gates the beam, see Laser safety.
• For fans, pump and coolant, see Cooling and airflow.

---

1. The pulse stream

The control board does not decide, moment by moment, when to move a motor. Instead a hardware timer (EPIT) fires at a fixed machine tick, and a DMA engine (SDMA) hands the next byte of a prepared stream straight to the GPIO register that drives the stepper and laser lines. No software runs between the timer and the pins.

That is what makes motion smooth: step timing cannot be disturbed by a busy CPU, a camera stream, a network client, or a garbage collector. The worst a loaded system can do is fail to supply bytes fast enough — and that case is detected and treated as a fault rather than as silent damage.

One byte per tick

Each byte covers exactly one tick. If the top bit is clear, the byte commands steps and fire; if it is set, the byte sets laser power.

Bit	Meaning
0	X step
1	X direction (set = −X)
2	Y step
3	Y direction (set = +Y; the two Y motors are driven complementary)
4	Laser fire during this tick
5	Z step
6	Z direction (set = lens up, away from the bed = +Z)
7	0 = step byte · 1 = power byte (low 7 bits are the power level)

Speed is density, not clock. The tick rate never changes inside a job. Going faster means setting a step bit in more of the bytes; going slower means spacing them out. A move is planned in the usual way — acceleration, cruise, deceleration — and then resampled onto this fixed grid.

Two consequences worth knowing:

• Resolution is bounded by the tick rate. At the default GRBL machine tick of 28160 Hz, one axis can take at most 28160 steps per second — about 528 mm/s, comfortably above the machine's 200 mm/s top speed.
• There is a hardware ceiling. The playback script needs about 6 µs per byte, so beyond roughly 165 kHz the timer outruns it. Ticks are chosen far below that.

The ring, and two ways to fill it

Pulse bytes go into a 32 MiB ring buffer in reserved memory, the same size the factory firmware uses. There are two ways to use it, and the mode you run decides which:

• Live streaming (GRBL mode). The controller keeps only a small window of the job in the ring — a fraction of a second — and refills it continuously while the job plays. A write that would overflow is refused, and the feeder backs off; that is normal flow control, not an error. If the feeder ever falls behind far enough to empty the ring, the machine enters an underrun state: motion stops instantly, and position is no longer trusted.
• Preloading (cloud mode). The whole job is written into the ring before it starts. Nothing can starve, but the ring size caps job length: roughly 1 MiB per 100 seconds at the cloud's 10 kHz tick, so about 56 minutes. A job larger than the ring is rejected cleanly before it runs.

Stopping and resuming at the hardware level

The pulse engine itself offers three ways out of a running program, and both modes are built on them:

• Controlled stop — the tick rate ramps down at a set rate (125000 Hz/s by default) until motion halts. No steps are lost, so position stays accurate. This is what a feed hold, a jog cancel, a lid-open cancel and a soft reset all use.
• Halt — an immediate stop with no ramp. Steps can be lost; used only for emergencies.
• Resume with a waypoint — from a controlled stop the program can be resumed a chosen number of steps backward (laser forced off) or forward. This is how the factory's pause-and-resume works, and cloud mode uses it. It is only available for a preloaded job: a live-streamed ring no longer holds the bytes to back into, and the kernel refuses the request.

Whenever a stream ends — normally or by starvation — the playback script drives the fire and step lines low as a hardware backstop.

---

2. Laser drive is part of the motion stream

The laser is not a separate subsystem that gets told "on" and "off" while motion happens elsewhere. Power and fire ride the same bytes as the steps, on the same grid:

• A power byte (top bit set) sets the PWM duty of the laser drive: 7 bits written straight into the hardware PWM against a 127-count period, at a carrier near 40 kHz. 127 is full power.
• The fire bit (bit 4) requests emission for that one tick, and only that tick.

Because both travel with the steps, power and position cannot drift apart. A power change lands at exactly the point along the path where it was planned, regardless of what the rest of the system is doing.

Three rules follow from the hardware, and both controllers obey them:

1. Power before fire. Starting a program resets the duty to about 100 %, so a stream must set power before its first fire bit — otherwise the first pulses would fire at full power.
2. No two power bytes in a row. The playback script applies the first of a run of power bytes and discards the rest, so power changes are spaced by at least one step byte.
3. End dark. Every stream ends with fire clear; the end-of-data backstop is the safety net, not the mechanism.

Also worth knowing: the duty setting persists after a program ends. The laser-off guarantee rests entirely on the fire bit and the hardware chain, never on power being zero.

What actually lets the beam out

The fire bit is a request. Emission additionally requires the hardware safety chain — lid switches, the remote interlock loop, HV good, supply rails, the charge-pump watchdog the kernel feeds only while a program is playing, and the physical button latch — to agree. On top of that, ForgeFIRM keeps the kernel's laser latch locked except inside an operator-armed job window (§5.4), and the kernel relocks it whenever the pulse device is closed.

Fire only ever rides motion segments of laser blocks. Jogs, rapids and homing are fire-free by construction, not by convention. See SAFETY.md for the chain itself.

---

3. Geometry, speeds and limits

Property	Value
X/Y resolution	0.15 mm per full step, ×8 microstepping → 53.333 µsteps/mm
Z resolution	0.3534 mm per half-step → 2.832 half-steps/mm
Work area	495 × 279 mm
Z travel	about 10.6 mm (0.417"), hall-referenced at the top
Max X/Y rate	12000 mm/min (200 mm/s)
Max Z rate	300 mm/min
Acceleration	700 mm/s² X, 590 mm/s² Y, 50 mm/s² Z
Laser PWM carrier	39.98 kHz, 7-bit duty

Origin is the back-left corner, and the workspace is all-positive from there. +Y moves the gantry toward the front of the machine. Z counts positive upward, away from the bed.

Z is never driven blind: the lens carriage is referenced against a hall sensor at the top of travel, and moves are supervised against it.

The machine has no limit or home switches as it ships. What that means in practice — how each mode establishes an origin, and how the machine behaves without one — is in §5.7 and §6.3.

---

4. Who owns the motion hardware

forgectrl, the machine-services daemon, owns the pulse device for as long as it runs and hands the open connection to whichever controller is active. Only one controller — GRBL or cloud — runs at a time, and switching between them is a live operation from the web panel.

Two behaviors follow from this that you will notice:

• The 40 V motor rail stays up while the machine is on. Handing the device from one controller to another never cycles it. The stepper drivers on this board can latch into an unserviceable state on a rail glitch — the position counters keep counting while the motors produce nothing — so the rail is left alone.
• The machine proves it can move before the first job of a session. Before the first controller start, forgectrl makes a short test move (always to the right first — a cable lives at the left end of travel) and confirms it with the accelerometer in the print head. If it sees no motion it powers the rail down and retries with progressively longer off periods; if the drivers still will not wake, it reports a motion fault instead of starting a controller, and the panel offers a retry. Position counters advancing are never accepted as proof that the machine moved.

---

5. GRBL mode

GRBL mode turns the machine into a standard Grbl-speaking laser cutter. It is the default and the one to use for your own designs.

5.1 Connecting

The controller speaks Grbl 1.1 over TCP port 23. Point LightBurn, UGS, cncjs or any Grbl sender at the machine's address on port 23. Setup details and a first job are in LIGHTBURN.md.

Only one sender at a time is meaningful. Opening a second connection displaces the first — which is also why the web panel reads position from the machine's own counters and never from the Grbl socket.

5.2 From G-code to pulse bytes

1. Your sender streams G-code over TCP.
2. grblHAL parses it and plans motion in the usual way: look-ahead, junction deviation, acceleration ramps.
3. A producer thread runs the planner's step generator against a virtual clock a thousand times finer than the machine tick and places each step event on the byte grid.
4. A high-priority shipper thread writes due bytes to the pulse device roughly every 10 ms, keeping a bounded queue ahead of real time.

The queue depth is the trade: deeper means more immunity to system load, shallower means a feed hold or a power override takes effect sooner. The default is 200 ms, and the machine tick defaults to 28160 Hz — the same tick the factory firmware uses for travel moves.

5.3 Laser mapping

• $32 (laser mode) is on by default, so M3/M4 and S behave the way senders expect. M4 gives dynamic power scaled with speed through acceleration ramps; M3 gives constant power.
• $30 is 1000, and S values map linearly onto the 7-bit power byte — S1000 = full power, S500 ≈ half.
• Power changes are emitted ahead of the tick they apply to, so a power change and the motion it belongs to stay together.

5.4 Arming: the button press is part of every job

The first laser-on of a job does not fire. Instead the controller:

1. Checks the coolant verdict. If a flow fault or an over-temperature condition stands, arming is refused outright (COOLING.md).
2. Checks that a print head is present. No head, no arming.
3. Forces the cut airflow profile on, so every fire window is covered by running fans and active flow verification.
4. Unlocks the kernel laser latch, lights the button white, and pauses the job — the sender keeps getting status reports, so it does not time out — until you press the physical button.

A press with the lid open does not arm; the hardware button latch would not clear on it either. A soft reset, or a lid or interlock open, cancels the job instead. If nobody presses within laser_button_timeout_s (default 300 s), the job ends in an alarm with the latch relocked. The coolant verdict is re-checked after the press, so a window can never open against a fault that appeared during the wait.

The window is per job, not per fire. It survives S changes and M5/M3 toggles, so nothing re-prompts mid-job, and it closes — relocking the latch — when any of these happens:

• program end (M2, M30, %) — the normal case, within the cycle;
• the sender's connection changes (the consent belonged to that session);
• laser_disarm_s (default 60 s) of spindle-off idle, counted down in Hold, Door and Tool Change as well as Idle;
• immediately on alarm, homing, reset, or a stream fault.

5.5 Pausing, stopping and faults

You do	What happens
Feed hold (!)	Controlled ramp to a stop, position kept, laser off. The disarm grace keeps counting.
Cycle start (~)	Resumes from the hold. A live-streamed job cannot back up, so the cut resumes where the deceleration ended.
Jog cancel (0x85)	Controlled stop, jog abandoned, position kept.
Soft reset (^X)	Controlled deceleration into Alarm, latch relocked, machine position retained; $X clears the alarm.
Press the button mid-job	Pause; press again to resume (§5.6).
Open the lid or the interlock loop	The job is canceled, not paused (§5.6).
Ring runs dry (underrun)	Motion stops instantly. While armed this is a hard fault: alarm, latch relocked, position invalidated — re-home before trusting coordinates. A motion-only job gets one sanctioned retry.
Coolant fault or over-temp	Feed hold with cut airflow forced on; fire is gated. Over-temp resumes automatically once the loop recovers.
Controller crash or hang	The daemon stops motion and relocks the latch, then restarts the controller.

5.6 Lid, interlock and button

ForgeFIRM reproduces the factory machine's behavior:

• A lid or interlock open during a job cancels it. Motion stops within milliseconds of the switch edge, the job is not resumable, the latch relocks, and the head returns to the position the job started from — with the lid still open, exactly as the factory does. The return-home move always runs to completion.
• The button pauses and resumes. In GRBL mode a press is a feed hold and the next press is a cycle start. A pause is not a cancel: the armed window stays open across it.
• Idle lid cycles are ignored. Opening the lid to load material, or powering up with it open, does not leave the controller parked — senders connect normally.
• Jogs are not lid-gated. The core is blind to the door signal while it is idle, jogging or homing, so a jog both starts and runs with the lid open — the beam is blocked in hardware regardless.
• Homing is lid-gated in practice, even though the core does not see the door during $H. With homing_mode = gfcloud — the only method that works today — the cycle is a cloud homing session (§5.7), and its move to the home corner is an ordinary motion action: refused with the lid open, and stopped if the lid opens partway through. The camera steps need the lid closed anyway. Only the lens/Z hunt inside that session ignores the lid (§6.3), which is where hunts happen in GRBL mode — there is no hunt outside a cloud homing session. Under homing_mode = switches a Z reference would just be part of the core homing cycle.

The next job re-arms with a fresh button press — the same press the hardware button latch itself requires, which is why software and hardware cannot disagree about whether the machine is armed.

If you prefer stock Grbl door behavior, set lid_policy = hold: the job parks in the Door state and a cycle start after the lid closes finishes the move with its position intact.

5.7 Homing, and running unhomed

The homing method is a setting (homing_mode), chosen in the web panel:

• gfcloud — camera homing through the Glowforge web service, the same cycle the factory machine runs. $H suspends the stream engine, runs the session, then hands the machine back. Takes roughly a minute and uses the machine's builtin credentials.
• switches — the future limit-switch cycle. Not enabled yet; brackets for the switches are in the project's 3d-models/ directory.
• none — $H is rejected.

The machine cuts fine unhomed. Without a reference, coordinates are relative to wherever the head happened to be, so the panel shows position in red to say so, and your sender should use a job-start mode that does not depend on machine coordinates. After a successful home the position is anchored and shown normally.

Anything that invalidates position — an underrun, a stream fault — drops the anchor deliberately, so a stale origin cannot be reused.

---

6. Cloud mode

Cloud mode runs the factory experience: the Glowforge app and web service, the camera bed image, the lens hunt, "push the button to print". It is kept and maintained on purpose. Behavior specific to the service — actions, events, credentials — is in the cloud-mode documentation (python3-gfhardware/forgefirm-app/docs/CLOUD.md).

6.1 What is different about the motion path

In cloud mode the machine does not plan anything. The service sends a precomputed pulse file — already resampled to the byte format described in §1 — which the client downloads, writes into the ring, and plays:

1. The service issues a print action with a URL for the motion data.
2. The client downloads it and validates the header before a byte reaches the ring. A job larger than the ring is refused cleanly.
3. The header's own parameters are applied: the machine tick (10 kHz for prints and hunts), the acceleration ramp, and the per-job fan duties, which are passed to the cooling engine as the run profile.
4. The button wait arms the laser, exactly as in GRBL mode.
5. The ring plays to the end; the client supervises it and reports state.

Because the whole job is preloaded, there is no feeder to starve — but there is also no live re-planning, and job length is capped by the ring.

6.2 Pause, cancel and park

• The button pauses and resumes a print, and here it does so exactly as the factory does: a press stops motion under control and then backs the stream up 2000 ticks with the laser off; the next press runs forward and re-enables the laser after a 1950-tick lead, so the resumed cut overlaps the material already burned instead of starting cold. Both counts are settings (cloud_pause_backtrack_ticks, cloud_resume_lead_ticks). Motions and hunts do not pause.
• A lid or interlock open, or a cancel from the app, ends the job. Motion stops, whatever remains in the ring is dropped so nothing can play later, and the head parks back at the job's starting point — ignoring the lid, as the factory does. The job is reported as canceled.
• The service dead-reckons position, so the park after every print, finished or aborted, matters: cutting it short would offset everything until the next camera home. That is why the park ignores the lid and the cancel flag.

6.3 Homing and hunts

Cloud homing is camera-based: the service takes a lid image, moves the head, takes another, and computes where it is. The lens hunt references Z against the hall sensor. Hunts are not lid-gated. Connecting zeroes the machine's counters at the head's current position, so GRBL-mode coordinates do not survive a switch to cloud mode and back — re-home after switching.

---

7. The two modes side by side

	GRBL mode	Cloud mode
Who plans motion	grblHAL on the machine	the Glowforge service
Input	G-code over TCP:23	a downloaded pulse file
Ring use	live-streamed, small window	whole job preloaded
Machine tick	28160 Hz default	10 kHz (from the job header)
Job length limit	none	~56 minutes (ring size)
Needs internet	no	yes
Laser arming	button press per job	button press per job
Button mid-job	feed hold / cycle start	pause with backtrack / resume with lead
Lid or interlock open	cancel + return to job start	cancel + park at job start
Homing	$H (camera or, later, switches)	automatic, camera-based
Fan control	M8/M9 plus the armed window	per-job duties from the job header
Underrun possible	yes (handled as a fault)	no (nothing is streamed)

Only one mode runs at a time. Switch from the panel's Status tab; the switch is allowed only when the machine is idle.

---

8. Settings that affect motion

Machine settings live in the web panel and are stored on the machine. They can only be changed while the machine is idle.

Setting	Default	Effect
controller_mode	grbl	Which controller runs: grbl or cloud.
homing_mode	gfcloud	What $H does: gfcloud, switches, none.
gfcloud_home_x/y/z	0 / 0 / Z max	Coordinates assigned after a successful camera home.
gfcloud_home_timeout_s	300	How long a homing session may take before it alarms.
lid_policy	cancel	cancel = factory behavior; hold = stock Grbl door parking.
laser_button_timeout_s	300	How long the machine waits at the button prompt.
laser_disarm_s	60	Spindle-off grace before the armed window closes.
laser_floor_density	10	The S-range floor, percent of full: the lowest pulse density that still marks. Loaded into $35 at every spindle precompute; $35 is derived, never typed.
laser_pulse_ticks	20	Density base period in machine ticks (35.5 us each).
laser_pulse_min_ticks	3	Shortest density pulse in ticks; below it a period is skipped and its debt carried.
rail_settle_s	2.5	Motor-rail off period when a controller takes the device standalone.
cloud_pause_backtrack_ticks	2000	Cloud pause: laser-off backtrack after the stop.
cloud_resume_lead_ticks	1950	Cloud resume: laser-off lead before firing again.

Grbl $ settings (steps/mm, rates, accelerations, laser mode) are set through your sender in the usual way; the defaults above are baked in from the factory machine's own measured values. If you change a baked default and it does not appear to take, remember that stored settings win — $RST=$ restores the defaults.

---

See also

• LightBurn setup & operation — practical sender setup.
• Laser safety — the hardware chain and what each interlock does.
• Cooling and airflow — the fire gates referenced above.
• kernel-module-glowforge/UAPI.md — the pulse-stream contract in full detail.
• forgectrl/docs/SERVICES.md — device ownership, mode supervision, switch map.