Skip to main content

Migration: MainsailOS from Raspberry Pi 4B → Raspberry Pi 3B+

04/06/2026 - This was done so that I could use the Raspberry Pi 4B that was being used for Mainsail as the host for Pi-hole instead. Mainsail was migrated to a Raspberry Pi 3B+.

This guide assumes:

  • Source: Raspberry Pi 4B running MainsailOS 1.3.2 (64‑bit Bullseye)
  • Target: Raspberry Pi 3B+ with a brand‑new SD card
  • Goal: Fresh MainsailOS install on Pi 3B+ + restore all configs
  • User: pi
  • Home: /home/pi
  • Config directory: /home/pi/printer_data/config (as shown in your screenshot)

1. Overview

You will:

  1. Back up all relevant configuration directories from the Pi 4B
  2. Flash a fresh MainsailOS image for the Pi 3B+
  3. Restore your configs onto the Pi 3B+
  4. Reinstall KlipperScreen (required due to Pi‑specific GPU stack)
  5. Validate everything

2. Back Up the Raspberry Pi 4B

2.1 SSH into the Pi 4B

ssh pi@<pi4-ip>

2.2 Stop all Klipper‑related services

sudo systemctl stop klipper moonraker crowsnest klipperscreen sonar || true

2.3 Create a backup directory

mkdir -p /home/pi/migration_backup

2.4 Back up printer_data/config (your main config directory)

rsync -avh /home/pi/printer_data/config/ /home/pi/migration_backup/config/

This includes:

  • printer.cfg
  • macros.cfg
  • mainsail.cfg
  • moonraker.conf
  • crowsnest.conf
  • timelapse.cfg
  • sonar.conf
  • KlipperScreen.conf
  • All timestamped printer backups
  • Any folders (e.g., KAMP/)

2.5 Back up Klipper source directory

rsync -avh /home/pi/klipper/ /home/pi/migration_backup/klipper/

2.6 Back up Moonraker directory

rsync -avh /home/pi/moonraker/ /home/pi/migration_backup/moonraker/

2.7 Back up KlipperScreen directory

rsync -avh /home/pi/KlipperScreen/ /home/pi/migration_backup/KlipperScreen/

2.8 Back up crowsnest directory (if present)

rsync -avh /home/pi/crowsnest/ /home/pi/migration_backup/crowsnest/ 2>/dev/null || true

2.9 Fix ownership

sudo chown -R pi:pi /home/pi/migration_backup

3. Transfer Backup to Your Workstation (Optional but Recommended)

From your workstation:

scp -r pi@<pi4-ip>:/home/pi/migration_backup ./pi4_mainsail_backup

4. Flash MainsailOS for Raspberry Pi 3B+

4.1 Download the correct image

Download the latest MainsailOS image that supports Raspberry Pi 3B+.

4.2 Flash the SD card

Use:

  • Raspberry Pi Imager
  • OR Balena Etcher

4.3 (Optional) Preconfigure Wi‑Fi

If needed, use Raspberry Pi Imager’s “OS Customisation” or create wpa_supplicant.conf manually.

5. First Boot of the Raspberry Pi 3B+

5.1 Boot the Pi 3B+

Insert the SD card → power on → wait 1–2 minutes.

5.2 Find its IP address

Use your router or a network scanner.

5.3 SSH into the Pi 3B+

ssh pi@<pi3-ip>

6. Prepare the Raspberry Pi 3B+ for Restore

6.1 Stop services

sudo systemctl stop klipper moonraker crowsnest klipperscreen sonar || true

6.2 Create restore directory

mkdir -p /home/pi/migration_restore

7. Transfer Backup to the Raspberry Pi 3B+

7.1 From Pi 4B directly to Pi 3B+

On the Pi 4B:

rsync -avh /home/pi/migration_backup/ pi@<pi3-ip>:/home/pi/migration_restore/

7.2 OR from workstation to Pi 3B+

scp -r ./pi4_mainsail_backup/* pi@<pi3-ip>:/home/pi/migration_restore/

8. Restore Configurations on the Raspberry Pi 3B+

SSH into the Pi 3B+:

ssh pi@<pi3-ip>

8.1 Restore printer_data/config

rsync -avh /home/pi/migration_restore/config/ /home/pi/printer_data/config/

8.2 Restore Klipper source directory

rsync -avh /home/pi/migration_restore/klipper/ /home/pi/klipper/

8.3 Restore Moonraker directory

rsync -avh /home/pi/migration_restore/moonraker/ /home/pi/moonraker/

8.4 Restore KlipperScreen directory

rsync -avh /home/pi/migration_restore/KlipperScreen/ /home/pi/KlipperScreen/

8.5 Restore crowsnest directory (if present)

rsync -avh /home/pi/migration_restore/crowsnest/ /home/pi/crowsnest/ 2>/dev/null || true

9. Reinstall KlipperScreen (Required)

The Pi 3B+ uses a different GPU stack than the Pi 4B.
Reinstalling ensures correct dependencies.

cd /home/pi/KlipperScreen
./scripts/KlipperScreen-install.sh

10. Validate Hardware‑Specific Settings

10.1 Update MCU serial path

nano /home/pi/printer_data/config/printer.cfg

Check the [mcu] section:

  • Ensure serial: points to the correct /dev/serial/by-id/...
  • Update if needed
  • Save and exit

10.2 Validate webcam settings (crowsnest)

nano /home/pi/printer_data/config/crowsnest.conf
  • 1280x720
  • 10–15 FPS

10.3 Validate KlipperScreen config

nano /home/pi/printer_data/config/KlipperScreen.conf

Check:

  • Rotation
  • Resolution
  • Touchscreen device (if applicable)

11. Start All Services

sudo systemctl start klipper
sudo systemctl start moonraker
sudo systemctl start crowsnest 2>/dev/null || true
sudo systemctl start klipperscreen 2>/dev/null || true
sudo systemctl start sonar 2>/dev/null || true

Check status:

systemctl status klipper moonraker klipperscreen

12. Validate Functionality

12.1 Validate Mainsail

Open:

http://<pi3-ip>

Verify:

  • Printer connects
  • No config errors
  • Webcam works
  • Macros load
  • Timelapse plugin loads
  • Sonar loads

12.2 Validate KlipperScreen

  • UI loads
  • Printer status updates
  • Homing works
  • Temps read correctly

13. Clean Up

13.1 Remove restore directory on Pi 3B+

rm -rf /home/pi/migration_restore

13.2 Remove backup directory on Pi 4B (optional)

rm -rf /home/pi/migration_backup

No comments to display

Back to top