root/lm-sensors/branches/lm-sensors-2.10/doc/chips/ds1621

Kernel driver `ds1621.o'
========================

Status: Complete and tested; enhanced features experimental

Supported chips: 
  * Dallas Semiconductor DS1621
    Prefix: 'ds1621'
    Addresses scanned: I2C 0x48 - 0x4f
    Datasheet: Publicly available at the Dallas Semiconductor website
               http://www.dalsemi.com/
  * Dallas Semiconductor DS1625
    Prefix: 'ds1621'
    Addresses scanned: I2C 0x48 - 0x4f
    Datasheet: Publicly available at the Dallas Semiconductor website
               http://www.dalsemi.com/

Author: Christian W. Zuckschwerdt <zany@triq.net>
valueable contributions by Jan M. Sendler <sendler@sendler.de>


Module Parameters
-----------------

* force: short array (min = 1, max = 48)
  List of adapter,address pairs to boldly assume to be present
* force_ds1621: short array (min = 1, max = 48)
  List of adapter,address pairs which are unquestionably assumed to
  contain a `ds1621' chip
* ignore: short array (min = 1, max = 48)
  List of adapter,address pairs not to scan
* ignore_range: short array (min = 1, max = 48)
  List of adapter,start-addr,end-addr triples not to scan
* probe: short array (min = 1, max = 48)
  List of adapter,address pairs to scan additionally
* probe_range: short array (min = 1, max = 48)
  List of adapter,start-addr,end-addr triples to scan additionally


Description
-----------

The DS1621 is a (one instance) digital thermometer and thermostat. It
has both high and low temperature limits which can be user defined
(i. e. programmed into non-volatile on-chip registers).
Temperature range is -55 degree Celsius to +125 in 0.5 increments. You
may convert this into a Fahrenheit range of -67 to +257 degrees with
0.9 steps. Unfortunally though, you will need a hash table or even a
conversion routine for that.

Temperature readings are internally converted into a 9bit value to be
read straight via the i2c-bus, but higher resolutions may be obtained
with little effort via 'precise_temp' access or using a simple algorithm.

As for the thermostat, behavior can also be programmed using the
polarity toggle.
On the one hand ("heater"), the thermostat output of the chip, Tout,
will trigger when the low limit temperature is met or underrun and
stays high until the high limit is met or exceeded. On the other hand
("cooler"), vice versa.
That way "heater" equals "active low", whereas "conditioner" equals
"active high". Please note that the DS1621 data sheet is somewhat
misleading in this point since setting the polarity bit does not
simply invert Tout.


A second thing is that, during extensive testing, Tout showed a
tolerance of up to +/- 0.5 degrees even when compared against precise
temperature readings.
Be sure to have a high vs. low temperature limit gap of al least 1.0
degree Celsius to avoid Tout "bouncing", though!

As for alarms, you can read the alarm status of the DS1621 via the
'alarms' proc file interface. The result consits mainly of bit 6 and 5
of the configuration register of the chip; bit 6 (0x40 or 64) is the
high alarm bit and bit 5 (0x20 or 32) the low one. These bits are set
when the high or low limits are met or exceeded and are reset by the
module as soon as the respective temperature ranges are left.

The alarm registers are in no way suitable to find out about the
actual status of Tout. They will only tell you about its history,
whether or not any of the limits have ever been met or exceeded since
last power-up or reset. Be aware: When testing, it showed that the
status of Tout can change with neither of the alarms set.

Temperature conversion of the DS1621 takes up to 1000ms; internal
access to non-volatile registers may last for 10ms or below.

This driver also detects DS1625. As this chip is discontinued, you
should use a DS1621 instead. Detected 1625s also get the
"ds1621"-prefix, but the accuracy registers are not supported.
The latest modification of this driver was not checked against 1625s,
though, but should work well with them.

Default values written into the DS1621 upon detection are:
Temperature limits: High 60.0; low 0.0 degree Celsius;
Continuous mode (not enabled), Tout active high, alarms reset.


Accessing DS1621 via /proc interface (part I)
---------------------------------------------

On detection (i.e. insmod, modprobe et al.), directories are being
created for each detected DS1621:

/proc/sys/dev/sensors/ds1621-<0>-<1>/
where <0> is the bus the chip was detected on (e. g. i2c-0)
and <1> the chip address ([48..4f]): ./ds1621-i2c-0-48/

Inside these directories, there are five files each:
alarms, continuous, enable, polarity and temp.

The temp, alarms and enable are LM75-like for compatibility reasons:

The temp file is rw. Reading gives TEMP_HIGH:TEMP_HYST:TEMP, where
TEMP_HIGH is the upper limit temp, TEMP_HYST is the hysteresis (lower
limit) temp and TEMP is the actual temperature. (For things like
ONE_SHOT, see below.) - Writing takes two results (read: input
values): TEMP_HIGH:TEMP_HYST. This provides an easy way to set limits.

The alarms file is ro. Basically, it is 0x40 ("64") for the high alarm
bit set plus 0x20 ("32") for the low one. Since alarms are being reset
by the module when the limit conditions are no longer met, you should
first read the alarms before you do anything else (such as reading the
temperature), or the information may be lost.

