Tool Config
Each tool has its own configuration file, stored by default in ~/printer_data/config/toolchanger/tools/.
These files should be named according to the tool’s index — for example, T0.cfg, T1.cfg, and so on. This structure keeps configurations organized and makes it easy to manage settings for individual tools.
Don't be too hasty
It’s a good idea to start by setting up a single tool (T0.cfg) first. Getting one toolhead working correctly helps identify and resolve any issues before applying the same configuration to additional tools.
As a minimum, the following sections are required in a tool config:
- [mcu]
- [extruder]
- [tmc2209]
- [heater_fan]
- [fan_generic]
- [tool]
- [tool_probe]
- [gcode_macro Tn]
Reference Examples
The following sections are for reference only. The contetnts of the reference examples may differ from your config. For complete examples, please reference the Examples page.
[mcu]¶
Each toolhead board requires a unique MCU name. Typically you would give them a descriptive name followed by the respective tool number.
[extruder]¶
The extruder section is much the same as your typical Klipper extruder section with the exception of tools that are not T0 requiring a tool number attached to them.
[tmc2209]¶
Behaves exactly like a typical [tmc2209] section.
[heater_fan]¶
Behaves exactly like a typical Klipper [heater_fan] section.
[fan_generic]¶
To be able to control a tool's part cooling fans while it is not in use, klipper-toolchanger uses [fan_generic] rather than [fan].
[fan]
Using [fan_generic] replaces the need for a [fan] section in your config. If you have an existing [fan] section, it must be removed.
[tool]¶
The [tool] section is a klipper-toolchanger-easy extension that is used to attach all the preceding sections and calibration values to a tool object that klipper-toolchanger-easy references.
Offset and Park Values
The gcode_[xyz]_offset and params_park_[xyz] values should all default to zero. They are values that need to be calibrated.
[tool T0]
tool_number: 0 # change to the index of the tool. 0, 1, 2, etc.
extruder: extruder # change to match the extruder you are configuring: extruder, extruder1, etc.
fan: T0_part_fan
# detection_pin: # Only required for non TAP probing.
params_park_x: 0 # The absolute X-position of the tool in its dock.
params_park_y: 0 # The absolute Y-position of the tool in its dock.
params_park_z: 0 # The absolute Z-position where the tool and shuttle mate in the dock, determined when the TAP (or Z-probe) triggers.
gcode_x_offset: 0 # The X-Axis offset of the nozzle's orifice in relation to tool 0
gcode_y_offset: 0 # The Y-Axis offset of the nozzle's orifice in relation to tool 0
gcode_z_offset: 0 # The Z-Axis offset of the nozzle's orifice in relation to tool 0
[tool T1]
tool_number: 1 # change to the index of the tool. 0, 1, 2, etc.
extruder: extruder1 # change to match the extruder you are configuring: extruder, extruder1, etc.
fan: T1_part_fan
# detection_pin: # Only required for non TAP probing.
params_park_x: 0 # The absolute X-position of the tool in its dock.
params_park_y: 0 # The absolute Y-position of the tool in its dock.
params_park_z: 0 # The absolute Z-position where the tool and shuttle mate in the dock, determined when the TAP (or Z-probe) triggers.
gcode_x_offset: 0 # The X-Axis offset of the nozzle's orifice in relation to tool 0
gcode_y_offset: 0 # The Y-Axis offset of the nozzle's orifice in relation to tool 0
gcode_z_offset: 0 # The Z-Axis offset of the nozzle's orifice in relation to tool 0
Alternate probing
If you are using a probing method other than TAP, the detection_pin variable must also be set with the pin for the tool's tap sensor.
Info
Further information on the [tool] section can be found in the Klipper-toolchanger-easy documentation.
[tool_probe]¶
The [tool_probe] section is a klipper-toolchanger extension that attaches a probe to the tool object. This gives each tool the ability to be used as a TAP probe and is also used to detect which tool is on the Shuttle.
[probe]
Using [tool_probe] replaces the need for a [probe] section in your config. If you have an existing [probe] section, it must be removed.
Alternative Probes
[tool_probe] should be disabled if using alternative probes, such as Eddy current sensors.
Info
Further information on the tool_probe section can be found in the Klipper-toolchanger-easy documentation.
[gcode_macro Tn]¶
Each tool gets assigned a gcode_macro which is used to call a change to that tool.