Machinekit

Machinekit

Machinekit Documentation

HAL Component — PID

INSTANTIABLE COMPONENTS — General

All instantiable components can be loaded in two manners

Using loadrt with or without count= | names= parameters as per legacy components
Using newinst, which names the instance and allows further parameters and arguments
primarily pincount= which can set the number of pins created for that instance (where applicable)

NAME

pid — HAL component that provides Proportional Integeral/Derivative control loops. It is a realtime component.

SYNOPSIS

pid

USAGE SYNOPSIS

loadrt pid
OR
newinst pid <newinstname> [ pincount=N | iprefix=prefix ] [instanceparamX=X | argX=X ]

( args in [ ] denote possible args and parameters, may not be used in all components )

DESCRIPTION

HAL component that provides Proportional/
Integeral/Derivative control loops.  It is a realtime component.
The number of pid components is set by the module parameter 'num_chan='
when the component is insmod'ed.  Alternatively, use the
names= specifier and a list of unique names separated by commas.
The names= and num_chan= specifiers are mutually exclusive.
In this documentation, it is assumed that we are discussing position
loops.  However this component can be used to implement other loops
such as speed loops, torch height control, and others.
Each loop has a number of pins and parameters, whose names begin
with 'pid.x.', where 'x' is the channel number.  Channel numbers
start at zero.
The three most important pins are 'command', 'feedback', and
'output'.  For a position loop, 'command' and 'feedback' are
in position units.  For a linear axis, this could be inches,
mm, metres, or whatever is relavent.  Likewise, for a angular
axis, it could be degrees, radians, etc.  The units of the
'output' pin represent the change needed to make the feedback
match the command.  As such, for a position loop 'Output' is
a velocity, in inches/sec, mm/sec, degrees/sec, etc.
Each loop has several other pins as well.  'error' is equal to
'command' minus 'feedback'.  'enable' is a bit that enables
the loop.  If 'enable' is false, all integrators are reset,
and the output is forced to zero.  If 'enable' is true, the
loop operates normally.
The PID gains, limits, and other 'tunable' features of the
loop are implemented as parameters.  These are as follows:
Pgain	Proportional gain
Igain	Integral gain
Dgain	Derivative gain
bias	Constant offset on output
FF0		Zeroth order Feedforward gain
FF1		First order Feedforward gain
FF2		Second order Feedforward gain
deadband	Amount of error that will be ignored
maxerror	Limit on error
maxerrorI	Limit on error integrator
maxerrorD	Limit on error differentiator
maxcmdD	Limit on command differentiator
maxcmdDD	Limit on command 2nd derivative
maxoutput	Limit on output value
All of the limits (max____) are implemented such that if the
parameter value is zero, there is no limit.
A number of internal values which may be usefull for testing
and tuning are also available as parameters.  To avoid cluttering
the parameter list, these are only exported if "debug=1" is
specified on the insmod command line.
errorI	Integral of error
errorD	Derivative of error
commandD	Derivative of the command
commandDD	2nd derivative of the command
The PID loop calculations are as follows (see the code for
all the nitty gritty details):
error = command - feedback
if ( abs(error) < deadband ) then error = 0
limit error to +/- maxerror
errorI += error * period
limit errorI to +/- maxerrorI
errorD = (error - previouserror) / period
limit errorD to +/- maxerrorD
commandD = (command - previouscommand) / period
limit commandD to +/- maxcmdD
commandDD = (commandD - previouscommandD) / period
limit commandDD to +/- maxcmdDD
output = bias + error * Pgain + errorI * Igain +
         errorD * Dgain + command * FF0 + commandD * FF1 +
         commandDD * FF2
limit output to +/- maxoutput
This component exports one function called 'pid.x.do-pid-calcs'
for each PID loop.  This allows loops to be included in different
threads and execute at different rates.

FUNCTIONS

pid.N.do-pid-calcs.funct ( OR <newinstname>.do-pid-calcs.funct (requires a floating-point thread) )

