----------------------------------------------------------------------------
  DigiTemp v3.7.2 for Linux                 (c)1996-2018 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 [email protected]

You can get the latest information by pointing your web browser at
http://www.digitemp.com/ and look at the Software page for the latest
release, or use the forums to talk to other DigiTemp users.

There is a DigiTemp support mailing list available from
https://lists.brianlane.com/mailman/listinfo/


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

  DigiTemp requires very little setup in order to work. Basically there are 3
requirements:

  1. Permission to access the serial port you will be using.
  2. A 1-wire serial port adapter
  3. A 1-wire sensor connected to the adapter

  If you think you have all of these taken care of you can try the following to
see if it 'Just Works':

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

    digitemp -s/dev/ttyS2 -i

    If you had my 1-wire setup (hub and sensors) you would see this:

	DigiTemp v3.3.0 Copyright 1996-2004 by Brian C. Lane
	GNU General Public License v2.0 - http://www.brianlane.com
	Turning off all DS2409 Couplers
	...
	Searching the 1-Wire LAN
	1F404301000000E4 : DS2409 MicroLAN Coupler
	1FB03001000000B5 : DS2409 MicroLAN Coupler
	1F881D01000000ED : DS2409 MicroLAN Coupler
	22B9B20500000049 : DS1822 Econo-Temperature Sensor
	286D1D2D000000EA : DS18B20 Temperature Sensor
	104C4D55000800D9 : DS1820/DS18S20/DS1920 Temperature Sensor
	1092B9330008002E : DS1820/DS18S20/DS1920 Temperature Sensor
	1009212E0008004B : DS1820/DS18S20/DS1920 Temperature Sensor
	1067FF33000800C2 : DS1820/DS18S20/DS1920 Temperature Sensor
	26E22C1500000046 : DS2438 Temperature, A/D Battery Monior
	ROM #0 : 22B9B20500000049
	ROM #1 : 286D1D2D000000EA
	ROM #2 : 104C4D55000800D9
	ROM #3 : 1092B9330008002E
	ROM #4 : 1009212E0008004B
	ROM #5 : 1067FF33000800C2
	ROM #6 : 26E22C1500000046
	Wrote .digitemprc

    Your network will be different, but the output should look similar, with 
    it listing the recognized devices, their serial numbers, and ROM numbers.

 4. Read all the temperatures with this command:

    digitemp -a

    Again, if you were using the same 1-wire lan as I am you would see:

	DigiTemp v3.3.0 Copyright 1996-2004 by Brian C. Lane
	GNU General Public License v2.0 - http://www.brianlane.com
	Jan 11 08:33:41 Sensor 0 C: 22.50 F: 72.50
	Jan 11 08:33:42 Sensor 1 C: 31.44 F: 88.59
	Jan 11 08:33:43 Sensor 2 C: 21.56 F: 70.81
	Jan 11 08:33:44 Sensor 3 C: 12.19 F: 53.94
	Jan 11 08:33:46 Sensor 4 C: 21.00 F: 69.80
	Jan 11 08:33:47 Sensor 5 C: 4.38 F: 39.88
	Jan 11 08:33:48 Sensor 6 C: 27.53 F: 81.56 H: 23%

 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 a terminal program such as minicom. If all else fails, email me!

    On older Linux kernels there was a problem with serial port support
    being a loadable module. With newer (v2.2.x and later) Linux kernels I
    have not noticed any problems with loadable modules.

    The problems that people usually run into are:

	a. Permission problems. DigiTemp will complain if you don't have
	   +rw permission on the serial port specified so this is a pretty
	   easy one to catch.

	b. Wrong serial port. Make sure you know which port the adapter is
	   plugged into. If you are using a DS2480 based adapter DigiTemp
	   will complain when it cannot find the DS2480.

	c. Bad connections. Make sure your wiring is correct. This is usually
	   only a problem with home built passive adapters.

	d. Bad serial port. Test the port with an external modem to make sure
	   it really does work.

	e. If you are seeing a temperature reading of 85C then you probably
	   built your own sensors and didn't connect the sensor's +5v pin to
	   GND to enable parasite power mode (assuming that you are not using
	   an external +5v power supply).
	   It can also be caused by not enough read time, the DS18S20 needs
	   about 750mS to do a temperature conversion. This time can be
	   adjusted with the -r X argument, but the default is 1000mS which
	   should be fine for most applications.

 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.


  DigiTemp Overview
  -----------------

  DigiTemp is a command line application used for reading 1-wire sensors like
the DS18S20 temperature sensor, or DS2438 battery monitor. DigiTemp supports
the following devices:

  DS18S20 (and older DS1820) Temperature Sensor
  DS18B20 Temperature Sensor
  DS1822 Temperature Sensor
  DS2438 Battery monitor
  DS2409 1-wire coupler (used in 1-wire hubs)
  DS2422 Counter
  DS2423 Counter

  The output format can be customized and all settings are stored in a
