This guide explains how to update the firmware on your printer’s microcontrollers after a Klipper update: the mainboard MCU and the toolhead MCU.
After some Klipper updates, the communication protocol between host and MCU changes, and older MCU firmware can become incompatible, which triggers errors in Mainsail until you reflash the affected MCU(s).

Updating Klipper itself follows the usual, well-documented Klipper workflow and is not something special or “FreeDi-specific”.
However, since this project is also aimed at beginners (and because it’s simply nice to have the right settings for your exact printer model at hand), I decided to provide this page as a practical step-by-step reference for everyone.
My hope is that it helps you quickly confirm your model-specific menuconfig options and get back to printing with less guesswork.

Typical symptoms in Mainsail (Console / Klipper errors) are messages like “MCU Protocol error” and hints that this is frequently caused by running older firmware on the MCU(s), recommending recompiling and reflashing.
This can happen right after Klipper updates, even if your printer was perfectly fine before.

For all supported models, the mainboard firmware update workflow is the same:

1. Compile Klipper for the mainboard (make menuconfig, then build).
2. Copy the resulting klipper.bin to your PC.
3. Rename it to the printer-specific filename and flash it using the “easy” method you already know for your printer.

Run:

cd ~/klipper
make menuconfig

Now set the options to match the reference screenshots (double-check the Klipper version string shown in your system).

Klipper Version	Screenshot
v0.12.0-289
v0.13.0-69

Save and exit with q.

Run:

make clean
make -j4

This will generate a klipper.bin in: /home/mks/klipper/out/

You now have the compiled firmware file here: ~/klipper/out/klipper.bin
In step 3 you will do two things in order: (3.1) rename the file to the exact filename your mainboard expects, and (3.2) flash it using either microSD or SPI.

Your mainboard will only recognize the update if the file has the correct name.
Create a renamed copy in the same folder:

• X_4.bin for X-Smart3, X-Plus3, X-Max3
  Example (X-Smart3 / X-Plus3 / X-Max3):

cp ~/klipper/out/klipper.bin ~/klipper/out/X_4.bin

• qd_mcu.bin for Q1 Pro, Plus4
  Example (Q1 Pro / Plus4):

cp ~/klipper/out/klipper.bin ~/klipper/out/qd_mcu.bin

You have two valid ways to flash the mainboard. Pick A or B.

1. Copy the renamed file (X_4.bin or qd_mcu.bin) to a microSD card.
2. Power off the printer.
3. Insert the microSD card into the mainboard microSD slot.
4. Power on the printer and wait about ~10 seconds.
5. Power off again.

Remove the SD card afterwards and boot normally.

If your microSD card is already/still inserted in the mainboard, you can flash over SPI using Klipper’s built-in script.
This is based on Klipper’s SD-card update workflow, using flash-sdcard.sh.

Thanks to the awesome integration work by Ben:

• https://github.com/Klipper3d/klipper/pull/6979
  …and the follow-up work (which I integrated for older printers):
  
• https://github.com/Klipper3d/klipper/pull/7006

Important: Use the script from your Klipper folder: ~/klipper/scripts/flash-sdcard.sh (not a random copy).

Run (uses the renamed file from step 3.1):

~/klipper/scripts/flash-sdcard.sh -f ~/klipper/out/X_4.bin -b 500000 /dev/ttyS0 qidi-x-max3

Run (uses the renamed file from step 3.1):

~/klipper/scripts/flash-sdcard.sh -f ~/klipper/out/qd_mcu.bin /dev/ttyS0 qidi-q1-pro

This part depends on your printer model. Pick your device below (each section is linkable via its heading).

Toolhead MCU update (X-Series / RP2040 / UF2)

Compile the toolhead firmware

Run:

cd ~/klipper
make menuconfig

Set it according to the screenshots below (match your Klipper version):

Klipper Version	Screenshot
v0.12.0-289
v0.13.0-69

Save and exit with q.

Run:

make clean
make -j4

This generates a klipper.uf2 file in ~/klipper/out/.

Flashing the toolhead (RP2 Boot mode)

Bring the toolhead into “RP2 Boot” mode (see the “easy” section / your printer docs for how to enter it).
Then check which partition appeared:

lsblk

In my example it shows up as sda1. Adjust the command to whatever you see and run:

sudo cp ~/klipper/out/klipper.uf2 /dev/sda1

After the copy finishes, reboot/power-cycle the printer so the toolhead restarts into Klipper firmware.

cd ~/klipper
make menuconfig

make clean
make -j4

sudo systemctl stop klipper

python3 ~/katapult/scripts/flashtool.py -d /dev/ttyS2 -f ~/klipper/out/klipper.bin

python3 ~/katapult/scripts/flashtool.py -d /dev/ttyS2 -f ~/FreeDi/mainboard_and_toolhead_firmwares/v0.12.0-289/Toolhead_Q1_klipper.bin

sudo systemctl start klipper

cd ~/klipper
make menuconfig

make clean
make -j4

sudo service klipper stop
python3 ~/katapult/scripts/flashtool.py -b 500000 -d /dev/ttyS2 -f ~/klipper/out/klipper.bin

sudo service klipper stop
python3 ~/katapult/scripts/flashtool.py -b 500000 -d /dev/ttyS2 -f ~/FreeDi/mainboard_and_toolhead_firmwares/v0.12.0-289/Toolhead_Plus4_klipper.bin

sudo service klipper start

• If the error persists after flashing: reboot the printer once, then re-check Mainsail for which MCU(s) it still lists as incompatible.
• If you’re stuck in a loop after a major Klipper update: it’s usually because one MCU was updated but another one is still on an older firmware (mainboard + toolhead need to match the host expectations).
• If you want a sanity-check: compare your make menuconfig screen with the reference screenshots for your version and model, then rebuild and flash again.

If something looks weird: grab a screenshot of the exact Mainsail error and ping me/community - we'll get you back to printing ☺️