Package: jataruku
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, thislist of conditions and the following disclaimer.* Redistributions in binary form must reproduce the above copyright notice, thislist of conditions and the following disclaimer in the documentation and/orother 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" ANDANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AREDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FORANY 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 ONANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THISSOFTWARE, 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, whichhe 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 easilyused if you are implementing a system in Python that wants to use PIDcontrol.How to Use----------The module exports only one object, a class called PID. The best wayto 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 thissection.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. whetheror 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 temperatureof the object in question* ``kp``, ``ki``, and ``kd``: the three PID parameters.  (If you don't knowwhat they are you should [go read about how PIDs work](http://en.wikipedia.org/wiki/PID_controller), though you maybe able to get away with using defaults based on the test code herein.)* ``direct``: True if an increase in the output value will produce anincrease 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()`` asfrequently as possible, preferably via an interrupt of some sort. Thefrequency required for good results will depend on the characteristicsof your entire system, but the default update frequency of 100milliseconds is probably a good place to start. If the system isworking, 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 atany 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 numberof milliseconds. The default value is ``100``. If you want to change theset point, just set ``pid.setpoint``, and if you want to re-set any of thePID parameters you can call ``pid.set_tunings(kp, ki, kd)``. The system shouldbe 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 itfrom 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 simplesimulation of a heater attached to a tank of water, and some tests tosee what the PIDs behavior is when attached to the heater simulation.The heater, when turned on, heats up at a certain rate, and if itstemperature is above the ambient temperature willlose a certain amount of heat to the environment over time.The first test should demonstrate that the dummy heater is basically working.test.py 0The second test should demonstrate that the system can bring the water toa given temperature and hold it there.test.py 1Caveats-------This is basically first draft code. Since the object is relatively straightforward there'shardly any need. If this bothers you, go ahead and add them,though it is not inconceivable that I would eventually get around to itmyself. Nevertheless, it should be usable as-is without too muchdifficulty.This code depends on ``pid.compute()`` being called at a predictable interval. It won'twork as well under conditions which delay the call by too much, such asuse under a non-real-time operating system which is trying to do toomany things.There are other PID features which could be added to make this evenbetter. I'm not even sure I know what they are. If you do, feel freeto 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