OS & Firmware Setup¶

This tutorial is taken from the "FreeQIDI" guide, originally made by C0co before FreeDi, for the X3 Series QIDI printers.

Following these steps, you'll go through the manual installation of the system and flashing steps.

DISCLAIMER¶

Caution!

Before you start, please understand that you will wipe the entire disk and install a different OS.

You will also update all sub-systems (Toolhead THR board and Mainboard STM32F402 MCU) to the latest klipper. So you will have an entirely free and custom 3D printer.

Please note, that this will all be done at your own risks, and please do not contact the QIDI support if you have any issues. By making these changes, you will lose your warranty in this regard.

There is however a "recovery“ image, that can restore your QIDI printer to its factory state. You have to downgrade the THR toolhead board, the mainboard MCU, and the screen, and you are basically back to factory settings and you should have your warranty back!

Getting started¶

Please follow the steps below carefully! Come to our Discord channel if you run into an issue.

Installing the OS (Armbian)¶

Thanks to redrathnure ¹ there is a great Armbian based OS that we can use as a foundation. So download the latest Armbian MKSPI release to get started.

OS Installation:

Turn your printer off, wait ~30s.
Open the back cover and remove the EMMC flash.
Use BalenaEtcher or Win32 disk imager and flash the armbian image to your EMMC using your adapter.
Insert the EMMC back to your printer.
Turn your printer ON and connect the printer via ethernet cable to your router.

Connect to your printer via SSH using its IP address and log in with these credentials:

user: root
password: 1234

You will be asked to create a new user, so create it using these:

user: mks
password: makerbase

Now start a new SSH session and login with the new credentials.

Update the system with:

sudo apt update
sudo apt upgrade

Installing Klipper¶

Now we need to install Klipper and all the dependencies with KIAUH ².

Install KIAUH:

sudo apt-get update && sudo apt-get install git -y
cd ~ && git clone https://github.com/dw-0/kiauh.git
./kiauh/kiauh.sh

Use KIAUH to install these softwares in this order:

1: Klipper
2: Moonraker
3: Mainsail

If you do have a webcam, also install Crowsnest.

When asked for the python version, make sure to select python v3.x.!

Now you should be able to access your printer via a web browser, and see the Mainsail web interface.

It will show you an error like this:

This is because the boards are not updated with the latest klipper firmware yet.

Flashing the mainboard MCU¶

This step is the same for all supported printer models

Building Klipper.bin:

To build the klipper.bin file, run:

cd ~/klipper
make menuconfig

Set everything according to this screenshot:

Quit with Q and save with Y

Now we clean the workspace first and then compile with all 4 cores:

make clean
make -j4

This will generate the klipper.bin file in the /home/mks/klipper/out/ folder.

Flashing Klipper:

Use your favorite program to copy this file from the printer into your computer (e.g. WinSCP or Mobaxterm).

Then:

Format a micro SD card as FAT32
Copy the klipper.bin file to this SD-card and rename it:
- For 3 series printers, rename it as: X_4.bin
- For Q1 & Plus 4, rename it as: qd_mcu.bin
Eject the microSD card.
Shut down your printer and wait at least 30sec.
Put the microSD card into the SD card slot of the printers mainboard.
Turn the printer on.

The mainboard MCU (STM32F402) will now be flashed, which takes about 10 seconds, but make sure to let your printer powered ON for 1 minute, just to be sure.

Flashing the Toolhead MCU¶

The toolheads use a derivate of MKS THR boards. These boards are powered by RP2040 microcontrollers on X3 series & Q1 pro, and by STM32 microcontrollers on Plus 4.

To be able to flash your toolhead, you will need to turn it into what is called "DFU mode" first.

During this tutorial we will do this once. In the future, this won’t be necessary anymore. Because the bootloader named "katapult“ ³ (formerly known as CanBoot) brings the ability to put microcontrollers in DFU mode without the need of manual intervention.

Installing katapult¶

Via SSH, connect to your printer with your new credentials then:

git clone https://github.com/Arksine/katapult
cd ~/katapult
make menuconfig

Katapult needs python3-serial dependency:

sudo apt install python3 python3-serial

configuring Katapult for X3 series:

First, make sure to build a katapult deployment application with the right settings:

Finish by hitting Q and save with Y:

