Merge pull request #1868 from petterreinholdtsen/pid-autotune-doc-zero

Adjusted at_pid documentation and logic

Author: c-morley

docs/man/man9/at_pid.9

@@ -1,14 +1,11 @@
 .TH AT_PID "9" "2007-01-16" "LinuxCNC Documentation" "HAL Component"
 
 .SH NAME
-at_pid \- proportional/integral/derivative controller
+at_pid \- proportional/integral/derivative controller with automatic tuning support
 .SH SYNOPSIS
 \fBloadrt at_pid [num_chan=\fInum\fB | names=\fIname1\fB[,\fIname2...\fB]] [\fBdebug=\fIdbg\fR]
 
 .SH DESCRIPTION
-\fBNOTE:\fR The auto-tuning part of this component have seen
-no development since 2011.
-.P
 \fBat_pid\fR is a classic Proportional/Integral/Derivative controller,
 used to control position or speed feedback loops for servo motors and
 other closed-loop applications.
@@ -165,26 +162,38 @@ limit output to +/- maxoutput
 .fi
 
 .P
-This component has a built in auto tune mode. It works by setting up a limit
-cycle to characterize the process. From this, \fBPgain/Igain/Dgain\fR or
-\fBPgain/Igain/FF1\fR can be determined using Ziegler-Nichols. When using
-\fBFF1\fR, scaling must be set so that \fBoutput\fR is in user units per second.
-.P
-During auto tuning, the \fBcommand\fR input should not change. The limit
-cycle is setup around the commanded position. No initial tuning values are
-required to start auto tuning.  Only \fBtune\-cycles\fR, \fBtune\-effort\fR
-and \fBtune\-mode\fR need be set before starting auto tuning.  When auto tuning
-completes, the tuning parameters will be set. If running from LinuxCNC, the
-FERROR setting for the axis being tuned may need to be loosened up as it must
-be larger than the limit cycle amplitude in order to avoid a following error.
-.P
-To perform auto tuning, take the following steps.  Move the axis to be tuned,
-to somewhere near the center of it's travel.  Set \fBtune\-cycles\fR (the
-default value should be fine in most cases) and \fBtune\-mode\fR. Set
-\fBtune\-effort\fR to a small value. Set \fBenable\fR to true. Set
-\fBtune\-mode\fR to true. Set \fBtune\-start\fR to true. If no oscillation
-occurs, or the oscillation is too small, slowly increase \fBtune\-effort\fR.
-Auto tuning can be aborted at any time by setting \fBenable\fR or
+This component has a built in auto tune mode. It works by setting up a
+limit cycle to characterize the process.  This is called the Relay
+method and described in the 1984 Automation paper \fBAutomatic Tuning
+of Simple Regulators with Specifications on Phase and Amplitude
+Margins\fR by Karl Johan Åström and Tore Hägglund
+(doi:10.1016/0005-1098(84)90014-1),
+https://lup.lub.lu.se/search/ws/files/6340936/8509157.pdf. Using this
+method, \fBPgain/Igain/Dgain\fR or \fBPgain/Igain/FF1\fR can be
+determined using the Ziegler-Nichols algorithm.  When using \fBFF1\fR
+tuning, scaling must be set so that \fBoutput\fR is in user units per
+second.
+
+.P
+During auto tuning, the \fBcommand\fR input should not change. The
+limit cycle is setup around the commanded position. No initial tuning
+values are required to start auto tuning.  Only \fBtune\-cycles\fR,
+\fBtune\-effort\fR and \fBtune\-mode\fR need be set before starting
+auto tuning.  Note that setting \fBtune\-mode\fR to true disable the
+control loop.  When auto tuning completes, the tuning parameters will
+be set, the output set to bias and the controller still be
+disabled. If running from LinuxCNC, the FERROR setting for the axis
+being tuned may need to be loosened up as it must be larger than the
+limit cycle amplitude in order to avoid a following error.
+.P
+To perform auto tuning, take the following steps.  Move the axis to be
+tuned somewhere near the center of it's travel.  Set
+\fBtune\-cycles\fR (the default value should be fine in most cases)
+and \fBtune\-mode\fR. Set \fBtune\-effort\fR to a small value. Set
+\fBenable\fR to true. Set \fBtune\-mode\fR to true. Set
+\fBtune\-start\fR to true. If no oscillation occurs, or the
+oscillation is too small, slowly increase \fBtune\-effort\fR.  Auto
+tuning can be aborted at any time by setting \fBenable\fR or
 \fBtune\-mode\fR to false.
 
 .SH NAMING

src/hal/components/at_pid.c

@@ -154,6 +154,8 @@ RTAPI_MP_ARRAY_STRING(names, MAX_CHAN,"at_pid names");
 static int debug = 0;		/* flag to export optional params */
 RTAPI_MP_INT(debug, "enables optional params");
 
+#define NAME "AT_PID"
+
 #define AUTO_TUNER 1
 #ifdef AUTO_TUNER
 #include "rtapi_math.h"
