HD44780 improve docs, move code comments to README.md.

Author: peterhinch

HD44780/README.md

@@ -1,23 +1,74 @@
-# Driver for character-based LCD displays
+# 1. Driver for character-based LCD displays
 
 This driver is for displays based on the Hitachi HD44780 driver: these are
 widely available, typically in 16 character x 2 rows format.
 
-# Files
+# 2. Files
 
  * `alcd.py` Driver, includes connection details.
  * `alcdtest.py` Test/demo script.
 
-Currently most of the documentation, including wiring details, is in the code.
+# 3. Typical wiring
 
-# Display Formatting
+The driver uses 4-bit mode to economise on pins and wiring. Pins are arbitrary
+but this configuration was used in testing:
+
+| LCD  |Board |
+|:----:|:----:|
+|  Rs  |  Y1  |
+|  E   |  Y2  |
+|  D7  |  Y3  |
+|  D6  |  Y4  |
+|  D5  |  Y5  |
+|  D4  |  Y6  |
+
+# 4. LCD Class
+
+## 4.1 Constructor
+
+This takes the following positional args:
+ * `pinlist` A tuple of 6 strings, being the Pyboard pins used for signals
+ `Rs`, `E`, `D4`, `D5`, `D6`, `D7` e.g. `('Y1','Y2','Y6','Y5','Y4','Y3')`.
+ * `cols` The number of horizontal characters in the display (typically 16).
+ * `rows` Default 2. Number of rows in the display.
+
+## 4.2 Display updates
+
+The class has no public properties or methods. The display is represented as an
+array of strings indexed by row. The row contents is replaced in its entirety.
+This is illustrated by the test program:
+
+```python
+import uasyncio as asyncio
+import utime as time
+from alcd import LCD, PINLIST
+
+lcd = LCD(PINLIST, cols = 16)
+
+async def lcd_task():
+    for secs in range(20, -1, -1):
+        lcd[0] = 'MicroPython {}'.format(secs)
+        lcd[1] = "{:11d}uS".format(time.ticks_us())
+        await asyncio.sleep(1)
+
+loop = asyncio.get_event_loop()
+loop.run_until_complete(lcd_task())
+```
+
+The row contents may be read back by issuing
+
+```python
+row0 = lcd[0]
+```
+
+# 5. Display Formatting
 
 The driver represents an LCD display as an array indexed by row. Assigning a
 string to a row causes that row to be updated. To write text to a specific
 column of the display it is recommended to use the Python string `format`
 method.
 
-For exampls this function formats a string such that it is left-padded with
+For example this function formats a string such that it is left-padded with
 spaces to a given column and right-padded to the specified width (typically the
 width of the display). This ensures previous contents are overwritten.
 
@@ -34,5 +85,5 @@ def print_at(st, col, width=16):
 >>> 
 ```
 
-Similar use of the `format` method can be used to achieve more complex
+This use of the `format` method may be extended to achieve more complex
 tabulated data layouts.

HD44780/alcd.py

@@ -13,31 +13,16 @@
 #
 # Author : Matt Hawkins
 # Site   : http://www.raspberrypi-spy.co.uk
-# 
-# Date   : 26/07/2012
 
 from machine import Pin
 import utime as time
 import uasyncio as asyncio
 
-# **************************************************** LCD DRIVER ***************************************************
+# ********************************** GLOBAL CONSTANTS: TARGET BOARD PIN NUMBERS *************************************
 
-"""
-Pin correspondence of default pinlist. This is supplied as an example
-Name LCD connector Board
-Rs    4   1 red    Y1
-E     6   2        Y2
-D7   14   3        Y3
-D6   13   4        Y4
-D5   12   5        Y5
-D4   11   6        Y6
-"""
+# Supply board pin numbers as a tuple in order Rs, E, D4, D5, D6, D7
 
-# *********************************** GLOBAL CONSTANTS: MICROPYTHON PIN NUMBERS *************************************
-
-# Supply as board pin numbers as a tuple Rs, E, D4, D5, D6, D7
-
-PINLIST = ('Y1','Y2','Y6','Y5','Y4','Y3')
+PINLIST = ('Y1','Y2','Y6','Y5','Y4','Y3')  # As used in testing.
 
 # **************************************************** LCD CLASS ****************************************************
 # Initstring:
@@ -121,5 +106,3 @@ async def runlcd(self):                     # Periodically check for changed tex
                         await asyncio.sleep_ms(0)  # Reshedule ASAP
                     self.dirty[row] = False
             await asyncio.sleep_ms(20)          # Give other coros a look-in
-
-