Updating FreeDi - Phil1988/FreeDi GitHub Wiki

What ist this about?

This guide explains how to keep your FreeDi installation up-to-date, including the screen firmware, Klipper, Mainsail, and other system components. You dont have do any updates - if the system is working and you dont notice any bugs or missing features, feel free to stay on this version :) You can "skip" updates, eg. if you are on v2.02 and you want to update to v2.08, you can do this directy (no intermediate updates needed).

📌 Note: This guide assumes you're already running FreeDi v2.00 or newer. If you're still on an older version (v1.x), please read the special section below first.

⚠️ General Warning About Updates

Updates often fix bugs and bring new features (this applies to FreeDi, Klipper, Mainsail, Moonraker, and other components), but there's also a risk of introducing new issues.

Important considerations before updating:

  • Critical projects: If you rely on your printer for time-sensitive work, consider postponing updates until after your project is complete.
  • Klipper updates require special attention: Sometimes a new Klipper version changes the communication protocol between the host and MCUs. This means after a Klipper update, you might need to reflash the mainboard MCU (via microSD card) and/or the toolhead MCU. Watch for "MCU firmware mismatch" errors after Klipper updates.
  • Config file backups: If you're making changes to configuration files, it's wise to back them up first - especially when you're still learning. Over time you'll get more confident, and since Klipper allows real-time adjustments, backups become less critical.
  • FreeDi updates are low-risk: Worst case scenario - the display stops working, but your printer remains fully functional via Mainsail or your slicer.

What Gets Updated Automatically?

The Moonraker Update Manager in Mainsail handles these components automatically:

  • FreeDi - Screen firmware and software (communication layer between Klipper and display)
  • Klipper - Motion control system
  • Moonraker - API server
  • Mainsail - Web interface
  • Crowsnest - Camera streaming service
  • System packages - Operating system updates

For this, check the Update via Update Manager section below.

What Does NOT Get Updated Automatically

Your configuration files are never automatically modified to protect your personal settings, for example:

  • printer.cfg - Your main printer configuration
  • macros.cfg - Custom macros and commands
  • freedi.cfg - FreeDi-specific settings

⚠️ Why? Auto-updating these files would overwrite your personal modifications like PID values, Z-offsets, custom macros, and other customizations you've made. You need to manually review and merge relevant changes when new versions include config improvements.

Some releases includes updates/improvements for the above mentioned files - especially the printer.cfg, macros.cfg and freedi.cfg. To get them you have only 2 choices:

  1. Add them manually to your configs
  2. Reflash your EMMC with the latest provided image file. (This will wipe and install the latest OS, so all your files, history and modifications will be gone)

For manual updating, check the Manually Updating Configuration Files section below.

For more information about the config files see also:

How to Update: Step-by-Step

Update via Update Manager

If you're on firmware v2.00 or newer, updating FreeDi is as simple as one click!

  1. Open Mainsail in your web browser
  2. Go to the Machine tab in the left sidebar
  3. Scroll down to the Update Manager section
  4. Click "UPDATE" next to FreeDi:

image

The new release will be downloaded and the FreeDi service will automatically restart. If your screen firmware needs updating, FreeDi will automatically send the new firmware to the display and update it. This process takes approximately ~4 minutes to complete.

After the update finishes, a system reboot is recommended but not mandatory.

[!WARNING] Do not shut off the printer during the update process! This will interrupt the firmware upload and can result in broken screen firmware.

Don't panic if this happens: Simply turn the printer off and on again. FreeDi will detect the broken status and clear it for you automatically. If that doesn't work, reach out for help - we can guide you through recovery ;)

[!NOTE] The display firmware update process occasionally freezes during the upload. If the white screen shows no changes for more than 5 seconds, it's likely stuck. This usually happens when the serial controller gets overwhelmed. Simply power cycle the printer - FreeDi will detect the incomplete update and automatically retry the flash. In some cases, this might happen multiple times in a row. If that occurs, let the printer rest for a few minutes before trying again - this often resolves the issue.

Updating Other Components

