lcd4linux

Introduction

lcd4linux is a small program that reads various information from the kernel (and from other subsystems, especially ISDN) and displays them on a LCD or other display device.

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

#ifdef USE_OLD_UDELAY
lcd4linux -d
  calibrate delay loop (necessary for some drivers)
#endif

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 info messages with '-v'
  generate debugging messages with '-vv'
  debug socket traffic too, with '-vvv'

Diagnostics

lcd4linux on foreground writes (depending on level) to stdout or stderr. The Text-Driver has ist's own diagnostics window.

Started in the background (the default), lcd4linux uses your syslog daemon for logging. Facility is USER, levels are ERR, INFO and DEBUG.

Supported Displays

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

Beckmann+Egle mini-terminal

thanks to Helmut A. Bender [email protected]

Mitsubishi M50530

I got a real cool display (8 lines by 24 characters!) from Udo Altmann ([email protected]) Thanks again! Unfortunately, the driver is not finished yet.

Toshiba T6963

I got another real cool display (240x128 pixel!) from Carsten Nau ([email protected]). Thanks again! Unfortunately, the driver is not finished yet.

PalmOrb

I was told that lcd4linux works fine with PalmOrb, a small program that emulates a Matrix Orbital display on the Palm Pilot.

X11

thanks to Herbert Rosmanith [email protected] 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

a generic raster driver (which is used by the X11-driver, too) is available, it supports:

• PPM (portable pixmap)
• PNG (with libgd)

Text

This is a ncurses based text driver, mainly intended for debugging.

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 [doc/Driver.md][doc/Driver.md] 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, separated 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.

Note

Because of security reasons the config file is assured to be:

• • file is a normal file (or /dev/null)
• • file owner is owner of program
• • file is not accessible by group
• • file is not accessible by other

So if you run lcd4linux as root, /etc/lcd4linux has to be:

chmod 600
chown root.root

Options

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

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

exec

x1 ... x9: command to execute, PATH=/usr/local/bin:/usr/bin:/bin ($X1 ... $X8 is result of command 1..8 in environment)

• Tick_x1 .. 9 delay in ticks (overrides delay_x)
• Delay_x1 ..9 delay in seconds (default 1)
• Max_x1 ..9 max value for bars (default 100)
• Min_x1 ..9 min value for bars (default 0)

battery

Battwarning 10 (default 10)

Mailbox

The option string may be a plain mbox file or a pop3/imap4/nntp server string with the following format:

pop3:[user[:pass]@]machine[:port]
imap4:[user[:pass]@]machine[:port][/dir]
nntp:[user[:pass]@]machine[:port][/dir]

• Port defaults to 110 and 143 respectively.

• If /dir is not given, INBOX is assumed.

• If dir is given for nntp: it should be a valid group name with '.' separating items

• If dir is not given for nntp: all/unread news of subscribed groups from Newsrc are calculated.

• Delay_e1..e9 delay in seconds for querying the MailboxN (default 5)

  • Newsrc ... path/name of your .newsrc file containing subscribed news
  • Note: authorization on newsservers is untested.
  • Note: user and pass may not contain a '/' with above syntax, I hope that's ok.

• SetiDir: directory where seti@home stores its data files

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 doc/<DriverName>.md 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!
• $t<height><token>,<width> will create a time series bar.
  • The data are displayed like '$u', but are shifted every second 1 pixel to the left.
  • Currently only displays based on the pixel-driver support this bar type.

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}
• 'hc' seti@home % completed
• 'ht' seti@home time spent on workunit
• 'e*' mails in mailbox 1-9, total mail
• 'u*' mails in mailbox 1-9, unseen mail
• 'x*' output of command 1-9

Please have a look at lcd4linux.conf.sample, where you can find examples of all options and there usage.

#$Id: README,v 1.23 2002/04/29 11:00:26 reinelt Exp $