0001 ======================
0002 Kernel driver w1_therm
0003 ======================
0004
0005 Supported chips:
0006
0007 * Maxim ds18*20 based temperature sensors.
0008 * Maxim ds1825 based temperature sensors.
0009 * GXCAS GX20MH01 temperature sensor.
0010 * Maxim MAX31850 thermoelement interface.
0011
0012 Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru>
0013
0014
0015 Description
0016 -----------
0017
0018 w1_therm provides basic temperature conversion for ds18*20, ds28ea00, GX20MH01
0019 and MAX31850 devices.
0020
0021 Supported family codes:
0022
0023 ==================== ====
0024 W1_THERM_DS18S20 0x10
0025 W1_THERM_DS1822 0x22
0026 W1_THERM_DS18B20 0x28
0027 W1_THERM_DS1825 0x3B
0028 W1_THERM_DS28EA00 0x42
0029 ==================== ====
0030
0031 Support is provided through the sysfs entry ``w1_slave``. Each open and
0032 read sequence will initiate a temperature conversion, then provide two
0033 lines of ASCII output. The first line contains the nine hex bytes
0034 read along with a calculated crc value and YES or NO if it matched.
0035 If the crc matched the returned values are retained. The second line
0036 displays the retained values along with a temperature in millidegrees
0037 Centigrade after t=.
0038
0039 Alternatively, temperature can be read using ``temperature`` sysfs, it
0040 returns only the temperature in millidegrees Centigrade.
0041
0042 A bulk read of all devices on the bus could be done writing ``trigger``
0043 to ``therm_bulk_read`` entry at w1_bus_master level. This will
0044 send the convert command to all devices on the bus, and if parasite
0045 powered devices are detected on the bus (and strong pullup is enabled
0046 in the module), it will drive the line high during the longer conversion
0047 time required by parasited powered device on the line. Reading
0048 ``therm_bulk_read`` will return 0 if no bulk conversion pending,
0049 -1 if at least one sensor still in conversion, 1 if conversion is complete
0050 but at least one sensor value has not been read yet. Result temperature is
0051 then accessed by reading the ``temperature`` entry of each device, which
0052 may return empty if conversion is still in progress. Note that if a bulk
0053 read is sent but one sensor is not read immediately, the next access to
0054 ``temperature`` on this device will return the temperature measured at the
0055 time of issue of the bulk read command (not the current temperature).
0056
0057 A strong pullup will be applied during the conversion if required.
0058
0059 ``conv_time`` is used to get current conversion time (read), and
0060 adjust it (write). A temperature conversion time depends on the device type and
0061 it's current resolution. Default conversion time is set by the driver according
0062 to the device datasheet. A conversion time for many original device clones
0063 deviate from datasheet specs. There are three options: 1) manually set the
0064 correct conversion time by writing a value in milliseconds to ``conv_time``; 2)
0065 auto measure and set a conversion time by writing ``1`` to
0066 ``conv_time``; 3) use ``features`` to enable poll for conversion
0067 completion. Options 2, 3 can't be used in parasite power mode. To get back to
0068 the default conversion time write ``0`` to ``conv_time``.
0069
0070 Writing a resolution value (in bits) to ``w1_slave`` will change the
0071 precision of the sensor for the next readings. Allowed resolutions are defined by
0072 the sensor. Resolution is reset when the sensor gets power-cycled.
0073
0074 To store the current resolution in EEPROM, write ``0`` to ``w1_slave``.
0075 Since the EEPROM has a limited amount of writes (>50k), this command should be
0076 used wisely.
0077
0078 Alternatively, resolution can be read or written using the dedicated
0079 ``resolution`` entry on each device, if supported by the sensor.
0080
0081 Some non-genuine DS18B20 chips are fixed in 12-bit mode only, so the actual
0082 resolution is read back from the chip and verified.
0083
0084 Note: Changing the resolution reverts the conversion time to default.
0085
0086 The write-only sysfs entry ``eeprom_cmd`` is an alternative for EEPROM operations.
0087 Write ``save`` to save device RAM to EEPROM. Write ``restore`` to restore EEPROM
0088 data in device RAM.
0089
0090 ``ext_power`` entry allows checking the power state of each device. Reads
0091 ``0`` if the device is parasite powered, ``1`` if the device is externally powered.
0092
0093 Sysfs ``alarms`` allow read or write TH and TL (Temperature High an Low) alarms.
0094 Values shall be space separated and in the device range (typical -55 degC
0095 to 125 degC). Values are integer as they are store in a 8bit register in
0096 the device. Lowest value is automatically put to TL. Once set, alarms could
0097 be search at master level.
0098
0099 The module parameter strong_pullup can be set to 0 to disable the
0100 strong pullup, 1 to enable autodetection or 2 to force strong pullup.
0101 In case of autodetection, the driver will use the "READ POWER SUPPLY"
0102 command to check if there are pariste powered devices on the bus.
0103 If so, it will activate the master's strong pullup.
0104 In case the detection of parasite devices using this command fails
0105 (seems to be the case with some DS18S20) the strong pullup can
0106 be force-enabled.
0107
0108 If the strong pullup is enabled, the master's strong pullup will be
0109 driven when the conversion is taking place, provided the master driver
0110 does support the strong pullup (or it falls back to a pullup
0111 resistor). The DS18b20 temperature sensor specification lists a
0112 maximum current draw of 1.5mA and that a 5k pullup resistor is not
0113 sufficient. The strong pullup is designed to provide the additional
0114 current required.
0115
0116 The DS28EA00 provides an additional two pins for implementing a sequence
0117 detection algorithm. This feature allows you to determine the physical
0118 location of the chip in the 1-wire bus without needing pre-existing
0119 knowledge of the bus ordering. Support is provided through the sysfs
0120 ``w1_seq``. The file will contain a single line with an integer value
0121 representing the device index in the bus starting at 0.
0122
0123 ``features`` sysfs entry controls optional driver settings per device.
0124 Insufficient power in parasite mode, line noise and insufficient conversion
0125 time may lead to conversion failure. Original DS18B20 and some clones allow for
0126 detection of invalid conversion. Write bit mask ``1`` to ``features`` to enable
0127 checking the conversion success. If byte 6 of scratchpad memory is 0xC after
0128 conversion and temperature reads 85.00 (powerup value) or 127.94 (insufficient
0129 power), the driver returns a conversion error. Bit mask ``2`` enables poll for
0130 conversion completion (normal power only) by generating read cycles on the bus
0131 after conversion starts. In parasite power mode this feature is not available.
0132 Feature bit masks may be combined (OR). More details in
0133 Documentation/ABI/testing/sysfs-driver-w1_therm
0134
0135 GX20MH01 device shares family number 0x28 with DS18*20. The device is generally
0136 compatible with DS18B20. Added are lowest 2\ :sup:`-5`, 2\ :sup:`-6` temperature
0137 bits in Config register; R2 bit in Config register enabling 13 and 14 bit
0138 resolutions. The device is powered up in 14-bit resolution mode. The conversion
0139 times specified in the datasheet are too low and have to be increased. The
0140 device supports driver features ``1`` and ``2``.
0141
0142 MAX31850 device shares family number 0x3B with DS1825. The device is generally
0143 compatible with DS1825. The higher 4 bits of Config register read all 1,
0144 indicating 15, but the device is always operating in 14-bit resolution mode.
