#
# $Id: README,v 1.12 2001/03/02 10:18:45 ltoetsch Exp $
#
This is the README file for lcd4linux
INTRODUCTION
lcd4linux is a small program that reads various information from the kernel
(and probably from other subsystems, especially ISDN) and displays them on a LCD.
It supports displaying text values and different types of bars: Horizontal and
vertical bars, logarithmic bars, split bars (two independent bars in one row).
USAGE
lcd4linux -h
print version number and a small help text, then exit
lcd4linux -l
list available drivers
lcd4linux -d
calibrate delay loop (necessary for some drivers)
lcd4linux [-c key=val] [-F] [-f config-file] [-o output] [-q] [-v]
run lcd4linux
overwrite entries from the config-file with '-c'
do not fork and detach with '-F'
use configuration from 'config-file' instead of /etc/lcd4linux.conf
write picture to 'output' (raster driver only)
suppress startup splash screen with '-q'
generate debugging messages with '-v'
SUPPORTED DISPLAYS
* Matrox Orbital: <http://www.matrixorbital.com>
"LCD0821": 2 lines by 8 characters
"LCD1621": 2 lines by 16 characters
"LCD2021": 2 lines by 20 characters
"LCD2041": 4 lines by 20 characters (tested)
"LCD4021": 2 lines by 40 characters
* CrystalFontz <http://www.crystalfontz.com>
any of 626, 632, 634 and 636.
* HD44780-based displays
This driver supports display modules based on the Hitachi HD44780 chip,
connected to a parallel port. These displays are made by different
manufactures, and come in various sizes.
* PalmOrb
I was told that lcd4linux works fine with PalmOrb, a small program that
emulates a Matrox Orbital display on the Palm Pilot.
* X11
thanks to Herbert Rosmanith <herp@wildsau.idv.uni-linz.ac.at> a driver for the
X Window System is available. It supports any size at any resolution. A very
small XLCD4Linux-Window can even swallow on the KDE Panel!
* Raster formats:
a generic raster driver (which is used by the X11-driver, too) is availiable,
PPM (portable pixmap) is the only output format at the moment. I'm working
on PNG!
* other displays: lcd4linux and especially the display driver code is very modular,
so it should be quite easy to write a driver for any display. See README.driver
for details. Contributors are welcome!!!
CONFIGURATION
The configuration file (default: /etc/lcd4linux.conf) has a very simple format:
Every line consists of a key and a value, seperated by whitespace (blanks or tabs).
Values can contain whitespace, and can be enclosed in single or double quotes.
A key must not contain whitespace. Keys are NOT case-sensitive. Order doesn't matter.
Empty lines and all text on a line after a '#' will be ignored. If you want to
use '#' in a value (think of X11-colors), you have to quote it with a backslash.
The configuration file contains information for different modules of lcd4linux:
Global options:
tick: time in milliseconds between bar updates
tack: time in milliseconds between text updates (text can be updated less often than
bars, so you get a smooth bar display and readable text)
tau: time constant (in milliseconds) for damping function (not used by now)
Data-specific options:
overload: load average threshold and bar scaling. The '%L' token (see below) displays
a '!' instead of a blank if the current load average exceeds this value.
load bars are scaled by this value (load=overload gives 100%)
fifo: path to fifo for communication with isdnlog (not yet implemented)
sensor1: path to the 1st temperature file (e.g. /proc/sys/dev/sensors/w83781d-isa-0290/temp1)
it is important that you use the isa sensors, because the i2c sensors are very slow!
sensor1_min: temperature where the corresponding bar starts
sensor1_max: temperature where bar ends
sensor[2..9], -_min, -_max: entries for the 2nd to 9th temperature sensor
Driver-specific options:
Display: the name of a display model (see "supported displays" above)
every driver has its own configuration options (e.g. 'Port', 'Speed', ...)
see README.<Drivername> for details!
Display options:
row1: Text to display in row 1
row[2-max]: Text to display in other rows
The text to be displayed can contain specific directives, which will be replaced
by the appropriate values, or will create bars:
'\nnn` will write the ASCII-character nnn (octal)
'%<token>' will be replaced by the value of <token>
'%%' will write a '%'
'%$' will write a '$'
'$<direction><length><token>[+<token>] will create a bar with the specified direction
and length (in characters) with the value of <token>. If the driver supports dual bars,
you can specify the second value with '+<token>'.
<direction> can be 'l' (left), 'r' (right), 'u' (up) or 'd' (down).
If you specify the direction in upper case, a logarithmic bar will be created.
note that the space occupied by a bar always grows from left to right or from top to
bottom, regardless of the direction!
Tokens:
'o', operating system name ('Linux')
'v', operating system release ('2.0.38')
'p', processor ('i686')
'r', total amount of memory installed (MB)
'mt', total memory from /proc/meminfo (kB)
'mu', used memory (kB)
'mf', free memory (kB)
'ms', shared memory (kB)
'mb', buffers (kB)
'mc', page cache (kB)
'ma', application memory (kB) = used - buffer - cache
'l1', load average for the past 1 minute
'l2', load average for the past 5 minutes
'l3', load average for the past 15 minutes
'L', '!' if load > overload (from config)
'cu', percentage of CPU in user mode
'cn', percentage of CPU in niced tasks
'cs', percentage of CPU in system mode
'cb', percentage of CPU busy (=100-idle)
'ci', percentage of CPU idle
'dr', disk blocks read
'dw', disk blocks written
'dt', disk blocks total (read+write)
'dm', disk blocks max (read, write)
'nr', network bytes received
'nw', network bytes transmitted
'nt', network bytes total (receive+transmit)
'nm', network bytes max (receive, transmit)
'ii', ISDN bytes received
'io', ISDN bytes sent
'it', ISDN bytes total (received+send)
'im', ISDN bytes max (received, send)
'ic', ISDN connected (0=offline, 1=online)
'ti', PPP bytes received
'to', PPP bytes sent
'tt', PPP bytes total (received+send)
'tm', PPP bytes max (received, send)
's1', temperature of sensor 1
's2', temperature of sensor 2 (up to s9)
'bp', battery percentage (APM by now)
'bs', battery status ('=' = online, '+' = charging, '-' discharging)
'bd', battery duration in s{econds}, m{ins}, h{ours} or d{ays}