Adventures in Klipper

Klipper (Last Updated On: April 30, 2021)

Let me start off by saying by no means am I an expert with Klipper, or 3D printing. I don’t really know wtf I am doing half the time, I just manage to get it working – hah! I few days ago I decided to take the plunge into Klipper with my printer, a Monoprice Maker Select v2.1 with an SKR 1.3. I had been running Marlin 2.x on my printer and it was all setup and configured and working perfectly. I decided apparently that “working perfectly” wasn’t good enough, and I needed to break it. Enter Klipper. From what I gather now that that I have a 32 bit board I wont really gain much in the way of performance with Klipper vs if I still had the 8 bit Melzi. What you do gain is a much easier way to configure the firmware over compiling and flashing the board after every change. You just save a file and reboot.

Now I wanted to document the process for others in case it helps, and I figured this would be a quick build process and a quick write up. Heheh, I was wrong. I has now been a solid week of tweaking and configuring Klipper as well as a few days of writing this post and attempting to get it finished. Every time I do something else comes along that I feel I need to add to the process. Well, I finally got it all done – I think. Now what started off as a nice clean post turned into a ton of sections that didn’t jive. I’ve done my best to make it all flow and make sense, if I missed something let me know.


Table of Contents


Flashing the Printer

Flashing Klipper to the SKR was a dead simple task, as well as getting it setup on the Raspberry Pi that I already had OctoPrint on. The SKR gets flashed with a premade firmware.bin file that you get from Github, that simple. The Raspberry Pi gets hit with a git clone command and after a make or two your OctoPrint (or another choice) is Klipper ready. The part that can be difficult is configuring the printer.cfg file for your board and your printer. While I said editing the firmware was easy that is true, figuring out what to configure is a different beast.

When I say configuring Klipper can be difficult is because I found the documentation and help out there severely lacking compared to setting up Marlin. When I dove into Marlin I found a plethora of assistance on the web and it was not scattered all over the place. Not so much for Klipper and Fluidd. And as it turns out there was major breaking changes made to Klipper just a few months ago that made a lot of the config files that you will find out there completely obsolete and not working without some heavy modifications. Mainly in the menu department. Plus, I know Marlin now after digging through it a few times, so I had to learn a new setup and configuration scheme. It was a pita, but not really all that bad. Don’t be scared. After digging through the Klipper docs and making my own printer.cfg  I am now as comfortable with Klipper as I am with Marlin.


Need an Ender 3 printer.cfg for Klipper?

Go visit Reddit here this post helped me out a ton setting up my printer with Klipper. If you happen to have an Ender 3 and not a Maker Select then you may want to head over there and use that config. Ender 3, BlTouch v3, SKR 1.3, TMC2208s, Runout sensor, and more.

If you have an Ender 3 or 5 you are set, there are a million config files for you to follow out there. I however do not have an Ender 3, I have an old discontinued Maker Select. So I am on my own so to speak. There are premade config examples for the SKR 1.3 and for the Maker Select (running a Melzi) and a ton of other printers. So I had to take both of those files and mash them together to get my printer up and running. Then I found a few configs on the web to scrape some goodies from, macros and such.


Enter MainsailOS, FluiddPi and DWC2 – Goodbye OctoPrint

There are a few alternatives to OctoPrint when it comes to Klipper. From scrounging the web I’ve noticed most people don’t particularly have a flawless experience with OctoPrint and Klipper. There is a plugin, OctoKlipper, and that has been referred to as a bandaid a few times. Then there is the issue of OctoPrint and how it handles gcode when printing. I’ve seen, and experienced, issues with OctoPrint and its printing quality. From what I read OctoPrint actually touches the gcode and sticks in its own gcode as needed for other commands, this is what causes the printing issues and stutters, that and I have heard many times there are issues with OctoPrint and how it communicates over USB. Things just seem so much better without OctoPrint. Don’t get me wrong I love OctoPrint and it is a great piece of software but with Klipper it seems there may be better options. Klipper with Mainsail or Fluidd seem to be the answer. They are both designed specifically for Klipper, native support. They don’t touch the gcode, the just stream it. Much better quality prints from what I have seen out there. It is sad that I will be losing the OctoPrint plugins system. Some of those plugins are fantastic. But I am in the search of quality and faster prints and OctoPrint was not giving it to me.

