firmware/docs/upgrading.md

# 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/anvil-data/config/printer.cfg` | **Yours** — preserved across updates. The installer removes FlashForge's obsolete `[output_pin DC24V_CTL]` once; overrides otherwise stay here after the includes. |
| `/usr/data/anvil-data/config/moonraker-custom.conf` | **Yours** — created once, never rewritten, included last so your settings win. Do not delete it. |
| `/usr/data/anvil-data/scripts/*.sh` | **Yours** — custom boot scripts, preserved across updates. |
| `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. |

**Two config directories, and only one of them is live.**
`/usr/data/anvil-data/config` is Reforge's, and it is where everything now
lives: your `printer.cfg`, `moonraker.conf` and `moonraker-custom.conf`, and
the `ff-*.cfg` set. Klipper and Moonraker both read it, and it is what
Mainsail's config editor shows you.

The first install copies your `printer.cfg` and the config files beside it out
of FlashForge's `/usr/data/config`, and nothing writes to that directory
afterwards. That is what makes going back to stock work; see below. If you edit
a config by hand over ssh, edit the copy in `/usr/data/anvil-data/config` — the
file of the same name in `/usr/data/config` is the frozen stock one and changes
nothing.

---

## 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`.

Custom boot scripts under `/usr/data/anvil-data/scripts` survive too. The
payload itself lives under `/usr/data/anvil` and is replaced as a unit, so do
not put user files there. See [Custom boot scripts](custom-scripts.md).

---

## 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.

Editing `moonraker.conf` itself does not survive: the next update overwrites
it, and that is how the `[webcam]` block and the API lockdown reach your
printer. Put the change in `moonraker-custom.conf` instead.

---

## A FlashForge OTA update is a different thing

Everything the mod installs is under `/usr/data/anvil` on the data partition,
the klippy tree and its extras included, so an OTA cannot delete them. What it
does rewrite is `/usr/prog`, and with it the `firmwareExe` the mod boots
from — so re-flash the mod after a firmware update. The `#*#` block in
`printer.cfg` survives either way.

---

## Going back to stock

Flashing the stock FlashForge package for your model is the uninstall — it
installs the same way, and it restores `/usr/prog`, which is everything the
mod replaced there.

It works because the mod never wrote to FlashForge's config directory.
`/usr/data/config` still holds the stock `printer.cfg`, the stock
`printer.base.cfg` and the stock includes, so a stock firmware boots on the
config it expects. The mod's own directory is left behind on the data
partition and stock ignores it.

The cost is the other half of that sentence: the calibration and the config
edits you made **while the mod was installed** live in
`/usr/data/anvil-data/config/printer.cfg`, and the stock firmware does not
read them. Going back to stock returns the machine to the `printer.cfg` it had
before you flashed the mod. Nothing is deleted — flash the mod again and your
tuned copy is still there, exactly as you left it.

The one thing a stock flash 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](support.md).