Documentation/hwmon/ds1621

   1 Kernel driver ds1621
   2 ====================
   3
   4 Supported 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
  30 Authors:
  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
  36 Module Parameters
  37 ------------------
  38
  39 * polarity int
  40   Output's polarity: 0 = active high, 1 = active low
  41
  42 Description
  43 -----------
  44
  45 The DS1621 is a (one instance) digital thermometer and thermostat. It has
  46 both high and low temperature limits which can be user defined (i.e.
  47 programmed into non-volatile on-chip registers). Temperature range is -55
  48 degree Celsius to +125 in 0.5 increments. You may convert this into a
  49 Fahrenheit range of -67 to +257 degrees with 0.9 steps. If polarity
  50 parameter is not provided, original value is used.
  51
  52 As for the thermostat, behavior can also be programmed using the polarity
  53 toggle. On the one hand ("heater"), the thermostat output of the chip,
  54 Tout, will trigger when the low limit temperature is met or underrun and
  55 stays 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
  58 is somewhat misleading in this point since setting the polarity bit does
  59 not simply invert Tout.
  60
  61 A second thing is that, during extensive testing, Tout showed a tolerance
  62 of up to +/- 0.5 degrees even when compared against precise temperature
  63 readings. Be sure to have a high vs. low temperature limit gap of al least
  64 1.0 degree Celsius to avoid Tout "bouncing", though!
  65
  66 The alarm bits are set when the high or low limits are met or exceeded and
  67 are reset by the module as soon as the respective temperature ranges are
  68 left.
  69
  70 The alarm registers are in no way suitable to find out about the actual
  71 status of Tout. They will only tell you about its history, whether or not
  72 any of the limits have ever been met or exceeded since last power-up or
  73 reset. Be aware: When testing, it showed that the status of Tout can change
  74 with neither of the alarms set.
  75
  76 Since there is no version or vendor identification register, there is
  77 no unique identification for these devices. Therefore, explicit device
  78 instantiation is required for correct device identification and functionality
  79 (one device per address in this address range: 0x48..0x4f).
  80
  81 The DS1625 is pin compatible and functionally equivalent with the DS1621,
  82 but the DS1621 is meant to replace it. The DS1631, DS1721, and DS1731 are
  83 also pin compatible with the DS1621 and provide multi-resolution support.
  84
  85 Additionally, the DS1721 data sheet says the temperature flags (THF and TLF)
  86 are used internally, however, these flags do get set and cleared as the actual
  87 temperature crosses the min or max settings (which by default are set to 75
  88 and 80 degrees respectively).
  89
  90 Temperature Conversion:
  91 -----------------------
  92 DS1621 - 750ms (older devices may take up to 1000ms)
  93 DS1625 - 500ms
  94 DS1631 - 93ms..750ms for 9..12 bits resolution, respectively.
  95 DS1721 - 93ms..750ms for 9..12 bits resolution, respectively.
  96 DS1731 - 93ms..750ms for 9..12 bits resolution, respectively.
  97
  98 Note:
  99 On the DS1621, internal access to non-volatile registers may last for 10ms
 100 or less (unverified on the other devices).
 101
 102 Temperature Accuracy:
 103 ---------------------
 104 DS1621: +/- 0.5 degree Celsius (from 0 to +70 degrees)
 105 DS1625: +/- 0.5 degree Celsius (from 0 to +70 degrees)
 106 DS1631: +/- 0.5 degree Celsius (from 0 to +70 degrees)
 107 DS1721: +/- 1.0 degree Celsius (from -10 to +85 degrees)
 108 DS1731: +/- 1.0 degree Celsius (from -10 to +85 degrees)
 109
 110 Note:
 111 Please refer to the device datasheets for accuracy at other temperatures.
 112
 113 Temperature Resolution:
 114 -----------------------
 115 As mentioned above, the DS1631, DS1721, and DS1731 provide multi-resolution
 116 support, which is achieved via the R0 and R1 config register bits, where:
 117
 118 R0..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
 125 Note:
 126 At initial device power-on, the default resolution is set to 12-bits.
 127
 128 The resolution mode for the DS1631, DS1721, or DS1731 can be changed from
 129 userspace, via the device 'update_interval' sysfs attribute. This attribute
 130 will normalize the range of input values to the device maximum resolution
 131 values defined in the datasheet as follows:
 132
 133 Resolution    Conversion Time    Input Range
 134  (C/LSB)       (msec)             (msec)
 135 ------------------------------------------------
 136 0.5             93.75              0....94
 137 0.25            187.5              95...187
 138 0.125           375                188..375
 139 0.0625          750                376..infinity
 140 ------------------------------------------------
 141
 142 The following examples show how the 'update_interval' attribute can be
 143 used to change the conversion time:
 144
 145 $ cat update_interval
 146 750
 147 $ cat temp1_input
 148 22062
 149 $
 150 $ echo 300 > update_interval
 151 $ cat update_interval
 152 375
 153 $ cat temp1_input
 154 22125
 155 $
 156 $ echo 150 > update_interval
 157 $ cat update_interval
 158 188
 159 $ cat temp1_input
 160 22250
 161 $
 162 $ echo 1 > update_interval
 163 $ cat update_interval
 164 94
 165 $ cat temp1_input
 166 22000
 167 $
 168 $ echo 1000 > update_interval
 169 $ cat update_interval
 170 750
 171 $ cat temp1_input
 172 22062
 173 $
 174
 175 As shown, the ds1621 driver automatically adjusts the 'update_interval'
 176 user input, via a step function. Reading back the 'update_interval' value
 177 after a write operation provides the conversion time used by the device.
 178
 179 Mathematically, the resolution can be derived from the conversion time
 180 via the following function:
 181
 182    g(x) = 0.5 * [minimum_conversion_time/x]
 183
 184 where:
 185  -> 'x' = the output from 'update_interval'
 186  -> 'g(x)' = the resolution in degrees C per LSB.
 187  -> 93.75ms = minimum conversion time