Installing Klipper onto your 3d printer is a multi part process. Those parts include:

  • Flashing an operating system on additional microcontroller[MCU dependent]

  • Installing Klipper, Moonraker, and Fluidd onto the microcontroller(or another front end ie mainsail)

  • Creating a firmware image

  • Flashing Klipper firmware image onto your 3d printer

  • setting up the printer configuration file for your 3d printer

Below you will find the steps to take in order to accomplish all these different processes. There’s also a video that goes over nearly the same information if you want to use that as a reference.

In this article I use a raspberry pi as the additional MCU running Klipper. However, with the cost of raspberry pis at an all time high, there are more and more options available to get Klipper running. If you aren’t using a raspberry pi some of these steps may be different, however, in general, this guide should be able to give you a good starting point and in most cases be directly compatible.

In this article I use KIAUH (Klipper Installation and Update Helper) to install Klipper. The work the people behind this project have put in really lowered the barrier of entry for many many people. The installation is easier than ever and the process is identical on a wide array of different MCUs.

**As with most things you find on the internet, especially for free, download and install any or all of these files and profiles at your own risk. Due your diligence and make sure the steps you are taking are all correct for your machine. PrintsLeo3D takes no responsibility for any harm this may cause you or your 3d printer, please proceed with caution!**

Flashing an operating system on additional microcontroller [MCU dependent]

To begin we need to create the operating system that will be loaded onto an SD card and power (live within)our raspberry pi. To do that I put my SD card into a USB adapter and plug it into my computer.

  • Format SD card FAT32/4096 bytes

  • Open Raspberry Pi Imager and prepare to flash SD card

    • Raspberry PI OS 32 bit lite

    • Select mounted SD card

    • Open advanced menu(gear icon) and change the following options:

      • Set a hostname .local (ie. ‘klippersetup.local’)

      • enable ssh

      • enable wifi

      • change password 

    • Perform the flash

      • Do not re-format when finished!

  • Remove the SD card from the computer, insert it into the PI and power it on. At this point the pi does not need to be connected to the printer in any way, it just needs to be powered on using a power cable.

    • This SD card is the Operating System for your Raspberry Pi and once inserted into the pi will not need to ever be ejected. It’s the brains of the operation and will remain there.

    • This is what’s called a ‘headless’ setup. Meaning our raspberry pi is a fully functional computer but it does not have a screen or keyboard for us to issue and read commands. In order to communicate with the pi we will use a computer to log in remotely using SSH, and execute all the necessary steps from the command line.

Installing Klipper, Moonraker, and Fluidd

SSH into the PI using PUTTY

  • Enter the .local hostname you configured while setting up the Operating System (ie. ‘klippersetup.local’). and log into the pi with the username and password you set up

  • Find the ip address of the pi by using command: ifconfig. Record the address somewhere, it’s what we will use to access the pi from here on out.

    • SSH and using the ‘ifconfig’ command is important to know. Most ip addresses are dynamic, meaning, after some time they will change. If one day you go to log onto your printer through this address and it’s not connecting it doesn’t mean there’s anything wrong with your setup, it’s possible the ip address has changed. If that happens SSH into the pi using the .local address and run that command ‘ifconfig’ and the pi will return it’s new ip address.

  • Once logged into the pi, at the command line run the following commands in this order:

git clone https://github.com/th33xitus/kiauh.git

