diff --git a/docs/Config_Reference.md b/docs/Config_Reference.md index 8ebb511c..7259d998 100644 --- a/docs/Config_Reference.md +++ b/docs/Config_Reference.md @@ -2585,6 +2585,10 @@ pins: # TMC stepper driver configuration +Configuration of Trinamic stepper motor drivers in UART/SPI mode. +Additional information is in the [TMC Drivers guide](TMC_Drivers.md) +and in the [command reference](G-Codes.md#tmc-stepper-drivers). + ## [tmc2130] Configure a TMC2130 stepper motor driver via SPI bus. To use this @@ -2652,8 +2656,7 @@ run_current: # pin which may be used as the stepper's endstop_pin. Doing this # enables "sensorless homing". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable -# sensorless homing. See docs/Sensorless_Homing.md for details on -# how to configure this. +# sensorless homing. ``` ## [tmc2208] @@ -2918,8 +2921,7 @@ run_current: # pin which may be used as the stepper's endstop_pin. Doing this # enables "sensorless homing". (Be sure to also set driver_SGT to an # appropriate sensitivity value.) The default is to not enable -# sensorless homing. See docs/Sensorless_Homing.md for details on -# how to configure this. +# sensorless homing. ``` # Run-time stepper motor current configuration diff --git a/docs/G-Codes.md b/docs/G-Codes.md index 0b0ad713..772815fc 100644 --- a/docs/G-Codes.md +++ b/docs/G-Codes.md @@ -474,7 +474,7 @@ enabled: carriage. It is typically invoked from the activate_gcode and deactivate_gcode fields in a multiple extruder configuration. -## TMC2130, TMC2660, TMC2208, TMC2209 and TMC5160 +## TMC stepper drivers The following commands are available when any of the [tmcXXXX config sections](Config_Reference.md#tmc-stepper-driver-configuration) @@ -486,14 +486,14 @@ are enabled: turned off then back on. - `SET_TMC_CURRENT STEPPER= CURRENT= HOLDCURRENT=`: This will adjust the run and hold currents of the TMC driver. - HOLDCURRENT is applicable only to the tmc2130, tmc2208, tmc2209 and tmc5160. -- `SET_TMC_FIELD STEPPER= FIELD= VALUE=`: This will - alter the value of the specified register field of the TMC driver. - This command is intended for low-level diagnostics and debugging only because - changing the fields during run-time can lead to undesired and potentially - dangerous behavior of your printer. Permanent changes should be made using - the printer configuration file instead. No sanity checks are performed for the - given values. + (HOLDCURRENT is not applicable to tmc2660 drivers.) +- `SET_TMC_FIELD STEPPER= FIELD= VALUE=`: This + will alter the value of the specified register field of the TMC + driver. This command is intended for low-level diagnostics and + debugging only because changing the fields during run-time can lead + to undesired and potentially dangerous behavior of your printer. + Permanent changes should be made using the printer configuration + file instead. No sanity checks are performed for the given values. ## Endstop adjustments by stepper phase diff --git a/docs/Overview.md b/docs/Overview.md index b67b3e6f..abe1a3b1 100644 --- a/docs/Overview.md +++ b/docs/Overview.md @@ -42,8 +42,8 @@ communication with the Klipper developers. - [Slicers](Slicers.md): Configure "slicer" software for Klipper. - [Command Templates](Command_Templates.md): G-Code macros and conditional evaluation. -- [Sensorless homing](Sensorless_Homing.md): Configuring tmc2130 - sensorless homing. +- [TMC Drivers](TMC_Drivers.md): Using Trinamic stepper motor drivers + with Klipper. - [Skew correction](skew_correction.md): Adjustments for axes not perfectly square. - [G-Codes](G-Codes.md): Information on commands supported by Klipper. diff --git a/docs/Sensorless_Homing.md b/docs/TMC_Drivers.md similarity index 56% rename from docs/Sensorless_Homing.md rename to docs/TMC_Drivers.md index 68d3d3bb..2cd9069d 100644 --- a/docs/Sensorless_Homing.md +++ b/docs/TMC_Drivers.md @@ -1,3 +1,26 @@ +This document provides information on using Trinamic stepper motor +drivers in SPI/UART mode on Klipper. + +Klipper can also use Trinamic drivers in their "standalone mode". +However, when the drivers are in this mode, no special Klipper +configuration is needed and the advanced Klipper features discussed in +this document are not available. + +In addition to this document, be sure to review the [TMC driver config +reference](Config_Reference.md#tmc-stepper-driver-configuration). + +# Enabling "Stealthchop" mode + +By default, Klipper places the TMC drivers in "spreadcycle" mode. If +the driver supports "stealthchop" then it can be enabled by adding +`stealthchop_threshold: 999999` to the TMC config section. + +It is recommended to always use "spreadcycle" mode (by not specifying +`stealthchop_threshold`) or to always use "stealthchop" mode (by +setting `stealthchop_threshold` to 999999). Unfortunately, the drivers +often produce poor and confusing results if the mode changes while the +motor is at a non-zero velocity. + # Sensorless Homing Sensorless homing allows to home an axis without the need for a @@ -35,7 +58,7 @@ well, homing the Z axis is generally not accurate enough and results in inconsistent first layer height. Homing a delta printer sensorless is not advisable due to missing accuracy. -Further, the stall detection of the stepper driver is dependant on the +Further, the stall detection of the stepper driver is dependent on the mechanical load on the motor, the motor current and the motor temperature (coil resistance). @@ -53,7 +76,7 @@ To enable sensorless homing add a section to configure the TMC stepper driver to your `printer.cfg`. In this guide we'll be using a TMC2130. The configuration however is -simailar to the other TMCs with StallGuard: +similar to the other TMCs with StallGuard: ``` [tmc2130 stepper_x] @@ -67,7 +90,7 @@ driver_SGT: # tuning value for sensorless homing The above snippet configures a TMC2130 for the stepper on the X axis. Make sure to fill in the missing values based on your configuration. -The `driver_SGT` value describes the threshhold when the driver +The `driver_SGT` value describes the threshold when the driver reports a stall. Values have to be in between -64 (most sensitive) and 64 (least sensitive). On some TMCs like the TMC2209 this value doesn't exist in this form as the behavior is different to the TMC2130. In the @@ -124,40 +147,6 @@ ones needed to set up sensorless homing. There are many other options to configure on a TMC2130, make sure to take a look at [config reference](Config_Reference.md#tmc2130) for all the available options. -## Testing of SPI/UART communication - -Now that the stepper driver is configured, let's make sure that -Klipper can communicate with the TMC2130 by sending the following -extended G-Code command to the printer: - -``` -DUMP_TMC stepper=stepper_x -``` - -This command tells Klipper to read a few registers via SPI from the -TMC2130. If everything works correctly, the output should look similar -to this (in OctoPrint terminal tab): - -``` -Send: DUMP_TMC stepper=stepper_x -Recv: // GCONF: 00000004 -Recv: // GSTAT: 00000001 -Recv: // IOIN: 11000078 -Recv: // TSTEP: 000fffff -Recv: // XDIRECT: 00000000 -Recv: // MSCNT: 00000010 -Recv: // MSCURACT: 00f60018 -Recv: // CHOPCONF: 15008384 -Recv: // DRV_STATUS: 800d0000 -Recv: // PWM_SCALE: 00000000 -Recv: // LOST_STEPS: 00000000 -``` - -The actual register values might differ based the configuration of -your TMC2130. If the register values are all `ffffffff` or look -otherwise bogus (for example, `LOST_STEPS` should be always `00000000` -here) make sure that the SPI is wired and configured correctly. - ## Homing and Tuning Let's try the first sensorless homing now. It will likely not work as @@ -184,7 +173,7 @@ G28 X If the axis stopped early (first outcome), the stepper driver detected a motor stall even though there was none. To trigger stall detection at a higher load, increase the value of `driver_SGT` (for example from -0 to 5). The values can be any interger between `-64` and `63`. The +0 to 5). The values can be any integer between `-64` and `63`. The higher the value, the later it triggers stall detection. If your axis did not stop (third outcome), the stepper driver was not @@ -199,3 +188,95 @@ into the mechanical limit, try to decrease the value by 1 or 2. At this point, your axis should be able to home based on the stall detection of the TMC2130. Congratulations! You can now proceed with the next axis of your printer. + +# Querying and diagnosing driver settings + +The `[DUMP_TMC command](G-Codes.md#tmc-stepper-drivers) is a useful +tool when configuring and diagnosing the drivers. It will report all +fields configured by Klipper as well as all fields that can be queried +from the driver. + +All of the reported fields are defined in the Trinamic datasheet for +each driver. These datasheets can be found on the [Trinamic +website](https://www.trinamic.com/). Obtain and review the Trinamic +datasheet for the driver to interpret the results of DUMP_TMC. + +# Configuring driver_XXX settings + +Klipper supports configuring many low-level driver fields using +`driver_XXX` settings. The [TMC driver config +reference](Config_Reference.md#tmc-stepper-driver-configuration) has +the full list of fields available for each type of driver. + +In addition, almost all fields can be modified at run-time using the +[SET_TMC_FIELD command](G-Codes.md#tmc-stepper-drivers). + +Each of these fields is defined in the Trinamic datasheet for each +driver. These datasheets can be found on the [Trinamic +website](https://www.trinamic.com/). + +Note that the Trinamic datasheets sometime use wording that can +confuse a high-level setting (such as "hysteresis end") with a +low-level field value (eg, "HEND"). In Klipper, `driver_XXX` and +SET_TMC_FIELD always set the low-level field value that is actually +written to the driver. So, for example, if the Trinamic datasheet +states that a value of 3 must be written to the HEND field to obtain a +"hysteresis end" of 0, then set `driver_HEND=3` to obtain the +high-level value of 0. + +# Common Questions + +## Can I use stealthchop mode on an extruder with pressure advance? + +Many people successfully use "stealthchop" mode with Klipper's +pressure advance. Klipper implements [smooth pressure +advance](Kinematics.md#pressure-advance) which does not introduce any +instantaneous velocity changes. + +However, "stealthchop" mode may produce lower motor torque and/or +produce higher motor heat. It may or may not be an adequate mode for +your particular printer. + +## I keep getting "Unable to read tmc uart 'stepper_x' register IFCNT" errors? + +This occurs when Klipper is unable to communicate with a tmc2208 or +tmc2209 driver. + +Make sure that the motor power is enabled, as the stepper motor driver +generally needs motor power before it can communicate with the +micro-controller. + +Otherwise, this error is typically the result of incorrect UART pin +wiring or an incorrect Klipper configuration of the UART pin settings. + +## I keep getting "Unable to write tmc spi 'stepper_x' register ..." errors? + +This occurs when Klipper is unable to communicate with a tmc2130 or +tmc5160 driver. + +Make sure that the motor power is enabled, as the stepper motor driver +generally needs motor power before it can communicate with the +micro-controller. + +Otherwise, this error is typically the result of incorrect SPI wiring, +an incorrect Klipper configuration of the SPI settings, or an +incomplete configuration of devices on an SPI bus. + +Note that if the driver is on a shared SPI bus with multiple devices +then be sure to fully configure every device on that shared SPI bus in +Klipper. If a device on a shared SPI bus is not configured, then it +may incorrectly respond to commands not intended for it and corrupt +the communication to the intended device. If there is a device on a +shared SPI bus that can not be configured in Klipper, then use a +[static_digital_output config +section](Config_Reference.md#static_digital_output) to set the CS pin +of the unused device high (so that it will not attempt to use the SPI +bus). The board's schematic is often a useful reference for finding +which devices are on an SPI bus and their associated pin settings. + +## How do I tune spreadcycle/coolstep/etc. mode on my drivers? + +The [Trinamic website](https://www.trinamic.com/) has guides on +configuring the drivers. These guides are often technical, low-level, +and may require specialized hardware. Regardless, they are the best +source of information.