LCDproc User's Guide

The Ultimate Guide to LCDproc 0.5

Peter Marschall

Rene Wagner

Guillaume Filion

William W. Ferrell

0.0.6

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

Abstract

This document is a guide to LCDproc written for users. It covers LCDproc 0.5.x


Table of Contents

1. Introduction
About this Document
What is LCDproc?
The LCDproc Server - LCDd
The LCDproc "Main" Client - lcdproc
Other LCDproc Clients
2. How to Obtain LCDproc
Versioning
Download Yesterday's CVS Version of LCDproc as a Tarball
Download The Latest Version of LCDproc from CVS
apt-get
3. Installation
Build LCDproc
Install LCDproc Directly From The Sources
Generate And Install Packages of LCDproc
4. LCDproc Configuration
Configure LCDd
LCDd.conf: The [Server] Section
LCDd.conf: The [Menu] Section
LCDd.conf: The Driver Section
The LCDproc Init Scripts
init-LCDd
init-lcdproc
init-lcdexec
init-lcdvc
5. LCDproc Drivers
The bayrad Driver
Features
Configuration in LCDd.conf
The CFontz Driver
Configuration in LCDd.conf
The CFontz633 Driver
Configuration in LCDd.conf
The CFontzPacket Driver
Configuration in LCDd.conf
The curses Driver
Configuration in LCDd.conf
The CwLnx Driver
Features
Configuration in LCDd.conf
The ea65 driver
EA65 front panel VFD
Configuration in LCDd.conf
The Eyebox One Driver (EyeboxOne)
Eyebox One LCD Module
Eyebox One Driver and lcdproc client
Copyright
Configuration in LCDd.conf
The G15 Driver
Features
Configuration in LCDd.conf
The glcdlib Driver
Connections
Configuration in LCDd.conf
The glk Driver
Supported devices
Configuration in LCDd.conf
The HD44780 Driver
Connections
Compiling
Configuration in LCDd.conf
Miscellanea
The i2500vfd Driver
Features
Options
The icp_a106 Driver
Configuration in LCDd.conf
The imon Driver
General
Configuration in LCDd.conf
The imonlcd Driver
General
Configuration in LCDd.conf
The IOWarrior Driver
General
Requirements
Configuration in LCDd.conf
The irman Driver
Configuration in LCDd.conf
The irtrans Driver
General
Configuration in LCDd.conf
The Joystick Input Driver
Configuration in LCDd.conf
The lb216 Driver
Configuration in LCDd.conf
The lcdm001 Driver
Configuration in LCDd.conf
The lcterm Driver
Configuration in LCDd.conf
The lirc Driver
Checking Your LIRC Setup
Build LCDd with the lirc Driver
Configure LCDd to Use the lirc Driver
Configuration in LCDd.conf
Modify Your ~/.lircrc
The lis Driver
Features
Requirements
Configuration in LCDd.conf
The MD8800 Driver
Features
Configuration in LCDd.conf
The mdm166a driver
Configuration in LCDd.conf
Using the icons
Special device hints
The ms6931 Driver
Configuration in LCDd.conf
The mtc_s16209x Driver
Configuration in LCDd.conf
The MtxOrb Driver
Matrix Orbital LCD Modules
Matrix Orbital Hardware Installation
Configuration in LCDd.conf
The MX5000 Driver
Features
Configuration in LCDd.conf
The NoritakeVFD Driver
Configuration in LCDd.conf
The Mini-Box.com USB LCD picoLCD Driver
Displays
Requirements
Configuration in LCDd.conf
picolcd driver status
Copyright
The pyramid Driver
Features
Connector
Requirements
LED output
Configuration in LCDd.conf
The sed1330 Driver
Connections
Keypad
Configuration in LCDd.conf
The sed1520 Driver
Connections
Configuration in LCDd.conf
The serialPOS Driver
Connecting The Display
Configuration in LCDd.conf
The serialVFD Driver
Connecting The Display
Configuration in LCDd.conf
The shuttleVFD Driver
Features
Configuration in LCDd.conf
The sli Driver
Configuration in LCDd.conf
The stv5730 Driver
Configuration in LCDd.conf
The SureElec Driver
Configuration in LCDd.conf
The svga Driver
Configuration in LCDd.conf
The Toshiba T6963 Driver
Connections
Compiling
Configuration in LCDd.conf
The text Driver
Configuration in LCDd.conf
The tyan Driver
Features
Configuration in LCDd.conf
The ula200 Driver
General
Requirements
Known problems
Implementation note
Configuration in LCDd.conf
The xosd Driver
Configuration in LCDd.conf
Parallel Port Troubleshooting
Check The Wiring
Power Source Unregulated / Noisy
Ground Lift
Latchup
Contrast
Parallel Port Voltage
Enable Signal Rise Time
EMI
One or Two Black Lines
Software Too Fast
LED Backlight
HD44780 Compatible
Miscellanea
6. Running LCDproc
Running LCDd
Running LCDd from the command line
The Command Line Options of LCDd
Running lcdproc
The Command Line Options of lcdproc
7. Contact Us
Errata
The LCDproc Mailing List
Reporting Bugs
A. GNU Free Documentation License
PREAMBLE
APPLICABILITY AND DEFINITIONS
VERBATIM COPYING
COPYING IN QUANTITY
MODIFICATIONS
COMBINING DOCUMENTS
COLLECTIONS OF DOCUMENTS
AGGREGATION WITH INDEPENDENT WORKS
TRANSLATION
TERMINATION
FUTURE REVISIONS OF THIS LICENSE
How to use this License for your documents

List of Figures

5.1. HD44780: Connecting the contrast adjusting pin (VLC)
5.2. HD44780: Direct Keys
5.3. HD44780: Single Matrix Key
5.4. HD44780: Complete Key Matrix
5.5. HD44780: One Return Line
5.6. HD44780: Backlight Wiring
5.7. HD44780: Serial LPT wiring ('simple')
5.8. HD44780: Serial LPT wiring ('complex')
5.9. HD44780: Serial LPT - Keypad return lines buffered
5.10. HD44780: Serial LPT - Backlight extra circuit
5.11. HD44780: PCF8574P port expander on I2C bus
5.12. HD44780: ethlcd - block diagram
5.13. serialVFD: Serial Inverter

List of Tables

5.1. HD44780: Power Connections
5.2. HD44780: Direct Key Mapping
5.3. HD44780: Matrix Keypad Layout
5.4. HD44780: 4bit Pinouts (1)
5.5. HD44780: 4bit Pinouts (2)
5.6. HD44780: 4bit Keypad Pinouts
5.7. HD44780: "Winamp" wiring
5.8. HD44780: "Winamp" wiring - Keypad
5.9. HD44780: "lcdtime" wiring
5.10. HD44780: "lcdtime" wiring - keypad
5.11. HD44780: Serial LPT - Keypad return lines
5.12. HD44780: 8bit FTDI
5.13. HD44780: 4bit FTDI
5.14. HD44780: Examples of I2C port expander addresses
5.15. Mapping between LCDproc keys and IrMan commands
5.16. mdm166a_output bitmask
5.17. USB Pinout
5.18. Mapping of output bits to LEDs
5.19. ConnectionType classic ordered by LPT port pins
5.20. ConnectionType bitshaker ordered by LPT port pins
5.21. SED1520 80-style wiring schematic
5.22. SED1520 68-style wiring schematic
5.23. serialPOS: Emulation Protocol Status
5.24. serialVFD: Display Status
5.25. T6963 wiring schematic

List of Examples

4.1. LCDd.conf: Specify which driver to use
5.1. HD44780: Configuration for FTDI 4bit
5.2. HD44780: Configuration for LCD2USB
5.3. HD44780: Configuration for I2C with port expander
5.4. LCDd.conf: Activate the lirc driver
5.5. ~/.lircrc: Specify the associations from buttons to keys for the lirc driver
5.6. Matrix Orbital: keymap config
5.7. Pyramid: How to use the LED output from the client
6.1. LCDd -h
6.2. lcdproc -h

Chapter 1. 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 ⌣. 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.

Therefore you might want to have a look at http://lcdproc.sourceforge.net/docs/, to get the latest version of this document (unless you want to generate it yourself from the docbook files in the CVS).

This document was originally written for LCDproc 0.4.3, but has been dramatically updated since. At the time of writing there had already been the "LCDproc User's Guide" written by William W. Ferrel in 1999. 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.

In several other places e-mails and other documents have been included in this document. The authors of those are listed below every such 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 TCP 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 here. So, take a look at the Clients page on LCDproc's web site or have fun searching Google or freshmeat. Simply use lcdproc as the search pattern.

Chapter 2. How to Obtain LCDproc

Versioning

At the time of writing the following majors versions of LCDproc are floating around on the internet:

LCDproc 0.5.3

LCDproc 0.5.3 is the current stable version of LCDproc. This is the version recommended to use.

LCDproc 0.5.2

LCDproc 0.5.2 is an old stable version of LCDproc. It now has been superseded with LCDproc 0.5.3.

LCDproc 0.5.1

LCDproc 0.5.1 is an old stable version of LCDproc. It was the second stable version of LCDproc after the move to the 0.5 API.

Download Yesterday'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

$ tar xvfz lcdproc-CVS-*.tar.gz

Download The Latest Version of LCDproc from CVS

Of course you can download the latest stuff from CVS via anonymous login.

Login to CVS:

$ cvs -d:pserver:anonymous@lcdproc.cvs.sourceforge.net:/cvsroot/lcdproc login

(Hit enter when prompted for a password.)

Get the files from CVS:

$ cvs -d:pserver:anonymous@lcdproc.cvs.sourceforge.net:/cvsroot/lcdproc checkout -r stable-0-5-x 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 to be in the lcdproc directory.):

$ cvs update -d

Now that once 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.

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

Chapter 3. 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 package management tool), you can skip this this chapter.

If you're building this version from CVS, you'll need autoconf, automake, aclocal and autoheader installed.

If you have autoconf and friends, run:

$ sh autogen.sh

This produces the configure script and supporting files. It has already been run if you are 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=curses,CFontz

Be sure to replace /usr/local with the prefixdir you want (e.g. /usr for RedHat) and curses,CFontz with the comma-separated list of drivers you want to have compiled.

$ 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.epmhome.org/ and install it according to the instructions that are included in its source distribution.

Debian users (who do not want to download the official lcdproc debs via apt-get) can of course use Debian's epm package:

# apt-get install epm

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.

Chapter 4. LCDproc Configuration

Configure LCDd

As mentioned in the introduction LCDd, the LCDproc server, has its own configuration file, which is usually /etc/LCDd.conf.

Note

If you have not installed LCDproc from the sources the configuration file might have a different location. You should be able to find it by 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 declarations that look like [section]; i.e. an opening square bracket, followed by the section name, and terminated by a closing square bracket, on a line by itself. Section names are case insensitive.

