/
README
467 lines (350 loc) · 19.4 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
----------------------------------------------------------------------------
DigiTemp v3.7.1 for Linux (c)1996-2016 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.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. 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 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.
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
bcl@brianlane.com
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 initialize 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 General
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.