Configuring Pin Replacement Instructions

This page guides users on how to modify an existing Klipper configuration to be compatible with the current FLY mainboard's pins. Many online configurations serve only as structural references and cannot be used directly. Before formal use, you must replace the corresponding pins based on your actual mainboard model, interface positions, and wiring methods.

Power Off Operation

Before starting, completely shut down the printer and disconnect the power supply. Do not plug or unplug wiring harnesses, arrange interface wiring, or touch terminals while the power is on.

Applicability Notes

This article only explains how to find and replace pins in the configuration; it does not provide a complete, ready-to-use configuration for a specific machine.
Parameters such as position_max, rotation_distance, microsteps, run_current, and sensor_type must be confirmed based on your actual machine and hardware. Do not blindly copy them just because you replaced the mainboard.
Mainboard pins should be based on the corresponding FLY product documentation, mainboard silkscreen, and official reference configurations.

Modification Approach

It is recommended to follow this sequence when modifying the configuration:

Confirm the FLY mainboard model currently in use.
Open the corresponding mainboard product documentation to find pin descriptions for driver ports, endstop ports, fan ports, heater ports, thermistor ports, etc. You can also directly refer to the Klipper reference configuration for the corresponding mainboard.
In printer.cfg and all [include] files, find the functional sections that need modification.
Search for the new pins you plan to use to confirm they are not occupied by other enabled configurations.
Only replace the pin items related to the mainboard interface, retaining necessary symbols like !, ^, ~.
Save the configuration and restart Klipper.
Test each individual function one by one; do not power on and test all peripherals simultaneously.

Common Functional Sections

Function	Common Configuration Section	Common Items to Replace
X / Y / Z Motors	`[stepper_x]`, `[stepper_y]`, `[stepper_z]`	`step_pin`, `dir_pin`, `enable_pin`, `endstop_pin`
Extruder Motor	`[extruder]`	`step_pin`, `dir_pin`, `enable_pin`
TMC Driver Communication	`[tmc2209 stepper_x]`, `[tmc5160 stepper_x]`, etc.	`uart_pin`, `cs_pin`, `spi_software_mosi_pin`, `spi_software_miso_pin`, `spi_software_sclk_pin`, `diag_pin`
Hotend Heater	`[extruder]`	`heater_pin`, `sensor_pin`
Heated Bed	`[heater_bed]`	`heater_pin`, `sensor_pin`
Fans	`[fan]`, `[heater_fan xxx]`, `[fan_generic xxx]`	`pin`, `tachometer_pin`
Endstop Switches	`[stepper_x]`, `[stepper_y]`, `[stepper_z]`	`endstop_pin`
Probes	`[probe]`, `[bltouch]`	`pin`, `sensor_pin`, `control_pin`
LEDs / Buzzers	`[output_pin xxx]`, `[neopixel xxx]`	`pin`

Finding the Corresponding Configuration

If you are unsure which file contains the configuration, it is recommended to search via the web configuration interface.

Open the printer's web interface in a browser, e.g., Fluidd or Mainsail.
Go to the configuration file page and open printer.cfg.
Use the browser's or editor's search function to search for the keywords below.
If you see [include xxx.cfg], it means part of the configuration is split into other files; you need to open that included file to continue searching.

Common search methods:

