**LCD4Linux-TUTORIAL**

(basierend auf lcd4linux 0.9.11)

LCD4Linux ist ein kleines Programm, das Informationen von Kernel und Subsystemen sammelt und auf einem externen Display ausgibt.

Dieses Tutorial ist für den Schnelleinstieg gedacht und soll eine Hilfestellung bei der Installation und Konfiguration von LCD4Linux bieten.

----

**INSTALLATION**

**Suse:**

Zuerst muss das zur Distribution passende rpm-Paket heruntergeladen werden:

http://prdownloads.sourceforge.net/lcd4linux/lcd4linux-0.9.11-8.i586.rpm?download

Die Installation erfolgt in der Konsole durch Aufruf des folgenden Befehls im Download-Verzeichnis:

 <code>
rpm -ivh lcd4linux-0.9.11-8.i586.rpm
 </code>


Folgende Dateien werden dadurch  installiert:

 <code>
/etc/init.d/lcd4linux
/etc/lcd4linux.conf
/usr/bin/lcd4linux
/usr/sbin/rclcd4linux
/usr/share/doc/packages/lcd4linux
/usr/share/doc/packages/lcd4linux/ChangeLog
/usr/share/doc/packages/lcd4linux/FAQ
/usr/share/doc/packages/lcd4linux/NEWS
/usr/share/doc/packages/lcd4linux/README
/usr/share/doc/packages/lcd4linux/README.Drivers
/usr/share/doc/packages/lcd4linux/README.KDE
/usr/share/doc/packages/lcd4linux/README.Rows
/usr/share/doc/packages/lcd4linux/README.Tokens
/usr/share/doc/packages/lcd4linux/TODO
/usr/share/doc/packages/lcd4linux/lcd4kde.conf
/usr/share/doc/packages/lcd4linux/lcd4linux.kdelnk
/usr/share/doc/packages/lcd4linux/lcd4linux.xpm
 </code>


Sollte sich das rpm-Paket nicht installieren lassen, bleibt noch immer der Weg über die Sourcen (Anleitung siehe weiter unten).

**Redhat:**

Grundsätzlich verwendet Redhat, wie Suse auch, das rpm-Format für die Paketinstallation. Allerdings unterscheiden sich die Distributionen in einigen wichtigen Punkten, daher sollte ein Suse-Paket nicht unter Redhat installiert werden. Es kann zwar manchmal funktionieren, wird es aber in den meisten Fällen nicht. Was LCD4Linux betrifft, gibt es noch keine diesbezüglichen Erfahrungen.
Nachdem kein spezielles Redhat-Installationspaket existiert, muss in diesem Fall direkt von den Sourcen installiert werden (Anleitung siehe weiter unten).

**Debian:**

Leider gibt es für Debian noch kein fertiges deb-Paket. Aus diesem Grund muss wie unter Redhat ebenfalls von den Sourcen installiert werden (Anleitung siehe weiter unten).
Es gibt möglicherweise auch einen (ungetesteten!) Umweg über das rpm-Paket, welches mit "**alien -c lcd4linux-0.9.11-8.i586.rpm**" in ein Debian-Paket umgewandelt und anschließend mit "**dpkg -i paketname.deb**" installiert werden kann. Allerdings kann nicht garantiert werden, dass das auch funktioniert.

**Gentoo:**

LCD4Linux ist ein offizielles Paket von Gentoo Linux: http://packages.gentoo.org/ebuilds/?lcd4linux-0.9.11

**Installation von den Sourcen:**

Zuerst muss das tar-Paket heruntergeladen werden:

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

Anschließend wird das Paket in der Konsole entpackt, dadurch wird ein Ordner namens **lcd4linux-0.9.11** angelegt:

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


Nachdem man mit "**cd lcd4linux-0.9.11**" in den neuen Ordner hineingewechselt ist, kompiliert man die Sourcen mit folgenden Befehlen:

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


Hinweis:
Die Angabe von "./" beim Configure-Befehl ist notwendig, wenn das aktuelle Verzeichnis nicht im Pfad ist.\\\

Während des Abarbeitens des Configure-Befehls (das kann eine Zeit lang dauern!), werden einige Status-Meldungen an der Konsole ausgegeben. Kommt es zu Fehlermeldungen, so sind diese zur Fehlersuche in der Datei **configure.log** nachzulesen.

Der Configure-Befehl versucht, automatisch alle benötigten Bibliotheken und Header zu finden und bei Nichtvorhandensein die entsprechenden Treiber zu deaktivieren. Leider funktioniert das nicht immer zuverlässig. In diesem Fall kann man auch manuell nur den benötigten Treiber einbinden:

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


Eine Liste der verfügbaren Treiber erhält man mit

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


Standardmäßig legt "make install" die Dateien unter "**/usr/local/bin**", "**/usr/local/lib**" etc. ab.

***)** unter Debian ist ein "**checkinstall**" einem "make install" vorzuziehen.
Dieses erzeugt aus den Sourcen ein deb-Paket, welches mit "**dpkg -i lcd4linux_0.9.11-1_i386.deb**" installiert werden kann und damit einen späteren Löschvorgang des Programms erleichtert.

**Installation über CVS (Concurrent Versions System):**

Um Zugriff auf das CVS-Repository zu erhalten, muss im System erst ein CVS-Client installiert werden.
Möchte man den aktuellsten LCD4Linux-Treiber verwenden, kann man diesen über einen anonymen Login installieren:

 <code>
cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/lcd4linux login
cvs -z9 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/lcd4linux co lcd4linux
 </code>


(die Passwort-Abfrage muss lediglich mit Enter bestätigt werden)

Damit wird ein Verzeichnis "lcd4linux" angelegt, das die aktuelle Version aus dem CVS enthält. Um den Inhalt zu aktualisieren, wechselt man in das Verzeichnis und gibt **"cvs -z9 update"** ein.

----

**KONFIGURATION**

Die Konfiguration von LCD4Linux erfolgt in der Datei **/etc/lcd4linux.conf**.\\\

Hat man von den Sourcen installiert, kopiert man am  besten die [[:Sample_09|lcd4linux.conf.sample]] aus dem Source-Verzeichnis nach /etc/lcd4linux.conf und passt diese an das betreffende Display an (es muss zumindest das Display, die Größe und der Port angegeben werden).

Aus Sicherheitsgründen darf die Datei lcd4linux.conf nur die Rechte des LCD4Linux-Benutzers haben, denn die Konfiguration könnte Benutzernamen/Passwörter für Mailaccounts beinhalten. Die Gruppe oder Andere dürfen nicht lesen und schreiben, sonst verweigert LCD4Linux den Dienst! \\\

Wenn das Programm als root gestartet wird, müssen die Rechte also folgendermaßen gesetzt sein:

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


**Beispiel-Konfiguration:**

<code>
Display HD44780
Port /dev/parport0
Size 20x4
Tick.Text 500
Tick.bar 100
Tick.icon 100
Row1 "*** %o %v ***"
Row2 "%p CPU %r MB RAM"
Row3 "Busy %cb%% $r10cs+cb"
Row4 "Load%l1%L$r10l1"
</code>


Die Display-Zeile legt fest, welcher Display-Treiber verwendet wird (im Beispiel ein HD44780-kompatibles Display).\\\

Die Port-Zeile legt fest, wo das Display angeschlossen  ist (im Beispiel am parallelen Port).\\\

Die Size-Zeile legt fest, wie viele Zeichen/Zeilen das Display besitzt (im Beispiel 20 Zeichen/4 Zeilen).\\\

Die Tick-Zeilen definieren, wie oft Text, Balken oder Icons aktualisiert werden.\\\

Die Row-Zeilen definieren, welche Informationen auf dem Display angezeigt werden. Sind keine Row-Einträge angegeben, werden sie mit Standardwerten belegt - möchte man z.B. eine leere erste Zeile haben, muss man also Row1 "" eintragen!

Im obigen Beispiel werden in der ersten Zeile der Name und die Version des Betriebssystems angezeigt, in der zweiten Zeile Informationen zu Prozessor und Hauptspeicher, in der dritten Zeile die CPU-Auslastung und in der vierten Zeile der Last-Durchschnitt.

Alle Konfigurationsoptionen sind im [[:Manual_09_de|LCD4Linux-Manual]] genau dokumentiert. Des weiteren sind in der Datei [[:Sample_09|lcd4linux.conf.sample]] schon einige Beispielkonfigurationen (auskommentiert) enthalten.

----

**AUFRUF**

Die Befehle "**which lcd4linux**" bzw. "**whereis lcd4linux**" zeigen die genauen Pfade zu LCD4Linux an.

LCD4Linux kann zum Testen mit "**lcd4linux -Fvv**" gestartet werden (die Optionen braucht man später nicht mehr, wenn alles funktioniert).

Hat man das rpm-Paket unter Suse installiert, kann man das Programm anschliessend mit "**rclcd4linux start**" aufrufen und mit "**rclcd4linux stop**" beenden.

**LCD4Linux-Optionen:**

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

<code>
'-c key=val'	   Einträge der Konfigurationsdatei überschreiben (Schlüssel und Wert angeben)
'-F'               Nicht als Dienst starten
'-f config-file'   Konfiguration aus 'config-file' holen statt aus /etc/lcd4linux.conf
'-o output'        Bild in Datei schreiben (nur Raster-Treiber)
'-q'               Begrüßungstext unterdrücken
'-v'               Ausgabe von Debug-Informationen
'-vv'              Ausgabe von mehr Debug-Informationen
'-vvv'             zusätzliche Debug-Informationen (Socket Traffic)
'-h'               Ausgabe der Versionsnummer und eines kurzen Hilfetextes
'-l'               Anzeige aller verfügbaren Treiber
</code>


**Automatisches Starten beim Booten:**

Hat man das rpm-Paket unter Suse installiert, kann man per Yast den Runlevel-Eintrag für LCD4Linux editieren, um LCD4Linux beim Booten automatisch aufzurufen.

Im anderen Fall legt man einen Startskript "**/etc/init.d/lcd4linux**" an und erzeugt die gewünschten Runlevel-Einträge händisch, z.B. mit "**ln -s /etc/init.d/lcd4linux /etc/rc5.d/S99lcd4linux**".

Beispiel für einen Startskript:

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


Alternativ könnte man den Aufruf von LCD4Linux auch in die Datei **/etc/init.d/boot.local** eintragen.

----

**TROUBLESHOOTING**

**Probleme beim Kompilieren:**

  * Berechtigungsprobleme? als root-Benutzer installieren
  * Fehler in der Datei configure.log? andere Configure-Optionen testen

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

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

**Probleme beim Aufruf:**

  * sind die Rechte auf /etc/lcd4linux.conf richtig gesetzt?
  * wird das Display beim Aufruf von LCD4Linux initialisiert?
  * LCD4Linux mit den Optionen "-Fvvq" aufrufen und Debug-Ausgabe verfolgen
  * Syntax in lcd4linux.conf kontrollieren

**Probleme mit der Verkabelung:**

95% aller Probleme bei Displays am Parallelport sind auf eine falsche Verkabelung zurückzuführen! Es gibt nämlich keinen "Standard", nach dem die Verkabelung ausgeführt werden soll. Deshalb unterstützt LCD4Linux das sogenannte "Soft-Wiring", d.h. man kann (fast) jede beliebige Verkabelung verwenden. Man muß diese nur in der lcd4linux.conf angeben.
Ein HD44780-Display hat normalerweise 16 Anschlüsse (sind nur 14 vorhanden, fehlen die Anschlüsse für die Hintergrundbeleuchtung). Diese haben folgende Bedeutung:

|**Pin**|**Name**|**Kommentar**|
|1|GND|Masse|
|2|VCC|Versorgungsspannung +5V|
|3|LCD_DRIVE|Kontrastspannung|
|4|RS|Register Select|
|5|R/W|Read/Write|
|6|ENABLE|Daten übernehmen|
|7|DB0|Daten Bit 0|
|8|DB1|Daten Bit 1|
|9|DB2|Daten Bit 2|
|10|DB3|Daten Bit 3|
|11|DB4|Daten Bit 4|
|12|DB5|Daten Bit 5|
|13|DB6|Daten Bit 6|
|14|DB7|Daten Bit 7|
|15|BACKLIGHT|Hintergrundbeleuchtung|
|16|BL GND|Hintergrundbeleuchtung|

Der Parallelport hat 25 Anschlüsse:

|**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|PAPER END|In|
|13|SELECT|Out|
|14|AUTOFD|Out|
|15|ERROR|In|
|16|INIT|Out|
|17|SLCTIN|In|
|18-25|GND|n/a|

Die Datenleitungen DB0 bis DB7 werden immer 1:1 miteinander verbunden (ausser man verwendet den 4-Bit-Modus - aber das ist eher etwas für Experten, und die lesen dieses Tutorial sowieso nicht :-).
Interessant ist jetzt, wie die Steuerleitungen vom Display mit den 4 möglichen Ausgängen vom Parallelport verbunden sind:

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


Parallelport:
 <code>
Pin 1: Strobe
Pin 13: Select
Pin 14: AutoFD
Pin 16: Init
 </code>


Für jede der Display-Steuerleitungen muß man angeben, welches Signal des Parallelports dafür verwendet wird. Dies geschieht mit Hilfe der "Wire.xy"-Einträge.

Wenn man z.B. die weitverbreitete WinAmp-Beschaltung verwendet, sieht das so aus:

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


Die dazupassenden Soft-Wiring-Einträge müssen lauten:

 <code>
Wire.RW "AUTOFD"
Wire.RS "INIT"
Wire.ENABLE "STROBE"
 </code>


Immer zusätzlich sollte folgender Eintrag vorhanden sein:

 <code>
Wire.ENABLE2 "GND"
Wire.GPO "GND"
 </code>


----