====== LCD4Linux-TUTORIAL ======

(based on lcd4linux 0.10.0)

LCD4Linux is a small program that grabs information from the kernel and some subsystems and displays it on an external liquid crystal display.

This tutorial is meant as a quick introduction and offers assistance with installing and configuring LCD4Linux.

----

===== INSTALLATION =====

**Installation from the sources: **

First you have to download the tarball from one of the sourceforge-mirrors, for example 

http://prdownloads.sourceforge.net/lcd4linux/lcd4linux-0.10.0.tar.gz?download

Then you have to unpack the tarball in a console window, thereby a directory named lcd4linux-0.10.0 is created: 

<code>
tar xvzf lcd4linux-0.10.0.tar.gz
</code>


After changing to the new directory with "cd lcd4linux-0.10.0", you have to compile the sources by using the following commands: 

<code>
./configure
make
make install        *)
</code>


Note: The usage of "./" with the configure-command is necessary, if the current directory is not included in the path.

During the execution of the configure-command (this may take a while!), some status messages are shown on the console. In case of errors you can look them up afterwards for debugging-purposes in the file configure.log.

The configure-command tries to find all necessary libraries and headers automatically and if they are lacking deactivates the according drivers. Unfortunately this is not always working reliably. If so, you can include the required driver manually:

<code>
./configure –-with-drivers=HD44780
</code>


You can get a list of available drivers with 

<code>
./configure --help
</code>


By default "make install" creates files under "/usr/local/bin", "/usr/local/lib", etc. 

*) in Debian a "checkinstall" is preferred to "make install". checkinstall will generate a deb package from the sources, which can be installed per "lcd4linux_lcd4linux-1_i386.deb" (this method eases a future deletion of the program).

**Installation from SVN (Subversion):**

In order to obtain access to the subversion repository, there must be installed a subversion client in your system first. If you want to use the most current version of LCD4Linux, you can access the subversion repository (read-only access):

<code>
svn co https://ssl.bulix.org/svn/lcd4linux/trunk lcd4linux
</code>


Therewith the directory "lcd4linux" containing the current version of the sources from SVN is created. To update the content (which you should do on a regular basis) use the following command:

<code>
svn up
</code>


After having fetched the newest files from svn, you have to compile the sources by using the following commands: 

<code>
./configure
./bootstrap
make
make install
</code>


(details see above)

----

===== CONFIGURATION =====

The config file **/etc/lcd4linux.conf** contains the configuration and layout of LCD4Linux. Starting with 0.10, the format changed a lot, and is now much more flexible.\\\

If you have installed LCD4Linux from the sources, it would be best to copy lcd4linux.conf.sample from the source directory to /etc/lcd4linux.conf and adapt it to your display.

Because of security reasons (the configuration may contain usernames/passwords for mail accounts) the config file is assured to have only the user's rights. Group or others must not read or write, otherwise LCD4Linux refuses to work! \\\

So if you run lcd4linux as root, /etc/lcd4linux.conf has to be: 

<code>
chmod 600 /etc/lcd4linux.conf
chown root.root /etc/lcd4linux.conf
</code>


**Example-Configuration: **

<code>
Display HD44780-20x2 {
    Driver  'HD44780'
    Model   'generic'
    UseBusy  1
    Port    '/dev/parport0'	
    Size    '20x2'
    Wire {
	RW      'AUTOFD'
	RS      'INIT'
	ENABLE  'STROBE'
	ENABLE2 'GND'
	GPO     'GND'
    }
}

Widget CPU {
    class      'Text'
    expression  uname('machine')
    prefix     'CPU '
    width       9
    align      'L'
    update      tick
}

Layout Default {
    Row1 {
        Col1 'CPU'
    }
}

Variables {
   tick 500
}

Display 'HD44780-20x2'
Layout  'Default'
</code>


The //Display// section set the display driver (in the given example a HD44780 display with 20x2 chars).\\\

The //Widget// sections define, what and how it is displayed. \\\

