Documentation/hwmon/ds1621.rst

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