# klipper_tmc_autotune: deriving Trinamic driver registers from a motor database

> This Klipper extra computes TMC driver register values from a motor entry in a local database and a chosen tuning goal, instead of asking you to hand tune StealthChop, CoolStep and chopper settings per axis. The payoff is repeatable per motor tuning, with the caveats that some drivers are untested and sensorless homing thresholds are silently overwritten.

**andrewmcgr/klipper_tmc_autotune** — TMC stepper driver autotuning Klipper python extra

- Repository: https://github.com/andrewmcgr/klipper_tmc_autotune
- Stars: 1,063 · Forks: 222
- Language: Python
- License: GPL-3.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/andrewmcgr-klipper-tmc-autotune

## Registers derived from a motor entry, not from guesswork

klipper_tmc_autotune is a Klipper extra for automatic configuration and tuning of TMC stepper motor drivers. The mechanism is straightforward once you know where the inputs come from: the extension looks up the motor you named in a local motor database, pulls the physical constants for that motor from it, and combines them with a tuning goal you select to calculate good values for most registers of the driver.

Those constants live in `motor_constants.py` and the database in `motor_database.cfg`, both at the top level of the repository, and the extension logic is in `autotune_tmc.py`. The database is a plain configuration file that names motors, with the example configuration referencing entries such as `ldo-42sth48-2004mah` and `ldo-36sth20-1004ahg`. This is the part of the design worth understanding: the quality of the output depends entirely on the accuracy of the motor entry you point at, not on any measurement taken from your printer.

The project states that autotuning can improve efficiency by allowing motors to run cooler and consume less power, and it immediately adds the counterweight: the process can also cause the TMC drivers to run hotter, so proper cooling measures must be implemented.

## StealthChop on Z, CoolStep where possible, full step at speed

The extension makes several mode decisions for you, and they are the reason people install it. StealthChop is enabled by default on Z motors and extruders. CoolStep is enabled where possible. And when the motor is running at very high speeds, the driver switches to full step operation, because StealthChop is not appropriate there.

The stated selection principle is that where multiple modes are possible, the extension should pick the lowest power and quietest modes available, subject to the constraints of sensorless homing, which does not allow certain combinations. So the tuning goal is not a single switch between quiet and fast. It is a search over mode combinations, with the sensorless homing requirement acting as a hard constraint that removes some candidates.

The tuning goal parameter is what selects between those outcomes. The `auto` value applies `performance` for the X and Y axes and `silent` for the Z axis and extruder, unless the motor is very small. A separate `autoswitch` value exists, and it is the one the project explicitly warns about, describing it as a highly experimental choice that enables dynamic switching between `silent` and `performance` modes in real time when needed, and noting that the transition can potentially be troublesome, resulting in unwanted behaviour, noise disturbances and lost steps.

## Installing over SSH and letting Moonraker update it

The installation is a single command that the project expects you to run over SSH on the Raspberry Pi. The script downloads this GitHub repository to your Raspberry Pi home directory and symlinks the files in the Klipper extra folder:

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

Piping a remote script into a shell is worth pausing on, as it is with any project that asks for it. The script lives in the repository at `install.sh` and the URL points at the `main` branch, so reviewing it before running it is a reasonable precaution. The alternative route, if you manage Klipper installations with KIAUH, is to find TMC autotune in the community extensions section.

Automatic updates are then wired into `moonraker.conf`:

```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
```

Note the `channel: dev` setting, since it means the update manager tracks the development branch rather than a release tag.

## One [autotune_tmc] section per motor, existing sections untouched

The configuration model is additive. You add an `[autotune_tmc]` section for each stepper motor you want tuned, naming the motor from the motor database, and your existing `[stepper_*]` and `[tmc* stepper_*]` sections stay as they are:

```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
```

The template in `docs/example.cfg` in the repository serves the same purpose for people who prefer to start from a working file. The advantage of the additive model is that the extension can compute its own register values without you having to hand edit the TMC driver sections.

The cost of that convenience is that the driver sections have to be reduced to a known state. They should contain the pins, the currents including run current, hold current and, on Klipper versions that support it, homing current, plus `interpolate: true`. Any other register settings and sensorless homing values should be commented out, kept for reference but not active. This is a departure from the Klipper documentation's own recommendation against interpolation, and the project explains why: that advice is most relevant with low microstep counts and the default driver configuration, while autotune gives better results dimensionally and in quality by using interpolation and as many microsteps as feasible.

## Sensorless homing thresholds that gcode cannot reach

Sensorless homing is where this extension has a sharp edge. The `sg4_thrs` values for TMC2209 and TMC2260, and the `sgt` values for TMC5160, TMC2240, TMC2130 and TMC2660, must be adjusted inside the autotune sections specifically. Attempting the same change through gcode or through the tmc driver sections produces no error message and has no effect, because the autotuning algorithm overwrites them.

That silent override is a genuine failure mode. A user who sets a threshold where they expect it to be read, sees no complaint, and gets different behaviour, has no signal that anything went wrong.

