docs: Add initial Pressure Advance tuning document

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

8 files changed, 324 insertions, 7 deletions

diff --git a/docs/Kinematics.md b/docs/Kinematics.md
index 924d1291..07ed3a1b 100644
--- a/docs/Kinematics.md
+++ b/docs/Kinematics.md
@@ -234,9 +234,9 @@ the pressure necessary to extrude is dominated by the flow rate
 through the nozzle orifice (as in
 [Poiseuille law](https://en.wikipedia.org/wiki/Poiseuille_law)). The
 details of the above physics are not important - only that the
-relationship between pressure and flow rate is linear. It is expected
-that an appropriate "pressure advance" value for a particular filament
-and extruder will be determined experimentally.
+relationship between pressure and flow rate is linear. See the
+[pressure advance](Pressure_Advance.md) document for information on
+how to find the pressure advance coefficients.
 
 Once configured, Klipper will push in an additional amount of filament
 during acceleration and retract that additional filament during
diff --git a/docs/Overview.md b/docs/Overview.md
index 14fb5bd3..da72f5f0 100644
--- a/docs/Overview.md
+++ b/docs/Overview.md
@@ -1,9 +1,12 @@
 See [installation](Installation.md) for information on compiling,
 installing, and running Klipper. Read [features](Features.md) for a
-high-level description of useful capabilities. The
-[kinematics](Kinematics.md) document provides information on how
-movement is implemented. The history of releases is available at
-[releases](Releases.md).
+high-level description of useful capabilities. The history of releases
+is available at [releases](Releases.md).
+
+See the [Pressure Advance](Pressure_Advance.md) document for
+information on tuning the pressure advance system. The
+[kinematics](Kinematics.md) document provides high level information
+on how movement is implemented in Klipper.
 
 There are also several documents available for developers interested
 in understanding how Klipper works:
diff --git a/docs/Pressure_Advance.md b/docs/Pressure_Advance.md
new file mode 100644
index 00000000..84372e0c
--- /dev/null
+++ b/docs/Pressure_Advance.md
@@ -0,0 +1,74 @@
+This document provides information on tuning the "pressure advance"
+configuration variables for a particular nozzle and filament. The
+pressure advance feature can be helpful in reducing ooze. For more
+information on how pressure advance is implemented see the
+[kinematics](Kinematics.md) document.
+
+Tuning pressure advance
+=======================
+
+Pressure advance does two useful things - it reduces ooze during
+non-extrude moves and it reduces blobbing during cornering. This guide
+uses the second feature (reducing blobbing during cornering) as a
+mechanism for measuring and tuning the pressure advance configuration.
+
+Start by changing the extruder section of the config file so that
+pressure_advance is set to 0.0. (Make sure to issue a RESTART command
+after each update to the config file so that the new configuration
+takes effect.) Then print at least 10 layers of a large hollow square
+at high speed (eg, 100mm/s). See **docs/prints/square.stl** file for
+an STL file that one may use. While the object is printing, make a
+note of which direction the head is moving during external
+perimeters. What many people see here is blobbing occurring at the
+corners - extra filament at the corner in the direction the head
+travels followed by a possible lack of filament on the side
+immediately after that corner:
+
+![corner-blob](img/corner-blob.jpg)
+
+This blobbing is the result of pressure in the extruder being released
+as a blob when the head slows down to corner.
+
+The next step is to set pressure_advance_lookahead_time to 0.0, slowly
+increase pressure_advance (eg, start with 0.05), and reprint the test
+object. (Be sure to issue RESTART between each config change.)  The
+goal is to attempt to eliminate the blobbing during cornering. (With
+pressure advance, the extruder will retract when the head slows down,
+thus countering the pressure buildup and ideally eliminate the
+blobbing.) If a test run is done with a pressure_advance setting that
+is too high, one typically sees a dimple in the corner followed by
+possible blobbing after the corner (too much filament is retracted
+during slow down and then too much filament is extruded during the
+following speed up after cornering):
+
+![corner-dimple](img/corner-dimple.jpg)
+
+The goal is to find the smallest pressure_advance value that results
+in good quality corners:
+
+![corner-good](img/corner-good.jpg)
+
+Typical pressure_advance values are between 0.05 and 0.20 (the high
+end usually only with bowden extruders).
+
+Once a good pressure_advance value is found, return
+pressure_advance_lookahead_time to its default (0.010). This parameter
+controls how far in advance to check if a head slow-down is
+immediately followed by a speed-up - it reduces pointless pressure
+changes in the head. It's possible to tune this - higher values will
+decrease the number of pressure changes in the nozzle at the expense
+of permitting more blobbing during cornering. (Tuning this value is
+unlikely to impact ooze.) The default of 10ms should work well on most
+printers.
+
+Although this tuning exercise directly improves the quality of
+corners, it's worth remembering that a good pressure advance
+configuration can reduce ooze throughout the print.
+
+Finally, once pressure_advance is tuned in Klipper, it may still be
+useful to configure a small retract value in the slicer (eg, 0.75mm)
+and to utilize the slicer's "wipe on retract option" if available.
+These slicer settings may help counteract ooze caused by filament
+cohesion (filament pulled out of the nozzle due to the stickiness of
+the plastic). It is recommended to disable the slicer's "z-lift on
+retract" option.
diff --git a/docs/img/corner-blob.jpg b/docs/img/corner-blob.jpg
new file mode 100644
index 00000000..6dd529a0
--- /dev/null
+++ b/docs/img/corner-blob.jpg
diff --git a/docs/img/corner-dimple.jpg b/docs/img/corner-dimple.jpg
new file mode 100644
index 00000000..14cae0c4
--- /dev/null
+++ b/docs/img/corner-dimple.jpg
diff --git a/docs/img/corner-good.jpg b/docs/img/corner-good.jpg
new file mode 100644
index 00000000..687c73aa
--- /dev/null
+++ b/docs/img/corner-good.jpg
diff --git a/docs/prints/square.scad b/docs/prints/square.scad
new file mode 100644
index 00000000..fb68cb09
--- /dev/null
+++ b/docs/prints/square.scad
@@ -0,0 +1,14 @@
+// Test square
+//
+// Generate STL using OpenSCAD:
+//   openscad square.scad -o square.stl
+
+square_width = 5;
+square_size = 60;
+square_height = 5;
+
+difference() {
+  cube([square_size, square_size, square_height]);
+  translate([square_width, square_width, -1])
+    cube([square_size-2*square_width, square_size-2*square_width, square_height+2]);
+}
diff --git a/docs/prints/square.stl b/docs/prints/square.stl
new file mode 100644
index 00000000..9b4b8676
--- /dev/null
+++ b/docs/prints/square.stl
@@ -0,0 +1,226 @@
+solid OpenSCAD_Model
+  facet normal -1 0 0
+    outer loop
+      vertex 0 0 0
+      vertex 0 60 5
+      vertex 0 60 0
+    endloop
+  endfacet
+  facet normal -1 -0 0
+    outer loop
+      vertex 0 60 5
+      vertex 0 0 0
+      vertex 0 0 5
+    endloop
+  endfacet
+  facet normal 0 0 1
+    outer loop
+      vertex 60 60 5
+      vertex 55 55 5
+      vertex 60 0 5
+    endloop
+  endfacet
+  facet normal 0 0 1
+    outer loop
+      vertex 60 60 5
+      vertex 5 55 5
+      vertex 55 55 5
+    endloop
+  endfacet
+  facet normal 0 0 1
+    outer loop
+      vertex 5 55 5
+      vertex 0 60 5
+      vertex 5 5 5
+    endloop
+  endfacet
+  facet normal -0 0 1
+    outer loop
+      vertex 0 60 5
+      vertex 5 55 5
+      vertex 60 60 5
+    endloop
+  endfacet
+  facet normal -0 0 1
+    outer loop
+      vertex 55 5 5
+      vertex 60 0 5
+      vertex 55 55 5
+    endloop
+  endfacet
+  facet normal -0 0 1
+    outer loop
+      vertex 5 5 5
+      vertex 60 0 5
+      vertex 55 5 5
+    endloop
+  endfacet
+  facet normal 0 0 1
+    outer loop
+      vertex 5 5 5
+      vertex 0 0 5
+      vertex 60 0 5
+    endloop
+  endfacet
+  facet normal 0 0 1
+    outer loop
+      vertex 0 0 5
+      vertex 5 5 5
+      vertex 0 60 5
+    endloop
+  endfacet
+  facet normal 1 -0 0
+    outer loop
+      vertex 60 0 5
+      vertex 60 60 0
+      vertex 60 60 5
+    endloop
+  endfacet
+  facet normal 1 0 0
+    outer loop
+      vertex 60 60 0
+      vertex 60 0 5
+      vertex 60 0 0
+    endloop
+  endfacet
+  facet normal 0 1 -0
+    outer loop
+      vertex 60 60 0
+      vertex 0 60 5
+      vertex 60 60 5
+    endloop
+  endfacet
+  facet normal 0 1 0
+    outer loop
+      vertex 0 60 5
+      vertex 60 60 0
+      vertex 0 60 0
+    endloop
+  endfacet
+  facet normal 0 0 -1
+    outer loop
+      vertex 60 0 0
+      vertex 55 5 0
+      vertex 60 60 0
+    endloop
+  endfacet
+  facet normal 0 0 -1
+    outer loop
+      vertex 60 0 0
+      vertex 5 5 0
+      vertex 55 5 0
+    endloop
+  endfacet
+  facet normal -0 0 -1
+    outer loop
+      vertex 5 5 0
+      vertex 0 0 0
+      vertex 5 55 0
+    endloop
+  endfacet
+  facet normal 0 0 -1
+    outer loop
+      vertex 0 0 0
+      vertex 5 5 0
+      vertex 60 0 0
+    endloop
+  endfacet
+  facet normal 0 0 -1
+    outer loop
+      vertex 55 55 0
+      vertex 60 60 0
+      vertex 55 5 0
+    endloop
+  endfacet
+  facet normal 0 0 -1
+    outer loop
+      vertex 5 55 0
+      vertex 60 60 0
+      vertex 55 55 0
+    endloop
+  endfacet
+  facet normal 0 0 -1
+    outer loop
+      vertex 5 55 0
+      vertex 0 60 0
+      vertex 60 60 0
+    endloop
+  endfacet
+  facet normal 0 0 -1
+    outer loop
+      vertex 0 60 0
+      vertex 5 55 0
+      vertex 0 0 0
+    endloop
+  endfacet
+  facet normal 0 -1 0
+    outer loop
+      vertex 0 0 0
+      vertex 60 0 5
+      vertex 0 0 5
+    endloop
+  endfacet
+  facet normal 0 -1 -0
+    outer loop
+      vertex 60 0 5
+      vertex 0 0 0
+      vertex 60 0 0
+    endloop
+  endfacet
+  facet normal 1 -0 0
+    outer loop
+      vertex 5 5 5
+      vertex 5 55 0
+      vertex 5 55 5
+    endloop
+  endfacet
+  facet normal 1 0 0
+    outer loop
+      vertex 5 55 0
+      vertex 5 5 5
+      vertex 5 5 0
+    endloop
+  endfacet
+  facet normal -1 0 0
+    outer loop
+      vertex 55 5 0
+      vertex 55 55 5
+      vertex 55 55 0
+    endloop
+  endfacet
+  facet normal -1 -0 0
+    outer loop
+      vertex 55 55 5
+      vertex 55 5 0
+      vertex 55 5 5
+    endloop
+  endfacet
+  facet normal 0 1 -0
+    outer loop
+      vertex 55 5 0
+      vertex 5 5 5
+      vertex 55 5 5
+    endloop
+  endfacet
+  facet normal 0 1 0
+    outer loop
+      vertex 5 5 5
+      vertex 55 5 0
+      vertex 5 5 0
+    endloop
+  endfacet
+  facet normal 0 -1 0
+    outer loop
+      vertex 5 55 0
+      vertex 55 55 5
+      vertex 5 55 5
+    endloop
+  endfacet
+  facet normal 0 -1 -0
+    outer loop
+      vertex 55 55 5
+      vertex 5 55 0
+      vertex 55 55 0
+    endloop
+  endfacet
+endsolid OpenSCAD_Model