Skip to main content

Firmware Compilation Guide

Important Safety Notice

To ensure stable system operation, please strictly follow the firmware usage principles below:

  • Firmware Compilation Consistency: The Klipper firmware must be compiled by the host machine you are currently using. Using firmware compiled by others or with mismatched versions may lead to unpredictable system failures.
  • Hardware Platform Standards: It is highly recommended to use standard host hardware. Avoid using unofficially modified devices (such as certain set-top boxes, WiFi dongles, or specific Redmi device models), as these may pose compatibility and stability risks.
  • Virtualization Environment Limitations: It is not recommended to run the host system in a virtual machine, as this may introduce performance and real-time interference, affecting print quality.

Firmware Type Description​

  • Katapult / HID Mode

    • Function: These two modes have identical functionality, both enabling contactless flashing (updating firmware directly via the host machine without inserting/removing the SD card).
    • Description: HID is the Bootloader used by the FLY onboard host machine, and its essence is the same as Katapult.
    • Important Note: When using Katapult, if the mainboard becomes unresponsive due to flashing incorrect firmware, locate the reset button on the mainboard and quickly double-click it to re-enter Katapult mode for re-flashing.

  • Bootloader Mode

    • Function: The traditional method of flashing via SD card.
    • Advantage: This method has high fault tolerance. If incorrect firmware is flashed accidentally, you can retry by re-flashing the SD card without worrying about "bricking" the mainboard.

Firmware Compilation Guide​

Compilation Preparation and Recommendations
  • To maximize the chance of successful compilation, it is recommended to use MobaXterm as your SSH client. According to user feedback, certain SSH tools may cause unknown compilation errors.
  • Important Configuration Option: In the compilation configuration interface, be sure to check Enable extra low-level configuration options, otherwise some advanced settings will not be displayed.

Startup Pin Configuration (GPIO pins to set at micro-controller startup)​

Important Note
  • This option is used to force specific GPIO pin levels at microcontroller startup.
  • Switch to English input mode, otherwise firmware compilation will fail.

  • Configuration Syntax:

    • Adding ! before a pin means pulling that pin low (low level) at startup; without ! means pulling it high (high level).
    • STM32 series: Pin numbers must be in uppercase format, fill in according to the actual mainboard documentation.
    • RP2040 series: Pin numbers must be in lowercase format, fill in according to the actual mainboard documentation.

  • Multiple Pin Configuration: To configure multiple pins, separate them with English commas ,.

    • Example: !<pin_a>,!<pin_b>,<pin_c> means pulling the first two pins low and the third pin high at startup.
Safety Description

The GPIO pins to set at micro-controller startup you configure only takes effect before Klipper establishes its connection. Once Klipper has fully connected and is running normally, this setting will not affect any other operations on the pins, so it is safe to use.

Global GPIO Startup State​

FLYOS-Klipper Feature

GPIO state at micro-controller startup is an extended feature provided by FLYOS-Klipper; standard Klipper versions may not have this option. Unless explicitly required by the mainboard or toolboard documentation, please keep the default Not set.

This option is used to uniformly set an initial state for most physical GPIOs during the microcontroller startup phase. It differs from the GPIO pins to set at micro-controller startup option above:

Configuration ItemScope of Effect
GPIO pins to set at micro-controller startupOnly sets the pins explicitly listed in the input field; ! can be used to specify low level individually
GPIO state at micro-controller startupUniformly sets the same startup state for all remaining available physical GPIOs

The following pins will not be overridden by the global state:

  • Pins filled into GPIO pins to set at micro-controller startup.
  • Pins reserved by the firmware for current communication functions such as UART, USB, CAN, USB-to-CAN, etc.

Available States​

OptionStartup Phase BehaviorUsage Recommendation
Not setDoes not uniformly modify the startup state of remaining GPIOsDefault and recommended option
Input pull-upConfigures remaining GPIOs as pull-up inputsOnly use when explicitly required by hardware design
Input pull-downConfigures remaining GPIOs as pull-down inputsOnly use when explicitly required by hardware design
Output highConfigures remaining GPIOs as high-level outputsHigher risk, only use per product documentation
Output lowConfigures remaining GPIOs as low-level outputsHigher risk, only use per product documentation
Do Not Blindly Set Global Output States

Output high or Output low will change the levels of a large number of GPIOs before Klipper establishes its connection. Incorrect selection may cause fans, heaters, driver enables, or other peripherals to behave unexpectedly. Unless explicitly specified in the corresponding FLY product documentation, you must select Not set.

Usage Method​

  1. Enable Enable extra low-level configuration options in make menuconfig.
  2. If needed, first fill in the exception pins that require individual control in GPIO pins to set at micro-controller startup, e.g., !gpio18. Separate multiple pins with English commas.
  3. Go to GPIO state at micro-controller startup:
    • Select Not set for standard firmware.
    • Only select the corresponding input or output state when the product documentation explicitly requires a global state.
  4. Press Q to exit, press Y when Save configuration appears, then recompile and update the firmware according to the product flashing tutorial.
  5. After flashing is complete, completely power off the lower machine, then power it back on.
Not set Does Not Disable Individual Startup Pins

Selecting Not set only means "do not uniformly modify the remaining GPIOs". Pins such as !gpio18, !PA15, or others filled into GPIO pins to set at micro-controller startup will still take effect according to their respective configurations.

Flashing Failure Recovery and General Protection
  • Protection Against Flashing Incorrect Firmware: The three firmware types Katapult, HID, and Bootloader have built-in protection mechanisms. As long as you do not enter special DFU mode for flashing, even if the main firmware is flashed incorrectly, these will not be overwritten, and the mainboard will not be "bricked".
  • Necessary Operation After Flashing: After any firmware is flashed, be sure to completely power off the lower machine once (unplug the power cable), then power it back on to ensure the new firmware is loaded correctly and runs stably.

Firmware Flashing Instructions​

Pre-Flashing Notices
  • Device Recognition: When flashing with Katapult, ensure the host machine can recognize the device. If the device cannot be found, quickly double-click the reset button on the mainboard to re-enter flashing mode, or re-flash the mainboard's BL firmware.
  • Follow Specifications: Strictly follow the official tutorial's flashing methods. Using other unverified methods may cause device damage.
  • Compilation Check: Before flashing, be sure to confirm the firmware has no compilation errors. Incorrect firmware files will cause flashing failure or prevent the device from functioning properly.

Katapult Firmware Incorrect Flashing Recovery​

  1. Locate the physical reset button on the mainboard and quickly double-click it.
  2. Under normal circumstances, an LED indicator on the Fly mainboard will begin blinking, indicating successful entry into Katapult mode.
  3. You can now enter Katapult mode and re-flash the correct Klipper firmware.

Bootloader Firmware Incorrect Flashing Recovery​

  1. Re-insert the TF card containing the correct firmware into the mainboard.
  2. If flashing fails, completely power off first, insert the TF card, then power back on.
  3. Keep power on for approximately 5 seconds to complete the automatic flashing.

Katapult Installation and Flashing Dependencies​

Important
  • If you are using a non-Fly official host machine, be sure to execute the following commands to install the firmware flashing dependency packages!
  • Choose one of the two repositories below.
  • GitHub Repository 
    cd && git clone https://github.com/Arksine/katapult.git
  • China Region Mirror Repository 
    cd && git clone https://cnb.cool/3dmellow/public/katapult
Loading...
Loading...