There are downsides to Fluidd/Mainsail, there are no plugins. Where there are no plugins there are Macros. Klipper allows you to make gcode macros to do pretty much anything. After adding the Raspberry Pi as a secondary MCU you gain access to the GPIOs and you can do whatever you need pretty much all with macros. Coding up a macro adds buttons or switches for you on the main GUI page to play with. No plugin needed, no bloat. They’re also very mobile responsive. Unlike OctoPrint.

I was first very hesitant switching from OctoPrint, because well thats really all I have ever known since I began 3D printing and I have been using it for a few years now. Well after a few days with Fluidd I am sold. I switched. I just happen to like Fluidd over Mainsail a little more. It was a GUI choice basically. DWC2 didn’t give me enough control over Klipper for me to want to use it. But it did have a really nice interface. As to why I like it over OctoPrint? It is so lightweight. I like the macro system, a lot. I like that I can add just what I need without someone else’s code by just adding some gcode. Neat.

Mobile view on Fluidd/Mainsail works very well. It will hover certain display portions as you scroll so you can view the console and have macro access at the same time. Awesome macros like screws_tilt_calculate. After using that to level the bed and print a few objects I am pumped for 3D printing. Fluidd feels great to me! This firmware is freaking awesome! The bed screws tilt feature alone is worth it to me. But the whole interface is great.

One major downside to the Klipper/Fluidd firmware software setup is that your macros, since they are gcode, do not get executed until there is time to send the gcode. So if you send a gcode command to turn on a light after you have started the homing process or a print, it will take a minute for the gcode for to get executed. Nothing major but it is a pain in the but sometimes. You just have to think ahead when using the macros.

Oh and any time you save the config files (SAVE_CONFIG command) just know it will restart the Klipper service… what the fuck, that is a huge pain in the ass, but that is the way it is.

I highly recommend printing large, white, thumb wheels for you bed screws if they didn’t come with them already. After you print the wheels make a mark with a marker on them or print dual color and use a darker color for the base and white for the line markings on the top. This will make it much easier to level the bed with Klippers assistance. When it tells you to turn the rear left wheel 1.26 turns CCW then you will have at least have a gauge to use when turning the knobs. Trust me just do it.

However, there is NO TIMELAPSE feature in Mainsail, Fluidd or DWC2, so ye turn back now if you all you care about is pretty fast videos of plastic printing more than quality and performance.

As for DWC2, it has a beautiful interface I can say that much. But I didn’t like the fact that I couldn’t figure out how to do a restart or a firmware restart or edit the config files – thats a problem. Maybe I am an idiot but I did not see them. But if you want to check it out, install KIAUH and select DWC2 for installation. Simple as that.


Mainsail Dashboard 1

Mainsail Dashboard 2

Mainsail Heightmap


Mainsail Settings

Fluidd Light Theme Dashboard 1

Fluidd Light Theme Dashboard 2


Fluidd Light Theme Bed Mesh

DWC2 Dashboard

DWC2 Status


Fluidd Docs Website –

Fluidd –

FluiddPi –

Mainsail Docs Website –

Mainsail –

MainsailOS –

DWC2 –


Try them out yourself!

Grab an SD card and flash Raspbian/RaspiOs Lite. Install and use KIAUH (Klipper Installation And Update Helper). It will help install and maintain the software. Super easy. It installs and maintains Klipper, Moonraker, Mainsail, Fluidd, KlipperScreen, DWC2 and OctoPrint for you. I used it to install all of them to try out on the same SD card on the same Pi. It will use different ports for the web GUIs. I also used it to install KlipperScreen on a second Pi. You can install all of them and try them out, or just one.


Fluidd Cloud Alternative

Run Moonraker only and outsource Fluidd to the cloud – –

Moonraker cloud example –


How to Install

