----------------------------------------------------------------------------
  DigiTemp v3.1.0 for Linux			    (c)2003 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.brianlane.com/ and looking at the DigiTemp page for the latest
release, or use the forums to talk to other DigiTemp users.

  -----
  Version 3.1.0 adds support for the DS2406 counters. A new output format
specifier has been added, using the -O option (capital Oh, not lower case).
I have included my first pass at a python script to log to MySQL and RRD.

  Version 3.0.0 add support for both the DS9097 passive adapter, and the newer
DS9097U adapter. It also introduces a better makefile and less CPU usage
when repeatedly reading multiple sensors.

  Version 2.5 adds compilation under Solaris. A new log option of %R has
been added to output the serial number in hex in the logging output string.
The quiet -q option now quiets down the 1-Wire walk and initalize routine so
that only the important information is output.

  Version 2.4 fixes the problems (finally!) with the DS18B20 and DS1822
sensors. I have also modified the search and read algorithms so that they
will work faster when used with a 1-wire hub.

  Version 2.3 adds support for one wire hubs like Simon Atkin's hub that can
be found at www.simat.enta.net

  -----

  Version 2.0+ removes support for the old adapter (based on the one
described in App. Note 74 from Dallas Semiconductor. Version 1.3 still
supports the older adapters and is now also released under the GNU public
license). This new version uses the DS9097-U adapter available from Dallas
Semiconductor. You can order them from their iButton webpage at
www.ibutton.com

  This adapter is more expensive but is easier to program and support higher
current capability so that it should work at higher temperatures than the
previous adapter.

  -----

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


  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 DS9097-U into the connector if you haven't already. 9-pin to 25-pin
     adapters can be used if they connect all the pins across.

  3. Initialize the ./.digitemprc file with the following command:

    digitemp -s/dev/ttyS2 -i

    You should see a response like this:
       DigiTemp v2.1 Copyright 1997-2001 by Brian C. Lane
       GNU Public License v2.0

       ROM #0 : 1077790000000078
       ROM #1 : 10777A0000000036

    The ROM numbers for your sensors will be different of course. They are
    listed in the order that the search routine finds them. You can then use
    the -t X command to read a single sensor at a time.

    The .digitemprc file is saved in the current directory so that you can
    have multiple configurations in different directories. If you run
    digitemp from a crontab and haven't changed the path it will write the
    .digitemprc file into your home directory.

 4. Read all the temperatures with this command:

    digitemp -a

    You should see something like this:
       DigiTemp v2.1 Copyright 1997-2001 by Brian C. Lane
       GNU Public License v2.0

       Dec 29 20:52:28 Sensor 0 C: 22.90 F: 73.22
       Dec 29 20:52:29 Sensor 1 C: 1.70 F: 35.06

 5. If it doesn't work, try running the initialization again.
    Make sure you have the right serial port and that it works, try
    plugging an external modem into the port and check that it works by
    using the minicom terminal program. If all else fails, email me! One
    problem I ran into during development was using 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.

    With newer kernels (v2.2.x) I've noticed that loadable serial support
    doesn't seem to cause any problems, so you might want to try it both
    ways and use whatever works.

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


  Overview
  --------

  When you specify the -i option to initialize the .digitemprc file the program
will store the serial port, serial numbers of the attached DS1820's, the read
delay time, log format type, and the log specifier string. The .digitemprc
file is written into the current directory.

  With v2.1 you have the option of specifying the location of the
configuration file by using the -c command line argument.

  The .digitemprc file is read before the command line arguments are read,
this way the configuration can be temporarily overridden by passing
arguments to the digitemp program.

  Digitemp needs at least the -a or -t option to tell it to read 1 sensor or
read all of the sensors. This is after you have initialized the system with
the -i command of course.


  Tree Walking
  ------------
  
  No acrobatics here, but if you run ./digitemp -w -s/dev/ttySx the program will
show all devices on the one-wire network and traverse all couplers connected
to the main LAN. The only think it doesn't support is couplers attached to
one branch of another coupler.


  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

  This runs as root, and can be added to your crontab using the crontab -e
