Last time I tried to convince you that, if you haven’t already, you should try running your 3D printer with Klipper. There are several ways to actually make it work.

The first thing you need is something to run the Klipper host. Most people use a Raspberry Pi and if you already have one that runs OctoPrint, for example, you might well use it. Just tuck your SD card away in case you give up and install a fresh Linux system on a new card.

However, a Pi isn’t your only option. You should be able to make it work on nearly anything that runs Linux. We’ve even seen it running on Windows under WSL. If you have an old laptop that can run Linux, that would work, too. We’ve even heard it works on a Chromebook.

The other option is to get a “pad.” Several vendors make touchscreens with some Linux single-board computer bundled together with Klipper preinstalled. For example, there is the Creality Sonic Pad, along with similar devices from other 3D printing companies.

If you decide to go that route, you might want to make sure it is easy to install your own software easily. Some pads, like the Creality unit, are notorious for having so much customization that they don’t lend themselves to upgrades unless they come from the manufacturer. In some cases, you can wipe out the stock firmware and install a normal operating system, but at that point, you could probably just buy a Pi and a touchscreen, right?

Installation

If you use something like a pad, it probably has a menu option to provide prebuilt firmware for your printer. Typically, you let it save the code to an SD card or a USB stick and then you are expected to flash it to your printer which, of course, depends on what kind of printer you have.

If you are rolling your own, you use a menu configuration program something like building a Linux kernel. If you have a pre-built configuration file, it will probably tell you in its comments what things you should pick. You need to know, for example, the type of CPU your board has, the bootloader offset, and if you are connecting via USB or serial. You can find details on the Klipper project pages.

Installing the Linux side is easy because there is a nice script called KIHUH. The easiest thing to do is clone the Git repository and run it. From there, you can install Klipper, Moonraker, Fluidd, Mainsail, and some other things, too.

The real trick isn’t installing the software. The challenge is creating a proper configuration file for your printer. If you have a totally stock and popular printer, you’ll probably be in luck. But, how many of us can say that?

Start with the GitHub list to see if your printer or board is there. Even if it isn’t an exact match for your hardware, it will give you a start. For example, my custom printer is a Fysetc Spider, but the canned configuration is for a core XY machine, which means I have to make changes.

Even if you get a pad that claims to be “plug and play,” don’t count on it. For example, a Creality Sonic Pad’s instructions for installing with a Creality Ender 3 first asks you to take the printer apart to determine the type of motherboard you have. That’s not really plug and play! Any deviation from the stock machine is likely to require you to change the default profile.

Ch…Ch…Ch…Changes

In addition to just setting things up to match my exact hardware, I also needed to adjust the extruder step count. That has to be simple, right? Most firmware requires you to plug in the number of steps per millimeter of filament.

Klipper, on the other hand, wants to know how many millimeters extrude from a full rotation of the stepper. If you know how many steps (and microsteps) your printer uses, you can easily calculate either number from the other. For example, if you have 200 steps per rotation and 16 microsteps, that’s 3200 steps total. If your current steps per millimeter is 100, then your Klipper “rotation distance” is 3200/100=32.

Configuration Example

I had another major change to make. My printers have a non-standard filament sensor that detects the filament moving. That way, it can detect not only broken filaments but jammed filaments, too.

To install it, I had to add a few lines to my printer.cfg file and restart Klipper. Since I have more than one printer with the same sensor, I put all the lines in a single file and then included it in each printer. So the printer.cfg change was very simple:

[include sfs.cfg]

Then the real work is in sfs.cfg:

[filament_motion_sensor SFS_T0]
detection_length: 10.00 
extruder: extruder
switch_pin: ^PA4 
pause_on_runout: True 
event_delay: 3.0
pause_delay: 0.5
runout_gcode:
  M117 Runout Detected!

[delayed_gcode DISABLEFILAMENTSENSOR] 
initial_duration: 1
gcode:
 SET_FILAMENT_SENSOR SENSOR=SFS_T0 ENABLE=0

[gcode_macro SFS_ENABLE] ; Add this to PRINT_START
description: Enable smart filament sensor
gcode:
  M117 ENABLING the Smart Filament Sensor
  G92 E0
  SET_FILAMENT_SENSOR SENSOR=SFS_T0 ENABLE=1