@@ -296,7 +298,7 @@ int rtapi_app_main(void)
     /* test for number of channels */
     if ((howmany <= 0) || (howmany > MAX_CHAN)) {
 	rtapi_print_msg(RTAPI_MSG_ERR,
-	    "AT_PID: ERROR: invalid number of channels: %d\n", howmany);
+	    NAME ": ERROR: invalid number of channels: %d\n", howmany);
 	return -1;
     }
     /* have good config info, connect to the HAL */
@@ -308,7 +310,7 @@ int rtapi_app_main(void)
     /* allocate shared memory for pid loop data */
     pid_array = hal_malloc(howmany * sizeof(hal_pid_t));
     if (pid_array == 0) {
-	rtapi_print_msg(RTAPI_MSG_ERR, "AT_PID: ERROR: hal_malloc() failed\n");
+	rtapi_print_msg(RTAPI_MSG_ERR, NAME ": ERROR: hal_malloc() failed\n");
 	hal_exit(comp_id);
 	return -1;
     }
@@ -326,12 +328,12 @@ int rtapi_app_main(void)
 
 	if (retval != 0) {
 	    rtapi_print_msg(RTAPI_MSG_ERR,
-		"AT_PID: ERROR: loop %d var export failed\n", n);
+		NAME ": ERROR: loop %d var export failed\n", n);
 	    hal_exit(comp_id);
 	    return -1;
 	}
     }
-    rtapi_print_msg(RTAPI_MSG_INFO, "AT_PID: installed %d PID loops\n",
+    rtapi_print_msg(RTAPI_MSG_INFO, NAME ": installed %d PID loops\n",
 	howmany);
     hal_ready(comp_id);
     return 0;
@@ -444,22 +446,22 @@ Pid_AutoTune(hal_pid_t *pid, long period)
         if(pid->cycleCount < *(pid->tuneCycles))
             break;
 
-        // Calculate PID.
+        // Calculate PID using Relay (Åström-Hägglund) method
         *(pid->ultimateGain) = (4.0 * fabs(*(pid->tuneEffort)))/(PI * pid->avgAmplitude);
         *(pid->ultimatePeriod) = 2.0 * pid->totalTime / *(pid->tuneCycles);
         *(pid->ff0gain) = 0;
         *(pid->ff2gain) = 0;
 
         if(*(pid->tuneType) == TYPE_PID){
-            // PID.
+            // insert ultimate gain and period in Ziegler-Nichols PID method
             *(pid->pgain) = 0.6 * *(pid->ultimateGain);
-            *(pid->igain) = *(pid->pgain) / (*(pid->ultimatePeriod) / 2.0);
-            *(pid->dgain) = *(pid->pgain) * (*(pid->ultimatePeriod) / 8.0);
+            *(pid->igain) = 1.2 * *(pid->ultimateGain) / (*(pid->ultimatePeriod));
+            *(pid->dgain) = (3.0/40.0) * *(pid->ultimateGain) * *(pid->ultimatePeriod);
             *(pid->ff1gain) = 0;
         }else{
-            // PI FF1.
+            // insert ultimate gain and period in Ziegler-Nichols PI method
             *(pid->pgain) = 0.45 * *(pid->ultimateGain);
-            *(pid->igain) = *(pid->pgain) / (*(pid->ultimatePeriod) / 1.2);
+            *(pid->igain) = 0.54 * *(pid->ultimateGain) / (*(pid->ultimatePeriod));
             *(pid->dgain) = 0;
 
             // Scaling must be set so PID output is in user units per second.
@@ -470,8 +472,8 @@ Pid_AutoTune(hal_pid_t *pid, long period)
 
     case STATE_TUNE_ABORT:
     default:
-        // Force output to zero.
-        *pid->output = 0;
+        // Force output to bias.
+        *pid->output = *(pid->bias);
 
         // Abort any tuning cycle in progress.
         *pid->pTuneStart = 0;
@@ -693,8 +695,8 @@ static int export_pid(hal_pid_t * addr, char * prefix)
        logging if msg_level is at INFO or ALL. So we save the current value
        of msg_level and restore it later.  If you actually need to log this
        function's actions, change the second line below */
-//    msg = rtapi_get_msg_level();
-//    rtapi_set_msg_level(RTAPI_MSG_WARN);
+    msg = rtapi_get_msg_level();
+    rtapi_set_msg_level(RTAPI_MSG_WARN);
 
     /* export pins */
     retval = hal_pin_bit_newf(HAL_IN, &(addr->enable), comp_id,
@@ -966,11 +968,11 @@ static int export_pid(hal_pid_t * addr, char * prefix)
 	hal_export_funct(buf, calc_pid, addr, 1, 0, comp_id);
     if (retval != 0) {
 	rtapi_print_msg(RTAPI_MSG_ERR,
-	    "AT_PID: ERROR: do_pid_calcs funct export failed\n");
+	    NAME ": ERROR: do_pid_calcs funct export failed\n");
 	hal_exit(comp_id);
 	return -1;
     }
     /* restore saved message level */
-   // rtapi_set_msg_level(msg);
+    rtapi_set_msg_level(msg);
     return 0;
 }