There are a few ways to install the software needed for Klipper. OctoPrint, Mainsail, Fluidd, DWC2. Along with those there are also premade images for the Raspberry Pi for most of those – OctoPi, MainsailOs, and FluiddPi. You can install them manually or you can use KIAUH to manage and install them for you. Or you can download and flash the image for the software you want to interface with your printer.


Important: I am going to walk you through the best as I can installing KIAUH, Fluidd and Klipper meant for a Raspberry Pi with an BigTreeTech SKR 1.3. I will also touch on Mainsail and OctoPrint. There are many ways but this way is mine.


Download and Install FluiddPi on the Raspberry Pi

Go out and download and flash a SD card with the FluiddPi image with your method of choice. I am going to assume that by now you know how to do that. Once FluiddPi is flashed slap it in the Pi and boot. Don’t forget to add a blank file named SSH (I can’t remember if it comes SSH ready or not) and edit the fluiddpi-wpa-supplicant.txt file for the wifi if needed. Do the usual and change the timezone, keyboard etc with raspi-config. Save and reboot. Then SSH back in.


Download and Install KIAUH

I know we already installed FluiddPi as an OS so Fluidd is preinstalled along with Moonraker. True, but installing KIAUH allows you to easily update the install, and you have options for the future.

First things first, update the raspberry pi, always update first. It could save you some headaches.

To download and install the KIUAH:

Use ./kiauh/  to run it. It will prompt you through the install/uninstall/backup/update process. Thats it. Quick and painless. Run KIAUH and see if you are up to date.


Install OctoPrint and Klipper on the Raspberry Pi

If you don’t want to install Fluidd or Mainsail now is the time to install OctoPrint or OctoPi instead. Install OctoPrint (or OctoPi) like you normally would (OR install KIAUH use that to install OctoPrint and Klipper). If you installed OctoPrint the original way then you need to install Klipper and the Klipper OctoPrint plugin, you  can still use KIAUH. If you installed FluiddPi or MainsailOS you should not need to install Klipper, but I am not 100%.

Don’t forget to also install the Klipper OctoPrint plugin, if you installed OctoPrint/OctoPi that is.


Install Klipper on the SKR 1.3 and Raspberry Pi (manually)

To compile the micro-controller code, start by running these commands on the Raspberry Pi (with an SKR 1.3):

Select the right micro-controller (LPC176x for the SKR 1.3) then run:

After you run make  to compile the firmware for the SKR 1.3 you will have a klipper.bin firmware file that we need to flash on the board. The file must be renamed firmware.bin when placed on the SDCard to flash the board. The board will flash itself and rename it to firmware.bin on its first boot. The klipper.bin file is located in ~/klipper/out/.

It is necessary to determine the serial port connected to the micro-controller. Run the following commands:

It should report something similar to the following:

That is you serial port. The board can usually be flashed with something similar to:

That did not work for me however, so if it throws an error for you too just copy the USB identifier (the string we were looking for) and we need to paste it into the “mcu” section of the printer.cfg file.


Set the Raspberry Pi as a Secondary MCU

This gives you control over the GPIOs. Now you can make macros to runs LEDs off and on, fans, read sensors etc…

Install the rc script

After installing Klipper, install the script. run:


Building the micro-controller code

To compile the Klipper micro-controller code for a secondary mcu we start by configuring it for the “Linux process”, re-run the commands:

To build and install the new micro-controller code, run:

If you get a permission denied error: '/tmp/klipper_host_mcu'  you can add yourself to the tty group.
Then reboot. If all else fails and it still produces a permission denied error you can (not recommended): sudo chmod 777 /home/pi/virtual_sdcard.

First Setup

Before you can successfully connect to the printer with Klipper we need to have the printer.cfg  file setup and configured correctly. Besides the basic stuff for your printer config Fluid/Mainsail wants a few things specified. Your printer.cfg  must contain the following macros:


Make sure you make the virtual SD card directory on the Pi first. SSH into the pi and run:

Or change “virtual_sdcard” to whatever path you want your STL files saved to, just remember what it is you are going to use it in the next step.


Then copy, past and edit any changes you need to. These are the macros required by Fluidd/Mainsail or it won’t start.


My Configuration

I originally had one large printer.cfg. Then I found out you can split them up and just include the files. So I have done just that. I have the main printer.cfg  and I also have menu_custom.cfg , menu_disable.cfg  (my attempt to disable stock menus), macros.cfg  and macros_gpio.cfg  for all the Raspberry Pi GPIO macros. They are rather large to just list so I will link to Github with my configurations.

Remember, these Klipper config files are made for a Maker Select v2.1 with an SKR 1.3 using dual Z-steppers and running four TMC2208s with a BLTouch v3.


Dual Z Steppers

Here is an example of a printer.cfg with dual Z steppers enabled, all you have to do is specify the pins and that there are two steppers. Pretty easy, once you see an example.


BLTouch v3 (for SKR 1.3)

My settings for the original BLTouch v3

A few useful commands:


Bed Mesh and Offsets

You must set you offsets for the BLTouch correctly and take those into account with your bed size and the mesh. for example you have to set a mesh_min and a mesh_max. You would think mesh_min: 0,0 and mesh_max: 200,200 would be the correct way to go but it is not and it will fail. The probe will try to go outsize the bed size when this happens, it will error out and stop. For a bed size of 200×200 and a BLTouch (using this mount) the mesh_min: 50,50 and mesh_max: 150,150 is what should work for you, that is what is working for me. I will probably play with that to see if I can get it tighter but those numbers are working.

Bed leveling out of range –

Bed Visualizer OctoPrint Plugin

To get Klipper and the Bed Visualizer plugin to play nice we have to add some special code to the plugin.


The Camera

I followed this guide it is what I used to get my Raspberry Pi camera up and running, below is basically the same thing – I am not sure about USB cameras as I do not have one and at the time of this writing there was jack squat on the big name searches for “fluidd usb camera”. Even the r/Klippers Reddit came up with a big fat zero. So sorry if you have a USB camera and wanted to use Fluidd/Mainsail.

The guide on that website all says Mainsail but don’t worry Fluidd is a fork of Mainsail and it *should* all work ok no problems.


Getting an RPi camera to work with Fluidd/Mainsail

We are going to install the raspberry pi camera for Fluidd or Mainsail. I have an official RPi camera v2 module and this worked for me with no issues.


I got an error cause the folder already exists on a FluiddPi install but the camera did not “work out of the box”, but why?


Now we can start and test the stream.

Start the streamer:

Test it in a browser – http://YOUR_RPI_IP:8080?action=stream or http://fluiddpi.local:8080?action=stream.


Now we are going to want to run the camera streamer on startup aren’t we? Of course we are. We need to create a file first and add some details.

sudo nano /etc/init.d/

Then copy and paste the info below, edit the details as needed (like file name or camera resolution).

After a copy and paste you can save ctrl+o  and then quite ctrl+x . Now that we have our startup file create we need to enable it at start up.


Now start the new service: sudo service fluidd-stream start . Then test the service: sudo service fluidd-stream status , ctrl+c  to exit. Then we need to add the settings to Fluidd or Mainsail themselves.

In Fluidd click on the menu and enter UI Settings, now we are going to add webcam/?action=stream in to the webcam URL for the webcam stream. Make sure it says “enabled” for the webcam. Click “Dashboard” again and now you should hopefully see your shiny webcam feed!


Raspberry Pi Camera Resolutions

On the V2 camera, these are:

# Resolution Aspect Ratio Framerates Video Image FoV Binning
1 1920×1080 16:9 0.1-30fps x Partial None
2 3280×2464 4:3 0.1-15fps x x Full None
3 3280×2464 4:3 0.1-15fps x x Full None
4 1640×1232 4:3 0.1-40fps x Full 2×2
5 1640×922 16:9 0.1-40fps x Full 2×2
6 1280×720 16:9 40-90fps x Partial 2×2
7 640×480 4:3 40-90fps x Partial 2×2



Klipper Menus & How to remove menu item in Klipper

Be aware that a lot of the examples out there will require modification to work, one of the last Klipper updates they changes how the menu system works. Example:

