cleanup

1 files changed, 53 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..de690e7
--- /dev/null
+++ b/README
@@ -0,0 +1,53 @@
+Project: DS1992 memory iButton dumper
+
+ * this project is designed for the USB AVR LAB board by ullihome
+ * (http://www.ullihome.de/wiki/USBAVRLab/index)
+ * That's a small Atmega8-powered board with software-USB and a small pinout
+ * that looks like this:
+ *  ____   ____         ____   ____
+ * | . . . . . |       | o . . . . |
+ * | . . . . . |  or   | x . . . . |
+ * |___________|       |___________|
+ *
+ * hold the DS1992 token against the pins, so that the outer ring touches the
+ * "x" pin, while the inner circle touches the "o" pin.
+ *
+ * How to use:
+ * the dumping device has three modes of operation, which are shown by the blinking
+ * speed of the blue LED.
+ * 1. reading mode: normal blinking
+ * 2. reading mode: slooow blinking (previous operation failed)
+ * 3. writing mode: fast blinking
+ *
+ * in either mode, the red LED flashes periodically. This means that the device
+ * probed for a DS1992, but couldn't find anything on the bus. If you hold you
+ * DS1992 against the pins, the flashing will turn green instead. This means that
+ * the token has been read into the device's RAM.
+ * You can now use `pc/a.out read` to read the contents.
+ * (If both green and red leds flash, this means you've a short circuit.)
+ *
+ * If you execute `pc/a.out write <page> <data>`, then the device will enter
+ * writing mode. The flashing red LED has the same meaning as before. If you now
+ * connect the token, the page <page> (1-indexed) will be written to with <data>,
+ * whenever the LED flashes green the next time.
+ * After that, the device enters reading mode again. If the LED blinks really slow,
+ * then there was a write error. re-execute a.out write, reconnect the token and retry.
+ * Additionally, after writing you can use `a.out read` again (without connecting the
+ * token for reading previously). This will output you a lot of garbage, but the first
+ * byte read tells you a more detailed error code:
+ * 0x01: "reset/presence pulse" failed after scratchpad write
+ * 0x02: scratchpad did not verify correctly
+ * 0x03: "reset/presence pulse" failed after scratchpad readback + verify
+ * 0xFF: probably successful
+ *
+ * Note that you should read back the data after writing, just to be sure.
+ * Also note that while you can read the whole memory at once, you must execute the write
+ * command, and also connect the token, four times for a full write (once for each page).
+
+
+WARNING: This tool does not adhere to the 1-wire-specification and may damage your devices.
+         see 1wire.{c,h} for details.
+
+Author: Florian Jung (flo@windfisch.org)
+Copyright: (c) 2015,2016 by Florian Jung. All rights reserved.
+License: 3-clause BSD for avr/main.c; Note that different licensing applies for the V-USB library.