HTTPS clone URL
Subversion checkout URL
1-wire temperature sensor cmdline interface
C Perl Python Other
---------------------------------------------------------------------------- DigiTemp v3.6.0 for Linux (c)1996-2008 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@example.com 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 4 requirements: 1. Permission to access the serial port you will be using. 2. Permission to write to /var/lock if you are using Linux 3. A 1-wire serial port adapter 4. 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 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 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. The same goes for permission on /var/lock/ 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 permisson to access the serial port and under Linux the /var/lock directory. 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). To allow access to the lock directory add the same user to the lock group. Alternativly you can set-group-id the binary to the lock group so that anyone running it will only need to be added to the serial port group, not the lock group. chmod g+s digitemp chown .lock digitemp 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 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. 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. 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 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. 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 firstname.lastname@example.org http://www.brianlane.com Release notes ------------- Version 3.6.0 adds ... Version 3.5.0 adds DS1923 Hygrochron support, fixes some small bugs in the userial driver. A lockdev bug was fixed (wasn't unlocking when done), a crash in free_couplers() was fixed, better error reporting when trying to access serial ports that don't exist, compiled for Windows with cygiwn. DS2490/9490 support still doesn't work well for me, although others have had success with it. Version 3.4.0 fixes temperature output using -o2 and -o3 log formats with the DS2438 sensor. Version 3.3.2 fixes the broken DS9097 support that I hosed in v3.3.1 and adds a performance patch to DS9097 from Erik Rigtorp that should speed up passive adapter operations. Version 3.3.1 works with the DS9490R USB adapter using the DS2490 USB to 1-wire adapter chip. It needs to be run as root, and your version of libusb may need to be patched using the patch in the ./contrib directory Version 3.3.0 adds support for the DS2490 USB adapter, DS2438 battery monitor and AAG TAI-8540 humidity sensor module. Additional format string specifiers have been added to handle the humidity reading. See the Initialization section below. The binary generated when building from source is now digitemp_DS9097, digitemp_DS9097U, or digitemp_DS2490 depending on which build you do. You can then make a symlink to 'digitemp' for whichever adapter you need to use. I now recommend use of the iButtonLink from www.ibuttonlink.com, it is 100% compatible with the DS9097U, but has been engineered to work with longer networks more reliably. 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 adds 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.x.x 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.