From bca8d498509d490e5c35429a53f00b3a72a6f68b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ond=C5=99ej=20Hru=C5=A1ka?= <ondra@ondrovo.com>
Date: Mon, 26 Mar 2018 22:44:02 +0200
Subject: [PATCH] 1wire docs

---
 README.md     |  2 +-
 UNIT_1WIRE.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 91 insertions(+), 1 deletion(-)
 create mode 100644 UNIT_1WIRE.md

diff --git a/README.md b/README.md
index 1402fca..881d2a1 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ This repository specifies the control protocol implemented by [gex-core](https:/
 - [UNIT_I2C.md](UNIT_I2C.md) - I2C master
 - [UNIT_SPI.md](UNIT_SPI.md) - SPI master with up to 16 slaves and multicast
 - [UNIT_FCAP.md](UNIT_FCAP.md) - Frequency, pulse length, PWM measurement; Pulse counter
-- UNIT_1WIRE.md - 1-Wire master
+- [UNIT_1WIRE.md](UNIT_1WIRE.md) - 1-Wire master (thermometers, iButton...)
 - UNIT_ADC.md - ADC with raw access, triggering, periodic capture
 - UNIT_DAC.md - DAC with DDS
 - UNIT_PWMDIM.md - Simpel PWM output
diff --git a/UNIT_1WIRE.md b/UNIT_1WIRE.md
new file mode 100644
index 0000000..e19ab4a
--- /dev/null
+++ b/UNIT_1WIRE.md
@@ -0,0 +1,90 @@
+# 1-Wire
+
+1-Wire is a Dallas (now Maxim) proprietary protocol used by the
+ubiquitous DS18x20 (DS1820, DS18S20, DS18B20), iButton (contact access
+chips) and other devices.
+
+The bus uses two wires, Data and GND. A third, Vdd wire, is optional and can be left out for parasitic power from the Data line. See the DS18x20 datasheet for more details.
+
+1-Wire requires precise timing and is implemented by bit-banging in GEX.
+GEX also implements the Search algorithm for finding all devices
+connected to the bus. Each device has a unique address, which are found
+using a form of binary search with hardware support in the individual devices.
+
+The search algorithm is available in a separate repository for easier re-use in other projects: [MightyPork/1wire-search](https://github.com/MightyPork/1wire-search).
+
+## Commands
+
+### CHECK_PRESENCE (0)
+
+Test if there are any devices attached to the bus.
+
+*Response:*
+- u8 - presence detected (0,1)
+
+### SEARCH_ADDR (1)
+
+Start the search algorithm, looking for all devices.
+
+Up to 32 devices can be found in one call. To find more, use the `SEARCH_CONTINUE`
+command.
+
+*Response:*
+- u8 - have more? (0,1) - indicates whether `SEARCH_CONTINUE` should be used.
+- u64[] - array of 8-byte addresses (litte-endian u64, or arrays of 8 bytes each)
+
+### SEARCH_ALARM (2)
+
+Identical to `SEARCH_ADDR` (see above), except only devices with
+an active Alarm status are detected. This is used with thermometers
+which can detect the temperature exceeding pre-selected limits.
+
+### SEARCH_CONTINUE (3)
+
+Continue a search (address or alarm). The report format is identical
+to `SEARCH_ADDR`, but continues after the last reported address.
+
+### READ_ADDR (4)
+
+Read the address of the single device connected to the bus.
+If more than one device is connected, this will likely fail due to a
+checksum mismatch.
+
+*Response:*
+- u64 - a 8-byte addresses (litte-endian u64, or an arrays of 8 bytes)
+
+### WRITE (10)
+
+Write bytes to the bus.
+
+*Request:*
+- u64 - a 8-byte device address
+  - 0 = all devices, uses the ROM_SKIP bus command
+- u8[] - bytes to write
+
+### READ (11)
+
+Send a query and read bytes from the bus.
+
+*Request:*
+- u64 - a 8-byte device address
+  - 0 = use the ROM_SKIP bus command, use with a single device connected only
+- u16 - read length (bytes)
+- u8 - verify the CRC chekcsum (0,1)
+- u8[] - request bytes (written before reading)
+
+*Response:*
+- u8[] - read bytes
+
+### POLL_FOR_1 (20)
+
+Wait for a READY status (used in DS18x20 measurements).
+
+*NOTE:* Not available if parasitic power is used, then it just waits the maximal measurement time of DS1820.
+
+A response is issued after all devices are done measuring,
+or a timeout error is returned.
+
+## Events
+
+*No events defined for this unit type.*