You can also update Klipper, Mainsail, Moonraker, and other components from the same Update Manager:

  1. In the Update Manager section, click the refresh icon (🔄) to check for available updates
  2. Review what's available:
    • Components show "UPDATE" button when newer versions are available
    • System shows "UPGRADE" for OS package updates
  3. Click Update next to each component you want to update
    • Tip: You can also use "Update all components" to update everything at once
    • The order doesn't really matter - update what you like ;)
  4. Wait for the update process to complete - a progress dialog will show the status
  5. After Klipper or Moonraker updates, restart the services when prompted

Understanding Update Status Indicators

  • UP-TO-DATE ✅ - Everything is current, no action needed
  • UPDATE 🔄 - New version available, recommended to update
  • DIRTY ⚠️ - Local files were modified, may need recovery
  • DETACHED ⚠️ - Repository is not on a standard branch
  • INVALID ❌ - Component path not found, reinstall may be needed

Manually Updating Configuration Files

When FreeDi releases include improvements to configuration files (like new macros, better defaults, or new features), you'll need to manually compare and merge these changes into your personal configs.

Which Files to Check

After a FreeDi update, check the Config Section to see this for your printer:

  • printer.cfg - Main printer configuration (found in config_section/YOUR_PRINTER_MODEL/)
  • macros.cfg - Custom macros and commands (found in config_section/YOUR_PRINTER_MODEL/)
  • freedi.cfg - FreeDi-specific settings (found in config_section/generic/ - applies to all printer models)

💡 Note: If you're not sure what these files do or whether you've modified them, that's totally fine. Just follow the simple cases (A and B) below. Case C is for advanced users who regularly customize their configs.

Choosing Your Update Strategy

There are three typical situations. Pick the one that matches how you use your printer:

Case A: You never touched the configs

You just use FreeDi "as is" and haven't modified macros.cfg, printer.cfg, or freedi.cfg.

  • Simply replace your existing files with the latest versions from GitHub
  • This gives you all new macros and improvements without any extra work
  • Follow the instructions in "Simple Replace Method" below

Case B: You changed a few small things

You made some minor edits (like one or two custom macros or a small tweak), but most of the file is still original.

💡 Tip: Mark your personal changes with special comments to find them easily later:
# === MY CUSTOM CHANGE START ===
# === MY CUSTOM CHANGE END ===

Recommended workflow:

  1. Create a backup of your current config files in Mainsail (download them or copy the content somewhere safe)
  2. Replace your files with the latest versions (see "Simple Replace Method" below)
  3. Open your backup and look for your special comment markers
  4. Copy your personal changes back into the new config files at the appropriate places
  5. Save and restart Klipper

This way you get all new features while keeping your personal tweaks.

Case C: You heavily customized your setup

You've made extensive modifications, added many custom macros, or significantly restructured parts of the config.

  • A full replacement would likely break your setup
  • You need to compare and merge changes carefully using GitHub's "Blame" feature
  • Follow the instructions in "Compare and Merge Method" below

Simple Replace Method (Cases A and B)

Use this method if you either didn't change the configs at all (Case A), or if you want to replace them and then manually re-add a few personal changes (Case B).

  1. Go to the FreeDi config section
    You'll see folders for each supported printer model:

  2. Navigate to your printer model's folder For printer.cfg and macros.cfg: Open your model-specific folder (e.g., X-Max3, Q1_Pro, Plus4)
    For freedi.cfg: Open the generic folder (applies to all models)

  3. Open the file you want to update (e.g., macros.cfg or printer.cfg)

  4. Copy the entire content of that file (click "Raw" button, then select all and copy)

  5. In Mainsail, go to Machine → Configuration Files

📌 For Case B users: Do a backup of the files/lines you changed..

  1. Open the corresponding config file (e.g., macros.cfg) and paste the new content to replace the old one

📌 For Case B users: Now re-apply your own changes from your backup using your comment markers as a guide, then save and restart Klipper again.

  1. Save the file and click "Restart Klipper" to apply changes

Compare and Merge Method (Case C)

