pid − proportional/integral/derivative controller
loadrt pid num_chan=num [debug=dbg]
pid is a classic Proportional/Integral/Derivative controller, used to control position or speed feedback loops for servo motors and other closed-loop applications.
pid supports a maximum of sixteen controllers. The number that are actually loaded is set by the num_chan argument when the module is loaded. If numchan is not specified, the default value is three. If debug 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.
pid.N.do-pid-calcs (uses floating-point)
Does the PID calculations for control loop N.
pid.N.command float in
The desired (commanded) value for the control loop.
pid.N.feedback float in
The actual (feedback) value, from some sensor such as an encoder.
pid.N.error float out
The difference between command and feedback.
pid.N.output float out
The output of the PID loop, which goes to some actuator such as a motor.
pid.N.enable bit in
When true, enables the PID calculations. When false, output is zero, and all internal integrators, etc, are reset.
pid.N.index-enable bit in
On the falling edge of index-enable, 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.
pid.N.saturated bit out
When true, the current PID output is saturated. That is,
output = ± maxoutput.
pid.N.saturated-s
float out
pid.N.saturated-count s32 out
When true, the output of PID was continually saturated for this many seconds (saturated-s) or periods (saturated-count).
pid.N.Pgain float rw
Proportional gain. Results in a contribution to the output that is the error multiplied by Pgain.
pid.N.Igain float rw
Integral gain. Results in a contribution to the output that is the integral of the error multiplied by Igain. For example an error of 0.02 that lasted 10 seconds would result in an integrated error (errorI) of 0.2, and if Igain is 20, the integral term would add 4.0 to the output.
pid.N.Dgain float rw
Derivative gain. Results in a contribution to the output that is the rate of change (derivative) of the error multiplied by Dgain. For example an error that changed from 0.02 to 0.03 over 0.2 seconds would result in an error derivative (errorD) of of 0.05, and if Dgain is 5, the derivative term would add 0.25 to the output.
pid.N.bias float rw
bias 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. bias 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.
pid.N.FF0 float rw
Zero order feed-forward term. Produces a contribution to the output that is FF0 multiplied by the commanded value. For position loops, it should usually be left at zero. For velocity loops, FF0 can compensate for friction or motor counter-EMF and may permit better tuning if used properly.
pid.N.FF1 float rw
First order feed-forward term. Produces a contribution to the output that FF1 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.
pid.N.FF2 float rw
Second order feed-forward term. Produces a contribution to the output that is FF2 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.
pid.N.deadband float rw
Defines a range of "acceptable" error. If the absolute value of error is less than deadband, 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 BUGS.)
pid.N.maxoutput float rw
Output limit. The absolute value of the output will not be permitted to exceed maxoutput, unless maxoutput is zero. When the output is limited, the error integrator will hold instead of integrating, to prevent windup and overshoot.
pid.N.maxerror float rw
Limit on the internal error variable used for P, I, and D. Can be used to prevent high Pgain 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.
pid.N.maxerrorD float rw
Limit on the error derivative. The rate of change of error used by the Dgain term will be limited to this value, unless the value is zero. Can be used to limit the effect of Dgain and prevent large output spikes due to steps on the command and/or feedback. Not normally needed.
pid.N.maxerrorI float rw
Limit on error integrator. The error integrator used by the Igain 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.
pid.N.maxcmdD float rw
Limit on command derivative. The command derivative used by FF1 will be limited to this value, unless the value is zero. Can be used to prevent FF1 from producing large output spikes if there is a step change on the command. Not normally needed.
pid.N.maxcmdDD float rw
Limit on command second derivative. The command second derivative used by FF2 will be limited to this value, unless the value is zero. Can be used to prevent FF2 from producing large output spikes if there is a step change on the command. Not normally needed.
pid.N.errorI float ro (only if debug=1)
Integral of error. This is the value that is multiplied by Igain to produce the Integral term of the output.
pid.N.errorD float ro (only if debug=1)
Derivative of error. This is the value that is multiplied by Dgain to produce the Derivative term of the output.
pid.N.commandD float ro (only if debug=1)
Derivative of command. This is the value that is multiplied by FF1 to produce the first order feed-forward term of the output.
pid.N.commandDD float ro (only if debug=1)
Second derivative of command. This is the value that is multiplied by FF2 to produce the second order feed-forward term of the output.
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 pid. However, the default behavior should not be changed.