
-------------------------------------------------------------------------------
    lcdtime ver 0.2             
    Copyright (C) 1995, 1997  Benjamin Tse 

    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.

-------------------------------------------------------------------------------

If you are already a user of lcdtime then you might want to skip
straight to the quickstart section near the end of this document.


What is lcdtime ?
=================

lcdtime is a modification to previous versions of LED status displays for
Linux. After implementing Joseph Vigneau's LED bargraph and seeing what
could be done with Brian Chase's meter, I decided to take it further.
lcdtime incorporates a LCD to the basic LED bargraph. The LED's still show
the system load and the LCD is used to display the time, amongst other things.

The first public release of lcdtime was in October 1995. Being bored
studying for exams I decided to document my interface, code and add
instructions. Almost two years later I'm in my final (hopefully :-))
year as an undergrad. After so long I've finally managed to sit down
and add some more functionality to the first iteration.


What's new ?
============

- lcdtime itself has been changed to display the month and day of the month
  as well as the time.
- Three new programs have been added:
    o sysload 	to display the system load
    o sysmem 	to display memory and swap space usage
    o lcdshift 	scrolls the display so more than the 16x2 character region
		is visible.

I've assumed that you have a 16x2 line lcd display. If you have something
else you may need to twiddle the code. (I know it seems like a hack,
but I haven't had time to make it more elegant.)


Putting it all together
=======================

Perhaps the hardest part is putting the hardware together. The basic circuit
is shown in lcd.ps: all you need is 8 x LED's (or a LED bargraph), a 74LS373
register, some resistors and capacitors, +5V dc supply and the LCD device.

Any LCD device with a Hitachi 44780 (or equivalent) controller will
do. I don't know how common these are to find overseas, but here in
Melbourne, Australia they are freely available (new) for around $40
each. Occasionally Jaycar Electronics in Melbourne sell second hand
displays for $10 - with the electroluminescent backlighting packages but
without the inverters for them. [Anyone have a spare inverter for me ? :-).]

The basic LCD device has a 5x7 array for each character and allows for
user definable characters. Be careful handling this device - in
particular watch out for static electricity. I like to touch something
that's grounded before fiddling with mine (I'm paranoid :-)). Also
make sure your soldering iron tip is earthed.

Hopefully the circuit diagram is self-explainatory. I put mine together on
a small piece of veroboard.

As for 5 volt supplies - you can use the game port (pins 8 or 15) or a spare
floppy drive cable. I use a 78L05 regulator configured as shown below. It
gives up to 100mA (the reason for the large LED current limiting resistors).
		       
		      .-------. 
    + o-----------+---| 78L05 |-----+------o +
    		  |   `-------'     |
7.5 - 12 V DC   +_|_220uF |       +_|_33uF    5 V
                 --- 16V  |        --- 10V
                  |       |         |
    - o-----------+-------+---------+------o -
			__|__
			 ---
			  ~

Make sure that you give your lcd the correct polarity ! Doing otherwise is
not good for your lcd - believe me, I know having learnt the hard way.

* A note on the parallel port: If you've got one of those new fangled
motherboards with the parallel port implemented in ASIC's, then double check
your connections. A simple short between the power supply and the parallel
port might wipe out just your parallel port (if you're lucky). Otherwise, it
might be your whole ASIC with its IDE controller et al. If you're unsure of
your connections you might as well just get a spare ISA parallel port card
(they shouldn't be too expensive these days).

Remember, this comes with no warranty, so I won't be held responsible should
you have to replace your motherboard. Don't let that deter you though !!


Installing the software
=======================

Get a copy of Brian Chase's meter from
ftp://sunsite.unc.edu/pub/Linux/system/Status/meter-0.2.tar.gz - this
isn't essential but you'll need it to make full use of the device. Then copy
meter.c from this file to the directory with the lcdtime files.

Or if you want to use Peter Heist's portato v1.2 (available in the same
directory as meter) instead, then copy portato.c to the lcdtime directory.

A "make meter all" or "make portato all" will apply a patch to meter
or portato (for the semaphore code) and compile these programs,
respectively. It will also create lcdtime.

If you don't plan to use either meter or portato then just type 
"make all".


Running
=======

Before running lcdtime, kill any previously running version of meter and run
the new patched version. Remember you must run these programs as root.

For lcdtime, simply execute lcdtime with the port address of your printer
port. Make sure that you use the patched version of meter with lcdtime
otherwise the output may be rather meaningless. 

The other programs, sysload, sysmem and lcdshift are pretty much run in
exactly the same manner. You can change the frequency of their updates via
the command line. 

* Note that sysload, sysmem and lcdshift assume that the lcd has been
initialized by lcdtime prior to their use.

Finally, you might want to execute the patched version of meter and
the lcdtime programs from /etc/rc.d/rc.local at boot-time.


The Future
==========

Thanks to all those who offered suggestions to the first version of lcdtime.
More suggestions are welcome !

Future (possible) work:
 - sysload, sysmem and lcdshift require prior initialization of the lcd
   with lcdtime. I have a better model in mind so that this is unnecessary.
 - a xload type display using the user definable characters of the lcd.
 - better distribution of lcd accesses amongst programs so that the impact
   on the LED bargraph is not so noticable (it doesn't seem so bad now ....).
 - code for other platforms (Win 95/NT) as I don't use Linux much these days.
 - a new interface using an ISA I/O card with 8255 chip. This appeared
   as a kit in Electronics Australia in 1996 ("24 Line I/O card"). Making 
   my own PCBs for PCs doesn't sound like much fun ....
 - photos of my actual display on my homepage (once I develop the photos).
   I've mounted the display and bargraph in my PC's case.

			  
Credits 
======= 

Thanks to:
 o Joseph Vigneau (joev@wpi.edu) for his led-stat.txt file which started all 
   of this.
 o damianf@wpi.edu for the port.h functions.
 o Brian D. Chase (chasebd@nextwork.rose-hulman.edu) for the meter program.
 o Peter Heist (heistp@rpi.edu) for his portato program.
 o Christopher Burian (cburian@uiuc.edu) for the LCD module FAQ.
 

QuickStart
==========

1 - put the hardware together and plug it in

2 - compile lcdtime and its companion programs with "make all". The code
    for meter and portato is unchanged from previous versions.

3 - kill off any currently running lcdtime.
    Run lcdtime as root with the appropriate printer port address.
    THEN run sysload, sysmem and lcdshift again with the printer port address.

    Note that sysload, sysmem and lcdshift all require the lcd to be
    initialized by lcdtime first.

4 - put the commands to run lcdtime, sysload, sysmem and lcdshift somewhere
    so that they get executed on startup - eg. /etc/rc.d/rc.local


The Author
==========

I can be contacted at the following addresses (in order of preference) most
months of the year: 
			blt@students.cs.mu.oz.au 
			blt@munagin.ee.mu.oz.au
			http://www.cs.mu.oz.au/~blt

Finally, this software is free, but this student would be grateful for
any offers of encouragement ... donations, job offers, backlit LCDs ... :-). 
(yeah right .... ha ha)

Have fun ! 
Benjamin Tse (25-Oct-1995, 18-Nov-1995, 15-Jul-1997)