Use this method if you've heavily customized your configuration and want to carefully "cherry pick" new features or fixes without losing your modifications.

  1. Go to the FreeDi config section
    You'll see folders for each supported printer model:

  2. Navigate to your printer model's folder and open the file you want to check (e.g., macros.cfg)

  3. Click "Blame" to see when each line was last changed:

  4. Look for changes made after your last installation or update

    • For example, if you installed FreeDi six months ago, focus on recent commits
    • In GitHub's dark mode, newer changes appear brighter; older ones are darker
    • Check the commit dates on the left side to identify recent modifications

  5. Identify relevant sections (new macros, bug fixes, safety improvements, etc.) and decide what to merge into your own config

📌 Tip: Some changes - especially for the macros - interact with each other and need inserts on different lines. It can help to also check for other changes in the same time range or checking the change title. In this example the NEXT_PRINT_STATIC_MESH macro needs also a few changes at the PRINT_START macro (see also the title "Apply changes for version 2.08"):

  1. In Mainsail, open Machine → Configuration Files, edit the corresponding file, and carefully paste the new parts into the correct locations

  2. Save the file and click "Restart Klipper" to apply changes

💡 Tip: Take your time with Case C if you are not familiar with this - its a learning curve ;)

Troubleshooting Updates

Update Fails with "DIRTY" Status

  • Click "Recover" in the Update Manager to reset to a clean state
  • If recovery fails, reach out for help (see "Getting Help" section - coming soon)

Klipper Won't Start After Update

  • Check the console in Mainsail for error messages
  • Most likely cause: Config file incompatibility with new Klipper version
  • Restore your backup config and check the release notes for breaking changes
  • Compare your config with the default configs on GitHub

MCU Firmware Mismatch Error

  • This happens when Klipper core was updated but the MCU firmware wasn't flashed yet
  • Usually resolved by clicking "Update" again in the Update Manager (Klipper will attempt to reflash)
  • If the error persists, you may need to manually reflash:
    • Mainboard MCU via microSD card
    • Toolhead MCU via the flashing guide
  • Reach out for help if you're unsure (see "Getting Help" section - coming soon)

Screen Firmware Appears Broken After Interrupted Update

  • Turn the printer off and back on again
  • FreeDi will automatically detect the broken firmware state and clear it
  • If the screen still doesn't work after a reboot, reach out for help

Checking Your Current FreeDi Version

Not sure which version you're running?

  1. Open Mainsail in your web browser
  2. Click the Machine tab in the left sidebar
  3. Scroll to the Update Manager section
  4. Look for "FreeDi" in the list - your current version is shown next to it
  5. Alternatively, check the About section in FreeDi's display menu

Updating from Older Versions (v1.x)

If you're still running FreeDi v1.x, updating to v2.x is possible but complicated and error-prone. The manual update process would likely require my direct support, which takes considerable time.

Recommended Approach: Fresh Install

I strongly recommend downloading the latest image and flashing it to your EMMC instead:

  1. Go to the FreeDi Releases page
  2. Look for releases with names like "FreeDi v2.08 (software and image)"
    • The keyword "image" indicates it includes a flashable image file
  3. Download the image file
  4. Follow the Installation Guide (see wiki navigation menu):
  5. You can skip these steps during installation:
    • Flashing the mainboard MCU via microSD
    • Flashing the toolhead MCU
    • These are likely already flashed with compatible firmware from your v1.x installation

💡 Why skip MCU flashing? Users coming from v1.x already have compatible Klipper firmware on their mainboard and toolhead MCUs. The fresh install focuses on updating the host system and FreeDi software.

Why This Approach?

  • Much faster than manual updating (saves hours of work)
  • Lower risk of configuration conflicts or missing steps
  • Clean slate with all the latest defaults and improvements
  • Less support needed from me, so you can get up and running independently

📌 Note: Make sure to back up your current configuration files before flashing! You'll want to reference your old printer.cfg, macros.cfg, and other customizations to merge them into the fresh installation.

Questions or issues? Check back soon for the "Getting Help" section, or visit the Community page for support options.