Short Description
-----------------
This project implements a simple python interface to text based LCD
modules i.e HD44780 clones. 

The only dependancy is on 'pyparallel' which provides a python-wrapper
over the standard parallel-port. 

License
-------
GPL.

Author
------
Anupam Kapoor (anupam.kapoor@gmail.com)

Installation
------------
Following needs to be done to get all working (on linux)

    STEP-1 : Install pyparallel
    ===========================
            - download from :
              http://sourceforge.net/projects/pyserial/files/pyparallel/0.2/pyparallel-0.2.zip/download
            - setup.py from the above package is br0ken. comment out
              the 'package_data' section from 'setup(...)' call and you should
              be fine. 
                   
    STEP-2 : Load appropriate kernel modules
    ========================================
            - 'ppdev' is what is required to make it all work. if 'lp'
              is already loaded, then that needs to be unloaded (it
              takes over the parallel port)
                 # rmmod lp
              and then load ppdev
                 # modprobe ppdev
              just make sure that your user-id has write access to the
              device file i.e. '/dev/parpor0' that got created you
              modprobed 'ppdev' above.
              
    STEP-3 : Run it !
    =================
            - in the top-level directory just run 
                 $ python2.7 lcd.py
              to see something useful 
            

Code Organization
-----------------
The code is layered as follows:

    - pp_driver.py provides the parallel-port interface routines for
      following basic operations:
         - strobing 
         - executing a command
         - writing a data-byte

    - hd44780_driver.py provides an abstraction for interfacing with
      hd44780 text based lcd displays.

    - lcd_interface provides an abstraction for the set of
      functionality that are to be supported by a 'real' lcd device.

      actual implementation of this interface is provided in two
      places:
         - lcd_dummy provides a dummy implementation, and is ofcourse
           not very interesting.
           
         - lcd_4x20 provides an interface to the 4x20 (row, col) lcd
           displays. 

    - lcd_4x20 is the real deal and supports the interface exported by
      'lcd_interface'. a 'matrix-display' provides a convenient
      interface into an abstract display.

      the act of writing on the display is split into 2 parts i.e
      writing text/custom-characters on the matrix above, and then
      'flushing' the contents on to the actual display.

      a 'put_string' function provides a printf like interface for
      dumping contents on the display. similarly custom characters are
      dumped using 'put_shape'.

    - a page-like wrapper is also provided over the display via
      lcd_page. it provides to the users a notion of 'multiple-pages'
      of display.

      each page has it's own display function as well as custom
      shapes. custom shapes are loaded just before displaying the
      contents of a page.
      
    - currently there are 2 'pages' provided with followning
      functionality:

          - machine_info_page: provides machine specific information
            e.g. hostname, textual as well as 'bar-graph'
            representation of current cpu-usage and uptime.

          - personal_info_page: provides boring personal details of
            about the author.

Driver (hd44780_driver.py) Implementation Details
-------------------------------------------------
Interacting with HD44780 module is primarily done via writing
commands/data to the display module. 

In this implementation, a 'LCD_INSTRUCTION_TABLE' provides a
dictionary which maps 'COMMAND-NAMES' to 'COMMAND-VALUES'.

For a given command, the corresponding rows provide values for
different parallel-port pins. For example:

   - DISPLAY_CLEAR corresponds to the following
       [  RS,  R/W,  DB7,  DB6,  DB5,  DB4,  DB3,  DB2,  DB1,  DB0]
     - [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01]

which is pretty self explantory, however for the sake of completeness:
     - RS         == 0 i.e. C2 == Low (from pp_driver.py)
     - RW         == 0 i.e. a 'write' operation
     - DB1 - DB7  == 0x00
     - DB0        == 0x01
     
A common routine i.e. 'get_instruction_data' is the central point for
interfacing with 'LCD_INSTRUCTION_TABLE'.

Of the multitudinous hd44780 interfacing projects on the web, to the
best of my knowledge, I have not seen this approach being used
anywhere. 

This approach has a great advantage of self documenting most of the
lcd-interactions in the program. For example, resetting the lcd is
written as :
        ,----
        | def reset_lcd():
        |     exec_named_cmdseq(['DISPLAY_CLEAR',
        |                        'DISPLAY_OFF',
        |                        'DISPLAY_ON_CURSOR_ON_BLINK_ON',
        |                        'DISPLAY_PARAM_8BIT_2LINE_5x8DOTS',
        |                        'RETURN_HOME'])
        `----
which basically implies that resetting the display is done by
executing the following commands in sequence:
      - DISPLAY_CLEAR
      - DISPLAY_OFF
      - DISPLAY_ON_CURSOR_ON_BLINK_ON
      - DISPLAY_PARAM_8BIT_2LINE_5x8DOTS
      - RETURN_HOME

Shortcomings
------------
1. As of now, no support for reading values at a given address is 
   provided. This is mostly intentional, as data is written more often
   on a display, than read. 

   This unfortunately, precludes computation of delay-values (during
   strobing) programmatically.