configuration file (.digitemprc) in the current directory. DigiTemp can
repeatedly read the sensors and output to stdout and/or to a logfile.

  I include a variety of scripts in Perl and Python for processing the output
of DigiTemp and doing various things with the data. Like logging to a Round
Robin database for easy graph generation, logging to a MySQL database, or using
GNU Plot to plot graphs from logfiles.


  Initialization
  --------------

  Before you can read the sensors you need to initialize the list of serial
numbers (each 1-wire sensor has a unique 64 bit serial number used to address
it on the bus). When you add sensors to your lan you need to rerun the
initialization process -- be aware that the order that they are detected in
depends on their number, so when you add new sensors it may change the order
of your sensors.

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

  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 -w, -a or -t option to tell it to walk the lan,
read all sensors, or read 1 sensor. This is after you have initialized the
system with the -i command of course.

  You need to make sure you have permission to access the serial port. To
allow access to the serial port, add the user that will be running DigiTemp
to the uucp group (or whatever group owns the serial port device).



  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 thing it doesn't support is nested couplers (couplers
connected to the branch of another coupler). The output will identify each
device connected, even if it isn't a sensor that DigiTemp supports.

	DigiTemp v3.3.0 Copyright 1996-2003 by Brian C. Lane
	GNU General Public License v2.0 - http://www.brianlane.com
	Turning off all DS2409 Couplers

	Devices on the Main LAN
	1F404301000000E4 : DS2409 MicroLAN Coupler
	1FB03001000000B5 : DS2409 MicroLAN Coupler
	1F881D01000000ED : DS2409 MicroLAN Coupler


	Devices on Main Branch of Coupler : 1F404301000000E4

	Devices on Aux Branch of Coupler : 1F404301000000E4

	Devices on Main Branch of Coupler : 1FB03001000000B5
	22B9B20500000049 : DS1822 Econo-Temperature Sensor

	Devices on Aux Branch of Coupler : 1FB03001000000B5
	286D1D2D000000EA : DS18B20 Temperature Sensor

	Devices on Main Branch of Coupler : 1F881D01000000ED
	104C4D55000800D9 : DS1820/DS18S20/DS1920 Temperature Sensor
	1092B9330008002E : DS1820/DS18S20/DS1920 Temperature Sensor
	1009212E0008004B : DS1820/DS18S20/DS1920 Temperature Sensor
	1067FF33000800C2 : DS1820/DS18S20/DS1920 Temperature Sensor

	Devices on Aux Branch of Coupler : 1F881D01000000ED
	26E22C1500000046 : DS2438 Temperature, A/D Battery Monior


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

  To log temperatures to a logfile instead of to the console you use the
-l command line option. The logfile name may use strftime format to generate
the filename. 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 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.

  Using -o4 or -o5 will output all the sensor readings on a single line like:
1476177670       23.22   1.33    12.69

  Like -o2 and -o3 except the first number is the elapsed time since
1970-01-01 00:00:00 (unixtime).

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

  The counter log format is specified by the -O command line argument, it is
stored in the configuration file when executed with a -i command.

  Humidity support adds the %h specifier for humidity from 0-100%, and the
format is specified by the -H command line argument. It too is saved to the
configuration file when executed with a -i command. The %C and %F in the
humidity specifier will display the temperature of the humidity sensor.

  If the -A command is passed then the humidity sensor data will be output as
raw voltages from the DS2438. The format string for this is hard-coded and
the output looks like this:

	DigiTemp v3.3.0 Copyright 1996-2003 by Brian C. Lane
	GNU General Public License v2.0 - http://www.brianlane.com
	Jan 11 16:56:00 Sensor 6 VDD: 4.70 AD: 1.46 C: 27.94


  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/

  you will also find a collection of other useful scripts, written in Perl and
in Python in the perl and python directories. All of these scripts will need 
some tweaking to work with your unique setup.


  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. Setting -n0 will make it loop forever.

  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.

  To log continously every 10 seconds into files named with current date:

    digitemp -a -d10 -n0 -o4 -ltemperature-%Y%m%d.txt

  This outputs the data as tab separated Centigrade readings to files named
temperature-20161011.txt, temperature-20161011.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.digitemp.com/users.shtml

    Brian C. Lane
    [email protected]
    http://www.brianlane.com


Problems with Linux Kernel ds2490 driver
----------------------------------------

The Linux kernel has included a ds2490 driver module for quite some time now.
This module will conflict with `digitemp_DS2490` use unless you unload it or
block it from being loaded.  In the past I've recommended using `modprobe -r
ds2490` to remove the module, but this no longer works correctly on some
systems (I've tested it on Fedora 32 with kernel 5.10.22).  It locks up the
`modprobe -r ds2490` process and you need to reboot to clear it.

The preferred way is to create a module blacklist file in
`/etc/modprobe.d/ds2490-blacklist.conf` with the contents being:

```
# ds2490 driver interferes with digitemp_DS2490 operation
blacklist ds2490
```

and then reboot. You can also test this by adding `modprobe.blacklist=ds2490` to
the kernel cmdline at boot time.