Configuration Basics for Beginners - Phil1988/FreeDi GitHub Wiki

Configuration Basics for Beginners

This guide explains the fundamental concepts behind Klipper's configuration system. If you're already familiar with Klipper, you can skip this and go directly to Configuration Files.

Why Configuration Files?

FreeDi uses Klipper firmware, which stores settings in text files instead of compiled firmware. This approach has several advantages:

Easy customization – Edit a text file instead of recompiling and flashing firmware

Version control friendly – Track changes over time, share configurations easily

Human readable – You can understand what each setting does by reading the file

Safe experimentation – Test changes without permanent modifications

How Configuration Files Work

Understanding this concept is crucial for working with FreeDi and Klipper:

The Startup Process

  1. Service starts – When Klipper, FreeDi, or another service boots up
  2. File is read – The service reads its configuration file from disk
  3. Settings are loaded – Configuration is applied to the running program
  4. Service operates – The program runs with these settings until stopped

Why Restart is Required

Configuration files are only read at startup. This means:

  • ✅ Editing a file → Changes are saved to disk
  • ❌ Not restarting → Running service doesn't know about changes
  • ✅ Restarting → Service reads the updated file and applies changes

The workflow:

  1. Edit configuration file
  2. Save file
  3. Restart the service ← This is when changes actually take effect
  4. Service reads updated file and applies new settings

💡 Real-world analogy: Think of it like updating a recipe book. You can write new instructions in the book (edit config), but the chef (service) only reads the recipe when starting to cook (startup). To use the new recipe, the chef needs to start a new dish (restart).

Klipper Configuration Syntax

Klipper uses a simple INI-style format that's easy to read and edit:

Basic Structure

[section_name]
parameter: value
another_parameter: value

# This is a comment
[another_section]
yet_another_parameter: value

Format Rules

Section names – Enclosed in [square brackets], define what you're configuring

[stepper_x]
[extruder]
[bed_mesh]

Parameters – Use : (colon) separator, not = (equals sign)

# Correct:
rotation_distance: 40

# Wrong:
rotation_distance = 40

Comments – Start with #, ignored by Klipper

# This explains what the next setting does
microsteps: 16

Whitespace – Spaces around : are ignored, use for readability

# Both are valid:
microsteps:16
microsteps: 16

Case sensitivity – Values and parameter names are case-sensitive

# Different meanings:
enable_pin: PE3
enable_pin: pe3  # This might not work!

Common Configuration Patterns

Including Other Files

Klipper can split configuration across multiple files:

[include macros.cfg]
[include hardware/*.cfg]

This is why FreeDi uses separate printer.cfg and macros.cfg files [attached_file:1] – they're all loaded as if they were one big file.

Overriding Settings

Later definitions override earlier ones:

[stepper_x]
microsteps: 16  # First definition

[stepper_x]
microsteps: 32  # This overwrites the previous value

Commenting Out Settings

Disable a setting without deleting it:

# Temporarily disabled:
# max_accel: 10000

# Currently active:
max_accel: 5000

Understanding Service Restarts

Different files require different restarts because they're used by different services:

Klipper Service

Files: printer.cfg, macros.cfg

Restart method: "Save & Restart" button in Mainsail

What it does: Restarts the Klipper firmware, reloads all printer configuration

FreeDi Service

Files: freedi.cfg

Restart method: Power menu → Restart FreeDi

What it does: Restarts only the display firmware, doesn't affect printing [attached_file:1]

Moonraker Service

Files: moonraker.conf

Restart method: Power menu → Restart Moonraker

What it does: Restarts the web interface backend

Other Services

Files: crowsnest.conf, etc.

Restart method: Power menu → Restart [Service Name]

What it does: Restarts specific features like camera streaming

Configuration Best Practices

Before Editing

  1. Understand what you're changing – Read comments, check documentation
  2. Backup the file – Download a copy before making changes
  3. Make small changes – Edit one thing at a time for easier troubleshooting

While Editing

  1. Preserve formatting – Keep indentation and structure consistent
  2. Add comments – Explain why you made a change
  3. Check syntax – One typo can prevent Klipper from starting

After Editing

  1. Save the file – Don't forget this step
  2. Restart the appropriate service – See table in Configuration Files
  3. Check for errors – Look at Mainsail console for error messages
  4. Test the change – Verify it works as expected

Learning More About Klipper Configuration

FreeDi uses standard Klipper configuration with some additions for the display [attached_file:1]. To deepen your understanding:

Official Klipper Documentation:

FreeDi-Specific:

Ready to customize? Head to Configuration Files to see what you can configure.

See Also: