-------------------------------------------------------------------------------
    lcdtext V1.0             
    Copyright (C) 1997  Matthias Prinke

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

-------------------------------------------------------------------------------
0. What are these bytes about?
-------------------------------

In short:
lcdtext prints what you like on an LCD with Hitachi's HD44780 controller (which
seem to be very common) connected to an 8 bit wide port. The program prints and
exits- so you can use it under DOS, too.

In a few more words: 
   After I had mounted several hundreds of LCDs on microcontroller-PCBs for
controlling room climate at my part-time job, I wondered how these nice
two-lines, 16-characters-per-line displays are programmed.
I got a Philips datasheet of the LTN211, searched on the web and found several
FAQs about these very common LCDs with Hitachi's controller HD44780 and some
sample programs. www.paranioa.com/~filipg was my starting point.

   Then I found lcdtime-0.11 by Benjamin Tse, a linux program which displays 
the time on the LCD connected to a printer port. I first changed it to display
some machine infos (load average, memory used, swap space used, time and system
up time). Since I'm currently developing a simple PC IO-card, I decided to
change the software to operate the LCD in it's 4 bit-mode. So you can operate
it at a single 8 bit port (4 data-/adress- and 3 control lines). This piece of
software can be found as lcdstat.
   After I finished lcdstat, I thought "Hmm, not too bad, but when I'm using DOS
(which sometimes you can't help) the display is unused." Since I'm really no
programmer, I wrote a very simple program which only prints text on the LCD and
exits. This is what lcdtext does--something to put into autoexec.bat. Some 
people out they may be able to display something interesting in the background,
writing a TSR- not my job!!!

1. The hardware part
---------------------

   You do this on your own risk! I won't be held responsible if you blow up your
hardware, cause fire, get a shock or whatever.

1.1 Connecting the LCD to a printer port
-----------------------------------------

    LCD			 printer port
Pin	signal		Pin	signal

1	GND		18..25	GND
2	+5V		--- *)
3	Vadj.		--- *)
4	RS		6	D4
5	RW		7	D5
6	EN		8	D6
11	D4		2	D0
12	D5		3	D1
13	D6		4	D2
14	D7		5	D3	

Getting the supply voltage: 
   Use a floppy supply connector, get it from the game port, take some diodes
and a capacitor and get it from the port's data lines, get it from the keyboard
connector or whatever you like. Be save to avoid short circuit. You need only
3mA at 5V! (if you have the same type lcd)

Connecting the contrast adjusting pin (Vadj.):
     
     (variable resistor)   
        .------.	
 Vcc ---|  10k |--- GND
	`---^--'
           /|\
            |
          Vadj.

1.2 Connecting the LCD to an IO card
-------------------------------------

   I have connected my LCD to a selfmade PC IO card. I will publish both
schematic diagram and PCB layout as soon as I have made a redesign, because my
PCB has some patches (like any prototype, I think). It should be quite easy to
be build if you can solder and have the possibility to etch PCBs. There are no
special parts, only a handfull of TTLs. The LCD needs only a part of the board,
there are two 8 bit ports for additional hardware hacking. So watch out for a
file 'pcio' or something like that.

2. The software part
---------------------

2.1 Building the software
--------------------------

When you unpack the archive, you will get these files:
lcd4.c
		- the functions for controlling the LCD
lcd4.h
		- some definitions for lcd4.c
lcdtext
	- the linux executable
lcdtext.c	- the main program 
lcdtext.exe     - the DOS executable
makefile.dos	- makefile to use with DOS GCC (DJGPP)
makefile.lin	- makefile to use with Linux
port.h		- functions to write/read bytes to/from ports
README		- this text
COPYING		- GNU GPL

Linux: -make sure that DOS is _NOT_ defined in port.h and lcdtext.c
       -copy 'makefile.lin' to 'makefile'
       -just type 'make'
       
DOS:   -it's only tested with the DOS version of GCC, i.e. the package DJGPP
       -make sure that DOS is defined in port.h and lcdtext.c
       -copy 'makefile.dos' to 'makefile'
       -just type 'make'
       -there will be an executable named 'lcdtext' in coff format (to be run
        with go32) and an executable named 'lcdtext.exe' in exe format
       
I hope it works on your machine, too.

2.2 Running the software
-------------------------

Just type lcdtext with the desired options:

lcdtext [-p io_addr] [-t1 "first line"] [-t2 "second line"] [-h] [-v]

-p The port adress in hex. Strange thing: using Linux, I can type '0x378'
   while with DOS it has to be '378'. If not given, the default as given in
   lcdtext.c (0x378) is used.
-t1/-t2 Text for first resp. second line. If not given, the line will be
   cleared. *)
-h Give some help and information.
-v Print program name and port address that will be used to stderr.

*) This is how you get special characters, i.e. those which are not
   represented in 7 bit ASCII:
   Have a look at the LCD's character table. Look up the desired special
   character in the right half of the table. Look up the character 6 columns to
   the left, that is "value of desired character" - 128. Print this character
   preceded by '\+' on the command line.
   Example: You want the special character "a, , a-Umlaut.
            Just type \+a instead.
   Okay, I can think of better ways implementing this, but due to my lack of
   time (exams!!!) this works reasonable well with a minimum of code. But you
   can't get '\+' on the display now. And you can't get the full-block-character
   because the corresponding character is 'backspace'.
    
I hope I did the command line parsing right so that no bad things happen if you
type nonsense :-)

3. Credits
-----------

Thanks to:
* Benjamin Tse (blt@mundil.cs.mu.oz.au) for his package lcdtime. I took most of
  the code from him and then changed it.
* Joseph Vigneau (damian@wpi.edu) for port.h. I hope my change for DOS users
  will be of any use to others.
* filipg for his most interesting electronics homepage www.paranoia.com/~filipg
  where I found a link to lcdtime and many LCD FAQs
* The various authors of lcd relating FAQs, esp. Cristopher Burian's
  (cburian@uiuc.edu). I could have saved a lot of time if I had read this one
  before I tried to change to the 4 bit mode! Have a look at the accompanying
  chset.gif if you need any special characters.
* Linus Thorvalds and all others who contributed to Linux.

4. About me
------------

   I'm Matthias Prinke. If you use this software, found an error, want to 
improve my english, just want to say hello or have a LCD with backlight which
you would like to give me as a present please send email to one of these
addresses:

m.prinke@trashcan.mcnet.de (preferred)
m.prinke@tu-bs.de

Have fun! May The Force be with you!
