linux/Documentation/hwmon/ds1621
<<
>>
Prefs
   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