Installing Klipper with KIAUH

Knowledge Base
1

Preface

The official installation instructions use Octoprint as a control interface. Nowadays, most setups involve Moonraker and fluidd / Mainsail as the primary ways to interact and control a Klipper printer.
The manual configuration of these components is quite involved, so this article will employ KIAUH, a superb shell script that conveniently handles the initial setup process.
This guide will only cover the basic setup, but there is a lot more to discover.

Content

  1. Preface

  2. Initial Considerations

  3. Prepare the Host

    1. Setting up the SD Card
    2. Completing the RPi OS Setup
    3. OS Sanity Checks and Fixes
    4. Accessing the RPi via SSH

  4. Install the Klipper Ecosystem

    1. Install and Run KIAUH
    2. Install Klipper and Associated Products
    3. Build and Flash the Firmware

  5. Configuring Klipper

    1. Initial Configuration
    2. Verify Basic Functionality

  6. Troubleshooting

  7. Fine Tuning and Finishing Touches

Initial Considerations

For better understanding, some background information:

  • Klipper requires a constant and stable connection between a host process running on a personal computer and the printer board. It is common to use Single Board Computers (SBC) such as the Raspberry Pi, but any current SBC will do the job. See Other Single Board Computers (SBC) apart from Raspberry Pis for more details.

  • The Klipper concept includes several interdependent and interacting products. To gain an understanding of the system, refer to Klipper Architecture / Ecosystem.

  • Some hardware, especially displays, may not have full support from Klipper. It is advisable to carefully examine the configuration files for a particular printer model to ensure that all hardware is compatible. For instance, the absence of a [display] section in a file strongly suggests that the printer’s stock display is not currently supported.

Prepare The Host

On the host computer, a Linux operating system must be running.

  • This guide will assume the use of a Raspberry Pi (RPi).

  • If setting up a different SBC, the approach must be tailored accordingly.

    • For example the popular Armbian distributions offer a comparable approach by using armbian-config as opposed to raspi-config (see below)
    • If you are installing another Linux distribution, in any case, check OS Sanity Checks and Fixes

  • For Raspberry Pi it might be preferable to use 32bit versions, especially when using CAN setups (there are reports of issues with CAN and 64bit Kernels).

Setting up the SD Card

  1. Get, install and run the Raspberry Pi Imager

  2. Choose the proper OS you want to use. Popular choices are

    • Mainsail OS (Other specific-purpose OS → 3D Printing → Mainsail OS)
      Mainsail OS comes with Klipper / Mainsail preinstalled, so you can skip installing them later
    • Raspberry Pi OS lite

  3. With the Pi_Img_Settings symbol, some settings can be baked into the image that can make the setup easier:

    RPI_Advanced_options_scaled
    RPI_Advanced_options_scaled595Ă—742 48.8 KB

  4. Prepare the SD card and proceed to boot the RPi with it. It is advisable to connect the RPi to a monitor and keyboard. Some distributions require manual intervention to complete the setup process.

Completing the RPi OS Setup

  1. Run sudo raspi-config

    • 1 System Options → S1 Wireless LAN → Follow the WIFI setup (skip for using Ethernet)
    • 3 Interface Options → I2 SSH → Enable yes
    • 3 Interface Options → I4 SPI → Enable yes
    • 3 Interface Options → I5 I2C → Enable yes
    • 6 Advanced Options → A1 Expand Filesystem

  2. Get the IP address of the RPi and write it down. To accomplish this, execute the following command:

    hostname -I

  3. Make sure your Linux is updated to the current state. Run

    sudo apt update
sudo apt upgrade

  4. Reboot via

    sudo reboot now

OS Sanity Checks and Fixes

This is applicable not only to RPi, but to any Linux OS:

Accessing the RPi via SSH

Usually, a monitor is not connected to the RPi and administration is executed “headless” using SSH. In the previous step, the SSH server was enabled, so this access should now work with either the configured or default username, password, and IP address.
After the initial setup is completed, most tasks can get done using the web-based interfaces. Familiarity with these tools, especially when troubleshooting, is strongly recommended.

Common tools to work with SSH are:

  • Windows

  • macOS

  • Linux typically has the options on board already, e.g. in Nautilus, Thunar, Konqueror and the Terminal app.

Install the Klipper Ecosystem

This chapter outlines the steps necessary to perform a basic setup of Klipper with KIAUH.

Install and Run KIAUH

Run the following commands:

sudo apt-get install git -y
cd ~ 
git clone https://github.com/dw-0/kiauh.git
./kiauh/kiauh.sh

Install Klipper and Associated Products

