$Id: README,v 1.4 2004/06/20 07:50:08 grog Exp $

This directory contains the source files for tempcontrol, a
temperature control program.  In its current version it is
specifically designed to control the temperature of beer fermenters in
a fridge.  It controls the temperatures when necessary by turning on
either the fridge motor to cool the surroundings, or a light bulb to
warm them.

The specific brewing-related details are relatively minor, and future
versions may become more general-purpose.

There should be real documentation for this program, but currently (20
June 2004) there isn't.  You can find more information on the web at
http://www.lemis.com/grog/brewing/temperature-control.html.  The
version of this page current at the time of writing is in this archive
as webpage.pdf; you'll need Acrobat reader to read it.  I still
recommend that you look at the web page: it contains numerous links,
including links to larger images.  Also, I will not automatically
update the distribution archive when I update the web page, so it's
better to check the web page if you can.  Look for the last
modification date:

  Last modified: $Date: 2004/06/20 07:50:08 $

If the date matches, the version is the same.

Here's a brief overview of the program:

0.  License requirements
------------------------

This software is available under a license.  You may not use the
software unless you accept it.  It's in the file LICENSE in this
directory, and states:

 Copyright (c) 2004 by Greg Lehey
 
  This software is distributed under the so-called ``Berkeley 
  License'': 
 
 Redistribution and use in source and binary forms, with or without 
 modification, are permitted provided that the following conditions 
 are met: 
 
 1. Redistributions of source code must retain the above copyright 
    notice, this list of conditions and the following disclaimer. 
 2. 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. 
 
 This software is provided ``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 Domenick Venezia 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. 

1.  Hardware requirements
-------------------------

The current version of the program requires:

 * An old computer, of course.  The size of the one I chose is simple:
   that's what I had left over.  It's an Intel 486-DX2/66 with 16 MB
   of RAM, something you can probably pick up for free if you know
   where to look.

 * A temperature logger kit available from Ozitronics kits.  See
   http://ozitronics.com/kitlist.html#k145 for more details.  It
   connects to the system via the serial port.

 * A relay board</a> also available from Ozitronics kits.  See
   http://ozitronics.com/kitlist.html#k74 for more details.  It
   connects to the parallel port and controls up to 8 relays with up
   to 250 VAC and 10 A, though they recommend additional wiring for
   currents of over 5 A.  A fridge typically uses a maximum of 3A, so
   this is of academic interest only.

The real fun in getting this working wasn't the hardware, which is
easy enough to get.  It's also not really the software, since I've
written it.  The real problem were the little details and connectors
and things.  I spent a lot of time--see the web page above--trying to
decide how to connect things.  Finally I discovered an old computer
lying around without a mother board, so all the front panel connectors
were hanging loose.  That's exactly what I was looking for to mount
the temperature sensors.

Other issues in the mounting included the fact that the kits are
designed for external mounting (and the relay board needs a 12V power
supply).  I wanted to mount both inside, which had the added advantage
that I could use the computer power supply to power the relay board.
The problem was a certain amount of external cabling.

2.  Software requirements
-------------------------

This software was developed under FreeBSD.  It compiles under Linux,
provided you have ncurses and readline installed, but I haven't tested
it.  If there are any issues, they'd probably be with controlling the
relay board via the parallel port.

It's pretty certain that the software will not compile and run on
Microsoft platforms without some changes.  It's written in C, so most
of it should be pretty straightforward.  If you do this work, please
let me know and I'll put your changes into the sources.

3. Installing the software
--------------------------

If you're installing this software on FreeBSD, you should use the
port:

  # cd /usr/ports/misc/tempcontrol
  # make install

On any platform, you can also unpack the archive in an empty directory
of your choice, and do:

  # cd directory-of-my-choice
  # make install

If you install this program on a new platform, please send me diffs so
that I can keep it as portable as possible.

4.  Configuring the software
----------------------------

The program is controlled by a configuration file called
/usr/local/share/tempcontrol/.temperaturecontrolrc.  On FreeBSD at any
rate, the installation will create a sample configuration file
/usr/local/share/tempcontrol/temperaturecontrolrc.sample.  This file
contains all the possible configuration parameters set to their
default values, so effectively it makes no difference.  It does,
however, contain a large number of comments.  Read the comments to
decide what you need to change.  You can either copy this file to
/usr/local/share/tempcontrol/.temperaturecontrolrc or create your own
one with only the values that interest you.

The most important things to change are:

1.  The temperature you want to maintain ("goal temperature").  You
    almost certainly want to set this.

2.  The numbers of the temperature probes, if they don't match the
    defaults.  The program only needs a single probe, the fermentation
    temperature probe, but since the logger kit comes with up to four
    sensors, it logs the following information:

    - fermentation temperature probe.
    - fridge temperature probe ("ambient" temperature).
    - temperature outside the fridge.
    - a second fermenter temperature probe.

    The log output logs all this information.  If you have a second
    fermentation temperature probe, you can use the configuration
    parameter probe2factor to specify to what extent it should be
    involved in the temperature control.

3.  The names of the log files.

4.  Add the command 'monitor' at the end of the configuration file.
    This command starts the temperature monitoring, the real meat of
    the program.  If you don't have a configuration file, or if it
    doesn't contain the 'monitor' keyword, you'll get a command line
    prompt.

    Note that configuration information after the 'monitor' command
    will not be executed, since monitor does not complete.

When running, the program checks for changes in the configuration file
after every temperature measurement (a little more than once a
second).  If it has changed, it reads in the configuration file and
changes its behaviour accordingly.  You don't need to restart the
program to change parameters.

5. Running the software
-----------------------

To run the program, simply type the name:

  # tempcontrol

If you have a configuration file, it will be processed.  If it doesn't
contain a 'monitor' command at the end, you will get a command line
prompt, to which you can enter configuration commands.  Normally
you'll enter the keyword 'monitor' to run the program itself.

By default, when monitoring, a continually refreshed display appears
on the terminal; see the configuration parameter "displayfile".

It's a good idea to start the program automatically when the system
boots.  If you have a power failure in the middle of the night, for
example, you'll want the system to reboot and carry on monitoring the
temperature.

The installation process installs a file
'temperaturecontrol.sh.sample' in the directory /usr/local/etc/rc.d/.
To enable automatic startup, rename this file to
'temperaturecontrol.sh'.

6.  Problems
------------

On FreeBSD, I've had surprisingly few problems.  The program also
compiles on Linux, but I haven't tried running it.  I don't expect any
show-stoppers, though a little experimentation may be needed with the
device names for the serial and parallel ports.  I have no idea what
kind of hoops you'd need to jump through to get it to work on
Microsoft, but it's written in standard C, so theoretically it
shouldn't be a big problem.  If you have either success or failure
installing on a new platform, please let me know.  I don't promise to
help, though I may if I can, but I'd like to know.

Greg Lehey
grog@lemis.com