Parameters are grouped into sections and have the form key=value; i.e. a key, also known as the configuration option, followed by an equality sign and finally the value for the option. All three elements must occur together on one line. The key, which is case insensitive, may be surrounded by spaces, but is must be one word (i.e. a sequence of non-space characters) not containing the equality sign. A similar rule applies to the value: it may be surrounded by spaces, but it must be either one word or enclosed within double quotes ("), which are not considered as part of value. When quoted, the following character sequences are evaluated as in literal C strings:

escape sequencecharacter
\aalert (bell) character
\bbackspace
\fformfeed
\nnewline
\rcarriage return
\thorizontal tab
\vvertical tab
\\backslash

All other occurrences of \ within quoted values will be ignored.

Comments are all line-based, and may start with '#' or ';'. Everything including and behind the character starting the comment up to the end of the line is ignored.

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 specifying them in a Driver= line in the server section, like:

Example 4.1. LCDd.conf: Specify which driver to use

[Server]
Driver=curses

This tells LCDd to use the curses driver.


The drivers read their own options from the config file. For this purpose they use the config sections that are named like the driver.

LCDd.conf: The [Server] Section

The [Server] section of the LCDd.conf contains the settings for the LCDproc server LCDd.

DriverPath = DRIVERPATH

Tells the server where to look for the driver files. See above for details. If not specified DRIVERPATH defaults to the empty string, resulting in drivers being searched in the directory LCDd is started in.

Driver = DRIVERNAME

Tells the server which driver(s) to use. The first driver specified here that is capable of output functionality will be used as the master output driver, defining display properties and capabilities. All other drivers specified can only serve as input drivers or slave output drivers. If not specified DRIVERNAME defaults to curses, a driver that is supposed to work on any half-way decent UNIX console.

This setting can be overridden on LCDd's command line using the -d DRIVER option. When the command line option is used, only the one driver given there will be loaded, and all drivers specified in the configuration file are ignored.

Bind = ADDRESS

Tells the server to bind to the given local IP address and listen for incoming client connections. The default value for ADDRESS is 127.0.0.1, which is actually the safest variant, as it allows connections only from the local machine and forbids connections from remote systems.

This setting can be overridden on LCDd's command line using the -a ADDRESS option.

Port = PORTNUMBER

Tells the server to listen to this specified port. If not specified PORTNUMBER defaults to 13666.

This setting can be overridden on LCDd's command line using the -p PORTNUMBER option.

ReportLevel = LEVEL

Sets the reporting level. Legal values for LEVEL range from 0 (only critical errors) to 5 (everything including debugging information). If not specified it defaults to 2 (warnings and errors only).

This setting can be overridden on LCDd's command line using the -r LEVEL option.

ReportToSyslog = { yes | no }

Should we report to syslog (yes) instead of stderr (no)? Default value is no.

This setting can be overridden on LCDd's command line using the -s NUMBER option. Passing -s 1 on the command line enables reporting to syslog while -s 0 disables it.

Warning

If LCDd is started automatically by an init script using the curses driver, it will lock /dev/tty1! So, be careful about what you are doing here.

User = USER

User to run as. When started as root LCDd will drop its privileges, and run as USER instead. Defaults to nobody.

This setting can be overridden on LCDd's command line using the -u USER option.

Foreground = { yes | no }

The server will stay in the foreground if set to true. Otherwise the server will fork to background and report to syslog. Defaults to no.

This setting can be overridden on LCDd's command line with the -f option that forces foreground mode.

Hello = HELLOMSG

Define the startup message printed on the screen when LCDd starts. This message will stay on the screen until the first client connects. If not given, it defaults to the built-in server screen that tells how many clients are connected and how many screens these clients are using in total. If it is given, each Hello= directive represents a line on the display.

The HELLOMSGs will be printed on the display one after each other starting on the beginning of each line. So, the definition of

        Hello="   Welcome to"
	Hello="    LCDproc!"
      

prints a nice 2-line welcome message to the display.

To simply disable the default built-in server screen on startup, and start with a blank screen a single Hello="" is sufficient.

GoodBye = GOODBYEMSG

Define the message left on the screen when LCDd exits. If not given, it defaults to the built-in Thanks for using LCDproc!. If it is given, each GoodBye= directive represents a line on the display.

The GOODBYEMSGs will be printed on the display one after each other starting on the beginning of each line. So, the definition of

        GoodBye="       So Long,"
        GoodBye="         and"
        GoodBye="Thanks for All the Fish!"
      

prints the well known dolphin's message on the first 3 lines of the display (which obviously needs to be 24 columns wide to show the full last line).

To simply disable the default built-in message, and leave the screen blank a single GoodBye="" suffices.

WaitTime = SECONDS

Sets the default time in seconds to display a screen. If not specified the default value for SECONDS is 4.

This setting can be overridden on LCDd's command line with the -w SECONDS option.

AutoRotate = { yes | no }

If set to no, LCDd will start with screen rotation disabled. This has the same effect as if the ToggleRotateKey had been pressed. Rotation will start if the ToggleRotateKey is pressed.

Note

This setting does not turn off priority sorting of screens. Therefore the client or LCDd may still show a different screen if it assigns it a higher priority than any other screen. Due to the way priority sorting works the screen shown when the first client connects may not be that clients first screen. If the client sets up more than two screens it will be the next to last one (this is not considered a bug).

ServerScreen = { yes | no | blank }

Control the behaviour of the server screen, that usually shows the number of active clients and screens. When set to its default value yes, the server screen is included into the screen rotation scheme when other screens exist. Whet set to no, the server screen only shows up when no other screen exists. The special value blank is similar to no, but instead of displaying the current number of clients and screens, only a blank screen is displayed.

This setting can be partially overridden on LCDd's command line using the -i NUMBER option. Passing -i 1 on the command line enables server screen rotation, while -i 0 disables it.

Note

Using the command line, it is not possible to set the server screen to blank mode.

Backlight = { off | open | on }

Set the master backlight setting. If set to the default value open, then the backlight setting of the display can be influenced by the clients. When set to off or on, the backlight is set to the appropriate value without the clients being able to change the value.

Heartbeat = { off | open | on }

Set the master heartbeat, the oscillating icon in the top right corner of the display, setting. If set to the default value open, then the heartbeat setting of the display can be influenced by the clients. When set to off or on, the heartbeat is turned on or off without the clients being able to change the value.

TitleSpeed = SPEED

Set the speed how fast over-long title lines shall scroll. Legal values are 0 to 10, where 0 means that no scrolling takes place and 10 stands for fastest scrolling. Default is 10, where no artificial delay is inserted.

The …Key lines define what the server does with keypresses that don't go to any client.

ToggleRotateKey = KEY

Defaults to Enter.

PrevScreenKey = KEY

Defaults to Left.

NextScreenKey = KEY

Defaults to Right.

ScrollUpKey = KEY

Defaults to Up.

ScrollDownKey = KEY

Defaults to Down.

LCDd.conf: The [Menu] Section

The [Menu] section enables you to set some general ("global") options related to the way LCDd handles input "events".

The menu is a special LCDproc client built into LCDd that allows changing server and display settings as well as extending it with entries from client applications.

You can configure what keys the menu should use.

MenuKey = KEY

The key that switches into menu mode (=open the main menu). In menu mode it cancels any operation. Cancelling the main menu means returning to the regular display mode. It has no default, but a natural candidate is Menu.

Note

The MenuKey will be reserved exclusively, while the others work in shared mode and can thus be used by a client application when not in the menu.

EnterKey = KEY

The key to enter a sub menu, to select an entry and/or to confirm the value of an input field. If the RightKey is not defined, it is also used to move right in input fields. In this case the value of the input field is not confirmed, until the right end of the input has been reached. It is not set by default, but a natural candidate is Enter.

UpKey = KEY

The key to move to the previous item in a menu and/or to select the previous value in input fields (e.g. the previous character available for the current position). If the DownKey is not set, moving up before the first entry automatically wraps around to the last entry. It is not set by default, but a natural candidate is Up.

DownKey = KEY

The key to move to the next item in a menu and/or to select the next value in input fields (e.g. the next character available for the current position). If the UpKey is not set, moving down below the last entry automatically wraps around to the first entry. It has no default, but a natural candidate is Down.

LeftKey = KEY

If defined, this optional key is used to to move left in input fields and to select submenu entries. It is not set by default, but if you have more than 4 keys, a natural candidate is Left.

RightKey = KEY

If defined, this optional key is used to to move right in input fields. It is not set by default, but if you have more than 4 keys, a natural candidate is Right.

The minimal keys required for the menu work correctly are the MenuKey, the EnterKey and one of UpKey or DownKey. With these 3 keys the menus can be operated. Of course with only 3 keys the navigation gets a bit awkward. So if you have 4 or more keys, you better use them. Especially the LeftKey and RightKey make a big difference in user experience.

LCDd.conf: The Driver Section

As mentioned earlier, each driver has its own section in the LCDd.conf.

Although the settings are more or less self-explanatory, they are explained in the next chapter in the section for each driver. So, read through the section of your driver and change everything necessary.

The LCDproc Init Scripts

The LCDproc distribution contains init scripts for LSB 3.1 (Linux Standard Base 3.1) conforming GNU/Linux distributions. In addition to those it contains init scripts for older RedHat- and Debian-based distributions that do not adhere to LSB 3.1. You can find all of them in the scripts/ 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.

Note

You can retrieve a listing of all options of lcdproc running lcdproc --help.

init-lcdexec

The file scripts/init-lcdexec.* is the init script for the LCDproc lcdexec client, which can execute predefined commands via the menu feature.

init-lcdvc

The file scripts/init-lcdvc.* is the init script for the LCDproc lcdvc client, a simple terminal.

Chapter 5. LCDproc Drivers

Table of Contents

The bayrad Driver
Features
Configuration in LCDd.conf
The CFontz Driver
Configuration in LCDd.conf
The CFontz633 Driver
Configuration in LCDd.conf
The CFontzPacket Driver
Configuration in LCDd.conf
The curses Driver
Configuration in LCDd.conf
The CwLnx Driver
Features
Configuration in LCDd.conf
The ea65 driver
EA65 front panel VFD
Configuration in LCDd.conf
The Eyebox One Driver (EyeboxOne)
Eyebox One LCD Module
Eyebox One Driver and lcdproc client
Copyright
Configuration in LCDd.conf
The G15 Driver
Features
Configuration in LCDd.conf
The glcdlib Driver
Connections
Configuration in LCDd.conf
The glk Driver
Supported devices
Configuration in LCDd.conf
The HD44780 Driver
Connections
Compiling
Configuration in LCDd.conf
Miscellanea
The i2500vfd Driver
Features
Options
The icp_a106 Driver
Configuration in LCDd.conf
The imon Driver
General
Configuration in LCDd.conf
The imonlcd Driver
General
Configuration in LCDd.conf
The IOWarrior Driver
General
Requirements
Configuration in LCDd.conf
The irman Driver
Configuration in LCDd.conf
The irtrans Driver
General
Configuration in LCDd.conf
The Joystick Input Driver
Configuration in LCDd.conf
The lb216 Driver
Configuration in LCDd.conf
The lcdm001 Driver
Configuration in LCDd.conf
The lcterm Driver
Configuration in LCDd.conf
The lirc Driver
Checking Your LIRC Setup
Build LCDd with the lirc Driver
Configure LCDd to Use the lirc Driver
Configuration in LCDd.conf
Modify Your ~/.lircrc
The lis Driver
Features
Requirements
Configuration in LCDd.conf
The MD8800 Driver
Features
Configuration in LCDd.conf
The mdm166a driver
Configuration in LCDd.conf
Using the icons
Special device hints
The ms6931 Driver
Configuration in LCDd.conf
The mtc_s16209x Driver
Configuration in LCDd.conf
The MtxOrb Driver
Matrix Orbital LCD Modules
Matrix Orbital Hardware Installation
Configuration in LCDd.conf
The MX5000 Driver
Features
Configuration in LCDd.conf
The NoritakeVFD Driver
Configuration in LCDd.conf
The Mini-Box.com USB LCD picoLCD Driver
Displays
Requirements
Configuration in LCDd.conf
picolcd driver status
Copyright
The pyramid Driver
Features
Connector
Requirements
LED output
Configuration in LCDd.conf
The sed1330 Driver
Connections
Keypad
Configuration in LCDd.conf
The sed1520 Driver
Connections
Configuration in LCDd.conf
The serialPOS Driver
Connecting The Display
Configuration in LCDd.conf
The serialVFD Driver
Connecting The Display
Configuration in LCDd.conf
The shuttleVFD Driver
Features
Configuration in LCDd.conf
The sli Driver
Configuration in LCDd.conf
The stv5730 Driver
Configuration in LCDd.conf
The SureElec Driver
Configuration in LCDd.conf
The svga Driver
Configuration in LCDd.conf
The Toshiba T6963 Driver
Connections
Compiling
Configuration in LCDd.conf
The text Driver
Configuration in LCDd.conf
The tyan Driver
Features
Configuration in LCDd.conf
The ula200 Driver
General
Requirements
Known problems
Implementation note
Configuration in LCDd.conf
The xosd Driver
Configuration in LCDd.conf
Parallel Port Troubleshooting
Check The Wiring
Power Source Unregulated / Noisy
Ground Lift
Latchup
Contrast
Parallel Port Voltage
Enable Signal Rise Time
EMI
One or Two Black Lines
Software Too Fast
LED Backlight
HD44780 Compatible
Miscellanea

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

This section talks about using LCDproc with the BayRAD LCD modules by EMAC, Inc.

Features

The BayRAD LCD modules are designed to fit into 5,25" drive bays. They contain an LCD display that is 20 characters wide and 2 lines high surrounded by 4 buttons labeled Menu, Select, +/Yes, and -/No.

BayRAD modules are connected to the PC using a serial RS232 connection getting operating power using the standard floppy drive power connector.

For more information see the BayRAD home page

Configuration in LCDd.conf

[bayrad]

Device = DEVICE

Select the serial output device to use. If not given, default is /dev/lcd.

Speed = { 1200 | 2400 | 9600 | 19200 }

Set the the baud rate to use when communicating with the LCD. 9600 is the default, if not specified.

The CFontz Driver

This section talks about using LCDproc with the serial LCD displays of the CFA632 and CFA634 series by CrystalFontz, Inc.

Configuration in LCDd.conf

[CFontz]

Device = DEVICE

Select the serial output device to use. If not given, default is /dev/lcd.

Size = WIDTH x HEIGHT

Set the LCD's dimensions in terms of characters per line and lines. If not given, it defaults to 20x4.

Contrast = CONTRAST

Set the initial contrast. Legal values for CONTRAST are in the range between 0 and 1000. If not given, it defaults to 140.

Brightness = BRIGHTNESS

Set the initial brightness. Legal values for BRIGHTNESS range from 0 to 1000. If not given, it defaults to 1000.

OffBrightness = BRIGHTNESS

Set the initial off-brightness. This value is used when the display is normally switched off in case LCDd is inactive. Legal values BRIGHTNESS are in the range from 0 to 1000. The default is 0.

Speed = { 1200 | 2400 | 9600 | 19200 | 115200 }

Set the the baud rate to use when communicating with the LCD. It defaults to 9600 if not specified.

NewFirmware = { yes | no }

Set the firmware version (New means >= 2.0) [default: no; legal: yes, no]

Reboot = { yes | no }

Reinitialize the LCD's BIOS [default: no; legal: yes, no] normally you shouldn't need this

The CFontz633 Driver

This section talks about using LCDproc with LCD displays that use the CFontz633 chipset.

Warning

This driver is deprecated. Please use the CFontzPacket driver with Model=633 instead. This driver will be removed in a future version.

Configuration in LCDd.conf

[CFontz633]

Device = DEVICE

Select the output device to use [default: /dev/lcd] may be serial device or USB device in serial emulation mode.

Size = WIDTH x HEIGHT

Select the LCD type (size) [default: 16x2]

Contrast = CONTRAST

Set the initial contrast. Legal values for CONTRAST are 0 - 1000. If not specified, it defaults to 560.

Brightness = BRIGHTNESS

Set the initial brightness [default: 1000; legal: 0 - 1000]

OffBrightness = BRIGHTNESS

Set the initial off-brightness [default: 0; legal: 0 - 1000] This value is used when the display is normally switched off in case LCDd is inactive

Speed = { 1200 | 2400 | 9600 | 19200 | 115200 }

Set the the baud rate for communication with the LCD. If not specified, the default is 19200.

NewFirmware = { yes | no }

Set the firmware version (New means >= 2.0) [default: no; legal: yes, no] Currently this flag is not in use, there is no such thing as NewFirmware. ;=)

Reboot = { yes | no }

Reinitialize the LCD's BIOS [default: no; legal: yes, no] I want to reboot the LCD to make sure we start from a known state

The CFontzPacket Driver

CrystalFontz offers a wide range of character and graphical LCD modules. The CFontzPacket driver supports the modules that communicate with the host computer using a packet-based communications protocol with 16-bit CRC (hence the driver name).

Currently this line of modules comprises the models:

CFA-631
  • 20x2 character LCD with backlight

  • keypad with 4 keys: Up, Down, enter & Escape

  • USB connection for data and power

  • mounting bracket to fit into 3,5" drive bays

  • Optional (via add-on board) temperature sensor, fan and ATX power control connectors (all unsupported by LCDproc)

CFA-633
  • 16x2 character LCD with backlight

  • keypad with 6 keys: 4 directions, Enter & Escape

  • serial or USB connection

  • mounting bracket to fit into 5,25" drive bays

  • Temperature sensor and fan control connectors (both unsupported by LCDproc)

CFA-533
  • This is the same as CFA-633 except it misses the fan control capabilities. The temperature monitoring is not supported in LCDproc though.

CFA-635
  • 20x4 characters LCD with backlight

  • keypad with 6 keys: 4 directions, Enter & Escape

  • USB connection for data and power

  • four bi-color LEDs to show status information

  • optional mounting bracket to fit into 5,25" drive bays

Configuration in LCDd.conf

[CFontzPacket]

Model = { 533 | 631 | 633 | 635 }

Select the LCD model that is connected. Legal values for this option are 631, 533, 633, or 635, with the default being 633.

Device = DEVICE

Select the output device to use. It may be a serial device or a USB device in serial emulation mode. If not given, it defaults to /dev/lcd.

Note

Mac OS X users may need to use one of the /dev/cu devices instead of the /dev/tty ones.

USB = { yes | no }

Enable this flag if the device is connected to an USB port. For serial ports leave it disabled. [default: no; legal: yes, no]

Size = WIDTH x HEIGHT

Select the LCD size. This overrides the size the driver uses for the selected model (631: 20x2, 533/633: 16x2, 635: 20x4).

Note

You should usually not need to set this value!

Contrast = CONTRAST

Set the initial contrast. Legal values for CONTRAST are 0 - 1000. If not specified, it defaults to 560.

Brightness = BRIGHTNESS

Set the initial brightness [default: 1000; legal: 0 - 1000]

OffBrightness = BRIGHTNESS

Set the initial off-brightness [default: 0; legal: 0 - 1000] This value is used when the display is normally switched off in case LCDd is inactive

Speed = { 19200 | 115200 }

Override the default baud rate the driver uses for communication with the selected LCD model. Allowed values are 19200 (default for CFA-533 and CFA-633) and 115200 (default for the CFA631 and CFA635).

Note

You should usually not need to set this value!

OldFirmware = { yes | no }

Very old 633 firmware versions do not support partial screen updates using 'Send Data to LCD' command (31). For those devices it may be necessary to enable this flag. [default: no; legal: yes, no]

Reboot = { yes | no }

Reinitialize the LCD's BIOS [default: no; legal: yes, no].

The curses Driver

This section talks about using LCDproc with the (n)curses library. This diver displays an emulated LCD display of configurable size at a configurable position of the terminal screen using (n)curses.

Configuration in LCDd.conf

[curses]

Foreground = COLOUR

Set the foreground color. If not given, it defaults to blue.

Legal values for COLOUR are red, black, green, yellow, blue, magenta, cyan and white.

Background = COLOUR

Set the background color. The default is cyan.

The legal values for COLOUR are the same as for the Foreground setting.

Backlight = COLOUR

Set the background color that is to be used when backlight is set on. backlight color. If not given, the default is red.

The legal values for COLOUR are the same as for the Foreground setting.

Size = WIDTH x HEIGHT

display size [default: 20x4]

TopLeftx = X-OFFSET , TopLefty = Y-OFFSET

What position (X,Y) to start the left top corner at. Default: (7,7)

UseACS = { yes | no }

Tell whether to use ACS (alternative character set) symbols for icons and bars instead of simple ASCII characters.

DrawBorder = { yes | no }

Tell whether to draw a border around the screen.

The CwLnx Driver

This section talks about using LCDproc with the serial / USB LCDs CW12232, CW12832 and CW1602 by CwLinux.

Features

The CwLinux CW12232 LCDs are graphical LCDs with 122 x 32 dots that also have a text mode with 20 x 4 characters, the CW12832 are graphical displays with 128 x 32 dots and a 21 x 4 character text mode, the CW1602 LCDs are character LCDs that are 16 characters wide and 2 lines high.

The modules can be ordered bare or as part of a kit mounted on brackets that fit in half-height 5.25" (CW12232 and CW1608) or 3,5" (CW12832) drive bays. The mounting brackets optionally feature a 6 button keypad that makes use of the keypad connector on the display modules.

The kits allow to programmatically switch on/off their backlight. Newer revisions of the kits also have programmable brighness as well as 4 general purpose IO ports.

The displays come in 2 variants that differ how they communicate with the host: The serial modules are connected to the PC using a serial RS232 connection getting operating power using the standard floppy drive power connector, while the USB modules only require an USB connection.

For more information see the CwLinux web site

Configuration in LCDd.conf

[CwLnx]

Model = { 12232 | 12832 | 1602 }

Select the LCD model [default: 12232; legal: 12232, 12832, 1602]

Device = DEVICE

Select the output device to use [default: /dev/lcd] May be serial device or USB device in serial emulation mode.

Size = WIDTH x HEIGHT

Select the LCD size [default: depending on model: 12232: 20x4, 12832: 21x4] 1602: 16x2]

Speed = { 9600 | 19200 }

Set the the baud rate for communication with the LCD. If not given, the default is 19200.

Reboot = { yes | no }

Reinitialize the LCD's BIOS [default: no; legal: yes, no] normally you shouldn't need this

Keypad = { yes | no }

Tells if you have a keypad connected. Keypad layout is currently not configurable from the config file.

KeyMap_A = KEY , KeyMap_B = KEY , KeyMap_C = KEY , KeyMap_D = KEY , KeyMap_E = KEY , KeyMap_F = KEY

If you have a non standard keypad you can associate any keystrings to keys. There are 6 input key in the CwLnx hardware that generate characters from 'A' to 'F'. Legal values for KEY are Up, Down, Left, Right, Enter and Escape.

The following it the built-in default mapping hardcoded in the driver.

KeyMap_AUp
KeyMap_BDown
KeyMap_CLeft
KeyMap_DRight
KeyMap_EEnter
KeyMap_FEscape

You may leave it unchanged if you have a standard keypad. You can change it if you want to report other keystrings or have a non standard keypad.

keypad_test_mode = { yes | no }

keypad_test_mode permit to test keypad assignment Default value is no

The ea65 driver

This section describes the ea65 driver which works with the front panel VFD display on the AOpen XC Cube-AV EA65 media barebone.

EA65 front panel VFD

The AOpen XC Cube-AV is a barebone designed for using as a media center. It comes with a front panel display which is capable of displaying one line of 9 characters.

The display is internally connected to the serial port (/dev/ttyS1) with a fixed rate of 9600 baud.

The display uses 13 segments per character. That's why the driver provides no custom characters like the ones for dot matrix displays do.

The front panel furthermore has 9 keys which are illuminated by blue LEDs. The LEDs can be controlled with the backlight functions. The keys are not supported by this driver. The red LED (RECORD) can be controlled with the output command of LCDd.

Configuration in LCDd.conf

[ea65]

Brightness = BRIGHTNESS

Set the brightness for the front LEDs if backlight is switched on. Legal values for BRIGHTNESS are in the range between 0 and 1000. Values under 300 set the LEDs off. Values between 300 and 700 turn on the LEDs with half brightness. Values above 700 turn on the LEDs with full brightness. If not given, it defaults to 500.

OffBrightness = OFFBRIGHTNESS

Set the brightness for the front LEDs if backlight is switched off. Legal values for OFFBRIGHTNESS are in the range between 0 and 1000. Values under 300 set the LEDs off. Values between 300 and 700 turn on the LEDs with half brightness. Values above 700 turn on the LEDs with full brightness. If not given, it defaults to 0.

The Eyebox One Driver (EyeboxOne)

This section describes the Eyebox One.

Eyebox One LCD Module

