lcdproc/docs/LCDd.8

.TH LCDd 8 "9 September 2001" LCDproc
.SH NAME
LCDd - LCDproc server daemon
.SH SYNOPSIS
.B LCDd
[\-\-help] 
[\-\-type <\fIsize\fP>] 
[\-\-driver <\fIdriver\fP> [\fIargs\fP] ]
[\-\-foreground \fI\fP] 
[\-\-backlight <\fImode\fP>] 
[\-\-serverinfo off] 
.SH DESCRIPTION
LCDd is the server portion of LCDproc which listens to a certain port (normally 13666) and displays information on an LCD display.  It works with several types
and sizes of displays.
.PP
LCDd will attempt to open /dev/lcd by default and will error if this
device is not available.  In most cases, it should be sufficient to
link /dev/lcd to the appropriate serial or parallel device.
.PP
To make full use of LCDd, a client such as lcdproc(1) is required.
.SH OPTIONS
Available
.I LCDd
options are:
.TP 8
.B \-h, \-\-help
Display this help screen
.TP 8
.B \-t, \-\-type <size>
select an LCD size (20x4, 16x2, etc...)
.TP 8
.B \-d, \-\-driver <\fIdriver\fP> [\fIargs\fP] 
Adds (another) driver to use to display information.  Any \fIargs\fP specified will be
passed to the chosen driver for initialization.
.TP 8
.B \-f, \-\-foreground
Run in the foreground (no daemon)
.TP 8
.B \-b\fP,\fB \-\--backlight \fI<mode>\fP
Set backlight mode (on, off, open)
.TP 8
.B \-i, \-\-serverinfo off
Set the server screen to low priority
.PP
Help on each driver's parameters are obtained upon request:
"LCDd -d driver --help"
.SS
Supported Drivers
Supported display drivers include:
.TP
.B CFontz
CrystalFontz LCD displays
.TP
.B curses
Standard video display using the ncurses library
.TP
.B HD44780
Hitachi HD44780 LCD displays
.TP
.B BayRad
EMAC BayRad displays
.TP
.B irmanin
IrMan infrared (input)
.TP
.B lircin
Infrared (input)
.TP
.B sli
Wirz SLI driver (unknown)
.TP
.B joy
Joystick driver (input)
.TP
.B MtxOrb
Matrix Orbital displays (not Matrix Orbital GLK displays)
.TP
.B LB216
LB216 LCD display
.TP
.B glk
Matrix Orbital GLK graphical LCD displays
.TP
.B text
Standard "hard-copy" text display
.TP
.B debug
Undocumented debug driver
.PP
Multiple drivers can be used simultaneously; thus, for example, a Matrix Orbital display (MtxOrb driver)
can be combined with the an infrared driver (irmanin driver).
.SH INVOCATION
.TP
LCDd -d MtxOrb "--device /dev/lcd --contrast 200" -d joy
Start LCDd with the Matrix Orbital driver and the Joystick input driver,
with the /dev/lcd device and a contrast value of 200.
.SH SERVER PROTOCOL
There is a basic sequence:
.TP 8
1. Open a TCP connection to the LCDd server port (usually 13666).
.TP 8
2. Say "hello"
.TP 8
3. The server will return some information on the type
of display available.
.TP 8
4. Define (and use) a new screen and its widgets.
.TP 8
5. Close the socket when done displaying data.
.PP
There are many commands for the LCDd server:
.TP 8
.B hello
This starts a client-server session with the LCDd server; the
server will return a data string detailing the type of display
and its size.
.TP 8
.B client_set [-name #id]
Set the client's name, etc.
.TP 8
.B screen_add #id
Add a new screen to the display.
.TP 8
.B screen_del #id
Remove a screen from the display.
.TP 8
.B screen_set \fI#id\fP [\fB-priority\fI number\fP] [\fB-name\fI "my_name"\fP] [\fB-duration\fI integer\fP] [\fB-wid\fI width\fP] [\fB-hgt\fI height\fP] [\fB-heartbeat\fI mode\fP]
Initialize a screen, or reset its data.
.TP 8
.B widget_add \fI#screen #id type\fR [\fB-in \fI#id\fR]
Add a widget to screen \fI#screen\fR.
.TP
.B widget_del \fI#screen #id\fR
Delete widget \fI#id\fR from screen \fI#screen\fR.
.TP
.B widget_set \fI#screen #id data\fR
Set the data used to define a particular widget \fI#id\fR on screen
\fI#screen\fR.
.SS
Heartbeat Modes
Valid heartbeat mode values (for the \fBscreen_set\fR command) are:
.TP
.BR on , " heart"
Display heart symbol.
.TP
.BR normal , " default"
Normal display.
.TP
.BR off , " none"
No heartbeat display.
.TP
.B slash
Display rotating slash display.
.SS
Priorities
Valid priority values (used in the \fBscreen_set\fR command) are as follows:
.TP
.B 0
This is rather extreme; \fIdon't do this!\fR
.TP
.B 1
Extremely important!
.TP
.B 16
Emergency priority
.TP
.B 32
Very high priority (important)
.TP
.B 64
High priority (normal)
.TP
.B 128
Normal (recommended)
.TP
.B 192
Low priority (normal)
.TP
.B 224
Very low priority (very unimportant)
.TP
.B 240
Extremely low priority
.TP
.B 255
This screen won't show up very much even if there are
no other screens queued...
.PP
An example of how to properly use priorities is as follows:
.PP
Imagine you're making an mp3 player for lcdproc.  When the
song changes, it's nice to display the new name immediately.
So, you could set your screen's priority to 64, wait for
the server to display (or ignore) your screen, then set the
screen back to 128.  This would cause the mp3 screen to
show up as soon as the one onscreen was finished, then
return to normal priority afterward.
.PP
Or, let's say your client monitors the health of hospital
patients.  If one of the patients has a heart attack, you
could set the screen priority to 16 (emergency), and it
would be displayed immediately.  It wouldn't even wait for
the previous screen to finish.  Also, the display would stay
on screen most of the time until the user did something about it.
.PP
A priority of 1 would stay onscreen permanently, with
flashing lights and other visual cues if possible.
Using this priority is \fInot\fR recommended.
.PP
The duration can be either a positive number, or -1.  A
positive number (greater than zero) indicates how many
display frames the screen should last.  A 0 (zero) or -1 means
that the server should use "auto" duration, which is
probably a good idea.  This will be
whatever the user wants.  It defaults to 4 seconds (32
frames), or will be a calculated value for things such as scrollers.
.SS
Widget Types
Widgets can be any of the following:
.TP
.B string
A text string to display (as is).
.TP
.B hbar
A horizontal bar graph.
.TP
.B vbar
A vertical bar graph.
.TP
.B title
A title displayed across the top of the display, within a banner.
.TP
.B icon
A graphic icon.
.TP
.B scroller
A scrolling text display, scrolling either horizontally or vertically.
.TP
.B frame
A \fIcontainer\fR to contain other widgets, permitting them to be refered to
as a single unit.  A widget is put inside a frame by using the -in \fI#id\fR
parameter, where \fI#id\fR refers to the id of the frame.
.PP
Widgets are drawn on the screen in the order they are created.
.SS Setting Widget Data
In the \fBwidget_set\fR command, the \fIdata\fR argument depends on which widget is being
set.  Each widget takes a particular set of arguments which defines its form and behavior:
.TP
.B string
x y text
.TP
.B hbar
x y length_in_pixels
.TP
.B vbar
x y length_in_pixels
.TP
.B icon
x y binary_data
.TP
.B title
text
.TP
.B scroller
left top right bottom direction speed text
.sp
The \fItext\fR defined will scroll in the direction defined.  Valid directions
are \fBh\fR (horizontal) and \fBv\fR (vertical).  The speed defines how many
"movements" (or changes) will occur per frame.  A positive number indicates
frames per movement; a negative number indicates movements per frame.
.TP
.B frame
left top right bottom wid hgt dir speed
.sp
Frames define a visible "box" on screen,
from the (\fIleft\fR, \fItop\fR) corner to the
(\fIright\fR, \fIbottom\fR) corner.  The actual data may be bigger,
and is defined as \fIwid\fR (width) by \fIhgt\fR (height); if it is
bigger, then the frame will scroll in the direction (\fIdir\fR)
and \fIspeed\fR defined.
.SH BUGS
If LCDd seems to quietly disappear upon invocation or other similar problems,
check the order of the options and the quoting involved.  Some combinations
of options will be misread and thus fail.
.PP
Try using the -d option last.
.SH AUTHOR
LCDd was written by William Ferrell (choadster@earthlink.net) and Scott Scriv
en (scriven@cs.colostate.edu).

The newest version of LCDd should be available from here as part of the lcdproc package:

                http://lcdproc.omnipotent.net/

.SH LEGAL STUFF
The lcdproc package is released as "WorksForMe-Ware".  In other words, it is free, kinda nea
t, and we don't guarantee that it will do anything in particular on any machine
except the ones it was developed on.
.PP
It is technically released under the GNU GPL license (you should have received t
he file, "COPYING", with LCDproc) (also, look on http://www.fsf.org/ for more in
formation), so you can distribute and use it for free -- but you must make the s
ource code freely available to anyone who wants it.
.PP
For any sort of real legal information, read the GNU GPL (GNU General Public Lic
ense).  It's worth reading.