This package provides general PID_ control software in Python with a
Melcor MTCA backend.  The idea is that experimentalists interested in
temperature controlled experiments or other processes should not need
to learn the inner workings of their PID controller before they can
perform simple control tasks.

Module structure
================

This package provides both a high level controller that uses
per-device backend drivers.  The controller handles auto-tuning the
PID feedback parameters and changing system temperatures, while the
backends communicate setpoint changes, temperature read requests,
etc. to the temperature control device.

Backends
--------

The only physicsal backend that is supported at the moment is a Melcor
Series MTCA Thermoelectric Cooler Controller, which we communicate
with via Modbus_ packets over a `serial port`_.  That's all I needed
for my experiments, but I tried to write a framework that was flexible
enough to swap in other backends.  By subclassing `Backend` for your
particular device, you can take advantage of the high-level
`Controller` code that's already written.

Melcor
~~~~~~

Companies don't stay in business forever, but lab equipment does ;).
Our controller is still going strong since 1999, but Melcor has moved
around.  According to their `2005 announcement`__ the Laird Group PLC
purchased Melcor from Fedders Corporation, and by 2009 (according to
the `Internet Archive Wayback Machine`__) they phased out the old
website at `melcor.com`_ in favor of `their own thermal site`__, and
it looks like there is no longer support for the older MTCA
controllers.  There seem to be a number of them on eBay_ though ;).

__ `Laird announcement`_
__ wayback_
__ `Laird thermal`_

TestBackend
~~~~~~~~~~~

To get a feel for driving a PID system, look atcheck out the
`TestBackend`, which simulates a standard first-order process with
dead time (FOPDT).

Installation
============

Packages
--------

Gentoo
~~~~~~

I've packaged `pypid` for Gentoo_.  You need layman_ and my `wtk
overlay`_.  Install with::

    # emerge -av app-portage/layman
    # layman --add wtk
    # emerge -av dev-python/pypid

Dependencies
------------

If you're installing by hand or packaging `pypid` for another
distribution, you'll need the following dependencies:

=========  =====================  ================  ==========================
Package    Purpose                Debian_           Gentoo_
=========  =====================  ================  ==========================
aubio_     Pitch detection        python-aubio      media-libs/aubio
nose_      testing                python-nose       dev-python/nose
NumPy_     Controller analysis    python-numpy      dev-python/numpy
pySerial_  serial comminication   python-serial     dev-python/pyserial
pymodbus_  Modbus stack           python-modbus     dev-python/twisted
SciPy_     Controller analysis    python-scipy      dev-python/scipy
=========  =====================  ================  ==========================

Actually, `pymodbus` may (depending on your packaging system) depend
on `pySerial`_ via Twisted_, so `pymodbus` alone may be enough to get
you going.

The Debian package for `pymodbus` has not been accepted yet.  `Debian
bug #578120`__ tracks the progress of the prospective package, but it
seems to have stalled out at the moment.

__ db578120_

Installing by hand
------------------

Pypid is available as a Git_ repository::

    $ git clone git://tremily.us/pypid.git

See the homepage_ for details.  To install the checkout, run the
standard::

    $ python setup.py install

Usage
=====

See the examples in the `examples` directory.

Testing
=======

Run the test suite with::

    $ nosetests --with-doctest --doctest-tests pypid

Note that you should have your temperature control device connected to
your computer before running this command, as backend tests require a
connected backend.

Licence
=======

This project is distributed under the `GNU General Public License
Version 3`_ or greater.

Author
======

W. Trevor King
wking@tremily.us
Copyright 2008-2012


.. _PID: http://en.wikipedia.org/wiki/PID_controller
.. _Modbus: http://en.wikipedia.org/wiki/Modbus
.. _serial port: http://en.wikipedia.org/wiki/Serial_port
.. _Laird announcement: http://www.lairdtech.com/NewsItem.aspx?id=953
.. _wayback: http://web.archive.org/web/20090204201524/http://melcor.com/
.. _melcor.com: http://melcor.com
.. _Laird thermal: http://lairdtech.thomasnet.com/category/thermal-management-solutions/
.. _eBay: http://www.ebay.com/
.. _layman: http://layman.sourceforge.net/
.. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
.. _Debian: http://www.debian.org/
.. _Gentoo: http://www.gentoo.org/
.. _aubio: http://aubio.org/
.. _NumPy: http://numpy.scipy.org/
.. _pymodbus: http://code.google.com/p/pymodbus/
.. _pySerial: http://pyserial.sourceforge.net/
.. _Twisted: http://twistedmatrix.com/trac/
.. _SciPy: http://www.scipy.org/
.. _db578120: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=578120
.. _nose: http://somethingaboutorange.com/mrl/projects/nose/
.. _Git: http://git-scm.com/
.. _homepage: http://blog.tremily.us/posts/pypid/
.. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.txt