----------------------------------------------------------------------------
  DigiTemp v1.3 for Linux		     (c)1996-2000 by Brian C. Lane
============================================================================

  Thank you for using DigiTemp for Linux. If you have any problems or
suggestions please feel free to contact me at bcl@brianlane.com You
can get the latest information by pointing your web browser at
http://www.brianlen.com/ or by subscribing to the digitemp mailing
list by sending a blank email to digitemp-subscribe@brianlane.com

  01/04/2000 GNU Public License release
  -------------------------------------

  DigiTemp is now Open Source using the GNU Public License v2.0, see the
COPYING file for a copy of the full license. Along with this license change
I am releasing v2.0 which supports the DS9097-U adapter that is available
from Dallas Semiconductor. I will no longer be writing code for the older
type of adapter.


  05/23/99 Important News
  -----------------------

  I have discontinued support for libc5 binaries. I no longer have libc5
installed on any of my systems, so it is difficult for me to support libc5.
If you buy the source, you can easily compile it with your libc5 system. I
apologize for any problems this may cause.

  -----

  Previous versions had a bug in the code for negative temperatures.
Basically it wasn't converting correctly for temperatures below 0C. This has
been fixed (it was a 1-off error in the do_temp() routine).

  -----

  Because of the way that DigiTemp is designed it will not be able to read
temperatures above about +70C, even though the DS1820 is designed to work up
to +125C. This is because of the power requirements for reading higher
temperatures and the voltage drop across the resistor in the simple circuit
that DigiTemp uses.


  Quick Setup
  -----------

  If you are like me you want to just plug it in and run it, right? Ok,
follow these steps to start reading temperatures:

  1. Find a free serial port on your system (I'll use /dev/ttyS2 in these
     examples).

  2. Plug DigiTemp into the connector if you haven't already.

  3. Initalize the .digitemprc file with the following command:

    digitemp -s/dev/ttyS2 -i

    You should see a response like this:
       DigiTemp v1.2 Copyright 1999 by Brian C. Lane

       ROM #0 : 1077790000000078
       ROM #1 : 10777A0000000036

    The ROM numbers for your sensors will be different of course.

    The .digitemprc file is saved in the current directory so that you can
    have multiple configurations.

 4. Read temperatures with this command:

    digitemp -a

    You should see something like this:
       DigiTemp v1.2 Copyright 1999 by Brian C. Lane

       Sensor 0 C: 37.59 F: 99.67
       Sensor 1 C: 21.53 F: 70.75


 5. If it doesn't work, try running the initalization again.
    Make sure you have the right serial port and that it works, try
    plugging a known working modem into the port. If all else fails,
    email me! One problem I ran into during development was uaing kerneld
    to load serial support on demand -- you should have serial compiled into
    the kernel, not as a module (or if you have it as a module, use insmod
    to load it).

    Also make sure the user running digitemp has permission to access the
    serial port you are using.

 6. Read the rest of this document to learn how to log data to a file, and
    how to upload include files to a remote web server.


  Overview
  --------

    When DigiTemp initalizes it stores the serial port and serial numbers
into a file called .digitemprc in the current directory. It reads this file
to set the default options when run. The command line arguments can be used
to override the settings in .digitemprc temporarily.


  Temperature Logging
  -------------------

    To log temperatures to a logfile instead of to the console you use the
-l command line option. I have a cron job that runs every 30 minutes and
logs the temperatures to a file called /var/log/temperature. The cron entry
look like this:

    0,30 * * * *      /usr/local/bin/digitemp -a -l/var/log/temperature


  Timing
  ------

    There are two timing values that you can adjust and store to the
.digitemprc file. They are the Failure timeout and the Read timeout. The
Failure timeout is the amount of time to wait for a response from DigiTemp
before failing the operation. The default is 5 seconds. The Fail timeout can
be set by issuing the following command:

    digitemp -f5     Set the Fail timeout to 5 seconds
    digitemp -i -f5  Set the Fail timeout to 5 seconds and store to .digitemprc

    The Read timeout is the amount of time for DigiTemp to pause after
issuing a temperature conversion command before it reads the temperature
(it takes the DS1820 a few microseconds to do the conversion and make the
temperature available to DigiTemp). The default value for this is 500mS. The
Read timeout can be set by issuing the following command:

    digitemp -r500      Set Read timeout to 500mS
    digitemp -i -r500   Set Read timeout to 500mS and save to .digitemprc

    If you don't specify either of these parameters then they are set to the
defaults. If Read timeout is set too short the temperature will not be read
too correctly. The shortest I can set it with my sensors is 300mS before
they fail.


New Features for v1.1+
----------------------

  I have added 3 new commands to v1.1 of the digitemp program. They allow
you to repeatedly sample the sensors and store the data in a format suitable
for importing into a spreadsheet or graphing program.

  -dx   This sets the sample interval. x is a number in seconds.
	-d5 will sample at 5 second intervals. The number of sensors
	that you have attached will determine the minimum interval that
	you can use. It can take as long as 1/2 second to sample each
	sensor attached, so if you have 6 sensors you will probably have
	a minimum sample interval of 3 seconds. The program will tell you
	when the sampleing process has taken longer than the interval you
	have specified.

  -nx   This sets the number of times to sample all the specified sensors.
	-n10 will sample 10 times.

  -ox   This sets the output format. -o1 is the default, displaying one
	sensor reading per line, with the date, time, C and F
	-o2 will display one line for each sample point. It will show
	the elapsed time in seconds, sensor #1, #2, etc. The fields are
	separated by tabs, and temperatures are displayed in C
	-o3 is the same as -o2 except that the temperatures are in F

  The output can be sent to a file by using the -lfilename.txt options. So
to log data every 10 seconds for 30 minutes you would run digitemp like
this:

    digitemp -a -d10 -n180 -o2 -ldata1.txt


  Web scripts
  -----------

    I have written some Perl scripts for use with local or remote web
pages:

  web_temp	This can be used as a CGI binary and will show the last
		two entries from the /var/log/temperature file

  inc_temp	This can be called from a cron job to create a server side
		include file that can be included from your webpage.

  rem_temp	This is the script I use to update my webpage at
                http://www.eskimo.com/~nexus every hour (or whenever the
		script can get through the busy signals). It creates
		a shtml file in the /tmp/ directory and then uses the Perl
		ftp functions to upload it to the remote site. The script
		lists the modules that need to be added to Perl to enable
		ftp.

		You need to have a connection script working for this script
		to work correctly. Or if you have diald just comment out
		the ppp-on and off lines. Please consult the various linux
		howto FAQs for information on how to construct the connect
		scripts if you don't already have them set up.

  led_temp	This is the rem_temp script with the addition of the
		creation of a script for the Java applet LED Sign v2.7
		This script may be a little out of date, I no longer use
		the LED sign. Java, in my opinion, is just too darn slow.

  tempplot	These perl scripts generate the temperature graph that you
  maxplot	see on my webpage (http://www.tatoosh.com/tempplot.shtml)
		They require the GD module for perl, which is available
		from -
                  http://www.perl.com/CPAN-local//modules/by-module/GD/

		They generate a .gif file, and move the file to the
		final location, so it will need some small changes
		in the paths and ownership at the end of the scripts.

    The scripts have been commented so that you can change them easily.
There are several variables that need to be setup for your system before
they will run.

  If you have any comments, questions, or scripts that you would like to
donate, drop me an email, and I'll set up a ftp directory for user
contributions.

    Brian Lane
    bcl@brianlane.com
    http://www.brianlane.com
