.TH PID "9" "2007-01-16" "LinuxCNC Documentation" "HAL Component"
.de TQ
.br
.ns
.TP \\$1
..

.SH NAME
pid \- proportional/integral/derivative controller
.SH SYNOPSIS
\fBloadrt pid [num_chan=\fInum\fB | names=\fIname1\fB[,\fIname2...\fB]] [\fBdebug=\fIdbg\fR]

.SH DESCRIPTION
\fBpid\fR is a classic Proportional/Integral/Derivative controller,
used to control position or speed feedback loops for servo motors and
other closed-loop applications.
.P
\fBpid\fR supports a maximum of sixteen controllers.  The number that
are actually loaded is set by the \fBnum_chan\fR argument when
the module is loaded.  Alternatively, specify names= and unique names
separated by commas.
.P
The \fBnum_chan=\fR and \fBnames=\fR specifiers are mutually exclusive.
If neither \fBnum_chan=\fR nor \fBnames=\fR are specified, the default
value is three.  If \fBdebug\fR is set to 1 (the default is 0), some
additional HAL parameters will be exported, which might be useful
for tuning, but are otherwise unnecessary.

.SH NAMING
The names for pins, parameters, and functions are prefixed as:
  \fBpid.N.\fR for N=0,1,...,num-1 when using \fBnum_chan=num\fR
  \fBnameN.\fR for nameN=name1,name2,... when using \fBnames=name1,name2,...\fR

The \fBpid.N.\fR format is shown in the following descriptions.

.SH FUNCTIONS

\fBpid.\fIN\fB.do-pid-calcs\fR (uses floating-point)
Does the PID calculations for control loop \fIN\fR.

.SH PINS

