readme

LCD module driver

Hardware
--------
This is for a 20 x 4 character LCD display based on the Hitachi HD44780
controller. Additional displays with other geometries should be suppported by
editing "hardware.h" and setting LCD_COLS and LCD_LINES correctly. I just
have the 20x4 display so it is only tested for this. The display can easily
be wired to a standard PC parallel port.
Just connect the eight data bits to the eight inputs of the display plus
STROBE (pin 1 on 25 pin Sub-D) to EN (enable) and FEED (pin 14 on 25 pin
Sub-D) to RS (command-/datamode). You will also have to connect GND
to the read/write selector input. The driver does not need to read from the
display so we can hard-wire the write mode. Don't forget to add at least one
GND line. The 5V power supply for the display can easily be obtained from a
game-port adapter.

        25 pin		LCD
        SUB D		Panel	Pin
        ---------------------------
        		GND	1  --+--- \ Connect to
        		+5V	2  --|--- / Gameport
        		R/W	5  --+
        1		EN	6    |
        2		DB1	7    |
        3		DB2	8    |
        4		DB3	9    |
        5		DB4	10   |
        6		DB5	11   |
        7		DB6	12   |
        8		DB7	13   |
        9		DB8	14   |
        14		RS	4    |
        18-25		GND	   --+

Pin 3 on the LCD is the LCD driver control voltage input, i.e. contrast
regulation. My display shows very good contrast when I wire it directly to
GND. Other display may need a real driver current. You can use a
variable resistor (>= 100 Ohm) to do it like this

  +5V ---+
         /
         \ <--+
         /    |
         \    |
  GND ---+    +--- VL (Pin 3 - driver input)

The PC game port offers several +5V lines that can be used as power supply.
You can use
  DB15 pins 1,8,9 or 15 for +5V
            4,5 or 12   for GND

But please try to verify this for your hardware because some soundcards may
carry additional signals like a Midi port on those lines.


Installation / compilation
--------------------------
1. choose the correct definition for Kernel 2.0.* or Kernel 2.1.* (use
   -DKERNEL21 for Kernel 2.2.* too).
2. edit the port address of the used parallel port in 'hardware.h' !
3. choose the correct number of lines and columns in 'hardware,h' !


Now just type 'make' to build the module.

Create a character device major 120 minor 0, you may choose to use the
included script 'mkdevice' for this.

'insmod' the module without any options.

Device is initialized (set initial mode, clear display, turn display on)
when module is inserted. You should see an underline cursor not blinking in
the upper left corner.

Now just write text to the device, done ;)
German "Umlaut" characters are mapped correctly. Additional mappings can be
done in "c_table.h".

Valid ESC commands:
 ESC c   - Clear display
 ESC h   - Home cursor
 ESC R   - Reset display
 ESC #   - Define user definable char number #

Defining a character:
Characters are organized in 8 bits per row (!) with last three bits
ignored for displays with 5x7 fonts. My display can also use 5x8 fonts,
i.e. the characters may use the cursor line. A character is defined as

  D7----D0
  00011111
  00010000
  00010001
  00011111
  00010001
  00010000
  00010000
  00000000

which is something like a big F.
To define this character as char number 0 you will have to write the sequence

  27 0 31 16 17 31 17 16 16 0

to the LCD device (which is ESC-0-31-16-17-31-17-16-16-0).
You can do this from your shell using the echo command with the "-e" switch
like in
  echo -n -e "\33\0\37\20\21\37\21\20\20\0" > /dev/lcd
A subsequent
  echo -n -e "\0" > /dev/lcd
will print the new character. The "-n" just suppresses a trailing line-feed.

Terminal-like behaviour:
If during write cursor reaches the right most character the cursor is
positioned at the beginning of the next line.

Line-feed character (dec 10) causes the cursor to move to the beginning of
the next line.

Carriage-return (dec 13) causes the cursor to move to the beginning of the
current line.


Installation
------------
If you use something like kerneld, i.e. automatically load modules when
needed, you might want to copy the driver 'lcd.o' to your modules directory
and add the following line to your 'conf.modules'

  alias char-major-120 lcd

After that update your module's dependencies by doing 'depmod -a' and the
module should load automatically when /dev/lcd is accessed.


Testing
-------
You should have received some test programs with this package. After the
display is installed and the module is inserted correctly you should be able
to run them and see the output.
  test/
    type 'make' to build a program 'dtest'
    running './dtest' will at first display a sequence of "12345..." in
    every line so you can count the number of characters ;) After pressing
    a key the whole font is displayed filling the whole screen with one
    character each and going through all characters >=32.
  tools/scripts/
    nice - prints date, time and system-load every ten seconds
           a simple demo for a shell script
  tools/defchars/
    horbars - simple shell script that defines horizontal bargraph
              characters
    vertbars - simple shell script that defines vertical bargraph
               characters
    printchars - simple shell script that prints the eight user definable
                 characters
  tools/proclcd/
    proclcd - C program to print date, time and system load on the display
              (if you want something like do use 'proclcd' not 'nice')

Usual blah-blah
---------------
This driver is incomplete and may crash your machine.
Also wrong wiring may cause severe damage to the display and to your
computer.
The driver is free software but
  (c) Siegen (Germany) 1998,1999, by Nils Faerber
  GNU Public License applies


Thanks go to:
  Michael Engel - for getting me started with driver programming
  Graham Stoney - for testing another display and a small fix