Configuration

Usually you don't need to create a configuration file, but if you need to change something that is not changeable in the UI create a blank file in ~/printer_data/config/KlipperScreen.conf, if the file already exist then just edit it.

Write in the file only the options that need to be changed, and restart KlipperScreen.

Critical

Each configuration option should be on a newline, as they are presented here.

The line endings should be of UNIX style (LF).

Main Options

The options listed here are not editable from within the user interface.

[main]

# Time in seconds before the Job Status page closes itself after a successful job/print
# 0 means disabled
# job_complete_timeout: 0

# Time in seconds before the Job Status closes itself if an error is encountered
# job_error_timeout: 0

# Allows the cursor to be displayed on the screen
# show_cursor: False

# If multiple printers are defined, this can be set the name of the one to show at startup.
# default_printer: MyPrinter

# To define a full set of custom menus (instead of merging user entries with default entries)
# set this to False. See Menu section below.
# use_default_menu: True

# Define one or more moonraker power devices that turn on/off with the screensaver (CSV list)
# screen_on_devices: example1, example2
# screen_off_devices:  example1, example2

Tip

It is strongly recommended that you do not add settings to the config file if you don't need them

Printer Options

Multiple printers can be defined

# Define printer and name. Name is anything after the first printer word
[printer MyPrinter]
# Define the moonraker host/port if different from 127.0.0.1 and 7125
moonraker_host: 127.0.0.1
# ports 443 and 7130 will use https/wss
moonraker_port: 7125
# Moonraker API key if this host is not connecting from a trusted client IP
# moonraker_api_key: False

# Define the z_babystep intervals in a CSV list. Currently only 2 are supported, the last value is default
# z_babystep_values: 0.01, 0.05

# For the 'Power on' button on the splash screen:
# Define one or more moonraker power devices that turn on this printer (CSV list)
# By Default it tries to match the printer name defined in this section header to the moonraker power device name.
# power_devices: example1, example2

# Define what items should be shown in titlebar besides the extruder and bed
# the name must be the same as defined in the klipper config
# valid options are temperature_sensors or temperature_fans, or heater_generic
# titlebar_items: chamber, MCU, Pi

# The style of the user defined items in the titlebar
# Can be 'full' indicating that the full name is shown, 'short' for the first letter, or None (default) for no name
# titlebar_name_type: None

# Z probe calibrate position
# By default it tries to guess the correct location
# it will try using zero reference position, safe_z, mesh midddle, middle of axis length, etc
# example:
# calibrate_x_position: 100
# calibrate_y_position: 100

# Rotation is useful if the screen is not directly in front of the machine.
# It will affect the bed mesh visualization.
# Valid values are 0 90 180 270
# screw_rotation: 0

# Define distances and speeds for the extrude panel. CSV list 2 to 4 integers the second value is default
# extrude_distances: 5, 10, 15, 25
# extrude_speeds: 1, 2, 5, 25

# Define distances for the move panel. comma-separated list with 2 to 7 floats and/or integers
# move_distances: 0.1, 0.5, 1, 5, 10, 25, 50

# Camera needs to be configured in moonraker:
# https://moonraker.readthedocs.io/en/latest/configuration/#webcam

Preheat Options

Added one the others disappeared, Is this normal?

Adding a custom preheat section will cause the defaults to not load, this is the intended behaviour.

[preheat my_temp_setting]
extruder: 195
extruder1: 60
heater_bed: 40
# Use the name
chamber: 60
# or the full name
heater_generic chamber: 60
# or for example apply the same temp to devices of the same type
temperature_fan: 40
heater_generic: 60
# optional GCode to run when the option is selected
gcode: MY_HEATSOAK_MACRO

There is a special preheat setting named cooldown to do additional things when the cooldown button is pressed do not add TURN_OFF_ALL_HEATERS or you will remove the ability to turn off individual heaters with this button. for example:

[preheat cooldown]
gcode: M107

Include files

# [include conf.d/*.conf]
# Include another configuration file. Wildcards (*) will expand to match anything.

This allows a custom configuration for the menu displayed while the printer is idle. You can use sub-menus to group different items and there are several panel options available. It is possible to have a gcode script run on a menu button press. There are two menus available in KlipperScreen, __main and __print. The __main menu is displayed while the printer is idle. The __print menu is accessible from the printing status page.

Info

A predefined set of menus is already provided

A menu item is configured as follows:

[menu __main my_menu_item]
name: Item Name
#   To build a sub-menu of this menu item, you would next define [menu __main my_menu_item sub_menu_item]
#
#   --- The following items are optional ---
#
# icon: home
#   Icon name to be used, it can be any image in the directory:
#   KlipperScreen/styles/{theme}/images/ where {theme} is your current theme
#   Supported formats svg or png
#
# style: mycolor4
#   Icon style, defined as "button.mycolor4" (for example) in the theme css
#
# panel: preheat
#   Panel from the panels folder in the KlipperScreen folder
#
# enable: {{ 'screws_tilt_adjust' in printer.config_sections and printer.power_devices.count > 0 }}
#   Enable allows hiding of a menu if the condition is false. (evaluated with Jinja2)
#   Available variables are listed in the next section.
#
#   --- The items below do not work if you define a panel to be loaded ---
#
# method: printer.gcode.script
#   Moonraker method to call when the item is selected, you will need params below
#   the most common is is printer.gcode.script check out other methods in moonraker documentation:
#   https://moonraker.readthedocs.io/en/latest/web_api/#run-a-gcode
#
# params: {"script":"G28 X"}
#   Parameters that would be passed with the method above
#
# confirm: 'Are you sure?'
#   If present this option will give you a confirmation prompt with the text above.
#   It's recommended that you use a Macro-prompt instead of this option,
#   as the Macro-prompt will also be shown on other interfaces, and it's more flexible.
#   Macro-prompts are described in: https://klipperscreen.github.io/KlipperScreen/macros/#prompts

Variables to conditionally test the enable statement:

# Configured in Moonraker
moonraker.power_devices.count # Number of power devices
moonraker.cameras.count # Number of cameras
moonraker.spoolman # Has spoolman

# Printer specific
printer.pause_resume.is_paused # Printing job is paused
printer.extruders.count # Number of extruders
printer.temperature_devices.count # Number of temperature related devices (not extruders)
printer.fans.count # Number of fans
printer.output_pins.count # Number of pins configured
printer.gcode_macros.count # Number of gcode macros
printer.gcode_macros.list # List of names of the gcode macros
printer.leds.count # Number of leds
printer.config_sections # Array of section headers of Klipper config (printer.cfg)

A sample configuration of a main menu would be as follows:

[menu __main homing]
name: Homing
icon: home

[menu __main homing homeall]
name: Home All
icon: home
method: printer.gcode.script
params: {"script":"G28"}

[menu __main homing mymacro]
name: My Macro
icon: home
method: printer.gcode.script
params: {"script":"MY_MACRO"}
enable: {{ 'MY_MACRO' in printer.gcode_macros.list }}

[menu __main preheat]
name: Preheat
icon: heat-up
panel: preheat

KlipperScreen behaviour towards configuration

KlipperScreen will search for a configuration file in the following order:

~/printer_data/config/KlipperScreen.conf
~/.config/KlipperScreen/KlipperScreen.conf
${KlipperScreen_Directory}/KlipperScreen.conf

If you need a custom location for the configuration file, you can add launch argument

If one of those files are found, it will be merged with the default configuration. Default Preheat options will be discarded if a custom preheat is found. If include files are defined then, they will be merged first.

The default config is included here: (do not edit use as reference) ${KlipperScreen_Directory}/config/defaults.conf

Do not copy the entire default.conf file, just configure the settings needed.

If no config file is found, then when a setting is changed in the settings panel, a new configuration file should be created automatically.

Starting on a different monitor/display/screen

Add -m or --monitor as a launch argument, to specify the number of the monitor, that will show Klipperscreen (default: 0).

Warning

Selecting the monitor is only allowed when KlipperScreen is set to launch fullscreen in standalone mode (no DE)

Adding launch arguments

The recommended way to add launch arguments is:

Create a launch script:

touch ~/KlipperScreen/scripts/launch_KlipperScreen.sh
chmod +x launch_KlipperScreen.sh

Edit the script:
```
nano ~/KlipperScreen/scripts/launch_KlipperScreen.sh
```
Add the init and the launch argument, this example will launch KlipperScreen on the second monitor if exists:
```
/usr/bin/xinit $KS_XCLIENT --monitor 1
```
Tip

you can use --configfile and --logfile to specify custom locations for those files