Speed is the second lever. The project states that sensorless homing is known to work with autotuning enabled on TMC2209, TMC2240 and TMC5160, provided you home fast enough, with `homing_speed` numerically greater than `rotation_distance` for those axes using sensorless homing. If tuning proves challenging, the guidance is to increase the homing speed, since sensorless homing becomes much more sensitive at higher speeds. The suggested starting points, given a `rotation_distance` of 40, are 40 to 60 mm/s for TMC2209 and TMC2260 drivers and 80 to 100 mm/s for TMC2130, TMC2240, TMC2660 and TMC5160 drivers. And the project repeats the general warning: be very careful when trying sensorless homing for the first time.

## Which drivers are trusted, and which are not

Official support covers TMC2209, TMC2240 and TMC5160. Support for TMC2130, TMC2208 and TMC2660 may work, but the project calls it completely untested. That distinction should drive your adoption decision more than any feature list, because the tuning algorithm's output quality depends on knowing how each driver behaves, and untested is not the same as unsupported so much as unknown.

Board layout is the second variable, and the project handles it with a short list of known setups rather than an automatic detection: BTT TMC 2240 stepsticks use `diag0_pin`, BTT TMC 5160 stepsticks use `diag1_pin`, and MKS TMC 2240 stepsticks use `diag0_pin`. The instruction is to check the pinouts of your own stepper driver boards, because there might be unusual boards out there.

Beyond the officially supported set, the per section parameters let you nudge the result. `extra_hysteresis` adds hysteresis to reduce humming and vibration at low to medium speeds, with a warning that too much brings more chopper noise and more heat. `tbl` sets comparator blank time, where 1 or 2 suits most typical applications but higher capacitive loads may need 3, and lower values let StealthChop regulate to lower coil currents. `toff` sets the chopper off time and limits the maximum chopper frequency, and when set to 0 the value is computed automatically by the algorithm, with high motor velocities sometimes benefiting from forcing it to 1 or 2.

## A single release candidate, and a branch that keeps moving

The licensing is GPL-3.0, and the repository's own `LICENSE` file is the text to read if that matters to your distribution. The project ships a `ruff.toml`, so the Python sources are linted with Ruff, and there is a `docs/` directory holding the example configuration.

What is harder to interpret is the release state. The only release tag listed for this project is v0.2.0, marked as a release candidate and dated 2023-06-19, while the last push to the repository was on 2026-08-22. The repository is not archived, so work continues, and the `moonraker.conf` snippet puts the update manager on the `dev` channel, which is consistent with a project whose users track the main branch rather than waiting for tags. Practically, that means there is no released version to pin, and upgrades arrive when the update manager pulls `main`.

Whether that trade suits you depends on your tolerance for change. A printer running unattended wants stability, while the extension's value is that the tuning logic keeps being improved. The one line in the project that applies to both cases is the cooling note: the drivers can run hotter, so proper cooling measures must be implemented.

## Conclusion

Adopt klipper_tmc_autotune if you run TMC2209, TMC2240 or TMC5160 drivers on Klipper and you want per motor register values derived from real motor constants instead of copied defaults, and you are willing to read the diagnostics before each print. Do not adopt it for TMC2130, TMC2208 or TMC2660, which the project says are completely untested, nor for anyone who needs the `autoswitch` tuning goal in production, since the project calls that choice experimental and warns of unwanted behaviour, noise disturbances and lost steps. Verify first that your board's diagnostic pin matches the known layouts, that `sg4_thrs` or `sgt` is set inside the `[autotune_tmc]` section, and that your steppers have adequate cooling, because the project states that autotuning can make the drivers run hotter.

## FAQ

### How do I install klipper_tmc_autotune on my Klipper printer?

Run the installation script over SSH on the Raspberry Pi, which downloads the repository to your home directory and symlinks the files in the Klipper extra folder: `wget -O - https://raw.githubusercontent.com/andrewmcgr/klipper_tmc_autotune/main/install.sh | bash`. If you use KIAUH, the extension is listed in its community extensions section.

### Which TMC drivers does klipper_tmc_autotune support?

Official support covers the TMC2209, TMC2240 and TMC5160. Support for TMC2130, TMC2208 and TMC2660 may work, but the project describes it as completely untested.

### Why are my sensorless homing threshold changes not taking effect?

The `sg4_thrs` and `sgt` values must be set in the `[autotune_tmc]` section rather than in the tmc driver sections or via gcode, because the autotuning algorithm overrides them, and no error message is produced when you change them elsewhere.

### What does the tuning_goal parameter do in klipper_tmc_autotune?

It selects how the driver is tuned using StealthChop and tailored parameters. `auto` applies `performance` for the X and Y axes and `silent` for the Z axis and extruder unless the motor is very small, and `autoswitch` enables real time switching between silent and performance modes but is described as highly experimental and is recommended against.

### Does autotuning make my TMC drivers run hotter?

Yes. The project states that autotuning can improve efficiency and let motors run cooler and consume less power, but that the process can also cause the TMC drivers to run hotter, so proper cooling measures must be implemented.

## Sources

- [andrewmcgr/klipper_tmc_autotune on GitHub](https://github.com/andrewmcgr/klipper_tmc_autotune)
- [Issues](https://github.com/andrewmcgr/klipper_tmc_autotune/issues)
- [License: GPL-3.0](https://github.com/andrewmcgr/klipper_tmc_autotune/blob/main/LICENSE)
- [README](https://github.com/andrewmcgr/klipper_tmc_autotune/blob/main/README.md)
- [Releases](https://github.com/andrewmcgr/klipper_tmc_autotune/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/andrewmcgr-klipper-tmc-autotune