Adjusted at_pid documentation and logic

Made sure output is set to bias, not zero, when tuning cycle ends.  Added
reference to paper describing the tuning method implemented.  Reinserted
code to supress some messages while running, similar to the pid component.
Adjusted man page text to better explain how to use auto tuning.

Author: petterreinholdtsen

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;
 }