From 6186c333d98d40354143afb884093e04d47a7dfc Mon Sep 17 00:00:00 2001 From: Advaith Menon Date: Wed, 21 Jan 2026 10:36:50 -0500 Subject: [PATCH] Update README * Add info on current changes --- README.adoc | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/README.adoc b/README.adoc index 44b2071..109f2cd 100644 --- 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. -- 2.47.3