jataruku 0.1.1

All rights reserved.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.

* The code must not be modified to destroy the extant physical universe.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Description: jataruku
========

This project provides a PID controller written in Python3 in contrast to the orignal. The original is made by Jeremy Bornstein This is based on [the Arduino PID code written by Brett Beauregard](https://github.com/br3ttb/Arduino-PID-Library).

Brett's code is the result of much research and thought on his part, which
he has [generously documented](http://brettbeauregard.com/blog/2011/04/improving-the-beginners-pid-introduction/).
Most of what I did is translate it into a form which I hope can be easily
used if you are implementing a system in Python that wants to use PID
control.

How to Use
----------

The module exports only one object, a class called PID. The best way
to learn how to use it is to look at the test.py file (see below).

The second-best way to learn how to use it is to keep reading this
section.

The PID object must be constructed with the following parameters:

* ``input``: a lambda which reports the input value, e.g. the temperature of the object the temperature of which is being controlled

* ``output``: a function which controls the output setting, e.g. whether
or not the heater is turned on or not. it takes a single parameter,
which is the value that the output object should receive

* ``setpoint``: the target value for input, e.g. the desired temperature
of the object in question

* ``kp``, ``ki``, and ``kd``: the three PID parameters. (If you don't know
what they are you should [go read about how PIDs work](http://en.wikipedia.org/wiki/PID_controller), though you may
be able to get away with using defaults based on the test code herein.)

* ``direct``: True if an increase in the output value will produce an
increase in the input value, False otherwise

``pid = PID(input, output, setpoint, kp, ki, kd, direct)``

After the object has been created, turn PID control on with ``pid.auto = True``,
and set the range of your output control with ``pid.set_output_limits(min_out, max_out)``.
At that point you can just call ``pid.compute()`` as
frequently as possible, preferably via an interrupt of some sort. The
frequency required for good results will depend on the characteristics
of your entire system, but the default update frequency of 100
milliseconds is probably a good place to start. If the system is
working, then the input value will approach the set point and stay there.

You can change the system back and forth from automatic to manual mode at
any time by setting ``pid.auto`` to ``False`` (for manual control) or ``True``
(for automatic).

If you want to change the sample rate, set ``pid.sample_time`` to a number
of milliseconds. The default value is ``100``. If you want to change the
set point, just set ``pid.setpoint``, and if you want to re-set any of the
PID parameters you can call ``pid.set_tunings(kp, ki, kd)``. The system should
be pretty reasonable under these changes.

Testing
-------

Since a PID is inherently real-time and dependent on external systems,
you can't really write code to test it quickly without decoupling it
from the wall clock or having an external system with which to integrate it.
In order to prove to myself that it basically works, I wrote a very simple
simulation of a heater attached to a tank of water, and some tests to
see what the PIDs behavior is when attached to the heater simulation.
The heater, when turned on, heats up at a certain rate, and if its
temperature is above the ambient temperature will
lose a certain amount of heat to the environment over time.

The first test should demonstrate that the dummy heater is basically working.

test.py 0

The second test should demonstrate that the system can bring the water to
a given temperature and hold it there.

test.py 1


Caveats
-------

This is basically first draft code. Since the object is relatively straightforward there's
hardly any need. If this bothers you, go ahead and add them,
though it is not inconceivable that I would eventually get around to it
myself. Nevertheless, it should be usable as-is without too much
difficulty.

This code depends on ``pid.compute()`` being called at a predictable interval. It won't
work as well under conditions which delay the call by too much, such as
use under a non-real-time operating system which is trying to do too
many things.

There are other PID features which could be added to make this even
better. I'm not even sure I know what they are. If you do, feel free
to write them and submit a pull request.

P.S. "jataruku" is a word in the Warlpiri language which according to
[the Australian Society for Indigenous Languages' Walpiri lexicon](http://ausil.org/Dictionary/Warlpiri/lexicon/index.htm) means
"stubborn, bullheaded, hot-tempered."

Platform: UNKNOWN