Oleksandr ShyshatskyiandClaude Opus 5
65a7528e09
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
3.5 KiB
Upgrading, and your files
A newer release installs exactly like the first flash: stick in, power on. Nothing you have set is asked for again. This page is the line between the files that are yours and the files the mod overwrites without asking, because that line is what makes an update safe.
Your files and the mod's files
| File | Whose |
|---|---|
/usr/data/config/printer.cfg |
Yours — never overwritten. Overrides go here, after the includes: restate only what you change, the last value wins. |
moonraker-custom.conf |
Yours — created once, never rewritten, included last so your settings win. Do not delete it. |
ff-*.cfg, printer.base.cfg, moonraker.conf |
The mod's — overwritten on every update; do not edit. |
anvil/helixscreen/config/settings.json |
Yours — everything you set on the screen. Written by HelixScreen itself; carried across updates along with helixscreen.env and its spool map. |
Upgrading
A newer release installs exactly like the first flash: stick in, power on.
Your printer.cfg with its saved calibration, moonraker-custom.conf, your
root password and everything you set on the screen survive; the ff-*.cfg
family is replaced. If a release changes helixscreen.env, yours is kept and
the new one is left beside it as helixscreen.env.mod-new.
The config files in detail
The .cfg includes are wired up for you: printer.base.cfg ends with
the seven [include ff-*.cfg] lines, so a flash brings the mod up by itself.
Your printer.cfg is not touched. The factory dock and nozzle numbers are
pulled in for you too: on the first boot after the flash, [ff_legacy] imports
firmwareExe's per-unit JSON and persists it with its own SAVE_CONFIG, so
Klipper restarts once, right after coming up — before the screen is on its
feet. TOOL_OFFSET_STATUS afterwards should show a nozzle triple for every
tool and no NOT CALIBRATED.
The included files are the mod's, and every update overwrites them without
asking — ff-*.cfg and printer.base.cfg alike. Do not edit them. Put changes
at the end of printer.cfg, restating only the option or macro you are
changing: Klipper merges same-named sections and the last value wins, so
everything you leave out keeps the shipped value and your overrides survive
every flash. Each of those files opens with a header saying as much.
moonraker.conf is mod-owned too — it is overwritten on every update, which
is how the [webcam] block and the API lockdown reach the printer. Its seam is
moonraker-custom.conf beside it: created once, never written again, and
included at the end of moonraker.conf, so anything you set there wins.
Do not delete it — Moonraker treats an include that matches no file as fatal
and will refuse to start. An empty one is fine.
If you edit moonraker.conf itself anyway, the installer notices and keeps
your copy, landing the new version beside it as .mod-new.
A FlashForge OTA update is a different thing
overwrite /usr/prog/klipper/, deleting the extras. Keep this repo and
re-run step 1 after every firmware update. The #*# block in
printer.cfg is on the data partition and survives.
Going back to stock
Flashing the stock FlashForge package for your model is the uninstall — it installs the same way, and it restores every file the mod touches. The one thing it cannot bring back is FlashForge's Moonraker, which the stock package does not carry: the mod's build stays, it works, and Mainsail is happy with it. The details, and the ladder below it, are in Support.