configuring Katapult for Q1 pro:

First, make sure to build a katapult deployment application with the right settings:

Finish by hitting Q then save with Y:

configuring Katapult for Plus 4:

First, make sure to build a katapult deployment application with the right settings:

Finish by hitting Q and save with Y:

Building the katapult bootloader:

Now build the firmware by first cleaning the workspace and then compile with all 4 cores:

make clean
make -j4

You should see something like this:

X3 series & Q1 pro: a katapult.u2f file is created inside the /Katapult/out folder.
Plus 4: a katapult.bin file is created inside the /Katapult/out folder.

Putting the Toolhead in DFU mode:

Put the toolhead board in dfu mode by doing this:

Remove the back cover of your toolhead.
Press and hold the "boot“ button.
Press and release the "reset“ button.
Release the "boot“ button.

Flashing katapult on X3 series:

Find your toolhead ID by running:

ls /dev/serial/by-id/*

You should see this:

To flash the katapult bootloader, run:

sudo mount /dev/sda1 /mnt
systemctl daemon-reload

You will be asked to authenticate by entering the password:

Now flash katapult to the RP2040 and unmount it:

sudo cp out/katapult.uf2 /mnt
sudo umount /mnt

Flashing katapult on Plus 4:

To enter bootloader mode, follow these steps:

Press and hold the „boot“ button on your toolhead board.
Press and release the „reset“ button.
Release the „boot“ button.

Then to flash the katapult bootloader, run:

sudo service klipper stop
sudo apt install stlink-tools
st-flash write ~/katapult/out/katapult.bin 0x8000000

or

sudo service klipper stop
sudo apt install stlink-tools    
st-flash write ~/FreeDi/mainboard_and_toolhead_firmwares/v0.13.0-154/Toolhead_Plus4_katapult.bin 0x8000000

Flashing katapult on Q1 pro:

To enter bootloader mode, follow these steps:

Press and hold the „boot“ button on your toolhead board.
Press and release the „reset“ button.
Release the „boot“ button.

Then run these commands:

sudo service klipper stop
sudo apt install stlink-tools
sudo cp ~/katapult/out/katapult.uf2 /dev/sda1

or

sudo service klipper stop
sudo apt install stlink-tools
sudo cp ~/FreeDi/mainboard_and_toolhead_firmwares/v0.12.0-458/Toolhead_Q1_katapult.uf2 /dev/sda1

Bonus!

Benefits of Katapult:
Pressing the BOOT + RESET buttons IS NOT NEEDED ANYMORE!
Q1 pro: NO USB breakout NEEDED ANYMORE!
Plus 4: NO ST-Link v2! NEEDED ANYMORE!

Yes — those "extra" wiring & manual intervention steps are gone, making your experience easier!

Flashing klipper in your toolhead¶

Now it's time to build then flash the latest klipper inside your toolhead.

Flashing Klipper on 3 Series:

Compile the toolhead board firmware with:

cd ~/klipper
make menuconfig

Set it according to the screenshot below:

Save and exit with Q then Y

Then run:

make clean
make -j4

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

Find your toolhead ID with:

ls /dev/serial/by-id/*

Flash your toolhead with Katapult, replacing the ID with yours:

sudo service klipper stop
python3 ~/katapult/scripts/flashtool.py -f ~/klipper/out/klipper.bin -d /dev/serial/by-id/usb-katapult_rp2040_C5DA4D951E145858-if00

If the update is successful, you should see this:
Restart Klipper:

sudo systemctl start klipper

Flashing Klipper on Q1 pro :

Compile the toolhead board firmware with:

cd ~/klipper
make menuconfig

Set it according to the screenshot below:

Save and exit with Q then Y

Then run:

make clean
make -j4

Flash your toolhead with Katapult:

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

If the update is successful, you should see this:
Restart Klipper:

sudo systemctl start klipper

Flashing Klipper on Plus 4:

Compile the toolhead board firmware with:

cd ~/klipper
make menuconfig

Set it according to the screenshot below:

Save and exit with Q then Y

Then run:

make clean
make -j4

Flash your toolhead with Katapult:

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

If the update is successful, you should see this:
Restart Klipper:

sudo systemctl start klipper

Now if you go to the machine settings of mainsail, you will see the current klipper version of the sub systems: