LCDproc User's Guide The Ultimate Guide to LCDproc 0.4.3 Rene Wagner reenoo@gmx.de Copyright © 2002 by Rene Wagner Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". 0.0.1 --------------------------------------------------------------------------- Table of Contents Introduction About this Document What is LCDproc? The LCDproc Server - LCDd The LCDproc "Main" Client - lcdproc Other LCDproc Clients How to Obtain LCDproc Versioning Download Last Day's CVS Version of LCDproc as a Tarball Download The Latest Version of LCDproc from CVS apt-get Installation Build LCDproc Install LCDproc Directly From The Sources Generate And Install Packages of LCDproc LCDproc Configuration Configure LCDd LCDd.conf: The [server] Section LCDd.conf: The Drivers Section The LCDproc Init Scripts init-LCDd init-lcdproc LCDproc Drivers The HD44780 Driver Connections Compiling Running Miscellania The Matrix Orbital Driver (MtxOrb) Matrix Orbital LCD Modules Matrix Orbital Hardware Installation Copyright Running LCDproc Running LCDd Running LCDd from the command line The Command Line Options of LCDd Running lcdproc The Command Line Options of lcdproc Contact Us Errata The LCDproc Mailing List Reporting Bugs --------------------------------------------------------------------------- Introduction About this Document This document was meant as a tutorial for LCDproc users. It tries to introduce you into the world of LCDproc giving you an overview of the project. After reading this document you will be able to set up your own LCDproc'ed system. Note Please note that this document is still "under construction". We hope to finish it until the final release of LCDproc, which will probably take place in May or June 2002. If you run into any trouble feel free to write to the LCDproc mailing list. See http:// lcdproc.omnipotent.net/mail.php3 for details on how to subscribe to the list. This document was written for LCDproc 0.4.3. At the time of writing there had already been the "LCDproc User's Guide" written by William W. Ferrel in 1998. William's stuff is copyright © 1998, William W. Ferrel. His version covered an early version of LCDproc and therefore concentrated on Matrix Orbital displays. William's document was "recycled" for the description of the Matrix Orbital display driver and for other parts of this document. --------------------------------------------------------------------------- What is LCDproc? LCDproc is a client/server suite including drivers for all kinds of nifty LCD displays. The server 'LCDd' makes it possible to display text and other data on an LCD display. As well LCDd can handle certain input devices. Support for devices is added by drivers. We distinguish between output and input drivers. LCDd currently supports only one single output driver, which may at the same time handle input. Nevertheless several input (only) drivers are supported. Currently there are drivers for several serial devices: Matrix Orbital, Crystal Fontz, Bayrad, LB216, LCDM001 (kernelconcepts.de), Wirz-SLI and PIC-an-LCD; and some devices connected to the LPT port: HD44780, STV5730, T6963, SED1520 and SED1330. There are input (only) drivers for LIRC and joysticks. Clients can connect to LCDd through common sockets. Various clients are available. The "main" client lcdproc, which is shipped with the LCDproc distribution, can display things like CPU load, system load, memory usage, uptime, and a lot more. --------------------------------------------------------------------------- The LCDproc Server - LCDd LCDd is one of those well known *NIX daemons. BUT it's not just *one* daemon. It's the one that is supposed to drive your LCD ;) LCDd can either be run from the command line or automatically by the init scripts shipped with the distribution. As other daemons, LCDd has to be configured. In this respect a lot has changed since LCDproc 0.4.1. While LCDd retrieved all its configuration settings from the command line in 0.4.1, it now has a configuration file, which is normally /etc/LCDd.conf. --------------------------------------------------------------------------- The LCDproc "Main" Client - lcdproc While LCDd only offer the functionality of displaying text on a display, lcdproc actually retrieves data worth displaying. lcdproc gets its information from the /proc filesystem. lcdproc can connect to an LCDproc server either on the local system or on a remote system as long as it is reachable. It extracts the same statistics regardless of where it sends this information. The statistics it gathers include CPU utilization, memory utilization, disk utilization, network utilization, system uptime, time, and date, and so on. It displays this information in assorted ways, and can be tailored to taste. --------------------------------------------------------------------------- Other LCDproc Clients As it is rather simple to write an LCDproc client, you can find various clients on the Internet. Unfortunately we cannot provide a list of LCDproc clients (yet). So, have fun searching google or freshmeat. Simply type 'lcdproc' for the keyword. --------------------------------------------------------------------------- How to Obtain LCDproc Versioning At the time of writing there were four versions of LCDproc floating around on the Internet. LCDproc 0.4.1 LCDproc 0.4.1 was the last "stable" release of LCDproc. It still uses the old command line configuration. Warning There are known security problems with LCDproc 0.4.1. A remote exploit is possible. An attacker can make use of some buffer-overflows in the client communication code of LCDd, in order to get root access to your system. Therefore running LCDproc 0.4.1 is NOT RECOMMENDED! LCDproc 0.4.2 LCDproc 0.4.2 was meant to be the next stable release of LCDproc. As 0.4.1 it uses the old command line configuration. Note The known issues about 0.4.1 had been fixed. Unfortunately the guy who had the last pending patches on his box kind of "vanished" from the LCDproc mailing list. Of course you can get 0.4.2 from CVS. BUT its current state is unknown. LCDproc 0.4.3 LCDproc 0.4.3 will definitely be the next stable release of LCDproc. It no longer uses the old command line configuration, but introduces the configuration file /etc/LCDd.conf. As well the driver API has slightly changed, which should not make older drivers incompatible, but might cause some trouble. As well the way LCDd reports messages (including error messages) has changed. Note Even though LCDproc 0.4.3 is the most stable version we can offer, it is still under developement. There has been a "feature freeze" long time ago, but from time to time bugs are reported on the mailing list, which are of course fixed. We also work on porting drivers from 0.4.1 to 0.4.3 on demand. We do not have all the hardware LCDd supports. So, we only work on drivers that can be tested by YOU. LCDproc 0.5 LCDproc 0.5 is the developement version of LCDproc. Everything is possible ;) Drivers can already be loaded at runtime. We will also work on client supplied menus and other nifty stuff. Warning From time to time LCDproc 0.5 might not even compile due to drastic changes. You have been warned! Furthermore older drivers will NOT work with LCDproc 0.5 AT ALL! Feel free to port a driver that has not been ported to 0.5 yet ;) --------------------------------------------------------------------------- Download Last Day's CVS Version of LCDproc as a Tarball There are nightly distributions of the CVS branches of LCDproc. You can download them from http://lcdproc.sourceforge.net/nightly/ To extract the files run either $ tar xvfz lcdproc-CVS-*.tar.gz or $ bunzip2 -c lcdproc-CVS-*.tar.bz2 | tar xv --------------------------------------------------------------------------- Download The Latest Version of LCDproc from CVS Of course you can download the latest stuff from CVS via anonymous login. Create a "cvs" directory somewhere on your machine (not really neccessary but useful): $ mkdir ~/cvs $ cd ~/cvs Login to CVS: $ cvs -d:pserver:anonymous@cvs.lcdproc.sourceforge.net:/cvsroot/lcdproc login (Hit enter when prompted for a password.) Get the files from CVS: $ cvs -d:pserver:anonymous@cvs.lcdproc.sourceforge.net:/cvsroot/lcdproc checkout -r stable-0-4-3 lcdproc Once you've done that and want to update the downloaded files to the latest stuff you can use the "update" command of CVS (Make sure you have logged in to CVS first.): $ cvs -d:pserver:anonymous@cvs.lcdproc.sourceforge.net:/cvsroot/lcdproc update -r stable-0-4-3 lcdproc Now that you have downloaded the files you can prepare them for compiling, but first you should (you don't have to) copy them to another place on your machine: $ mkdir ~/lcdproc-cvs $ cp -f -R ~/cvs/lcdproc ~/lcdproc-cvs/`date +%Y%m%d` $ cd ~/lcdproc-cvs/`date +%Y%m%d` --------------------------------------------------------------------------- apt-get Debian GNU/Linux users can get the debian package of LCDproc, which is in the unstable and testing distributions. Provided apt-get is configured properly. You should be able to install the package running: $ su Password: top secret # apt-get install lcdproc --------------------------------------------------------------------------- Installation Build LCDproc Now that you have downloaded the LCDproc distribution you can start building it. Note If you have installed the debian package with apt-get (or another debian tool), you can skip this this chapter. If you're building this version from CVS, you'll need autoconf, automake, aclocal & autoheader installed. If you have autoconf and friends, run: $ sh autogen.sh This produces the configure script and supporting files. It has allready been run if you using the tarball distribution. Once the above command has run, the rest is pretty standard: $ ./configure --help Read about the options, figure out what to use. $ ./configure --prefix=/usr/local --enable-drivers=ncurses,cfontz Be sure to replace /usr/local with the prefixdir you want (e.g. /usr for RedHat) and ncurses,cfontz with comma-separated list of drivers you want. $ make Congratulations: You have just compiled your version of LCDproc ;) --------------------------------------------------------------------------- Install LCDproc Directly From The Sources If you want to install LCDproc more or less permanently you can run: $ su Password: top secret # make install Note make install is absolutely OPTIONAL You can also run LCDproc directly from the source directory. See below for details. --------------------------------------------------------------------------- Generate And Install Packages of LCDproc As an alternative (which is actually better ;) to installing directly from the sources you can generate packages using the packaging tool EPM. First of all you may need to download EPM from http://www.easysw.com/epm/ and install it according to the instructions that are included in its source distribution. Note There are of course other and maybe better ways to generate packages for your system. The reason for us to choose EPM was that it provide the developers with a tool that makes it possible to write one list file for all platforms defining what the resulting package is meant to look like. This way we do not have to learn all the package managing tools of the different platforms that are supported by LCDproc. To generate an LCDproc package follow these instructions: Tip It is of certain importance that you have run ./configure with the correct pathname settings for your system. Otherwise the resulting package will install the files in the wrong directories. $ epm -v -f native LCDproc Note Generating an RPM package as a non-root user will fail, RPM wants to generate the files from the tree under /usr/src/RPM, which you do not have write access to as a non-root user. If you want to generate the package as a non-root user anyway, you may want to follow these instructions. A workaround for the described problem is creating a file named ~ /.rpmmacros which contains: %_topdir ~/rpm Important ~/rpm must contain the same tree usually found under /usr/src/RPM Unfortunately epm does not read ~/.rpmmacros and of course returns warnings. Don't worry! That's OK ;) In order to actually install the generated package follow the instructions in your system's manual. --------------------------------------------------------------------------- LCDproc Configuration Configure LCDd As mentioned in the introduction LCDd, the LCDproc server, now (with version 0.4.3 of LCDproc) has its own configuration file, which is normally /etc/LCDd.conf. Note If you have not installed LCDproc from the sources the configuration file might have a different location. You should find it when making your system's package manager list all the files in the LCDproc package. The format of the /etc/LCDd.conf is ini-file-like. It is divided into sections that start at markers that look like [section]. Comments are all line-based comments, and are lines that start with '#' or ';'. The server has a 'central' section named [server]. Further each driver has a section which defines how the driver acts. Those sections start with [drivername]. The drivers are activated by specifiying them in a driver= line in the server section, like: Example 1. LCDd.conf: Specify which driver to use Driver=curses This tells LCDd to use the curses driver. The first driver specified here must be 'the' output driver. Currently LCDd will exit when several output drivers have been specified here. All extra drivers can only serve as input. The default driver to use is curses. Warning If LCDd is started automatically by an init-script using the curses drivers will lock /dev/tty1! So, be careful about what you are doing here. The drivers can read their own options from the config file, but most of them don't do this yet. They expect 'command-line'-format parameters that were previously placed on the command line. These parameters can be given to the driver in the following way: Example 2. LCDd.conf: Compatibility mode for drivers written for 0.4.1 Arguments="place arguments here" The arguments between the quotes are passed to the driver. As said before these are the same arguments that the driver would have been passed under the old command line format of LCDd -d driver "driverargs" Note The -d option still works, but does not allow driverargs any more. If -d is specified on the command line, the Driver= options in the config file are ignored. --------------------------------------------------------------------------- LCDd.conf: The [server] Section The [server] section of the LCDd.conf contains the settings for the LCDproc server LCDd. Driver= Tells the server which driver(s) to use. See above for details Note The default setting is Driver=none which makes the server exit right after the start. This is neccessary to avoid trouble with package installations. Bind= Tells the server to bind to the given interface. Default to Bind= 127.0.0.1 which is actually the safest variant. Port= Tells the server to listen to this specified port; defaults to 13666. ReportLevel= Sets the reporting level; defaults to 2 (warnings and errors only). ReportToSyslog= Should we report to syslog instead of stderr ? Defaults to no. WaitTime= Sets the default time in seconds to display a screen. User= User to run as. LCDd will drop its root privileges, if any, and run as this user instead. Defaults to User=nobody. Note If you want to use the server menu, to shutdown or reboot your system, you will have to set this to root. Otherwise LCDd does not have the privileges to run commands like init 6. ServerScreen= Enables the server screen even when other screens are active. Defaults to no. Foreground= The server will stay in the foreground if set to true. Otherwise the server will fork to background and report to syslog. Defaults to yes. --------------------------------------------------------------------------- LCDd.conf: The Drivers Section As mentioned earlier, each driver has its own section in the LCDd.conf. The settings are more or less self-explanatory. So, read through the section of your driver and change everything neccessary. --------------------------------------------------------------------------- The LCDproc Init Scripts The LCDproc distribution contains init scripts for RedHat- and Debian-based GNU/Linux distributions. You can find them in the docs/ directory of the LCDproc sources. Note The init scripts are generated using autoconf. So, again it is important that you have run ./configure with the correct options for your system. Refer to your system's manual on how to install the scripts. --------------------------------------------------------------------------- init-LCDd The file scripts/init-LCDd.* is the init script for the LCDproc server LCDd. It does not require modification. --------------------------------------------------------------------------- init-lcdproc The file scripts/init-lcdproc.* is the init script for the LCDproc "main" client lcdproc. As lcdproc does not (yet) have a configuration file you may want to modify the options that are passed to lcdproc. Note You can retrieve a listing of all options of lcdproc running lcdproc --help. Example 3. init-lcdproc.debian: Modify the option passed to lcdproc (Debian) start-stop-daemon --start --quiet --background --exec ${lcdproc} -- C In this example lcdproc will only send information on the CPU usage to the server. Example 4. init-lcdproc.rpm: Modify the option passed to lcdproc (RedHat) daemon ${lcdproc} C X & In this example lcdproc will only send information on the CPU usage [C] and system load [X] to the server. --------------------------------------------------------------------------- LCDproc Drivers This chapter contains the documentation of each LCDproc driver, which may include the installation process of the hardware as well as the configuration of LCDd. --------------------------------------------------------------------------- The HD44780 Driver There are several ways of wiring up the HD44780 devices. Your choice will probably be governed largely by your ability to wire up each one and/or a desire to use the device with other programs. The LCDproc HD44780 driver supports the following connections on a parallel port: * 4-bit * 8-bit (winamp style) * extended 8-bit (LCD + LED bargraph) * serial LPT And supports a PIC-an-LCD connected to a serial port. The driver also lets you use multiple displays as a single virtual display. For example, a 4, 2 and 1 line display can be used to form a 7 line display. The number of displays is limited by the individual HD44780 driver. --------------------------------------------------------------------------- Connections Common connections for all connectiontypes No matter what connectiontype you choose, you will always need some connections. They are explaned here. --------------------------------------------------------------------------- Power All variants use the same method of obtaining power. i.e., for each LCD: Table 1. HD44780: Power Connections +------------+------+-----------------------------------------------------+ | | | | +------------+------+-----------------------------------------------------+ | LCD | pin | signal | +------------+------+-----------------------------------------------------+ | | | | +------------+------+-----------------------------------------------------+ | 1 | GND | (connect to any of pins 18 - 25 of you parallel | | | | port) | +------------+------+-----------------------------------------------------+ | 2 | +5V | | +------------+------+-----------------------------------------------------+ | 3 | Vadj | (contrast) | +------------+------+-----------------------------------------------------+ | | | | +------------+------+-----------------------------------------------------+ Warning Always double check your power connection, your display will probably NOT survive a reversely connected supply ! There are several ways to get 5V: * Connect to a 5V line intented for disk drives (the red wire is 5V, black is GND). * Get it from a joystick port (pin 1 and 9 are 5V, 4, 5 and 12 are GND). It seems that some soundcards can use these lines for communication, so if you want to use this first check wether it really gives a 'clean' 5V. * If you don't have a backlight, you can sometimes get the needed mA's from the LPT port itself. Connect a few diodes from the data pins to a capacitor and you have the 5V. If it's strong enough is another question... * Get it from the keyboard connector. I do not recommend to use this with a backlight, as the keyboard connector is often protected with a fuse of 100mA or 200mA. (variable resistor) .------. Vcc ---| 10k |--- GND `---^--' /|\ | Vadj. Figure 1. HD44780: Connecting the contrast adjusting pin (Vadj.) --------------------------------------------------------------------------- Keypad You can connect a keypad with all connection types. The maximum supported number of keys differs per type. There are several ways to connect the keys to the input pins. --------------------------------------------------------------------------- Direct Keys If you connect a key like sketched below, then you can only connect one key per input pin. It is a simple solution if you need only few keys. O 5V | | - | | 10k | | - | +-----------o input (X) | | o \ o | | === GND Figure 2. HD44780: Direct Keys By default, the following keystrokes are generated by the different keys: Table 2. HD44780: Default Keystrokes +-------+-----+ | | | +-------+-----+ | X0 | A | +-------+-----+ | X1 | B | +-------+-----+ | X2 | C | +-------+-----+ | X3 | D | +-------+-----+ | | | +-------+-----+ --------------------------------------------------------------------------- Matrix Keys Using a matrix, we can connect much more keys. To simplify the drawing here, we replace all switches with an @ symbol: X line | | Y line ---+--------- | | | o | = --@-- \ | | o | | | +---+ | | Figure 3. HD44780: Single Matrix Key We connect the matrix of keys like this: Y0 o---|<---@--@--@ | | | Y1 o---|<---@--@--@ | | | Y2 o---|<---@--@--@ | | | Y3 o---|<---@--@--@ O 5V | | | | diodes | | | ___ | 1N4148 +----------|___|---+ | | | ___ | | +-------|___|---+ | | | ___ | | | +----|___|---+ resistors 22k | | | o o o X0 X1 X2 Figure 4. HD44780: Complete Key Matrix As you can see, you need 1 resistor per X line, and 1 diode per Y line. Lcdproc will presume that you have a keypad with a layout like a telephone connected, with X and Y lines connected as show. To be more precise, it assumes this: X0 X1 X2 X3 Y0 1 2 3 A Y1 4 5 6 B Y2 7 8 9 C Y3 * 0 # D Figure 5. HD44780: Keypad Layout If you only need 10 keys, leave the rest away. However, the lcdproc menu is controlled by the keystrokes A to D. You should modify and recompile the driver to get an other keypad layout. You can buy arrays of keys that are connected like this in the electronics shop. They usually call it a matrix keypad. To hook it to lcdproc, you would only need to add the resistors and diodes. If you want to use just one return line, for example with the serialLpt wiring, it looks (completely drawn) like this: O 5V | .-. | | 4k7 or 22k diodes | | 1N4148 '-' ___ | Y0 o---|<---o o---+ ___ | Y1 o---|<---o o---+ ___ | Y2 o---|<---o o---+ ___ | Y3 o---|<---o o---+----o return line Figure 6. HD44780: One Return Line Tip If the driver generates keypresses without that you actually press a key, it might be that the unconnected input lines are picking up electromagnetic waves from the air. In that case connect the unconnected input lines (pin 10, 11, 12, 13 and 15 of the LPT) to VCC = 5V. --------------------------------------------------------------------------- Backlight A small extension allows you to switch the backlight of the display on and off. At the moment only the 4bit and winamp connection types support this. The extension uses one output pin, you cannot use that pin for other functions anymore. The wiring looks like this: O 5V ___ | +---|___|---+ LPT Sub-D connector | 4k7 | | |e ___ | b |/ BL pin o------------|___|---+---------| 1k |\ bc327 |c | LCD connector | +--------o 15 backlight +--------o 16 GND backlight | === GND Note: 4k7 means 4,7 kohm. The BC327 transistor has the following connections: _____ | | |bc327| |_____| | | | | | | | | | c b e Figure 7. HD44780: Backlight Wiring Caution Sometimes the backlight connections are not on the 'main' connector, but on the side. If that is the case, there is usually NO RESISTOR present to limit the current through the LEDs. Therefor you should then add a resistor after the transistor of about 10 ohm (see display documentation). Tip If you want the backlight to light a bit while it's switched 'off', you can add a resistor bypassing the transistor from e to c, with a value of, say 47ohm or 22ohm. (My 4x20 has an internal resistor of 6ohm, so with 47 ohm extra it lights at only 1/9th. I like this. Joris.) --------------------------------------------------------------------------- 4-bit This is originally based on "lcdtext" (by Matthias Prinke). Table 3. HD44780: 4-bit Pinouts (1) +---------------------------+---------------------------------------------+ | | | +---------------------------+---------------------------------------------+ | printer port | LCD | +---------------------------+---------------------------------------------+ | | | +---------------------------+---------------------------------------------+ | D0 (2) | D4 (11) | +---------------------------+---------------------------------------------+ | D1 (3) | D5 (12) | +---------------------------+---------------------------------------------+ | D2 (4) | D6 (13) | +---------------------------+---------------------------------------------+ | D3 (5) | D7 (14) | +---------------------------+---------------------------------------------+ | D4 (6) | RS (4) | +---------------------------+---------------------------------------------+ | D5 (7) | RW (5) (LCD3 - 6) (optional - pull all LCD | | | RW low) | +---------------------------+---------------------------------------------+ | D6 (8) | EN (6) | +---------------------------+---------------------------------------------+ | D7 (9) | EN2 (LCD2 - 6) (optional) | +---------------------------+---------------------------------------------+ | | | +---------------------------+---------------------------------------------+ If you want to connect more than two displays to the parallel port then wire D5 (pin 7) to the enable line (pin 6) of the third LCD. Then for displays four to seven use: Table 4. HD44780: 4-bit Pinouts (2) +----------------+-------+ | | | +----------------+-------+ | printer port | LCD | +----------------+-------+ | | | +----------------+-------+ | STR (1) | EN4 | +----------------+-------+ | LF (14) | EN5 | +----------------+-------+ | INIT (16) | EN6 | +----------------+-------+ | SEL (17) | EN7 | +----------------+-------+ | | | +----------------+-------+ The optional keypad can be connected as follows: Table 5. HD44780: 4-bit Keypad Pinouts +-----------------+-------+ | | | +-----------------+-------+ | printer port | LCD | +-----------------+-------+ | | | +-----------------+-------+ | D0 (2) | Y0 | +-----------------+-------+ | D1 (3) | Y1 | +-----------------+-------+ | D2 (4) | Y2 | +-----------------+-------+ | D3 (5) | Y3 | +-----------------+-------+ | D4 (6) | Y4 | +-----------------+-------+ | D5 (7) | Y5 | +-----------------+-------+ | nSTRB (1) | Y6 | +-----------------+-------+ | nLF (14) | Y7 | +-----------------+-------+ | INIT (16) | Y8 | +-----------------+-------+ | nSEL (17) | Y9 | +-----------------+-------+ | | | +-----------------+-------+ | nACK (10) | X0 | +-----------------+-------+ | BUSY (11) | X1 | +-----------------+-------+ | PAPEREND (12) | X2 | +-----------------+-------+ | SELIN (13) | X3 | +-----------------+-------+ | nFAULT (15) | X4 | +-----------------+-------+ | | | +-----------------+-------+ The optional backlight wiring should be connected to D5, pin 7. --------------------------------------------------------------------------- 8-bit "Winamp" This type of connection should work with winamp. printer port LCD D0 (2) D0 (7) D1 (3) D1 (8) D2 (4) D2 (9) D3 (5) D3 (10) D4 (6) D4 (11) D5 (7) D5 (12) D6 (8) D6 (13) D7 (9) D7 (14) nSTRB (1) EN (6) nLF (14) nRW (5) (EN3 6 - LCD 3) (optional) INIT (16) RS (4) nSEL (17) EN2 (6 - LCD 2) (optional) Figure 8. HD44780: "Winamp" wiring If you want the display to work with the Winamp plugin, wire nLF (pin 14) to nRW of your LCD. You can then use the plugin in bidirectional mode (wich is much faster). With 3 connected LCDs this is not possible. Note from Benjamin: I haven't tried using winamp while having the third LCD connected to this line. The optional keypad can be connected as follows: printer port keypad D0 (2) Y0 D1 (3) Y1 D2 (4) Y2 D3 (5) Y3 D4 (6) Y4 D5 (7) Y5 D6 (8) Y6 D7 (9) Y7 nLF (14) Y8 INIT (16) Y9 nACK (10) X0 BUSY (11) X1 PAPEREND (12) X2 SELIN (13) X3 nFAULT (15) X4 Figure 9. HD44780: "Winamp" wiring - Keypad The optional backlight wiring should be connected to nSEL, pin 17. --------------------------------------------------------------------------- 8-bit "lcdtime" This is originally based on "lcdtime" (by Benjamin Tse ) and allows you to combine the LCD with a LED bargraph. The LCD is driven by LCDproc and the LEDs by another program such as portato. Further details can be obtained from: http://metalab.unc.edu/pub/linux/system/status/lcdtime-0.2.tar.gz http:// metalab.unc.edu/pub/linux/system/status/meter-0.2.tar.gz http:// metalab.unc.edu/pub/linux/system/status/portato-1.2.tar.gz Note Theoretically this wiring sends the data over twice as slow as the winamp or ext8bit wirings, because it only sends 4 bits at a time. The LCD connections are: printer port LCD D0 (2) D0 (7) D1 (3) D1 (8) D2 (4) D2 (9) D3 (5) D3 (10) D4 (6) D4 (11) D5 (7) D5 (12) D6 (8) D6 (13) D7 (9) D7 (14) nSEL (17) - nSTRB (1) RS (4) nLF (14) RW (5) (LCD2 - 6) (optional - pull all LCD RW low) INIT (16) EN (6) Figure 10. HD44780: "lcdtime" wiring See the lcdtime tar-ball (above) for full details of the bargraph connections. The optional keypad can be connected as follows: printer port keypad D0 (2) Y0 D1 (3) Y1 D2 (4) Y2 D3 (5) Y3 D4 (6) Y4 D5 (7) Y5 D6 (8) Y6 D7 (9) Y7 nSTRB (1) Y8 nSEL (17) Y9 nACK (10) X0 BUSY (11) X1 PAPEREND (12) X2 SELIN (13) X3 nFAULT (15) X4 Figure 11. HD44780: "lcdtime" wiring - keypad The backlight wiring should be attached to nSEL, pin 17. Because the portato program (mentioned above) also uses this pin to control the bargraph, you cannot use the backlight control together with the bargraph. --------------------------------------------------------------------------- Serial LPT This interface uses a handful of wires to interface to the HD44780. Suitable for high noise, long connections. Designed by Andrew McMeikan < andrewm@engineer.com>. The original wiring and driver can be found at: http://members.xoom.com/andrewmuck I (Joris) have extended this driver and the wiring a bit. It now supports keys again (it had earlier supported keys, but some time did not). Further I have extended the driver and the wiring to be able to run using 2 instead of 3 output pins. That's even one less pin ! :) Of course the use of fewer lines than the other wirings can not stay without drawbacks. In this case the simplicity of the long feeding wires is compensated by some intelligence in the decoding of the data. If you have no experience with the soldering iron, I do not recommend to build this wiring. OK, so here is the wiring. First of the 'simple' 3 wires version. IC1 is the shift register, a 4094. Do not forget to connect the 5V to pin 16 and GND to pin 8 of the IC. IC1 ----------- | 4094 | 5V | shift reg | display O | | /keys | 1| |3 +----|STR Q0|---------------------o 7 D0 | | |4 /Y0 Data | 2| Q1|---------------------o 8 D1 D3 5 o---------------------------|D |5 /Y1 | | Q2|---------------------o 9 D2 | 3|CK |6 /Y2 D4 6 o---------------------------| Q3|---------------------o 10 D3 | | |10 /Y3 | 15| Q4|---------------------o Y4 +----|OE |11 | Q5|---------------------o 4 RS | |12 /Y5 | Q6|---------------------o Y6 | |13 | Q7|---------------------o Y7 | |9 | QS|-- +--o 5 RW | __|10 | | QS|-- === | | ----------- D2 4 o-------------------------------------------------------------o 6 EN D7 9 o-------------------------------------------------------------o 6 EN2 (2nd LCD) 5V O-----+--------+----------------------------------+-----o 2 VCC | | | | | | |100n O 16 .-. --- IC1 | |<---o 3 Vlcd --- O 8 | |10k | | '-' GND | | | 18..25 o-----------+--------+--------------------------+-------+-----o 1 GND | === GND Figure 12. HD44780: Serial LPT wiring ('simple') The second possible wiring is with 2 output lines. This one is a bit more complex. If you do not understand the schematic, do not build it. IC2 ----------- | 74HCT164 | | shift reg | display | | /keys Data 1| |3 D3 5 o-----------------------+---|D Q0|---------------------o 7 D0 | | |4 /Y0 | 2| Q1|---------------------o 8 D1 +---|D |5 /Y1 | Q2|---------------------o 9 D2 | |6 /Y2 | Q3|---------------------o 10 D3 | |10 /Y3 Clock 8| Q4|---------------------o Y4 D4 6 o---------------------------|CK |11 | Q5|---------------------o 4 RS ___ 9|\ 8 9|_ |12 /Y5 +--|___|--+----| >o----|R Q6|---------------------o Y6 | 22k | |/ | |13 | --- IC1 | Q7|---+ +--o 5 RW | --- | | | 5V | | |100p ----------- | O === | | | | | === | .-. | | | |22k +--------------------------------------+ | | | '-' | ___ 11|\ 10 | 5|\ 6 +--|___|--+----| >o-------------------||----+-----| >o---o 6 EN 22k | |/ 22p |/ --- IC1 IC1 --- |22p | IC1=74HCT14 (6x Schmitt trigger inverter) === 5V O--+-------+------+------+------------------------+-----o 2 VCC | | | | 13|\ 12 | | | | +---| >o- | |100n O 14 O 14 |/ .-. --- IC1 IC2 | |<---o 3 Vlcd --- O 7 O 7 1|\ 2 3|\ 4 | |10k | | | +--| >o- +--| >o- '-' GND | | | | |/ | |/ | 18..25 o--------+-------+------+-------+----------+-----+------+-----o 1 GND | === GND Figure 13. HD44780: Serial LPT wiring ('complex') --------------------------------------------------------------------------- Serial LPT Keypad Note To understand this part of the serialLpt documentation, you also need to read the keypad section in this document. serialLpt wiring supports a keypad. The 3 wires version supports 8 keys, or if you use multiple return lines up to 8 x 5 = 40 lines. The 2 wires version supports 7 keys, or with multiple return lines 7 x 5 = 35 keys. nACK (10) X0 BUSY (11) X1 PAPEREND (12) X2 SELIN (13) X3 nFAULT (15) X4 Figure 14. HD44780: Serial LPT - Keypad return lines On lines longer than, say a meter, you should buffer the return line(s). If you only have 1 return line, you can buffer it with two remaining buffers from the 74HCT14: 1|\ 2 13|\ 12 ___ keypad o-----| >o------| >o---|___|---+---o input pin on LPT port return |/ |/ 220E | IC1 IC1 --- --- 1nF | === Figure 15. HD44780: Serial LPT - Keypad return lines buffered --------------------------------------------------------------------------- Serial LPT Backlight Also a backlight is suported. You will also need a port from the 74HCT14 for that. The BL output below should be connected to the BL input in the backlight section ___ 3|\ 4 Data o-----|___|--+----| >o----o BL output LPT-D3 470k | |/ --- IC1 --- |100nF | === Figure 16. HD44780: Serial LPT - Backlight extra circuit --------------------------------------------------------------------------- PIC-an-LCD serial device "picanlcd" The PIC-an-LCD module is also supported. It is not connected to the LPT port but to a serial port, which saves you from a lot of potential problems. To use it, specify the device to which you have connected the module in the config file with the Device= setting. The default is /dev/ lcd. It does not support a keypad nor backlight switching. --------------------------------------------------------------------------- Compiling Make sure that the HD44780 files are built when you run configure. This can be done by specifying "--enable-drivers=all" or by "--enable-drivers= hd44780". --------------------------------------------------------------------------- Running Modify the LCDd.conf file before you run LCDd. In this config file are detailed instructions on how to configure the HD44780 driver. Then as usual, start LCDd with the correct config file: E.g. LCDd -c ./LCDd.conf If you want to override the driver selection in LCDd.conf then use: LCDd -c ./LCDd.conf -d HD44780 If you use this, the HD44780 driver will read the options from the config file anyway. --------------------------------------------------------------------------- Miscellania This text has originally been taken from a message by Bill Farrow < bfarrow@arrow.bsee.swin.edu.au>. Updated February 2000, Benjamin Tse Updated October 2001, Joris Robijn Converted to docbook March 2002, Rene Wagner --------------------------------------------------------------------------- The Matrix Orbital Driver (MtxOrb) This section covers the installation process for the Matrix Orbital LCD module intended for use with LCDproc. We will examine the installation process of the hardware in small steps, as it is vitally important to pay close attention to detail during hardware installation to avoid damaging equipment. --------------------------------------------------------------------------- Matrix Orbital LCD Modules LCDproc was born out of original tinkering by William Ferrell with one of these LCD modules. Their ease of installation and use (as well as the amazing amount of patience demonstrated by the folks at Matrix Orbital whilst William figured things out) meant one less thing to worry about during the early stages of LCDproc's life. These 20x4 alphanumeric modules are connected via standard DB-9 cabling and connectors. They draw either 5V or 12V, depending on the module purchased, and are attached with a standard floppy cable connector (with a slightly modified wire configuration). Once connected, using them is a breeze. They can operate at any number of different baud rates and serial configurations, but normally they run at 19,200 baud, 8-N-1, making them quite quick. Sending ASCII to the module will make it simply display that text at its current cursor position. The module has a built-in BIOS that recognizes commands (sent by transmitting a single-byte "marker" signifying that a command is on the way, followed by the single-byte command character itself along with any parameters, if needed) allowing the programmer to clear the screen, position the cursor anywhere, define custom characters (up to 8 at a time), draw bar graphs and large numbers, change the LCD's contrast, and so on. The BIOS included also implements line-wrapping (i.e. writing past the twentieth character on the first row will automatically move the cursor to the first character on the second row), and screen scrolling (i.e. writing past the twentieth character on the fourth row causes the whole screen to scroll up one row, clearing the fourth line and positioning the cursor at the first character on that line). These modules are fast. Using the auto-line-wrap feature and disabling the auto-scrolling feature, the screen can be updated thirty times per second if *every* character on the screen is changed. If updating less than the whole screen, the LCD can update faster than can be seen by the human eye. This, of course, more than meets LCDproc's needs. --------------------------------------------------------------------------- Matrix Orbital Hardware Installation Regardless of what specific type of hardware you intend to use with LCDproc, installation is usually straightforward, and requires only a few steps. Regardless, you must use caution while working inside your computer system or with any hardware attachments. Warning Installing new hardware inside a computer system can be dangerous to both system components and the installer. Use caution whenever adding a component to the inside of your system, altering a power cable, or physically mounting a device inside a computer system. When installing hardware inside a computer, make sure it's turned off and that its power is disconnected. This is especially important when making changes to power cables (as some LCD modules require). --------------------------------------------------------------------------- Matrix Orbital LCD/VFD Module Installation The LCD and VFD modules from Matrix Orbital are relatively straightforward to install. With a small, regular (flat-head) screwdriver, a spare floppy drive power cable, and a bit of luck, installation will take less than an hour. These installation instructions assume that you are installing the module into a PC or PC-style system (one with AT- or ATX-compliant power cabling) and that you have some idea of where you intend to permanently mount the module. For mounting ideas and tips, refer to the section "Mounting" below. Tip Before you start Your Matrix Orbital LCD or VFD module should be clearly marked with an indication of the module's power requirements. It should be either a 5 volt or 12 volt unit. You should have this information available before proceeding. --------------------------------------------------------------------------- Power Cable Modification The first step in installing the module is making the necessary modifications to a floppy drive power cable in order to provide power to the module. The modifications must be made based on the module's power requirements -- either 5V or 12V -- depending on which module you purchased. A standard floppy drive power cable has a smaller connection than a "normal" PC power connector. However, like a "normal" power connector, it has four wires: one yellow, one red, and two black. The red wire provides +5V power, and is "hot" or live when the system is powered up. The yellow wire provides +12V power, and is also hot when the system is powered up. Both black wires are ground. [TODO: INCLUDE A FIGURE HERE SHOWING A "STANDARD" FLOPPY CONNECTOR] One of the hot wires and one of the black wires will not be needed for your module's power connection; they will be completely removed when the power cable modification is complete. Warning Do NOT make this modification to a power cable attached to a running system! Electrocution resulting in personal injury and/or damage to the system can result. Using a regular screwdriver, press down the small metal locking flap of one of the two black wires on the small end of the cable, and pull the black wire from the connector. Using a pair of needle-nose pliers, squeeze the other end of the same black wire, and pull it out of the large end of the cable. This black wire can be set aside; it will not be used for the module's power connection. Either wire can be safely removed; you may safely remove either wire. [TODO: INCLUDE A FIGURE HERE SHOWING THIS PROCESS] Next, using the same procedure, remove the unneeded hot wire. If your module is 5V, you do not need the yellow (+12V) wire. Conversely, if your module is 12V, you do not need the red (+5V) wire. The removed wire can be set aside; it will not be used for the module's power connection. [TODO: INCLUDE A FIGURE HERE] The floppy power connector should now have only two wires attached to it. Leave the larger end alone from now on; these connections are correct (the larger end connects to your system's power mains). Move the two remaining wires to the outside connectors on the small end of the cable. Orientation does not particularly matter here; the connector will fit on the module's receptacle in either orientation. [TODO: A FIGURE HERE] You should now have a properly modified power connector. When physically attaching this connector to the module, the black (ground) lead should be connected to the pin labelled GND, while the colored (+5V/+12V) lead should be connected to the pin labelled +5V/+12V. Test the power connection before connecting the data line or mounting the module. Connect the module to the power connector, and the connector to your system's power mains. Turn the system on. Caution If the module does not immediately display its initial BIOS screen and light up its backlight (or light up the screen if a VFD module is being used), immediately power down the system, disconnect the module and connector, and double-check the modification before trying again. Do NOT leave the system on if the module does not immediately respond; module or system damage could result. When the LCD powers up and displays its initial BIOS screen, you've gotten the power connection wired properly and can now properly mount the module and make its final connections. Matrix Orbital Corporation sells a PC bay insert mount for the 20x4 and 20x2 modules (LCDproc, however, only supports the 20x4 at present). The inserts provide an easy means of mounting the LCD modules inside a PC using one (for the 20x2) or two (for the 20x4) 5 1/4" bays. Note Describing how to physically mount the module in a PC case is beyond the scope of this document; LCDproc's website contains more detailed mounting information and examples. --------------------------------------------------------------------------- Serial Connection The LCD module uses a standard DB9 serial connector. You can attach the module to your system using a direct cable to the motherboard, or by removing one of your system's serial ports from the back of the case, then connecting it to a standard serial cable to the module. While connecting the serial cable to the module, be sure to configure the module's serial interface settings. Typically, setting the module to its fastest setting (19,200 baud, 8-N-1) is recommended. The speed settings can be configured from the config file /etc/LCDd.conf. If not specified in the config file, the Matrix Orbital module driver in LCDproc default to use these settings. --------------------------------------------------------------------------- Copyright This section was originally part of the lcdproc.sgml file by William W. Ferrell Slightly modified in order to include it in this document March 2002, Rene Wagner --------------------------------------------------------------------------- Running LCDproc Running LCDd If you have installed the init-scripts you can simply start, stop and restart LCDd with the init-script. --------------------------------------------------------------------------- Running LCDd from the command line There are several reasons for running LCDd from the command line * You don't want to install LCDd but run it from the source directory. * You want to do some debugging. * You want to get the output directly on stderr. * ... Note If you run LCDd as a "normal" user, it will not change to the user specified in the config file. For parallel port devices you will need root privileges anyway ;) The simplest command that will run LCDd is the following. It is useful for running LCDd from the source directory, e.g. after building. $ server/LCDd -c LCDd.conf --------------------------------------------------------------------------- The Command Line Options of LCDd Running LCDd -h gives you an overview of the currently available command line options, including a list of the compiled in drivers. Example 1. LCDd -h LCDd Server Daemon (part of lcdproc), 0.4.3dev Copyright (c) 1999 Scott Scriven, William Ferrell, and misc contributors This program is freely redistributable under the terms of the GNU Public License Usage: LCDd [ -hfiws ] [ -c ] [ -d ] [ -a ] \ [ -p ] [ -u ] [ -w