0.0.6
Copyright © 2006, 2007 Peter Marschall
Copyright © 2002 Rene Wagner
Copyright © 2002 Guillaume Filion
Copyright © 1999 William W. Ferrell
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
List of Figures
List of Tables
output bits to LEDsclassic ordered by LPT port pinsbitshaker ordered by LPT port pinsList of Examples
LCDd.conf: Specify which driver to useLCDd.conf: Activate the lirc driver~/.lircrc: Specify the associations from buttons to keys
for the lirc driverTable of Contents
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.
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.
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.
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.
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.
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.
Table of Contents
At the time of writing the following majors versions of LCDproc are floating around on the internet:
LCDproc 0.5.3 is the current stable version of LCDproc. This is the version recommended to use.
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 is an old stable version of LCDproc. It was the second stable version of LCDproc after the move to the 0.5 API.
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
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.
Table of Contents
Now that you have downloaded the LCDproc distribution you can start building it.
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 ;)
If you want to install LCDproc more or less permanently you can run:
$suPassword:top secret#make install
make install is absolutely OPTIONAL You can also run LCDproc directly from the source directory. See below for details.
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
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:
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
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
~/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.
Table of Contents
As mentioned in the introduction
LCDd, the LCDproc server, has its own configuration file,
which is usually /etc/LCDd.conf.
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
[; 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.
section]
Parameters are grouped into sections and have the form
key=valuekey, 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 sequence | character |
|---|---|
\a | alert (bell) character |
\b | backspace |
\f | formfeed |
\n | newline |
\r | carriage return |
\t | horizontal tab |
\v | vertical 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.
The [Server] section of the LCDd.conf contains the
settings for the LCDproc server LCDd.
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.
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 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.
DRIVER
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 option.
ADDRESS
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 option.
PORTNUMBER
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 option.
LEVEL
yesno
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 option.
Passing NUMBER-s 1 on the command line enables reporting to syslog
while -s 0 disables it.
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 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 option.
USER
yesno
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.
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.
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.
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 option.
SECONDS
yesno
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.
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).
yesnoblank
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 option.
Passing NUMBER-i 1 on the command line enables server screen rotation,
while -i 0 disables it.
Using the command line, it is not possible to set the server screen to
blank mode.
offopenon
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.
offopenon
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.
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.
KEY
Defaults to Enter.
KEY
Defaults to Left.
KEY
Defaults to Right.
KEY
Defaults to Up.
KEY
Defaults to Down.
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.
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.
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.
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.
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.
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.
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.
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.
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 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.
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.
The file scripts/init-LCDd.* is the init script for the
LCDproc server LCDd. It does not require modification.
The file scripts/init-lcdproc.* is the init script for the
LCDproc "main" client lcdproc.
You can retrieve a listing of all options of lcdproc running lcdproc --help.
The file scripts/init-lcdexec.* is the init script for the
LCDproc lcdexec client, which can execute predefined
commands via the menu feature.
Table of Contents
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.
This section talks about using LCDproc with the BayRAD LCD modules by EMAC, Inc.
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
This section talks about using LCDproc with the serial LCD displays of the CFA632 and CFA634 series by CrystalFontz, Inc.
DEVICE
Select the serial output device to use.
If not given, default is /dev/lcd.
WIDTH
x
HEIGHT
Set the LCD's dimensions in terms of characters per line and lines.
If not given, it defaults to 20x4.
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
Set the initial brightness.
Legal values for BRIGHTNESS range from
0 to 1000.
If not given, it defaults to 1000.
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.
12002400960019200115200
Set the the baud rate to use when communicating with the LCD.
It defaults to 9600 if not specified.
yesno
Set the firmware version (New means >= 2.0) [default: no; legal: yes, no]
yesno
Reinitialize the LCD's BIOS [default: no; legal: yes, no]
normally you shouldn't need this
This section talks about using LCDproc with LCD displays that use the CFontz633 chipset.
This driver is deprecated. Please use the CFontzPacket driver
with Model=633 instead. This driver will be removed in
a future version.
DEVICE
Select the output device to use [default: /dev/lcd]
may be serial device or USB device in serial emulation mode.
WIDTH
x
HEIGHT
Select the LCD type (size) [default: 16x2]
CONTRAST
Set the initial contrast.
Legal values for CONTRAST are 0 - 1000.
If not specified, it defaults to 560.
BRIGHTNESS
Set the initial brightness [default: 1000; legal: 0 - 1000]
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
12002400960019200115200Set the the baud rate for communication with the LCD. If not specified, the default is 19200.
yesno
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. ;=)
yesno
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
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:
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)
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)
This is the same as CFA-633 except it misses the fan control capabilities. The temperature monitoring is not supported in LCDproc though.
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
533631633635
Select the LCD model that is connected.
Legal values for this option are 631,
533,
633, or 635,
with the default being 633.
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.
Mac OS X users may need to use one of the /dev/cu
devices instead of the /dev/tty ones.
yesno
Enable this flag if the device is connected to an USB port. For serial ports
leave it disabled. [default: no; legal: yes,
no]
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).
You should usually not need to set this value!
CONTRAST
Set the initial contrast.
Legal values for CONTRAST are 0 - 1000.
If not specified, it defaults to 560.
BRIGHTNESS
Set the initial brightness [default: 1000; legal: 0 - 1000]
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
19200115200
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).
You should usually not need to set this value!
yesno
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]
yesno
Reinitialize the LCD's BIOS [default: no; legal:
yes, no].
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.
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.
COLOUR
Set the background color.
The default is cyan.
The legal values for COLOUR are
the same as for the Foreground setting.
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.
WIDTH
x
HEIGHT
display size [default: 20x4]
X-OFFSETY-OFFSETWhat position (X,Y) to start the left top corner at. Default: (7,7)
yesnoTell whether to use ACS (alternative character set) symbols for icons and bars instead of simple ASCII characters.
yesnoTell whether to draw a border around the screen.
This section talks about using LCDproc with the serial / USB LCDs CW12232, CW12832 and CW1602 by CwLinux.
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
12232128321602
Select the LCD model [default: 12232;
legal: 12232, 12832, 1602]
DEVICE
Select the output device to use [default: /dev/lcd]
May be serial device or USB device in serial emulation mode.
WIDTH
x
HEIGHT
Select the LCD size [default: depending on model: 12232: 20x4,
12832: 21x4]
1602: 16x2]
960019200
Set the the baud rate for communication with the LCD.
If not given, the default is 19200.
yesno
Reinitialize the LCD's BIOS [default: no; legal: yes, no]
normally you shouldn't need this
yesnoTells if you have a keypad connected. Keypad layout is currently not configurable from the config file.
KEYKEYKEYKEYKEYKEY
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_A | Up |
| KeyMap_B | Down |
| KeyMap_C | Left |
| KeyMap_D | Right |
| KeyMap_E | Enter |
| KeyMap_F | Escape |
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.
yesnokeypad_test_mode permit to test keypad assignment Default value is no
This section describes the ea65 driver which works with the front panel VFD display on the AOpen XC Cube-AV EA65 media barebone.
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.
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
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.
This section describes the Eyebox One.
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.
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...
This section was originally part of the mtxorb.docbook file by Rene Wagner <reenoo@gmx.de>
This section has been modified by Cédric TESSIER (http://www.nezetic.info)
DEVICE
Select the output device to use [default: /dev/ttyS1]
WIDTH
x
HEIGHT
Set the display size [default: 20x4]
yesno
Switch on the backlight [default: yes; legal: yes, no]
If you choose yes, you can switch on/off the backlight in real time using the LCDproc server menu with the keypad.
yesno
Switch on the cursor? [default: no; legal: yes, no]
12002400960019200
Set the the baud rate to use when communicating with the LCD.
If not specified, it defaults to 19200.
As I said, I think only 19200 is a good choice.
DCABPThe following table translate from EyeboxOne Key to Logical Key. EyeboxOne Enter Key is a \r character, so it's hardcoded in the driver.
yesnoYou 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.
This section talks about using LCDproc with LCD displays on Logitech G15 gaming keyboards.
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.
This section talks about using LCDproc with LCD displays supported by graphlcd-base.
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.
Mandatory settings
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.
yesno
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.
Setting it to yes requires Freetype2 support in libglcdprocdriver and its dependants.
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.
FILENAME
Set path to font file to use, e.g. /usr/share/fonts/corefonts/courbd.ttf.
Availalble parameters if UseFT2 = yes
CHARSET
Specify character encoding to use, e.g. iso8859-2.
If not given, use the default ISO8859-1.
COLUMNS
x
ROWS
minimum size in pixels in which fonts should be rendered
Optional settings
BRIGHTNESS
Brightness (in %) if applicable
Legal values are 0 - 100.
If not specified, the default is 50.
CONTRAST
Set the contrast (in %) if applicable.
Legal values are 0 - 100,
with 50 being the default when not specified.
yesnoBacklight if applicable
yesnoflip image upside down
yesnoinvert light/dark pixels
yesnoturns on/off 1 pixel thick debugging border within the usable text area, for setting up TextResolution and MinFontFaceSize (if using FT2);
yesnoborder around the unused area
yesnoborder around the unused area
SHIFTXSHIFTY
Shifts the content of the display by SHIFTX
(default: 0) and SHIFTY
(default: 0) pixels.
This section talks about using LCDproc with LCD displays that use the Matrix Orbital GLK and GLC chipset.
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)
Modules not in the list above are not recognized and the driver will not load if it encounteres an unrecognized display.
DEVICE
select the serial device to use [default: /dev/lcd]
CONTRAST
Set the initial contrast.
Legal values for CONTRAST are 0 - 1000.
If not given, it defaults to 560.
96001920038400
Set the the baud rate for communication with the LCD.
The default is 19200.
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:
picanlcd: PIC-an-LCD serial device
lcdserializer: LCD serializer
los-panel: LCD on Serial panel device (http://www.xs4all.nl/~mlf/los/)
vdr-lcd: VDR LCD serial device
vdr-wakeup: VDR-Wakeup module
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:
pertelian: Pertelian X2040 LCD display (http://pertelian.com/joomla/index.php?option=com_content&task=view&id=43&Itemid=48)
bwctusb: BWCT USB LCD module (http://www.bwct.de/lcd.html)
lcd2usb: Till Harbaum's LCD2USB (http://www.harbaum.org/till/lcd2usb/)
usbtiny: Dick Streefland's USBtiny (http://www.xs4all.nl/~dicks/avr/usbtiny/)
uss720: Display connected to USS-720 USB-to-IEEE 1284 Bridge (Belkin F5U002)
lis2: LIS2 from VLSystem (http://www.vlsys.co.kr)
mplay: MPlay Blast from VLSystem (http://www.vlsys.co.kr)
ftdi: Display connected to a dual channel FTDI 2232D USB chip
usblcd: USBLCD from Adams IT Services (http://www.usblcd.de/)
Last but not least, for special purposes, there are even more connection types:
i2c: LCD driven by PCF8574(A)/PCA9554(A) connected via I2C
ethlcd: Display connected via TCP to PoE powered ethlcd device (http://manio.skyboo.net/ethlcd/)
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
No matter what connection type you choose, you will always need some connections. They are explained here.
All variants use the same method of obtaining power. i.e., for each LCD:
Table 5.1. HD44780: Power Connections
| LCD | Signal | |
|---|---|---|
| name | pin | |
| VEE | 1 | GND (connect to any of pins 18 - 25 of you parallel port) |
| VCC | 2 | +5V |
| VLC | 3 | (contrast adjustment) |
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
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.
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:
You can change the mapping using the
KeyDirect_NUM
configuration option, where NUM
is the subscript to the X in the table above.
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:
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
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.
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
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).
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.)
This wiring is originally based on "lcdtext" (by Matthias Prinke).
Table 5.4. HD44780: 4bit Pinouts (1)
| printer port | <-> | LCD | ||
|---|---|---|---|---|
| name | pin | name | pin | |
| GND | VEE | 1 | ||
| +5V | VCC | 2 | ||
| (contrast adjustment) | VLC | 3 | ||
| D4 | 6 | RS | 4 | |
| GND | RW | 5 | ||
| D6 | 8 | EN | 6 | |
| D0 | 2 | D4 | 11 | |
| D1 | 3 | D5 | 12 | |
| D2 | 4 | D6 | 13 | |
| D3 | 5 | D7 | 14 | |
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 | ||
|---|---|---|---|---|
| name | pin | name | pin | |
| D7 | 9 | EN2 | 6 of 2nd display | |
| D5 | 7 | EN3 | 6 of 3rd display | |
| STR | 1 | EN4 | 6 of 4th display | |
| LF | 14 | EN5 | 6 of 5th display | |
| INIT | 16 | EN6 | 6 of 6th display | |
| SEL | 17 | EN7 | 6 of 7th display | |
The optional keypad can be connected as follows:
Table 5.6. HD44780: 4bit Keypad Pinouts
| printer port | <-> | keypad | remarks | |
|---|---|---|---|---|
| name | pin | pin | ||
| D0 | 2 | Y1 | ||
| D1 | 3 | Y2 | ||
| D2 | 4 | Y3 | ||
| D3 | 5 | Y4 | ||
| D4 | 6 | Y5 | ||
| D5 | 7 | Y6 | Only if not used for backlight or 3rd controller. | |
| nSTRB | 1 | Y7 | Only if not used for additional controllers. | |
| nLF | 14 | Y8 | ||
| INIT | 16 | Y9 | ||
| nSEL | 17 | Y10 | ||
| nACK | 10 | X1 | ||
| BUSY | 11 | X2 | ||
| PAPEREND | 12 | X3 | ||
| SELIN | 13 | X4 | ||
| nFAULT | 15 | X5 | ||
The optional backlight wiring should be connected to D5, pin 7.
This type of connection should work with winamp.
Table 5.7. HD44780: "Winamp" wiring
| printer port | <-> | LCD | ||
|---|---|---|---|---|
| name | pin | name | pin | |
| D0 | 2 | D0 | 7 | |
| D1 | 3 | D1 | 8 | |
| D2 | 4 | D2 | 9 | |
| D3 | 5 | D3 | 10 | |
| D4 | 6 | D4 | 11 | |
| D5 | 7 | D5 | 12 | |
| D6 | 8 | D6 | 13 | |
| D7 | 9 | D7 | 14 | |
| nSTRB | 1 | EN | 6 | |
| nLF | 14 | RW | 5 (EN3 6 - LCD 3) (optional (*) ) | |
| INIT | 16 | RS | 4 | |
| nSEL | 17 | 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 | |
|---|---|---|---|
| name | pin | pin | |
| D0 | 2 | Y1 | |
| D1 | 3 | Y2 | |
| D2 | 4 | Y3 | |
| D3 | 5 | Y4 | |
| D4 | 6 | Y5 | |
| D5 | 7 | Y6 | |
| D6 | 8 | Y7 | |
| D7 | 9 | Y8 | |
| nACK | 10 | X1 | |
| BUSY | 11 | X2 | |
| PAPEREND | 12 | X3 | |
| SELIN | 13 | X4 | |
| nFAULT | 15 | X5 | |
The optional backlight wiring should be connected to nSEL, pin 17.
This is originally based on "lcdtime" (by Benjamin Tse
<blt@ComPorts.com>) 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 | ||
|---|---|---|---|---|
| name | pin | name | pin | |
| D0 | 2 | D0 | 7 | |
| D1 | 3 | D1 | 8 | |
| D2 | 4 | D2 | 9 | |
| D3 | 5 | D3 | 10 | |
| D4 | 6 | D4 | 11 | |
| D5 | 7 | D5 | 12 | |
| D6 | 8 | D6 | 13 | |
| D7 | 9 | D7 | 14 | |
| nSEL | 17 | - | ||
| nSTRB | 1 | RS | 4 | |
| nLF | 14 | RW | 5 (optional - pull LCD RW low (*) | |
| INIT | 16 | EN | 6 | |
(*) 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 | |
|---|---|---|---|
| name | pin | pin | |
| D0 | 2 | Y1 | |
| D1 | 3 | Y2 | |
| D2 | 4 | Y3 | |
| D3 | 5 | Y4 | |
| D4 | 6 | Y5 | |
| D5 | 7 | Y6 | |
| D6 | 8 | Y7 | |
| D7 | 9 | Y8 | |
| nSTRB | 1 | Y9 | |
| nSEL | 17 | Y10 (only if not used for backlight) | |
| nACK | 10 | X1 | |
| BUSY | 11 | X2 | |
| PAPEREND | 12 | X3 | |
| SELIN | 13 | X4 | |
| nFAULT | 15 | 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.
This interface uses a handful of wires to interface to the
HD44780. Suitable for high noise, long connections. Designed by
Andrew McMeikan <andrewm@engineer.com>.
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
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 | |
|---|---|---|---|
| name | pin | pin | |
| nACK | 10 | X1 | |
| BUSY | 11 | X2 | |
| PAPEREND | 12 | X3 | |
| SELIN | 13 | X4 | |
| nFAULT | 15 | 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
|
===
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
|
===
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 | ||
|---|---|---|---|---|
| name | pin | name | pin | |
| ADBUS0 | 24 | D0 | 7 | |
| ADBUS1 | 23 | D1 | 8 | |
| ADBUS2 | 22 | D2 | 9 | |
| ADBUS3 | 21 | D3 | 10 | |
| ADBUS4 | 20 | D4 | 11 | |
| ADBUS5 | 19 | D5 | 12 | |
| ADBUS6 | 18 | D6 | 13 | |
| ADBUS7 | 17 | D7 | 14 | |
| BDBUS0 | 40 | RS | 4 | |
| BDBUS1 | 39 | RW | 5 | |
| BDBUS2 | 38 | EN | 6 | |
| BDBUS3 | 37 | BL | Backlight (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 | ||
|---|---|---|---|---|
| name | pin | name | pin | |
| D0 | 25 | D4 | 11 | |
| D1 | 24 | D5 | 12 | |
| D2 | 23 | D6 | 13 | |
| D3 | 22 | D7 | 14 | |
| D4 | 21 | EN | 6 | |
| D5 | 20 | RS | 4 | |
| D6 | 19 | RW | 5 | |
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 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/ttyUSB).
x
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/ttyUSB).
x
See http://www.xs4all.nl/~mlf/los/ for more information on this device.
… to be documented …
Please address Matteo Pillon for further information.
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.
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/ttyUSB.
x
See the X4020 product page for more information.
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 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.
Some electronic knowledge and familiarity with the soldering iron
A PIC16F84 (I used PIC16F84A) or PIC16C54
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
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.
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.
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).
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.
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
In order to make the lcd2usb connection type work with a 2-controller display
you may need to set the vSpan config option accordingly.
“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.
LCDproc does not make use of the IR receiver. 3rd party software is required to make it do anything, e.g. LIRC.
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.
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.
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.
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
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 value | Meaning |
|---|---|
0x20…0x27 | PCF8574 with A[012]=0…7 |
0x38…0x3f | PCF8574A with A[012]=0…7 |
0xa0…0xa7 | PCA9554 with A[012]=0…7 |
0xa0…0xa7 | PCA9554A with A[012]=0…7 |
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.
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/lcd.
The kernel driver providing this device currently only exists for Linux kernels
newer than 2.4.20-pre7.
x
As of 2007 these device are not sold anymore. This driver has been ported from lcdproc 0.4.5 to support existing users.
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).
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
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.
4bit8bitwinampserialLptpicanlcdlcdserializerlos-panelvdr-lcdvdr-wakeuppertelianbwctusblcd2usblis2mplayi2cftdiusblcdSelect the type of the wiring / display connection.
| ConnectionType | Wiring / Display Type |
|---|---|
4bit | 4bit Wiring to parallel port(default) |
8bit | 8bit Wiring to parallel port ("lcdtime") |
winamp | 8bit Wiring "winamp" Style to parallel port |
serialLpt | Serial LPT Wiring |
picanlcd | PIC-an-LCD serial device "picanlcd" |
lcdserializer | LCD serializer "lcdserializer" |
los-panel | LCD on Serial panel device "los-panel" (http://www.xs4all.nl/~mlf/los/) |
vdr-lcd | VDR LCD serial device "vdr-lcd" |
vdr-wakeup | VDR-Wakeup module "vdr-wakeup" |
pertelian | Pertelian X2040 LCD display (http://pertelian.com/joomla/index.php?option=com_content&task=view&id=43&Itemid=48) |
bwctusb | BWCT USB device "bwctusb" (http://www.bwct.de/lcd.html) |
lcd2usb | Till Harbaum's LCD2USB (http://www.harbaum.org/till/lcd2usb/) |
usbtiny | Dick Streefland's USBtiny (http://www.xs4all.nl/~dicks/avr/usbtiny/) |
lis2 | LIS2 from VLSystem (http://www.vlsys.co.kr) |
mplay | MPlay Blast from VLSystem (http://www.vlsys.co.kr) |
ftdi | Display connected to a dual channel FTDI 2232D USB chip |
usblcd | USBLCD adapter from Adams IT Services (http://www.usblcd.de/) |
i2c | LCD driven by PCF8574(A)/PCA9554(A) connected via I2C |
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.
BITRATEFor a serial connection, set to the serial port bitrate. To use the default value for the chosen interface, just set to 0.
hd44780_defaulthd44780_euroea_ks0073sed12780f_0bhd44780_koi8_rhd44780_cp1251hd44780_8859_5upd16314noneSet 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.
See server/drivers/hd44780-charset.h
in LCDproc's source directory for the actual
mappings.
yesnoTell whether you have a keypad connected. You may also need to configure the keypad layout further on in this file.
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.
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
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.
yesnoSpecify if you have a switchable backlight.
yesnoTell if you have the additional output port ("bargraph") and you want to be able to control it with the lcdproc OUTPUT command.
yesno
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.
WIDTH
x
HEIGHT
Specifies the size of the LCD.
Default: 20x4
In case of multiple combined displays, this should be the total size.
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=.
yesnoIf you have a KS0073 or an other 'almost HD44780-compatible', set this flag to get into extended,4-line linear addressing mode.
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.
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.
yesno
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.
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.
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.
NUM =
KEYX_Y =
KEYIf 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
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
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.
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.
This text has originally been taken from a message by Bill Farrow
<bfarrow@arrow.bsee.swin.edu.au>.
Updated February 2000, Benjamin Tse <blt@ComPorts.com>
Updated October 2001, Joris Robijn <joris@robijn.net>
Converted to Docbook March 2002, Rene Wagner <reenoo@gmx.de>
Updated April 2002, Rene Wagner <reenoo@gmx.de>
Updated and extended April 2006 to November 2007, Peter Marschall <peter@adpm.de>
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
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.
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.
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:
standalone iMON VFD driver from http://venky.ws/projects/imon/
the iMON module included with LIRC ver. 0.7.1 or newer from the LIRC project
For further details, please consult the page and the forum at http://venky.ws/projects/imon/.
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
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.
hd44780_eurohd44780_koi8_rhd44780_cp1251hd44780_8859_5upd16314noneSet 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.
See server/drivers/hd44780-charset.h
in LCDproc's source directory for the actual
mappings.
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.
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
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
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
Select the display's contrast 200 is the default.
Permissible values are in the range of 0-1000.
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
Set the backlight state. The default is 1, which turns
the backlight on. 0 turns the backlight off.
DISCMODE
Sets the disc mode. The default is 0 which spins the
"slim" disc. 1 spins their complement.
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:
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
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
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.
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.
When using a libusb based driver like IOWarrior,
LCDd needs to be started as root.
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.
WIDTH
x
HEIGHT
Set the display dimensions. If not given, it defaults to 20x4.
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.
yesnoIf 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
yesno
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 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 key | IrMan command |
|---|---|
Up | lcdproc-Up |
Down | lcdproc-Down |
Left | lcdproc-Left |
Right | lcdproc-Right |
Enter | lcdproc-Enter |
Escape | lcdproc-Escape |
If you have trouble using the irman driver,
you might try the lirc driver.
lirc supports IrMan as well.
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.
yesno
Tell whether the device has a backlight, or whether the backlight shall be used.
If not given, it defaults to no.
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.
WIDTH
x
HEIGHT
Select the display size [default: 16x2]
This section covers the joystick input driver for LCDd.
DEVICE
Select the input device to use [default: /dev/js0]
NUMneg =
KEYNUMpos =
KEYSet 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.
NUM =
KEYSet 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.
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 :-)
DEVICE
Select the output device to use [default: /dev/lcd]
BRIGHTNESS
Set the initial brightness [default: 255; legal: 0 - 255]
24009600
Set the the baud rate to use when communicating with the LCD.
If not given, the default is 9600.
yesno
Reinitialize the LCD's BIOS [default: no; legal: yes, no]
This section talks about using LCDproc with serial LCD displays from kernel concepts.
DEVICE
Default: /dev/lcd
KEYKEYKEYKEYkeypad settings
| key name | function (normal context) | function (menu context) |
|---|---|---|
| PauseKey | Pause/Continue | Enter/select |
| BackKey | Back(Go to previous screen) | Up/Left |
| ForwardKey | Forward(Go to next screen) | Down/Right |
| MainMenuKey | Open main menu | Exit/Cancel |
You can rearrange the settings here.
If your device is broken, have a look at server/drivers/lcdm001.h
This section talks about using LCDproc with serial LCD displays from Helmut Neumark Elektronik.
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.
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.
You need to add lirc to the --enable-drivers=... list.
Then simply run make.
First of all you need to activate the driver by adding a Driver=lirc line
to your LCDd.conf
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.
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.
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.
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.
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.
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.
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.
When using a libusb based driver like lis,
LCDd needs to be started as root.
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
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
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
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.
This section talks about using LCDproc with VFD displays in Medion MD8800 PCs.
You may find more information about the LCD on Martin Moeller's homepage.
DEVICE
device to use [default: /dev/ttyS1]
WIDTH
x
HEIGHT
display size [default: 16x2]
BRIGHTNESS
Set the initial brightness [default: 1000; legal: 0 - 1000]
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
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.
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 |
|---|---|
| 0 | Play |
| 1 | Pause |
| 2 | Record |
| 3 | Message |
| 4 | Mail (at-symbol) |
| 5 | Mute |
| 6 | WLAN tower |
| 7 | Volume (the word) |
| 8…12 | Volume (decimal 0…28) |
| 13…14 | WLAN strength (0…3) |
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.
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,
This section talks about using LCDproc with LCD displays that use the ms6931 chipset.
This section talks about using LCDproc with LCD displays that use the mtc_s16209x chipset.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
DEVICE
Select the output device to use [default: /dev/lcd]
WIDTH
x
HEIGHT
Set the display size [default: 20x4]
lcdlkdvfdvkd
Set the display type [default: lcd; legal: lcd,
lkd,
vfd,
vkd]
CONTRAST
Set the initial contrast.
Legal values for CONTRAST are 0 - 1000.
If not given, the default value is 480.
The driver will ignore this setting if the display is a VFD or VKD as they do not support this feature.
yesno
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
Set the initial brightness [default: 1000; legal: 0 - 1000]
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
12002400960019200
Set the the baud rate to use when communicating with the LCD.
If not specified, it defaults to 19200.
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
yesnoYou 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.
This section talks about using LCDproc with LCD displays on Logitech MX5000 keyboards.
This section talks about using LCDproc with text mode VFD displays from Noritake Itron.
DEVICE
Port where the VFD is. Usual values are /dev/ttyS0 and /dev/ttyS1
Default: /dev/lcd
WIDTH
x
HEIGHT
Specifies the size of the LCD.
Default: 20x4
BRIGHTNESS
Set the initial brightness [default: 1000; legal: 0 - 1000]
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
12002400960019200115200
Set the the baud rate to use when communicating with the VFD.
If not specified, it defaults to 9600.
012
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.
yesno
Reinitialize the VFD [default: no; legal: yes, no]
This section covers the use of the Mini-Box USB LCD displays.
Mini-Box.com offers two types of USB LCD displays:
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 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.
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.
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.
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).
yesno
Turns the backlight on or off on start-up, default yes.
BRIGHTNESS
Set the initial brightness if the backlight is on. Legal values are:
0 - 1000. If not given, it defaults
to 1000.
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: 0-1000, default to
1000 (full contrast).
yesno
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.
yesno
If Keylights is set, you can disable the directional pad LED by
setting this value to no. Default is yes.
yesno
If Keylights is set, you can disable the F1 LED by setting this value
to no. Default is yes.
yesno
If Keylights is set, you can disable the F2 LED by setting this value
to no. Default is yes.
yesno
If Keylights is set, you can disable the F3 LED by setting this value
to no. Default is yes.
yesno
If Keylights is set, you can disable the F4 LED by setting this value
to no. Default is yes.
yesno
If Keylights is set, you can disable the F5 LED by setting this value
to no. Default is yes.
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.
HOSTNAME_OR_IP-ADDRESSSet 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.
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.
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.
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.
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.
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.
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.
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.
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:
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:
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
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).
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 | ||
|---|---|---|---|---|
| pin | name | name | pin | |
| 1 | ^STROBE | ^RESET | 1 | |
| 2-9 | D0-D7 | D0-D7 | 8-15 | |
| 16 | ^INIT | ^WR | 3 | |
| 17 | ^SELECT_IN | A0 | 7 | |
| 18-25 | GND | GND | VEE | 17 |
| +5V | ^RD | 2 | ||
| GND | SEL1 | 4 | ||
| GND | SEL2 | 5 | ||
| GND | ^CS | 6 | ||
| +5V | VCC | 16 | ||
| potentiometer | V0 | 18 | ||
| -24V (not required for G242C) | VLC | 19 | ||
| GND | FGND | 20 | ||
Table 5.20. ConnectionType bitshaker ordered by LPT port pins
| LPT port | <-> | LCD | ||
|---|---|---|---|---|
| pin | name | name | pin | |
| 1 | ^STROBE | ^WR | 3 | |
| 2-9 | D0-D7 | D0-D7 | 8-15 | |
| 14 | ^LF | A0 | 7 | |
| 16 | ^INIT | ^RESET | 1 | |
| 18-25 | GND | GND | VEE | 17 |
| +5V | ^RD | 2 | ||
| GND | SEL1 | 4 | ||
| GND | SEL2 | 5 | ||
| GND | ^CS | 6 | ||
| +5V | VCC | 16 | ||
| potentiometer | V0 | 18 | ||
| -24V (not required for G242C) | VLC | 19 | ||
| GND | FGND | 20 | ||
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
The sed1330 driver supports the same direct keys and matrix keypad connections as the hd44780 driver. See the section called “Keypad”.
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.
classicbitshakerSelect the type of the wiring, see the section called “Connections”.
If not given, it defaults to classic.
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.
G321DG121CG242CG191DG2446SP14Q002HG25504Type of LCD module. Besides other things (internal setup) this configuration setting determines the size of the display in pixels.
| Type | Size (in pixels) |
|---|---|
G321D | 320 x 200 |
G121C | 128 x 128 |
G242C | 240 x 128 |
G191D | 192 x 192 |
G2446 | 240 x 64 |
SP14Q002 | 320 x 240 |
HG25504 | 320 x 240 |
Currently the G321D and SP14Q002 are the only ones that this driver is tested with.
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.
Those SED1520 displays are the most troublesome I have ever used. You should probably avoid using them and get a 20x4 text display instead.
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:
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 | ||
|---|---|---|---|---|
| name | pin | name | pin | |
| D0-D7 | 2-9 | DB0-DB7 | * | |
| nSTRB | 1 | /WR | * | |
| nLF | 14 | /CS1 | * | |
| INIT | 16 | /CS2 | * | |
| nSEL | 17 | A0 | * | |
| VDD | /RD | * | ||
| GND | RESET/IF | * | ||
| 2 kHz clock | CL | * | ||
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 | ||
|---|---|---|---|---|
| name | pin | name | pin | |
| D0-D7 | 2-9 | DB0-DB7 | * | |
| nSTRB | 1 | R/-W | * | |
| nLF | 14 | E1 | * | |
| INIT | 16 | E2 | * | |
| nSEL | 17 | A0 | * | |
| VDD | RESET/IF | * | ||
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.
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.
INTERFACEThe 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.
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.
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
| Protocol | Display tested | Currently Supported | Remark |
|---|---|---|---|
| AEDEX | Emax | Yes | |
| IEE | No | ||
| Epson | No | Yes | |
| Emax | No | ||
| IBM | No | ||
| Logic Controls | No | Yes | |
| Ultimate | No |
(…): Feature not tested.
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.
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.
DEVICE
Device to use in serial mode. Usual values are /dev/ttyS0 or
/dev/cu.usbserial. Default is /dev/lcd.
WIDTH
x
HEIGHT
Specifies the size of the VFD in characters.
If not given, it defaults to 16x2.
IEEAEDEXEpsonEmaxIBMLogicControlsUltimate
Set the communication protocol to use with the POS display.
If not specified it defaults to AEDEX.
Currently, only AEDEX is supported.
12002400960019200115200
Set the the baud rate communication with the POS display.
If not given the default of 9600 is used.
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
| Display | Controller | Serial | Parallel | Display tested | Type | Remark |
|---|---|---|---|---|---|---|
| NEC FM20X2KB-AB | NEC FIPC8367 | Ok | Ok | Yes | 0 | |
| NEC FC20X2JA | NEC FIPC8367 | (Ok)[1] | (Ok)[1] | No | 0 | Same Controller as on FM20X2KB-AB |
| NEC FC20X1SA-AB/AA | NEC FIPC8367 | (Ok)[1] | (Ok)[1] | No | 0 | Same Controller as on FM20X2KB-AB |
| KD Rev 2.1 | AT90S.... microcontroller | Ok | - | Yes | 1, 0[2] | |
| FUTABA M402SD06GJ | ? | (?)[1] | Ok | Yes | 3 | The display has no user-characters. Serial interface with PC compatible baudrate is optional only, feature not tested. |
| FUTABA M204SD01AA | FUTABA 5P00A016 | (Ok)[1] | (Ok)[1] | No | 3 | |
| Futaba NA202SD08FA | ? | Ok | Ok | Yes | 6 | almost IEE compatible, no Custom-Characters |
| Samsung 20S204DA2 and 20S207DA1 | ? | Ok | Ok | Yes | 3[2], 7[2][1] | The display is FUTABA compatible (hard- and software). Custom-Characters not supported(?). |
| Samsung 20S207DA4 and 20S207DA6 | ? | Ok | Ok | Yes | 7, 3[2] | almost Futaba compatible |
| Noritake CU20026SCPB-T | microcontroller | (Ok)[1] | (Ok)[1] | No | 2 | |
| Noritake CU20045SCPB-T28A | ? | (Ok)[1] | (Ok)[1] | No | 2 | |
| IEE 36657-01 (= 02S-93290-VFD 36657-01) | ? | Ok | Ok | Yes | 4 | |
| IEE S03601-95B | ? | (Ok)[1] | (Ok)[1] | No | 4 | |
| IEE S03601-96-080 | ? | (Ok)[1] | (Ok)[1] | No | 5 | |
| Siemens/Wincor Nixdorf BA63/66 | ? | Ok | - | Yes | 8 | Display 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 | ||||||
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.
The Connections shown have been tested successfully.
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.
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.
CN1:
Pin 33 ------- RxD (Testmode: connect pins 25 and 26, then power up)
CN2:
Pin 1 ------- +5V Pin 2 ------- GND
The blue connector (6pin in a row) (the important one!):
-------------------------------- | +5V +5V RxD GND GND GND | --------------------------------
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.
Pin 2 ------ +5V Pin 4 ------ +5V Pin 6 ------ +5V Pin 10 ------ GND Pin 12 ------ GND Pin 14 ------ GND Pin 19 ------ RxD
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.
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
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
yesno
"no" if display connected serial, "yes" if connected parallel [default: no(serial)].
PORT
Portaddress where the LPT is. Used in parallel mode only. Usual values are 0x278, 0x378 and 0x3BC [default: 0x278].
DELAY
Set parallel port timing delay (us). Used in parallel mode only. [default: 2; legal: 0 - 255].
DEVICE
Device to use in serial mode. Usual values are /dev/ttyS0 and /dev/ttyS1
[default: /dev/lcd].
CUSTOM-CHARACTERSNumber of Custom-Characters [default: Display-Type dependent].
WIDTH
x
HEIGHT
Specifies the size of the VFD.
[default: 20x2]
CODESpecifies the display type.[default: 0] The following type codes are available:
CODE | VFD model |
|---|---|
0 | NEC (FIPC8367 based) VFDs |
1 | KD Rev 2.1 |
2 | Noritake VFDs |
3 | Futaba VFDs |
4 | IEE S03601-95B |
5 | IEE S03601-96-080 |
6 | Futaba NA202SD08FA (allmost IEE compatible) |
7 | Samsung 20S207DA? |
8 | Siemens/Wincor Nixdorf BA63/66 |
Noritake VFDs have not been tested yet. Feedback is welcome.
BRIGHTNESSSet the initial brightness [default: 1000; legal: 0 - 1000] (4 steps 0-250, 251-500, 501-750, 751-1000)
OFFBRIGHTNESSSet 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)
12002400960019200115200
Set the the baud rate communication with the VFD.
If not given [default 9600].
yesno
Enable ISO-8859-1 compatibility [default is yes].
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.
This section talks about using LCDproc with Serial LCD Interface (SLI-OEM) boards from Wirz Electronics.
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.
This section talks about using LCDproc with LCD displays that use the stv5730 chipset.
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.
DEVICE
Name of the device the display appears as. By default first USB serial device
/dev/ttyUSB0 is used.
EDITION
Edition level of the device (can be 1, 2 or 3). The default is 2.
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
Select the display's contrast, 480 is the default.
Permissible values are in the range of 0-1000.
BRIGHTNESS
Select the display's brightness, 480 is the default.
Permissible values are in the range of 0-1000.
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.
This section talks about using LCDproc with LCD displays that use the svga library.
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.
WIDTH
x
HEIGHT
set display size [default: 20x4]
CONTRAST
Set the initial contrast.
Legal values for CONTRAST are 0 - 1000.
If not given, the default value is 500.
This parameter can be set but it does not change anything in the driver.
BRIGHTNESS
Set the initial brightness [default: 1000; legal: 1 - 1000]
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
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!
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 | ||
|---|---|---|---|---|
| name | pin | name | pin | |
| nSTRB | 1 | /WR | * | |
| D0-D7 | 2-9 | DB0-DB7 | * | |
| nLF | 14 | /CE | * | |
| INIT | 16 | C/D | * | |
| nSEL | 17 | /RD | * | |
| VDD | FS | * | ||
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".
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
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.
yesno
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.
yesno
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.
yesno
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 simply outputs the content of the internal framebuffer to the current console using printf().
This section talks about using LCDproc with LCD modules used in Tyan GS10 and GS12 barebones.
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.
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
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.
When using a libusb based driver like IOWarrior,
LCDd needs to be started as root.
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.
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.
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.
WIDTH
x
HEIGHT
Select the LCD size [default: 20x4]
KEYKEYKEYKEYKEYKEY
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_A | Up |
| KeyMap_B | Down |
| KeyMap_C | Left |
| KeyMap_D | Right |
| KeyMap_E | Enter |
| KeyMap_F | Escape |
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.
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.
WIDTH
x
HEIGHT
set display size [default: 20x4]
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
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
Set the initial contrast.
Legal values for CONTRAST are 0 - 1000.
If not given, the default value is 500.
This parameter can be set but it does not change anything in the driver.
BRIGHTNESS
Set the initial brightness [default: 1000; legal: 1 - 1000]
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
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:
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.
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.
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.
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.
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.
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.
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.
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.
The rise time of a digital output can (usually) not be altered by software.
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.
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.
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.
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.
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 ...
This text has originally been taken from a message by
Robin Adams <robin@adams-online.de>
Converted to Docbook and slightly modified May 2002, Rene Wagner <reenoo@gmx.de>
Table of Contents
If you have installed the init-scripts you can simply start, stop and restart LCDd with the init-script.
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.
...
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
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
You will probably more often run lcdproc from the command line than you will run LCDd.
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
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.
Table of Contents
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.
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).
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.
Table of Contents
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.
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.
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.
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.
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.
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:
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.
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).
State on the Title page the name of the publisher of the Modified Version, as the publisher.
Preserve all the copyright notices of the Document.
Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
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.
Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
Include an unaltered copy of this License.
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.
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.
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.
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.
Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.
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.
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."
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.
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 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.
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.
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.
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.