root/lm-sensors/branches/lm-sensors-2.10/doc/chips/ds1621

Revision 3007, 10.4 KB (checked in by khali, 10 years ago)

Backport the cleanups and corrections Rudolf Marek and I did when
porting the chips documentation to Linux 2.6.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1Kernel driver `ds1621.o'
2========================
3
4Status: Complete and tested; enhanced features experimental
5
6Supported chips:
7  * Dallas Semiconductor DS1621
8    Prefix: 'ds1621'
9    Addresses scanned: I2C 0x48 - 0x4f
10    Datasheet: Publicly available at the Dallas Semiconductor website
11               http://www.dalsemi.com/
12  * Dallas Semiconductor DS1625
13    Prefix: 'ds1621'
14    Addresses scanned: I2C 0x48 - 0x4f
15    Datasheet: Publicly available at the Dallas Semiconductor website
16               http://www.dalsemi.com/
17
18Author: Christian W. Zuckschwerdt <zany@triq.net>
19valueable contributions by Jan M. Sendler <sendler@sendler.de>
20
21
22Module Parameters
23-----------------
24
25* force: short array (min = 1, max = 48)
26  List of adapter,address pairs to boldly assume to be present
27* force_ds1621: short array (min = 1, max = 48)
28  List of adapter,address pairs which are unquestionably assumed to
29  contain a `ds1621' chip
30* ignore: short array (min = 1, max = 48)
31  List of adapter,address pairs not to scan
32* ignore_range: short array (min = 1, max = 48)
33  List of adapter,start-addr,end-addr triples not to scan
34* probe: short array (min = 1, max = 48)
35  List of adapter,address pairs to scan additionally
36* probe_range: short array (min = 1, max = 48)
37  List of adapter,start-addr,end-addr triples to scan additionally
38
39
40Description
41-----------
42
43The DS1621 is a (one instance) digital thermometer and thermostat. It
44has both high and low temperature limits which can be user defined
45(i. e. programmed into non-volatile on-chip registers).
46Temperature range is -55 degree Celsius to +125 in 0.5 increments. You
47may convert this into a Fahrenheit range of -67 to +257 degrees with
480.9 steps. Unfortunally though, you will need a hash table or even a
49conversion routine for that.
50
51Temperature readings are internally converted into a 9bit value to be
52read straight via the i2c-bus, but higher resolutions may be obtained
53with little effort via 'precise_temp' access or using a simple algorithm.
54
55As for the thermostat, behavior can also be programmed using the
56polarity toggle.
57On the one hand ("heater"), the thermostat output of the chip, Tout,
58will trigger when the low limit temperature is met or underrun and
59stays high until the high limit is met or exceeded. On the other hand
60("cooler"), vice versa.
61That way "heater" equals "active low", whereas "conditioner" equals
62"active high". Please note that the DS1621 data sheet is somewhat
63misleading in this point since setting the polarity bit does not
64simply invert Tout.
65
66
67A second thing is that, during extensive testing, Tout showed a
68tolerance of up to +/- 0.5 degrees even when compared against precise
69temperature readings.
70Be sure to have a high vs. low temperature limit gap of al least 1.0
71degree Celsius to avoid Tout "bouncing", though!
72
73As for alarms, you can read the alarm status of the DS1621 via the
74'alarms' proc file interface. The result consits mainly of bit 6 and 5
75of the configuration register of the chip; bit 6 (0x40 or 64) is the
76high alarm bit and bit 5 (0x20 or 32) the low one. These bits are set
77when the high or low limits are met or exceeded and are reset by the
78module as soon as the respective temperature ranges are left.
79
80The alarm registers are in no way suitable to find out about the
81actual status of Tout. They will only tell you about its history,
82whether or not any of the limits have ever been met or exceeded since
83last power-up or reset. Be aware: When testing, it showed that the
84status of Tout can change with neither of the alarms set.
85
86Temperature conversion of the DS1621 takes up to 1000ms; internal
87access to non-volatile registers may last for 10ms or below.
88
89This driver also detects DS1625. As this chip is discontinued, you
90should use a DS1621 instead. Detected 1625s also get the
91"ds1621"-prefix, but the accuracy registers are not supported.
92The latest modification of this driver was not checked against 1625s,
93though, but should work well with them.
94
95Default values written into the DS1621 upon detection are:
96Temperature limits: High 60.0; low 0.0 degree Celsius;
97Continuous mode (not enabled), Tout active high, alarms reset.
98
99
100Accessing DS1621 via /proc interface (part I)
101---------------------------------------------
102
103On detection (i.e. insmod, modprobe et al.), directories are being
104created for each detected DS1621:
105
106/proc/sys/dev/sensors/ds1621-<0>-<1>/
107where <0> is the bus the chip was detected on (e. g. i2c-0)
108and <1> the chip address ([48..4f]): ./ds1621-i2c-0-48/
109
110Inside these directories, there are five files each:
111alarms, continuous, enable, polarity and temp.
112
113The temp, alarms and enable are LM75-like for compatibility reasons:
114
115The temp file is rw. Reading gives TEMP_HIGH:TEMP_HYST:TEMP, where
116TEMP_HIGH is the upper limit temp, TEMP_HYST is the hysteresis (lower
117limit) temp and TEMP is the actual temperature. (For things like
118ONE_SHOT, see below.) - Writing takes two results (read: input
119values): TEMP_HIGH:TEMP_HYST. This provides an easy way to set limits.
120
121The alarms file is ro. Basically, it is 0x40 ("64") for the high alarm
122bit set plus 0x20 ("32") for the low one. Since alarms are being reset
123by the module when the limit conditions are no longer met, you should
124first read the alarms before you do anything else (such as reading the
125temperature), or the information may be lost.
126
127The polarity file is rw. Reading gives "0" for active high, which
128describes a need for cooling corresponds to Tout status. "1" means
129active low, so you can connect a powerful heater directly to Tout
130(DON'T TRY!). - Writing accepts "0" and "1" accordingly. Again, note
131that the statements on page 5 of the DS1621 data sheet are misleading;
132change the orientation of the vertical arrows in the sketch there
133instead.
134
135To understand the use of the other things, it is useful to have a
136brief look at the internal DS1621 procedures:
137
138
139High Accuracy Temperature Reading
140---------------------------------
141
142As said before, the temperature issued via the 9bit i2c-bus data is
143somewhat arbitrary. Internally, the temperature conversion is of a
144different kind that is explained (not so...) well in the DS1621 data
145sheet. To cut the long story short: Inside the DS1621 there are two
146oscillators, both of them biassed by a temperature coefficient.
147
148Higher accuracy of the temperature reading can be achieved using the
149internal projection, which means taking account of REG_COUNT and
150REG_SLOPE (the driver manages them):
151
152Taken from Dallas Semiconductors App Note 068: 'Increasing Temperature
153Resolution on the DS1620' and App Note 105: 'High Resolution
154Temperature Measurement with Dallas Direct-to-Digital Temperature
155Sensors'
156
157- Read the 9bit temperature and strip the LSB (Truncate the .5 degs)
158- The resulting value is TEMP_READ.
159- Then, read REG_COUNT.
160- And then, REG_SLOPE.
161
162      TEMP = TEMP_READ - 0.25 + ((REG_SLOPE - REG_COUNT) / REG_SLOPE)
163
164Note that this is what the DONE bit in the DS1621 configuration
165register is good for: Internally, one temperature conversion takes up
166to 1000ms. Before that conversion is complete you will not be able to
167read valid things out of REG_COUNT and REG_SLOPE. The DONE bit, as you
168may have guessed by now, tells you whether the conversion is complete
169("done", in plain english) and thus, whether the values you read are
170good or not.
171
172The DS1621 has two modes of operation: "Continuous" conversion, which
173can be understood as the default stand-alone mode where the chip gets
174the temperature and controls external devices via its Tout pin or
175tells other i2c's about it if they care. The other mode is called
176"1SHOT", that means that it only figures out about the temperature
177when it is explicitly told to do so; this can be seen as power saving
178mode.
179
180Now if you want to read REG_COUNT and REG_SLOPE, you have to either
181stop the continuous conversions until the contents of these registers
182are valid, or, in 1SHOT mode, you have to have one conversion made.
183
184
185
186Accessing DS1621 via /proc interface (part II and end)
187------------------------------------------------------
188
189The continuous file is rw. Reading gives "1" when the chip is in
190continuous mode and "0" for 1SHOT. - Writing accepts "1" to put it
191into continuous mode or "0" for 1SHOT.
192
193The enable file is rw. Reading gives "1" if in continuous mode the
194DS1621 is "running" or if in 1SHOT mode it is "shooting". In fact, the
195value returned here is the negated DONE bit, just like a "BUSY"
196flag. This means, that the "1" tells you that the values in REG_COUNT
197and REG_SLOPE are not valid. "0", on the other hand, means that the
198continuous conversion had been stopped long enough to provide valid
199readings and that one shot has successfully been fi- red,
200respectively. - Writing accepts "1" to start continuous conversion or
201to pull the trigger in 1SHOT mode, and "0" stops continuous conversion
202to allow for valid readings. Writing "0" in 1SHOT doesn't make much
203sense since you cannot catch a bullet, can you? No, the thing is that
204DS1621 does only do one conversion then anyway, and after that,
205there's nothing to stop.
206
207Last, but best try writing "0" to the "continuous" file and after that
208"1" to the "enable" file. This gives you the precise temperature with
209two digits after the radix (decimal point).
210The precise results are only updated if the DONE bit was set, thus you
211have to stop continuous conversion early enough prior to reading,
212i. e. 1000ms. And, on the other hand, you shouldn't forget to fire off
2131SHOT in order to get the actual temperature rather than that of the
214day before yesterday. So read enable before any of these.
215
216
217Chip Features
218-------------
219
220Chip `ds1621'
221          LABEL     LABEL CLASS   COMPUTE CLASS ACCESS MAGNITUDE
222           temp            NONE            NONE     R      1
223      temp_hyst            temp            temp     RW     1
224      temp_over            temp            temp     RW     1
225         alarms            NONE            NONE     R      0
226         enable            NONE            NONE     RW     0
227     continuous            NONE            NONE     RW     0
228       polarity            NONE            NONE     RW     0
229
230          LABEL                   FEATURE SYMBOL     SYSCTL FILE:OFFSET
231           temp              SENSORS_DS1621_TEMP            temp:3
232      temp_hyst         SENSORS_DS1621_TEMP_HYST            temp:2
233      temp_over         SENSORS_DS1621_TEMP_OVER            temp:1
234         alarms            SENSORS_DS1621_ALARMS          alarms:1
235         enable            SENSORS_DS1621_ENABLE          enable:1
236     continuous        SENSORS_DS1621_CONTINUOUS      continuous:1
237       polarity          SENSORS_DS1621_POLARITY        polarity:1
Note: See TracBrowser for help on using the browser.