Search for X-axis: Search for [stepper_x]
Search for Y-axis: Search for [stepper_y]
Search for Z-axis: Search for [stepper_z]
Search for Extruder: Search for [extruder]
Search for Heated Bed: Search for [heater_bed]
Search for Fans: Search for [fan], [heater_fan, [fan_generic
Search for Drivers: Search for [tmc2209, [tmc5160, [tmc2240
Search for Pin Items: Search for step_pin, dir_pin, enable_pin, heater_pin, sensor_pin, endstop_pin, uart_pin, cs_pin

Search Suggestion

The configuration is usually not entirely written in the single printer.cfg file. When you see content like [include mainsail.cfg], [include fluidd.cfg], [include printer/*.cfg], [include xxx.cfg], you need to open the corresponding file to check the actual configuration.

Checking for Pin Conflicts

Before replacing a pin, first search for the new pin you plan to use to confirm it is not already occupied by another function. In Klipper, the same physical GPIO can usually only be assigned to one function. If used repeatedly, you may encounter the error pin xxx used multiple times in config.

When searching, remove any modifiers before the pin. For example, if you plan to use !PA15, search for PA15; if you plan to use ^PD9, search for PD9.

Location Found	Need to Handle?	Description
The same item within the same functional section	Usually not	e.g., `step_pin` appearing in the `[stepper_x]` section you are modifying
Commented example lines	Usually not	Lines starting with `#` are examples and will not take effect
Other enabled functional sections	Needs handling	The same pin cannot be used simultaneously by multiple functions like fan, heater, endstop, probe, etc.
TMC driver's `diag_pin` shared with physical endstop	Need to choose one	When using a physical endstop, do not enable the `diag_pin` on the same pin simultaneously; when using sensorless homing, `endstop_pin` should be changed to the corresponding driver's `virtual_endstop`
Multi-MCU pins	Need to confirm prefix	`toolboard:PA0` and mainboard `PA0` are not the same MCU, but the prefix must match the `[mcu toolboard]` name

Duplicate Pins

If pin xxx used multiple times in config appears after saving, go back to the web configuration interface, search for the reported xxx in printer.cfg and all include files, keep the correct function, and delete, comment out, or change the other duplicate entries.

Pin Symbol Explanation

Klipper pins may have special symbols before them; do not arbitrarily delete them when replacing pins:

Symbol	Meaning	Common Location
`!`	Invert Logic Level	`dir_pin`, `enable_pin`, `endstop_pin`
`^`	Enable Pull-Up	Mechanical endstops, probe inputs
`~`	Enable Pull-Down	A few input signals
`mcu1:PA0`	Specify a pin on a specific MCU	Multi-MCU or toolboard configurations

Example:

enable_pin: !PC3
endstop_pin: ^PA1
sensor_pin: toolboard:PA0

In !PC3, the actual pin is PC3; ! only indicates logic inversion. When replacing for a new mainboard, write it as similar !<new_enable_pin> based on the new mainboard's pin, do not simply delete the !.

Replacement Example

Assume the old configuration uses pins from another mainboard for the X-axis:

Before Modification
[stepper_x]
step_pin: PA3
dir_pin: PA2
enable_pin: !PA1
endstop_pin: ^PB10

Using the FLY-C8P X-axis driver port as an example. After checking the C8P mainboard documentation, you can change the X-axis driver port and X-axis endstop port to corresponding pins. Before modifying, search for PE5, PA8, PA15, PD9 first to confirm these pins are not occupied by other enabled configurations.

After Modification
[stepper_x]
step_pin: PE5
dir_pin: !PA8
enable_pin: !PA15
endstop_pin: ^PD9

If the X-axis uses a TMC2209 driver, you also need to check the corresponding driver communication pins:

After Modification
[tmc2209 stepper_x]
uart_pin: PC9
run_current: 0.800

Example Notes

The example above only shows the writing for the X-axis driver port of FLY-C8P. If your motor is connected to a different driver port, or if you are not using a C8P, please fill in the pins based on your actual mainboard documentation and actual wiring, do not copy directly.

If the motor direction is opposite, you usually only need to add or remove the ! before the dir_pin. For example, if it is currently dir_pin: !PA8, change it to dir_pin: PA8; or vice versa.

If the endstop state is inverted, usually check if the ! and ^ before endstop_pin match the actual wiring method:

endstop_pin: ^!PD9

Replacement by Function

Motor and Driver

For the same motor, you usually need to check both the [stepper_x] and [tmc2209 stepper_x] configuration sections (see the "Replacement Example" above for a complete example). Also pay attention to the following points when replacing pins:

Driver Model

Configuration sections like [tmc2209 stepper_x], [tmc5160 stepper_x], [tmc2240 stepper_x] must match the actual driver model. When replacing the mainboard, do not just change the pins; also confirm whether the driver model, communication method, and sense resistor parameters match.

Sensorless Homing

The FLY-C8P X-axis endstop port example is PD9. If using sensorless homing, you should not continue using endstop_pin: ^PD9. Instead, change it to virtual_endstop according to the driver model, and enable the corresponding diag_pin in the TMC configuration. Do not mix physical endstops and sensorless homing on the same endstop pin.

Sensorless Homing Example
[stepper_x]
endstop_pin: tmc2209_stepper_x:virtual_endstop
homing_speed: 40
homing_retract_dist: 0

[tmc2209 stepper_x]
uart_pin: PC9
diag_pin: ^PD9
run_current: 0.800

Heater and Temperature

Hotend heating is usually in [extruder]:

printer.cfg
[extruder]
heater_pin: PD12
sensor_pin: PC2
sensor_type: Generic 3950

Heated bed heating is usually in [heater_bed]:

printer.cfg
[heater_bed]
heater_pin: PB0
sensor_pin: PC5
sensor_type: Generic 3950

The above is a common example of the C8P hotend and heated bed. heater_pin corresponds to the heater output port, and sensor_pin corresponds to the thermistor input port. Do not swap them, and do not write the same thermistor pin into multiple temperature sensors. The sensor_type example is Generic 3950; please confirm based on your actual thermistor model (common types include ATC Semitec 104GT-2, PT1000, etc.).

Fans

Common model fan configuration:

printer.cfg
[fan]
pin: PA0

Common hotend cooling fan configuration:

printer.cfg
[heater_fan hotend_fan]
pin: PA1
heater: extruder
heater_temp: 50.0

The above is an example of the C8P fan ports. Before replacing, search for PA0 and PA1 to ensure these pins are not also occupied by [output_pin], [fan_generic], or other fan configurations. If the mainboard fan ports are divided into normally open and controllable ports, confirm from the documentation whether the corresponding fan port supports PWM control.

Probe and Endstop

Common mechanical endstop configuration:

printer.cfg
[stepper_x]
endstop_pin: ^PD9

Common standard probe configuration:

printer.cfg
[probe]
pin: ^PC0

Common BLTouch-type probe configuration:

printer.cfg
[bltouch]
sensor_pin: ^PC0
control_pin: PE6

Input Signals

The above are examples of C8P endstop and probe ports. Choose only one type between a standard [probe] and [bltouch]; do not enable the same probe signal pin for both. Whether input signals like endstops and probes require ^ or ! depends on the module type and wiring method. Before modifying, search for PD9, PC0, PE6 to confirm they are not duplicated; after modification, first use commands like QUERY_ENDSTOPS, QUERY_PROBE in the web console to check the trigger state before performing homing or leveling.

Saving and Verification

After completing modifications, click the SAVE & RESTART button in the upper right corner of the web page to save and restart Klipper. If the modification involves underlying configurations like MCU connections or driver communication, you may need to execute FIRMWARE_RESTART in the console instead of a regular RESTART.

It is recommended to verify in the following order:

Check if Klipper starts normally without any configuration errors such as Unknown pin chip name, Pin is not a valid pin name, or Unable to parse option.
If pin xxx used multiple times in config appears, first search for and resolve the duplicated xxx; do not proceed with further testing.
Use QUERY_ENDSTOPS in the web console to check if the endstop states are normal.
Test fans, heaters, and probes individually, not multiple peripherals simultaneously.
Test motor direction with small distance moves, e.g., first move 1mm or 5mm.
After confirming direction, endstops, temperature, and fans are all normal, proceed with homing and printing tests.

Common Issues

Symptom	Common Cause	Resolution Direction
Motor does not move	Incorrect `enable_pin` logic level, incorrect driver communication pin, mismatched driver model configuration	Check if `enable_pin` needs `!`, verify TMC configuration section
Motor direction is reversed	`dir_pin` logic level direction mismatch	Add or remove `!` before `dir_pin`
Endstop always triggered	`endstop_pin` inversion or pull-up configuration mismatch	Check `^` and `!`, execute `QUERY_ENDSTOPS` to verify
Prompt for duplicate pin after saving	Same GPIO used by multiple functions simultaneously	Search for the pin name in the error, delete, comment out, or change the duplicate item
TMC communication error	Incorrect `uart_pin` / `cs_pin` / SPI pins, or driver model mismatch	Recheck communication pins according to the mainboard driver port
Heater does not respond	`heater_pin` incorrectly assigned, or connected to an uncontrollable output port	Check the heater port number and mainboard documentation
Abnormal temperature reading	`sensor_pin` or `sensor_type` mismatch	Check the thermistor port and thermistor type
Fan is uncontrollable	`pin` incorrectly assigned, or connected to a normally-open fan port	Switch to a controllable fan port and modify the configuration

For more mainboard installation considerations, please refer to: Mainboard Common Precautions.

Pin Error Troubleshooting: Unknown pin / pin used multiple times

Modification Approach​

Common Functional Sections​

Finding the Corresponding Configuration​

Checking for Pin Conflicts​

Pin Symbol Explanation​

Replacement Example​

Replacement by Function​

Motor and Driver​

Heater and Temperature​

Fans​

Probe and Endstop​

Saving and Verification​

Common Issues​