Skip to content

Commit ec91c44

Browse files
petterreinholdtsenpetterreinholdtsen
committed
Baseline for new at_pid implementation, copied pid.c and pid.9.
Copied from commit bab0790.
1 parent 074d46f commit ec91c44

2 files changed

Lines changed: 1090 additions & 0 deletions

File tree

‎docs/man/man9/at_pidv2.9‎

Lines changed: 376 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,376 @@
1+
.TH PID "9" "2007-01-16" "LinuxCNC Documentation" "HAL Component"
2+
3+
.SH NAME
4+
pid \- proportional/integral/derivative controller
5+
.SH SYNOPSIS
6+
\fBloadrt pid [num_chan=\fInum\fB | names=\fIname1\fB[,\fIname2...\fB]] [\fBdebug=\fIdbg\fR]
7+
8+
.SH DESCRIPTION
9+
\fBpid\fR is a classic Proportional/Integral/Derivative controller,
10+
used to control position or speed feedback loops for servo motors and
11+
other closed-loop applications.
12+
.P
13+
\fBpid\fR supports a maximum of sixteen controllers. The number that
14+
are actually loaded is set by the \fBnum_chan\fR argument when
15+
the module is loaded. Alternatively, specify names= and unique names
16+
separated by commas.
17+
.P
18+
The \fBnum_chan=\fR and \fBnames=\fR specifiers are mutually exclusive.
19+
If neither \fBnum_chan=\fR nor \fBnames=\fR are specified, the default
20+
value is three. If \fBdebug\fR is set to 1 (the default is 0), some
21+
additional HAL parameters will be exported, which might be useful
22+
for tuning, but are otherwise unnecessary.
23+
24+
.P
25+
In the following description, it is assumed that we are discussing
26+
position loops. However this component can be used to implement other
27+
loops such as speed loops, torch height control, and others.
28+
29+
.P
30+
Each loop has a number of pins and parameters, whose names begin
31+
with 'pid.N.', where 'N' is the channel number. Channel numbers start
32+
at zero.
33+
.P
34+
The three most important pins are 'command', 'feedback', and 'output'.
35+
For a position loop, 'command' and 'feedback' are in position units.
36+
For a linear axis, this could be inches, mm, metres, or whatever is
37+
relevant. Likewise, for a angular axis, it could be degrees, radians,
38+
etc. The units of the 'output' pin represent the change needed to
39+
make the feedback match the command. As such, for a position
40+
loop 'Output' is a velocity, in inches/sec, mm/sec, degrees/sec, etc.
41+
.P
42+
Each loop has several other pins as well. 'error' is equal
43+
to 'command' minus 'feedback'. 'enable' is a bit that enables the
44+
loop. If 'enable' is false, all integrators are reset, and the output
45+
is forced to zero. If 'enable' is true, the loop operates normally.
46+
.P
47+
The PID gains, limits, and other 'tunable' features of the loop are
48+
implemented as parameters. These are as follows:
49+
50+
.PP
51+
\fBPgain\fR Proportional gain
52+
.PD 0
53+
.P
54+
.PD
55+
\fBIgain\fR Integral gain
56+
.PD 0
57+
.P
58+
.PD
59+
\fBDgain\fR Derivative gain
60+
.PD 0
61+
.P
62+
.PD
63+
\fBbias\fR Constant offset on output
64+
.PD 0
65+
.P
66+
.PD
67+
\fBFF0\fR \fR Zeroth order Feedforward gain
68+
.PD 0
69+
.P
70+
.PD
71+
\fBFF1\fR \fR First order Feedforward gain
72+
.PD 0
73+
.P
74+
.PD
75+
\fBFF2\fR \fR Second order Feedforward gain
76+
.PD 0
77+
.P
78+
.PD
79+
\fBFF3\fR \fR Third order Feedforward gain
80+
.PD 0
81+
.P
82+
.PD
83+
\fBdeadband\fR Amount of error that will be ignored
84+
.PD 0
85+
.P
86+
.PD
87+
\fBmaxerror\fR Limit on error
88+
.PD 0
89+
.P
90+
.PD
91+
\fBmaxerrorI\fR Limit on error integrator
92+
.PD 0
93+
.P
94+
.PD
95+
\fBmaxerrorD\fR Limit on error differentiator
96+
.PD 0
97+
.P
98+
.PD
99+
\fBmaxcmdD\fR Limit on command differentiator
100+
.PD 0
101+
.P
102+
.PD
103+
\fBmaxcmdDD\fR Limit on command 2nd derivative
104+
.PD 0
105+
.P
106+
.PD
107+
\fBmaxcmdDDD\fR Limit on command 3rd derivative
108+
.PD 0
109+
.P
110+
.PD
111+
\fBmaxoutput\fR Limit on output value
112+
.P
113+
All of the limits (max____) are implemented such that if the parameter
114+
value is zero, there is no limit.
115+
.P
116+
A number of internal values which may be useful for testing and tuning
117+
are also available as parameters. To avoid cluttering the parameter
118+
list, these are only exported if "debug=1" is specified on the insmod
119+
command line.
120+
121+
.PP
122+
\fBerrorI\fR Integral of error
123+
.PD 0
124+
.P
125+
.PD
126+
\fBerrorD\fR Derivative of error
127+
.PD 0
128+
.P
129+
.PD
130+
\fBcommandD\fR Derivative of the command
131+
.PD 0
132+
.P
133+
.PD
134+
\fBcommandDD\fR 2nd derivative of the command
135+
.PD 0
136+
.P
137+
.PD
138+
\fBcommandDDD\fR 3rd derivative of the command
139+
140+
.P
141+
The PID loop calculations are as follows (see the code in pid.c for
142+
all the nitty gritty details):
143+
.IP
144+
.nf
145+
error = command - feedback
146+
if ( abs(error) < deadband ) then error = 0
147+
limit error to +/- maxerror
148+
errorI += error * period
149+
limit errorI to +/- maxerrorI
150+
errorD = (error - previouserror) / period
151+
limit errorD to +/- maxerrorD
152+
commandD = (command - previouscommand) / period
153+
limit commandD to +/- maxcmdD
154+
commandDD = (commandD - previouscommandD) / period
155+
limit commandDD to +/- maxcmdDD
156+
commandDDD = (commandDD - previouscommandDD) / period
157+
limit commandDDD to +/- maxcmdDDD
158+
output = bias + error * Pgain + errorI * Igain +
159+
errorD * Dgain + command * FF0 + commandD * FF1 +
160+
commandDD * FF2 + commandDDD * FF3
161+
limit output to +/- maxoutput
162+
.fi
163+
164+
.SH NAMING
165+
The names for pins, parameters, and functions are prefixed as:
166+
\fBpid.N.\fR for N=0,1,...,num\-1 when using \fBnum_chan=num\fR
167+
\fBnameN.\fR for nameN=name1,name2,... when using \fBnames=name1,name2,...\fR
168+
169+
The \fBpid.N.\fR format is shown in the following descriptions.
170+
171+
.SH FUNCTIONS
172+
173+
\fBpid.\fIN\fB.do\-pid\-calcs\fR (uses floating-point)
174+
Does the PID calculations for control loop \fIN\fR.
175+
176+
.SH PINS
177+
178+
.TP
179+
\fBpid.\fIN\fB.command\fR float in
180+
The desired (commanded) value for the control loop.
181+
.TP
182+
\fBpid.\fIN\fB.Pgain\fR float in
183+
Proportional gain. Results in a contribution to the output that is the error
184+
multiplied by \fBPgain\fR.
185+
.TP
186+
\fBpid.\fIN\fB.Igain\fR float in
187+
Integral gain. Results in a contribution to the output that is the integral
188+
of the error multiplied by \fBIgain\fR. For example an error of 0.02 that
189+
lasted 10 seconds would result in an integrated error (\fBerrorI\fR) of 0.2,
190+
and if \fBIgain\fR is 20, the integral term would add 4.0 to the output.
191+
.TP
192+
\fBpid.\fIN\fB.Dgain\fR float in
193+
Derivative gain. Results in a contribution to the output that is the rate of
194+
change (derivative) of the error multiplied by \fBDgain\fR. For example an
195+
error that changed from 0.02 to 0.03 over 0.2 seconds would result in an error
196+
derivative (\fBerrorD\fR) of of 0.05, and if \fBDgain\fR is 5, the derivative
197+
term would add 0.25 to the output.
198+
.TP
199+
\fBpid.\fIN\fB.feedback\fR float in
200+
The actual (feedback) value, from some sensor such as an encoder.
201+
.TP
202+
\fBpid.\fIN\fB.output\fR float out
203+
The output of the PID loop, which goes to some actuator such as a motor.
204+
.TP
205+
\fBpid.\fIN\fB.command\-deriv\fR float in
206+
The derivative of the desired (commanded) value for the control loop. If no
207+
signal is connected then the derivative will be estimated numerically.
208+
.TP
209+
\fBpid.\fIN\fB.feedback\-deriv\fR float in
210+
The derivative of the actual (feedback) value for the control loop. If no
211+
signal is connected then the derivative will be estimated numerically. When
212+
the feedback is from a quantized position source (e.g., encoder feedback
213+
position), behavior of the D term can be improved by using a better velocity
214+
estimate here, such as the velocity output of encoder(9) or hostmot2(9).
215+
.TP
216+
\fBpid.\fIN\fB.error\-previous\-target\fR bit in
217+
Use previous invocation's target vs. current position for error calculation,
218+
like the motion controller expects. This may make torque-mode position loops
219+
and loops requiring a large I gain easier to tune, by eliminating
220+
velocity\-dependent following error.
221+
.TP
222+
\fBpid.\fIN\fB.error\fR float out
223+
The difference between command and feedback.
224+
.TP
225+
\fBpid.\fIN\fB.enable\fR bit in
226+
When true, enables the PID calculations. When false, \fBoutput\fR is zero,
227+
and all internal integrators, etc, are reset.
228+
.TP
229+
\fBpid.\fIN\fB.index\-enable\fR bit in
230+
On the falling edge of \fBindex\-enable\fR, pid does not update the
231+
internal command derivative estimate. On systems which use the encoder
232+
index pulse, this pin should be connected to the index\-enable signal.
233+
When this is not done, and FF1 is nonzero, a step change in the input
234+
command causes a single-cycle spike in the PID output. On systems which use
235+
exactly one of the \fB\-deriv\fR inputs, this affects the D term as well.
236+
.TP
237+
\fBpid.\fIN\fB.bias\fR float in
238+
\fBbias\fR is a constant amount that is added to the output. In most cases
239+
it should be left at zero. However, it can sometimes be useful to compensate
240+
for offsets in servo amplifiers, or to balance the weight of an object that
241+
moves vertically. \fBbias\fR is turned off when the PID loop is disabled,
242+
just like all other components of the output. If a non-zero output is needed
243+
even when the PID loop is disabled, it should be added with an external HAL
244+
sum2 block.
245+
.TP
246+
\fBpid.\fIN\fB.FF0\fR float in
247+
Zero order feed-forward term. Produces a contribution to the output that is
248+
\fBFF0\fR multiplied by the commanded value. For position loops, it should
249+
usually be left at zero. For velocity loops, \fBFF0\fR can compensate for
250+
friction or motor counter-EMF and may permit better tuning if used properly.
251+
.TP
252+
\fBpid.\fIN\fB.FF1\fR float in
253+
First order feed-forward term. Produces a contribution to the output that
254+
is \fBFF1\fR multiplied by the derivative of the commanded value. For
255+
position loops, the contribution is proportional to speed, and can be used
256+
to compensate for friction or motor CEMF. For velocity loops, it is
257+
proportional to acceleration and can compensate for inertia. In both
258+
cases, it can result in better tuning if used properly.
259+
.TP
260+
\fBpid.\fIN\fB.FF2\fR float in
261+
Second order feed-forward term. Produces a contribution to the output that is
262+
\fBFF2\fR multiplied by the second derivative of the commanded value. For
263+
position loops, the contribution is proportional to acceleration, and can be
264+
used to compensate for inertia. For velocity loops, the contribution is
265+
proportional to jerk, and should usually be left at zero.
266+
.TP
267+
\fBpid.\fIN\fB.FF3\fR float in
268+
Third order feed-forward term. Produces a contribution to the output that is
269+
\fBFF3\fR multiplied by the third derivative of the commanded value. For
270+
position loops, the contribution is proportional to jerk, and can be
271+
used to compensate for residual errors during acceleration. For velocity
272+
loops, the contribution is proportional to snap(jounce), and should usually
273+
be left at zero.
274+
.TP
275+
\fBpid.\fIN\fB.deadband\fR float in
276+
Defines a range of "acceptable" error. If the absolute value of \fBerror\fR
277+
is less than \fBdeadband\fR, it will be treated as if the error is zero.
278+
When using feedback devices such as encoders that are inherently quantized,
279+
the deadband should be set slightly more than one-half count, to prevent
280+
the control loop from hunting back and forth if the command is between two
281+
adjacent encoder values. When the absolute value of the error is greater
282+
than the deadband, the deadband value is subtracted from the error before
283+
performing the loop calculations, to prevent a step in the transfer function
284+
at the edge of the deadband. (See \fBBUGS\fR.)
285+
.TP
286+
\fBpid.\fIN\fB.maxoutput\fR float in
287+
Output limit. The absolute value of the output will not be permitted
288+
to exceed \fBmaxoutput\fR, unless \fBmaxoutput\fR is zero. When the output
289+
is limited, the error integrator will hold instead of integrating, to prevent
290+
windup and overshoot.
291+
.TP
292+
\fBpid.\fIN\fB.maxerror\fR float in
293+
Limit on the internal error variable used for P, I, and D. Can be used to
294+
prevent high \fBPgain\fR values from generating large outputs under conditions
295+
when the error is large (for example, when the command makes a step change).
296+
Not normally needed, but can be useful when tuning non-linear systems.
297+
.TP
298+
\fBpid.\fIN\fB.maxerrorD\fR float in
299+
Limit on the error derivative. The rate of change of error used by the
300+
\fBDgain\fR term will be limited to this value, unless the value is
301+
zero. Can be used to limit the effect of \fBDgain\fR and prevent large
302+
output spikes due to steps on the command and/or feedback. Not normally
303+
needed.
304+
.TP
305+
\fBpid.\fIN\fB.maxerrorI\fR float in
306+
Limit on error integrator. The error integrator used by the \fBIgain\fR
307+
term will be limited to this value, unless it is zero. Can be used to prevent
308+
integrator windup and the resulting overshoot during/after sustained errors.
309+
Not normally needed.
310+
.TP
311+
\fBpid.\fIN\fB.maxcmdD\fR float in
312+
Limit on command derivative. The command derivative used by \fBFF1\fR will
313+
be limited to this value, unless the value is zero. Can be used to prevent
314+
\fBFF1\fR from producing large output spikes if there is a step change on the
315+
command. Not normally needed.
316+
.TP
317+
\fBpid.\fIN\fB.maxcmdDD\fR float in
318+
Limit on command second derivative. The command second derivative used by
319+
\fBFF2\fR will be limited to this value, unless the value is zero. Can be
320+
used to prevent \fBFF2\fR from producing large output spikes if there is a
321+
step change on the command. Not normally needed.
322+
.TP
323+
\fBpid.\fIN\fB.maxcmdDDD\fR float in
324+
Limit on command third derivative. The command third derivative used by
325+
\fBFF3\fR will be limited to this value, unless the value is zero. Can be
326+
used to prevent \fBFF3\fR from producing large output spikes if there is a
327+
step change on the command. Not normally needed.
328+
.TP
329+
\fBpid.\fIN\fB.saturated\fR bit out
330+
When true, the current PID output is saturated. That is,
331+
.RS 12
332+
\fBoutput\fR = \(+- \fBmaxoutput\fR.
333+
.RE
334+
.TP
335+
\fBpid.\fIN\fB.saturated\-s\fR float out
336+
.br
337+
.ns
338+
.TP
339+
\fBpid.\fIN\fB.saturated\-count\fR s32 out
340+
When true, the output of PID was continually saturated for this many seconds
341+
(\fBsaturated\-s\fR) or periods (\fBsaturated\-count\fR).
342+
.SH PARAMETERS
343+
.TP
344+
\fBpid.\fIN\fB.errorI\fR float ro (only if debug=1)
345+
Integral of error. This is the value that is multiplied by \fBIgain\fR to produce the Integral term of the output.
346+
.TP
347+
\fBpid.\fIN\fB.errorD\fR float ro (only if debug=1)
348+
Derivative of error. This is the value that is multiplied by \fBDgain\fR to produce the Derivative term of the output.
349+
.TP
350+
\fBpid.\fIN\fB.commandD\fR float ro (only if debug=1)
351+
Derivative of command. This is the value that is multiplied by \fBFF1\fR to produce the first order feed-forward term of the output.
352+
.TP
353+
\fBpid.\fIN\fB.commandDD\fR float ro (only if debug=1)
354+
Second derivative of command. This is the value that is multiplied by
355+
\fBFF2\fR to produce the second order feed-forward term of the output.
356+
.TP
357+
\fBpid.\fIN\fB.commandDDD\fR float ro (only if debug=1)
358+
Third derivative of command. This is the value that is multiplied by
359+
\fBFF3\fR to produce the third order feed-forward term of the output.
360+
361+
.SH BUGS
362+
Some people would argue that deadband should be implemented such that error is
363+
treated as zero if it is within the deadband, and be unmodified if it is outside
364+
the deadband. This was not done because it would cause a step in the transfer
365+
function equal to the size of the deadband. People who prefer that behavior are
366+
welcome to add a parameter that will change the behavior, or to write their own
367+
version of \fBpid\fR. However, the default behavior should not be changed.
368+
369+
Negative gains may lead to unwanted behavior. It is possible in some
370+
situations that negative FF gains make sense, but in general all gains
371+
should be positive. If some output is in the wrong direction, negating
372+
gains to fix it is a mistake; set the scaling correctly elsewhere
373+
instead.
374+
375+
.SH SEE ALSO
376+
\fBat_pid\fR(9)

0 commit comments

Comments
 (0)