docs: Warn against using the TMC2208 in standalone mode

Signed-off-by: Kevin O'Connor <kevin@koconnor.net>

3 files changed, 135 insertions, 10 deletions

diff --git a/docs/FAQ.md b/docs/FAQ.md
index 0f1eea53..bde845b2 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -265,17 +265,46 @@ configured in Marlin.
 
 ### My TMC motor driver turns off in the middle of a print
 
-There have been reports of some TMC drivers being disabled in the
-middle of a print. (In particular, with the TMC2208 driver.) When this
-issue occurs, the stepper associated with the driver moves freely,
-while the print continues.
+Short answer: Do not use the TMC2208 driver in "standalone mode" with
+Klipper! Do not use the TMC2224 driver in "stealthchop standalone
+mode" with Klipper!
 
-It is believed this may be due to "over current" detection within the
-TMC driver. Trinamic has indicated that this could occur if the driver
-is in "stealthChop mode" and an abrupt velocity change occurs. If you
-experience this problem during homing, consider using a slower homing
-speed. If you experience this problem in the middle of a print,
-consider using a lower square_corner_velocity setting.
+Long answer: Klipper implements very precise timing.
+
+![tmc2208](img/tmc2208.svg.png)
+
+In the above picture, if Klipper is requested to move along the red
+line and if each black line represents the nominal location to step a
+stepper, then in the middle of that movement Klipper will arrange to
+take a step, change the step direction, and then step back. Klipper
+can perform this step, direction change, and step back in a very small
+amount of time.
+
+It is our current understanding that the TMC2208 and TMC2224 will
+react poorly to this when they are in "stealthchop" mode. (It is not
+believed any other TMC drivers are impacted.) It is believed that when
+the driver sees the two step requests in a small time frame that it
+dramatically increases current in anticipation of high acceleration.
+That high current can trip the driver's internal "over current"
+detection which causes the driver to disable itself.
+
+This pattern of steps can occur on all stepper motors and on all
+robot kinematics.
+
+The TMC2208 and TMC2224 do work well with Klipper when run-time
+configuration mode is used (that is, when a wire is routed from the
+micro-controller to the PDN-UART pin and the printer config file has a
+corresponding [tmc2208] config section). When using run-time
+configuration, either configure the drivers to use "spreadcycle mode"
+or configure them to use "stealthchop mode" with a reasonable
+"stealthchop threshold". If one wishes to exclusively use
+"stealthchop" mode with run-time UART configuration then make sure the
+stealthchop_threshold is no more than about 10% greater than the
+maximum velocity of the given axis. It is speculated that with a
+reasonable stealthchop threshold, then if Klipper sends a "step,
+direction change, step back" sequence, the driver will briefly
+transition from stealthchop mode, to spreadcycle mode, and back to
+stealthchop mode, which should be harmless.
 
 ### I keep getting random "Lost communication with MCU" errors
 
diff --git a/docs/img/tmc2208.svg b/docs/img/tmc2208.svg
new file mode 100644
index 00000000..0a2d8c6e
--- /dev/null
+++ b/docs/img/tmc2208.svg
@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:osb="http://www.openswatchbook.org/uri/2009/osb"
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="210mm"
+   height="297mm"
+   viewBox="0 0 210 297"
+   version="1.1"
+   id="svg8"
+   inkscape:export-filename="/home/kevin/bitmap.png"
+   inkscape:export-xdpi="96"
+   inkscape:export-ydpi="96"
+   inkscape:version="0.92.3 (2405546, 2018-03-11)"
+   sodipodi:docname="move-desc.svg">
+  <defs
+     id="defs2">
+    <linearGradient
+       id="linearGradient4609"
+       osb:paint="solid">
+      <stop
+         style="stop-color:#ffffff;stop-opacity:1;"
+         offset="0"
+         id="stop4607" />
+    </linearGradient>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="1"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.98994949"
+     inkscape:cx="429.37872"
+     inkscape:cy="710.19584"
+     inkscape:document-units="mm"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:pagecheckerboard="false"
+     inkscape:window-width="1182"
+     inkscape:window-height="699"
+     inkscape:window-x="237"
+     inkscape:window-y="79"
+     inkscape:window-maximized="0" />
+  <metadata
+     id="metadata5">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 40.398947,86.676759 169.6668,87.432709"
+       id="path4518-3"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 40.764446,101.81154 170.0323,102.56749"
+       id="path4518-6"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 40.702855,116.60959 129.267855,0.75595"
+       id="path4518-7"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 40.465706,131.82822 129.267854,0.75595"
+       id="path4518-5"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#fc0000;stroke-width:0.29816988px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 66.015573,81.729992 C 95.790705,139.21551 118.11752,118.84351 138.71287,80.372264"
+       id="path4613"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
+  </g>
+</svg>
diff --git a/docs/img/tmc2208.svg.png b/docs/img/tmc2208.svg.png
new file mode 100644
index 00000000..f46a6f8d
--- /dev/null
+++ b/docs/img/tmc2208.svg.png