0001 Kernel driver ds1621
0002 ====================
0003
0004 Supported chips:
0005
0006 * Dallas Semiconductor / Maxim Integrated DS1621
0007
0008 Prefix: 'ds1621'
0009
0010 Addresses scanned: none
0011
0012 Datasheet: Publicly available from www.maximintegrated.com
0013
0014 * Dallas Semiconductor DS1625
0015
0016 Prefix: 'ds1625'
0017
0018 Addresses scanned: none
0019
0020 Datasheet: Publicly available from www.datasheetarchive.com
0021
0022 * Maxim Integrated DS1631
0023
0024 Prefix: 'ds1631'
0025
0026 Addresses scanned: none
0027
0028 Datasheet: Publicly available from www.maximintegrated.com
0029
0030 * Maxim Integrated DS1721
0031
0032 Prefix: 'ds1721'
0033
0034 Addresses scanned: none
0035
0036 Datasheet: Publicly available from www.maximintegrated.com
0037
0038 * Maxim Integrated DS1731
0039
0040 Prefix: 'ds1731'
0041
0042 Addresses scanned: none
0043
0044 Datasheet: Publicly available from www.maximintegrated.com
0045
0046 Authors:
0047 - Christian W. Zuckschwerdt <zany@triq.net>
0048 - valuable contributions by Jan M. Sendler <sendler@sendler.de>
0049 - ported to 2.6 by Aurelien Jarno <aurelien@aurel32.net>
0050 with the help of Jean Delvare <jdelvare@suse.de>
0051
0052 Module Parameters
0053 ------------------
0054
0055 * polarity int
0056 Output's polarity:
0057
0058 * 0 = active high,
0059 * 1 = active low
0060
0061 Description
0062 -----------
0063
0064 The DS1621 is a (one instance) digital thermometer and thermostat. It has
0065 both high and low temperature limits which can be user defined (i.e.
0066 programmed into non-volatile on-chip registers). Temperature range is -55
0067 degree Celsius to +125 in 0.5 increments. You may convert this into a
0068 Fahrenheit range of -67 to +257 degrees with 0.9 steps. If polarity
0069 parameter is not provided, original value is used.
0070
0071 As for the thermostat, behavior can also be programmed using the polarity
0072 toggle. On the one hand ("heater"), the thermostat output of the chip,
0073 Tout, will trigger when the low limit temperature is met or underrun and
0074 stays high until the high limit is met or exceeded. On the other hand
0075 ("cooler"), vice versa. That way "heater" equals "active low", whereas
0076 "conditioner" equals "active high". Please note that the DS1621 data sheet
0077 is somewhat misleading in this point since setting the polarity bit does
0078 not simply invert Tout.
0079
0080 A second thing is that, during extensive testing, Tout showed a tolerance
0081 of up to +/- 0.5 degrees even when compared against precise temperature
0082 readings. Be sure to have a high vs. low temperature limit gap of al least
0083 1.0 degree Celsius to avoid Tout "bouncing", though!
0084
0085 The alarm bits are set when the high or low limits are met or exceeded and
0086 are reset by the module as soon as the respective temperature ranges are
0087 left.
0088
0089 The alarm registers are in no way suitable to find out about the actual
0090 status of Tout. They will only tell you about its history, whether or not
0091 any of the limits have ever been met or exceeded since last power-up or
0092 reset. Be aware: When testing, it showed that the status of Tout can change
0093 with neither of the alarms set.
0094
0095 Since there is no version or vendor identification register, there is
0096 no unique identification for these devices. Therefore, explicit device
0097 instantiation is required for correct device identification and functionality
0098 (one device per address in this address range: 0x48..0x4f).
0099
0100 The DS1625 is pin compatible and functionally equivalent with the DS1621,
0101 but the DS1621 is meant to replace it. The DS1631, DS1721, and DS1731 are
0102 also pin compatible with the DS1621 and provide multi-resolution support.
0103
0104 Additionally, the DS1721 data sheet says the temperature flags (THF and TLF)
0105 are used internally, however, these flags do get set and cleared as the actual
0106 temperature crosses the min or max settings (which by default are set to 75
0107 and 80 degrees respectively).
0108
0109 Temperature Conversion
0110 ----------------------
0111
0112 - DS1621 - 750ms (older devices may take up to 1000ms)
0113 - DS1625 - 500ms
0114 - DS1631 - 93ms..750ms for 9..12 bits resolution, respectively.
0115 - DS1721 - 93ms..750ms for 9..12 bits resolution, respectively.
0116 - DS1731 - 93ms..750ms for 9..12 bits resolution, respectively.
0117
0118 Note:
0119 On the DS1621, internal access to non-volatile registers may last for 10ms
0120 or less (unverified on the other devices).
0121
0122 Temperature Accuracy
0123 --------------------
0124
0125 - DS1621: +/- 0.5 degree Celsius (from 0 to +70 degrees)
0126 - DS1625: +/- 0.5 degree Celsius (from 0 to +70 degrees)
0127 - DS1631: +/- 0.5 degree Celsius (from 0 to +70 degrees)
0128 - DS1721: +/- 1.0 degree Celsius (from -10 to +85 degrees)
0129 - DS1731: +/- 1.0 degree Celsius (from -10 to +85 degrees)
0130
0131 .. Note::
0132
0133 Please refer to the device datasheets for accuracy at other temperatures.
0134
0135 Temperature Resolution:
0136 -----------------------
0137 As mentioned above, the DS1631, DS1721, and DS1731 provide multi-resolution
0138 support, which is achieved via the R0 and R1 config register bits, where:
0139
0140 R0..R1
0141 ------
0142
0143 == == ===============================
0144 R0 R1
0145 == == ===============================
0146 0 0 9 bits, 0.5 degrees Celsius
0147 1 0 10 bits, 0.25 degrees Celsius
0148 0 1 11 bits, 0.125 degrees Celsius
0149 1 1 12 bits, 0.0625 degrees Celsius
0150 == == ===============================
0151
0152 .. Note::
0153
0154 At initial device power-on, the default resolution is set to 12-bits.
0155
0156 The resolution mode for the DS1631, DS1721, or DS1731 can be changed from
0157 userspace, via the device 'update_interval' sysfs attribute. This attribute
0158 will normalize the range of input values to the device maximum resolution
0159 values defined in the datasheet as follows:
0160
0161 ============= ================== ===============
0162 Resolution Conversion Time Input Range
0163 (C/LSB) (msec) (msec)
0164 ============= ================== ===============
0165 0.5 93.75 0....94
0166 0.25 187.5 95...187
0167 0.125 375 188..375
0168 0.0625 750 376..infinity
0169 ============= ================== ===============
0170
0171 The following examples show how the 'update_interval' attribute can be
0172 used to change the conversion time::
0173
0174 $ cat update_interval
0175 750
0176 $ cat temp1_input
0177 22062
0178 $
0179 $ echo 300 > update_interval
0180 $ cat update_interval
0181 375
0182 $ cat temp1_input
0183 22125
0184 $
0185 $ echo 150 > update_interval
0186 $ cat update_interval
0187 188
0188 $ cat temp1_input
0189 22250
0190 $
0191 $ echo 1 > update_interval
0192 $ cat update_interval
0193 94
0194 $ cat temp1_input
0195 22000
0196 $
0197 $ echo 1000 > update_interval
0198 $ cat update_interval
0199 750
0200 $ cat temp1_input
0201 22062
0202 $
0203
0204 As shown, the ds1621 driver automatically adjusts the 'update_interval'
0205 user input, via a step function. Reading back the 'update_interval' value
0206 after a write operation provides the conversion time used by the device.
0207
0208 Mathematically, the resolution can be derived from the conversion time
0209 via the following function:
0210
0211 g(x) = 0.5 * [minimum_conversion_time/x]
0212
0213 where:
0214
0215 - 'x' = the output from 'update_interval'
0216 - 'g(x)' = the resolution in degrees C per LSB.
0217 - 93.75ms = minimum conversion time
