The following article gives a basic explanation for how configuration files are interpreted by Klipper and how we can organize these configuration settings more effectively.
The most basic method of organizing Klipper configuration is copy pasting all the settings into printer.cfg
. However, as your printer increases in complexity, your printer.cfg file will inevitably grow in size, making it hard to find relevant settings when making small changes.
We propose a method of organization that seperates Klipper configurations into multiple files by taking advantage of [include]
. By seperating your config files, you can:
Before we start, it is beneficial to understand how Klipper reads your configuration settings. The following are some of the rules that Klipper follows:
Each time Klipper starts up or restarts, it will always look for a file named printer.cfg
under the directory ~/klipper_config/
to obtain configuration data. All Other files in that directory are essentially ignored unless they are included using the [include]
setting.
Klipper will read configuration settings line by line by order of their appearance in a file.
Lines that start with #
are considered comments and ignored. Lines that start with #*#
are NOT ignored, these are special config settings that are auto generated (more on this later)
[include xxxxx.cfg]
instructs Klipper to read all the settings in an external file with the name “xxxx.cfg” before continuing onto the next line. You can imagine this as Klipper copying the entire content of an external configuration file and pasting it where the [include]
line appeared.
If there are multiple instances of the same configuration setting with different values, the instance that appears last is used. All earlier instances are essentially “discarded”. For example:
[heater_fan hotend_fan]
pin: PE5
heater: extruder
heater_temp: 50.0
pin: PA7
Here, the hotend fan is controlled by the pin PA7 because pin: PA7
appears after pin: PE5
.
The basic idea here is to keep printer.cfg
relatively clutter free. We'll do this by using printer.cfg
as a top level configuration file that only contains [include]
statements (mostly). Below is an example of a Voron 0.2-S1 printer.cfg
:
[include fluidd.cfg]
[include skr-pico.cfg]
[include picobilical.cfg]
[include v0_display.cfg]
[include sensorless_homing.cfg]
[include ldo_macros.cfg]
#*# <---------------------- SAVE_CONFIG ---------------------->
#*# DO NOT EDIT THIS BLOCK OR BELOW. The contents are auto-generated.
#*#
#*# [extruder]
#*# control = pid
#*# pid_kp = 34.413
#*# pid_ki = 7.401
#*# pid_kd = 40.004
#*#
#*# [heater_bed]
#*# control = pid
#*# pid_kp = 69.356
#*# pid_ki = 1.233
#*# pid_kd = 975.321
#*#
#*# [stepper_z]
#*# position_endstop = 116.825
As you can see the contents of this printer.cfg is very short - aside from [include] statements, there are only auto-generated settings from klipper (lines that start with #*#). Let's take a look at each [include] statement:
mainsail.cfg
instead.skr-pico.cfg
, certain pin configs in this file will override settings in skr-pico.cfg
.skr-pico.cfg
and picobilical.cfg
. Therefore it is included after those files.As you probably know lines that start with #*#
are settings auto-generated by Klipper. Most commonly, you will see them show up after PID tuning and fine tuning the first layer height. These auto-generated configs must appear at the very end of the printer.cfg - and no other config settings can appear after them. When reorganizing your Klipper configurations, these auto-generated lines will often cause error messages if not dealt with properly. Below are common problems related to auto-generated configs:
This usually occurs if you accidentally deleted your auto-generated settings. The klipper error message will typically say that you are missing some setting. When Klipper generates these settings, it will usually comment out it's counterpart in a config file. For example, when Klipper generates this after you fine tune your Z height
#*# [stepper_z]
#*# position_endstop = 116.825
if will also comment out the same setting inside skr-pico.cfg
(or whatever mainboard config file you are using)
# [stepper_z]
# position_endstop = 120
Simply look for the missing setting in your config file and remove the #
at the beginning of the line. Then re-perform the corresponding tuning procedure.
This commonly occurs when you are reorganizing your old configuration setup to use our top level printer.cfg
file structure. To fix the problem, look for auto-generated configs at the end of your config files. then cut and paste the settings at the end of your printer.cfg
. Remember, you have to make sure that Klipper auto-generated settings only occur at the end of printer.cfg
and nowhere else.