PINS

pid.N.enable bit in (default: false) ( OR <newinstname>.enable bit in (default: false) ) - Enable/disabled the PID loop

pid.N.command float in (default: 0.0) ( OR <newinstname>.command float in (default: 0.0) ) - Commanded value

pid.N.command-deriv float in (default: 0.0) ( OR <newinstname>.command-deriv float in (default: 0.0) ) - Derivative command input

pid.N.feedback float in (default: 0.0) ( OR <newinstname>.feedback float in (default: 0.0) ) - Feedback input

pid.N.feedback-deriv float in (default: 0.0) ( OR <newinstname>.feedback-deriv float in (default: 0.0) ) - Derivative feedback input

pid.N.error float out ( OR <newinstname>.error float out ) - Current error

pid.N.output float out ( OR <newinstname>.output float out ) - Ouput value

pid.N.saturated bit out ( OR <newinstname>.saturated bit out ) - If the PID loop is saturated

pid.N.saturated-s float out ( OR <newinstname>.saturated-s float out ) - Saturated time

pid.N.saturated-count s32 out ( OR <newinstname>.saturated-count s32 out ) - How often the PID loop was saturated

pid.N.Pgain float in (default: 1.0) ( OR <newinstname>.Pgain float in (default: 1.0) ) - Proportional gain

pid.N.Igain float in (default: 0.0) ( OR <newinstname>.Igain float in (default: 0.0) ) - Integral gain

pid.N.Dgain float in (default: 0.0) ( OR <newinstname>.Dgain float in (default: 0.0) ) - Derivative gain

pid.N.bias float in (default: 0.0) ( OR <newinstname>.bias float in (default: 0.0) ) - Constant offset on output

pid.N.FF0 float in (default: 0.0) ( OR <newinstname>.FF0 float in (default: 0.0) ) - Zeroth order Feedforward gain

pid.N.FF1 float in (default: 0.0) ( OR <newinstname>.FF1 float in (default: 0.0) ) - First order Feedforward gain

pid.N.FF2 float in (default: 0.0) ( OR <newinstname>.FF2 float in (default: 0.0) ) - Second order Feedforward gain

pid.N.deadband float in (default: 0.0) ( OR <newinstname>.deadband float in (default: 0.0) ) - Amount of error that will be ignored

pid.N.maxerror float in (default: 0.0) ( OR <newinstname>.maxerror float in (default: 0.0) ) - Limit on error

pid.N.maxerrorI float in (default: 0.0) ( OR <newinstname>.maxerrorI float in (default: 0.0) ) - Limit on error integrator

pid.N.maxerrorD float in (default: 0.0) ( OR <newinstname>.maxerrorD float in (default: 0.0) ) - Limit on error differentiator

pid.N.maxcmdD float in (default: 0.0) ( OR <newinstname>.maxcmdD float in (default: 0.0) ) - Limit on command differentiator

pid.N.maxcmdDD float in (default: 0.0) ( OR <newinstname>.maxcmdDD float in (default: 0.0) ) - Limit on command 2nd derivative

pid.N.maxoutput float in (default: 0.0) ( OR <newinstname>.maxoutput float in (default: 0.0) ) - Limit on output value

pid.N.index-enable bit in (default: false) ( OR <newinstname>.index-enable bit in (default: false) ) - Index enable

pid.N.error-previous-target bit in (default: false) ( OR <newinstname>.error-previous-target bit in (default: false) ) - Error previous target

pid.N.errorI float out ( OR <newinstname>.errorI float out ) - Integral of error

pid.N.errorD float out ( OR <newinstname>.errorD float out ) - Derivative of error

pid.N.commandD float out ( OR <newinstname>.commandD float out ) - Derivative of the command

pid.N.commandDD float out ( OR <newinstname>.commandDD float out ) - 2nd derivative of the command

AUTHOR

John Kasunich

LICENCE

GPL v2