The //Layout// sections determine, which widget is displayed and where it is displayed. \\\

The //Variables// section specifies variables.\\\

The //Display// row defines the display to be used. \\\

The //Layout// row specifies the standard layout. \\\


In the above example there is shown the systems's CPU in the first row of the display. 

All configuration options are documented in detail in the [[:Manual|LCD4Linux-Manual]]. Furthermore the file lcd4linux.conf.sample contains some (commented out) sample configurations.

----

===== INVOCATION =====

The commands **"which lcd4linux"** and **"whereis lcd4linux"** show you the exact path to LCD4Linux.

For testing purposes LCD4Linux can be started with **"lcd4linux -Fvv"** (you don't need this options later on, if everything is working).

**LCD4Linux-Options:**

<code>
lcd4linux [[:-c|key=val]] [[:-F]] [[:-f|config-file]] [[:-i[i]]] [[:-o|output]] [[:-q]] [[:-v]]
</code>


|-c key=val|overwrite entries from the config-file (key and value have to be specified) |
|-F|do not fork and detach (run in foreground)|
|-f config-file|use configuration from 'config-file' instead of /etc/lcd4linux.conf|
|-i|enter 'interactive mode' (after display initialisation)|
|-ii|enter 'interactive mode' (before display initialisation)|
|-o output|write picture to 'output' (raster driver only)|
|-q|suppress startup and exit splash screen|
|-v|generate info messages|
|-vv|generate debugging messages|
|-h|print version number and a small help text, then exit|
|-l|list available drivers|

**Start automatically during boot:**

You have to create the startscript **"/etc/init.d/lcd4linux"** and generate the necessary runlevel entries by hand, e.g. with the command **"ln -s /etc/init.d/lcd4linux /etc/rc5.d/S99lcd4linux"**. 

Example for a startscript: 

<code>
#! /bin/sh
#
# lcd4linux
#
PATH=/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin
DAEMON=/usr/local/bin/lcd4linux
NAME=lcd4linux
DESC=lcd4linux
test -f $DAEMON | exit 0
set -e
case "$1" in
  start)
	echo -n "Starting $DESC: "
	start-stop-daemon --start --quiet --pidfile /var/run/$NAME.pid --exec $DAEMON
	echo "$NAME."
	;;
  stop)
	echo -n "Stopping $DESC: "
	start-stop-daemon --oknodo --stop --quiet --pidfile /var/run/$NAME.pid --exec $DAEMON
	echo "$NAME."
	;;
  reload)
	start-stop-daemon --stop --signal 1 --quiet --pidfile /var/run/$NAME.pid --exec $DAEMON
  	;;
  restart|force-reload)
	echo -n "Restarting $DESC: "
	start-stop-daemon --stop --quiet --pidfile /var/run/$NAME.pid --exec $DAEMON
	sleep 1
	start-stop-daemon --start --quiet --pidfile /var/run/$NAME.pid --exec $DAEMON
	echo "$NAME."
	;;
  *)
	N=/etc/init.d/$NAME
	echo "Usage: $N {start|stop|restart|reload|force-reload}" >&2
	exit 1
	;;
esac
exit 0
</code>


Alternatively you can invoke LCD4Linux within the file /etc/init.d/boot.local. 

----

===== HD44780 Wiring =====

95% of all trouble with displays connected to the parallel port are due to wrong wiring! There is no "standard", whereupon the wiring should be carried out. Thus LCD4Linux supports the so-called "soft wiring", which means that you can use (nearly) any wiring you like. You just have declare it in lcd4linux.conf. A HD44780 display typically has 16 connections (if only 14 are available, then the connections for backlight are missing). The connections have the following meaning: 

