Foreword

First and foremost, this is a work in progress and is incomplete, pull requests and feedback welcome.
The source repository can be found at https://github.com/Scopeuk/3dPrintingNotes

This document aims to help a new user understand the commands they are likely to encounter in setup guides or similar, it necessarily skips over some elements of detail and nuance in favour of clarity. The intention of this document is not to replace existing guides to instalation or update of klipper, that subject has been covered extensively and well elsewhere. This document aims to let someone unfamiliar with linux understand what the commands given in guides do as an aid to trouble shooting and to give confidence. This is not intended to be a be all and end all guide to any of these commands. As part of the shortcuts taken to make this accessible guidance around system commands and application installation will focus on tools used by debian and it's derivatives (ubunutu, raspberry pi os etc) as these are the most commonly used distributions for new users.

Current Sections

Linux For Klipper Users
Finding Information
Klipper Pin Configurations
Reading Klipper Configuration Files
Sensorless Homing
Numpy Errors
Additional Useful Links

Structure of Commands

Running a Command

Commands are in the format below where command is the name of a command, parameter_1, parameter_2 and parameter_3 are parameters or arguments passed to the command command parameter_1 parameter_2 parameter_3

• All commands are executed in the current folder
• Commands can take any number of parameters 0 or more which change their behaviour
  Examples:
  • ls lists the current folder the command is ls
  • ls /home lists the /home directory the command is ls again but this time we also have a parameter /home, Many commands will take a path or file as a parameter to instruct the command which item to work from.
    Parameters can also modify command behaviour.
  • ls -l the command is ls but we give an argument -l in this case ls will list extra details
  • ls /dev/serial/by-id/* This is a fairly common command during initial setup for a klipper machine, the command is ls and the parameter is /dev/serial/by-id/*. /dev/serial/by-id/* is a special directory on the linux file system which contains a file for each serial device connected with a name reflecting what the operating system calls it see Block Devices
• Parameters may also be refered to arguments or switches. Switch is normally used for parameters of the form -x or --help which change the command behaviour

Escaping a Running command

In the event you open a command which doesn’t close itself (or runs for a long time) the command can be instructed to stop with the keyboard combination ctrl + c

Case Sensitivity

All linux commands and folder names are case sensitive, this means that file, File and FiLe are all different files and could be in the same directory, as this is for obvious reasons confusing people avoid names like this. This is of note because whilst ls will list the files in the current directory LS or Ls will result in a command not found error.

Tab Completion

Whilst using the terminal it is possible to ask for your current command or command part to be finished for you. This is helpful with say long file names where you can type the first two or three letters and then press tab to complete the full name, if there are multiple options hitting tab twice will list all of them. This does not work with all commands but does work with almost all file commands and service commands.

Sudo

The sudo command is a powerful utility command which is used to perform tasks with elevated permissions, roughly analogous to run as administrator functionality on windows. sudo does not do anything directly but instead runs the command in its parameters under the "root" user, the top level administrator account for a linux machine. Typically the sudo command is needed when installing or updating tools, changing configuration files for the operating system or controlling services.

Example

Running whoami will return your username Running sudo whoami will return the username root as the command has been run as the root user.

Command Chaining

Many commands in guides will chain commands, this is the process of writing a single line which executes multiple commands. Most of these depend on the "return value" of the commands as they execute, the finer points of what these means is beyond this guide, for our purposes each command reports if it succeeded or failed and the joins can check this there are multiple ways to do this but the most common are below

Examples

cd ~ && git clone https://github.com/dw-0/kiauh.git run the command cd ~ and if that is successful then run the command git clone https://github.com/dw-0/kiauh.git

Finding Help

Help Parameters

Most commands supply a help option usually this is --help or -h as a parameter e.g. ls --help

Man Command

man is the manual command, man is a command which accesses documentation for other commands, these manual pages can be very verbose and technical but likely include all the detail you could need if doing something unusual Example

• man ls this will launch the manual tool pointed at the entry for the ls command

Finding your way around the file system

Assuming you have found your way into a terminal via ssh or the device itself the following commands should help with moving between folders or identifying where you are
included here are also the comands for moving, copying and renaming files

Magic symbols

Commands

common usage

cd .. move up one folder i.e. from /home/me to /home
cd ~/klipper move to the folder called klipper in the users home directory, frequently this is where klipper is installed by most people
mv out/klipper.bin out/firmware.bin rename the generated firmware image from klipper.bin to firmware.bin, here the comand is assumed to be running from ~/klipper as this is where the firmware build commands normally run from

Git

Git is a version control system, these are likely unfamiliar terms but for most of our usage this means that the git command can be used to make a copy of a folder from a git repository (like the one klipper is held in https://github.com/Klipper3d/klipper) or update the files in a repository we previously copied. The tool will track files it is made aware of and allow for copies of the "repository" or collection of files to be made and for any changes to be kept in sync, this is how updates made through mainsail or fluid work in the background.
Git is a complex tool and can produce errors or issues which will need different resolutions, this is rare when using commands such as clone or creating an initial installation.
A "cheat sheet" for many git commands is available at https://training.github.com/downloads/github-git-cheat-sheet/ and full details are available online. One good resource for further reading is https://glasskube.dev/guides/git/. Full usage of git is outside of the scope of this documentation.

The git command works like other commands documented above although the first parameter passed to git is normally an instruction for the type of action to be undertaken.
In the next few sections we explore a few commonly used git commands

git clone

This command is used to get a copy of a repository held in git a in the current working folder, most commonly this is used to get klipper(https://github.com/Klipper3d/klipper) or KIAUH (https://github.com/dw-0/kiauh) during an initial installation.

Example command

git clone https://github.com/dw-0/kiauh.git This command breaks down into three parts, git the command we want to run clone the operation we want to perform and https://github.com/dw-0/kiauh.git this tells git clone where to get the files it should clone. This will create a folder with the repository name kiauh (the last bit after / and before .git) in the current working directory. Additional parameters can be passed to the clone command to tweak its behaviour, these are rarely needed in our use case.

git pull

This command must be run inside a directory which git created (usually in our case through a git clone command). It will update the local files in the folder to match the latest version it was cloned from.

Example command

git pull This command breaks down as run git with an instruction to pull the latest version of the parent repository. git will then check for changes between your local files and the parent and try to update the files, in the event there is a conflict (a file modified differently both locally and in the parent repository) git will attempt to resolve the issue or if this fail will ask you what to do. It is rate for klipper users to directly perform this operation and it is more typically invoked via one of the klipper web interfaces like Fluid or Mainsail.

Installing tools (apt-get)

The apt and apt-get commands allow for tools and their dependencies to be installed and maintained by the operating system. This can be considered to be a little like an app store in how it behaves apt and apt-get are two different interfaces to the same tooling, apt is the more modern version but frequently apt-get os called for in example commands. we will document apt-get here for this reason. all commands in this section will require "admin" permissions to run successfully, this is done by starting the command with the sudo, super user do command see sudo

apt-get works like other commands documented above although the first parameter passed to apt-get is normally an instruction for the type of action to be undertaken.

apt-get update

The command apt-get update will update the locally stored index of what tools are available and at what version, it does not make any changes to the installed files

apt-get upgrade

The command apt-get upgrade will update the tools installed and tracked by apt-get (including most of the pre-installed applications) to the latest version in the local database (see apt-get update ) This command will note upgrade code operating system features

apt-get dist-upgrade

The command apt-get dist-upgrade is much like the apt-get upgrade command but it will also update the underlying core operating system files

apt-get install

The command apt-get install is used to install a new tool or library. install accepts a -y switch which will make it automatically answer yes to questions to the user. The most frequent question posed by this tool is "installing this tool will require 30MB of disk space, continue?" so it is frequently added in installation guides.

examples

apt vs apt-get

apt is the replacement for apt-get, for install/remove/upgrade commands the user visible behaviour is the same, there are some subtleties to what is going on inside the black box. AWS have a good write up on the finer details https://aws.amazon.com/compare/the-difference-between-apt-and-apt-get/. It is expected for the foreseeable further both will be available.

Commands which end in .sh

These are not strictly commands but are instead scripts, scripts are a series of commands which automate tasks for you, commonly tools which we install from git such as Kiauh or Klipper itself provide scripts to simplify initial setup. Commonly these commands will have the form ./toolname/script.sh this is running a script called script.sh which is located in a folder called toolname under the current working folder.

Example

Below we have an example of a sequence from the Kiauh install script First move to the home directory (~) and then git is used to get Kiauh into the folder kiauh cd ~ && git clone https://github.com/dw-0/kiauh.git And then run a script that is in that folder ./kiauh/kiauh.sh This runs the script by starting in the current folder . then folder kiauh then a script called kiauh.sh, this assumes that the user is still in the directory ~ from the cd command above A common error to see with script launch commands is to try and launch the command whilst in the wrong directory, look carefully at any instructions for any cd commands.

Where is my hardware

Block Devices

The linux operating system maps all hardware devices are files, this may seem a little odd if you are used to how windows handles devices, it is not necessary to understand why this is the case or the advantages or disadvantages here. This affords some advantages in our use case. The underlying hardware handling on modern linux distribution is performed by a tool called udev. This uses a series of rules to create device files on the disk. All very confusing and "technical" but for us this means that a printer connected by a usb port will appear in the directory /dev/serial/by-id/ and look like a file. We can therefore use the ls command to look for printers, due to the magic of udev these will even frequently have helpful names including klipper or marlin in the device names. This is helpful to us as these names remain attached to a single serial device, particuatly with usb serial devices the ports can be renamed in their "raw" form of /dev/usbTTY0, /dev/usbTTY1 and simlar depending on the order in which they are detected.

Useful Commands

Services

Like all operating systems linux uses background services to provide functionality which runs at boot up. In common use with klipper instalations there are a handful of services which we might interact with. On most modern linux discributions, including all common klipper host options services are managed through systemd. The finer details of what all of this means and how it works is not too important however commands come up for starting and stopping services so these are recorded below Most control of the services are done through the systemctl command

Why?

These commands are not used in normal operation but can be helpful if a machine is not starting properly or during firmware flashing. A common use case is to stop the klipper service so that a firmware update tool can talk to the serial port used by the control board during an mcu firmware update.

General Structure

systemctl commands are generally structured as systemctl instruction service where

Instructions

This is an incomplete list of instructions for systemd and only aims to cover the main options in common use.

Service Names

Example Systemd Commands

Notes here are focused around setting up boards with Klipper, the process for Marlin is similar but frequently requires translating from device pins to wiring pins, this is not described here.
This page links out to a handful of manufacturer pages. These are listed as they are known to be widely used. There is no recommendation for or against anything by inclusion or exclusion from this list. If you have something you would like to add raise a PR or issue.

Klipper Repository

The Klipper repository contains a large set of example configurations, these cover configurations for a large number of printers as well as many common printer control boards. https://github.com/Klipper3d/klipper/tree/master/config

Manufacturer Github Repositories

Usually most easily found by using your search engine of choice to look for the name of your control board and the keyword github
As an example Skr mini e3 v3 https://www.google.com/search?q=skr+mini+e3+v3+github

Some manufactures are listed below for quick reference:
Big Tree Tech
https://github.com/bigtreetech?tab=repositories

Mellow
https://github.com/orgs/Mellow-3D/repositories

MakerBase(MKS)
https://github.com/makerbase-mks?tab=repositories

FYSETC
https://github.com/orgs/FYSETC/repositories

Every manufacturer lays out these repositories differently. Frequently there will be a repository for each board they supply. Inside that repository are a series of folders, typically you want to look for a pinout or pin diagram, this will list all of the pin names and what they are connected to.
This is frequently but not always to be found in a folder called hardware.

Some manufacturers will also supply basic Klipper configuration files for their boards on github.

Manufacturer Website

Some manufacturers (notably Mellow) also maintain documentation on their own website. Sometimes this information is ahead of the github particularly for very new products. There is no standardisation around how this information is laid out.

Mellow wiki
https://mellow.klipper.cn/#/README

Big Tree wiki
https://bttwiki.com/

Layout of Pin Diagrams

These Diagrams frequently consist of a series of tables around a picture or render of the board. Each table will match with either a specific connector or list of a series of similar components, a single table for all the stepper drivers is common.

These tables map pin names as used by Klipper to functions of the board like stepper enable, stepper direction or thermistor input.
Unfortunately not all of these diagrams are in a standardised format so some level of effort may have to be applied to understanding the diagram. Frequently the Klipper Repository will have an example configuration for a board which has all of this information converted to Klipper format. It is advised to double check any configuration file taken from the internet before use.

Board Versions, A Word of Caution

Many manufactures issue revisions to boards throughout their lifetime, sometimes these updates can change which pins are used for certain features. When looking up a board make sure to carefully check the silkscreen (the text printed on the board) for any version markings, this will frequently be in the format V1.2 or similar near the board name.

This section aims to provide additional clarity or expansion of https://www.klipper3d.org/Config_Reference.html#format-of-micro-controller-pin-names this does not replace the klipper documentation but augments it and expands upon reasoning.

Pin Names

Pinnames are specific to the controler in use, typically they are in one of a handful of formats and depend on the type of microcontroler used on the control board. The format is not itself important but must match the defintions used for your control board.
A few common formats are listed below:
PB1 - Two letters followed by a number in this case Port B Pin 1. This is common on STM32 and AVR based controlers.
P1.1 - Port 1 Pin 1. This is common on LPC based controlers.
gpio1 - gpio followed by a number. This is common on RP2040 based controlers and raspberry pi mcu.

If any of this is confusing or intimindating, ignore it. The steps needed to get this working are setting the name to match what the manufacuter documentation states, what it all means is unimportant. Some help on where to look for this information is avaliable in Finding Information

Modifiers

Modifiers are added to a pin name in a configuration to change how the pin behaves

Inverting Pins

Many devices on a 3d printer controler use boolean, true and false signals which map to on or off on a pin on the micro controler,
The chips which recived this signal (for instance stepper drivers) assign specific meaning to on and to off. Inverting the pin lets us map klippers idea of what is on to the same thing the chip expects. Frequently this is used with the direction pin on a stepper driver, if on makes the motor rotate clockwise, off will make it rotate counter clockwise.

Normal: pin1

Inverted: !pin1

This changes the signal recieved by external hardware but not how the software see's the world. This is particularly useful for devices which use "active low" signals, this is very common and simply means that the pin being "off" will make the device run. Stepper driver enable signals are frequently active low This can also be used on input pins, this is commonly done for "normally open" endstops to make them false when not pressed and true when pressed.

Why use pull resistors?

This section talks about a pull up resistor as this is by far the most common.
Think about a common endstop circuit, this has a switch which connects ground to a pin of the micro controler on the printer control board.

This switch can make a circuit connecting the pin to ground or it can break the circuit. This might seam to give us both on and off, but what we actually have is off (pin connected to ground) and unknown, when there is no circuit there is nothing to make the pin on.
The pull up resistor is part of the micro controler on the printer control board which connects the pin to a resistor connected to the on voltage.

This resistor will mean that when we break the circuit the pin goes to on, but as this is a faily high resistance if we add a low resistance connection to ground (press the switch) the pin will go to off. This gives us our off (switch and circuit connected) and on (switch and circuit disconnected, resistor pulls to on instead).

Pull Up Resistors

When the pin is not connected this will make the pin go to on. All klipper controlers support pull up resistors

Pull Down Resistors

When the pin is not connected this will make the pin go to off. Support for pull down resistors is limited. It is much more common to use pull up.

Combing Modifiers

The ! modifier can be combined with either ^ or ~ on an input pin (one taking information from the world like an end stop switch). adding both ^! or ~! will cause both effects to happen. When combining operators the order is pull (up or down, ^ or ~) and then the inversion operator !.

Getting Started With printer.cfg

Klipper configuration files can appear to be intimidating at a first attempt. The files however are laid out in sections with each section self-contained. As such the sections can be dealt with one at a time and it is not necessary to understand everything to get started. This is not aimed at walking you through creating a configuration file from scratch but acts a guide to how to read an existing file and the details of what each section does.

Before We Start

Changes to your printer.cfg file can stop your printer working, before making any changes take a backup copy of the file. In the worst case you can always swap back to the backup.

What is printer.cfg

printer.cfg is the configuration file Klipper reads when it first starts. This configuration file tells Klipper how your printer is configured. This is how Klipper can tell apart an Ender 3 and a Voron 2.4 (although Klipper really doesn’t care). It is responsible for documenting the physical configuration of the machine, for instance it's dimensions and kinematics, electrical setup like the type of stepper drivers used and how they are wired up on the controls board, and finally any Klipper settings like arc support or the virtual sd card.

CASE SeNsItIvItY

All Klipper configuration files are case sensitive. What this means is that all of the following names are different.
test
Test
TEST
TeSt
This can be a little tricky as in normal English these are all the same word. The whats and whys of this are unimportant, just make sure it matches and you'll be fine.

Comments

Klipper configuration files allow for "comments" these are bits of text put in for the benefit of the humans reading the file.
Comment lines start with # everything after # is ignored by Klipper.
There is one special case exception to this SAVE_CONFIG.
This is used extensivly within the Klipper configuration reference where the details of each parameter are documented in comments, these can be included in your printer configuration along with any of your own notes to help you understand.

File Structure

The general structure of a printer.cfg file will be some lines starting [include. see Include Lines
followed by a series of series of sections which start with [section name]. see Configuration Sections
A line in the form
#*# <---------------------- SAVE_CONFIG ---------------------->
A series of lines startin with #*# . see SAVE_CONFIG

Include Lines

A line starting [include is being used to "include" another configuration file. Effectively what this does is add the included file at this point in the current file.
An example include
[include anExtraFile.cfg]

So what does this do?
This is equivalent to copying the whole contents of anExtraFile.cfg into our printer.cfg starting at this line.

Why would you do this?
This may seem like just complexity for the sake of it however this is a powerful way to allow us to separate out infrequently used functionality or functionally which is grouped together. Everyone uses this differently, just know that if there is an [include fileName.cfg] line that there is another configuration file to look at.

Configuration Sections (lines starting [word] or [word anotherWord])

Klipper functionality is split into a series of sections to configure each element of your printer. I will not talk about each section here as they are documented in the Klipper configuration reference.
This always be your starting point for understanding what the section does. Some additional notes about Klipper pin configurations are available in Klipper Pin Configurations
A typical configuration file will have 10's or possibly hundreds of these sections depending on the complexity of the printer and the features used.

Each section starts with the section name inside a square brackets for example called myHotend would be on a new line starting [myHotend] This heading can optionally have an "instance name", this allows things like fans to have a unique name that can be used elsewhere in Klipper. An example is given below
[heater_fan heatbreak_cooling_fan]
This represents a section "heater_fan" which can be looked up in the Klipper configuration reference which has been named "heatbreak_cooling_fan".
This heading will then be followed by a series of lines setting named parameters to values.
These lines are written in the format "name: value" where name is the name of the parameter and value is the value to assign to that parameter The list of parameters for each configuration section is specific to that section and must be looked up in the Klipper configuration reference

Example section

Below is an example configuration section, specifically this is the printer section for an ender 3: [printer]
kinematics: cartesian
max_velocity: 300
max_accel: 3000
max_z_velocity: 5
max_z_accel: 100

Let’s break this down:
The section is called printer see printer in the Klipper configuration reference
This section has five parameters:
kinematics which is set to cartesian max_velocity which is set to 300
max_accel which is set to 3000
max_z_velocity which is set to 5 max_z_accel which is set to 100

There is nothing to mark the end of a section, this is done implicitly at the end of the file or when finding the start of the next section.

What each of these values means or does is left to the Klipper configuration reference as anything recorded here will inevitably get out of date and the purpose of this is to help you find information and get started with understanding your printer configuration.

SAVE_CONFIG

Klipper will sometimes save some data for us, things like your Z offset or PID tuning parameters. In order to do this Klipper has to put the data somewhere and the somewhere is the end of printer.cfg. Klipper helpfully puts a line in the configuration file to tell us that it has done this and that lines is
#*# <---------------------- SAVE_CONFIG ---------------------->
Every line after this will start with "#*# " but you will notice that the things after "#*# " look exactly the same as the normal configuration settings.
That is because they are, Klipper will read the configuration (lines without "#*# ") and then read the lines starting with "#*# " to see if anything has been updated with a saved setting. Normally you should not need to edit after the SAVE_CONFIG line but under some error conditions (normally relating to a change of hardware) where you remove a user created section it may be necessary to find and delete the matching saved settings section.

Terrifyingly complex looking stuff full of {}'s and %'s

This is almost certainly some sort of G Code macro, these can be quite complex and are fundamentally a programming language. Most users will simply use macros created for a specific job by someone else. You can confirm you are looking at one of these section by scrolling up from the section until you find the section heading, it should start [gcode_macro. These are not documented here the Klipper documentation starts at https://www.Klipper3d.org/Config_Reference.html?h=macro#g-code-macros-and-events and the details of all the content can be found at https://www.Klipper3d.org/Command_Templates.html. This is an advanced topic and should not be needed to get a printer started outside of pre-defined macros supplied by the printer designer or manufacturer.

What is Sensorless Homing

Sensorless homing uses the "stall guard" feature of the Trinamic TMC family of drivers to detect when the stepper motors are unable to turn.
In 3d printing we use this to detect when an axis or carriage has reached the end of its travel.
The TMC drives have a single Diagnostic pin known as "diag" which is used to communicate status of the driver. In typical 3d printing configurations only the stall guard system is using this pin.

The process is typically as follows (although in the real world it happens very quickly)

1. The tool head hits the frame (or some stopper attached to the frame) and stops.
2. The tool head stops the belt connected to the tool head.
3. The belt stops the motor driving the tool head.
4. The motor driver detects that driving the motor suddenly became harder.
5. The motor driver sets its diag pin true.
6. Dependant on controller board, the diag signal crosses the diag jumper
7. The controller sees the diag pin go true and considers this like an end stop.

How is it setup

Electrically

There are two main ways of connecting the diag pin to the MCU,

1. The board provides dedicated pins on the MCU permanently connected to the motor driver diag pins.
2. The board provides jumpers which allow the diag pins to be optionally connected to the MCU, typically in this configuration the jumpers will connect the diag pin to the associated end stop input.

External Drivers / Step Sticks

Some external drivers, have a jumper or switch to connect the diag pin of the tmc driver to the step stick socket the driver is in. In order to use sensorless homing this jumper must be installed or the switch must be switched on.

Some older boards did not provide a method for connecting to the diag pin and this had to be done with jumper wires, modern controller boards have moved away from this.

Software

Klipper has special sections in it's configuration for configuring TMC drivers see https://www.klipper3d.org/Config_Reference.html#tmc-stepper-driver-configuration The Klipper guide to setting this up is at https://www.klipper3d.org/TMC_Drivers.html#sensorless-homing

The bits of interest to us are the threshold and the diag pin name.
The diag pin must be set to match the layout of the board.
The threshold must be tuned per machine, there are many factors which affect this. The name of the threshold variable varies by driver, see Klipper docs.

Once the TMC section has been added a new "virtual pin" becomes available within Klipper the name of this is given in the Klipper section but will be similar to "tmc2130_stepper_x:virtual_endstop" where the TMC model number and stepper name with change with the associated section in the configuration. This new virtual pin can be used as the end stop pin in the normal stepper section for the axis.

Numpy Errors

Background

Numpy is a maths library used as part of python the programming language Klipper is written in, well the bits that run on the host anyway. This is used during calculations as part of input shaper calibration.

There are two basic errors that come up, they have very similar display error messages.

Symptoms

Klipper log displays "Failed to import `numpy` module".
This will be followed by a message stating make sure it is installed via pip install this message will also include a path to pip something like '~/klippy-env/bin/pip' There are two root causes of this:
1). numpy is not installed.
2). A library upon which numpy depends (lib blas) is not installed.

So how do we fix this?

It is possible to dig through Klipper logs and issue commands to determine which issue is at play, but it is as quick and easy to try and fix issue 1 first, the solution for issue 1 will highlight if issue 2 is at play. It is not uncommon to need to fix both of these issues depending upon how you installed your initial Klipper image.

Issue 1

To fix issue 1 we install numpy this should be done using the pip path given in the Klipper error message.
The command to install will look like the command below with the path modified to match your Klipper error message. ~/klippy-env/bin/pip install numpy
This command can take a long time to run as various things need to be built. If this command returns a message which states "Requirements already satisfied" numpy is already installed and you actually have issue 2.

Issue 2

To fix issue 2 we need to install the supporting library libblas. This is done through the apt command, command below. If you dont understand what this is doing see Linux For Klipper Users
sudo apt install libopenblas0
Note: the name of the package libopenblas0 has changed relatively recently the package used to be called libopenblas-base. if you tried installing libopenblas-base and the command failed this is why.

Useful links