1Kernel driver ds1621
2====================
3
4Supported chips:
5  * Dallas Semiconductor / Maxim Integrated DS1621
6    Prefix: 'ds1621'
7    Addresses scanned: none
8    Datasheet: Publicly available from www.maximintegrated.com
9
10  * Dallas Semiconductor DS1625
11    Prefix: 'ds1625'
12    Addresses scanned: none
13    Datasheet: Publicly available from www.datasheetarchive.com
14
15  * Maxim Integrated DS1631
16    Prefix: 'ds1631'
17    Addresses scanned: none
18    Datasheet: Publicly available from www.maximintegrated.com
19
20  * Maxim Integrated DS1721
21    Prefix: 'ds1721'
22    Addresses scanned: none
23    Datasheet: Publicly available from www.maximintegrated.com
24
25  * Maxim Integrated DS1731
26    Prefix: 'ds1731'
27    Addresses scanned: none
28    Datasheet: Publicly available from www.maximintegrated.com
29
30Authors:
31        Christian W. Zuckschwerdt <zany@triq.net>
32        valuable contributions by Jan M. Sendler <sendler@sendler.de>
33        ported to 2.6 by Aurelien Jarno <aurelien@aurel32.net>
34        with the help of Jean Delvare <jdelvare@suse.de>
35
36Module Parameters
37------------------
38
39* polarity int
40  Output's polarity: 0 = active high, 1 = active low
41
42Description
43-----------
44
45The DS1621 is a (one instance) digital thermometer and thermostat. It has
46both high and low temperature limits which can be user defined (i.e.
47programmed into non-volatile on-chip registers). Temperature range is -55
48degree Celsius to +125 in 0.5 increments. You may convert this into a
49Fahrenheit range of -67 to +257 degrees with 0.9 steps. If polarity
50parameter is not provided, original value is used.
51
52As for the thermostat, behavior can also be programmed using the polarity
53toggle. On the one hand ("heater"), the thermostat output of the chip,
54Tout, will trigger when the low limit temperature is met or underrun and
55stays high until the high limit is met or exceeded. On the other hand
56("cooler"), vice versa. That way "heater" equals "active low", whereas
57"conditioner" equals "active high". Please note that the DS1621 data sheet
58is somewhat misleading in this point since setting the polarity bit does
59not simply invert Tout.
60
61A second thing is that, during extensive testing, Tout showed a tolerance
62of up to +/- 0.5 degrees even when compared against precise temperature
63readings. Be sure to have a high vs. low temperature limit gap of al least
641.0 degree Celsius to avoid Tout "bouncing", though!
65
66The alarm bits are set when the high or low limits are met or exceeded and
67are reset by the module as soon as the respective temperature ranges are
68left.
69
70The alarm registers are in no way suitable to find out about the actual
71status of Tout. They will only tell you about its history, whether or not
72any of the limits have ever been met or exceeded since last power-up or
73reset. Be aware: When testing, it showed that the status of Tout can change
74with neither of the alarms set.
75
76Since there is no version or vendor identification register, there is
77no unique identification for these devices. Therefore, explicit device
78instantiation is required for correct device identification and functionality
79(one device per address in this address range: 0x48..0x4f).
80
81The DS1625 is pin compatible and functionally equivalent with the DS1621,
82but the DS1621 is meant to replace it. The DS1631, DS1721, and DS1731 are
83also pin compatible with the DS1621 and provide multi-resolution support.
84
85Additionally, the DS1721 data sheet says the temperature flags (THF and TLF)
86are used internally, however, these flags do get set and cleared as the actual
87temperature crosses the min or max settings (which by default are set to 75
88and 80 degrees respectively).
89
90Temperature Conversion:
91-----------------------
92DS1621 - 750ms (older devices may take up to 1000ms)
93DS1625 - 500ms
94DS1631 - 93ms..750ms for 9..12 bits resolution, respectively.
95DS1721 - 93ms..750ms for 9..12 bits resolution, respectively.
96DS1731 - 93ms..750ms for 9..12 bits resolution, respectively.
97
98Note:
99On the DS1621, internal access to non-volatile registers may last for 10ms
100or less (unverified on the other devices).
101
102Temperature Accuracy:
103---------------------
104DS1621: +/- 0.5 degree Celsius (from 0 to +70 degrees)
105DS1625: +/- 0.5 degree Celsius (from 0 to +70 degrees)
106DS1631: +/- 0.5 degree Celsius (from 0 to +70 degrees)
107DS1721: +/- 1.0 degree Celsius (from -10 to +85 degrees)
108DS1731: +/- 1.0 degree Celsius (from -10 to +85 degrees)
109
110Note:
111Please refer to the device datasheets for accuracy at other temperatures.
112
113Temperature Resolution:
114-----------------------
115As mentioned above, the DS1631, DS1721, and DS1731 provide multi-resolution
116support, which is achieved via the R0 and R1 config register bits, where:
117
118R0..R1
119------
120 0  0 => 9 bits, 0.5 degrees Celcius
121 1  0 => 10 bits, 0.25 degrees Celcius
122 0  1 => 11 bits, 0.125 degrees Celcius
123 1  1 => 12 bits, 0.0625 degrees Celcius
124
125Note:
126At initial device power-on, the default resolution is set to 12-bits.
127
128The resolution mode for the DS1631, DS1721, or DS1731 can be changed from
129userspace, via the device 'update_interval' sysfs attribute. This attribute
130will normalize the range of input values to the device maximum resolution
131values defined in the datasheet as follows:
132
133Resolution    Conversion Time    Input Range
134 (C/LSB)       (msec)             (msec)
135------------------------------------------------
1360.5             93.75              0....94
1370.25            187.5              95...187
1380.125           375                188..375
1390.0625          750                376..infinity
140------------------------------------------------
141
142The following examples show how the 'update_interval' attribute can be
143used to change the conversion time:
144
145$ cat update_interval
146750
147$ cat temp1_input
14822062
149$
150$ echo 300 > update_interval
151$ cat update_interval
152375
153$ cat temp1_input
15422125
155$
156$ echo 150 > update_interval
157$ cat update_interval
158188
159$ cat temp1_input
16022250
161$
162$ echo 1 > update_interval
163$ cat update_interval
16494
165$ cat temp1_input
16622000
167$
168$ echo 1000 > update_interval
169$ cat update_interval
170750
171$ cat temp1_input
17222062
173$
174
175As shown, the ds1621 driver automatically adjusts the 'update_interval'
176user input, via a step function. Reading back the 'update_interval' value
177after a write operation provides the conversion time used by the device.
178
179Mathematically, the resolution can be derived from the conversion time
180via the following function:
181
182   g(x) = 0.5 * [minimum_conversion_time/x]
183
184where:
185 -> 'x' = the output from 'update_interval'
186 -> 'g(x)' = the resolution in degrees C per LSB.
187 -> 93.75ms = minimum conversion time
188