Eyebox One is a small rackmounted server marketed by Rightvision (http://www.alcateleyebox.rightvision.com/). This server has an LCD module, a keypad, two graphbars and some leds.

The LCD is a 20x4 alphanumeric module connected via standard DB-9 cabling and connector.

I couldn't find any documentation about it. All I know has been obtained with some reverse engineering. It seems that it can run only at 19.200 baud. 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, hide/show the cursor, on/off the backlight, and so on.

This module is fast. 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.

Eyebox One Driver and lcdproc client

You can use the two Eyebox One graphbars, one as a free CPU meter, and one as a free RAM meter with lcdproc client (see eyebox.c in lcdproc client sources).

In order to use it, you must execute ./configure with a special parameter: CPPFLAGS=-DLCDPROC_EYEBOXONE ./configure --enable-drivers=EyeboxOne

This is only a BETA version modification, take it as a demo...

Copyright

This section was originally part of the mtxorb.docbook file by Rene Wagner

This section has been modified by Cédric TESSIER (http://www.nezetic.info)

Configuration in LCDd.conf

[EyeboxOne]

Device = DEVICE

Select the output device to use [default: /dev/ttyS1]

Size = WIDTH x HEIGHT

Set the display size [default: 20x4]

Backlight = { yes | no }

Switch on the backlight [default: yes; legal: yes, no]

Note

If you choose yes, you can switch on/off the backlight in real time using the LCDproc server menu with the keypad.

Cursor = { yes | no }

Switch on the cursor? [default: no; legal: yes, no]

Speed = { 1200 | 2400 | 9600 | 19200 }

Set the the baud rate to use when communicating with the LCD. If not specified, it defaults to 19200.

Note

As I said, I think only 19200 is a good choice.

LeftKey = D , RightKey = C , UpKey = A , DownKey = B , EscapeKey = P , EnterKey =

The following table translate from EyeboxOne Key to Logical Key. EyeboxOne Enter Key is a \r character, so it's hardcoded in the driver.

keypad_test_mode = { yes | no }

You can find out which key of your display sends which character by setting keypad_test_mode to yes and running LCDd. LCDd will output all characters it receives. Afterwards you can modify the settings above and set keypad_set_mode to no again.

The G15 Driver

This section talks about using LCDproc with LCD displays on Logitech G15 gaming keyboards.

Features

This driver uses g15daemon's virtual screen capabilities to enable multiple LCDd instances to display on the LCD of the Logitech G15 gaming keyboard. Text and other rendering services are provided by libg15render from the g15tools project. Input is provided by g15daemon, enabling use of the L1-L5 and G1 keys. The required libraries are available from the g15daemon and g15tools projects at sourceforge.net.

Configuration in LCDd.conf

Currently there aren't really any configuration options to be set. The width and height are hardcoded based on the font currently used. In the future, now that libg15render has FreeType2 support, there may be options to adjust the font used and the display size.

The glcdlib Driver

Lucian Muresan

This section talks about using LCDproc with LCD displays supported by graphlcd-base.

Connections

The so-called "meta-driver" glcdlib extends LCDproc's supported drivers by all the drivers supported by graphlcd-base, which you can get from http://graphlcd.berlios.de.

In order to be able to use it, you have to get and install the glcdprocdriver from http://www.muresan.de/graphlcd/lcdproc/ before configuring the LCDproc build process --enable-drivers=glcdlib.

Configuration in LCDd.conf

[glcdlib]

Mandatory settings

Driver = GRAPHLCD-DRIVER

Specify which graphical display supported by graphlcd-base to use. Legal values for GRAPHLCD-DRIVER are specified in graphlcd's configuration file /etc/graphlcd.conf. For graphlcd 0.13 they comprise avrctl, framebuffer, gu140x32f, gu256x64-372, gu256x64C-3xx0, hd61830, image, ks0108, noritake800, sed1330, sed1520, serdisp, simlcd, and t6963c. If not specified it defaults to image.

UseFT2 = { yes | no }

Tell whether to use FreeType2 or not. If set to no use graphlcd's bitmap fonts, which is only one size/font file. If set to to the default value yes use the fonts that FreeType2 provides.

Note

Setting it to yes requires Freetype2 support in libglcdprocdriver and its dependants.

TextResolution = WIDTH x HEIGHT

Give text resolution in fixed width characters. If it won't fit according to the available physical pixel resolution and the minimum available font face size in pixels, 'DebugBorder' will automatically be turned on. If not specified, it defaults to 16x4.

FontFile = FILENAME

Set path to font file to use, e.g. /usr/share/fonts/corefonts/courbd.ttf.

Availalble parameters if UseFT2 = yes

CharEncoding = CHARSET

Specify character encoding to use, e.g. iso8859-2. If not given, use the default ISO8859-1.

MinFontFaceSize = COLUMNS x ROWS

minimum size in pixels in which fonts should be rendered

Optional settings

Brightness = BRIGHTNESS

Brightness (in %) if applicable Legal values are 0 - 100. If not specified, the default is 50.

Contrast = CONTRAST

Set the contrast (in %) if applicable. Legal values are 0 - 100, with 50 being the default when not specified.

Backlight = { yes | no }

Backlight if applicable

UpsideDown = { yes | no }

flip image upside down

Invert = { yes | no }

invert light/dark pixels

ShowDebugFrame = { yes | no }

turns on/off 1 pixel thick debugging border within the usable text area, for setting up TextResolution and MinFontFaceSize (if using FT2);

ShowBigBorder = { yes | no }

border around the unused area

ShowThinBorder = { yes | no }

border around the unused area

PixelShiftX = SHIFTX , PixelShiftY = SHIFTY

Shifts the content of the display by SHIFTX (default: 0) and SHIFTY (default: 0) pixels.

The glk Driver

This section talks about using LCDproc with LCD displays that use the Matrix Orbital GLK and GLC chipset.

Supported devices

Currently the drivers supports the following devices:

  • GLC12232 (20x4)

  • GLC12864 (20x8)

  • GLC128128 (20x16)

  • GLC24064 (40x8)

  • GLK12232-25 (20x4)

  • GLK12232-25-SM (20x4)

  • GLK12864-25 (20x8)

  • GLK128128-25 (20x16)

  • GLK24064-25 (40x8)

Note

Modules not in the list above are not recognized and the driver will not load if it encounteres an unrecognized display.

Configuration in LCDd.conf

[glk]

Device = DEVICE

select the serial device to use [default: /dev/lcd]

Contrast = CONTRAST

Set the initial contrast. Legal values for CONTRAST are 0 - 1000. If not given, it defaults to 560.

Speed = { 9600 | 19200 | 38400 }

Set the the baud rate for communication with the LCD. The default is 19200.

The HD44780 Driver

The HD44780 has become the de-facto standard of alphanumeric character displays. Although the original Hitachi HD44780 is long out of production, its command set has survived in a variety of (fully or nearly) compatible LCD, VFD and even OLED displays sold by a broad range of manufacturers all over the world. To name only a few: KS0066, KS0070, KS0076, LC7985, NT3881, SED1278, ST7066 ...

The command set of these displays, which sometimes are advertised as being "industry standards compatible", is thus the workhorse of controllers for displays ranging from 8x1 to 20x4 or 40x2 characters. There are even displays with larger dimensions sporting two controllers, one for each half of the display.

The HD44780 driver supports various ways of connecting HD44780 devices to your system. Each of these different ways is called a connection type of the driver.

On a parallel port, probably the first interface type HD44780 devices were historically connected to, the driver supports the connection types:

For serial RS-232 ports you can choose among these connection types:

In recent years, with with parallel ports and serial ports being declared legacy and on the demise on modern computers, the USB connection types get more important. Here are the USB connection types the HD44780 driver supports:

Last but not least, for special purposes, there are even more connection types:

Depending on the connection type and the display connected, the driver supports various special features.

  • Input keys

  • software controllable brightness / backlight

  • software controllable contrast

  • multiple displays / multi-controller displays

Connections

Common connections for all connection types

No matter what connection type you choose, you will always need some connections. They are explained here.

Power

All variants use the same method of obtaining power. i.e., for each LCD:

Table 5.1. HD44780: Power Connections

LCDSignal
namepin
VEE1GND (connect to any of pins 18 - 25 of you parallel port)
VCC2+5V
VLC3(contrast adjustment)

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 intended for disk drives (the red wire is 5V, black is GND).

  • Get it from the VCC and GND pins of an USB connector. For the USB connection types this is done automatically, as the circuits used there automatically power the LCD.

  • 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 whether 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.

Figure 5.1. HD44780: Connecting the contrast adjusting pin (VLC)



     (variable resistor)
        .------.
 Vcc ---|  10k |--- GND
        `---^--'
           /|\
            |
           Vlc



Keypad

You can connect a keypad with most 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.

Figure 5.2. HD44780: Direct Keys



      O 5V
      |
      |
      -
     | | 10k
     | |
      -
      |
      +-----------o input  (X)
      |
      |
      o
       \
      o
      |
      |
     === GND



By default, the following keystrokes are generated by the different keys:

Table 5.2. HD44780: Direct Key Mapping

key indexmapped string
X1A
X2B
X3C
X4D
X5E


You can change the mapping using the KeyDirect_NUM configuration option, where NUM is the subscript to the X in the table above.

Matrix Keys

Using a matrix, we can connect much more keys. To simplify the drawing here, we replace all switches with an @ symbol:

Figure 5.3. HD44780: Single Matrix Key



             X line
                |
                |
  Y line ---+---------
            |   |                    |
            o   |               =  --@--
             \  |                    |
            o   |
            |   |
            +---+
                |
                |



We connect the matrix of keys like this:

Figure 5.4. HD44780: Complete Key Matrix



Y1 o---|<---@--@--@
            |  |  |
Y2 o---|<---@--@--@
            |  |  |
Y3 o---|<---@--@--@
            |  |  |
Y4 o---|<---@--@--@            O 5V
            |  |  |            |
    diodes  |  |  |     ___    |
    1N4148  +----------|___|---+
            |  |  |     ___    |
            |  +-------|___|---+
            |  |  |     ___    |
            |  |  +----|___|---+     resistors 22k
            |  |  |
            o  o  o
            X1 X2 X3



As you can see, you need 1 resistor per X line, and 1 diode per Y line. By default, 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 mapping:

Table 5.3. HD44780: Matrix Keypad Layout

 X1X2X3X4X5
Y1123AE
Y2456BF
Y3789CG
Y4*0#DH

This mapping can be changed using the KeyMatrix_X_Y configuration option, where X and Y are the subscripts to the respective axes above.

If you only need e.g. 10 keys, leave the rest away. 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:

Figure 5.5. HD44780: One Return Line



                  O 5V
                  |
                 .-.
                 | | 4k7 or 22k
     diodes      | |
     1N4148      '-'
            ___   |
Y1 o---|<---o o---+
            ___   |
Y2 o---|<---o o---+
            ___   |
Y3 o---|<---o o---+
            ___   |
Y4 o---|<---o o---+----o 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:

Figure 5.6. HD44780: Backlight Wiring



                                             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



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. Therefore 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 is "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.)

4bit

This wiring is originally based on "lcdtext" (by Matthias Prinke).

Table 5.4. HD44780: 4bit Pinouts (1)

printer port<->LCD
namepinnamepin
  GNDVEE1
  +5VVCC2
  (contrast adjustment)VLC3
D46 RS4
  GNDRW5
D68 EN6
D02 D411
D13 D512
D24 D613
D35 D714

Note

The RW (pin 5) line of the display decides whether the display receives data from the LPT port, or whether it sends data to the LPT port: if grounded it receives, if High or connected to nothing at all it "sends" (i.e., will not work as intended). So, if you are not sure that you need it otherwise, then connect it to GND. This certainly applies if you have only one display.

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 4bit connection type supports more than one display connected to the same parallel port. If you want to connect more than one display, then wire the all the displays to the parallel port according to the scheme above with the exception of the EN (pin 6) line of the LCDs.

For the second and further displays, you can find the wiring for the EN (pin 6) line in the table below.

Table 5.5. HD44780: 4bit Pinouts (2)

printer port<->LCD
namepinnamepin
D79 EN26 of 2nd display
D57 EN36 of 3rd display
STR1 EN46 of 4th display
LF14 EN56 of 5th display
INIT16 EN66 of 6th display
SEL17 EN76 of 7th display

The optional keypad can be connected as follows:

Table 5.6. HD44780: 4bit Keypad Pinouts

printer port<->keypadremarks
namepinpin
D02 Y1 
D13 Y2 
D24 Y3 
D35 Y4 
D46 Y5 
D57 Y6Only if not used for backlight or 3rd controller.
nSTRB1 Y7Only if not used for additional controllers.
nLF14 Y8
INIT16 Y9
nSEL17 Y10
nACK10 X1 
BUSY11 X2 
PAPEREND12 X3 
SELIN13 X4 
nFAULT15 X5 

The optional backlight wiring should be connected to D5, pin 7.

8bit "Winamp"

This type of connection should work with winamp.

Table 5.7. HD44780: "Winamp" wiring

printer port<->LCD
namepinnamepin
D02 D07
D13 D18
D24 D29
D35 D310
D46 D411
D57 D512
D68 D613
D79 D714
nSTRB1 EN6
nLF14 RW5 (EN3 6 - LCD 3) (optional (*) )
INIT16 RS4
nSEL17 EN2(6 - LCD 2) (optional)

(*) on the RW line of the display: this line decides whether the display receives data from the LPT port, or whether it sends data to the LPT port: if grounded it receives, if High or connected to nothing at all it "sends" (i.e., will not work as intended). So, if you are not sure that you need it otherwise, then connect it to GND. This certainly applies if you have only one display.

If you want the display to work with the Winamp plugin, wire nLF (pin 14) to RW of your LCD. You can then use the plugin in bidirectional mode (which 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:

Table 5.8. HD44780: "Winamp" wiring - Keypad

printer port<->keypad
namepinpin
D02 Y1
D13 Y2
D24 Y3
D35 Y4
D46 Y5
D57 Y6
D68 Y7
D79 Y8
nACK10 X1
BUSY11 X2
PAPEREND12 X3
SELIN13 X4
nFAULT15 X5

The optional backlight wiring should be connected to nSEL, pin 17.

8bit "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://www.ibiblio.org/pub/linux/system/status/lcdtime-0.2.tar.gz
http://www.ibiblio.org/pub/linux/system/status/meter-0.2.tar.gz
http://www.ibiblio.org/pub/linux/system/status/portato-1.2.tar.gz

The LCD connections are:

Table 5.9. HD44780: "lcdtime" wiring

printer port<->LCD
namepinnamepin
D02 D07
D13 D18
D24 D29
D35 D310
D46 D411
D57 D512
D68 D613
D79 D714
nSEL17 - 
nSTRB1 RS4
nLF14 RW5 (optional - pull LCD RW low (*)
INIT16 EN6

(*) on the RW line of the display: this line decides whether the display receives data from the LPT port, or whether it sends data to the LPT port: if grounded it receives, if High or connected to nothing at all it "sends" (i.e., will not work as intended). So, if you are not sure that you need it otherwise, then connect it to GND.

See the lcdtime tar-ball (above) for full details of the bargraph connections.

The optional keypad can be connected as follows:

Table 5.10. HD44780: "lcdtime" wiring - keypad

printer port<->keypad
namepinpin
D02 Y1
D13 Y2
D24 Y3
D35 Y4
D46 Y5
D57 Y6
D68 Y7
D79 Y8
nSTRB1 Y9
nSEL17 Y10 (only if not used for backlight)
nACK10 X1
BUSY11 X2
PAPEREND12 X3
SELIN13 X4
nFAULT15 X5

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 .

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.

Figure 5.7. HD44780: Serial LPT wiring ('simple')



                                      IC1
                                   -----------
                                  |   4094    |
                            5V    | shift reg |                    display
                             O    |           |                            keys
                             |   1|           |4
                             +----|STR      Q0|--------------------o 11 D4   Y1
                             |    |           |5
           Data              |   2|         Q1|--------------------o 12 D5   Y2
   D3 5 o-------------------------|D          |6
                             |    |         Q2|--------------------o 13 D6   Y3
                             |   3|           |7
   D4 6 o-------------------------|CK       Q3|--------------------o 14 D7   Y4
                             |    |           |14
                             |  15|         Q4|--------------------o         Y5
                             +----|OE         |13
                                  |         Q5|--------------------o 4  RS   Y6
                                  |           |12
                                  |         Q6|--------------------o         Y7
                                  |           |11
                                  |         Q7|--------------------o         Y8
                                  |           |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



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.

Figure 5.8. HD44780: Serial LPT wiring ('complex')



                                      IC2
                                   -----------
                                  |  74HCT164 |
                                  | shift reg |                    display
                                  |           |                            keys
           Data                  1|           |3
   D3 5 o---------------------+---|D        Q0|--------------------o 11 D4   Y1
                              |   |           |4
                              |  2|         Q1|--------------------o 12 D5   Y2
                              +---|D          |5
                                  |         Q2|--------------------o 13 D6   Y3
                                  |           |6
                                  |         Q3|--------------------o 14 D7   Y4
                                  |           |10
           Clock                 8|         Q4|--------------------o         Y5
   D4 6 o-------------------------|CK         |11
                                  |         Q5|--------------------o 4  RS   Y6
               ___       9|\ 8   9|_          |12
           +--|___|--+----| >o----|R        Q6|--------------------o         Y7
           |   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



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.

Table 5.11. HD44780: Serial LPT - Keypad return lines

printer port<->keypad
namepinpin
nACK10 X1
BUSY11 X2
PAPEREND12 X3
SELIN13 X4
nFAULT15 X5

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:

Figure 5.9. HD44780: Serial LPT - Keypad return lines buffered



               1|\ 2    13|\ 12   ___
   keypad o-----| >o------| >o---|___|---+---o input pin on LPT port
   return       |/        |/      220E   |
                IC1       IC1           ---
                                        --- 1nF
                                         |
                                        ===



Serial LPT Backlight

Also a backlight is supported. 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

Figure 5.10. HD44780: Serial LPT - Backlight extra circuit



                 ___       3|\ 4
     Data o-----|___|--+----| >o----o BL output
   LPT-D3       470k   |    |/
                      ---   IC1
                      ---
                       |100nF
                       |
                      ===



FTDI FT2232D USB chip "ftdi"

You can use a FTDI FT2232D dual channel USB <-> parallel FIFO chip to connect a display via the USB bus. The chip is switched to bitbang mode and drives both channels as outputs to control the display in 8bit mode.

Table 5.12. HD44780: 8bit FTDI

FTDI chip<->LCD
namepinnamepin
ADBUS024 D07
ADBUS123 D18
ADBUS222 D29
ADBUS321 D310
ADBUS420 D411
ADBUS519 D512
ADBUS618 D613
ADBUS717 D714
BDBUS040 RS4
BDBUS139 RW5
BDBUS238 EN6
BDBUS337 BLBacklight (optional)

You can configure the USB vendor/product ID in LCDd.conf. The wiring of the control lines can optionally be reconfigured, please look at the driver source if you really need that.

Alternatively you can use a single channel FTDI FT245BM USB <-> parallel FIFO chip and use the display in its 4 bit mode.

Table 5.13. HD44780: 4bit FTDI

FTDI chip<->LCD
namepinnamepin
D025 D411
D124 D512
D223 D613
D322 D714
D421 EN6
D520 RS4
D619 RW5

The following special configuration settings are required to use a single channel FTDI FIFO chip:

Example 5.1. HD44780: Configuration for FTDI 4bit


[hd44780]
ConnectionType=ftdi
ftdi_mode=4
ftdi_line_RS=0x40
ftdi_line_RW=0x20
ftdi_line_EN=0x10


LIS2 USB device "lis2"

LIS2 from VLSystem (http://www.vlsys.co.kr) is a full featured USB VFD module with four channel fan controls. This device can be accessed as a serial device with the help of the kernel module ftdi_sio.ko that maps the USB port to a serial port (e.g. /dev/ttyUSBx).

MPlay Blast USB device "mplay"

MPlay Blast from VLSystem (http://www.vlsys.co.kr) is a full featured USB VFD module with two channel fan controls and two channel temperature sensors. This device can be accessed as a serial device with the help of the kernel module ftdi_sio.ko that maps the USB port to a serial port (e.g. /dev/ttyUSBx).

LCD on Serial panel device "los-panel"

See http://www.xs4all.nl/~mlf/los/ for more information on this device.

VDR LCD serial device "vdr-lcd"

… to be documented …

Please address Matteo Pillon for further information.

VDR-Wakeup module "vdr-wakeup"

The VDR-Wake module by Frank Jepsen is a serial IO extension module for the famous Linux-based VDR that allows to connect an LCD to it and supports LCDproc.

See http://www.jepsennet.de/vdr/ (German) for more information on VDR-Wakeup.

Pertelian X2040 "pertelian"

The Pertelian X2040 includes an HD44780 display with enclosure and USB connection. In order to work with LCDproc in Linux you need the usbserial.ko and ftdi_sio.ko kernel modules loaded. The display will then be available on a serial port /dev/ttyUSBx.

See the X4020 product page for more information.

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.

For more information see the PIC-an-LCD User Manual by Dale Wheat.

LCD serializer device "lcdserializer"

LCD serializer connection is technically the same as PIC-an-LCD with the same advantages, it uses the serial port making things really simple. Unlike PIC-an-LCD LCD serializer is not a commercial product. it's just a project found digging on the net and freely available. You have all the tools and the code to build it yourself and to customize the behaviour of the device.

What you need

  • Some electronic knowledge and familiarity with the soldering iron

  • A PIC16F84 (I used PIC16F84A) or PIC16C54

  • JDM PIC programmer

  • gputils and picprog installed on your GNU/Linux box

Burning the PIC

First, you need to download the ASM source for your PIC and then make the hex:

$ gpasm lcd16f84_custom.asm

Now the binary is ready to be flashed to the PIC. Connect the programmer with the PIC installed and issue the following command to see it burning ;-):

$ picprog --erase --burn --input lcd16f84.hex --pic /dev/ttyS0
Running lcdproc

It's time to build the operating circuit, remember this driver uses a baud rate of 9600, so JP2 need to be closed.

Now power on the board. You should see OK on the LCD screen. Otherwise double-check all the connections.

Change LCDd.conf to include the following statements in the [hd44780] section:

ConnectionType=lcdserializer
Device=/dev/ttyS0

Finally, start the daemon and relax watching lcdproc running.

Customizing startup message

If want to change the default startup message (OK.), you can edit the asm source and write anything you want. Open the asm source with your preferred editor and look for this:


;******* START Main Loop Here **************

; This is where we should insert any little startup LCD messages...
;   Print "OK." on startup...
                        movlw   0x4F
                        movwf   ARG1
                        call    SendLCDData
                        call    InitDelay200MS
                        movlw   0x4B
                        movwf   ARG1
                        call    SendLCDData
                        call    InitDelay200MS
                        movlw   0x2E
                        movwf   ARG1
                        call    SendLCDData
                        call    InitDelay200MS

This piece of code sends three characters to the LCD. The first line sets the value of w register (working register, aka accumulator) to 0x4F ('O' in ascii). The second line copies this value to ARG1, then the value is sent to the LCD. The fourth line delays the execution.

You don't have to write the ASCII values in your modification, gpasm does the translation for you, so if you want to see Booting... at startup, change the code above to look like this:


;******* START Main Loop Here **************

; This is where we should insert any little startup LCD messages...
;   Print "Booting..." on startup...
                       movlw   'B'
                       movwf   ARG1
                       call    SendLCDData
                       call    InitDelay200MS
                       movlw   'o'
                       movwf   ARG1
                       call    SendLCDData
                       call    InitDelay200MS
                       movlw   'o'
                       movwf   ARG1
                       call    SendLCDData
                       call    InitDelay200MS
                       movlw   't'
                       movwf   ARG1
                       call    SendLCDData
                       call    InitDelay200MS
                       movlw   'i'
                       movwf   ARG1
                       call    SendLCDData
                       call    InitDelay200MS
                       movlw   'n'
                       movwf   ARG1
                       call    SendLCDData
                       call    InitDelay200MS
                       movlw   'g'
                       movwf   ARG1
                       call    SendLCDData
                       call    InitDelay200MS
                       movlw   '.'
                       movwf   ARG1
                       call    SendLCDData
                       call    InitDelay200MS
                       movlw   '.'
                       movwf   ARG1
                       call    SendLCDData
                       call    InitDelay200MS
                       movlw   '.'
                       movwf   ARG1
                       call    SendLCDData
                       call    InitDelay200MS

Refer to burning section in order to compile and reflash the new firmware.

BWCT USB LCD module "bwctusb"

The BWCT USB LCD module, sold by Bernd Walter Computing Technology (http://www.bwct.de/lcd.html) is a little board that can be piggy-packed to a HD44780 display and connects that to USB.

The board, driven by the bwctusb connection type, does neither support a keypad for input, nor more than one single-controller display, nor does it allow setting the backlight or brightness. But you can set the display's contrast using software (see the Contrast configuration parameter).

Special configuration options

If there is more than one BWCT USB module connected to the system, the SerialNumber configuration parameter allows selecting which display is used in LCDd.

Till Harbaum's "lcd2usb"

LCD2USB is a cheap but powerful do-it-yourself interface to connect HD44780 based displays via USB, consisting of easily available parts only. The device supports software adjustable contrast and backlight as well as dual controller displays (required for 4*27 and 4*40).

It is based upon an Atmel AVR Mega8 CPU with a pure software implementation of the USB protocol for the Atmel AVR microcontroller series.

The whole interface incl. the hardware layout is under a GPL like license. This means that you can take these schematics and use it as a basis for your own interface e.g. for a graphic LCD.

Two keys can be connected to the LCD2USB interface board. They can generate three key events that can be mapped to key names using the DirectKey_1 to DirectKey_3 commands: one for each key and the third if the keys are pressed simultaneously. With this 3-key setup, menus can be used (see example below).

This driver supports the original LCD2USB interface board as described above as well as compatible devices like those sold by Lcdmod Kit or those developed by Malte Pöggel.

Special configuration options

Besides the standard configuration options for hd44780 displays, the lcd2usb connection type supports three additional options: Contrast to set the display's contrast, Brightness to set the display's brightness when the backlight is switched on and OffBrightness to set the display's brightness when is backlight is switched off. All three options expect a number in the range from 0 to 1000.

Example 5.2. HD44780: Configuration for LCD2USB


[menu]
MenuKey=Escape
EnterKey=Enter
DownKey=Down

[hd44780]
ConnectionType=lcd2usb
Contrast=850
Brightness=800
OffBrightness=0
Keypad=yes
Backlight=yes
Size=20x2
KeyDirect_1=Enter
KeyDirect_2=Down
KeyDirect_3=Escape


Tip

In order to make the lcd2usb connection type work with a 2-controller display you may need to set the vSpan config option accordingly.

Dick Streefland's "USBtiny"

USBtiny is a software implementation of the USB low-speed protocol for the Atmel ATtiny microcontrollers. It is also the name of a 'reference circuit' using the ATtiny2313.

The reference circuit features an IR receiver for remote controls and a LCD. Due to hardware limitations of the ATtiny2313 the LCD does not have switchable backlight, adjustable contrast, any keys, nor does it support displays with more than one controller. If you want these features and do not require the IR receiver we recommend to take a look at the LCD2USB device.

Note

LCDproc does not make use of the IR receiver. 3rd party software is required to make it do anything, e.g. LIRC.

USS-720 USB-to-IEEE 1284 Bridge (Belkin F5U002) "uss720"

The USS-720 USB-to-IEEE 1284 Bridge is a fully featured USB to parallel chip that is used in most (but not all) Belkin F5U002 USB Parallel Printer Adapters. Because these adapters are inexpensive and readily available on the second-hand market, they provide an excellent solution for users who want to experiment with a parallel port but only have USB ports on their computers.

Because the chip acts as a parallel port, the driver maintains the same features and wiring as the 8-bit "winamp" driver. However, because most USB Parallel Printer Adapters use a centronics printer connector, be sure to convert the pin numbering of the parallel port pins in the "winamp" wiring to the pin numbering of the centronics port. Many tables are available on the internet that illustrate how the pin numbering differs between the two.

Special configuration options

Because several manufacturers used the USS720 chip in their USB Parallel Printer Adapters, the VendorID and ProductID options are configurable in the LCDd.conf file.

Note

Not all Belkin F5U002 USB Parallel Printer Adapters used the USS720 chip. Look for the dark grey adapters with the removable USB cable for best results.

I2C with Port-Expander

If you have an I2C port available that is supported by your kernel (through /dev/i2c*), you can add a I2C port expander there (PCF8574P in this example).

Figure 5.11. HD44780: PCF8574P port expander on I2C bus


                                       IC1
                                   -----------
                                  | PCF8574P  |
                                  | I2C-Port- |                            HD44780
                                  | Expander  |                            display
                                  |           |4
                                  |         P0|----------------------------o 11 D4
                                  |           |5
           I2C-Bus              14|         P1|----------------------------o 12 D5
    SCL o-------------------------|SCL        |6
                                  |         P2|----------------------------o 13 D6
                                15|           |7
    SDA o-------------------------|SDA      P3|----------------------------o 14 D7
                                  |           |9
                                  |1        P4|----------------------------o 4  RS
           Set I2C-Address  +-----|A0         |10
           here:            |     |2        P5|----------------------------o 5  RW
           GND: Bit:=0      +-----|A1         |11
           VCC: Bit:=1      |     |3        P6|----------------------------o 6  EN
                            +-----|A1         |                      ___
           Here: 0x00       |     |           |                 +---|___|--o 15 backlight
                           ===    |           |                 |c   10R
                                  |           |12    ___       b|/
                                  |13       P7|-----|___|-----|
                                 -|INT        |      1k       |\
                                  |           |           bc557 |e
                                   -----------                  |
                                                                |
    +5V o-----------+------------------+---------------------+--+----------o 2  VCC
                    |                  |                     |
                    |                  |                     |
                    |10uF              O 16                 .-.
                   ---                IC1                   | |<-----------o 3  Vlcd
                   ---                 O 8                  | |10k
                    |                  |                    '-'
                    |                  |                     |
    GND o-----------+-------+----------+---------------------+-------+-----o 1  GND
                            |                                        |
                           === GND                                   +-----o 16 GND Backlight


Configuration

Example 5.3. HD44780: Configuration for I2C with port expander


[HD44780]
ConnectionType=i2c
Device=/dev/i2c-0
Port=0x20
Backlight=yes
Size=40x2
DelayBus=false
DelayMult=1
Keypad=no


The Device configuration setting denotes the device file of your I2C bus (here /dev/i2c-0). You have to load the kernel standard module i2c-dev.ko and the bus driver, but no I2C chip modules (e.g. pcf8574.ko)!

The Port config option contains the I2C address of the I2C port expander (here 0x20, the PCF8574 from the example above, with all address bits set to 0). Bit 8 of the address (normally 0 in I2C addresses) has a special meaning: It tells the driver to treat the device as PCA9554 or similar, a device that needs a 2-byte command, and it will be stripped off the address.

Table 5.14. HD44780: Examples of I2C port expander addresses

Port valueMeaning
0x200x27PCF8574 with A[012]=07
0x380x3fPCF8574A with A[012]=07
0xa00xa7PCA9554 with A[012]=07
0xa00xa7PCA9554A with A[012]=07

ethlcd Device

The ethlcd (http://manio.skyboo.net/ethlcd/) device is simply an LCD display driven by an ATmega microcontroller, controlled and powered by "home-made" Power over Ethernet. The hardware and software are open source.

Features

  • ethernet connection using ENC28J60 ethernet controller

  • Power over Ethernet (data and power using single UTP cable)

  • Atmel's ATmega168 microcontroller

  • 6 buttons (MENU, UP, DOWN, LEFT, RIGHT, ENTER)

  • backlight control in three states: ON, Night-Mode (partialy ON) and OFF

  • beeper

  • device act as a TCP server - LCDproc driver is connecting to device just by creating a TCP socket - no need to PC-side additional hardware besides NIC

Figure 5.12. HD44780: ethlcd - block diagram



   _____________________________________________________
  |                    buttons                          |
  |                       ^                             |
  |                       |                             |
  |  _________       ___________         ____________   |
  | |         |     |           |       |            |  |
  | |         |     |           |       |            |  |
  | |   LCD   |     |           |  SPI  |  ENC28J60  |  |  UTP cable
  | | HD44780 |<--- | ATmega168 | <---> |  ethernet  |<========+------> PC running
  | |         |     |           |       | controller |  |      |         LCDproc
  | |         |     |           |       |            |  |      |
  | |_________|     |___________|       |____________|  |      |
  |                       |                             |      |
  |                       |                             |      |
  |                     beeper                          |      |
  |_____________________________________________________|      |
   ethlcd                                                  AC Adapter



The device is "visible" to LCDproc just like any other HD44780 device. The difference is the wiring - instead of connecting the display directly to PC (via serial/parallel/usb port), it is connected via ethernet and the communication is done over TCP connection. The main feature is - that to power and control the LCD is needed single UTP cable. To use the driver, specify the device IP address or hostname, on which the ethlcd device is accessible by setting in config file the Device value. The default is ethlcd.

USBLCD adapter

The USBLCD adapter from Adams IT Services (http://www.usblcd.de/) is a small interface board which allows you to connect an alphanumerical display module based on the HD44780 or compatible controller to the USB. The display will be powered by the USB. It features a switchable backlight (on or off) and can be used with 16x2, 16x4 or 20x4 displays.

The usblcd connection type communicates with a kernel driver by using a device file /dev/usb/lcdx. The kernel driver providing this device currently only exists for Linux kernels newer than 2.4.20-pre7.

Note

As of 2007 these device are not sold anymore. This driver has been ported from lcdproc 0.4.5 to support existing users.

Compiling

Make sure that the HD44780 files are built when you run ./configure. This can be done by specifying --enable-drivers=all or by including hd44780 in the list of enabled drivers (e.g. --enable-drivers=hd44780).

Configuration in LCDd.conf

[hd44780]

Port = PORT

For parallel connections, specify the address of the parallel port the LCD is connected to. Common values for PORT are 0x278, 0x378 and 0x3BC. If not given, the default is 0x378.

Device = DEVICE

If you are using a serial or I2C connection, you need to set this parameter to the device your LCD is connected to. For example, if the display is connected to the first serial port, you have to set it to /dev/ttyS0. The default value is /dev/lcd.

ConnectionType = { 4bit | 8bit | winamp | serialLpt | picanlcd | lcdserializer | los-panel | vdr-lcd | vdr-wakeup | pertelian | bwctusb | lcd2usb | lis2 | mplay | i2c | ftdi | usblcd }

Select the type of the wiring / display connection.

ConnectionTypeWiring / Display Type
4bit4bit Wiring to parallel port(default)
8bit8bit Wiring to parallel port ("lcdtime")
winamp8bit Wiring "winamp" Style to parallel port
serialLptSerial LPT Wiring
picanlcdPIC-an-LCD serial device "picanlcd"
lcdserializerLCD serializer "lcdserializer"
los-panelLCD on Serial panel device "los-panel" (http://www.xs4all.nl/~mlf/los/)
vdr-lcdVDR LCD serial device "vdr-lcd"
vdr-wakeupVDR-Wakeup module "vdr-wakeup"
pertelianPertelian X2040 LCD display (http://pertelian.com/joomla/index.php?option=com_content&task=view&id=43&Itemid=48)
bwctusbBWCT USB device "bwctusb" (http://www.bwct.de/lcd.html)
lcd2usbTill Harbaum's LCD2USB (http://www.harbaum.org/till/lcd2usb/)
usbtiny Dick Streefland's USBtiny (http://www.xs4all.nl/~dicks/avr/usbtiny/)
lis2LIS2 from VLSystem (http://www.vlsys.co.kr)
mplayMPlay Blast from VLSystem (http://www.vlsys.co.kr)
ftdiDisplay connected to a dual channel FTDI 2232D USB chip
usblcdUSBLCD adapter from Adams IT Services (http://www.usblcd.de/)
i2cLCD driven by PCF8574(A)/PCA9554(A) connected via I2C

Tip

If you suspect the table above to be outdated, you might want to have a look at server/drivers/hd44780-drivers.h in LCDproc's source directory which contains the actual translation code.

Speed = BITRATE

For a serial connection, set to the serial port bitrate. To use the default value for the chosen interface, just set to 0.

CharMap = { hd44780_default | hd44780_euro | ea_ks0073 | sed12780f_0b | hd44780_koi8_r | hd44780_cp1251 | hd44780_8859_5 | upd16314 | none }

Set the character mapping depending on the display you have:

  • The default, hd44780_default, is for "classic" HD44780 displays.

  • hd44780_euro is for displays with a ROM mask supporting the european charset (ROM code A02).

  • ea_ks0073 is the charmap for Electronic Assembly's KS0073 based displays. These devices have a richer charset, including many icons and many more characters of the ISO-8859-1 than standard HD44780s.

  • sed12780f_0b is for some SED 1278 displays.

  • The none charmap does not translate any characters. It displays the characters the display controllers actually has stored in its CGROM for that position instead. This setting is intended for debugging purpose.

You only need to set this parameter if you have a non-standard HD44780 display or charmap.

If LCDproc was configured with '--enable-extra-charmaps' option the following character mappings are available, too:

  • hd44780_koi8_r maps input from a client in Russian KOI8-R to displays with a ROM mask supporting the european charset (ROM code A02).

  • hd44780_cp1251 maps input from a client in Russian CP1251 (Windows-1251) to displays with a ROM mask supporting the european charset (ROM code A02).

  • hd44780_8859_5 maps input from a client in Russian ISO 8859-5 to displays with a ROM mask supporting the european charset (ROM code A02).

  • upd16314 is for displays with a Nec uPD16314 vacuum fluorescent display (VFD) controller with ROM code 002 character set. If your display has ROM code 001 character set you may use the hd44780_euro charmap instead.

Tip

See server/drivers/hd44780-charset.h in LCDproc's source directory for the actual mappings.

Keypad = { yes | no }

Tell whether you have a keypad connected. You may also need to configure the keypad layout further on in this file.

Brightness = BRIGHTNESS

Set the initial brightness when the backlight is on for the lcd2usb connection type. Legal values are 0 - 1000, with 800 being the default.

OffBrightness = BRIGHTNESS

Set the initial off-brightness, i.e. the brightness when the backlight is off, for the lcd2usb connection type. The ilegal range is 0 - 1000. If not given, it defaults to 300.

Contrast = CONTRAST

Set the initial contrast for the bwctusb and lcd2usb connection types. Legal values for CONTRAST are 0 - 1000. If not given, it defaults to 500 which may be too low or too high for the selected connection type. So, if the screen is blank or dark, please try playing with the contrast a bit.

Backlight = { yes | no }

Specify if you have a switchable backlight.

OutputPort = { yes | no }

Tell if you have the additional output port ("bargraph") and you want to be able to control it with the lcdproc OUTPUT command.

Lastline = { yes | no }

Specifies whether the lowest pixel line of a character is pixel addressable or if it controls an underline effect. The default is yes, meaning a pixel addressable last pixel line.

Size = WIDTH x HEIGHT

Specifies the size of the LCD. Default: 20x4 In case of multiple combined displays, this should be the total size.

vSpan = HEIGHT ,

The "vertical span" when using the driver with multi-controller displays or with multiple displays that are treated as a single virtual display. It is a comma separated list of the heights of each display. In multi-controller displays it lists the number of lines each controller is responsible for.

E.g. vSpan=2,2,1 means you have three physical displays, the first two having two lines each, and the third having one line, that together form a virtual display that is 5 lines high.

The sum of the HEIGHTs must match the total height given in Size=.

ExtendedMode = { yes | no }

If you have a KS0073 or an other 'almost HD44780-compatible', set this flag to get into extended,4-line linear addressing mode.

LineAddress = ADDR

If the next line of your display doesn't start 0x20 higher in DDRAM you can override the default value of the ExtendedMode with this parameter.

DelayMult = DELAY

If your display is slow and cannot keep up with the flow of data from LCDd, garbage can appear on the LCDd. Set this delay multiplier to 2 or 4 to increase the delays. The default is 1 for a non-multiplied delay.

DelayBus = { yes | no }

You can reduce the inserted delays by setting this to no. On fast PCs it is possible your LCD does not respond correctly. Default: yes.

KeepAliveDisplay = SECONDS

Some displays (e.g. vdr-wakeup) need a message from the driver to indicate that it is still alive. When set to a value greater than 0 the character in the upper left corner is updated every SECONDS seconds. The default 0 does not cause any extra updates.

RefreshDisplay = SECONDS

If you experience occasional garbage on your display you can use this option as workaround. If set to a value greater than 0 it forces a full screen refresh every SECONDS seconds. Default: 0.

KeyDirect_NUM = KEY , KeyMatrix_X_Y = KEY

If you have a keypad you can assign keystrings to the keys. See the keypad section for used terms and the section on the specific connection type how to wire it.

To map, for example, the directly connected key 4 to the string Enter, use KeyDirect_4=Enter. For matrix keys use the X and Y coordinates of the key; e.g. KeyMatrix_1_3=Enter.

VendorID = VENDORID

USB vendor ID to look for in certain USB connection types. When using an FTDI chip with connection type ftdi, the default value is 0x4003. When using a USS720 chip with connection type uss720, the default value is 0x1293.

ProductID = PRODUCTID

USB product ID to look for in certain USB connection types. When using an FTDI chip with connection type ftdi, the default value is 0x6001. When using a USS720 chip with connection type uss720, the default value is 0x0002.

SerialNumber = SERIALNO

Serial number of the USB device to look for with connection type bwctusb. If not given, the first BWCT USB module found will be used.

Miscellanea

This text has originally been taken from a message by Bill Farrow .

Updated February 2000, Benjamin Tse

Updated October 2001, Joris Robijn

Converted to Docbook March 2002, Rene Wagner

Updated April 2002, Rene Wagner

Updated and extended April 2006 to November 2007, Peter Marschall

The i2500vfd Driver

This section talks about using LCDproc with an Intra2net Intranator 2500 VFD display. The displays are part of a custom high grade steel chassis and not sold separately. More information can be found here: Intra2net AG

It connects to USB using a FTDI FT245BM chip and therefore needs libftdi as requirement. libftdi can be found here: libftdi

Features

The display features a 140x32 pixel Noritake VFD tube which gets driven by an Atmel ATmega128 processor and used as a 23x4 character display with a 6x8 pixel font. It features B/W colors and two additional adjustable grayscale colors. It does hardware double buffering with up to 27 FPS and shows an animated boot logo until data is received from USB.

Options

There are currently no options for this driver.

The icp_a106 Driver

This section talks about using LCDproc with the ICP A106 alarm/LCD board, used in 19" rack cases by ICP.

Both LCD and alarm functions are accessed via one serial port, using separate commands. Unfortunately, the device runs at slow 1200bps and the LCD does not allow user-defined characters, so the bargraphs do not look very nice.

Configuration in LCDd.conf

[icp_a106]

Device = DEVICE

Sets the device to use. Defaults to /dev/lcd.

The imon Driver

General

The imon driver controls Soundgraph iMON VFD devices, that are either preinstalled or available as optional accessories for a variety of Home Theater PC (HTPC) cases from Ahanix, Silverstone, Cooler Master and others. They can also be bought separately and then fit into a 5,25" disk drive bay of any regular PC.

The iMON VFD sports a vacuum fluorescent display with 16x2 characters that connects to the computer using USB. Although the device is shipped with an IR remote control and some versions even have a volume knob, LCDproc's driver currently only supports the display part of the device.

In order to be able to use it, you have to get and install one of the following Linux kernel modules:

For further details, please consult the page and the forum at http://venky.ws/projects/imon/.

Configuration in LCDd.conf

[imon]

Size = WIDTH x HEIGHT

Set the display size. The default 16x2 should be safe for most if not all users, since the device seems to be made only with this one size. But who knows …

Device = DEVICE

Select the output device to use. Change this from the default /dev/lcd to the device file that gets created when the kernel module (see above) is loaded.

CharMap = { hd44780_euro | hd44780_koi8_r | hd44780_cp1251 | hd44780_8859_5 | upd16314 | none }

Set the character mapping depending on the display you have:

  • The default, hd44780_euro is for displays with a ROM mask supporting the european charset (ROM code A02).

  • The none charmap does not translate any characters and is only useful for debugging.

You only need to set this parameter if you have a non-standard charmap.

If LCDproc was configured with '--enable-extra-charmaps' option the following character mappings are available, too:

  • hd44780_koi8_r maps input from a client in Russian KOI8-R to displays with a ROM mask supporting the european charset (ROM code A02).

  • hd44780_cp1251 maps input from a client in Russian CP1251 (Windows-1251) to displays with a ROM mask supporting the european charset (ROM code A02).

  • hd44780_8859_5 maps input from a client in Russian ISO 8859-5 to displays with a ROM mask supporting the european charset (ROM code A02).

  • upd16314 is for displays with a Nec uPD16314 vacuum fluorescent display (VFD) controller with ROM code 002 character set. If your display has ROM code 001 character set you may use the hd44780_euro charmap instead.

Tip

See server/drivers/hd44780-charset.h in LCDproc's source directory for the actual mappings.

The imonlcd Driver

General

This section talks about using LCDproc with LCD devices manufactured by SoundGraph. For example, the iMON OEM LCD.

This driver currently supports versions 15c2:ffdc and 15c2:0038 of the device. (You can find the version of your LCD via the lsusb command).

In many systems, the LCD backlight will remain on after the system is shutdown. This behavior remains a mystery - somehow the LCD receives a reset command (or similar) AFTER LCDd is stopped.

This driver requires the iMON module included with LIRC v0.8.4a or newer, available from the LIRC project. The 15c2:0038 device may require LIRC v0.8.5 or newer.

Configuration in LCDd.conf

[imonlcd]

Protocol = PROTOCOL

Specify which version of iMON LCD is installed. The default, 0 specifies the :ffdc device. 1 should be used for the :0038 device.

OnExit = ONEXIT

Specify the exit behavior. The default is 1, which turns on the big ugly clock upon shutdown. 0 leaves the shutdown message on the screen. 2 turns the LCD off.

Device = DEVICE

Select the output device to use. Change this from the default /dev/lcd0 to the device file that gets created when the kernel module (see above) is loaded.

Contrast = CONTRAST

Select the display's contrast 200 is the default. Permissible values are in the range of 0-1000.

Size = WIDTH x HEIGHT

Set the display size in pixels. The default 96x16 should be safe for most if not all users, since the device seeems to be made only with this one size.

Backlight = BACKLIGHT

Set the backlight state. The default is 1, which turns the backlight on. 0 turns the backlight off.

DiscMode = DISCMODE

Sets the disc mode. The default is 0 which spins the "slim" disc. 1 spins their complement.

The IOWarrior Driver

General

IOWarrior is the name of a series of multi-purpose USB controller chips produced and sold by Code Mercenaries. This series currently consists of three main types, that - among other features - support controlling LCD displays:

IOWarrior24
  • USB 1.1 Low Speed

  • 16 generic I/O Pins, typ. 125Hz read rate

  • I2C master function, 100kHz, throughput typ. 750 bytes/sec

  • SPI master interface, up to 2MHz, throughput typ. 750 bytes/sec

  • control an HD44780 compatible LCD

  • drive a matrix of up to 8x32 LEDs

  • decode RC5 compatible infrared remote controls

IOWarrior40
  • USB 1.1 Low Speed

  • 32 generic I/O Pins, typ. 125Hz read rate

  • I2C master function, 100kHz, throughput typ. 750 bytes/sec

  • control an HD44780 compatible LCD

  • drive a matrix of up to 8x32 LEDs

  • drive a 8x8 switch or button matrix

IOWarrior56
  • USB 1.1 Full Speed

  • 50 generic I/O Pins, typ. 1000Hz read rate

  • I2C master function, 50, 100, or 400kHz

  • SPI master interface, up to 12MHz, throughput up to 62Kbytes/sec

  • control various display modules, including most graphic modules

  • drive a matrix of up to 8x64 LEDs

  • drive a 8x8 switch or button matrix

The IOWarrior driver currently only supports writing to a single-controller HD44780-type display. LED output using the output() function is also implemented, although not tested very well. The hardware's support for input using keys or IR and dual-controller displays is not implemented yet. Please note that the latter requires extra circuitry with IOWarrior24 and IOWarrior40.

The driver was developed and tested with IOWarrior24 and the IOWarrior40. Although there are good chances for it to work with an IOWarrior56, the current state regarding support of this chip is unknown due to the lack of the required hardware.

Requirements

The driver is based on the libusb USB library, which should make it work with Linux, the different BSD variants as well as Darwin/MacOS X.

Note

When using a libusb based driver like IOWarrior, LCDd needs to be started as root.

Note

Newer Linux kernels (2.6.20 and higher) provide a kernel module iowarrior.ko that allows controlling IOWarrior chips using device files. LCDd tries to unload this kernel module for libusb to be able to control IOWarrior devices. If this fails, this may hinder LCDd from starting using the IOWarrior driver. In this case, simply unload the kernel module by hand.

Configuration in LCDd.conf

[IOWarrior]

Size = WIDTH x HEIGHT

Set the display dimensions. If not given, it defaults to 20x4.

SerialNumber = SERIALNO

Use the IOWarrior module with the serial number SERIALNO. If this parameter is missing, the default is to use the first IOWarrior module found.

ExtendedMode = { yes | no }

If you have a KS0073 or an other 'almost HD44780-compatible' display connected to the IOWarrior, set this flag to get into extended, 4-line linear addressing mode

Lastline = { yes | no }

Specifies if the last line is pixel addressable or it controls an underline effect. The default yes means, it is pixel addressable.

The irman Driver

The irman driver allows you to use the IrMan IR remote control to control the LCDproc server LCDd and/or clients that can handle input.

The keys are mapped according to the following table:

Table 5.15. Mapping between LCDproc keys and IrMan commands

LCDproc keyIrMan command
Uplcdproc-Up
Downlcdproc-Down
Leftlcdproc-Left
Rightlcdproc-Right
Enterlcdproc-Enter
Escapelcdproc-Escape

Tip

If you have trouble using the irman driver, you might try the lirc driver. lirc supports IrMan as well.

Configuration in LCDd.conf

[IrMan]

Device = DEVICE

Select the input device to use, e.g. /dev/irman.

Config = FILENAME

Select the IrMan configuration file to use, e.g. /etc/irman.cfg.

The irtrans Driver

General

The irtrans driver controls IRTrans VFD devices, that are preinstalled in cases such as the Ahanix MCE303.

The IRTrans VFD sports a vacuum fluorescent display with 16x2 characters that connects to the computer using USB. Although the device is shipped with an IR remote control, LCDproc's driver currently only supports the display part of the device.

In order to be able to use it, you have to get and install the IRTrans irserver package from http://www.irtrans.de/en/download/linux.php.

Configuration in LCDd.conf

[irtrans]

Backlight = { yes | no }

Tell whether the device has a backlight, or whether the backlight shall be used. If not given, it defaults to no.

Hostname = HOSTNAME_OR_IP-ADDRESS

Set the hostname or IP address of the IRTrans device to connect to. If not set or set, the default is localhost.

Size = WIDTH x HEIGHT

Select the display size [default: 16x2]

The Joystick Input Driver

This section covers the joystick input driver for LCDd.

Configuration in LCDd.conf

[joy]

Device = DEVICE

Select the input device to use [default: /dev/js0]

Map_AxisNUMneg = KEY , Map_AxisNUMpos = KEY

Set the axis map.

NUM is an integer starting with 1 that represents each axis with the affixes neg and pos determining the direction. The exact numbering of the axes depends on the hardware used.

KEY can be one of the keys that LCDd recognizes (Left, Right, Up, Down, Enter or Escape) or any other string that a client can parse.

Map_ButtonNUM = KEY

Set the button map.

NUM is an integer starting with 1 that represents each button. The exact numbering of the buttons depends on the hardware used.

KEY can be one of the keys that LCDd recognizes (Left, Right, Up, Down, Enter or Escape) or any other string that a client can parse.

The lb216 Driver

This section talks about using LCDproc with LCD displays that use the lb216 chipset.

Heres a bit more info on the display.
It is the LB216 and is made by R.T.N. Australia
The web page for it is http://www.nollet.com.au/
It is a serial 16x2 LCD with software controllable backlight.
They also make 40x4 displays (which I'll be getting one of soon :-) )
3 wire connection (5V,0V and serial), 2400 or 9600 bps.
8 custom characters
40*83.5MM size
made in australia :-)

Configuration in LCDd.conf

[lb216]

Device = DEVICE

Select the output device to use [default: /dev/lcd]

Brightness = BRIGHTNESS

Set the initial brightness [default: 255; legal: 0 - 255]

Speed = { 2400 | 9600 }

Set the the baud rate to use when communicating with the LCD. If not given, the default is 9600.

Reboot = { yes | no }

Reinitialize the LCD's BIOS [default: no; legal: yes, no]

The lcdm001 Driver

This section talks about using LCDproc with serial LCD displays from kernel concepts.

Configuration in LCDd.conf

[lcdm001]

Device = DEVICE

Default: /dev/lcd

PauseKey = KEY , BackKey = KEY , ForwardKey = KEY , MainMenuKey = KEY

keypad settings

key namefunction (normal context)function (menu context)
PauseKeyPause/ContinueEnter/select
BackKeyBack(Go to previous screen)Up/Left
ForwardKeyForward(Go to next screen)Down/Right
MainMenuKeyOpen main menuExit/Cancel

You can rearrange the settings here.

If your device is broken, have a look at server/drivers/lcdm001.h

The lcterm Driver

This section talks about using LCDproc with serial LCD displays from Helmut Neumark Elektronik.

Configuration in LCDd.conf

[lcterm]

Device = DEVICE

Default: /dev/lcd

Size = WIDTH x HEIGHT

Default: 16x2.

The lirc Driver

The lirc driver enables you to use any IR remote control that works with LIRC to control the LCDproc server LCDd and/or clients that can handle input.

Of course you need a working LIRC setup. Refer to the LIRC project for more information on LIRC itself.

Checking Your LIRC Setup

Basically all you need is a running lircd. And of course you have to start lircd as root.

Also, make sure that the permission of /dev/lircd are correct.

Build LCDd with the lirc Driver

You need to add lirc to the --enable-drivers=... list.

Then simply run make.

Configure LCDd to Use the lirc Driver

First of all you need to activate the driver by adding a Driver=lirc line to your LCDd.conf

Example 5.4. LCDd.conf: Activate the lirc driver

 Driver=mtxorb
 Driver=lirc

This activates the mtxorb driver as the output driver and the lirc driver as the input driver.

Then you have to modify the [lirc] section of your LCDd.conf.

Configuration in LCDd.conf

[lirc]

lircrc = FILENAME

Normally all LIRC clients scan the file ~/.lircrc. However, you might want to have a separate file to configure the LCDproc lirc driver only.

This option enables you to specify the file you want the lirc driver to scan. If not given it defaults to ~/.lircrc.

Prog = PROGRAM

All LIRC keys are assigned to a program using the prog=... directive in the lirc configuration file.

PROGRAM must be the same as in your lirc configuration file.

Modify Your ~/.lircrc

As mentioned above you can either modify the ~/.lircrc or use a separate file for the lirc LCDproc driver (See above for details).

No matter which file you use, you have to add at least the following lines to the file:

Example 5.5. ~/.lircrc: Specify the associations from buttons to keys for the lirc driver

begin
        prog = lcdd
        button = 2
        config = Up
end

begin
        prog = lcdd
        button = 4
        config = Left
end

begin
        prog = lcdd
        button = 6
        config = Right
end

begin
        prog = lcdd
        button = 8
        config = Down
end

begin
        prog = lcdd
        button = 1
        config = Escape
end

begin
        prog = lcdd
        button = 0
        config = Enter
end

Which buttons you specify here depends on your remote control and your LIRC configuration.

The config values need to be one of Up, Down, Left, Right, Escape or Enter. For LCDd's server menu at least the keys Up, Escape and Enter are necessary.

Of course you can define other keys. Those keys will not be handled by the server but sent to a client. Refer to the documentation of the client you want to use, to find out which keys are necessary for that client.

The lis Driver

This section talks about using LCDproc with the VLSystem L.I.S MCE 2005 Vacuum Fluorescent Display (VFD) based on the FTDI USB-to-serial converter, the Microchip PIC-16F716 microcontroller, and the NEC UPD16314 display driver manufactured by VLSystem.

Features

This device uses a vacuum fluorescent display of 20 characters by 2 lines. Each each character is 5 pixels wide by 8 pixels high. The device is connected by USB. The FTDI chip translates the USB protocol to serial expected by the VFD driver chip, an NEC UPD16314. A programmable interrupt controller (PIC), the PIC16F716 by Microchip, provides the glue between the FTDI and the NEC chips.

Requirements

The driver depends on libftdi, version 0.8 or higher, from http://www.intra2net.com/en/developer/libftdi/.

libftdi itself depends on the libusb USB library.

Note

When using a libusb based driver like lis, LCDd needs to be started as root.

Configuration in LCDd.conf

[lis]

Size = WIDTH x HEIGHT

Set the display size. The default 20x2 should be safe for most if not all users, since the device seems to be made only with this one size. But who knows …

VendorID = VENDORID

The USB Vendor ID of the device to use. If not given, it defaults to 0x0403 for a VLSystems L.I.S. MCE 2005 VFD based on a FT232BL USB-to-RS232 converter by FTDI, which was produced before March 2007.

It is usually not necessary to specify a VENDORID. Please do so only if you want to test a compatible device.

ProductID = PRODUCTID

The USB Product ID of the device to use. If not given, it defaults to 0x6001 for a VLSystems L.I.S. MCE 2005 VFD based on a FT232BL USB-to-RS232 converter by FTDI, which was produced before March 2007.

It is usually not necessary to specify a PRODUCTID. Please do so only if you want to test a compatible device.

Brightness = BRIGHTNESS

Set the initial brightness [default: 1000; legal: 0 - 1000. Values between 0 and 250 give 25% brightness, 251 to 500 give 50% brightness, 501 and 750, give 75% brightness, and values higher than 751 give 100% brightness.

The MD8800 Driver

This section talks about using LCDproc with VFD displays in Medion MD8800 PCs.

Features

You may find more information about the LCD on Martin Moeller's homepage.

Configuration in LCDd.conf

[MD8800]

Device = DEVICE

device to use [default: /dev/ttyS1]

Size = WIDTH x HEIGHT

display size [default: 16x2]

Brightness = BRIGHTNESS

Set the initial brightness [default: 1000; legal: 0 - 1000]

OffBrightness = BRIGHTNESS

Set the initial off-brightness [default: 0; legal: 0 - 1000] This value is used when the display is normally switched off in case LCDd is inactive

The mdm166a driver

Markus Dolze

This section talks about using LCDproc with the Futaba / Targa USB Graphic Vacuum Fluorescent Display (MDM166A; USB VID=0x19c2, PID=0x6a11).

The MDM166A is a graphical VFD with a 96x16 pixel dot matrix area which is used for 16x2 characters with a 6x8 pixel font. It features several icons, volume level and WLAN strength indicator which are all software controllable using the output function.

The mdm166a driver builds on top of libhid which in turn uses libusb.

The driver was developed by Christoph Rasim (http://www.rasim.net/) without any available documentation from the vendor, but with a good protocol description from Thomas Koos (http://www.muetze1.de) created by reverse engineering the protocol.

Configuration in LCDd.conf

[mdm166a]

Clock = TYPE

Show self-running clock after LCDd shutdown. Possible values for TYPE are no, small and big. If not given no clock is shown.

Dimming = { yes | no }

Dim display, no dimming gives full brightness.

OffDimming = { yes | no }

Dim display in case LCDd is inactive.

Using the icons

The icons, the volume bar and the WLAN indicator supported by the VFD can be controlled by use of the output function.

The on parameter is used as a bitmask to control which elements to display. Setting an icon bit to 1 enables the icon, setting the bit to 0 disables an icon. Volume and WLAN strength indicator accept an numeric value in the given bit mask.

Table 5.16. mdm166a_output bitmask

bit(s)Icon
0Play
1Pause
2Record
3Message
4Mail (at-symbol)
5Mute
6WLAN tower
7Volume (the word)
8…12Volume (decimal 0…28)
13…14WLAN strength (0…3)

Special device hints

This display may appear as a HID device in your system which may prevent libhid from being able to open the USB device. In this case you have to create some OS-specific configuration to prevent the HID driver to take control of this display.

Configuring FreeBSD 7.x to exclude this device from uhid

To make the uhid driver ignore this device you have to apply the following patch to your kernel source and recompile and install your kernel:


--- sys/dev/usb/usbdevs.orig    2010-11-24 02:06:30.000000000 +0100
+++ sys/dev/usb/usbdevs 2010-11-24 07:36:38.000000000 +0100
@@ -623,6 +623,7 @@
 vendor AMIT            0x18c5  AMIT
 vendor QCOM            0x18e8  Qcom
 vendor LINKSYS3                0x1915  Linksys
+vendor TARGA           0x19c2  Targa Corporation
 vendor QUALCOMMINC     0x19d2  Qualcomm, Incorporated
 vendor STELERA         0x1a8d  Stelera Wireless
 vendor DRESDENELEKTRONIK 0x1cf1 dresden elektronik
@@ -2343,6 +2344,9 @@
 /* System TALKS, Inc. */
 product SYSTEMTALKS SGCX2UL    0x1920  SGC-X2UL

+/* Targa Corporation */
+product TARGA VFD              0x6a11  Targa USB Graphic VFD
+
 /* Tapwave products */
 product TAPWAVE ZODIAC         0x0100  Zodiac

--- sys/dev/usb/usb_quirks.c.orig       2010-11-24 02:07:03.000000000 +0100
+++ sys/dev/usb/usb_quirks.c    2010-11-24 02:16:30.000000000 +0100
@@ -112,6 +112,8 @@
        ANY, { UQ_HID_IGNORE }},
  { USB_VENDOR_APPLE, USB_PRODUCT_APPLE_IPHONE_3G,
        ANY, { UQ_HID_IGNORE }},
+ { USB_VENDOR_TARGA, USB_PRODUCT_TARGA_VFD,
+       ANY, { UQ_HID_IGNORE }},

  /* Devices which should be ignored by both ukbd and uhid */
  { USB_VENDOR_CYPRESS, USB_PRODUCT_CYPRESS_WISPY1A,

The ms6931 Driver

This section talks about using LCDproc with LCD displays that use the ms6931 chipset.

Configuration in LCDd.conf

[ms6931]

Device = DEVICE

device to use [default: /dev/ttyS1]

Size = WIDTH x HEIGHT

display size [default: 16x2]

The mtc_s16209x Driver

This section talks about using LCDproc with LCD displays that use the mtc_s16209x chipset.

Configuration in LCDd.conf

[mtc_s16209x]

Device = DEVICE

Select the output device to use [default: /dev/lcd]

Brightness = BRIGHTNESS

Set the initial brightness [default: 255; legal: 0 - 255]

Reboot = { yes | no }

Reinitialize the LCD's BIOS [default: no; legal: yes, no]

The MtxOrb Driver

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.

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.

Configuration in LCDd.conf

[MtxOrb]

Device = DEVICE

Select the output device to use [default: /dev/lcd]

Size = WIDTH x HEIGHT

Set the display size [default: 20x4]

Type = { lcd | lkd | vfd | vkd }

Set the display type [default: lcd; legal: lcd, lkd, vfd, vkd]

Contrast = CONTRAST

Set the initial contrast. Legal values for CONTRAST are 0 - 1000. If not given, the default value is 480.

Note

The driver will ignore this setting if the display is a VFD or VKD as they do not support this feature.

hasAdjustableBacklight = { yes | no }

Some old firmware versions of Matrix Orbital modules do not support an adjustable backlight but only can switch the backlight on/off. If you own such a module and experience randomly appearing block characters and backlight cannot be switched on or off, use this to no [default: yes].

Brightness = BRIGHTNESS

Set the initial brightness [default: 1000; legal: 0 - 1000]

OffBrightness = BRIGHTNESS

Set the initial off-brightness [default: 0; legal: 0 - 1000] This value is used when the display is normally switched off in case LCDd is inactive

Speed = { 1200 | 2400 | 9600 | 19200 }

Set the the baud rate to use when communicating with the LCD. If not specified, it defaults to 19200.

KeyMap_LETTER = KEY

Matrix Orbital displays support keypads with up to 25 keys, which return one of the letters A - Y for each pressed key.

These settings allow to map the letter LETTER, that is generated by the display when a key is pressed, to be mapped to a key name KEY that LCDd can understand (see LCDd.conf: The [Menu] Section for more information).

There is no default key mapping; if no keys are mapped in the LCDd.conf config file, the display is treated as if it had no keys attached.

Example 5.6. Matrix Orbital: keymap config

      KeyMap_A=Left
      KeyMap_B=Right
      KeyMap_C=Up
      KeyMap_D=Down
      KeyMap_E=Enter
      KeyMap_F=Escape
      

keypad_test_mode = { yes | no }

You can find out which key of your display sends which character by setting keypad_test_mode to yes and running LCDd. LCDd will output all characters it receives. Afterwards you can modify the settings above and set keypad_set_mode to no again.

The MX5000 Driver

This section talks about using LCDproc with LCD displays on Logitech MX5000 keyboards.

Features

This drivers uses the library from mx5000tools.

Configuration in LCDd.conf

[mx5000]

Device = DEVICE

Select the output device to use [default: /dev/hiddev0]

WaitAfterRefresh = MS

Set the time (in ms) to wait after each screen sent to the keyboard. Default is 1000ms.

The NoritakeVFD Driver

This section talks about using LCDproc with text mode VFD displays from Noritake Itron.

Configuration in LCDd.conf

[NoritakeVFD]

Device = DEVICE

Port where the VFD is. Usual values are /dev/ttyS0 and /dev/ttyS1 Default: /dev/lcd

Size = WIDTH x HEIGHT

Specifies the size of the LCD. Default: 20x4

Brightness = BRIGHTNESS

Set the initial brightness [default: 1000; legal: 0 - 1000]

OffBrightness = BRIGHTNESS

Set the initial off-brightness [default: 0; legal: 0 - 1000] This value is used when the display is normally switched off in case LCDd is inactive

Speed = { 1200 | 2400 | 9600 | 19200 | 115200 }

Set the the baud rate to use when communicating with the VFD. If not specified, it defaults to 9600.

Parity = { 0 | 1 | 2 }

Set the parity for communication with the device to even parity (2), odd parity (1) or no parity (0). If not given, it defaults to 0.

Reboot = { yes | no }

Reinitialize the VFD [default: no; legal: yes, no]

The Mini-Box.com USB LCD picoLCD Driver

This section covers the use of the Mini-Box USB LCD displays.

Displays

Mini-Box.com offers two types of USB LCD displays:

PicoLCD 4x20-Sideshow

PicoLCD 4x20-Sideshow is the desktop variant targeted at end users. It is an external USB 2.0 full speed device that comes in a stylish case and sports a 4 line by 20 character display with white letters on a blue background, a built-in InfraRed receiver as well as a keypad with 8 keys labelled Escape, F1, F2, F3, Home, Up, Down and Enter.

picoLCD 20x2 (OEM)

picoLCD-20x2-OEM is the OEM version. It is a 2 line by 20 character display with black letters on a yellow-green background, that can be connected to the system via USB, I2C or USART (the latter two are not supported by this driver). It has connectors for an InfraRed receiver, keypad and LEDs.

When pre-installed in enclosures like the Mini-Box M300 LCD it comes equipped with an InfraRed receiver as well as key pad with 12 keys labeled Plus, Minus, F1, F2, F3, F4, F5, Up, Down, Left, Right, and Enter.

Finally, the picoLCD 20x2 (OEM) supports 8 general purpose outputs and 10 custom splash screens. Although these features are not supported by this driver, the splash screens can be changed using the usblcd tool, that can be built from the Linux SDK available on the picoLCD web page.

Requirements

The driver is based on the libusb USB library, which should make it work with Linux, the different BSB variants as well as Darwin/MacOS X.

Note

When using a libusb based driver like picolcd, LCDd needs to be started as root.

On Linux, the only kernel module required is the USB host controller driver (uhci_hcd on the M300) to fire up the USB bus to which the LCD is attached. For other operating systems, analogous requirements apply.

Lastly, for libusb to work correctly, the usbfs file system must be mounted on /proc/bus/usb, e.g. using the command mount -t usbfs usbfs /proc/bus/usb or by your system's default configuration.

Configuration in LCDd.conf

[picolcd]

Note

The Brightness and OffBrightness settings only have an effect on the 20x4 device. With the 20x2 device the backlight can only be set on (any value greater than 1000) or off (0).

Backlight = { yes | no }

Turns the backlight on or off on start-up, default yes.

Brightness = BRIGHTNESS

Set the initial brightness if the backlight is on. Legal values are: 0 - 1000. If not given, it defaults to 1000.

OffBrightness = OFFBRIGHTNESS

Set the initial value for the backlight if it is off. Legal values are: 0 - 1000. If not given, it defaults to 0.

Contrast = CONTRAST

Contrast: 0-1000, default to 1000 (full contrast).

KeyLights = { yes | no }

Allow key LEDs to be turned on or off. Default is yes. This setting affects all keys. If set to on each key can be disabled independently by setting KeyXLight below.

Key0Light = { yes | no }

If Keylights is set, you can disable the directional pad LED by setting this value to no. Default is yes.

Key1Light = { yes | no }

If Keylights is set, you can disable the F1 LED by setting this value to no. Default is yes.

Key2Light = { yes | no }

If Keylights is set, you can disable the F2 LED by setting this value to no. Default is yes.

Key3Light = { yes | no }

If Keylights is set, you can disable the F3 LED by setting this value to no. Default is yes.

Key4Light = { yes | no }

If Keylights is set, you can disable the F4 LED by setting this value to no. Default is yes.

Key5Light = { yes | no }

If Keylights is set, you can disable the F5 LED by setting this value to no. Default is yes.

KeyTimeout = DURATION

This value controls how long LCDd waits for a key press when get_key() is called. The value represents milliseconds and the default is 500 or .5 seconds. Lowering this value will make LCDd more responsive but also causes LCDd to use more CPU time and, as the timeout grows shorter, key presses become harder to detect. Large values make key presses more reliable but may slow down LCDd. Values in the range 0-1000 (1s) are allowed.

LircHost = HOSTNAME_OR_IP-ADDRESS

Set the hostname or IP address to which the driver will send IR data from the sensor. If not set or set to an empty value, IR support for LIRC will be disabled.

LIRC should be configured to use the driver "udp", which will cause it to listen on some UDP port for packets containing a series of integers, representing pulse and mark intervals from the sensor. It doesn't matter whether LCDd or LIRC is started first; if LIRC isn't listening, the packets from LCDd will be discarded. When LIRC comes back, it will start picking up the packets. Similarly, LCDd can be stopped and restarted without affecting anything, because UDP is a connectionless protocol.

LircPort = PORTNUM

This value determines the UDP port to which the driver will send IR data from the sensor. It defaults to 8765, which is also the default port on which LIRC will listen.

LircFlushThreshold = DURATION

This value is the length in jiffies (1/16384 seconds) of the synthesized sync space that will trigger sending the queued IR data to LIRC. Values up to 32767 (2s) are permitted, values lower than 16 will suppress the flushing IR data during processing. The default is 100 jiffies (6.1ms). It's should only be needed to change this value when lircd.conf has a gap < 6100 or the samples > 6300.

picolcd driver status

The hardware also reports key-up events. Normally this would be of no issue (they are usually a 0 or 'no key') except that when keys are used in combination, the key-up event may actually come back as multiple events depending on how the user released the keys. If the key-up event for a multiple key press comes back as two events, the first up event will actually look like a new key press. The algorithm in get_key tries to deal with this in a sane way and toss out all key-up events for now. The hardware is touchy and both combo key-down and key-up actions may be reported as multiple events if the user is more than a tenth of a second (maybe less?) off in motions.

Infrared sensor status

LIRC expects sensor data that starts with a longish 'sync' space, denoting the start of a command; followed by the code data, a sequence of mark/space pairs; sometimes followed by a 'gap', which should be a space long enough to make the entire command up to a preset duration in milliseconds. The 'sync' and the 'gap' are absent from the data emitted by the picolcd hardware. I found that LIRC configuration files for remotes similar to the ones I tested all used such a fixed-duration encoding, and as that was the only way I could get it working, this driver by default adds the gap as well as the sync. However I have still had trouble getting irrecord to work; you need at least to feed it a template configuration containing sync and gap data.

Copyright

The lcdproc picolcd driver originally was written by Gatewood Green (woody@nitrosecurity.com) or (woody@linif.org) and paid for by NitroSecurity, Inc (nitrosecurity.com), but has been extended with code from various contributors since then.

The pyramid Driver

Stefan Reinauer

This section talks about using LCDproc with programmable LC displays sold by Pyramid Computer.

Pyramid Computer builds these LC displays into its thriving server products to show system data, and to allow the user to change important parameters or shut down the appliance in a controlled manner. The LCD module, accessible via USB, can be integrated by Pyramid's BTO server and appliance manufacturing division at the customer's request or it can be made available separately for self-integration, e.g. as a 5.25" module.

Features

The displays are 16 characters wide and 2 lines high. They have 4 programmable buttons as well as 3 (or 9) LEDs which can also be software controlled.

Connector

The display is connected to the host system using USB, with the usual USB pinout as shown below. The +5V VCC pin is marked with red colour.

Table 5.17. USB Pinout

GNDD+D-VCC
GNDP0+P0-+5V

Requirements

For Linux the driver depends on features of the ftdi_sio.ko that have only been added to version 2.6.15 version of the 2.6 kernel series. For older Linux kernels of the 2.6 series these patches to ftdi_sio.c may help:

LED output

I've added support for the LEDs on the Pyramid LC-Display to the "pyramid" driver of lcdproc.

Since it seems that LEDs on an LCD are not directly supported by the lcdproc API I've used the "output" command of the server to trigger the LEDs, similar to what the IOWarrior driver does.

The Pyramid LC displays come in two different versions, with 3 and with 9 LEDs. Two of these LEDs can not be controlled by software but are usually hard wired to power and HDD. The other 1 or 7 LEDs can now be controlled by sending an output command to the server.

The argument to the output command is a bitmask that controls the LEDs according to the table below:

Table 5.18. Mapping of output bits to LEDs

BitLED
03
14
25
36
47
58
69


For the LCDd server there is no way to find out whether 3 or 9 LEDs are available, so it is up to the client software to do the right thing.

Example 5.7. Pyramid: How to use the LED output from the client

telnet localhost 13666
hello
output 67

will light up LEDs 3, 4 and 9.

output 0

will clear all LEDs.


More information on the Pyramid LC-Display can be found here: http://www.pyramid.de/en/products/specialities.php

Configuration in LCDd.conf

[pyramid]

Device = DEVICE

Device to connect to. Default: /dev/lcd

The sed1330 Driver

This section talks about using LCDproc with graphical LCD displays driven by the EPSON/SMOS SED1330 or SED1335 LCD controllers, which may also be known by their new names: S1D13300 (= SED1330) and S1D13305 (= SED1335).

The displays are driven in text mode using their built-in character generator and the graphic mode for bars and the heartbeat icon (a bouncing ball).

Connections

Warning

Displays using SED1330/1335 chipset come in a variety of pin-outs and power configurations. They usually require negative voltage for contrast and some displays have a negative voltage generator onboard.

Connections below are for the G242C, G121C and G321D displays. Always consult documentation about the specific display before assuming the connections given here are also correct for your display!

Table 5.19. ConnectionType classic ordered by LPT port pins

LPT port<->LCD
pinnamenamepin
1^STROBE ^RESET1
2-9D0-D7 D0-D78-15
16^INIT ^WR3
17^SELECT_IN A07
18-25GNDGNDVEE17
  +5V^RD2
  GNDSEL14
  GNDSEL25
  GND^CS6
  +5VVCC16
  potentiometerV018
  -24V (not required for G242C)VLC19
  GNDFGND20

Table 5.20. ConnectionType bitshaker ordered by LPT port pins

LPT port<->LCD
pinnamenamepin
1^STROBE ^WR3
2-9D0-D7 D0-D78-15
14^LF A07
16^INIT ^RESET1
18-25GNDGNDVEE17
  +5V^RD2
  GNDSEL14
  GNDSEL25
  GND^CS6
  +5VVCC16
  potentiometerV018
  -24V (not required for G242C)VLC19
  GNDFGND20

The potentiometer should be connected like this on these display modules:


	=== GND
	 |
	.-.
	| |
	| |5k
	'-'
	 |
	 |
	.-.10k potentiometer
	| |
	| |<----------------o V0
	| |
	'-'
	 |
	 O Vlc (= -24V)

The G242C generates -24V internally. It is available on Vlc.

To generate -24 from the +5V without an external power source, you can use the following circuit.


 5V O------+----------+                                 pinout:
           |          |                                  _____
           |         --- 100uF                          |  _  |
           |         --- 10V                            | (_) | <-3
           |          |                                 |_____|
           |          +--------+--------+--------+      | max |
           |5         |        |        |        |      | 724 |
       ---------     === GND   C        -        |      |_____|
      |         |              C coil  | |       |       |||||
      |         |              C 47uH  | |10k    |       |||||.
      |         |4             |        -        |       | | |
      | MAX724  |--------------+        |        |       12345
      |   or    |              |        |        |
      | MAX726  |1             |        |        |+
      |         |-----------------------+       --- 47uF
      |         |              |        |       --- 50V
      |         |              |        |        |
       ---------               |        -        |
        |2    |3               |       | |       |
        |     |              '---,     | |1k     |
       ---    |        SB160  / \       -        |
  100nF---    |               ^T^       |        |
        |     |                |        |        |
        +-----+----------------+--------+--------+----O -24V out

Keypad

The sed1330 driver supports the same direct keys and matrix keypad connections as the hd44780 driver. See the section called “Keypad”.

Configuration in LCDd.conf

[sed1330]

CellSize = WIDTH x HEIGHT

Specify the size of a character in pixels. WIDTH may vary between 6 and 8; legal values for HEIGHT range from 7 to 16. If not given CellSize defaults to 6x10.

Contrary to other drivers the character size of an LCD using the sed1330 driver is not given directly. Instead it is determined by the pixel size of the display, which is derived from the display type setting and the character cell size specified with this setting.

ConnectionType = { classic | bitshaker }

Select the type of the wiring, see the section called “Connections”.

If not given, it defaults to classic.

Port = PORT

Specify the address of the parallel port the LCD is connected to. Common values for PORT are 0x278, 0x378 and 0x3BC. If not given, it defaults to 0x278.

Type = { G321D | G121C | G242C | G191D | G2446 | SP14Q002 | HG25504 }

Type of LCD module. Besides other things (internal setup) this configuration setting determines the size of the display in pixels.

TypeSize (in pixels)
G321D320 x 200
G121C128 x 128
G242C240 x 128
G191D192 x 192
G2446240 x 64
SP14Q002320 x 240
HG25504320 x 240

Note

Currently the G321D and SP14Q002 are the only ones that this driver is tested with.

The sed1520 Driver

This section talks about using LCDproc with LCD displays that use the SED1520 chipset.

Currently the driver supports 122x32 pixel graphic displays based on the SED1520 controller connected to the parallel port.

Note

Those SED1520 displays are the most troublesome I have ever used. You should probably avoid using them and get a 20x4 text display instead.

Connections

Warning

Displays using SED1520 come in a wide variety of configurations. It is possible to cause harm to your display (e.g. connecting negative voltage incorrectly. Be sure to check your datasheet! Do not try to use a display without having a datasheet to check against!

Here here some of the options I encountered:

  • Negative voltage: The chip requires negative voltage for driving the display. Some display modules have a negative voltage converter on-board. On those that don't you have to supply about -7 V (will not show how to do this).

  • Reset circuit: Some display modules have an R/C-combination on-board selecting an MCU interface if the pin is not connected.

  • Frequency generator: The SED1520 is manufactured in several versions. Some contain an on-chip frequency generator, others require an external clock of 2 kHz (won't show this here). Note that display modules with an on-chip generator do not have a /CS (chip select) line.

  • Incorrect datasheets: I have seen display datasheets incorrectly naming pins, missing some of the commands, missing pages from the chip description and other odds. Be warned!

  • No pin numbers are given in the tables below. You have to figure out those yourself from the datasheet for your display!

That said here some wirings:

80-style connection style

This mode of operation is selected if the RESET line is wired to ground. The wiring used by this driver in 80-style mode requires the use of an external 74HC04 inverter and assumes you have /CS1 and /CS2 lines available (thus you must have an external clock generator) and toggles the /RW line. This is the original wiring by Robin Adams.

Table 5.21. SED1520 80-style wiring schematic

Parallel port<->LCD
namepinnamepin
D0-D72-9 DB0-DB7*
nSTRB1 /WR*
nLF14 /CS1*
INIT16 /CS2*
nSEL17 A0*
  VDD/RD*
  GNDRESET/IF*
  2 kHz clockCL*

68-style connection style

This mode of operation is selected if the RESET line is wired to VDD. For this wiring the display is required to have an on-board frequency generator (something you really want to have) and the display module has an E1 and E2 line. Writing is controlled by toggling the E1 and E2 line while /RW is low.

Table 5.22. SED1520 68-style wiring schematic

Parallel port<->LCD
namepinnamepin
D0-D72-9 DB0-DB7*
nSTRB1 R/-W*
nLF14 E1*
INIT16 E2*
nSEL17 A0*
  VDDRESET/IF*

Note

This is the only wiring I was able to test. My display (Crystalfontz CFAG12232J-TFH-TA) has E1 and E2 lines. Trying to use it with 80-style wiring was not successful. I suspect that (as the E# line is used as /RD line in 80-style mode) the wiring resulted in reading from one chip while writing to the other at the same time and the data bus got fuzzed.

Configuration in LCDd.conf

[sed1520]

Port = PORT

Specify the address of the parallel port the LCD is connected to. Common values for PORT are 0x278, 0x378 and 0x3BC. The default value is 0x378.

InterfaceType = INTERFACE

The SED1520 chip can be driven with one of two interface types selected by the level of the RESET line: 68-style MCU interface (high level) or 80-style MCU interface (low level).

Use value 68 if your display is connected 68-style style. In this mode the E1 and E2 lines are cycled to write the data. If you use 80 (the default), 80-style style is selected and the /WR line is cycled and /CS1 and /CS2 lines are required.

DelayMult = DELAY

This value adds an additional delay to each write, in microseconds. For the 80-style connection type actual two delays are added each. The default value of 1 already slows down communication a lot, larger value should likely be avoided.

The serialPOS Driver

This section talks about using LCDproc with a point of sale ("POS") character-display.

The serialPOS driver is currently working with the AEDEX emulation protocol, and may support Epson ESC/POS and Logic Controls. It can be extended to work with various other protocol displays.

The driver should operate most character POS displays with a serial (RS-232) input. Because these displays use a standardized protocol, if the protocol is supported by your display, it should work as expected. Feedback is welcome.

Table 5.23. serialPOS: Emulation Protocol Status

ProtocolDisplay testedCurrently SupportedRemark
AEDEXEmaxYes
IEE No
EpsonNoYes
Emax No
IBM No
Logic ControlsNoYes
Ultimate No


(): Feature not tested.

Connecting The Display

Connecting the display should consist of simply plugging it into your computer's RS-232 serial port. Because these displays typically support full RS-232, no additional wiring is needed. If your computer does not have such a port (many newer computers don't), you can use a USB to serial adapter with a driver provided by the adapter manufacturer.

If your display supports a pass-through function, you can connect an RS-232 keyboard or terminal to the pass-through port. This will allow you to input keystrokes to LCDproc and control features and menus. Use the pass-through keyboard's arrow, delete, and return keys by default.

Note

If your display supports a pass-through function, but you do not have another RS-232 device connected to the pass-through port, you may experience hangs if an improperly formatted command sneaks through. This is because the display is waiting for the pass-through device to accept the data and a blocking state is created within the display. You can either connect another RS-232 device or use a wire to jumper the CTS and RTS pins together within the display.

Configuration in LCDd.conf

[serialPOS]

Device = DEVICE

Device to use in serial mode. Usual values are /dev/ttyS0 or /dev/cu.usbserial. Default is /dev/lcd.

Size = WIDTH x HEIGHT

Specifies the size of the VFD in characters. If not given, it defaults to 16x2.

Type = { IEE | AEDEX | Epson | Emax | IBM | LogicControls | Ultimate }

Set the communication protocol to use with the POS display. If not specified it defaults to AEDEX. Currently, only AEDEX is supported.

Speed = { 1200 | 2400 | 9600 | 19200 | 115200 }

Set the the baud rate communication with the POS display. If not given the default of 9600 is used.

The serialVFD Driver

This section talks about using LCDproc with VFD character-displays build by NEC, FUTABA and NORITAKE.

The serialVFD-driver is working with NEC FIPC8367 based VFDs and the "KD Rev 2.1" (an ATMEL AT90S.... based FM20X2KB-AB replacement). It is also known to work on FUTABA VFDs.

The driver should operate most of NEC, Futaba and Noritake 7x5 dot VFDs with serial(RS-232) and/or parallel interface. See the following table for testing-status. Feedback is welcome.

Table 5.24. serialVFD: Display Status

DisplayControllerSerialParallelDisplay testedTypeRemark
NEC FM20X2KB-ABNEC FIPC8367OkOkYes0
NEC FC20X2JANEC FIPC8367(Ok)[1] (Ok)[1]No0Same Controller as on FM20X2KB-AB
NEC FC20X1SA-AB/AANEC FIPC8367(Ok)[1](Ok)[1]No0Same Controller as on FM20X2KB-AB
KD Rev 2.1AT90S.... microcontrollerOk-Yes1, 0[2]
FUTABA M402SD06GJ?(?)[1]OkYes3The display has no user-characters. Serial interface with PC compatible baudrate is optional only, feature not tested.
FUTABA M204SD01AAFUTABA 5P00A016(Ok)[1](Ok)[1]No3
Futaba NA202SD08FA?OkOkYes6almost IEE compatible, no Custom-Characters
Samsung 20S204DA2 and 20S207DA1?OkOkYes3[2], 7[2][1] The display is FUTABA compatible (hard- and software). Custom-Characters not supported(?).
Samsung 20S207DA4 and 20S207DA6?OkOkYes7, 3[2]almost Futaba compatible
Noritake CU20026SCPB-Tmicrocontroller(Ok)[1](Ok)[1]No2
Noritake CU20045SCPB-T28A?(Ok)[1](Ok)[1]No2
IEE 36657-01 (= 02S-93290-VFD 36657-01)?OkOkYes4
IEE S03601-95B?(Ok)[1](Ok)[1]No4
IEE S03601-96-080?(Ok)[1](Ok)[1]No5
Siemens/Wincor Nixdorf BA63/66?Ok-Yes8Display needs different connection, see below! no Custom-Characters, no brightness-control

[1] Should work, but feature not tested yet.

[2] Custom-Characters are not supported with this Type, set Custom-Characters=0 in LCDd.conf.


If your display isn't working 100% satisfactorily you can add a new device with modified hardware commands to the driver if you want. To do that you have to add a new section to the display Type-switch-case in ./server/drivers/serialVFD-displays.c and to write a new "load" function with the correct commands for the display. (Try which display Type works best with your display, then copy, rename and modify this function to your needs - that is the easiest way I guess.)

On Malte Poeggel's page you may find pictures and datasheets of the VFDs: http://www.maltepoeggel.de/index.php?site=vfd

It is possible to switch the display off and back on while the server is running. It may take a few minutes until the next full refresh makes the display show everything correctly.

Connecting The Display

The Connections shown have been tested successfully.

Warning

Always cross-check with your datasheet, before connecting your display! Different displays of even the same manufacturer may have different pin assignments!

With this example connections it will be easy to connect displays with different connector pin-layouts, the pins are commonly named equal in the datasheet.

Serial Connections

It is not possible to connect most of the displays directly to the serial port. The signal has to be inverted. I use the following circuit to do that job.

Figure 5.13. serialVFD: Serial Inverter


Computer                                          Display
						  (signal)
HDD Powerconnector
color(Voltage)

red(+5V)    ----------------------------------o----- +5V
                                              |
black(GND)  ----------------------o          .-.
                                  |          | | 10k
Serial(SUB-D  9Pin female)        |          | |
pin(signal)                       V*         '-'
           ___                                |
3(TxD)  --|___|--o---o      o-----------------o----- RxD
           10k   |   |      |
                 |   |     C|
                .-.  |   -----  BC547c (or similar NPN)
                | |  | B|  /  |
            10k | |  o--|-|   |
                '-'     |  \  |
                 |       --->-    A*
                 |          E|    |
                 |           |    |
5(GND)  ---------o-----------o----o--------------o-- GND
                                                 |*
Shield  -----------------------------------------o
optional

*connect near display


The pins on the different displays vary.

NEC Displays (FM20X2KB-AB):

CN1:

Pin 33 ------- RxD
(Testmode: connect pins 25 and 26, then power up)

CN2:

Pin 1  ------- +5V
Pin 2  ------- GND
KD Rev 2.1:

The blue connector (6pin in a row) (the important one!):


--------------------------------
| +5V  +5V  RxD  GND  GND  GND |
--------------------------------

Tip

Hold the display in that position where you can read the KD Rev 2.1 marking normally!

The gray connector (10pin 2 rows):

Do not use. (the ATMEL ISP connector I guess)

The two jumpers next to the gray connector:

Normally not used.
You can activate two different testmodes with them.

FUTABA Displays (M402SD06GJ):
Pin 2   ------ +5V
Pin 4   ------ +5V
Pin 6   ------ +5V

Pin 10  ------ GND
Pin 12  ------ GND
Pin 14  ------ GND

Pin 19  ------ RxD
Siemens/Wincor Nixdorf BA63/66:

This display doesn't need the inverter! It must be connected directly with the serial port.

Check the serial port setup of the display, it has to be "9600 8N1". In most cases JP3 needs to be modified (closed) by the user!

Suggested Jumper Setting:
JP1 open, JP2 open, JP3 closed, JP4 open, JP5 open

More detailed information can be found in the users manual of the display.

Parallel Connections

NEC Displays (FM20X2KB-AB):

CN1:

parallel Port:			Display (NEC):
Pin: 	Name:			Name:   Pin:

1	/STROBE --------------	/WR	17
2	D0      --------------	D0	15
3	D1      --------------	D1	13
4	D2      --------------	D2	11
5	D3      --------------	D3	9
6	D4      --------------	D4	7
7	D5      --------------	D5	5
8	D6      --------------	D6	3
9	D7      --------------	D7	1
10	/ACK	--o
		  |
11	BUSY    --o-----------	BUSY	27

			   o--  /CS	23
			   |
18 - 25	GND    ------------o--	GND	2,4,6,8,10,12,14,16,18,20,22,24,26,28,20,32,34
			   |*
Shield  -------------------o
optional

*connect near display

CN2:

Pin 1  ------ +5V
Pin 2  ------ GND
FUTABA Displays (M402SD06GJ):
parallel Port:			Display (FUTABA):
Pin: 	Name:			Name:   Pin:

1	/STROBE --------------	/WR	17
2	D0      --------------	D0	15
3	D1      --------------	D1	13
4	D2      --------------	D2	11
5	D3      --------------	D3	9
6	D4      --------------	D4	7
7	D5      --------------	D5	5
8	D6      --------------	D6	3
9	D7      --------------	D7	1
10	/ACK	--o
		  |
11	BUSY    --o-----------	BUSY	20

			   o--  /SEL	18
			   |
18 - 25	GND    ------------o--	GND	10,12,14
			   |*
Shield  -------------------o
optional
			   0--	TEST	16
			   |
		+5V -------o--	+5V	2,4,6

*connect near display

Configuration in LCDd.conf

[serialVFD]

use_parallel = { yes | no }

"no" if display connected serial, "yes" if connected parallel [default: no(serial)].

Port = PORT

Portaddress where the LPT is. Used in parallel mode only. Usual values are 0x278, 0x378 and 0x3BC [default: 0x278].

PortWait = DELAY

Set parallel port timing delay (us). Used in parallel mode only. [default: 2; legal: 0 - 255].

Device = DEVICE

Device to use in serial mode. Usual values are /dev/ttyS0 and /dev/ttyS1 [default: /dev/lcd].

Custom-Characters = CUSTOM-CHARACTERS

Number of Custom-Characters [default: Display-Type dependent].

Size = WIDTH x HEIGHT

Specifies the size of the VFD. [default: 20x2]

Type = CODE

Specifies the display type.[default: 0] The following type codes are available:

CODEVFD model
0NEC (FIPC8367 based) VFDs
1KD Rev 2.1
2Noritake VFDs
3Futaba VFDs
4IEE S03601-95B
5IEE S03601-96-080
6Futaba NA202SD08FA (allmost IEE compatible)
7Samsung 20S207DA?
8Siemens/Wincor Nixdorf BA63/66

Note

Noritake VFDs have not been tested yet. Feedback is welcome.

Brightness = BRIGHTNESS

Set the initial brightness [default: 1000; legal: 0 - 1000] (4 steps 0-250, 251-500, 501-750, 751-1000)

OffBrightness = OFFBRIGHTNESS

Set the initial off-brightness [default: 0; legal: 0 - 1000]. This value is used when the display is normally switched off in case LCDd is inactive. (4 steps 0-250, 251-500, 501-750, 751-1000)

Speed = { 1200 | 2400 | 9600 | 19200 | 115200 }

Set the the baud rate communication with the VFD. If not given [default 9600].

ISO_8859_1 = { yes | no }

Enable ISO-8859-1 compatibility [default is yes].

The shuttleVFD Driver

Features

The shuttleVFD drivers works with Shuttle Computer Group VFDs. These VFDs are found on various Shuttle XPC models. A partial list include Shuttle M1000, Shuttle M2000, Shuttle G5 3300m and Shuttle SG33G5M.

The display itself is a 20x1 character display. Each character cell is 5x8 pixels. It also has smaller row of specialized icons: clock, radio, music, CD/DVD, television, camera, rewind, record, play, pause, stop, fast-forward, reverse, repeat, mute, and a series of volume bars. Some or all of the icons can be displayed.

The display is driven by Princeton Technologies PT6314 VFD Controller according to the sources cited in the driver source. The PT6314 is probably driven off the Serial Peripheral Interface of a Cypress CY7C63723C low-speed USB controller that is connected to the mainboard via USB. Data is written to the Cypress CY7C63723C in bytes. The specifications for both the PT6314 and CY7C63723C are available, but not used when writing this driver. It seems that much more advanced uses are available if the specifications were to be used, specifically pixel addressing.

A current limitation of the driver is that it sleeps for some number of microseconds after writing to the display. If data is written to the display too quickly, it is simply discarded therefore the driver must sleep. The sleep time was experimentally found on a Shuttle M1000 machine and is hard-coded into the driver. This maybe different for other machines and configurations. This may occasionally cause the display to flicker or refresh unevenly across the display. It seems that the PT6314 can signal when it has read the data from the buffer, but this functionality is not used.

Configuration in LCDd.conf

[shuttleVFD]

There are no configuration options available for this display.

The sli Driver

This section talks about using LCDproc with Serial LCD Interface (SLI-OEM) boards from Wirz Electronics.

Note

This driver is intended for use with the original SLI-OEM boards from Wirz Electronics. As of 2010 Parallax, Inc. sells serial displays designed by Element Products (formerly Wirz Electronics). Due to the lack of documentation it is unclear if these devices do work with this driver.

Configuration in LCDd.conf

[sli]

Device = DEVICE

Select the output device to use [default: /dev/lcd]

Speed = { 1200 | 2400 | 9600 | 19200 | 38400 | 57600 | 115200 }

Set the the baud rate communication with the LCD. If not specified, the default is 19200.

The stv5730 Driver

This section talks about using LCDproc with LCD displays that use the stv5730 chipset.

Configuration in LCDd.conf

[stv5730]

Port = PORT

Specify the address of the parallel port the LCD is connected to. Common values for PORT are 0x278, 0x378 and 0x3BC. If not given, it defaults to 0x378.

The SureElec Driver

Driver for the LCD modules (actually the controller board) available from the 'SURE electronics' shop (http://www.sureelectronics.net/).

These devices are PIC based controlled, using a serial communication protocol with the host. The actual connection to host is done through USB through a serial-to-USB converter (CP2102 USB to UART Bridge) integrated on the board.

Configuration in LCDd.conf

[SureElec]

Device = DEVICE

Name of the device the display appears as. By default first USB serial device /dev/ttyUSB0 is used.

Edition = EDITION

Edition level of the device (can be 1, 2 or 3). The default is 2.

Size = WIDTH x HEIGHT

Set the display size in characters. This is required for edition 1 devices. For edition 2 & 3 devices this value, if defined, overrides the size read directly from the device.

Contrast = CONTRAST

Select the display's contrast, 480 is the default. Permissible values are in the range of 0-1000.

Brightness = BRIGHTNESS

Select the display's brightness, 480 is the default. Permissible values are in the range of 0-1000.

OffBrightness = OFFBRIGHTNESS

Select the display's when the display is normally switched off in case LCDd is inactive, 100 is the default. Permissible values are in the range of 0-1000.

The svga Driver

This section talks about using LCDproc with LCD displays that use the svga library.

Configuration in LCDd.conf

[svga]

Mode = SCGALIB-MODE

svgalib mode to use [default: G320x240x256] SCGALIB-MODE can be any legal mode string for svgalib. See the svgalib(7) manual page for legal mode strings.

Size = WIDTH x HEIGHT

set display size [default: 20x4]

Contrast = CONTRAST

Set the initial contrast. Legal values for CONTRAST are 0 - 1000. If not given, the default value is 500.

Note

This parameter can be set but it does not change anything in the driver.

Brightness = BRIGHTNESS

Set the initial brightness [default: 1000; legal: 1 - 1000]

OffBrightness = BRIGHTNESS

Set the initial off-brightness [default: 500; legal: 1 - 1000] This value is used when the display is normally switched off in case LCDd is inactive

The Toshiba T6963 Driver

This section talks about using LCDproc with LCD displays that use the T6963 chipset from Toshiba. Usually, this chipset is used on big graphical LCD displays that can often act as a screen.

The driver uses the text mode of the chipset with a custom font loaded which resembles the characters from HD44780 ROM 002 character set (European character set). If your display has a 'Font Select' pin it must be wired to use the 6x8 font.

Only displays in 'Single Scan' configurations are supported. Displays configured as 'Dual Scan' are currently not supported. Those use on-board memory differently. Check the datasheet of your display!

Connections

Warning

Displays using T6963 chipset come in a variety of pin-outs and power configurations. They usually require negative voltage for contrast and some displays have a negative voltage generator on-board. Therefore the wiring table below does only list signal names, not LCD pins. Be sure to get the correct datasheet for your display and identify the pins to use!

We do not give wiring examples for power, contrast, and other control lines. You have to figure out this from your display's datasheet!

Table 5.25. T6963 wiring schematic

Parallel port<->LCD
namepinnamepin
nSTRB1 /WR*
D0-D72-9 DB0-DB7*
nLF14 /CE*
INIT16 C/D*
nSEL17 /RD*
  VDDFS*

Compiling

Make sure that the T6963 files are built when you run configure. This can be done by specifying "--enable-drivers=all" or by "--enable-drivers=t6963".

Configuration in LCDd.conf

[t6963]

Size = WIDTH x HEIGHT

Set display size in pixels [default: 128x64]. The size in characters is automatically calculated assuming the font size is set to 6x8 for the display.

Port = PORT

Specify the address of the parallel port the LCD is connected to. Common values for PORT are 0x278, 0x378 and 0x3BC. Legal values are 0x200 - 0x400. If not given the default value is 0x378.

bidirectional = { yes | no }

Use LPT port in bi-directional mode. [default: yes; legal: yes, no]

Most LPT ports can be used in bi-directional mode. It is required for proper timing of the display. Leave this on unless you experience problems.

ClearGraphic = { yes | no }

Clear graphic memory on start-up [default: no; legal: yes, no]. The T6963 has a graphic and a text area which can be combined using several modes. This driver uses default OR-mode. Usually the graphic area is empty after power-on but if you see random garbage overlaying the text this option may be enabled.

delayBus = { yes | no }

Use additional delay in read / write operations. [default: no; legal: yes, no]. The display can execute operations very fast. As the driver implements busy checking no additional delays are required. But if you experience problems you may try to slow down communication by enabling this setting.

The text Driver

The text driver simply outputs the content of the internal framebuffer to the current console using printf().

Configuration in LCDd.conf

[text]

Size = WIDTH x HEIGHT

Set the display size [default: 20x4]

The tyan Driver

This section talks about using LCDproc with LCD modules used in Tyan GS10 and GS12 barebones.

Features

The LCD modules used on the front side of the Tyan GS10 and GS12 series barebones consist of an LCD display by Winstar Display Co. LTD that is 16 characters wide and 2 lines high. To the right of the display there is a 6 button keypad: 4 array buttons and two buttons labeled C and S.

For more information see the LCD pack from the Tyan support page. Besides a useless old version of LCDproc it contains some documentation about the panel itself including a PDF specification of the LCD display by its manufacturer.

Configuration in LCDd.conf

[tyan]

Device = DEVICE

Select the output device to use [default: /dev/lcd]

Speed = { 4800 | 9600 }

Set the the baud rate communication with the LCD. If not given, the default is 9600.

Size = WIDTH x HEIGHT

set display size [default: 16x2]

The ula200 Driver

General

The ULA-200 (short for German USB-LCD-Ansteuerung), manufactured and sold by ELV, is a small board that connects a HD44780-compatible display to the computer using the USB interface. Additionally it provides 6 digital inputs that can be used for keys.

The ula200 driver controls this board supporting the features:

  • display on a single-controller HD44780 display

  • standard icons (heart, checkbox)

  • backlight control

  • input buttons

  • no horizontal or vertical bars

Requirements

The driver uses libftdi, which again uses libusb for communication with the device, so no kernel driver is needed on Linux, and the driver can be used on other operating systems as well.

Note

When using a libusb based driver like IOWarrior, LCDd needs to be started as root.

Note

On Linux, you have to take care that the ftdi_sio.ko kernel module doesn't claim the ELV device. If you didn't change the IDs in the kernel driver (ftdi_sio.c), this should not matter.

Known problems

Sometimes the display hangs (the ACK response is not received) on shutdown. Reconnect the display in that case. Please do the same if it hangs while starting up. The latter only happens if it was not the first time LCDd talked to the display.

Implementation note

(by the driver's author Bernhard Walle)

The ULA-200 talks a text protocol which allows to display text using a high-level language, i.e. STX s len char0 char1 ... ETX. It also allows low-level register access to the HD44780. So in theory, it would be possible to write a connection type for the hd44780 driver and let the hd44780 core do the rest. I tried this. It was slow and didn't work with user-specific characters (the hd44780 frequently changes this characters which seems to confuse the microcontroller, at least I cannot explain why it didn't work, there was garbage).

So I wrote a separate driver, the ula200, which uses the high-level language and should work for displays with all sizes. I only tested 20x4, so maybe for other sizes the positioning code may be adapted.

As I mentioned, there were problems with frequently changing the user-definable characters. I also tried to implement bar code in the ula200 driver with similar effects. I gave it up because I don't need it personally and it can be done later. However, standard icons are implemented. The user-definable characters are set in startup and are not changed. This works like a charm. It is not possible to use character 0 with the high-level language (or at least it isn't documented how to escape it). It could be done with hd44780 code, but I replaced the character with a standard character which looks good.

Configuration in LCDd.conf

[ula200]

Size = WIDTH x HEIGHT

Select the LCD size [default: 20x4]

KeyMap_A = KEY , KeyMap_B = KEY , KeyMap_C = KEY , KeyMap_D = KEY , KeyMap_E = KEY , KeyMap_F = KEY

If you have a non standard keypad you can associate any keystrings to keys. There are 6 input keys in the ULA-200 hardware that generate characters from 'A' to 'F'. Legal values for KEY are Up, Down, Left, Right, Enter and Escape.

The following table lists the built-in default mapping hardcoded in the driver.

KeyMap_AUp
KeyMap_BDown
KeyMap_CLeft
KeyMap_DRight
KeyMap_EEnter
KeyMap_FEscape

You may leave it unchanged if you have a standard keypad. You can change it if you want to report other keystrings or have a non-standard keypad.

The xosd Driver

This section talks about using LCDproc with libxosd.

libxosd is a system that displays text on top of your X-Windows screen, much like the on-screen display (OSD) used by most modern televisions and video-players.

Configuration in LCDd.conf

[xosd]

Size = WIDTH x HEIGHT

set display size [default: 20x4]

Offset = X-OFFSET x Y-OFFSET

Offset (in pixels) of the top-left corner of LCDproc's xosd window from the top-left corner of the monitor. If not given, it defaults to 0x0.

Font = FONT

X font to use, in XLFD (X Logical Font Description) format, as given by the xfontsel property. E.g. -*-terminus-*-r-*-*-*-320-*-*-*-*-*.

For best results it is recommended to use a mono-spaced font to mimic the aspect of a physical LCD display that most clients expect with regard to their screen layouts.

Contrast = CONTRAST

Set the initial contrast. Legal values for CONTRAST are 0 - 1000. If not given, the default value is 500.

Note

This parameter can be set but it does not change anything in the driver.

Brightness = BRIGHTNESS

Set the initial brightness [default: 1000; legal: 1 - 1000]

OffBrightness = BRIGHTNESS

Set the initial off-brightness [default: 500; legal: 1 - 1000] This value is used when the display is normally switched off in case LCDd is inactive

Parallel Port Troubleshooting

Unfortunately attaching an LCD module to a parallel port is not trivial.

In most cases it requires soldering abilities and basic knowledge of electronics.

The following hints might be helpful:

Check The Wiring

Wiring errors can easily be made. If you are inexperienced with the soldering iron better have someone solder it for you. Display modules are sensitive to electrostatic discharges, so touch an earthed surface (computer case, water pipes...) before you handle these.

Power Source Unregulated / Noisy

Make sure your power supply delivers steady 5 Volts without noise or interruptions. The bare wall plug-in transformer is often not suitable, though you can make it stabilized by adding an 7805 and a few capacitors. Some noise induced in the supply lines my be tricky to track, even if you have an oscilloscope.

Ground Lift

The power supply wires and especially the GND wires should be a little thicker than the other wires. If GND is not thick enough (or not existent, see 1) the resistance of the wire may cause differing GND potentials in the circuit. This may lead to strange display behaviour. It may also be wise to solder a 100nF capacitor directly to the GND and VCC pins of the display.

Latchup

Never let the supply voltage get much below the io signal voltage. It may lead to a latchup condition which will destroy the controller chip on the display.

Contrast

If you don't see anything on your display it may be that your contrast voltage is set wrong. Turn your contrast potentiometer all the way to the end connected to GND. Contrast is highest then.

Beware

The module you got so ultra cheap may be an enhanced temperature model which needs a negative contrast voltage for sufficient contrast - see chapter 99 on how to make negative voltage.

Parallel Port Voltage

Many modern mainboards and especially notebooks will not nearly output 5V for a logic H as the older parallel ports did, because the operating voltage of computers is lower than 5V these days. I have measured voltages between 2.5V and 4V for logic H, which is barely within specification of the HD44780. If you account RCL of your cable, this may not be enough and can cause unreliable operation.

Enable Signal Rise Time

If you ever read the HD44780 datasheet you will notice that somewhere in the 'signal timing' table is written: 'Enable Signal Rise Time max. 20nS'. That means the Voltage on the HD44780 pin called 'Enable' has to rise from 0 Volts to 5 Volts within 20 Nanoseconds and the other way round. They should better print that in big fat red letters, because most HD44780s are really picky about the enable signal rise time.

That is a Problem: If you count together the bad driving characteristics of the parallel port combined with the capacitance of flat ribbon cable you may easily get an order of magnitude slower rise time. Therefore you should only use really short cable (shorter than 50cm) for connecting the display to the parallel port. It may also be useful to use pull-up resistors on the display module or a schmitt-trigger.

Note

The rise time of a digital output can (usually) not be altered by software.

EMI

The cable from the parallel port to the display may be sensible to electromagnetic interference and may emit electromagnetic radiation. If you place your cellphone near the cable, you may get unexpected display readings, on the other hand your house neighbour may not be able to listen to his/her favourite radio station any more - so better use shielded cable and put the display in a metallic case, perhaps a computer case.

One or Two Black Lines

If you see one or two black lines on the display it means nothing more than that the display is powered and contrast voltage is present. If one or two black lines appear the controller has not been reset properly by the on chip power on reset generator. No need to worry - it will be reset by the LCDd software. But if the black line will not disappear although the wiring is working, the controller on the display may be defective.

Software Too Fast

If you have a super GHz computer it may happen that the signal timing generated by LCDd is too fast. Adjust DELAYMULT in the source file to a bigger value. Parallel port wirings usually don't permit to read back the busy flag of the controller chip, so timing must be adjust so that the controller never is busy.

LED Backlight

Check whether you need a resistor for your LED Backlight and which value it should have. If you forget the required resistor the backlighting LEDs might become hot and draw excessive current.

HD44780 Compatible

The original HD44780 controller that we advertise to support has become the industry standard for alphanumeric character displays. The original HD44780 is out of production. It has many successors from many manufactures, which sometimes won't tell you that their chips are 'compatible'.

To name a few: KS0066, KS0070, KS0076, LC7985, NT3881, SED1278, ST7066 ...

Miscellanea

This text has originally been taken from a message by Robin Adams

Converted to Docbook and slightly modified May 2002, Rene Wagner

Chapter 6. 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 some devices, mostly parallel port devices but also some USB 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.

Example 6.1. LCDd -h

 

LCDd - LCDproc Server Daemon, 0.5dev

Copyright (c) 1999-2006 Selene Scriven, William Ferrell, and misc. contributors.
This program is released under the terms of the GNU General Public License.

Usage: LCDd [<options>]
  where <options> are:
    -h                  Display this help screen
    -c <config>         Use a configuration file other than /etc/lcdproc/LCDd.conf
    -d <driver>         Add a driver to use (overrides drivers in config file) [curses]
    -f                  Run in the foreground
    -a <addr>           Network (IP) address to bind to [127.0.0.1]
    -p <port>           Network port to listen for connections on [13666]
    -u <user>           User to run as [nobody]
    -w <waittime>       Time to pause at each screen (in seconds) [4]
    -s <bool>           If set, reporting will be done using syslog
    -r <level>          Report level [2]
    -i <bool>           Whether to rotate the server info screen



Running lcdproc

You will probably more often run lcdproc from the command line than you will run LCDd.

The Command Line Options of lcdproc

Running lcdproc -h gives you an overview of the currently available command line options.

Example 6.2. lcdproc -h

 

lcdproc - LCDproc system status information viewer

Copyright (c) 1999-2006 Selene Scriven, William Ferrell, and misc. contributors.
This program is released under the terms of the GNU General Public License.

Usage: lcdproc [<options>] [<screens> ...]
  where <options> are
    -s <host>           connect to LCDd daemon on <host>
    -p <port>           connect to LCDd daemon using <port>
    -f                  run in foreground
    -e <delay>          slow down initial announcement of screens (in 1/100s)
    -c <config>         use a configuration file other than /etc/lcdproc/lcdproc.conf
    -h                  show this help screen
    -v                  display program version
  and <screens> are
    C CPU               detailed CPU usage
    P SMP-CPU           CPU usage overview (one line per CPU)
    G CPUGraph          CPU usage histogram
    L Load              load histogram
    M Memory            memory & swap usage
    S ProcSize          biggest processes size
    D Disk              filling level of mounted file systems
    I Iface             network interface usage
    B Battery           battery status
    T TimeDate          time & date information
    O OldTime           old time screen
    U Uptime            uptime screen
    K BigClock          big clock
    N MiniClock         minimal clock
    A About             credits page

Example:
    lcdproc -s my.lcdproc.server.com -p 13666 C M X



Note

You will not be able to connect to a remote server, unless it listens to the correct interface and port! See LCDd.conf: The [server] Section for details on the server setup.

Chapter 7. Contact Us

Errata

Of course LCDproc is not perfect (yet). We do our very best to improve it, but in some cases we are very much restricted in our efforts.

The main reason for that is the fact that we do not have all the hardware people have written drivers for. Unfortunately some developers have kind of vanished and don't react to mails from the mailing list any more.

So, as far as drivers are concerned we rely on you as testers. We have developed elaborate "coding in the dark" skills over the time. E.g. the CFontz driver has been updated and ported to 0.4.3 without the developers having the hardware.

The LCDproc Mailing List

We are a bit lazy about the bug-tracking and whatever stuff on SourceForge. So, please contact us directly through the mailing list.

For details on how to subscribe to the list see http://lcdproc.omnipotent.net/mail.php3.

We like people to subscribe to the list with their real names. Of course we cannot and do not want to force you to do so. Anyway, we need to know your name, if you want to contribute code to LCDproc (legal issues of copyrights).

Reporting Bugs

Possibly you will find a bug in the LCDproc distribution. Before reporting this to the mailing list, please respect the following:

  • Your system should be more or less up to date. This does not mean that you have to update from GNU/Linux kernel 2.2.x to 2.4.x or from 2.4.x to 2.6.x. But we would like to make sure that your problem is not related to a known bug in the kernel or maybe your compiler.

  • Especially LCDd might need certain privileges to access a device. Make sure LCDd has the required rights to do so.

  • When experiencing problems with LCDd, make sure that your hardware is OK. E.g. you should make sure that the wiring for your (in this case most likely parallel) device is correct.

  • Make sure that you use the correct speed settings for your device. Incorrect speed settings (baud rate) are most likely to produce garbage scrolling on your display. Refer to the specifications of your device. If your device needs a speed setting that is not supported by LCDd send us a mail.

  • Make sure that you have modified the configuration file according to your needs and that LCDd actually uses the configuration file. I.e. you might have to run LCDd with the -c option

Anyway, no question is too stupid to ask ;) Feel free to ask whatever you want. Unfortunately replying to mails takes time as well (a damn lot of time). So, if you want LCDproc to develop faster, please try to solve a problem yourself first.

BUT if you have actually FOUND A BUG we will be quite happy if you let us know. We NEED YOU as testers and appreciate any feedback.

Appendix A. GNU Free Documentation License

Version 1.1, March 2000

Copyright (C) 2000 Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

PREAMBLE

The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

COPYING IN QUANTITY

If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

  1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.

  2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).

  3. State on the Title page the name of the publisher of the Modified Version, as the publisher.

  4. Preserve all the copyright notices of the Document.

  5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.

  6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.

  7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.

  8. Include an unaltered copy of this License.

  9. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.

  10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.

  11. In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.

  12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.

  13. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.

  14. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."

COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

TRANSLATION

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

Copyright (c) YEAR YOUR NAME. 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 the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled "GNU Free Documentation License".

If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.