Installation guide for fresh systems - Phil1988/FreeDi GitHub Wiki

Who's this guide for?

This guide is for users who:

  • Have a stock printer with stock software or
  • Dont have an open armbian system with mainline klipper or
  • Want to start with a fresh system to make it from scratch

If you followed my guide for an open armbian system with mainline klipper (FreeQIDI) already,
and you just want to add the screen functionality, please head over to my Installation guide for open systems.

Before we begin, a kind note:

If you arrived here via a direct link from another website/social media,
please be aware that this is just a part of the full guide.
I encourage you to check out the complete guide and learn more about FreeDi :)

You are lucky!

I have prepared a full image ready to go for you.
Its a fresh and clean system to make it as simple for you as I can.

Whats in the box?

To understand what is included in my image, here is the list, what it is based on:

  • Armbian-unofficial_24.2.0-trunk_Mkspi_bookworm_current_6.6.17 Installed is:
  • kiauh v5.1 (v6 is in alpha state)
  • Klipper v0.12.0-289
  • Moonraker v0.9.2-6
  • and everything you need for input shaping, wifi and of course the touch screen functionality.
  • no crowsnest, klippain-shaketune or other things. Simply a pure basis for everyone

This makes it:
image
--> on a 8GB EMMC.

Flashing the operating system (OS) image:

  1. Simply download the image file for your needs.
    You can find the full image at the releases section.
    Search for a *.rar file, download it and unpack it (you will get an *.img file).
  2. Flash the *.img file to your EMMC card or an USB flash drive (eg. by using Win32DiskImager, balenaEtcher or a similar tool).
  3. Insert the EMMC/USB drive to your printer and start it.
  4. Done.

The whole operating system with the required software is now on your printer.

Flashing the display:

Your display will be automatically flashed with my tft firmware.
This normally takes ~4min (which is a lot faster then the official 30-40min updates from Qidi).
When finished, it will get stuck on the boot screen and show an error, that klipper isnt working properly.
Thats totally normal, as we haven't flashed the MCU and the toolhead and inserted their unique ID to the printer.cfg.
We will do this in the next step :)

Note: It can occasionally happen that the flash process gets stuck.
This problem is known and is caused by a serial overload during the flash process.
In this case, please simply switch off the printer and switch it on again.

Creating the "perfect match" with your hardware

Your operating system and screen are now set up.
Next, we need to ensure that the subsystems (mainboard MCU and toolhead) are running the same Klipper version and adjust the configuration to match your specific hardware.

Open the Mainsail UI of your printer with a browser by entering the printer's IP address.
Note, that your printer will likely get a new IP address, as you are now having a new OS and your router will recognize it as a new device.
Don't use the modified port (10088) that you might know from the stock machine.
Then go to the "MACHINE" section:
image

If everything is working correctly, you will find a box on the right side. This will show your current Klipper versions for the MCU, the toolhead (MKS_THR) and also the host:
image

Dont worry if you cant see it yet.
This is normal if your config is not completely correct.
You can fix it by following this guide :)

You may also see a hint, that your printer cant find the toolhead (MKS_THR):
image
Dont worry, that is completely OK!
It simply says it cant find your toolhead by the default ID I set as placeholder.
We will fix this in soon, but before we do that, please...

Adjust the printer configuration to your specific hardware

As you have read, Qidi bought several different hardware revisions of their printers.
Open the printer.cfg and compare it to your backup version.
It might be missing some entries (e.g. it may not include the controllable board fan if your printer support that - mistyped in the Qidi config as borad_fan) or it has different values for the run_current for your steppers.

Please make sure to not overlook the post install and config section where I try to collect and share the different sections.
Take your time here.

In the next steps, we will adjust your printer config to match the unique ID of your toolhead.

Depending on hardware setup and liking, choose one of the following guides:

#1 Your mainboard MCU and the toolhead are on Klipper v0.12.0-289 already?

Yes, its on Klipper v0.12.0-289

