Thermachron(3)

1DS1921-Thermochron(3)        One-Wire File System        DS1921-Thermochron(3)
2
3
4

NAME

6       DS1921 - Thermochron temperature logging iButton.
7

SYNOPSIS

9       Temperature logging iButton.
10
11       21 [.]XXXXXXXXXXXX[XX][/[
12       about/[measuring| resolution| samples| templow| temphigh| version] |
13       clock/[date| running| udate] |
14       histotgram/[counts[0-62|ALL]| gap| temperature[counts[0-62|ALL]] |
15       log[date[0-2047|ALL]|         elements|        temperature[0-2047|ALL]|
16       udate[0-2047|ALL]] |
17       memory |
18       mission/[date| delay| easystart| frequency| rollover| running| samples|
19       sampling| udate] |
20       overtemp/[date[0-11|ALL]|   elements|  end[0-11|ALL]|  count[0-11|ALL]|
21       temperature[0-11|ALL]| udate[0-11|ALL]] |
22       pages/page.[0-15|ALL] |
23       temperature |
24       undertemp/[date[0-11|ALL]|   elements|end[0-11|ALL]|   count[0-11|ALL]|
25       temperature[0-11|ALL]| udate[0-11|ALL]] | address | crc8 | id | locator
26       | r_address | r_id | r_locator | type ]]
27

FAMILY CODE

29       21
30

SPECIAL PROPERTIES

32   about/measuring
33       read-only, yes-no
34       Is this DS1921 currently measuring a temperature?
35
36   about/resolution
37       read-only, floating point
38       What is the resolution of the temperature measurments (in  the  current
39       temperature scale).
40
41   about/samples
42       read-only, unsigned integer
43       How many total temperature measurements has this DS1921 performed?
44
45   about/temphigh
46       read-only, floating point
47       Highest temperature this DS1921 can measure (in the current temperature
48       scale).
49
50   about/templow
51       read-only, floating point
52       Lowest temperature this DS1921 can measure (in the current  temperature
53       scale).
54
55   about/version
56       read-only, ascii
57       Specific version of this DS1921.
58
59   clock/date
60       read-write, ascii
61       26  character  date  representation of the internal time stored in this
62       DS1921.  Increments once per second while clock/running
63       Setting date to a null string will put the current system time.
64       Accepted date formats are:
65         Sat[urday] March 12 12:23:59 2001
66         Apr[il] 4 9:34:56 2002
67         3/23/04 23:34:57
68         current locale setting (your system's format)
69
70   clock/running
71       read-write, yes-no
72       Whether the internal clock is running. This can be explicitly set,  and
73       is  automatically  started  by  setting clock/date or clock/udate or by
74       starting a mission with mission/easystart or mission/frequency
75
76       The main reason to stop the clock is to conserve the internal  battery.
77       The  clock  cannot be stopped during a mission, and the clock is essen‐
78       tial for a mission.
79
80   clock/udate
81       read-write, unsigned integer
82       A numeric representation of clock/date
83       The number of seconds in UNIX time (since Jan 1, 1970).
84
85   histogram/counts.0 ... histogram/counts.62 histogram/counts.ALL
86       read-only, unsigned integer
87       The number of samples in the current  mission  whose  temperature  fell
88       within the histogram/temperature to histogram/temperature+histogram/gap
89       range.
90
91   histogram/elements
92       read-only, unsigned integer
93       The number of bins in the histogram. Always 63.
94
95   histogram/gap
96       read-only, floating point
97       The size of the histogram bin. Depends on  the  Thermochron  version  (
98       about/version ) and is usually 4 times about/resolution
99
100       Given in the current temperatature scale.
101
102   histogram/temperature.0   ...  histogram/temperature.62  histogram/tempera‐
103       ture.ALL
104       read-only, floating point
105       Lower limit of the temperature range for  the  corresponding  histogram
106       bin. In the current temperature scale.
107
108   log/date.0 ... log/date.2047 log/date.ALL
109       read-only, ascii
110       Date that the corresponding log/temperature was taken, in ascii format.
111       (See clock/date for more on the format).  The number of  valid  entries
112       is actually log/elements since the log may not be full.
113
114       mission/samples  gives the total number of samples that have been taken
115       but there is only room in the log for 2048 entries.  Once  the  log  is
116       full, mission/rollover determines the Thermochron's behavior.
117
118       If  mission/rollover is false(0), the log will hold the first 2048 sam‐
119       ples and log/date.0 will always be the same as mission/date
120
121       If mission/rollover is true (1) then the log will hold  the  last  2048
122       samples and the entries will be shifted down with each new sample.
123
124       Note  the OWFS code "untwists" the rollover behavior. The data will al‐
125       ways be a linear array of earliest to latest.
126
127       ALL is the all data elements comma separated.
128
129   log/elements
130       read-only, unsigned integer
131       Number of valid entries in the log.  OWFS offers the full  2048  values
132       in  the  log memory, but not that many samples may yet have been taken.
133       log/elements will range from 0 to 2048 and always be less than or equal
134       to mission/samples
135
136   log/temperature.0 ... log/temperature.2047 log/temperature.ALL
137       read-write, floating point
138       The temperature readings (in the current temperature scale) that corre‐
139       spond to the log/date sample. See log/date for details on the  indexing
140       scheme and rollover behavior.
141
142   log/udate.0 ... log/udate.2047 log/udate.ALL
143       read-write, unsigned integer
144       A numeric representation of log/date
145       The number of seconds in UNIX time (since Jan 1, 1970).
146
147   memory
148       read-write, binary
149       User  available  storage  space.  512 bytes. Can also be accessed as 16
150       pages of 32 bytes with the pages/page.x properties.
151
152   overtemp/count.0 ... overtemp/count.11 overtemp/count.ALL
153   undertemp/count.0 ... undertemp/count.11 undertemp/count.ALL
154       read-only, unsigned integer
155       Number of sampling periods that the Thermochron  stayed  out  of  range
156       during  a  mission.  Each  sampling period is mission/frequency minutes
157       long.
158
159   overtemp/end.0 ... overtemp/end.11 overtemp/end.ALL
160   undertemp/end.0 ... undertemp/end.11 undertemp/end.ALL
161       read-only, ascii
162       End of time that the Thermochron went out of range during  the  current
163       mission. See clock/date for format.
164
165       Each  period  can  be  up  to  255 samples in length, and span the time
166       overtemp/date to overtemp/end ( or undertemp/date to undertemp/end ).
167
168   overtemp/date.0 ... overtemp/date.11 overtemp/date.ALL
169   undertemp/date.0 ... undertemp/date.11 undertemp/date.ALL
170       read-only, ascii
171       Time that the Thermochron went out of range during the current mission.
172       See clock/date for format.
173
174   overtemp/elements
175   undertemp/elements
176       read-only, unsigned integer
177       Number of entries (0 to 12) in the overtemp or undertemp array.
178
179   overtemp/temperature
180   undertemp/temperature
181       read-write, floating point
182       Temperature limit to trigger alarm and error log.  overtemp/temperature
183       gives upper limit and undertemp/temperature gives lower limit.
184       In current temperature scale.
185
186   overtemp/udate.0 ... overtemp/udate.11 overtemp/udate.ALL
187   undertemp/udate.0 ... undertemp/udate.11 undertemp/udate.ALL
188       read-only, unsigned integer
189       A numeric representation of overtemp/date or undertemp/date
190       The number of seconds in UNIX time (since Jan 1, 1970).
191
192   pages/page.0 ... pages/page.15 pages/page.ALL
193       read-write, binary
194       Memory is split into 16 pages of 32 bytes each. User available. The log
195       memory,  register  banks  and histogram data area are all separate from
196       this memory area.
197       ALL is an aggregate of the pages. Each page is accessed sequentially.
198
199   temperature
200       read-only, floating point
201       Last temperature explicitly requested. Only available when the  mission
202       is not in progress. Value returned in in the current temperature scale.
203

STANDARD PROPERTIES

205   address
206   r_address
207       read-only, ascii
208       The  entire  64-bit  unique  ID. Given as upper case hexadecimal digits
209       (0-9A-F).
210       address starts with the family code
211       r address is the address in reverse order, which is often used in other
212       applications and labeling.
213
214   crc8
215       read-only, ascii
216       The  8-bit error correction portion. Uses cyclic redundancy check. Com‐
217       puted from the preceding 56 bits of the unique ID number. Given as  up‐
218       per case hexadecimal digits (0-9A-F).
219
220   family
221       read-only, ascii
222       The  8-bit  family  code. Unique to each type of device. Given as upper
223       case hexadecimal digits (0-9A-F).
224
225   id
226   r_id
227       read-only, ascii
228       The 48-bit middle portion of the unique ID number. Does not include the
229       family code or CRC. Given as upper case hexadecimal digits (0-9A-F).
230       r  id is the id in reverse order, which is often used in other applica‐
231       tions and labeling.
232
233   locator
234   r_locator
235       read-only, ascii
236       Uses an extension of the 1-wire design from  iButtonLink  company  that
237       associated  1-wire  physical  connections with a unique 1-wire code. If
238       the connection is behind a Link Locator the locator will show a  unique
239       8-byte number (16 character hexadecimal) starting with family code FE.
240       If  no  Link  Locator is between the device and the master, the locator
241       field will be all FF.
242       r locator is the locator in reverse order.
243
244   present (DEPRECATED)
245       read-only, yes-no
246       Is the device currently present on the 1-wire bus?
247
248   type
249       read-only, ascii
250       Part name assigned by Dallas Semi. E.g.  DS2401  Alternative  packaging
251       (iButton vs chip) will not be distiguished.
252

ALARMS

254       None.
255

DESCRIPTION

257   1-Wire
258       1-wire is a wiring protocol and series of devices designed and manufac‐
259       tured by Dallas Semiconductor, Inc. The bus is  a  low-power  low-speed
260       low-connector scheme where the data line can also provide power.
261
262       Each  device  is  uniquely and unalterably numbered during manufacture.
263       There are a wide variety of devices, including memory, sensors  (humid‐
264       ity, temperature, voltage, contact, current), switches, timers and data
265       loggers. More complex devices (like thermocouple sensors) can be  built
266       with  these  basic devices. There are also 1-wire devices that have en‐
267       cryption included.
268
269       The 1-wire scheme uses a single bus master and multiple slaves  on  the
270       same  wire.  The bus master initiates all communication. The slaves can
271       be individually discovered and addressed using their unique ID.
272
273       Bus masters come in a variety of configurations including serial,  par‐
274       allel, i2c, network or USB adapters.
275
276   OWFS design
277       OWFS  is  a  suite of programs that designed to make the 1-wire bus and
278       its devices easily accessible. The underlying principle is to create  a
279       virtual filesystem, with the unique ID being the directory, and the in‐
280       dividual properties of the device are represented as simple files  that
281       can be read and written.
282
283       Details  of  the  individual slave or master design are hidden behind a
284       consistent interface. The goal is to provide an easy set of tools for a
285       software  designer  to create monitoring or control applications. There
286       are some performance enhancements in the implementation, including data
287       caching, parallel access to bus masters, and aggregation of device com‐
288       munication. Still the fundamental goal has been ease of use,  flexibil‐
289       ity and correctness rather than speed.
290
291   DS1921 Thermochron
292       The DS1921 (3) is an iButton device with many intriguing functions. Es‐
293       sentially it monitors temperature, giving both a log of readings, and a
294       histogram of temperature ranges. The specification is somewhat complex,
295       but OWFS hides many of the implementation details.
296
297       While on a mission the DS1921 (3) records  temperature  readings  in  a
298       2048-sample log and adds them to a 62-bin histogram.
299

ADDRESSING

301       All  1-wire  devices are factory assigned a unique 64-bit address. This
302       address is of the form:
303
304       Family Code
305              8 bits
306
307       Address
308              48 bits
309
310       CRC    8 bits
311
312       Addressing under OWFS is in hexadecimal, of form:
313
314              01.123456789ABC
315
316       where 01 is an example 8-bit family code, and 12345678ABC is an example
317       48 bit address.
318
319       The  dot  is  optional,  and the CRC code can included. If included, it
320       must be correct.
321

DATASHEET

323       http://pdfserv.maxim-ic.com/en/ds/DS2438.pdf
324       http://pdfserv.maxim-ic.com/en/an/humsensor.pdf
325

AVAILABILITY

388       http://www.owfs.org
389

AUTHOR

391       Paul Alfille (paul.alfille@gmail.com)
392
393
394
395OWFS Manpage                         2005                DS1921-Thermochron(3)