Single block mode (also called "block mode" or "single step mode") runs a job one
GCode line at a time. Before each line of a running job, FluidNC finishes all
buffered motion, reports the line it is about to run, and then pauses in Hold
state. The line does not execute until you issue a cycle start. After that line
finishes, FluidNC pauses again before the next line.
It behaves as though an M0 (program pause) were inserted ahead of every line of
the program, except that nothing in the file is modified and no look-ahead
blending occurs across the pause.
This is useful for:
Single block mode only affects lines that come from a running job: a file
started with $SD/Run or
$LocalFS/Run, or a macro. It does
not affect GCode that a sender streams line by line, nor commands you type at
a console - to FluidNC those are the same thing, plain lines arriving on a channel
with no job on the job stack, and there is nothing to step through. To prove out a
program one line at a time this way, put it in a file and run it with $SD/Run or
$LocalFS/Run.
Single-stepping a streamed job is up to the sender itself: it would have to send
one line, wait for the ok, wait for you to say "continue", then send the next.
That is a sender feature; FluidNC cannot add it to a sender that lacks it.
There are three independent ways to control single block mode. Any of them turns
the same internal switch on or off; you can mix them freely.
$GB command$GB (long form $GCode/BlockMode) toggles single block mode from a console or
sender.
| Command | Effect |
|---|---|
$GB |
Toggle: on if it was off, off if it was on |
$GB=On |
Enable |
$GB=Off |
Disable |
$GB=On
[MSG:INFO: Single Block Mode Enabled]
ok
$GB works in any state and from any channel, including while a job is running.
Enabling it partway through a job does not stop the machine right away - see
Enabling it during a running job. To let a
running job finish without stops, send $GB=Off and then one more cycle start;
the change takes effect at the next line boundary.
single_block_pinYou can assign a physical switch or expander input to
control: single_block_pin.
When the pin becomes active it toggles single block mode. This pin is optional -
the feature works without it - and, unlike the other control pins, it does not
raise an "active at startup" alarm.
control:
single_block_pin: gpio.16:low:pu
The FluidNC build of WebUI version 2 has a turtle icon that toggles single
block mode. It is only in WebUI 2's tablet mode (the tablet-optimized layout
with the GCode visualizer), not the standard WebUI 2 screen. Click the turtle to
turn the mode on. While a job is paused before a line, click the normal
Resume (play) button to run that line and advance to the next one. Click the
turtle again to turn the mode off; the next Resume then lets the job finish
without further stops.
Under the hood the turtle drives the same channel-independent pin event that
single_block_pin uses, registered on every channel whether or not a
single_block_pin is configured. Any other UI - a custom WebUI, a pendant - can
toggle the mode the same way without a config entry.
Send $GB=On (or click the turtle icon in WebUI 2 tablet mode, or flip your
single_block_pin switch).
Start the job with $SD/Run=myfile.nc (or $LocalFS/Run=..., or run a
macro). You can also enable the mode after a job is already running, but see
Enabling it during a running job below -
it does not take effect immediately.
FluidNC drains the planner, prints a preview line, and enters Hold:
[MSG:INFO: Step /sd/myfile.nc:12 G1 X10.000 Y10.000 F...]
The preview shows the job channel name, the line number within the file, and
the first 20 characters of the line (... when the line is longer).
Issue a cycle start to run that one line: the ~ real time character, the
Resume (play) button in your sender or the WebUI, or a switch on
cycle_start_pin.
The line runs, motion completes, and FluidNC pauses again before the next
line. Repeat from step 4.
To stop stepping and let the job run to the end, turn the mode off ($GB=Off, the
turtle icon, or the pin) and issue one more cycle start / press Resume.
Turning single block mode on while a job is already running does not stop the
machine at the next line. It only gates GCode lines that FluidNC has not read from
the file yet, and by the time a job is up and cutting it has usually read well
ahead of the tool:
planner_blocks moves of look-ahead (16 by default),G2/G3 arc counts as oneSo after you enable it mid-job and press cycle start, expect the machine to run
out the buffered moves first - often 10-15 of them - and only then pause before
the first not-yet-read line. To single-step reliably from the start, enable the
mode before you run the job.
While single block mode is enabled, the ? status report includes Q in the
Pn: (pin) field, regardless of how it was enabled:
<Hold:0|MPos:10.000,10.000,-1.000|FS:0,0|Pn:Q>
Pn:Q disappears when the mode is turned off.
$C) - When GCode check modeHold-state behavior applies (feed and spindle overrides work; jogging doesM0 breaks in the program instead.