[gcode_macro SFS_DISABLE] ; Add this to PRINT_END and PRINT_CANCEL
description: Disable smart filament sensor
gcode:
  M117 DISABLING the Smart Filament Sensor
  G92 E0
  SET_FILAMENT_SENSOR SENSOR=SFS_T0 ENABLE=0

This defines a few macros you can use elsewhere. Like Python, the indentation matters. You can organize your files using [include], and that’s especially useful if you have multiple printers that can share files.

Reference

So, how do you know what’s available? The Klipper reference. It will show you all the configuration sections you can use and what can possibly go in them. Don’t forget that some features — like print status notifications — will be in the Moonraker configuration which is a separate document.

Since the system is in Python, you can hack on it to your heart’s content. Just back up first. For example, you can add some custom Python scripts in the klipper/extras directory, like the one that can run arbitrary system commands from G-code.

Tinkering is what most of us like the best, and there’s plenty of opportunity to tinker with here. Klipper is also a good way to put new life in a very old printer since what runs on the printer is very simple, and all the heavy lifting is done elsewhere.

Klipper can easily do adaptive bed leveling, for example. If you can work in Python, it is also easy to experiment with things like exotic sensors.

I have several 3D printers, and I’ve always been satisfied with using either Repetier or Marlin on all of them. There are a few other firmware versions that could run on my hardware, but those two have been all I’ve needed. Sure, it was painful for a while having to juggle features to fit the firmware image onto the smaller microcontroller boards. Now that Marlin supports big 32-bit boards however, that hasn’t been a problem. But recently, I’ve been on a program to switch everything to Klipper.

In this post, I’ll tell you why I did it and give you some data about why you might consider it, too.

The Landscape

Marlin is written in C and burned into a 3D printer’s flash memory. It does a lot. It receives G-code commands, interprets them, and translates them to meaningful actions on the hardware. Modern versions handle automatic transformations to account for lumpy beds, input shaping to reduce shaking, and linear advance to produce better prints.

It might seem simple to control a 3D printer, but there are lots of little details to take into account. For example, if you are moving the head between two XY coordinates and you expect a certain flow rate, then you have to figure out how fast to turn the steppers to get the right amount of plastic out over that time. You also may have to retract before you start a move, make sure temperatures are stable, and transform the actual coordinates based on bed leveling data. There’s a lot going on.

Klipper does the exact same job, but it does it differently. On the 3D printer board is a tiny piece of software that does very little. It’s a bit like a device driver for the printer. All by itself, it does nothing. But it can handle very basic commands that describe how to move the machine.

All the rest of the processing you expect to happen now runs on some Linux computer. That is very often a Raspberry Pi, but it could be a spare laptop, your desktop computer, or anything that will run a reasonable Linux install. Several vendors even sell single-board computers with touchscreens made specifically for running this part of Klipper.

However, even though a screen is nice, you don’t really need it. I’ll talk about that more later.

The Problem

Historically, Klipper was a way to break out of the limitations of using tiny 8-bit controller boards with limited memory. These days, you can get plenty of powerful 3D printer controller boards, so that isn’t as much of an issue as it used to be.

Instead, I have another problem. The build. One of my printers is a custom printer that doesn’t really match any other printer in the world. So, I have to build my own version of Marlin. That’s actually not very hard to do. However, there are two things that are very annoying. First, you have to flash the firmware. The printer uses DFU, and I have brought out the “bootload” switch, but it is still a pain, and I possibly will brick the printer if I make a mistake. A recoverable brick, but still.

But the real problem is keeping my version of Marlin up to date with the official version. The version I have running now is old enough to not have some of the cool features, so I would have to merge the mainline in with my fork. Can it be done? Of course. But it’s awkward, and the longer you wait, the worse it gets.

For a recent 3D printing class I sometimes teach, I picked up two cheap printers that had great support for Klipper, so they were my guinea pigs before I attempted to switch over to the custom printer.

