G1OS installation

Full procedure to flash G1OS (the Mainsail-based operating system) onto the Raspberry Pi 4 SD card inside the G1 printer. Required when reinstalling the OS or replacing the SD card.

Note

Official guide: Install G1OS G1OS image download: the G1OS GitHub repository → Releases. (The image is no longer hosted on gingeradditive.com.)

---

What flashing the card changes — and what it does not

Everything the printer knows about itself lives on the SD card, and the flash replaces all of it. Nothing else on the machine is touched.

	Erased by the flash
G1OS, Klipper, Moonraker, Mainsail	Yes — replaced by the versions in the image
Your serial number and machine configuration	Yes — the card comes back blank
Bed mesh, Z offset, Rotation Volume, SAVE_CONFIG values	Yes — you will recalibrate
G-code files you uploaded	Yes
Firmware on the Octopus, extruder_board and feeder board	No — see below

The card is not the firmware

The three control boards each hold their own firmware, in their own flash, and an SD card has no way to reach it. A newly flashed card talks to boards still running exactly what they ran yesterday.

That is almost always what you want, and reflashing them is not part of setting up a machine. It is a separate, rarer job: Flashing the control boards.

---

When to do it

• First-time setup of a new machine
• OS is corrupted and the printer does not boot
• Replacing the SD card

Prerequisites

• Tools: hex screwdriver (to open electronics box), SD card reader/adapter
• Files: latest G1OS image from the G1OS GitHub repository (→ Releases) — the arm64 .img.xz for Raspberry Pi 4
• Software: Raspberry Pi Imager installed on your computer
• Machine state: powered off

---

Steps

1 — Remove the SD card from the printer

1. Turn off the printer
2. Open the electronics box: unscrew the two hex screws on the left side of the display
3. Locate the Raspberry Pi 4 behind the display
4. The SD card slot is behind the flat ribbon cable — gently remove the SD card

2 — Download the G1OS image

1. Go to the G1OS GitHub repository → Releases
2. Download the latest G1OS image — the arm64 .img.xz for Raspberry Pi 4 (e.g. ...-G1OS-raspberry_pi-arm64-bookworm-X.X.X.img.xz)

Do not unpack it. Raspberry Pi Imager reads .img.xz as it is, and unpacking only costs you disk space.

Each release also carries a .sha256 file next to the image. If the write fails or the machine will not boot afterwards, checking that first tells you whether you are chasing a bad download or a bad card.

3 — Flash the SD card with Raspberry Pi Imager

1. Insert the SD card into your computer
2. Open Raspberry Pi Imager
3. Choose Device → Select Raspberry Pi 4
4. Choose OS → Select Use custom → pick the .img file you extracted
5. Choose Storage → select your SD card
6. Click Next, then EDIT SETTINGS and configure:
   • Hostname: g1os — that gives you g1os.local
   • Username: pi
   • Password: raspberry
   • Go to Services tab → enable SSH → Use password authentication
7. Click Save, then confirm YES to apply OS customisation settings
8. Confirm to start flashing — wait for “Write Successful”

4 — Reinstall the SD card

1. Safely remove the SD card from your computer
2. Insert it back into the Raspberry Pi in the G1 printer
3. Reassemble and close the electronics box
4. Power on the printer

5 — Connect and configure G1OS

1. Connect the printer to your Wi-Fi from the Klipper menu on the display
2. From your PC, open a browser and go to g1os.local

   If the printer doesn’t connect via g1os.local, try restarting the router

---

Final verification

The G1OS Mainsail dashboard appears at http://g1os.local in your browser. The printer shows as connected and temperatures are visible.

What comes next

A flashed card is a blank printer. It boots, but it does not yet know which machine it is, and none of your calibration survived. Work straight down this list — each step needs the one above it.

1. Initialize the printer — give it your serial number, then press UPDATE G1 to download your machine’s own configuration. Until this is done the printer is running a generic config and printer.cfg does not describe your machine

   Read that page as first setup. It also serves older machines being migrated onto the Configurator, but there is nothing to migrate on a card you just wrote — no old state, nothing to back up

2. Update the software components — one row at a time in the Update Manager, and not Moonraker. The image ships with whatever was current when it was built

3. Re-check the boards are talking. STATUS in the console must show both mcu and extruder_board connected. The new printer.cfg picks up their USB addresses by itself; if one is missing, go to Klipper MCU communication lost — reflashing is not the first thing to try

4. Bed levelling — run BED_LEVEL hot and save. The old mesh is gone

5. Z offset and first layer — measure the first layer with a caliper and save

6. Rotation Volume calibration — per material

Steps 4 to 6 are the same calibrations as a brand-new machine, for the same reason: they were stored on the card you overwrote. The rest of the commissioning checks are in the First boot checklist.

Notes

• The SD card slot is tight and partially hidden by the ribbon cable — be gentle to avoid bending the connector

Related notes

• Raspberry Pi and SD card
• Klipper firmware update
• Initialize the printer
• First boot checklist
• Mainsail dashboard basics