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 Authors:
  26         Christian W. Zuckschwerdt <zany@triq.net>
  27         valuable contributions by Jan M. Sendler <sendler@sendler.de>
  28         ported to 2.6 by Aurelien Jarno <aurelien@aurel32.net>
  29         with the help of Jean Delvare <khali@linux-fr.org>
  30
  31 Module Parameters
  32 ------------------
  33
  34 * polarity int
  35   Output's polarity: 0 = active high, 1 = active low
  36
  37 Description
  38 -----------
  39
  40 The DS1621 is a (one instance) digital thermometer and thermostat. It has
  41 both high and low temperature limits which can be user defined (i.e.
  42 programmed into non-volatile on-chip registers). Temperature range is -55
  43 degree Celsius to +125 in 0.5 increments. You may convert this into a
  44 Fahrenheit range of -67 to +257 degrees with 0.9 steps. If polarity
  45 parameter is not provided, original value is used.
  46
  47 As for the thermostat, behavior can also be programmed using the polarity
  48 toggle. On the one hand ("heater"), the thermostat output of the chip,
  49 Tout, will trigger when the low limit temperature is met or underrun and
  50 stays high until the high limit is met or exceeded. On the other hand
  51 ("cooler"), vice versa. That way "heater" equals "active low", whereas
  52 "conditioner" equals "active high". Please note that the DS1621 data sheet
  53 is somewhat misleading in this point since setting the polarity bit does
  54 not simply invert Tout.
  55
  56 A second thing is that, during extensive testing, Tout showed a tolerance
  57 of up to +/- 0.5 degrees even when compared against precise temperature
  58 readings. Be sure to have a high vs. low temperature limit gap of al least
  59 1.0 degree Celsius to avoid Tout "bouncing", though!
  60
  61 The alarm bits are set when the high or low limits are met or exceeded and
  62 are reset by the module as soon as the respective temperature ranges are
  63 left.
  64
  65 The alarm registers are in no way suitable to find out about the actual
  66 status of Tout. They will only tell you about its history, whether or not
  67 any of the limits have ever been met or exceeded since last power-up or
  68 reset. Be aware: When testing, it showed that the status of Tout can change
  69 with neither of the alarms set.
  70
  71 Temperature conversion of the DS1621 takes up to 1000ms; internal access to
  72 non-volatile registers may last for 10ms or below.
  73
  74 The DS1625 is pin compatible and functionally equivalent with the DS1621,
  75 but the DS1621 is meant to replace it. The DS1631 and DS1721 are also
  76 pin compatible with the DS1621, but provide multi-resolution support.
  77
  78 Since there is no version or vendor identification register, there is
  79 no unique identification for these devices. Therefore, explicit device
  80 instantiation is required for correct device identification and functionality.
  81
  82 And, for correct identification and operation, each device must be
  83 explicitly instantiated, one device per address, in this address
  84 range: 0x48..0x4f.
  85
  86 The DS1721 is pin compatible with the DS1621, has an accuracy of +/- 1.0
  87 degree Celsius over a -10 to +85 degree range, a minimum/maximum alarm
  88 default setting of 75 and 80 degrees respectively, and a maximum conversion
  89 time of 750ms.
  90
  91 In addition, the DS1721 supports four resolution settings from 9 to 12 bits
  92 (defined in degrees C per LSB: 0.5, 0.25, 0.125, and 0.0625, respectifully),
  93 that are set at device power on to the highest resolution: 12-bits.
  94
  95 One additional note about the ds1721 is that although the data sheet says
  96 the temperature flags (THF and TLF) are used internally, these flags do
  97 get set and cleared as the actual temperature crosses the min or max settings.
  98
  99 The DS1631 is also pin compatible with the DS1621 and feature compatible with
 100 the DS1721, however the DS1631 accuracy is +/- 0.5 degree Celsius over the
 101 same range.
 102
 103 Changing the DS1631/1721 resolution mode affects the conversion time and can be
 104 done from userspace, via the device 'update_interval' sysfs attribute. This
 105 attribute will normalize range of input values to the device maximum resolution
 106 values defined in the datasheet as such:
 107
 108 Resolution    Conversion Time    Input Range
 109  (C/LSB)       (msec)             (msec)
 110 --------------------------------------------
 111 0.5             93.75              0....94
 112 0.25            187.5              95...187
 113 0.125           375                188..375
 114 0.0625          750                376..infinity
 115 --------------------------------------
 116
 117 The following examples show how the 'update_interval' attribute can be
 118 used to change the conversion time:
 119
 120 $ cat update_interval
 121 750
 122 $ cat temp1_input
 123 22062
 124 $
 125 $ echo 300 > update_interval
 126 $ cat update_interval
 127 375
 128 $ cat temp1_input
 129 22125
 130 $
 131 $ echo 150 > update_interval
 132 $ cat update_interval
 133 188
 134 $ cat temp1_input
 135 22250
 136 $
 137 $ echo 1 > update_interval
 138 $ cat update_interval
 139 94
 140 $ cat temp1_input
 141 22000
 142 $
 143 $ echo 1000 > update_interval
 144 $ cat update_interval
 145 750
 146 $ cat temp1_input
 147 22062
 148 $
 149
 150 As shown, the ds1621 driver automatically adjusts the 'update_interval'
 151 user input, via a step function. Reading back the 'update_interval' value
 152 after a write operation provides the conversion time used by the device.
 153
 154 Mathematically, the resolution can be derived from the conversion time
 155 via the following function:
 156
 157    g(x) = 0.5 * [minimum_conversion_time/x]
 158
 159 where:
 160  -> 'x' = the output from 'update_interval'
 161  -> 'g(x)' = the resolution in degrees C per LSB.
 162  -> 93.75ms = minimum conversion time