The polarity file is rw. Reading gives "0" for active high, which
describes a need for cooling corresponds to Tout status. "1" means
active low, so you can connect a powerful heater directly to Tout
(DON'T TRY!). - Writing accepts "0" and "1" accordingly. Again, note
that the statements on page 5 of the DS1621 data sheet are misleading;
change the orientation of the vertical arrows in the sketch there
instead.

To understand the use of the other things, it is useful to have a
brief look at the internal DS1621 procedures:


High Accuracy Temperature Reading
---------------------------------

As said before, the temperature issued via the 9bit i2c-bus data is
somewhat arbitrary. Internally, the temperature conversion is of a
different kind that is explained (not so...) well in the DS1621 data
sheet. To cut the long story short: Inside the DS1621 there are two
oscillators, both of them biassed by a temperature coefficient.

Higher accuracy of the temperature reading can be achieved using the
internal projection, which means taking account of REG_COUNT and
REG_SLOPE (the driver manages them):

Taken from Dallas Semiconductors App Note 068: 'Increasing Temperature
Resolution on the DS1620' and App Note 105: 'High Resolution
Temperature Measurement with Dallas Direct-to-Digital Temperature
Sensors'

- Read the 9bit temperature and strip the LSB (Truncate the .5 degs)
- The resulting value is TEMP_READ.
- Then, read REG_COUNT.
- And then, REG_SLOPE.

      TEMP = TEMP_READ - 0.25 + ((REG_SLOPE - REG_COUNT) / REG_SLOPE)

Note that this is what the DONE bit in the DS1621 configuration
register is good for: Internally, one temperature conversion takes up
to 1000ms. Before that conversion is complete you will not be able to
read valid things out of REG_COUNT and REG_SLOPE. The DONE bit, as you
may have guessed by now, tells you whether the conversion is complete
("done", in plain english) and thus, whether the values you read are
good or not.

The DS1621 has two modes of operation: "Continuous" conversion, which
can be understood as the default stand-alone mode where the chip gets
the temperature and controls external devices via its Tout pin or
tells other i2c's about it if they care. The other mode is called
"1SHOT", that means that it only figures out about the temperature
when it is explicitly told to do so; this can be seen as power saving
mode.

Now if you want to read REG_COUNT and REG_SLOPE, you have to either
stop the continuous conversions until the contents of these registers
are valid, or, in 1SHOT mode, you have to have one conversion made.



Accessing DS1621 via /proc interface (part II and end)
------------------------------------------------------

The continuous file is rw. Reading gives "1" when the chip is in
continuous mode and "0" for 1SHOT. - Writing accepts "1" to put it
into continuous mode or "0" for 1SHOT.

The enable file is rw. Reading gives "1" if in continuous mode the
DS1621 is "running" or if in 1SHOT mode it is "shooting". In fact, the
value returned here is the negated DONE bit, just like a "BUSY"
flag. This means, that the "1" tells you that the values in REG_COUNT
and REG_SLOPE are not valid. "0", on the other hand, means that the
continuous conversion had been stopped long enough to provide valid
readings and that one shot has successfully been fi- red,
respectively. - Writing accepts "1" to start continuous conversion or
to pull the trigger in 1SHOT mode, and "0" stops continuous conversion
to allow for valid readings. Writing "0" in 1SHOT doesn't make much
sense since you cannot catch a bullet, can you? No, the thing is that
DS1621 does only do one conversion then anyway, and after that,
there's nothing to stop.

Last, but best try writing "0" to the "continuous" file and after that
"1" to the "enable" file. This gives you the precise temperature with
two digits after the radix (decimal point).
The precise results are only updated if the DONE bit was set, thus you
have to stop continuous conversion early enough prior to reading,
i. e. 1000ms. And, on the other hand, you shouldn't forget to fire off
1SHOT in order to get the actual temperature rather than that of the
day before yesterday. So read enable before any of these.


Chip Features
-------------

Chip `ds1621'
          LABEL     LABEL CLASS   COMPUTE CLASS ACCESS MAGNITUDE
           temp            NONE            NONE     R      1
      temp_hyst            temp            temp     RW     1
      temp_over            temp            temp     RW     1
         alarms            NONE            NONE     R      0
         enable            NONE            NONE     RW     0
     continuous            NONE            NONE     RW     0
       polarity            NONE            NONE     RW     0

          LABEL                   FEATURE SYMBOL     SYSCTL FILE:OFFSET
           temp              SENSORS_DS1621_TEMP            temp:3
      temp_hyst         SENSORS_DS1621_TEMP_HYST            temp:2
      temp_over         SENSORS_DS1621_TEMP_OVER            temp:1
         alarms            SENSORS_DS1621_ALARMS          alarms:1
         enable            SENSORS_DS1621_ENABLE          enable:1
     continuous        SENSORS_DS1621_CONTINUOUS      continuous:1
       polarity          SENSORS_DS1621_POLARITY        polarity:1