blog/data/2022-07-16-linuxcnc-pid-autotuning.txt

   1 Title: Automatic LinuxCNC servo PID tuning?
   2 Tags: english, debian, 3d-printer, robot
   3 Date: 2022-07-16 21:00
   4 Publish: 2022-07-16 21:00
   5
   6 <p>While working on a CNC with servo motors controlled by the
   7 <a href="https://en.wikipedia.org/wiki/LinuxCNC">LinuxCNC</a>
   8 <a href="https://en.wikipedia.org/wiki/PID_controller">PID
   9 controller</a>, I had to learn how to tune the collection of values
  10 that control this mathematical machinery.  It proved to be a lot
  11 harder than I hoped, and I still have not succeeded in getting the Z
  12 PID controller to successfully defy gravity.  But while climbing up
  13 this rather steep learning curve, I discovered that some motor control
  14 systems are able to tune their PID controllers.  I got the impression
  15 from the documentation that LinuxCNC were not.  This proved to be not
  16 true</p>
  17
  18 <p>The LinuxCNC
  19 <a href="http://linuxcnc.org/docs/html/man/man9/pid.9.html">pid
  20 component</a> is the recommended PID controller to use.  It uses eight
  21 values Pgain, Igain, Dgain, bias, FF0, FF1, FF2 and FF3 to calculate
  22 the output value, and all of these need to have a sensible value for
  23 the controller to behave properly.  Note, there are even more values
  24 involved in more edge cases.  In my case I need the X, Y and Z axes to
  25 follow the requested path with little error.  This has proved quite a
  26 challenge for someone who have never tuned a PID controller before,
  27 but there is some help to be found.
  28
  29 <p>I discovered that included in LinuxCNC was this old PID component
  30 at_pid claiming to have auto tuning capabilities.  Sadly it had been
  31 neglected since 2011, and could not be used as a plug in replacement
  32 for the default pid component.  One would have to rewriting the
  33 LinuxCNC HAL setup to test at_pid.  This was rather sad, when I wanted
  34 to quickly test auto tuning to see if it did a better job than me at
  35 figuring out good P, I and D values to use.</p>
  36
  37 <p>So I decided to have a look if the situation could be improved.
  38 This involved trying to understand the code and history of the pid and
  39 at_pid components.  Apparently they had a common ancestor, as code
  40 structure, comments and variable names were quite close to each other.
  41 But this was not reflected in the git history.  My guess is that the
  42 author of at_pid took a version of pid.c, rewrote it to follow the
  43 structure he wished pid.c to have, then added support for auto tuning
  44 and then committed it into the LinuxCNC repository.  This made it
  45 harder to figure out which part of the code were relevant to the auto
  46 tuning, and which part of the code needed to be updated to work the
  47 same way as the current pid.c implementation.  I started by trying to
  48 isolate relevant changes in pid.c, and applying them to at_pid.  My
  49 aim was to make sure the at_pid component could replace the pid
  50 component with a simple change in the HAL setup loadrt line, without
  51 having to "rewire" the rest of the HAL configuration.  After a few
  52 hours following this approach, I had learned quite a lot about the
  53 code structure of both components, while concluding I was heading down
  54 the wrong rabbit hole, and should get back to the surface and find a
  55 different path.</p>
  56
  57 <p>For the second attempt, I decided to throw away all the PID control
  58 related part of the original at_pid.c, and instead isolate and lift
  59 the auto tuning part of the code and inject it into a copy of pid.c.
  60 This ensured compatibility with the current pid component, while
  61 adding auto tuning as a run time option.  To make it easier to identify
  62 the relevant parts in the future, I wrapped all the auto tuning code
  63 with '#ifdef AUTO_TUNER'.  The end result behave just like the current
  64 pid component by default, as the code is identical.  The
  65 <a href="https://github.com/LinuxCNC/linuxcnc/pull/1820">end result
  66 entered the LinuxCNC master branch</a> a few days ago.  To enable auto
  67 tuning, one need to set a few HAL pins in the PID component.  The most
  68 important ones are tune-effort, tune-mode and tune-start.  But lets
  69 take a step back, and see what the auto tuning code will do.</p>
  70
  71 <p>I do not know the mathematical foundation of the at_pid algorithm,
  72 but from observation I can tell that the algorithm will, when enabled,
  73 produce a square wave pattern centered around the bias value on the
  74 output pin of the PID controller.  This can be seen using the HAL
  75 Scope provided by LinuxCNC.  In my case, this is translated into
  76 voltage (+-10V) sent to the motor controller, which in turn is
  77 translated into motor speed.  So it will ask the motor to move the
  78 axis back and forth.  The number of cycles in the pattern is
  79 controlled by the tune-cycles, and the extremes of the wave pattern is
  80 controlled by the tune-effort pin.  Of course, trying to change the
  81 direction of a physical object instantly (as in going directly from a
  82 positive voltage to the equivalent negative voltage) do not work, and
  83 it take some time for the object to slow down and move in the opposite
  84 direction.  This result in more smooth movement wave form, as the axis
  85 in question were vibrating back and forth.  When the axis reached the
  86 target speed in the opposing direction, the auto tuner change
  87 direction again.  After several of these, the average time delay
  88 between the 'peaks' and 'valleys' of this movement graph is then used
  89 to calculate proposed values for Pgain, Igain and Dgain, and insert
  90 them into the HAL model to use by the pid controller.  The end result
  91 is not great, but it work a lot better than the values I had been able
  92 to cook up on my own, at least for the horizontal X and Y axis.  I've
  93 been less lucky with the Z axis, which is moving a heavy object up and
  94 down, and seem to confuse the algorithm.  It became a lot better when
  95 I introduced a bias value to counter the gravitational drag, but I
  96 will have to work a lot more on the Z axis PID values.</p>
  97
  98 <p>Armed with this knowledge, it is time to look at how to do the
  99 tuning.  Lets say the HAL configuration in question load the PID
 100 component for X, Y and Z like this:</p>
 101
 102 <blockquote><pre>
 103 loadrt pid names=pid.x,pid.y,pid.z
 104 </pre></blockquote>
 105
 106 <p>Armed with the new and improved at_pid component, the new line will
 107 look like this:</p>
 108
 109
 110 <blockquote><pre>
 111 loadrt at_pid names=pid.x,pid.y,pid.z
 112 </pre></blockquote>
 113
 114 <p>The rest of the HAL setup can stay the same.</p>
 115
 116 <p>So, to start tuning the X axis, move the axis to the middle of its
 117 range, to make sure it do not hit anything when it start moving back
 118 and forth.  Next, set the pid.x.tune-effort to a low number in the
 119 output range.  I used 0.1 as my initial value.  Next, assign 1 to the
 120 tune-mode value. Note, this will disable the pid controlling part and
 121 feed 0 to the output pin, which in my case initially caused a lot of
 122 drift.  In my case it proved to be a good idea with X and Y to tune
 123 the motor driver to make sure 0 voltage stopped the motor rotation.
 124 On the other hand, for the Z axis this proved to be a bad idea, so it
 125 will depend on your setup.  It might help to set the bias value to a
 126 output value that reduce or eliminate the axis drift.  Finally, after
 127 setting tune-mode, set tune-start to 1 to activate the auto tuning.
 128 If all go well, your axis will vibrate for a few seconds and when it
 129 is done, new values for Pgain, Igain and Dgain will be active.  To
 130 test them, change tune-mode back to 0.  Note that this might cause the
 131 machine to suddenly jerk as it bring the axis back to its commanded
 132 position, which it might have drifted away from during tuning.  To
 133 summarize with some halcmd lines:</p>
 134
 135 <blockquote><pre>
 136 setp pid.x.tune-effort 0.1
 137 setp pid.x.tune-mode 1
 138 setp pid.x.tune-start 1
 139 # wait for the tuning to complete
 140 setp pid.x.tune-mode 0
 141 </pre></blockquote>
 142
 143 <p>After doing this task quite a few times while trying to figure out
 144 how to properly tune the PID controllers on the machine in, I decided
 145 to figure out if this process could be automated, and wrote a script
 146 to do the entire tuning process from power on.  The end result will
 147 ensure the machine is powered on and ready to run, home all axis if it
 148 is not already done, check that the extra tuning pins are available,
 149 move the axis to its mid point, run the auto tuning and re-enable the
 150 pid controller when it is done.  It can be run several times.  Check
 151 out the
 152 <a href="https://github.com/SebKuzminsky/MazakVQC1540/blob/bon-dev/scripts/run-auto-pid-tuner">run-auto-pid-tuner</a>
 153 script on github if you want to learn how it is done.</p>
 154
 155 <p>My hope is that this little adventure can inspire someone who know
 156 more about motor PID controller tuning can implement even better
 157 algorithms for automatic PID tuning in LinuxCNC, making life easier
 158 for both me and all the others that want to use LinuxCNC but lack the
 159 in depth knowledge needed to tune PID controllers well.</p>
 160
 161 <p>As usual, if you use Bitcoin and want to show your support of my
 162 activities, please send Bitcoin donations to my address
 163 <b><a href="bitcoin:15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b">15oWEoG9dUPovwmUL9KWAnYRtNJEkP1u1b</a></b>.</p>