THE BASICS

What Is PID?

From Wikipedia: "A PID controller calculates an 'error' value as the difference between a
measured [Input] and a desired setpoint. The controller attempts to minimize the error by
adjusting [an Output]."
So, you tell the PID what to measure (the "Input",) Where you want that measurement to be (the
"Setpoint",) and the variable to adjust that can make that happen (the "Output".) The PID then
adjusts the output trying to make the input equal the setpoint.
For reference, in a car, the Input, Setpoint, and Output would be the speed, desired speed, and
gas pedal angle respectively.
Tuning Parameters

The black magic of PID comes in when we talk about HOW it adjusts the Output to drive the
Input towards Setpoint. There are 3 Tuning Parameters (or "Tunings"): Kp, Ki & Kd. Adjusting
these values will change the way the output is adjusted. Fast? Slow? God-awful? All of these can
be achieved depending on the values of Kp, Ki, and Kd.
So what are the "right" tuning values to use? There isn't one right answer. The values that work
for one application may not work for another, just as the driving style that works for a truck may
not work for a race car. With each new application you will need to try Several Tuning values
until you find a set that gives you what you want.
Note: there is also now a PID Autotune Library that can help you determine tuning
parameters.
Should I Use PID?

PID is a pretty impressive control algorithm, but it's not magic. You should at least be able to
answer "yes" to these questions:

Is it worth the extra work? If you're using a more basic system and it's working for you, there's
no real reason to use PID.
Is your system repeatable? The PID needs some semblance of repeatability. When the output is
changed from A to B, at least roughly the same thing should happen every time. (think of a car
where you step on the gas and sometimes you speed up and sometimes you slow down. not
repeatable, not a place where you could use PID)

(This list will probably grow as I think of more criteria. These are the big ones though)

A Note About Relays

Even though a PID controller is designed to work with an analog output, it is possible to connect
to a discrete output such as a relay. Be sure to look at the RelayOutput example below.

Questions?
Try the newly created Google group.

The Library
Using The PID Library has two benefits in my mind
1. There are many ways to write the PID algorithm. A lot of time was spent making the algorithm in
this library as solid as any found in industry. If you want to read more about this, check out this
detailed explanation.
2. When using the library all the PID code is self-contained. This makes your code easier to
understand. It also lets you do more complex stuff, like say having 8 PIDs in the same program.
Functions
PID()
Compute()
SetMode()
SetOutputLimits()
SetTunings()
SetSampleTime()
SetControllerDirection()
Display Functions

PID()
Description
Creates a PID controller linked to the specified Input, Output, and Setpoint. The PID algorithm is
in parallel form.
Syntax

PID(&Input, &Output, &Setpoint, Kp, Ki, Kd, Direction)

Parameters
Input: The variable we're trying to control (double)
Output: The variable that will be adjusted by the pid (double)
Setpoint: The value we want to Input to maintain (double)
Kp, Ki, Kd: Tuning Parameters. these affect how the pid will chage the output. (double>=0)
Direction: Either DIRECT or REVERSE. determines which direction the output will move
when faced with a given error. DIRECT is most common.
Returns
None

Compute()
Description
Contains the pid algorithm. it should be called once every loop(). Most of the time it will just return
without doing anything. At a frequency specified by SetSampleTime it will calculate a new Output.

Syntax
Compute()

Parameters
None

Returns
True: when the output is computed
False: when nothing has been done

SetMode()
Description

Specifies whether the PID should be on (Automatic) or off (Manual.) The PID defaults to the off position
when created.

Syntax
SetMode(mode)

Parameters
mode: AUTOMATIC or MANUAL

Returns
None

SetTunings()
Description
Tuning parameters (or "Tunings") dictate the dynamic behavior of the PID. Will it oscillate or not? Will it
be fast or slow? An initial set of Tunings is specified when the PID is created. For most users this will be
enough. There are times however, tunings need to be changed during run-time. At those times this
function can be called.

Syntax
SetTunings(Kp, Ki, Kd)

Parameters
Kp: Determines how aggressively the PID reacts to the current amount of error (Proportional) (double
>=0)
Ki: Determines how aggressively the PID reacts to error over time (Integral) (double>=0)
Kd: Determines how aggressively the PID reacts to the change in error (Derivative) (double>=0)

Returns
None

SetOutputLimits()
Description
The PID controller is designed to vary its output within a given range. By default this range is 0-255: the
arduino PWM range. There's no use sending 300, 400, or 500 to the PWM. Depending on the application
though, a different range may be desired.

Syntax
SetOutputLimits(min, max)

Parameters
min: Low end of the range. must be < max (double)
max: High end of the range. must be > min (double)

Returns
None

SetSampleTime()
Decription
Determines how often the PID algorithm evaluates. The default is 200mS. For robotics applications this
may need to be faster, but for the most part 200mS is plenty fast.

Syntax
SetSampleTime(SampleTime)

Parameters
SampleTime: How often, in milliseconds, the PID will be evaluated. (int>0)

Returns
None

SetControllerDirection()
Description
If my Input is above Setpoint, should the output be increased or decreased? Depending on what the PID
is connected to, either could be true. With a car, the output should be decreased to bring the speed
down. For a refrigerator, the opposite is true. The output (cooling) needs to be increased to bring my
temperature down.
This function specifies which type of process the PID is connected to. This information is also specified
when the PID constructed. Since it's unlikely that the process will switch from direct to reverse, it's
equally unlikely that anyone will actually use this function.

Syntax
SetControllerDirection(Direction);

Parameters
Direction: DIRECT (like a car) or REVERSE (like a refrigerator)

Returns
None

Display Functions
GetKp()
GetKi()
GetKd()
GetMode()
GetDirection()
Decription

These functions query the PID internals to get current values. These are useful for display purposes.

Syntax
GetKp()
GetKi()
GetKd()
GetMode()
GetDirection()

Parameters
None

Returns
The corresponding internal value