summaryrefslogtreecommitdiffstats
path: root/Documentation/w1/slaves
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/w1/slaves')
-rw-r--r--Documentation/w1/slaves/index.rst16
-rw-r--r--Documentation/w1/slaves/w1_ds2406.rst27
-rw-r--r--Documentation/w1/slaves/w1_ds2413.rst59
-rw-r--r--Documentation/w1/slaves/w1_ds2423.rst54
-rw-r--r--Documentation/w1/slaves/w1_ds2438.rst86
-rw-r--r--Documentation/w1/slaves/w1_ds28e04.rst41
-rw-r--r--Documentation/w1/slaves/w1_ds28e17.rst72
-rw-r--r--Documentation/w1/slaves/w1_therm.rst144
8 files changed, 499 insertions, 0 deletions
diff --git a/Documentation/w1/slaves/index.rst b/Documentation/w1/slaves/index.rst
new file mode 100644
index 000000000..d0697b202
--- /dev/null
+++ b/Documentation/w1/slaves/index.rst
@@ -0,0 +1,16 @@
+. SPDX-License-Identifier: GPL-2.0
+
+====================
+1-wire Slave Drivers
+====================
+
+.. toctree::
+ :maxdepth: 1
+
+ w1_ds2406
+ w1_ds2413
+ w1_ds2423
+ w1_ds2438
+ w1_ds28e04
+ w1_ds28e17
+ w1_therm
diff --git a/Documentation/w1/slaves/w1_ds2406.rst b/Documentation/w1/slaves/w1_ds2406.rst
new file mode 100644
index 000000000..d3e682660
--- /dev/null
+++ b/Documentation/w1/slaves/w1_ds2406.rst
@@ -0,0 +1,27 @@
+=======================
+w1_ds2406 kernel driver
+=======================
+
+Supported chips:
+
+ * Maxim DS2406 (and other family 0x12) addressable switches
+
+Author: Scott Alfter <scott@alfter.us>
+
+Description
+-----------
+
+The w1_ds2406 driver allows connected devices to be switched on and off.
+These chips also provide 128 bytes of OTP EPROM, but reading/writing it is
+not supported. In TSOC-6 form, the DS2406 provides two switch outputs and
+can be provided with power on a dedicated input. In TO-92 form, it provides
+one output and uses parasitic power only.
+
+The driver provides two sysfs files. state is readable; it gives the
+current state of each switch, with PIO A in bit 0 and PIO B in bit 1. The
+driver ORs this state with 0x30, so shell scripts get an ASCII 0/1/2/3 to
+work with. output is writable; bits 0 and 1 control PIO A and B,
+respectively. Bits 2-7 are ignored, so it's safe to write ASCII data.
+
+CRCs are checked on read and write. Failed checks cause an I/O error to be
+returned. On a failed write, the switch status is not changed.
diff --git a/Documentation/w1/slaves/w1_ds2413.rst b/Documentation/w1/slaves/w1_ds2413.rst
new file mode 100644
index 000000000..c15bb5b91
--- /dev/null
+++ b/Documentation/w1/slaves/w1_ds2413.rst
@@ -0,0 +1,59 @@
+=======================
+Kernel driver w1_ds2413
+=======================
+
+Supported chips:
+
+ * Maxim DS2413 1-Wire Dual Channel Addressable Switch
+
+supported family codes:
+
+ ================ ====
+ W1_FAMILY_DS2413 0x3A
+ ================ ====
+
+Author: Mariusz Bialonczyk <manio@skyboo.net>
+
+Description
+-----------
+
+The DS2413 chip has two open-drain outputs (PIO A and PIO B).
+Support is provided through the sysfs files "output" and "state".
+
+Reading state
+-------------
+The "state" file provides one-byte value which is in the same format as for
+the chip PIO_ACCESS_READ command (refer the datasheet for details):
+
+======== =============================================================
+Bit 0: PIOA Pin State
+Bit 1: PIOA Output Latch State
+Bit 2: PIOB Pin State
+Bit 3: PIOB Output Latch State
+Bit 4-7: Complement of Bit 3 to Bit 0 (verified by the kernel module)
+======== =============================================================
+
+This file is readonly.
+
+Writing output
+--------------
+You can set the PIO pins using the "output" file.
+It is writable, you can write one-byte value to this sysfs file.
+Similarly the byte format is the same as for the PIO_ACCESS_WRITE command:
+
+======== ======================================
+Bit 0: PIOA
+Bit 1: PIOB
+Bit 2-7: No matter (driver will set it to "1"s)
+======== ======================================
+
+
+The chip has some kind of basic protection against transmission errors.
+When reading the state, there is a four complement bits.
+The driver is checking this complement, and when it is wrong then it is
+returning I/O error.
+
+When writing output, the master must repeat the PIO Output Data byte in
+its inverted form and it is waiting for a confirmation.
+If the write is unsuccessful for three times, the write also returns
+I/O error.
diff --git a/Documentation/w1/slaves/w1_ds2423.rst b/Documentation/w1/slaves/w1_ds2423.rst
new file mode 100644
index 000000000..755d659ad
--- /dev/null
+++ b/Documentation/w1/slaves/w1_ds2423.rst
@@ -0,0 +1,54 @@
+Kernel driver w1_ds2423
+=======================
+
+Supported chips:
+
+ * Maxim DS2423 based counter devices.
+
+supported family codes:
+
+ =============== ====
+ W1_THERM_DS2423 0x1D
+ =============== ====
+
+Author: Mika Laitio <lamikr@pilppa.org>
+
+Description
+-----------
+
+Support is provided through the sysfs w1_slave file. Each opening and
+read sequence of w1_slave file initiates the read of counters and ram
+available in DS2423 pages 12 - 15.
+
+Result of each page is provided as an ASCII output where each counter
+value and associated ram buffer is outpputed to own line.
+
+Each lines will contain the values of 42 bytes read from the counter and
+memory page along the crc=YES or NO for indicating whether the read operation
+was successful and CRC matched.
+If the operation was successful, there is also in the end of each line
+a counter value expressed as an integer after c=
+
+Meaning of 42 bytes represented is following:
+
+ - 1 byte from ram page
+ - 4 bytes for the counter value
+ - 4 zero bytes
+ - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes
+ - 31 remaining bytes from the ram page
+ - crc=YES/NO indicating whether read was ok and crc matched
+ - c=<int> current counter value
+
+example from the successful read::
+
+ 00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+ 00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+ 00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761
+ 00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5
+
+example from the read with crc errors::
+
+ 00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+ 00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
+ 00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
+ 00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO
diff --git a/Documentation/w1/slaves/w1_ds2438.rst b/Documentation/w1/slaves/w1_ds2438.rst
new file mode 100644
index 000000000..4fa671fbc
--- /dev/null
+++ b/Documentation/w1/slaves/w1_ds2438.rst
@@ -0,0 +1,86 @@
+Kernel driver w1_ds2438
+=======================
+
+Supported chips:
+
+ * Maxim DS2438 Smart Battery Monitor
+
+supported family codes:
+ ================ ====
+ W1_FAMILY_DS2438 0x26
+ ================ ====
+
+Author: Mariusz Bialonczyk <manio@skyboo.net>
+
+Description
+-----------
+
+The DS2438 chip provides several functions that are desirable to carry in
+a battery pack. It also has a 40 bytes of nonvolatile EEPROM.
+Because the ability of temperature, current and voltage measurement, the chip
+is also often used in weather stations and applications such as: rain gauge,
+wind speed/direction measuring, humidity sensing, etc.
+
+Current support is provided through the following sysfs files (all files
+except "iad" and "offset" are readonly):
+
+"iad"
+-----
+This file controls the 'Current A/D Control Bit' (IAD) in the
+Status/Configuration Register.
+Writing a zero value will clear the IAD bit and disables the current
+measurements.
+Writing value "1" is setting the IAD bit (enables the measurements).
+The IAD bit is enabled by default in the DS2438.
+
+When writing to sysfs file bits 2-7 are ignored, so it's safe to write ASCII.
+An I/O error is returned when there is a problem setting the new value.
+
+"page0"
+-------
+This file provides full 8 bytes of the chip Page 0 (00h).
+This page contains the most frequently accessed information of the DS2438.
+Internally when this file is read, the additional CRC byte is also obtained
+from the slave device. If it is correct, the 8 bytes page data are passed
+to userspace, otherwise an I/O error is returned.
+
+"page1"
+-------
+This file provides full 8 bytes of the chip Page 1 (01h).
+This page contains the ICA, elapsed time meter and current offset data of the DS2438.
+Internally when this file is read, the additional CRC byte is also obtained
+from the slave device. If it is correct, the 8 bytes page data are passed
+to userspace, otherwise an I/O error is returned.
+
+"offset"
+--------
+This file controls the 2-byte Offset Register of the chip.
+Writing a 2-byte value will change the Offset Register, which changes the
+current measurement done by the chip. Changing this register to the two's complement
+of the current register while forcing zero current through the load will calibrate
+the chip, canceling offset errors in the current ADC.
+
+
+"temperature"
+-------------
+Opening and reading this file initiates the CONVERT_T (temperature conversion)
+command of the chip, afterwards the temperature is read from the device
+registers and provided as an ASCII decimal value.
+
+Important: The returned value has to be divided by 256 to get a real
+temperature in degrees Celsius.
+
+"vad", "vdd"
+------------
+Opening and reading this file initiates the CONVERT_V (voltage conversion)
+command of the chip.
+
+Depending on a sysfs filename a different input for the A/D will be selected:
+
+vad:
+ general purpose A/D input (VAD)
+vdd:
+ battery input (VDD)
+
+After the voltage conversion the value is returned as decimal ASCII.
+Note: To get a volts the value has to be divided by 100.
diff --git a/Documentation/w1/slaves/w1_ds28e04.rst b/Documentation/w1/slaves/w1_ds28e04.rst
new file mode 100644
index 000000000..b12b11889
--- /dev/null
+++ b/Documentation/w1/slaves/w1_ds28e04.rst
@@ -0,0 +1,41 @@
+========================
+Kernel driver w1_ds28e04
+========================
+
+Supported chips:
+
+ * Maxim DS28E04-100 4096-Bit Addressable 1-Wire EEPROM with PIO
+
+supported family codes:
+
+ ================= ====
+ W1_FAMILY_DS28E04 0x1C
+ ================= ====
+
+Author: Markus Franke, <franke.m@sebakmt.com> <franm@hrz.tu-chemnitz.de>
+
+Description
+-----------
+
+Support is provided through the sysfs files "eeprom" and "pio". CRC checking
+during memory accesses can optionally be enabled/disabled via the device
+attribute "crccheck". The strong pull-up can optionally be enabled/disabled
+via the module parameter "w1_strong_pullup".
+
+Memory Access
+
+ A read operation on the "eeprom" file reads the given amount of bytes
+ from the EEPROM of the DS28E04.
+
+ A write operation on the "eeprom" file writes the given byte sequence
+ to the EEPROM of the DS28E04. If CRC checking mode is enabled only
+ fully aligned blocks of 32 bytes with valid CRC16 values (in bytes 30
+ and 31) are allowed to be written.
+
+PIO Access
+
+ The 2 PIOs of the DS28E04-100 are accessible via the "pio" sysfs file.
+
+ The current status of the PIO's is returned as an 8 bit value. Bit 0/1
+ represent the state of PIO_0/PIO_1. Bits 2..7 do not care. The PIO's are
+ driven low-active, i.e. the driver delivers/expects low-active values.
diff --git a/Documentation/w1/slaves/w1_ds28e17.rst b/Documentation/w1/slaves/w1_ds28e17.rst
new file mode 100644
index 000000000..e2d9f96d8
--- /dev/null
+++ b/Documentation/w1/slaves/w1_ds28e17.rst
@@ -0,0 +1,72 @@
+========================
+Kernel driver w1_ds28e17
+========================
+
+Supported chips:
+
+ * Maxim DS28E17 1-Wire-to-I2C Master Bridge
+
+supported family codes:
+
+ ================= ====
+ W1_FAMILY_DS28E17 0x19
+ ================= ====
+
+Author: Jan Kandziora <jjj@gmx.de>
+
+
+Description
+-----------
+The DS28E17 is a Onewire slave device which acts as an I2C bus master.
+
+This driver creates a new I2C bus for any DS28E17 device detected. I2C buses
+come and go as the DS28E17 devices come and go. I2C slave devices connected to
+a DS28E17 can be accessed by the kernel or userspace tools as if they were
+connected to a "native" I2C bus master.
+
+
+An udev rule like the following::
+
+ SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
+ SYMLINK+="i2c-$attr{name}"
+
+may be used to create stable /dev/i2c- entries based on the unique id of the
+DS28E17 chip.
+
+
+Driver parameters are:
+
+speed:
+ This sets up the default I2C speed a DS28E17 get configured for as soon
+ it is connected. The power-on default of the DS28E17 is 400kBaud, but
+ chips may come and go on the Onewire bus without being de-powered and
+ as soon the "w1_ds28e17" driver notices a freshly connected, or
+ reconnected DS28E17 device on the Onewire bus, it will re-apply this
+ setting.
+
+ Valid values are 100, 400, 900 [kBaud]. Any other value means to leave
+ alone the current DS28E17 setting on detect. The default value is 100.
+
+stretch:
+ This sets up the default stretch value used for freshly connected
+ DS28E17 devices. It is a multiplier used on the calculation of the busy
+ wait time for an I2C transfer. This is to account for I2C slave devices
+ which make heavy use of the I2C clock stretching feature and thus, the
+ needed timeout cannot be pre-calculated correctly. As the w1_ds28e17
+ driver checks the DS28E17's busy flag in a loop after the precalculated
+ wait time, it should be hardly needed to tweak this setting.
+
+ Leave it at 1 unless you get ETIMEDOUT errors and a "w1_slave_driver
+ 19-00000002dbd8: busy timeout" in the kernel log.
+
+ Valid values are 1 to 9. The default is 1.
+
+
+The driver creates sysfs files /sys/bus/w1/devices/19-<id>/speed and
+/sys/bus/w1/devices/19-<id>/stretch for each device, preloaded with the default
+settings from the driver parameters. They may be changed anytime. In addition a
+directory /sys/bus/w1/devices/19-<id>/i2c-<nnn> for the I2C bus master sysfs
+structure is created.
+
+
+See https://github.com/ianka/w1_ds28e17 for even more information.
diff --git a/Documentation/w1/slaves/w1_therm.rst b/Documentation/w1/slaves/w1_therm.rst
new file mode 100644
index 000000000..758dadba8
--- /dev/null
+++ b/Documentation/w1/slaves/w1_therm.rst
@@ -0,0 +1,144 @@
+======================
+Kernel driver w1_therm
+======================
+
+Supported chips:
+
+ * Maxim ds18*20 based temperature sensors.
+ * Maxim ds1825 based temperature sensors.
+ * GXCAS GX20MH01 temperature sensor.
+ * Maxim MAX31850 thermoelement interface.
+
+Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru>
+
+
+Description
+-----------
+
+w1_therm provides basic temperature conversion for ds18*20, ds28ea00, GX20MH01
+and MAX31850 devices.
+
+Supported family codes:
+
+==================== ====
+W1_THERM_DS18S20 0x10
+W1_THERM_DS1822 0x22
+W1_THERM_DS18B20 0x28
+W1_THERM_DS1825 0x3B
+W1_THERM_DS28EA00 0x42
+==================== ====
+
+Support is provided through the sysfs entry ``w1_slave``. Each open and
+read sequence will initiate a temperature conversion, then provide two
+lines of ASCII output. The first line contains the nine hex bytes
+read along with a calculated crc value and YES or NO if it matched.
+If the crc matched the returned values are retained. The second line
+displays the retained values along with a temperature in millidegrees
+Centigrade after t=.
+
+Alternatively, temperature can be read using ``temperature`` sysfs, it
+returns only the temperature in millidegrees Centigrade.
+
+A bulk read of all devices on the bus could be done writing ``trigger``
+to ``therm_bulk_read`` entry at w1_bus_master level. This will
+send the convert command to all devices on the bus, and if parasite
+powered devices are detected on the bus (and strong pullup is enabled
+in the module), it will drive the line high during the longer conversion
+time required by parasited powered device on the line. Reading
+``therm_bulk_read`` will return 0 if no bulk conversion pending,
+-1 if at least one sensor still in conversion, 1 if conversion is complete
+but at least one sensor value has not been read yet. Result temperature is
+then accessed by reading the ``temperature`` entry of each device, which
+may return empty if conversion is still in progress. Note that if a bulk
+read is sent but one sensor is not read immediately, the next access to
+``temperature`` on this device will return the temperature measured at the
+time of issue of the bulk read command (not the current temperature).
+
+A strong pullup will be applied during the conversion if required.
+
+``conv_time`` is used to get current conversion time (read), and
+adjust it (write). A temperature conversion time depends on the device type and
+it's current resolution. Default conversion time is set by the driver according
+to the device datasheet. A conversion time for many original device clones
+deviate from datasheet specs. There are three options: 1) manually set the
+correct conversion time by writing a value in milliseconds to ``conv_time``; 2)
+auto measure and set a conversion time by writing ``1`` to
+``conv_time``; 3) use ``features`` to enable poll for conversion
+completion. Options 2, 3 can't be used in parasite power mode. To get back to
+the default conversion time write ``0`` to ``conv_time``.
+
+Writing a resolution value (in bits) to ``w1_slave`` will change the
+precision of the sensor for the next readings. Allowed resolutions are defined by
+the sensor. Resolution is reset when the sensor gets power-cycled.
+
+To store the current resolution in EEPROM, write ``0`` to ``w1_slave``.
+Since the EEPROM has a limited amount of writes (>50k), this command should be
+used wisely.
+
+Alternatively, resolution can be read or written using the dedicated
+``resolution`` entry on each device, if supported by the sensor.
+
+Some non-genuine DS18B20 chips are fixed in 12-bit mode only, so the actual
+resolution is read back from the chip and verified.
+
+Note: Changing the resolution reverts the conversion time to default.
+
+The write-only sysfs entry ``eeprom_cmd`` is an alternative for EEPROM operations.
+Write ``save`` to save device RAM to EEPROM. Write ``restore`` to restore EEPROM
+data in device RAM.
+
+``ext_power`` entry allows checking the power state of each device. Reads
+``0`` if the device is parasite powered, ``1`` if the device is externally powered.
+
+Sysfs ``alarms`` allow read or write TH and TL (Temperature High an Low) alarms.
+Values shall be space separated and in the device range (typical -55 degC
+to 125 degC). Values are integer as they are store in a 8bit register in
+the device. Lowest value is automatically put to TL. Once set, alarms could
+be search at master level.
+
+The module parameter strong_pullup can be set to 0 to disable the
+strong pullup, 1 to enable autodetection or 2 to force strong pullup.
+In case of autodetection, the driver will use the "READ POWER SUPPLY"
+command to check if there are pariste powered devices on the bus.
+If so, it will activate the master's strong pullup.
+In case the detection of parasite devices using this command fails
+(seems to be the case with some DS18S20) the strong pullup can
+be force-enabled.
+
+If the strong pullup is enabled, the master's strong pullup will be
+driven when the conversion is taking place, provided the master driver
+does support the strong pullup (or it falls back to a pullup
+resistor). The DS18b20 temperature sensor specification lists a
+maximum current draw of 1.5mA and that a 5k pullup resistor is not
+sufficient. The strong pullup is designed to provide the additional
+current required.
+
+The DS28EA00 provides an additional two pins for implementing a sequence
+detection algorithm. This feature allows you to determine the physical
+location of the chip in the 1-wire bus without needing pre-existing
+knowledge of the bus ordering. Support is provided through the sysfs
+``w1_seq``. The file will contain a single line with an integer value
+representing the device index in the bus starting at 0.
+
+``features`` sysfs entry controls optional driver settings per device.
+Insufficient power in parasite mode, line noise and insufficient conversion
+time may lead to conversion failure. Original DS18B20 and some clones allow for
+detection of invalid conversion. Write bit mask ``1`` to ``features`` to enable
+checking the conversion success. If byte 6 of scratchpad memory is 0xC after
+conversion and temperature reads 85.00 (powerup value) or 127.94 (insufficient
+power), the driver returns a conversion error. Bit mask ``2`` enables poll for
+conversion completion (normal power only) by generating read cycles on the bus
+after conversion starts. In parasite power mode this feature is not available.
+Feature bit masks may be combined (OR). More details in
+Documentation/ABI/testing/sysfs-driver-w1_therm
+
+GX20MH01 device shares family number 0x28 with DS18*20. The device is generally
+compatible with DS18B20. Added are lowest 2\ :sup:`-5`, 2\ :sup:`-6` temperature
+bits in Config register; R2 bit in Config register enabling 13 and 14 bit
+resolutions. The device is powered up in 14-bit resolution mode. The conversion
+times specified in the datasheet are too low and have to be increased. The
+device supports driver features ``1`` and ``2``.
+
+MAX31850 device shares family number 0x3B with DS1825. The device is generally
+compatible with DS1825. The higher 4 bits of Config register read all 1,
+indicating 15, but the device is always operating in 14-bit resolution mode.