README

   1 This package provides an object-oriented interface for temperature
   2 monitoring and PID_ control.  The idea is that experimentalists
   3 interested in temperature controlled experiments should not need to
   4 learn the inner workings of their PID controller before they can
   5 perform simple temperature control tasks.
   6
   7 Module structure
   8 ================
   9
  10 This package provides both a high level controller that uses
  11 per-device backend drivers.  The controller handles auto-tuning the
  12 PID feedback parameters and changing system temperatures, while the
  13 backends communicate setpoint changes, temperature read requests,
  14 etc. to the temperature control device.
  15
  16 Backends
  17 --------
  18
  19 The only physicsal backend that is supported at the moment is a Melcor
  20 Series MTCA Thermoelectric Cooler Controller, which we communicate
  21 with via Modbus_ packets over a `serial port`_.  That's all I needed
  22 for my experiments, but I tried to write a framework that was flexible
  23 enough to swap in other backends.  By subclassing `Backend` for your
  24 particular device, you can take advantage of the high-level
  25 `Controller` code that's already written.
  26
  27 Melcor
  28 ~~~~~~
  29
  30 Companies don't stay in business forever, but lab equipment does ;).
  31 Our controller is still going strong since 1999, but Melcor has moved
  32 around.  According to their `2005 announcement`__ the Laird Group PLC
  33 purchased Melcor from Fedders Corporation, and by 2009 (according to
  34 the `Internet Archive Wayback Machine`__) they phased out the old
  35 website at `melcor.com <http://melcor.com>`_ in favor of `their own
  36 thermal site`__, and it looks like there is no longer support for the
  37 older MTCA controllers.  There seem to be a number of them on eBay_
  38 though ;).
  39
  40 __ `Laird announcement`_
  41 __ wayback_
  42 __ `Laird thermal`_
  43
  44 TestBackend
  45 ~~~~~~~~~~~
  46
  47 To get a feel for driving a PID system, check out the `TestBackend`.
  48 For example, you can experiment with different feedback terms and dead
  49 times to understand why you're getting instability or other control
  50 effects.  Here's an example that shows a reasonable approach with a
  51 bit of integrator overshoot::
  52
  53   >>> from tempcontrol.backend.test import TestBackend
  54   >>> from time import sleep
  55   >>> from matplotlib import pyplot
  56   >>> from numpy import loadtxt
  57   >>> log_file = 'pid.log'
  58   >>> log_stream = open('pid.log', 'w')
  59   >>> b = TestBackend(log_stream=log_stream)
  60   >>> b.set_max_current(0.6)
  61   >>> b.set_heating_gains(propband=2, integral=.1)
  62   >>> b.set_cooling_gains(propband=2, integral=.1)
  63   >>> b.set_setpoint(25)
  64   >>> sleep(120)
  65   >>> t.cleanup()
  66   >>> log_stream.close()
  67   >>> header = open(log_file, 'r').readline()
  68   >>> label = header.strip('#\n').split('\t')
  69   >>> data = loadtxt('pid.log')
  70   >>> pyplot.hold(True)
  71   >>> for i in range(1, len(label)):
  72   ...     if i in [1, 3, 5]:
  73   ...         if i:
  74   ...             pyplot.legend(loc='best')  # add legend to previous subplot
  75   ...         pyplot.subplot(3, 1, (i-1)/2 + 1)
  76   ...     pyplot.plot(data[:,0], data[:,i], '.', label=label[i])
  77   >>> pyplot.legend(loc='best')
  78   >>> pyplot.show()
  79
  80 Of course, you can use whatever plotting program you like to graph the
  81 values stored to `pid.log`.  Matplotlib_ and NumPy_ are just
  82 convenient Python-based packages.
  83
  84 Installation
  85 ============
  86
  87 Packages
  88 --------
  89
  90 Gentoo
  91 ~~~~~~
  92
  93 I've packaged `tempcontrol` for Gentoo_.  You need layman_ and my `wtk
  94 overlay`_.  Install with::
  95
  96     # emerge -av app-portage/layman
  97     # layman --add wtk
  98     # emerge -av dev-python/tempcontrol
  99
 100 Dependencies
 101 ------------
 102
 103 If you're installing by hand or packaging `tempcontrol` for another
 104 distribution, you'll need the following dependencies:
 105
 106 =========  =====================  ================  ==========================
 107 Package    Purpose                Debian_           Gentoo_
 108 =========  =====================  ================  ==========================
 109 pymodbus_  Modbus stack           python-modbus     dev-python/twisted
 110 pySerial_  serial comminication   python-serial     dev-python/pyserial
 111 nose_      testing                python-nose       dev-python/nose
 112 =========  =====================  ================  ==========================
 113
 114 Actually, `pymodbus` may (depending on your packaging system) depend
 115 on `pySerial`_ via Twisted_, so `pymodbus` alone may be enough to get
 116 you going.
 117
 118 The Debian package for `pymodbus` has not been accepted yet.  `Debian
 119 bug #578120`__ tracks the progress of the prospective package, but it
 120 seems to have stalled out at the moment.
 121
 122 __ db578120_
 123
 124 Installing by hand
 125 ------------------
 126
 127 Tempcontrol is available as a Git_ repository::
 128
 129     $ git clone http://www.physics.drexel.edu/~wking/code/git/tempcontrol.git
 130
 131 See the homepage_ for details.  To install the checkout, run the
 132 standard::
 133
 134     $ python setup.py install
 135
 136 Usage
 137 =====
 138
 139 See the examples in the `examples` directory.
 140
 141 Testing
 142 =======
 143
 144 Run the test suite with::
 145
 146     $ nosetests --with-doctest --doctest-tests tempcontrol
 147
 148 Note that you should have your temperature control device connected to
 149 your computer before running this command, as backend tests require a
 150 connected backend.
 151
 152 Licence
 153 =======
 154
 155 This project is distributed under the `GNU General Public License
 156 Version 3`_ or greater.
 157
 158 Author
 159 ======
 160
 161 W. Trevor King
 162 wking@drexel.edu
 163 Copyright 2008-2011
 164
 165
 166 .. _PID: http://en.wikipedia.org/wiki/PID_controller
 167 .. _Modbus: http://en.wikipedia.org/wiki/Modbus
 168 .. _serial port: http://en.wikipedia.org/wiki/Serial_port
 169 .. _Matplotlib: http://matplotlib.sourceforge.net/
 170 .. _NumPy: http://numpy.scipy.org/
 171 .. _Laird announcement: http://www.lairdtech.com/NewsItem.aspx?id=953
 172 .. _wayback: http://web.archive.org/web/20090204201524/http://melcor.com/
 173 .. _Laird thermal: http://lairdtech.thomasnet.com/category/thermal-management-solutions/
 174 .. _eBay: http://www.ebay.com/
 175 .. _layman: http://layman.sourceforge.net/
 176 .. _wtk overlay:
 177      http://www.physics.drexel.edu/~wking/unfolding-disasters/posts/Gentoo_overlay
 178 .. _Debian: http://www.debian.org/
 179 .. _Gentoo: http://www.gentoo.org/
 180 .. _pymodbus: http://code.google.com/p/pymodbus/
 181 .. _pySerial: http://pyserial.sourceforge.net/
 182 .. _Twisted: http://twistedmatrix.com/trac/
 183 .. _db578120: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=578120
 184 .. _nose: http://somethingaboutorange.com/mrl/projects/nose/
 185 .. _Git: http://git-scm.com/
 186 .. _homepage:
 187      http://www.physics.drexel.edu/~wking/unfolding-disasters/posts/tempcontrol/
 188 .. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.txt