Update README

* Add info on current changes

diff --git a/README.adoc b/README.adoc
index 44b2071b7bbf2cacc6a3c4b76926a20184fd0c6e..109f2cdde7d1e4157bfe5f985bca8ddb4e51aaed 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -14,7 +14,49 @@ This is not necessary - 4D provides {link-spe}[comprehensive
 documentation] on the opcodes and how to use them. It is left as an exercise to
 the reader to replicate the same without referring to library code.
 
+== Approach
+The code uses ESP-IDF as its platform. Since all other platforms, such as
+Arduino, run on top of ESP-IDF, this code should be portable. The wiring for the
+reset is also done directly to the ESP's reset line, hence there is no code to
+reset the uLCD.
+
 == Code
 Code can be found at Advaith's personal Git server. The link is as follows:
 {link-repository}. To clone the repository, run `git clone
 git://git.devinivas.org/4dulcd-nolibrary.git`.
+
+== Basic Steps
+We do not cover the steps to initialize UART here, since these depend on the
+platform that the user chooses to use. We have abstracted the UART interface to
+four functions:
+
+* `write_tx(const void *data, size_t bufsz)`: Send `bufsz` data from the `data`
+  buffer via the TX line. Returns number of bytes sent.
+* `read_rx(void *data, size_t bufsz, uint32_t tout)`: Read `bufsz` data into the
+  `data` buffer, and limit to `tout` seconds. If it takes longer, this function
+  fails. Returns number of bytes read.
+* `flush_rx()`: Flush the receiving buffer.
+* `flush_tx(uint32_t timeout)`: Flush the transmit buffers. The operation times
+  out if it exceeds `timeout` seconds.
+
+The uLCD is a "big-endian" device. This means we send the most significant bit
+over UART.
+
+=== Initialization
+The EVE takes 3 seconds to boot up. This is the most reliable way to perform the
+boot wait - alternate methods, like sending a bunch of 'K's until we get an
+acknowledge are not reliable and can even cause irrepairable harm to the uLCDs
+in some cases.
+
+=== uLCD opcodes
+uLCD opcodes are 8 bits in length. These opcodes can be found at {link-spe}[the
+4D Systems documentation]. For example, the opcode for clearing the screen is
+`0xFFD7`, which means you send `0xFF`, then `0xD7`.
+
+Most opcodes (except the baud rate switch) return an acknowledge. This
+acknowledge can be obtained by reading one byte of data from the UART device,
+and this byte should be `0x06`.
+
+=== Demos
+The function `ulcd_txt_demo` demonstrates this process by writing a Hello World
+string to the first line and column. More demo functions will come soon.