|**Pin**|**Name**|**Comment**|
|1|GND|ground|
|2|VCC|supply voltage +5V|
|3|LCD_DRIVE|contrast voltage (0 .. +5V)|
|4|RS|Register Select (low=instruction, high=data)|
|5|R/W|Read / not Write (high=read, low=write)|
|6|ENABLE|starts data read/write|
|7|DB0|Data Bit 0|
|8|DB1|Data Bit 1|
|9|DB2|Data Bit 2|
|10|DB3|Data Bit 3|
|11|DB4|Data Bit 4|
|12|DB5|Data Bit 5|
|13|DB6|Data Bit 6|
|14|DB7|Data Bit 7|
|15|BACKLIGHT|backlight supply voltage|
|16|BL GND|backlight ground|

The parallel port has 25 connections: 

|**Pin**|**Name**|**I/O**|
|1|STROBE|Out|
|2|DB0|I/O|
|3|DB1|I/O|
|4|DB2|I/O|
|5|DB3|I/O|
|6|DB4|I/O|
|7|DB5|I/O|
|8|DB6|I/O|
|9|DB7|I/O|
|10|ACK|In|
|11|BUSY|In|
|12|PAPEROUT|In|
|13|SELECT|In|
|14|AUTOFD|Out|
|15|ERROR|In|
|16|INIT|Out|
|17|SLCTIN|Out|
|18-25|GND|n/a|

The data lines (DB0..DB7 on the display, DB0..DB7 on the parallel port) are always connected directly (unless you are using the 4-bit mode - but that is intended for experts rather, and these are not reading this tutorial anyway :-). The interesting part is, how the display's control signal is connected with the 4 possible output lines from the parallel port: 

display: 

<code>
Pin 4: RS (Register Select)
Pin 5: R/W (Read/Write)
Pin 6: Enable
</code>


parallel port: 

<code>
Pin 1:  Strobe
Pin 14: AutoFD
Pin 16: Init
Pin 17: SelectIn
</code>


For each control line you have to specify, which signal of the parallel port is used. This is done by the "Wire.xy"-entries. 

E.g. if you are using the popular WinAmp wiring, it has to be defined like this: 

<code>
Display Pin 4 (RS)     => Parallelport Pin 16 (Init)
Display Pin 5 (R/W)    => Parallelport Pin 14 (AutoFD)
Display Pin 6 (Enable) => Parallelport Pin 1  (Strobe)
</code>


The adequate soft-wiring entries have to be: 

<code>
Wire.RW        'AUTOFD'
Wire.RS        'INIT'
Wire.ENABLE    'STROBE'
Wire.ENABLE2   'GND'
Wire.BACKLIGHT 'GND'
Wire.GPO       'GND'
</code>


==== Wiring example: ====

If you want to connect a standard HD44780 display to the parallel port using the WinAmp-Wiring, do it like the following:

|**LCD**|**Parallel Port**|**Power Supply**|**contrast pot** (10k)|
|Pin 1|Pin 18|GND|Pin 1|
|Pin 2|-|+5V|Pin 3|
|Pin 3|-| |Pin 2 (slider)|
|Pin 4|Pin 16| | |
|Pin 5|Pin 14| | |
|Pin 6|Pin 1| | |
|Pin 7|Pin 2| | |
|Pin 8|Pin 3| | |
|Pin 9|Pin 4| | |
|Pin 10|Pin 5| | |
|Pin 11|Pin 6| | |
|Pin 12|Pin 7| | |
|Pin 13|Pin 8| | |
|Pin 14|Pin 9| | |
|Pin 15|-|100 ohm resistor to +5V| |
|Pin 16|-|GND| |

----

===== TROUBLESHOOTING =====

**Problems when compiling:**

  * problems with user rights? install as root user 
  * error in configure.log? try different configure options

e.g. errormessage 

 <code>
#error "gd.h not found!"
make: *** [[:Raster.o]] Error 1
</code>


workaround: configure --with-drivers=all,\!PNG 

**Problems starting LCD4Linux:**

  * rights on /etc/lcd4linux.conf set correctly? 
  * is the display initialised when starting LCD4Linux? 
  * invoke LCD4Linux with the options "-Fvvq" and have a look at the debug-output 
  * check syntax in lcd4linux.conf 



----