Article in Progress
So you have chosen Klipper (or Kalico)! Installation is easy, getting it running can vary. While you have other choices, the Raspberry Pi is the most widely supported device. We will be covering 2 very common choices. In this article we will cover installing MainsailOS using the RasPi Imager which will give us a complete working installation out of the box. The alternative is using KIUAH which is an extra step but worth learning as well.
RasPi Imager
Download for WIndows, MacOS, or Debian/Ubuntu here - https://www.raspberrypi.com/software/
Set your Raspberry Pi device, we typically use a 3 or 4. Then choose the operating system. In this case go to Other specific-purpose OS, 3D printing, Mainsail OS. Then select the microSD card you intend to flash.
You will be asked if you wish to edit settings. You should take this opportunity to set a hostname, this is what you will type into your browser to upload prints and manage the printer. I typically recommend leaving the default login but in the name of network security you should probably set your own. Don't forget this as you will use it a few times a year. Then set your Wifi as desired.
Flashing and verifying the SD card will probably take awhile but once it is done insert it into the Raspberry Pi and power it on and be prepared to wait some more.
Hello Mainsail!
If the pi successfully connects to your network you will eventually be able to see the web interface by navigating to the hostname you chose. In my case replicator.local. If you are too early you may see some additional errors, sometimes rebooting the host also solves problems. But you should be greeted with this error.
This error tells us we haven't supplied a config yet. We can go ahead and do that but we will have to come back and add our unique board identifier before it will work. Navigate to machine and then create a new file called printer.cfg by clicking on the button with the file+ logo. Then paste the premade config for your printer if you have one.
After saving and restarting we will see this message followed by this error.
This error will occur for a few reasons starting with we haven't actually compiled and flashed the firmware to the printer! But also if the USB cable isn't connected or the "serial: /dev/serial/by-id/" hasn't been edited to the correct id which we will do after flashing the printer.
Compiling
Klipper firmware is compiled for the board, rather than the printer. As such each printer or board you will be compiling for needs specific settings. Refer to the guide for your printer at this point in time. I will for the sake of completeness show the process for the Replicator, these settings are common to Arduino Mega 2560 boards and would actually apply to several older printers.
First step is to login to the Pi using an SSH client. There are many choices but the classic solution is Putty.
Login with your username and password, the default is pi and raspberry
We will run the following commands to stop the klipper service and bring up the configuration for compiling firmware.
We will be greeted by this which if you happen to be flashing an Arduino Mega 2560 board then your options are already set. However for the Replicator we are actually using a 1280 so i will change
We will then hit Q to exit and save and Y for yes.
Then type the Make command. You will see a whole lot of activity ending with this:
We need to flash this file to our printer. In some cases like an Ultimaker Original with a Mega 2560 or a few printers with a Rambo we can do this with the Make Flash command but in many cases we will need to move this file off the pi for flashing with another method or in the case of modern printers often using a microsd card.
If you are linux savy this is no big deal but here is a trick for the beginners. We will move this file to a folder mainsail can see and then download it from there.
Run the following command while still in the /klipper folder we did our previous work in, if your user is not pi change that username in the command:
mv out/klipper.elf.hex /home/pi/printer_data/config/klipper.elf.hex
Then go back to the browser under machine and the hex file should now be there. Check the box and you will get the blue download button. You should now have the file on your local machine for use with the flashing instructions relevant to your printer.
Flashing
This is another area specific to the printer/board in question. But we will discuss the most common methods. After flashing the firmware any LCD screen you might have on the printer may not initially work. It's scary but its also usually a sign the board no longer has Marlin on it. The screen will work if properly configured in printer.cfg once Klipper successfully connects.
The method of flashing your board will likely be exactly the same as you would with Marlin using a premade hex file if you happen to be familiar with flashing your machine. Otherwise these are the most common methods:
USB - Many arduino based boards can be flashed over USB. Our example Replicator could be flashed over USB but it is a difficult task of timing the reset button. The Ultimaker Original is an example of board we can flash directly from the Pi after the make command using make flash.
MicroSD - Many modern aftermarket boards are flashed over MicroSD. You may need to name the file a specific name or even a unique name each time you flash it.
ICSP - Older 8 bit boards without a bootloader or USB flashing method or ones that are just a pain can often be flashed directly over ICSP using something like an Arduino UNO and avrdude. I prefer this method for the Replicator.
UART - Some modern aftermarket boards can be flashed over uart saving the need for opening up the machine which is useful for updates.
Dont forget to restart Klipper
Updating Device ID
After supplying a config and flashing the board we should still be seeing an error for MCU unable to connect. Run the following command in SSH on the Pi.
ls /dev/serial/by-id/*
If the USB cable is connected and the board is powered you should get a response similar to this:
Your example config might have a similar but incorrect value as these are typically unique.
After updating the value then saving and restarting the printer should come to life. If not sometimes the baud rate may need to change. This step not working can easily be the most frustrating for beginners.
After succesfully connecting you will probably see this message:
Your printers example config doesn't usually include the file for your choice of Klipper web interface as you have more than one choice. Since we installed mainsailos we will need to include mainsail.cfg like below:
If you are still having trouble feel free to comment on the article for your printer or jump into discord so someone can help you.
So you have chosen Klipper (or Kalico)! Installation is easy, getting it running can vary. While you have other choices, the Raspberry Pi is the most widely supported device. We will be covering 2 very common choices. In this article we will cover installing MainsailOS using the RasPi Imager which will give us a complete working installation out of the box. The alternative is using KIUAH which is an extra step but worth learning as well.
RasPi Imager
Download for WIndows, MacOS, or Debian/Ubuntu here - https://www.raspberrypi.com/software/
Set your Raspberry Pi device, we typically use a 3 or 4. Then choose the operating system. In this case go to Other specific-purpose OS, 3D printing, Mainsail OS. Then select the microSD card you intend to flash.
You will be asked if you wish to edit settings. You should take this opportunity to set a hostname, this is what you will type into your browser to upload prints and manage the printer. I typically recommend leaving the default login but in the name of network security you should probably set your own. Don't forget this as you will use it a few times a year. Then set your Wifi as desired.
Flashing and verifying the SD card will probably take awhile but once it is done insert it into the Raspberry Pi and power it on and be prepared to wait some more.
Hello Mainsail!
If the pi successfully connects to your network you will eventually be able to see the web interface by navigating to the hostname you chose. In my case replicator.local. If you are too early you may see some additional errors, sometimes rebooting the host also solves problems. But you should be greeted with this error.
This error tells us we haven't supplied a config yet. We can go ahead and do that but we will have to come back and add our unique board identifier before it will work. Navigate to machine and then create a new file called printer.cfg by clicking on the button with the file+ logo. Then paste the premade config for your printer if you have one.
After saving and restarting we will see this message followed by this error.
This error will occur for a few reasons starting with we haven't actually compiled and flashed the firmware to the printer! But also if the USB cable isn't connected or the "serial: /dev/serial/by-id/" hasn't been edited to the correct id which we will do after flashing the printer.
Compiling
Klipper firmware is compiled for the board, rather than the printer. As such each printer or board you will be compiling for needs specific settings. Refer to the guide for your printer at this point in time. I will for the sake of completeness show the process for the Replicator, these settings are common to Arduino Mega 2560 boards and would actually apply to several older printers.
First step is to login to the Pi using an SSH client. There are many choices but the classic solution is Putty.
Login with your username and password, the default is pi and raspberry
We will run the following commands to stop the klipper service and bring up the configuration for compiling firmware.
We will be greeted by this which if you happen to be flashing an Arduino Mega 2560 board then your options are already set. However for the Replicator we are actually using a 1280 so i will change
We will then hit Q to exit and save and Y for yes.
Then type the Make command. You will see a whole lot of activity ending with this:
We need to flash this file to our printer. In some cases like an Ultimaker Original with a Mega 2560 or a few printers with a Rambo we can do this with the Make Flash command but in many cases we will need to move this file off the pi for flashing with another method or in the case of modern printers often using a microsd card.
If you are linux savy this is no big deal but here is a trick for the beginners. We will move this file to a folder mainsail can see and then download it from there.
Run the following command while still in the /klipper folder we did our previous work in, if your user is not pi change that username in the command:
mv out/klipper.elf.hex /home/pi/printer_data/config/klipper.elf.hex
Then go back to the browser under machine and the hex file should now be there. Check the box and you will get the blue download button. You should now have the file on your local machine for use with the flashing instructions relevant to your printer.
Flashing
This is another area specific to the printer/board in question. But we will discuss the most common methods. After flashing the firmware any LCD screen you might have on the printer may not initially work. It's scary but its also usually a sign the board no longer has Marlin on it. The screen will work if properly configured in printer.cfg once Klipper successfully connects.
The method of flashing your board will likely be exactly the same as you would with Marlin using a premade hex file if you happen to be familiar with flashing your machine. Otherwise these are the most common methods:
USB - Many arduino based boards can be flashed over USB. Our example Replicator could be flashed over USB but it is a difficult task of timing the reset button. The Ultimaker Original is an example of board we can flash directly from the Pi after the make command using make flash.
MicroSD - Many modern aftermarket boards are flashed over MicroSD. You may need to name the file a specific name or even a unique name each time you flash it.
ICSP - Older 8 bit boards without a bootloader or USB flashing method or ones that are just a pain can often be flashed directly over ICSP using something like an Arduino UNO and avrdude. I prefer this method for the Replicator.
UART - Some modern aftermarket boards can be flashed over uart saving the need for opening up the machine which is useful for updates.
Dont forget to restart Klipper
Updating Device ID
After supplying a config and flashing the board we should still be seeing an error for MCU unable to connect. Run the following command in SSH on the Pi.
ls /dev/serial/by-id/*
If the USB cable is connected and the board is powered you should get a response similar to this:
Your example config might have a similar but incorrect value as these are typically unique.
After updating the value then saving and restarting the printer should come to life. If not sometimes the baud rate may need to change. This step not working can easily be the most frustrating for beginners.
After succesfully connecting you will probably see this message:
Your printers example config doesn't usually include the file for your choice of Klipper web interface as you have more than one choice. Since we installed mainsailos we will need to include mainsail.cfg like below:
If you are still having trouble feel free to comment on the article for your printer or jump into discord so someone can help you.
Last edited: