-------------------------------------------------------------------------------
    lcdstat4 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:
   lcdstat4 prints some system information on an LCD with Hitachi's HD44780
controller (which seem to be very common) connected to an 8 bit wide port. The
program does an endless loop, so don't forget the ampersand.

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). Note: the first three values are percentages. 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 is what lcdstat4 does.

   There also is a program named lcdtext which prints text of your choice on
the LCD and exits. I did this, because I didn't like the LCD to stay clear if I
use DOS (which sometimes I can't help).  

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:
COPYING		- GNU GPL
Makefile	- guess what!
README		- this text
lcd4.c		- the functions for controlling the LCD
lcd4.h		- some definitions for lcd4.c
lcdstat.h	- functions used in lcdstat4.c
lcdstat4	- the executable
lcdstat4.c	- the main program
loadavg.c	- function to get average cpu load
memload.c	- function to get memory load (%)
port.h		- function to write/read bytes to/from ports
swpload.c	- function to get swap load (%)
uptime.c	- function to get system up time

Building the software:
Linux: -make sure that DOS is _NOT_ defined in port.h
       -just type 'make'
       
I hope it works on your machine, too.

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

Just type lcdstat4 with the desired options:

lcdtext [-p io_addr] [-v]

-p The port adress in hex. If not given, the default as given in
   lcdstat4.c (0x378) is used.
-v Print program name and port address that will be used to stderr.

You may wish to put a line like

lcdstat4 -p302 -v &

in your rc.local, but then don't forget the ampersand ('&') !

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!
