KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #codex #claude-code #mcp #rust #deepseek-harness #typescript #ai-agent #cli

klipper_tmc_autotune

★ 1,037 Open GitHub ↗

TMC stepper driver autotuning Klipper python extra

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Klipper TMC Autotune

Klipper extension for automatic configuration and tuning of TMC drivers.

This extension calculates good values for most registers of TMC stepper motor drivers, given the motor's datasheet information and user selected tuning goal.

In particular, it enables StealthChop by default on Z motors and extruders, CoolStep where possible, and correctly switches to full step operation at very high speeds. Where multiple modes are possible, it should select the lowest power and quietest modes available, subject to the constraints of sensorless homing (which does not allow certain combinations).

### Current status

- Official support for TMC2209, TMC2240, and TMC5160.
- Support for TMC2130, TMC2208 and TMC2660 may work, but is completely untested.
- Sensorless homing with autotuning enabled is known to work on TMC2209, TMC2240 and TMC5160, provided you home fast enough (homing_speed should be numerically greater than rotation_distance for those axes using sensorless homing). As always, be very careful when trying sensorless homing for the first time.
- Using autotuning for your motors can improve efficiency by allowing them to run cooler and consume less power. However, it's important to note that this process can also cause the TMC drivers to run hotter, so proper cooling measures must be implemented.

## Installation

To install this plugin, run the installation script using the following command over SSH. This script will download this GitHub repository to your Raspberry Pi home directory, and symlink the files in the Klipper extra folder. Alternatively, if you are using KIAUH to manage your installation, you can find TMC autotune in the community extensions section.

```bash
wget -O - https://raw.githubusercontent.com/andrewmcgr/klipper_tmc_autotune/main/install.sh | bash
```

Then, add the following to your `moonraker.conf` to enable automatic updates:
```ini
[update_manager klipper_tmc_autotune]
type: git_repo
channel: dev
path: ~/klipper_tmc_autotune
origin: https://github.com/andrewmcgr/klipper_tmc_autotune.git
managed_services: klipper
primary_branch: main
install_script: install.sh
```

## Adjusting existing configuration

Your driver configurations should contain:
* Pins
* Currents (run current, hold current, homing current if using a Klipper version that supports the latter)
* `interpolate: true`
* Comment out any other register settings and sensorless homing values (keep them for reference, but they will not be active)

The Klipper documentation recommends not using interpolation. However, this advice is most relevant when using low microstep counts with the default driver configuration. Autotune gives better results, both dimensionally and quality, by using interpolation and as many microsteps as feasible.

Check the pinouts of your stepper driver boards, as there might be unusual boards out there. Known setups:
  - BTT TMC 2240 stepsticks use `diag0_pin`.
  - BTT TMC 5160 stepsticks use `diag1_pin`.
  - MKS TMC 2240 stepsticks use `diag0_pin`.

## Sensorless homing

Autotune can be used together with homing overrides for sensorless homing. However, you must adjust the `sg4_thrs` (TMC2209, TMC2260) and/or `sgt` (TMC5160, TMC2240, TMC2130, TMC2660) values specifically in the autotune sections. Attempting to make these changes via gcode or via the tmc driver sections will not result in an error message, but will have no effect since the autotuning algorithm will simply override them.

Also, note that the sensorless homing tuning may be affected by other settings. In particular, autotune might require faster homing speeds for sensorless homing to function effectively. As a minimum speed that can work, consider the `rotation_distance` of the stepper. If tuning proves challenging, increase the homing speed since sensorless homing becomes much more sensitive at higher speeds. For instance, with a `rotation_distance` of 40, suitable starting homing speeds are 40-60mm/s for TMC2209/TMC2260 drivers and 80-100mm/s for TMC2130/TMC2240/TMC2660/TMC5160 drivers.

## Autotune configuration

Add an `[autotune_tmc]` section for each of the stepper motors you want to tune to your `printer.cfg`, using the motor name from the [motor database](motor_database.cfg). Your existing `[stepper_*]` and `[tmc* stepper_*]` sections should remain unchanged. You can also use the [example.cfg](./docs/example.cfg) as a template.

```ini
[autotune_tmc stepper_x]
motor: ldo-42sth48-2004mah
[autotune_tmc stepper_y]
motor: ldo-42sth48-2004mah

[autotune_tmc stepper_z]
motor: ldo-42sth48-2004ac
[autotune_tmc stepper_z1]
motor: ldo-42sth48-2004ac
[autotune_tmc stepper_z2]
motor: ldo-42sth48-2004ac
[autotune_tmc stepper_z3]
motor: ldo-42sth48-2004ac

[autotune_tmc extruder]
motor: ldo-36sth20-1004ahg
```

All the `[autotune_tmc]` sections accept additional parameters to tweak the behavior of the autotune process for each motor:

| Parameter | Default value | Range | Description |
| --- | --- | --- | --- |
| motor |  | [See DB](motor_database.cfg) | This parameter is used to retrieve the physical constants of the motor connected to the TMC driver |
| tuning_goal | `auto` | `auto`, `silent`, `performance`, and `autoswitch` | Parameter to choose how to fine-tune the TMC driver using StealthChop and tailored parameters. By opting for `auto`, it will automatically apply `performance` for the X and Y axes and `silent` for the Z axis and extruder unless the motor is very small. `autoswitch` is a highly experimental choice that enables dynamic switching between `silent` and `performance` modes in real-time when needed. However, at the moment, this transition can potentially be troublesome, resulting in unwanted behavior, noise disturbances and lost steps. Hence, it is recommended to avoid using `autoswitch` until these issues are fully resolved. |
| extra_hysteresis | 0 | 0 to 8 | Additional hysteresis to reduce motor humming and vibration at low to medium speeds and maintain proper microstep accuracy. Warning: use only as much as necessary as a too high value will result in more chopper noise and motor power dissipation (ie. more heat) |
| tbl | 1 | 0 to 3 | Comparator blank time. This time must safely cover the TMC switching events. A value of 1 (default) or 2 should be fine for most typical applications, but higher capacitive loads may require this to be set to 3. Also, lower values allow StealthChop to regulate to lower coil current values |
| toff | 0 | 0 to 15 | Sets the slow decay time (off time) of the chopper cycle. This setting also limits the maximum chopper frequency. When set to 0, the value is automatically computed by this autotuning algorithm. Highest motor velocities sometimes benefit from forcing `toff` to 1 or 2 and a setting a short `tbl` of 1 or 0 |
| sgt | 1 | -64 to 63 | Sensorless homing threshold for TMC5160, TMC2240, TMC2130, TMC2660. Set value appropriately if using sensorless homing (lower value means more sensitive detection and easier stall) |
| sg4_thrs | 40 (TMC2209) / 0 (TMC2240) | 0 to 255 | StallGuard4 threshold. On TMC2209/TMC2260 this controls sensorless homing sensitivity (higher value = more sensitive). On TMC2240, a non-zero value switches Klipper to SG4/StealthChop-based homing instead of the default SGT/SpreadCycle path; leave at 0 (default) unless you specifically want SG4 homing. |
| semin | 2 | 0 to 15 | **Coolstep**: Lower StallGuard threshold for increasing the current to the motor coils. When set to 0 CoolStep is disabled. |
| semax | 4 | 0 to 15 | **Coolstep**: Upper StallGuard threshold for decreasing the current to the motor coils. |
| seup | 3 | 0 to 3 | **Coolstep**: Sets the current increment step. The motor current becomes incremented based on this setting whenever a new StallGuard value is measured that lies below the lower threshold |
| sedn | 2 | 0 to 3 | **Coolstep**: Sets the number of StallGuard readings above the upper threshold necessary for each current decrement of the motor current. |
| seimin | 1 | 0 to 1 | **Coolstep**: Sets the lower motor current limit for CoolStep operation by scaling the run current. 0 = 50%, 1 = 25% of run current. |
| pwm_freq_target | varies | 10e3 to 60e3 | Switching frequency target, in Hz. The code selects the highest available PWM frequency at or below this target, which usually results in 48 kHz switching. Defaults to 55 kHz for TMC2130/2208/2209 and 20 kHz for TMC2240/2660/5160 to avoid excessive driver heat. |
| voltage | 24 | 0.0 to 60.0 | Voltage used to power this motor and stepper driver |
| overvoltage_vth |  | above 0.0 to 41.0 | Set the optional overvoltage snubber built into the TMC2240. Users of the BTT SB2240 toolhead board should use it for the extruder by reading the actual toolhead voltage and adding 0.8V |

Also if needed, you can adjust everything on the go when the printer is running by using the `AUTOTUNE_TMC` macro in the Klipper console. All previous parameters are available:
```
AUTOTUNE_TMC STEPPER=<name> [PARAMETER=<value>]
```

## User-defined motors

The motor names and their physical constants are in the [motor_database.cfg file](motor_database.cfg), which is automatically loaded by the script. If a motor is not listed, you can add its definition directly in your `printer.cfg` configuration file by adding this section (PRs for other motors are also welcome). You can usually find this information in their datasheets but pay close attention to the units!
```ini
[motor_constants my_custom_motor]
# Coil resistance, Ohms
resistance: 0.00
# Coil inductance, Henries
inductance: 0.00
# Holding torque, Nm
holding_torque: 0.00
# Nominal rated current, Amps
max_current: 0.00
# Steps per revolution (1.8deg motors use 200, 0.9deg motors use 400)
steps_per_revolution: 200
```

Note that lead screw motors very often do not have a published torque. Use an online calculator to estimate the torque from the lead screw thrust, for example https://www.dingsmotionusa.com/torque-calculator.

## How do I know tuning was applied?

Autotune logs all the settings it applies to the Klipper logfile (`klippy.log`), if autotune is correctly configured you should see lines similar to the following on printer startup:

```text
autotune_tmc set stepper_x pwm_freq=2
autotune_tmc set stepper_y pwm_freq=2
autotune_tmc set stepper_z pwm_freq=0
autotune_tmc set stepper_z1 pwm_freq=0
autotune_tmc set stepper_z2 pwm_freq=0
autotune_tmc set extruder pwm_freq=0
autotune_tmc stepper_x ncycles=219 pfdcycles=73
autotune_tmc set stepper_x tpfd=1
autotune_tmc stepper_y ncycles=219 pfdcycles=73
autotune_tmc set stepper_y tpfd=1
autotune_tmc stepper_z ncycles=625 pfdcycles=223
autotune_tmc set stepper_z tpfd=2
autotune_tmc stepper_z1 ncycles=625 pfdcycles=223
autotune_tmc set stepper_z1 tpfd=2
autotune_tmc stepper_z2 ncycles=625 pfdcycles=223
autotune_tmc set stepper_z2 tpfd=2
autotune_tmc extruder ncycles=625 pfdcycles=223
...
```

## Removing this Klipper extension

Commenting out all `[autotune_tmc xxxx]` sections from your config and restarting Klipper will completely deactivate the plugin. So you can enable/disable it as you like.

If you want to uninstall it completely, remove the moonraker update manager section from your `moonraker.conf` file, delete the `~/klipper_tmc_autotune` folder on your Raspberry Pi and restart Klipper and Moonraker.

klipper_tmc_autotune

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README