In KIAUH follow this simple sequence:

  1. Choose 1) [Install]

  2. Choose 1) [Klipper]

    • Choose Python 3
    • Choose the number of instances. Typically 1, unless you want to run more than one printer off the same host SBC
    • Answer any question about missing group membership with Yes

  3. Followed by 2) [Moonraker]

  4. Install the web-interface of your choice: 3) [Mainsail] and / or 4) [Fluidd]

    • Installing both is possible
    • The first one installed will be accessible via port 80, the second one via the port given during installation, e.g. 81
    • Confirm questions about downloading any macro files.

  5. Hit B to go back to main menu

  6. On your main personal computer, use your browser to navigate to

    http://the_IP_you_noted_earlier/

    to access the web-interface for the first time

  7. Download the appropriate configuration file for your printer / printer-board (screenshots from fluidd)

    • Move to Configuration (Machine in Mainsail) in the left-hand side menu
      fluidd1
    • Choose Other Files → Config_Examples (Drop-down in Mainsail)
      fluidd 2
    • Select the matching printer model or board, right click and select Download
      fluidd3

  8. Open the downloaded file in a proper editor, e.g. Notepad++ (Windows only) or Sublime Text (also macOS)

Build and Flash the Firmware

In the previous step, the installation of the host components on the SBC was completed. The next task is to build and flash the firmware component on the printer-boards.

  1. Carefully review the initial lines of the configuration file downloaded in the preceding step, as it contains important information.

    • It provides instructions on how to build the firmware and which build settings to choose
    • Information how to install it on the Printer-Board

  2. To build the firmware, select 4) [Advanced] and then 2) [Build only] in KIAUH.

  3. Enter the information from the configuration file in the screen that appears. To establish a connection to the board later on, it is crucial to adhere to all settings.

    • Complete the setup by selecting Q to confirm and save the settings.

  4. The firmware file will be generated at ~/klipper/out/klipper.bin. Flash the board based on the instructions provided in the configuration file.

    • The flashing functions in KIAUH under 4) [Advanced] can be used as well, but for the first time setup, the manual approach is recommended
    • If the instructions call for a specific flashing command, the command
      ls /dev/serial/by-id/*
      will provide the required target address
    • The most common command to flash the board is (also used if no other specific command is mentioned in the configuration file):
      sudo service klipper stop
make flash FLASH_DEVICE=<the_complete_target_address_from_above>
sudo service klipper start
    • If the instructions call for copying the bin-file to the SD card, tools like the above-mentioned WinSCP can be used. Only copy and potentially rename the klipper.bin to a SD card, not the entire folder

Configuring Klipper

Initial Configuration

  1. In KIAUH call 4) [Advanced] and then 5) [Get MCU ID] or run the command

    ls /dev/serial/by-id/*

    in the shell.

  2. Copy the complete path as displayed, e.g.

    /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0

  3. Paste the copied address into the configuration file that has been downloaded and opened in a editor above. It should then look like:

     [mcu]
 serial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0

  4. Also add the web interface specific macro to the configuration file. This can either be fluidd.cfg or mainsail.cfg depending on the web interface that is used. The config shall then include a section like

    [include fluidd.cfg] # Alternatively: [include mainsail.cfg]
    • Do not add both. One of them is sufficient for both web interfaces
    • Note that this file contains macro definitions for CANCEL_PRINT, PAUSE, RESUME etc. Avoid adding duplicate definitions anywhere else in the configuration files.
    • For further information, refer to Mainsail Configuration

  5. Save the adapted configuration as printer.cfg

  6. Upload the printer.cfg via the Configuration section in the web interface (Mainsail dropdown → config). The default path on OS level is ~/printer_data/config
    grafik

  7. Restart Klipper either via the web interface or via issuing the command sudo systemctl restart klipper

Verify Basic Functionality

With the above steps, the basic setup is completed and the web interface should show the temperatures of the bed and extruder and not display any errors.

The following step should now be performed to ensure a proper basic functionality: Configuration Checks and, if using a BLTouch (or clone), its Initial Tests.

Troubleshooting

If there are any problems or error messages at the end of this simple installation process, it is time to troubleshoot your installation.

  • Carefully work through How-To Trouble-Shoot and check About the Knowledge Base category / Table of Contents. Almost all typical errors are covered there

  • Reviewing the klippy.log file is necessary for all troubleshooting purposes. On the web interfaces, it’s easy to access or download and is prominently displayed on the home or dashboard page if there are any errors.

    grafik

  • If you encounter unanticipated or irregular behavior, the klippy.log can also be a helpful resource. It is always accessible via the navigation bar on the left side of the screen under Configuration (fluidd) or Machine (Mainsail).

  • If you require aid, attach the klippy.log to your post at all times. Posts without the log will not receive a response. Use any compression tool like zip if the file is too big to attach.

Fine Tuning and Finishing Touches

The following steps are optional but will enhance the printing experience and quality:

  1. Check and adjust potentially twisted X axis (requires a probe)

  2. Perform bed_leveling

  3. Create a bed_mesh (requires a probe)

  4. Compensate for detrimental resonances (requires an Inertial Measurement Unit for the automatic process)

  5. Calibrate the extruder’s rotation_distance

  6. Dial in Pressure Advance for your filaments

7 Likes