I should note that Klipper, I think, appeals to people who like tweaking settings and editing configuration files. Since you’re reading Hackaday, there’s a good chance that describes you. But if you despise opening a Bash shell and entering text, you might think about avoiding Klipper. While the UIs do a good job of protecting you from most of this, there’s going to be times when you’ll need to get your hands dirty.

Is Klipper the Solution?

You do have to flash a small program over to your board to run Klipper, but once you do it, you very likely will never do it again. If you are dissatisfied, you can flash Marlin back and there’s no harm done. Just make sure you can get your hands on a stock firmware image for your printer before you start making any changes. In my case, I do have the ability to go back to Marlin if I ever wanted to. But at this point, the only reason I’d make the switch back was if I planned on selling the machine to a beginner.

After that one flash, all the other setups for anything you want to do are done through Linux, mostly through a simple configuration file. There are also web-based and touchscreen-based GUIs, but everything is really in a file. The code, too, is mostly in Python, so making a change or adding something is relatively simple, especially if you are comfortable with Linux. The hardware stub and a small part of the host is in C, however.

If you aren’t comfortable with Linux, the user interfaces will help. You can even use them to edit your configuration files in your browser, so it is possible to have no idea how to use Linux and still get by.

Klipper Architecture

I was going to draw a diagram of the Klipper architecture, but [Sineos] beat me to it, so I borrowed this one from the Klipper discourse group’s documentation.

At the top right is the Klipper firmware — that’s the stub that executes basic commands on the hardware. The box on the bottom right indicates that you can even treat the computer Klipper is running on as a hardware host, and — what isn’t shown — is that Klipper can manage multiple controller boards (more on that later).

The final red block is the host, and that’s where all the real processing occurs. It reads G-code and worries about bed level, temperature, and so on. One of the key features is that you control it with macros, which could look like G-code or something else.

Custom G-Code

For example, suppose you want to create a new G-code, say G12345. As far as I know, that’s not a legal G-code. But you can define a macro named G12345 and make it do whatever you want. You can also define macros for real G-codes if you want. So, defining G28 would allow you to take over how the printer homes itself.

You can also have a macro named HACKADAY_LOGO or FILAMENT_CHANGE and stick those in your G code to make Klipper do anything you want. You can even do programming language constructions like for loops and if/then/else in your macros.

Klipper is almost completely concerned with reading input codes and spitting out basic movements. A lot of system management falls to Moonraker, which talks to Klipper for you and communicates with the Web, MQTT, Home Automation, and more. A configuration file is also used to set up Moonraker. So for example, if you want a text message when your print is complete, Moonraker can do that. It also can keep your system up to date.

User Interfaces

It also communicates with user interfaces. For example, if you have a touch screen, it also talks to the system via Moonraker. However, the user interface is usually a web browser viewing pages provided by Fluidd or Mainsail. In fact, you can run both on different ports and use either one you like at any time. The browser doesn’t have to be on the machine you have Klipper on, by the way. In that way, it is like OctoPrint, which you can also use if you like.

OctoPrint has many features but can be heavy to run. For whatever reason, most people seem to run Fluidd or Mainsail, even though it is possible to use OctoPrint and benefit from its many plugins and features. Moonraker can even be made to mimic OctoPrint — so slicers that know how to send jobs to Octoprint can also send jobs to Klipper.

Here’s a look at part of Fluidd’s main page (you can, of course, configure and theme it):

The Next Trick… Juggling!

I mentioned earlier that Klipper can control multiple boards. Some new bed sensors, for example, are their own computers, and Klipper can talk to them directly.

For another example. Suppose you have a board with lots of stepper drivers, and you decide to build a printer with four extruders. Later, you decide you want filament run-out sensors for each one, but your board doesn’t have enough input ports. No problem! Just get a second cheap board, flash it with the stub firmware, and tell Klipper about it. There’s no reason those sensors have to be on the same board as the other electronics. If you are running on a Raspberry Pi, there may be times when you want the Pi to not only run the main Klipper code but also host I/O devices, and that’s the function of that bottom block.

Next Steps

In the next installment, I’ll tell you more about how you can get started and a few things to look out for. If you already use Klipper, let us know your favorite tricks in the comments.

We covered Klipper way back in 2017, and it has come a long way since then. Of course, there are other ways to speed up your 3D prints.