1*4882a593Smuzhiyun====================== 2*4882a593SmuzhiyunKernel driver w1_therm 3*4882a593Smuzhiyun====================== 4*4882a593Smuzhiyun 5*4882a593SmuzhiyunSupported chips: 6*4882a593Smuzhiyun 7*4882a593Smuzhiyun * Maxim ds18*20 based temperature sensors. 8*4882a593Smuzhiyun * Maxim ds1825 based temperature sensors. 9*4882a593Smuzhiyun * GXCAS GC20MH01 temperature sensor. 10*4882a593Smuzhiyun 11*4882a593SmuzhiyunAuthor: Evgeniy Polyakov <johnpol@2ka.mipt.ru> 12*4882a593Smuzhiyun 13*4882a593Smuzhiyun 14*4882a593SmuzhiyunDescription 15*4882a593Smuzhiyun----------- 16*4882a593Smuzhiyun 17*4882a593Smuzhiyunw1_therm provides basic temperature conversion for ds18*20, ds28ea00, GX20MH01 18*4882a593Smuzhiyundevices. 19*4882a593Smuzhiyun 20*4882a593SmuzhiyunSupported family codes: 21*4882a593Smuzhiyun 22*4882a593Smuzhiyun==================== ==== 23*4882a593SmuzhiyunW1_THERM_DS18S20 0x10 24*4882a593SmuzhiyunW1_THERM_DS1822 0x22 25*4882a593SmuzhiyunW1_THERM_DS18B20 0x28 26*4882a593SmuzhiyunW1_THERM_DS1825 0x3B 27*4882a593SmuzhiyunW1_THERM_DS28EA00 0x42 28*4882a593Smuzhiyun==================== ==== 29*4882a593Smuzhiyun 30*4882a593SmuzhiyunSupport is provided through the sysfs entry ``w1_slave``. Each open and 31*4882a593Smuzhiyunread sequence will initiate a temperature conversion, then provide two 32*4882a593Smuzhiyunlines of ASCII output. The first line contains the nine hex bytes 33*4882a593Smuzhiyunread along with a calculated crc value and YES or NO if it matched. 34*4882a593SmuzhiyunIf the crc matched the returned values are retained. The second line 35*4882a593Smuzhiyundisplays the retained values along with a temperature in millidegrees 36*4882a593SmuzhiyunCentigrade after t=. 37*4882a593Smuzhiyun 38*4882a593SmuzhiyunAlternatively, temperature can be read using ``temperature`` sysfs, it 39*4882a593Smuzhiyunreturns only the temperature in millidegrees Centigrade. 40*4882a593Smuzhiyun 41*4882a593SmuzhiyunA bulk read of all devices on the bus could be done writing ``trigger`` 42*4882a593Smuzhiyunto ``therm_bulk_read`` entry at w1_bus_master level. This will 43*4882a593Smuzhiyunsend the convert command to all devices on the bus, and if parasite 44*4882a593Smuzhiyunpowered devices are detected on the bus (and strong pullup is enabled 45*4882a593Smuzhiyunin the module), it will drive the line high during the longer conversion 46*4882a593Smuzhiyuntime required by parasited powered device on the line. Reading 47*4882a593Smuzhiyun``therm_bulk_read`` will return 0 if no bulk conversion pending, 48*4882a593Smuzhiyun-1 if at least one sensor still in conversion, 1 if conversion is complete 49*4882a593Smuzhiyunbut at least one sensor value has not been read yet. Result temperature is 50*4882a593Smuzhiyunthen accessed by reading the ``temperature`` entry of each device, which 51*4882a593Smuzhiyunmay return empty if conversion is still in progress. Note that if a bulk 52*4882a593Smuzhiyunread is sent but one sensor is not read immediately, the next access to 53*4882a593Smuzhiyun``temperature`` on this device will return the temperature measured at the 54*4882a593Smuzhiyuntime of issue of the bulk read command (not the current temperature). 55*4882a593Smuzhiyun 56*4882a593SmuzhiyunA strong pullup will be applied during the conversion if required. 57*4882a593Smuzhiyun 58*4882a593Smuzhiyun``conv_time`` is used to get current conversion time (read), and 59*4882a593Smuzhiyunadjust it (write). A temperature conversion time depends on the device type and 60*4882a593Smuzhiyunit's current resolution. Default conversion time is set by the driver according 61*4882a593Smuzhiyunto the device datasheet. A conversion time for many original device clones 62*4882a593Smuzhiyundeviate from datasheet specs. There are three options: 1) manually set the 63*4882a593Smuzhiyuncorrect conversion time by writing a value in milliseconds to ``conv_time``; 2) 64*4882a593Smuzhiyunauto measure and set a conversion time by writing ``1`` to 65*4882a593Smuzhiyun``conv_time``; 3) use ``features`` to enable poll for conversion 66*4882a593Smuzhiyuncompletion. Options 2, 3 can't be used in parasite power mode. To get back to 67*4882a593Smuzhiyunthe default conversion time write ``0`` to ``conv_time``. 68*4882a593Smuzhiyun 69*4882a593SmuzhiyunWriting a resolution value (in bits) to ``w1_slave`` will change the 70*4882a593Smuzhiyunprecision of the sensor for the next readings. Allowed resolutions are defined by 71*4882a593Smuzhiyunthe sensor. Resolution is reset when the sensor gets power-cycled. 72*4882a593Smuzhiyun 73*4882a593SmuzhiyunTo store the current resolution in EEPROM, write ``0`` to ``w1_slave``. 74*4882a593SmuzhiyunSince the EEPROM has a limited amount of writes (>50k), this command should be 75*4882a593Smuzhiyunused wisely. 76*4882a593Smuzhiyun 77*4882a593SmuzhiyunAlternatively, resolution can be read or written using the dedicated 78*4882a593Smuzhiyun``resolution`` entry on each device, if supported by the sensor. 79*4882a593Smuzhiyun 80*4882a593SmuzhiyunSome non-genuine DS18B20 chips are fixed in 12-bit mode only, so the actual 81*4882a593Smuzhiyunresolution is read back from the chip and verified. 82*4882a593Smuzhiyun 83*4882a593SmuzhiyunNote: Changing the resolution reverts the conversion time to default. 84*4882a593Smuzhiyun 85*4882a593SmuzhiyunThe write-only sysfs entry ``eeprom`` is an alternative for EEPROM operations. 86*4882a593SmuzhiyunWrite ``save`` to save device RAM to EEPROM. Write ``restore`` to restore EEPROM 87*4882a593Smuzhiyundata in device RAM. 88*4882a593Smuzhiyun 89*4882a593Smuzhiyun``ext_power`` entry allows checking the power state of each device. Reads 90*4882a593Smuzhiyun``0`` if the device is parasite powered, ``1`` if the device is externally powered. 91*4882a593Smuzhiyun 92*4882a593SmuzhiyunSysfs ``alarms`` allow read or write TH and TL (Temperature High an Low) alarms. 93*4882a593SmuzhiyunValues shall be space separated and in the device range (typical -55 degC 94*4882a593Smuzhiyunto 125 degC). Values are integer as they are store in a 8bit register in 95*4882a593Smuzhiyunthe device. Lowest value is automatically put to TL. Once set, alarms could 96*4882a593Smuzhiyunbe search at master level. 97*4882a593Smuzhiyun 98*4882a593SmuzhiyunThe module parameter strong_pullup can be set to 0 to disable the 99*4882a593Smuzhiyunstrong pullup, 1 to enable autodetection or 2 to force strong pullup. 100*4882a593SmuzhiyunIn case of autodetection, the driver will use the "READ POWER SUPPLY" 101*4882a593Smuzhiyuncommand to check if there are pariste powered devices on the bus. 102*4882a593SmuzhiyunIf so, it will activate the master's strong pullup. 103*4882a593SmuzhiyunIn case the detection of parasite devices using this command fails 104*4882a593Smuzhiyun(seems to be the case with some DS18S20) the strong pullup can 105*4882a593Smuzhiyunbe force-enabled. 106*4882a593Smuzhiyun 107*4882a593SmuzhiyunIf the strong pullup is enabled, the master's strong pullup will be 108*4882a593Smuzhiyundriven when the conversion is taking place, provided the master driver 109*4882a593Smuzhiyundoes support the strong pullup (or it falls back to a pullup 110*4882a593Smuzhiyunresistor). The DS18b20 temperature sensor specification lists a 111*4882a593Smuzhiyunmaximum current draw of 1.5mA and that a 5k pullup resistor is not 112*4882a593Smuzhiyunsufficient. The strong pullup is designed to provide the additional 113*4882a593Smuzhiyuncurrent required. 114*4882a593Smuzhiyun 115*4882a593SmuzhiyunThe DS28EA00 provides an additional two pins for implementing a sequence 116*4882a593Smuzhiyundetection algorithm. This feature allows you to determine the physical 117*4882a593Smuzhiyunlocation of the chip in the 1-wire bus without needing pre-existing 118*4882a593Smuzhiyunknowledge of the bus ordering. Support is provided through the sysfs 119*4882a593Smuzhiyun``w1_seq``. The file will contain a single line with an integer value 120*4882a593Smuzhiyunrepresenting the device index in the bus starting at 0. 121*4882a593Smuzhiyun 122*4882a593Smuzhiyun``features`` sysfs entry controls optional driver settings per device. 123*4882a593SmuzhiyunInsufficient power in parasite mode, line noise and insufficient conversion 124*4882a593Smuzhiyuntime may lead to conversion failure. Original DS18B20 and some clones allow for 125*4882a593Smuzhiyundetection of invalid conversion. Write bit mask ``1`` to ``features`` to enable 126*4882a593Smuzhiyunchecking the conversion success. If byte 6 of scratchpad memory is 0xC after 127*4882a593Smuzhiyunconversion and temperature reads 85.00 (powerup value) or 127.94 (insufficient 128*4882a593Smuzhiyunpower), the driver returns a conversion error. Bit mask ``2`` enables poll for 129*4882a593Smuzhiyunconversion completion (normal power only) by generating read cycles on the bus 130*4882a593Smuzhiyunafter conversion starts. In parasite power mode this feature is not available. 131*4882a593SmuzhiyunFeature bit masks may be combined (OR). More details in 132*4882a593SmuzhiyunDocumentation/ABI/testing/sysfs-driver-w1_therm 133*4882a593Smuzhiyun 134*4882a593SmuzhiyunGX20MH01 device shares family number 0x28 with DS18*20. The device is generally 135*4882a593Smuzhiyuncompatible with DS18B20. Added are lowest 2\ :sup:`-5`, 2\ :sup:`-6` temperature 136*4882a593Smuzhiyunbits in Config register; R2 bit in Config register enabling 13 and 14 bit 137*4882a593Smuzhiyunresolutions. The device is powered up in 14-bit resolution mode. The conversion 138*4882a593Smuzhiyuntimes specified in the datasheet are too low and have to be increased. The 139*4882a593Smuzhiyundevice supports driver features ``1`` and ``2``. 140