(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

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:

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

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


Display HD44780-20x2 {
    Driver  'HD44780'
    Model   'generic'
    UseBusy  1
    Port    '/dev/parport0'	
    Size    '20x2'
    Wire {
	RW      'AUTOFD'
	RS      'INIT'
	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 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 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 [-c key=val] [-F] [-f config-file] [-i[i]] [-o output] [-q] [-v]
-c key=valoverwrite entries from the config-file (key and value have to be specified)
-Fdo not fork and detach (run in foreground)
-f config-fileuse configuration from 'config-file' instead of /etc/lcd4linux.conf
-ienter 'interactive mode' (after display initialisation)
-iienter 'interactive mode' (before display initialisation)
-o outputwrite picture to 'output' (raster driver only)
-qsuppress startup and exit splash screen
-vgenerate info messages
-vvgenerate debugging messages
-hprint version number and a small help text, then exit
-llist 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:

#! /bin/sh
# lcd4linux
test -f $DAEMON || exit 0
set -e
case "$1" in
	echo -n "Starting $DESC: "
	start-stop-daemon --start --quiet --pidfile /var/run/$ --exec $DAEMON
	echo "$NAME."
	echo -n "Stopping $DESC: "
	start-stop-daemon --oknodo --stop --quiet --pidfile /var/run/$ --exec $DAEMON
	echo "$NAME."
	start-stop-daemon --stop --signal 1 --quiet --pidfile /var/run/$ --exec $DAEMON
	echo -n "Restarting $DESC: "
	start-stop-daemon --stop --quiet --pidfile /var/run/$ --exec $DAEMON
	sleep 1
	start-stop-daemon --start --quiet --pidfile /var/run/$ --exec $DAEMON
	echo "$NAME."
	echo "Usage: $N {start|stop|restart|reload|force-reload}" >&2
	exit 1
exit 0

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:

2VCCsupply voltage +5V
3LCD_DRIVEcontrast voltage (0 .. +5V)
4RSRegister Select (low=instruction, high=data)
5R/WRead / not Write (high=read, low=write)
6ENABLEstarts data read/write
7DB0Data Bit 0
8DB1Data Bit 1
9DB2Data Bit 2
10DB3Data Bit 3
11DB4Data Bit 4
12DB5Data Bit 5
13DB6Data Bit 6
14DB7Data Bit 7
15BACKLIGHTbacklight supply voltage
16BL GNDbacklight ground

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:


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.ENABLE2   'GND'
Wire.GPO       'GND'

Wiring example:

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

LCDParallel PortPower Supplycontrast pot (10k)
Pin 1Pin 18GNDPin 1
Pin 2-+5VPin 3
Pin 3- Pin 2 (slider)
Pin 4Pin 16
Pin 5Pin 14
Pin 6Pin 1
Pin 7Pin 2
Pin 8Pin 3
Pin 9Pin 4
Pin 10Pin 5
Pin 11Pin 6
Pin 12Pin 7
Pin 13Pin 8
Pin 14Pin 9
Pin 15-100 ohm resistor to +5V
Pin 16-GND


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

Last modified 6 years ago Last modified on 10/04/10 03:29:31