./kiauh/kiauh.sh (run as a single command. Can be found https://github.com/th33xitus/kiauh)

  • ****Optional if installing CUSTOM REPOSITORY****

    • Before using the KIAUH menu(after installing installing it) exit PUTTY

    • Open WINSCP and SSH into the pi (using the ip address)

    • Inside WINSCP the files contained on the pi will be shown to the right side of the app, while the left side will be showing your local device(i.e. the computer you're using).

    • On the pi side(right ) open the file “Klipper_repo.txt.example”. At the bottom remove all example repos(3) and add your custom repo(ie. https://github.com/stas2z/klipper-aquila-n32.git,aquila-n32,aquila-n32) 

    • The text file has all the information on how to go about this process

    • Save the file as Klipper_repo.txt (removing the word example) and exit WINSCP

    • Using PUTTY SSH back into the pi and continue with KIAUH by running the command:  cd ~

git clone https://github.com/th33xitus/kiauh.git

./kiauh/kiauh.sh (run as a single command. Can be found https://github.com/th33xitus/kiauh)

  • You will now be at the KIAUH menu where you will install the Klipper files. Navigate to the INSTALL menu, #1, and then install in this order

    • Klipper OS (#1 Klipper)

    • Moonraker API(#2 moonraker)

    • Fluidd FRONTEND (#4 fluidd)[add recommended macros and camera stream]

  • ****Optional if installing from CUSTOM REPOSITORY***** 

    • Exit the INSTALL menu by using B(back) and then enter the SETTINGS menu

    • Enter the Custom Repo menu option(#2)

    • Select your custom repo by entering it’s number (should be #0) and then running through all the prompts.

    • Exit this menu (B) to the home screen  

Create a Firmware Image

It’s possible I have already created the images for your 3D printer. Head over to the Klipper FIRMWARE IMAGES page and find out.

Exit the INSTALL menu by using B(back) then enter the ADVANCED(#4) menu.

  • Enter FIRMWARE BUILD ONLY

  • We are now compiling the firmware for the mainboard we are using. This information will be different for each board (ie. SKR mini E3V3, Creality 4.2.2., Aquila G32 chip, etc.)

  • Set up the firmware image exacly how it needs to be for your mainboard. If you have questions you can try my webpage here. Alternatively the printer.cfg file that will accompany your printer will often have the correct way to flash the firmware at the top of the file.

  • Q(quit) when finished, this will build the firmware.

  • When the firmware is finished building go back(B), Quit(Q), and exit PUTTY

  • Open WINSCP and ssh into the pi(ip, username, password). We are going to copy the ‘built’ firmware(meant for the 3d printer) onto an SD card, then insert and flash it to the 3d printer

    • Insert an available SD card into your computer and format it with these parameters = [FAT32 / 4096 bytes]

    • Inside WINSCP the files contained on the pi will be shown to the right side of the app, while the left side will be showing your local device(i.e. the computer you're using). On the local side (left) the available SD card needs to be the open and active folder. Navigate there using the dropdown menu available

    • On the pi side(right) Enter the KLIPPER folder

    • Enter the OUT folder

    • Find the Klipper.bin (or firmware.bin) file, copy it, then paste it to the SD card which should be active on the left side of the app. You can simple drag and drop this file as well.

    • The manner of firmware execution will vary from printer to printer. Make sure the klipper.bin file is named correctly and nested within any folders if necessary (ie. Aquila needs to be nested in ‘firmware’ folder)

    • Quit WinSCP and eject the SD card

Flashing Klipper firmware image onto your 3D Printer

Insert the firmware.bin equipped SD card into the 3d printer and power it on. This should begin the firmware flash.

  • Again each printer(mainboard) has a different way of flashing the firmware through SD, make sure to follow the correct guidelines based on your mainboard. Also I don’t want to confuse, we are flashing the mainboard of the 3d printer, I am saying ‘flashing the printer’ as shorthand. EACH MAINBOARD HAS ITS OWN UNIQUE METHOD OF BEING FLASHED. Follow the method for the mainboard not necessarily for the model of printer. (ie the stock Voxelab Aquila needs the firmware.bin to be within a folder, however if you have installed a different mainboard, like the SKR miniE3V3, onto the Aquila, then you will not perform the flash in this way. SKR mini’s need the firmware.bin to be outside of a folder and named ‘firmware.bin’)

  • After 20-30 seconds the firmware should be flashed. Klipper is not compatible with most 3d printing screens, at this point after a flash your screen may become corrupted or unresponsive. Power down the 3d printer and remove the SD card

Setting up the printer configuration(printer.cfg) file for your 3D printer

Power on the 3d printer, and then power on the raspberry pi. After startup connect the raspberry pi to the 3d printer.

  • Open the PUTTY app and SSH once again into the raspberry pi

    • Get the serial port (this is the address for how the pi is connected to the printer)

    • Execute this command: ls /dev/serial/by-id/*

    • Copy the returned result to be used later(i.e. ‘insert example here’’)

    • Exit PUTTY

  • Open your preferred web browser and enter the PI’s ip address to access the front end of your 3d printer (ie. FLUIDD).

  • You are brought to the home screen of FLUIDD. At this point the printer will not be communicating with the pi.

  • Enter the CONFIGURATION tab of FLUIDD 

    • The left partition of files are what the pi is using to run Klipper, while the files on the right are meant to be example configurations and help documents.

  • Find the file printer.cfg on the left side of the partition and open it. 

    • This is your printer configuration file, it is the end all be all of your printer, and it is a simple text document. Open it and you’ll notice it’s extremely bare bones. You need to add all the options available for your printer into this file and save it. You can do this manually which is tedious and painstaking. Luckily Klipper also has a ton of built in example configs (you can also find them online). 

  • Close the printer.cfg file (saving or not does not matter at this point)

  • On the right side of the partition find the example_configs file, enter in the search bar the model of your printer. Once you find the correct printer download the printer.cfg file. Bypassing any warnings. (you could also open the file and pursue it if you’d like, but we’ll be doing that shortly anyway)

    • The printer.cfg file cares about the physical attributes of the 3d printer: build size, thermistor brand, bed leveling enabled, stepper drives, board pinout, etc. When building the firmware we cared about the mainboard, because the firmware was built to be read and accepted by the mainboard. The printer.cfg cares about the physical characteristics and the operation of the 3d printer). 

  • Back on the left side of the partition choose to Upload File. 

    • Find the “example_config” you just downloaded and upload that file. (You should be able to drag and drop the files across the screen but it’s never worked for me)

  • Delete printer.cfg and rename the uploaded file printer.cfg (this needs to be spelled exactly). This document becomes your CONFIGURATION

  • Open the new printer.cfg file. You can see it is way more robust than the previous. 

    • Find the heading [mcu] and paste in the serial response you copied from PUTTY several steps ago.

      • serial_port: example_goes_here

      • The language used within this document is PYTHON and we need to abide by all its rules in order for the printer.cfg file to be read correctly. PYTHON cares about indentation and formatting(among other things) so please make sure to copy and paste things correctly. Follow the examples that are already within the printer.cfg if you are not sure. If you want more information about the do’s and don’ts head to this section.

    • Save printer.cfg using the option “Save and Close” at the top of the screen. 

      • Saving updates the firmware, but the printer still needs to be restarted for the changes to go into effect. Whenever you make a change to the configuration file that you want to take effect, always SAVE AND RESTART. 

  • Click the FIRMWARE_RESTART button located in the upper portion of FLUIDD. 

    • At this point your pi attempts to connect to the printer. If the connection is successful several warnings will pop up. They should all be related to MISSING MACROS. 

      • Macros are commands compiled within the firmware that can be run. The macros in question are usually all safety protocols and adding them is as easy as copy and pasting. However newer version of KIAUH have included the safety macros in a separate file, a simple line within the printer.cg finds that file and includes them. The file name in this example is likely wrong so just use it as an example [include kiauhMacros.cfg] where kiauhMacros is the .cfg file that houses all the macros you need.

      • For a more in depth look at Macros, what they are, and some exmaples head over to my Macros page.

    • The fault codes that Fluidd provides are usually great at helping to diagnose the issue. Follow the link that is accompanying the warnings and there will be several example macros. All we need to do is copy and past these into the printer.cfg

  • Within the CONFIGURATION tab open printer.cfg

    • Using the HELP url that Klipper opened(when it threw all the warnings it provided a website address) copy all the necessary macros and paste them into printer.cfg 

      • Make sure to only add sections between other sections.

      • It doesn’t matter where they are within the body of the document (beginning, middle, or end) but they need to be formatted properly. Python uses color coding to delineate different sections, so make sure they are all uniform.

    • Save and Restart from printer.cfg

  • After a moment Klipper should restart and be ready to go!

While you are now at a point where you can communicate and use your 3d printer there are a few additional steps you should perform in order to get the best experience and safeguard your printer from damage. The official Klipper documentation has all the necessary checks and procedures to follow, and I add new Klipper videos as often as I can. Of course you will need to run new calibration tests, like a PID tune, and convert your e-steps to rotation distance if you saved your e-step value. If you had an problems during the process or have any questions PLEASE LET ME KNOW. If this article helped you and you want to see or read more please go to my YouTube channel and SUBSCRIBE

*I thank everyone for the support and feedback to help make these articles better!!