The pages written on top of the old README inherited its premise: that after
flashing you face a gauntlet -- go/no-go checks, a safety net, a mandatory
calibration -- before the machine can be trusted with a model. That is not
what happens. The factory numbers import themselves on the first boot, a bed
mesh loads at the start of every print, and the mod is built to run the files
the stock firmware ran. A printer that printed before the flash prints after
it. "Your first print" now says so in its first line, and everything under it
is optional, ordered by what you would actually reach for: check the offsets
are applied, and calibrate only if that disagrees with the machine.
Three audiences now, because owner and contributor was not the real split.
"For experienced users" sits between them: How a print runs, and How
calibration works. Someone who knows Klipper and wants to change what happens
around their file has a place to go that is neither a walkthrough nor the
build system.
What was cut is most of what changed. Pages that were cryptic to the reader
they were aimed at -- Printing, Upgrading -- are out of the nav and kept on
disk to be rewritten rather than deleted. Within the pages that stayed:
Expected output, Probe sampling, What is being measured, the symptom table,
the dark-screen diagnosis, TOOL_Z_ADJUST, PLATE_CHECK, the ff-*.cfg
inventory, [ff_legacy] and SAVE_CONFIG in a paragraph about factory
calibration. Filenames and internals earn their place on an owner page only
when the reader has to type them or look at them; the rest moved to the
experienced pages or to Internals, where the audience wants them.
Calibration became a section rather than a page, because tool offsets are not
the only calibration: bed mesh has its own page now, and its own gotcha
written down -- BED_MESH_CALIBRATE writes `default`, a print loads
`MESH_DATA`, so a mesh probed by hand is a mesh no print will use. Input
shaping is described but has no procedure page yet.
Several claims came out because they were not true. "Is this for you" listed
calibration and input shaping as things the mod gives you; both are the
touchscreen's own sequences, recovered and reimplemented, and the notes say
so plainly. What the mod actually gives you is that anything speaking
Moonraker can drive the machine -- on stock, FlashForge's Klipper does not
toolchange at all, it raises a flag and waits for an application that is not
watching a Mainsail print, and the print hangs at the first T2. The page now
opens by telling most owners not to flash it.
Contributors are still deferred. Their pages are regrouped, not rewritten.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S3XZh4SqPdXAowVndz6tMr
__init__ called refresh_offsets() nineteen lines before it built the
transform that refresh_offsets() reads to decide whether gcode_move's
position cache needs invalidating. The read is guarded by `changed`, and
nothing has changed only when every derived offset is zero -- so the
section parsed on a factory-fresh machine and raised AttributeError on any
printer that had ever been calibrated. Which is also why the suite missed
it: the replica boots uncalibrated, and the transform tests build the
object with __new__. Both are now pinned.
While in there: the three offset series were one list bound to three names.
The job term gets its own slot. It shared homing_origin with the operator's
babystep, and SET_GCODE_OFFSET Z=0 -- what the end/cancel block issued --
cannot tell them apart, so ending a print wiped the babystep too. It is a
term of the tool frame now, set absolutely by TOOLCHANGE_SET_PRINT_OFFSET
and dropped by its new CLEAR=1, which moves nothing and so no longer needs
END_PRINT's homed/unhomed fork. Reported as toolchanger.print_z_offset,
because a macro converting a G-code Z to a machine Z now has three layers
to subtract, not two.
And a way back from an aborted toolchange, which leaves the frame off with
a tool still on the carriage -- a bare G1 Z0 then aims 3.2 mm into the
plate. INITIALIZE_TOOLCHANGER re-applies the frame, as upstream's does,
touching no dock; TOOLCHANGE_STATUS says which frame is on; and applying an
uncalibrated tool's frame says so at the moment it goes on rather than only
at startup. _log_transform_chain now checks that bed_mesh and
skew_correction really did end up below us instead of only printing the
chain. TOOL_Z_ADJUST no longer claims "in force now": it is
SET_GCODE_OFFSET Z_ADJUST without MOVE=1, so it lands on the next Z move.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Taking effect and persisting were one act, and they should not be.
SAVE_CONFIG is a restart, so a per-tool trim that needed one could never
be made during a print -- which is precisely when you know what the
number should be. Staging on every tweak also left the config dirty for
anyone dialling one in by feel.
Now the value reaches the tool's frame immediately and stages nothing;
SAVE=1 also writes it for the next SAVE_CONFIG. Nothing moves, as with
SET_GCODE_OFFSET Z_ADJUST without MOVE=1: the frame shifts and the next
move lands in it, which is what babystepping into a live print has to do.
This is only possible because the per-tool offsets are a move transform
now (previous commit). While they lived in gcode_move's single offset,
"live" meant rewriting the number the operator's babystep also sat in.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
STATION_CALIBRATE is TOOL_LOCATE_SENSOR and TOOL_OFFSET_CALIBRATE is
TOOL_CALIBRATE_TOOL_OFFSET, with upstream's call shape as well as its
names: no TOOL= (the mounted tool is the one measured, so SELECT_TOOL
first, as upstream's macro does) and no PLATE_REMOVED=.
The renames are not just conformance. Upstream says "run
TOOL_LOCATE_SENSOR with tool 0" because tool 0's nozzle is the only
thing on their machine that can reach the pin -- their baseline is a
tool, so tool 0's own error rides into every other tool. Here the
carriage's probe element sits above the tool mount and reaches the
station directly with nothing installed, so the command means what it
says: locate the sensor, with no tool. That baseline cannot be spoiled
by a badly seated T0, which is what lets nozzle_x/y/z stay absolute and
per-tool independent.
PLATE_REMOVED=1 goes because the plate check that runs anyway is the
better guard: it parks the carriage and MEASURES whether the plate is
there, where the flag only asked the operator to promise. Dropping it
also removes the last non-upstream required parameter.
Losing TOOL= means losing TOOL=ALL, so CALIBRATE_TOOL_OFFSETS loops over
printer.toolchanger.tool_numbers -- the same shape as upstream's macro.
GRAB=/RELEASE= go with it: they cannot mean anything once the tool has
to be mounted already. The plate check still needs an empty carriage, so
the command parks the selected tool and picks it straight back up.
Probe sampling gets klipper-toolchanger's parameters -- SAMPLES,
SAMPLES_TOLERANCE, SAMPLES_TOLERANCE_RETRIES, SAMPLES_RESULT,
SAMPLE_RETRACT_DIST, PROBE_SPEED -- on both commands and in
[ff_tool_offset]. The fork's e_stop ALREADY samples (sub_cycle_cnt
touches, spread rejected above error_v, retried main_cycle_cnt times,
averaged); what was missing was reaching those numbers from a command
and a median. So _estop runs that loop itself over the fork's
single-touch _probe, every default is read off the [e_stop <axis>]
object, and an unparameterised command probes exactly as it did before.
Spread is judged after each touch, as the fork does, so a round already
known bad is not finished. Two things the fork does not bound are
bounded here: the 9999 move-failure sentinel it spins on forever, and an
e_stop with no _probe, which falls back to run_probe as one sample
rather than cubing the touch count.
Also fixes _plate_check reaching for z_trigger where it had bound
station_z -- a NameError left by the rename sweep in 4704ca0, on the one
path that runs before a nozzle is allowed to descend, and now the only
guard that the plate is off.
docs/calibration.md is the operator's side of all of it: the order, what
each command prints, and every refusal it can raise.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