command from the user's account that you want to run digitemp from.

  The format of the data to be written to the logfile can be controlled in
several ways. The default is to use a format specifier string that outputs
a line of data like: Dec 29 20:52:29 Sensor 1 C: 1.70 F: 35.06

  The -o argument is used to change this. Using -o2 or -o3 will output all the
sensor readings on a single line like: 0       23.22   1.33    12.69

  The first number is the elapsed time (see timing, below) and the rest are
the sensor readings, separated by tabs. This makes it easy to import the data
into a spreadsheet program. The data is output in Centigrade when -o2 is used
and Fahrenheit when -o3 is used.

  The other option is to use a format specifier string. To do this you pass
the string as the argument to -o, like this:
  -o"%b %d %H:%M:%S Sensor %s C: %.2C F: %.2F"

  The specifiers are the same as those used for strftime with the addition of
five special ones. %s for the sensor number, %C for the temperature in
Centigrade and %F for the temperature in Fahrenheit. %R outputs the sensor's
serial number in HEX, and %N output the number of seconds since Epoch (this
is because DigiTemp's %s masks the %s which normally does this in strftime.
See the strftime manpage for the rest of the specifiers that are supported.

  The new counter specifier string has 2 special specifiers:
  %n is the number of the counter
  %C is the count for that counter

  In the rrdb directory you will find a collection of scripts that I use to
generate the graphs at www.brianlane.com/digitemp.php, they create a RRDB
database and log data to it every 5 minutes. The web server dynamically
generates a graph when a page update is requested.

  RRDB is the Round Robin Database Tool, and it is available for free from
its website at http://ee-staff.ethz.ch/~oetiker/webtools/rrdtool/

  Timing
  ------

  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 milliseconds to do the conversion and make the
temperature available to DigiTemp). The default value for this is 1000mS. 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 Read timeout is set too short the temperature will not be read correctly.
The shortest I can set it with my sensors is 300mS before they fail. You may
have other problems if the delay is set too short, depending on the
temperature being read. I currently have mine set to 1000mS.

  The older DS1820 sensors would work with a read timing of about 500mS, but
the new (and greatly improved IMHO) DS18S20 takes a little longer, between
750mS and 1S, so I have set the default to 1S.

Repeated Temperature Sampling
-----------------------------

  You can setup a script to repeatedly call DigiTemp and process its output,
or you can setup DigiTemp to repeatedly sample the sensors and output the
data in one of the logfile formats specified in the 'Temperature Logging'
section of this document.

  -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 sampling process has taken longer than the interval you
	have specified so that you can adjust it accordingly.

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

  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 to sample
every 10 seconds for a count of 180 (10 x 180 = 1800 seconds = 3 minutes) like
this:

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

  This outputs the data as tab separated Centigrade readings to a file named
data1.txt in the current directory.


  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
                www.brianlane.com/digitemp.php 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.

  maxplot	This perl script generates the temperature graph that you
		can use on your webpage.
		They require the GD module for perl, which is available
		from -
                  http://www.perl.com/CPAN-local//modules/by-module/GD/

		It generates 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 to customize it for
		your setup.

  RRD tool	I have also written several scripts to manipulate data
		with RRD (Round Robin Database) tool databases. RRD tool
		is available from -
		  http://ee-staff.ethz.ch/~oetiker/webtools/rrdtool/
		There are several scripts, one to add data to the database,
                and one to retrieve data as a .png image.

  NetSaint      I have written a Net Saint/Nagios (http://www.nagios.com)
		plugin. It is named check_digitemp.pl and it located in the
		perl directory. Installation instructions are in the top of
		the file's comments.

  MySQL		I have written a perl script to log temperature readings to
		a MySQL database. It is named digitemp_mysql.pl and is in
		the perl directory. Instructions for setup and use are in
		the README file in the perl directory.

    The scripts have been commented so that you can change them easily (I
hope! Email any changes you have). 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.

  Have Fun! And when you get your sensors up on your website send me the URL
and I will add it to the list at http://www.brianlane.com/digitemp.php

    Brian C. Lane
    bcl@brianlane.com
    www.brianlane.com