Here is an example of the new menu system:

Here is a good generic menu example –

Do not edit the default menu.cfg – /home/pi/klipper/klippy/extras/display/menu.cfg

Don’t edit the menu.cfg  file, it may be overwritten with a Klipper update. Instead, according to this Github issue, you can specify to not display the menu item by placing it in your printer.cfg file. Instead add enable: false to the tag and it will hide the menu item.





Other Useful Things


How to make Macros guide

Here is a really good guide and description of how to make custom gcode macros for Fluidd/Klipper, it popped up on the Fluidd Discord (which I recommend joining).


Some useful Klipper Commands

  • QUERY_ENDSTOPS: Gets the state of the endstops open/close.
  • GET_POSITION: Returns the position of the toolhead.
  • QUERY_PROBE: Report the status of the probe.
  • TURN_OFF_HEATERS: Turns off all the heaters.
  • RESTART: This will cause the host software to reload its config and perform an internal reset. Does NOT clear errors.
  • FIRMWARE_RESTART: This is similar to a RESTART command, but it also clears any error state from the micro-controller.
  • SAVE_CONFIG: Saves the current state to printer.cfg  and restarts the host.
  • STATUS: Report the Klipper host software status.
  • HELP: Gives you a list of Klipper G-Code commands.
  • BLTOUCH_DEBUG COMMAND=<command> (commands are pin_up, pin_down, self_test, reset)
  • DUMP_TMC, DUMP_TMC STEPPER=stepper_x (stepper_x, stepper_y, stepper_z, stepper_e)


Klipper Discourse


Pressure Advance (Marlin calls it Linear Advance)

Resonance Compensation (ringing)


Calibrate Z Offsets


Calibrate E-Steps the Klipper way


Calibrate E-Step as Rotation Distance


Adding Sensors and Switches to Klipper/Fluidd/Mainsail and maybe OctoPrint


Raspberry Pi CPU Temperature example (this will report on the temperature graph):


Example of a GPIO on/off switch:


Samba Shares

Setup SAMBA shares on the Raspberry Pi running Klipper and access the printers virtual SD card from your computer for uploading print files.


You want system monitoring?

You want system monitoring? Miss the OctoPrint Resource Monitor Plugin? Install and use Glances. Glances is like top/htop  as it works for the command line but it also has a webgui frontend that serves the same information. Here is a quick how to install for Glances and how to use it as a service, if you want a more detailed install see this guide.

Install Glances

You can use the command line glances too from here or you can fire up the webgui. Type this in a command terminal (ctrl+c to stop):
You should be able to see Glances at http://YOUR_IP:61208.

Pretty sweet right? Now we need to set up Glances webgui so it starts on load for us.


Copy and paste the following:

Now we have to enable and start the new service.

If everything went as planned you should have access to Glances at http://YOUR_IP:61208.


Filament Sensor

Now this one has proven to be a pain. If you search for “Klipper filament sensor” you will get results but I’d imagine most of them won’t work. Give this one a try – its from the Klipper Github after all.

  • QUERY_FILAMENT_SENSOR SENSOR=<sensor_name>: Queries the current status of the filament sensor. The data displayed on the terminal will depend on the sensor type defined in the configuration.
  • SET_FILAMENT_SENSOR SENSOR=<sensor_name> ENABLE=[0|1]: Sets the filament sensor on/off. If ENABLE is set to 0, the filament sensor will be disabled, if set to 1 it is enabled.




  1. September 15, 2021 / 1:04 am

    really nice overview with all the essentials in once place.. I can commission a new printer&camera in just a few minutes by following your guide.

  2. September 26, 2021 / 8:55 am

    Nice summery. I am running a Monoprice Maker Select V2 with the stock board. I am using an inductive level sensor. The whole setup works well. The only issue (none Klipper) was the extruder. I had rampant heat creep and frequent throat tube clogs. I solved the problem by switching to a Bisque bi-metallic throat tube with an MK8 nozzle and heat block. Now I don’t have the clogs and it heats like a bat out of hell.

Leave a Reply