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 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:

tar xvzf lcd4linux-0.10.0.tar.gz

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

./configure
make
make install        *)

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:

./configure –-with-drivers=HD44780

You can get a list of available drivers with

./configure --help

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):

svn co https://ssl.bulix.org/svn/lcd4linux/trunk lcd4linux

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:

svn up

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

./configure
./bootstrap
make
make install

(details see above)

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:

chmod 600 /etc/lcd4linux.conf
chown root.root /etc/lcd4linux.conf

Example-Configuration:

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'

The Display section set the display driver (in the given example a HD44780 display with 20×2 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 LCD4Linux-Manual. Furthermore the file lcd4linux.conf.sample contains some (commented out) sample configurations.

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:

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

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:

#! /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

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

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:

The parallel port has 25 connections:

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:

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

parallel port:

Pin 1:  Strobe
Pin 14: AutoFD
Pin 16: Init
Pin 17: SelectIn

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:

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)

The adequate soft-wiring entries have to be:

Wire.RW        'AUTOFD'
Wire.RS        'INIT'
Wire.ENABLE    'STROBE'
Wire.ENABLE2   'GND'
Wire.BACKLIGHT 'GND'
Wire.GPO       'GND'

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

Problems when compiling:

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

e.g. errormessage

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

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