To finish your configuration, we need find the unique ID of your toolhead and insert it to your printer.cfg.

  1. SSH to your printer (eg. via putty) and run the command:
    ls /dev/serial/by-id/*
    Note the device ID which will be printed like:
    image

  2. Connect to your printer via your favorite browser and replace the ID in the [mcu MKS_THR] section of the printer.cfg with the one you got before:

image
You are done :)
Happy printing!


#2 Your mainboard MCU and the toolhead are NOT on Klipper v0.12.0-289
- and you want it the easy way?

Yes please, go easy on me!

On FreeDi v1.40 and later

Yes I am using FreeDi v1.40 or later

Flashing the toolhead and MCU automatically using klipper auto flasher (KAF)

If you are using FreeDi v1.40 and higher, you can use the new "klipper auto flasher" tool. To use it you simply have to do the following:

  1. Shut off the printer.

  2. Open the back cover of your toolhead.

  3. Press and hold the boot button. Here is an example image to help you locate the buttons:

    image
    It might look different for your toolhead, as different revisions have been installed in the machines.

  4. Switch the printer on and then release the boot button.
    The toolhead is now starting in boot mode.
    FreeDi will automatically recognize the toolhead and flash the latest klipper to it.
    When finished, FreeDi will flash klipper to MCU on your mainboard too.
    Magic made simple 🧙✨

You only have to enter the serial ID to your config..

Enter the serial ID to your printer.cfg

  1. SSH to your printer (eg. via putty) and run the command
    ls /dev/serial/by-id/* Note the device ID which will be printed like:
    image

  2. Connect to your printer via your favorite browser and replace the ID in the [mcu MKS_THR] section of the printer.cfg with the one you got before:
    image

  3. Dont forget to hit save & restart at the top right corner ;)


On FreeDi lower than v1.40

Yes I am using FreeDi v1.30 or older To make it easy for you, I pre-compiled files for your subsystems.
You can find them in the

mainboard_and_toolhead_firmwares section.
Make sure you get the version matching your Klipper.

You will see a Toolhead_RP2040.uf2 for the toolhead and a X_4.bin for the mainboard MCU:
image
Please click on the file names and download them as "raw file":
image
Use a sftp client (eg. WinSCP) and uploaad the Toolhead_RP2040.uf2 to ~/FreeDi.
Save the X_4.bin somewhere on your computer. You will need it in the next step to flash the mcu.

Flashing the Mainboard MCU:

  1. Format a microSD card as FAT32 (not lager in size then 32GB – maybe larger sized microSD-cards will work if you create a partition not larger then 32GB).
  2. Copy the „X_4.bin“ file to your microSD-card.
  3. Eject the microSD card from your computer.
  4. Shut down your printer and wait at least 30sec.
  5. Put the microSD card into the microSD card slot of the printers mainboard.
  6. Turn the printer on. The mainboard STM32F402 MCU will now be flashed (which takes about 10sec, but make sure to not turn it down before 1min… just in case).
  7. (Optional) Turn off the printer and remove the microSD card if desired.
    You can verify that the firmware was successfully flashed, if the file on the microSD card has been renamed from X_4.bin to X_4.CUR.

Flashing the THR toolhead:

Put your Toolhead into "RP2 Boot" mode.

  1. Remove the back cover of the tool head.
  2. Press and hold the „boot“ button.
    Here is an example image to help you locate the buttons:

image
It might look different for your toolhead, as different revisions have been installed in the machines.

  1. Press and release the „reset“ button.
  2. Release the „boot“ button.

Verify if its really in "RP2 Boot" mode. You can do this by:

lsusb

This means it is in boot mode:
tut6_in_bootloaderMode
This means it NOT in boot mode:
tut6_not_in_bootloaderMode

Run lsblk:

lsblk

See if you can find a partition at 128MB size. This means it is in boot mode and the partition is "sda1":
Image
This means it NOT in boot mode:
tut2 8
if thats the case, go back to step 1.

Flashing the firmware to the toolhead.

  1. Find the file Toolhead_RP2040.uf2 from the mainboard_and_toolhead_firmwares section matching your Klipper version.
  2. Download it.
  3. Use your favourite program to copy this file to the ~/FreeDi folder of your printer (eg. WinSCP).
  4. Flash the toolhead by run:
sudo cp ~/FreeDi/Toolhead_RP2040.uf2 /dev/sda1
  1. Shut the system down (sudo shutdown) and shut it off (switch off or cable disconnected).
  2. Wait a few seconds (at least ~10s) and turn the printer on.

Enter the serial ID to your printer.cfg

  1. SSH to your printer (eg. via putty) and run the command
    ls /dev/serial/by-id/* Note the device ID which will be printed like:
    image

  2. Connect to your printer via your favorite browser and replace the ID in the [mcu MKS_THR] section of the printer.cfg with the one you got before:
    image

  3. Dont forget to hit save & restart at the top right corner ;)



#3 You are a hardliner and want to compile it on your own?

Yessir, I want it the hard way!

Compiling the toolhead firmware

Run:

cd ~/klipper
make menuconfig

set it according to this:

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

save with q

Run:

make clean
make -j4

Flashing the tool head

Bring the toolhead into "RP2 Boot" mode (check the easy section how to do that).
Check the partition with lsblk - in my case "sda1".
Run the following command adjusted to the partition you found.

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

Compiling the mainboard mcu firmware

Run:

cd ~/klipper
make menuconfig

set it according to this:

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

save with q

Run:

make clean
make -j4

This will generate a „klipper.bin“ file in the /home/mks/klipper/out/ folder.
Use your favourite program to get this file onto your computer (I am using WinSCP).
Rename it to „X_4.bin“ and flash it like in the easy section.

⚠️ **GitHub.com Fallback** ⚠️