.TP
\fBpid.\fIN\fB.command\fR float in
The desired (commanded) value for the control loop.
.TP
\fBpid.\fIN\fB.command-deriv\fR float in
The derivative of the desired (commanded) value for the control loop.  If no
signal is connected then the derivative will be estimated numerically.
.TP
\fBpid.\fIN\fB.feedback\fR float in
The actual (feedback) value, from some sensor such as an encoder.
.TP
\fBpid.\fIN\fB.feedback-deriv\fR float in
The derivative of the actual (feedback) value for the control loop.  If no
signal is connected then the derivative will be estimated numerically.  When
the feedback is from a quantized position source (e.g., encoder feedback
position), behavior of the D term can be improved by using a better velocity
estimate here, such as the velocity output of encoder(9) or hostmot2(9).
.TP
\fBpid.\fIN\fB.error-previous-target\fR bit in
Use previous invocation's target vs. current position for error calculation,
like the motion controller expects.  This may make torque-mode position loops
and loops requiring a large I gain easier to tune, by eliminating
velocity-dependent following error.
.TP
\fBpid.\fIN\fB.error\fR float out
The difference between command and feedback.
.TP
\fBpid.\fIN\fB.output\fR float out
The output of the PID loop, which goes to some actuator such as a motor.
.TP
\fBpid.\fIN\fB.enable\fR bit in
When true, enables the PID calculations.  When false, \fBoutput\fR is zero,
and all internal integrators, etc, are reset.
.TP
\fBpid.\fIN\fB.index-enable\fR bit in
On the falling edge of \fBindex-enable\fR, pid does not update the
internal command derivative estimate.  On systems which use the encoder
index pulse, this pin should be connected to the index-enable signal.
When this is not done, and FF1 is nonzero, a step change in the input
command causes a single-cycle spike in the PID output.  On systems which use
exactly one of the \fB-deriv\fR inputs, this affects the D term as well.
.TP
\fBpid.\fIN\fB.saturated\fR bit out
When true, the current PID output is saturated.  That is,
.RS 12
\fBoutput\fR = \(+- \fBmaxoutput\fR.
.RE
.TP
\fBpid.\fIN\fB.saturated-s\fR float out
.TQ
\fBpid.\fIN\fB.saturated-count\fR s32 out
When true, the output of PID was continually saturated for this many seconds
(\fBsaturated-s\fR) or periods (\fBsaturated-count\fR).
.SH PARAMETERS
.TP
\fBpid.\fIN\fB.Pgain\fR float rw
Proportional gain.  Results in a contribution to the output that is the error
multiplied by \fBPgain\fR.
.TP
\fBpid.\fIN\fB.Igain\fR float rw
Integral gain.  Results in a contribution to the output that is the integral
of the error multiplied by \fBIgain\fR.  For example an error of 0.02 that
lasted 10 seconds would result in an integrated error (\fBerrorI\fR) of 0.2,
and if \fBIgain\fR is 20, the integral term would add 4.0 to the output.
.TP
\fBpid.\fIN\fB.Dgain\fR float rw
Derivative gain.  Results in a contribution to the output that is the rate of
change (derivative) of the error multiplied by \fBDgain\fR.  For example an
error that changed from 0.02 to 0.03 over 0.2 seconds would result in an error
derivative (\fBerrorD\fR) of of 0.05, and if \fBDgain\fR is 5, the derivative
term would add 0.25 to the output.
.TP
\fBpid.\fIN\fB.bias\fR float rw
\fBbias\fR is a constant amount that is added to the output.  In most cases
it should be left at zero.  However, it can sometimes be useful to compensate
for offsets in servo amplifiers, or to balance the weight of an object that
moves vertically. \fBbias\fR is turned off when the PID loop is disabled,
just like all other components of the output.  If a non-zero output is needed
even when the PID loop is disabled, it should be added with an external HAL
sum2 block.
.TP
\fBpid.\fIN\fB.FF0\fR float rw
Zero order feed-forward term.  Produces a contribution to the output that is
\fBFF0\fR multiplied by the commanded value.  For position loops, it should
usually be left at zero.  For velocity loops, \fBFF0\fR can compensate for
friction or motor counter-EMF and may permit better tuning if used properly.
.TP
\fBpid.\fIN\fB.FF1\fR float rw
First order feed-forward term.  Produces a contribution to the output that
\fBFF1\fR multiplied by the derivative of the commanded value.  For
position loops, the contribution is proportional to speed, and can be used
to compensate for friction or motor CEMF.  For velocity loops, it is
proportional to acceleration and can compensate for inertia.  In both
cases, it can result in better tuning if used properly.
.TP
\fBpid.\fIN\fB.FF2\fR float rw
Second order feed-forward term.  Produces a contribution to the output that is
\fBFF2\fR multiplied by the second derivative of the commanded value.  For
position loops, the contribution is proportional to acceleration, and can be
used to compensate for inertia.  For velocity loops, it should usually be
left at zero.
.TP
\fBpid.\fIN\fB.deadband\fR float rw
Defines a range of "acceptable" error.  If the absolute value of \fBerror\fR
is less than \fBdeadband\fR, it will be treated as if the error is zero.
When using feedback devices such as encoders that are inherently quantized,
the deadband should be set slightly more than one-half count, to prevent
the control loop from hunting back and forth if the command is between two
adjacent encoder values.  When the absolute value of the error is greater
than the deadband, the deadband value is subtracted from the error before
performing the loop calculations, to prevent a step in the transfer function
at the edge of the deadband.  (See \fBBUGS\fR.)
.TP
\fBpid.\fIN\fB.maxoutput\fR float rw
Output limit.  The absolute value of the output will not be permitted
to exceed \fBmaxoutput\fR, unless \fBmaxoutput\fR is zero.  When the output
is limited, the error integrator will hold instead of integrating, to prevent
windup and overshoot.
.TP
\fBpid.\fIN\fB.maxerror\fR float rw
Limit on the internal error variable used for P, I, and D.  Can be used to
prevent high \fBPgain\fR values from generating large outputs under conditions
when the error is large (for example, when the command makes a step change).
Not normally needed, but can be useful when tuning non-linear systems.
.TP
\fBpid.\fIN\fB.maxerrorD\fR float rw
Limit on the error derivative.  The rate of change of error used by the
\fBDgain\fR term will be limited to this value, unless the value is
zero.  Can be used to limit the effect of \fBDgain\fR and prevent large
output spikes due to steps on the command and/or feedback.  Not normally
needed.
.TP
\fBpid.\fIN\fB.maxerrorI\fR float rw
Limit on error integrator.  The error integrator used by the \fBIgain\fR
term will be limited to this value, unless it is zero.  Can be used to prevent
integrator windup and the resulting overshoot during/after sustained errors.
Not normally needed.
.TP
\fBpid.\fIN\fB.maxcmdD\fR float rw
Limit on command derivative.  The command derivative used by \fBFF1\fR will
be limited to this value, unless the value is zero.  Can be used to prevent
\fBFF1\fR from producing large output spikes if there is a step change on the
command.  Not normally needed.
.TP
\fBpid.\fIN\fB.maxcmdDD\fR float rw
Limit on command second derivative.  The command second derivative used by
\fBFF2\fR will be limited to this value, unless the value is zero.  Can be
used to prevent \fBFF2\fR from producing large output spikes if there is a
step change on the command.  Not normally needed.
.TP
\fBpid.\fIN\fB.errorI\fR float ro (only if debug=1)
Integral of error.  This is the value that is multiplied by \fBIgain\fR to produce the Integral term of the output.
.TP
\fBpid.\fIN\fB.errorD\fR float ro (only if debug=1)
Derivative of error.  This is the value that is multiplied by \fBDgain\fR to produce the Derivative term of the output.
.TP
\fBpid.\fIN\fB.commandD\fR float ro (only if debug=1)
Derivative of command.  This is the value that is multiplied by \fBFF1\fR to produce the first order feed-forward term of the output.
.TP
\fBpid.\fIN\fB.commandDD\fR float ro (only if debug=1)
Second derivative of command.  This is the value that is multiplied by
\fBFF2\fR to produce the second order feed-forward term of the output.

.SH BUGS
Some people would argue that deadband should be implemented such that error is
treated as zero if it is within the deadband, and be unmodified if it is outside
the deadband.  This was not done because it would cause a step in the transfer
function equal to the size of the deadband.  People who prefer that behavior are
welcome to add a parameter that will change the behavior, or to write their own
version of \fBpid\fR. However, the default behavior should not be changed.

Negative gains may lead to unwanted behavior.  It is possible in some
situations that negative FF gains make sense, but in general all gains
should be positive.  If some output is in the wrong direction, negating
gains to fix it is a mistake; set the scaling correctly elsewhere
instead.