lcdproc/docs/LCDd.8

.TH LCDd 8 "18 June 2006" LCDproc "LCDproc suite"
.SH NAME
LCDd - LCDproc server daemon
.SH SYNOPSIS
.B LCDd
[\fB\-hfis\fP] 
[\fB\-c\fP \fIconfig\fP] 
[\fB\-d\fP \fIdriver\fP] 
[\fB\-a\fP \fIaddr\fP] 
[\fB\-p\fP \fIport\fP] 
[\fB\-u\fP \fIuser\fP] 
[\fB\-w\fP \fItime\fP] 
[\fB\-r\fP \fIlevel\fP] 

.SH DESCRIPTION
LCDd is the server part of LCDproc, a deamon 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
Most settings of LCDproc are configured through the LCDd configuration file,
which is normally /etc/LCDd.conf. Before running LCDd you should carefully
read through that file and modify everything neccessary according to your needs.
Otherwise you might encounter LCDd not running properly on your system.
.PP
To make full use of LCDd, a client such as lcdproc(1) is required.

.SH OPTIONS
Available LCDd options are:
.TP
.B \-h
Display this help screen
.TP
.B \-c \fIconfig\fP
Use a configuration file other than /etc/LCDd.conf
.TP
.B \-d \fIdriver\fP
Add a driver to use (output only to first)
.TP
.B \-f
Run in the foreground
.TP
.B \-i
Disable showing the main LCDproc server screen in rotation
.TP
.B \-w \fIwaittime\fP
Time to pause at each screen (in seconds)
.TP
.B \-a \fIaddr\fP
Network IP address to bind to
.TP
.B \-p \fIport\fP
Network port to listen for connections on
.TP
.B \-u \fIuser\fP
User to run as
.TP
.B \-s
Output messages to syslog
.TP
.B \-r \fIlevel\fP
Report level (default=2)

.SS Supported Drivers
Currently supported display drivers include:
.TP
.B bayrad
BayRAD LCD modules by EMAC Inc.
.TP
.B CFontz
CrystalFontz CFA-632 and CFA-634 serial LCD displays
.TP
.B CFontz633
CrystalFontz CFA-633 serial/USB LCD displays
.TP
.B CFontzPacket
CrystalFontz CFA-631, CFA-633 and CFA-635 serial/USB LCD displays
.TP
.B curses
Standard video display using the (n)curses library
.TP
.B CwLnx
serial/USB displays by Cwlinux (http://www.cwlinux.com)
.TP
.B EyeboxOne
LCD display on the EyeboxOne (http://www.rightvision.com)
.TP
.B g15
LCD display on the Logitech G15 keyboard
.TP
.B glcdlib
graphical LCDs supported by graphlcd-base
.TP
.B glk
Matrix Orbital GLK Graphic Displays
.TP
.B hd44780
Hitachi HD44780 LCD displays.
This driver supports the following sub-drivers (a.k.a. \fIconnection types\fP):
.RS
.TP
.B 4bit
LCD 4bit-mode, connected to a PC parallel port
.TP
.B 8bit
LCD 8bit-mode, connected to a PC parallel port
.TP
.B serialLpt
LCD in 4bit-mode through a 4094 shift register
.TP
.B winamp
LCD in 8bit-mode using \fIWinAmp\fP-wiring, connected to a PC parallel port
.TP
.B picanlcd
LCD driven by a PIC-an-LCD chip/board by Dale Wheat, connected to a serial port
.TP
.B lcdserializer
LCD driven by a PIC16C54-based piggy-back board, connected to a serial port
.TP
.B los-panel
LCD driven by an Atmel AVR based board, connected to a serial port
.TP
.B vdr-lcd
???, connected to a serial port
.TP
.B lis2
LIS2 from VLSystem (http://www.vlsys.co.kr), connected to USB
.TP
.B bwctusb
USB-to-HD44780 converter by BWCT (http://www.bwct.de)
.TP
.B i2c
LCD in 4-bit mode driven by PCF8574(A) / PCA9554(A), connected via I2C bus
.RE
.TP
.B icp_a106
ICP A106 alarm/LCD board in 19" rack cases by ICP
.TP
.B imon
iMON IR/VFDamodules in cases by Soundgraph/Ahanix/Silverstone/Uneed/Accent
.TP
.B IOWarrior
Code Mercenaries IOWarrior
.TP
.B irman
IrMan infrared (input)
.TP
.B joy
Joystick driver (input)
.TP
.B lb216
LB216 LCD displays
.TP
.B lcdm001
kernelconcepts.de 20x4 serial LCD displays
.TP
.B lcterm
serial LCD terminal from Helmut Neumark Elektronik (http://www.neumark.de)
.TP
.B lirc
Infrared (input)
.TP
.B MD8800
VFD displays in Medion MD8800 PCs
.TP
.B ms6931
MSI-6931 displays in 1U rack servers by MSI
.TP
.B mtc_s16209x
MTC_S16209x LCD displays by Microtips Technology Inc
.TP
.B MtxOrb
Matrix Orbital displays (except Matrix Orbital GLK displays)
.TP
.B NoritakeVFD
Noritake VFD Device CU20045SCPB-T28A
.TP
.B pyramid
LCD displays from Pyramid (http://www.pyramid.de) 
.TP
.B sed1330
SED1330/SED1335 (aka S1D13300/S1D13305) based graphical displays
.TP
.B sed1520
122x32 pixel graphic displays based on SED1520 controllers
.TP
.B serialVFD
NEC (FIPC8367 based) and FUTABA VFDs
.TP
.B sli
Wirz SLI driver (unknown)
.TP
.B stv5730
STV5730A on-screen display chip
.TP
.B svga
VGA monitors using svgalib 
.TP
.B t6963
Toshiba T6963 based LCD displays
.TP
.B text
Standard "hard-copy" text display
.TP
.B tyan
LCDi module in Tyan Barebone GS series
.TP
.B ula200
ULA-200 device from ELV (http://www.elv.de)
.TP
.B xosd
On Screen Display on X11
.PP
Multiple drivers can be used simultaneously; thus, for example, a Matrix Orbital display (MtxOrb driver)
can be combined with an infrared driver (irmanin driver).

.SH INVOCATION
.R LCDd -d MtxOrb -d joy
.PP
As of version 0.4.3, driver parameters are read from a configuration file
(default location /etc/LCDd.conf) rather than being passed on the command
line as arguments.
The invocation example above will start LCDd with the Matrix Orbital driver
and the Joystick input driver,and attempt to load the driver parameters
from the default configuration file.

.SH LCDPROC CLIENT-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 \fIname\fP
Set the client's name.
.TP 8
.B screen_add \fI#id\fP
Add a new screen to the display.
.TP 8
.B screen_del \fI#id\fP
Remove a screen from the display.
.TP 8
.B screen_set \fI#id\fP [\fB-name\fI "name"\fP] [\fB-wid\fI width\fP] [\fB-hgt\fI height\fP] [\fB-priority\fI prio\fP] [\fB-duration\fI int\fP] [\fB-timeout\fI int\fP] [\fB-heartbeat\fI mode\fP] [\fB-backlight\fI mode\fP] [\fB-cursor\fI mode\fP] [\fB-cursor_x\fI xpos\fP] [\fB-cursor_y\fI ypos\fP]
Initialize a screen, or reset its data.
.TP 8
.B widget_add \fI#screen #id type\fR [\fB-in \fI#frame\fR]
Add a widget of type \fItype\fPto 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
Display pulsing heart symbol.
.TP
.BR off
No heartbeat display.
.TP
.BR open
Use client's heartbeat setting. This is the default.

.SS Backlight Modes
Valid heartbeat mode values (for the \fBscreen_set\fR command) are:
.TP
.B on
Turn backlight on.
.TP
.B off
Turn backlight off
.TP
.B toggle
Turn backlight off when it is on and vice versa.
.TP
.B open
Use client's backlight setting. This is the default.
.TP
.B blink
Blinking backlight
.TP
.B flash
Flashing blacklight

.SS Priorities
Valid priority settings (used in the \fBscreen_set\fR command) are as follows:
.TP
.B input
The client is doing interactive input.
.TP
.B alert
The screen has an important message for the user.
.TP
.B foreground
an active client
.TP
.B info
Normal info screen, default priority.
.TP
.B background
The screen is only visible when no normal info screens exists.
.TP
.B hidden
The screen will never be visible.
.PP
For compatibility with older versions of clients a mapping of numeric
priority values is also supported:
.TP
.B 1 - 64
foreground
.TP
.B 65 - 192
normal
.TP
.B 193 - (infinity)
background
.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 \fBforeground\fP, wait for
the server to display (or ignore) your screen, then set the
screen back to i\fBnormal\fP.  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 \fBalert\fP, 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.

.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 \fIx y text\fP
.sp
Displays \fItext\fP at position (\fIx\fP,\fIy\fP).
.TP
.B title \fItext
.sp
Uses \fItext\fP as title to display.
.TP
.B hbar \fIx y length\fP
.sp
Displays a horizontal bar starting at position (\fIx\fP,\fIy\fP) that is \fIlength\fP pixels wide.
.TP
.B vbar \fIx y length\fP
.sp
Displays a vertical bar starting at position (\fIx\fP,\fIy\fP) that is \fIlength\fP pixels high.
.TP
.B icon \fIx y name\fP
.sp
Displays the icon \fIname\fP at position (\fIx\fP,\fIy\fP).
.TP
.B scroller \fIleft top right bottom direction speed text\fP
.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 \fIleft top right bottom wid hgt dir speed\fP
.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.
.TP
.B num \fIx int\fP
.sp
Displays large decimal digit \fIint\fP at the horizontal position \fIx\fP,
which is a normal character x coordinate on the display.
The special value 10 for \fIint\fP displays a colon.

.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 FILES
.na
.nf
\fB/etc/LCDd.conf\fR, LCDd default configuration file

.Sh SEE ALSO
.Xr lcdproc 1

.SH AUTHOR
LCDd was originally written by William Ferrell (wwf@splatwerks.org) and Scott Scriv
en (scriven@cs.colostate.edu).

Since that time various people have contributed to LCDproc.

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

                http://www.lcdproc.org/

.SH LEGAL STUFF
The lcdproc package is released as "WorksForMe-Ware".
In other words, it is free, kinda neat, 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 the file,
"COPYING", with LCDproc) (also, look on http://www.fsf.org/ for more information),
so you can distribute and use it for free -- but you must make the source code freely
available to anyone who wants it.
.PP
For any sort of real legal information, read the GNU GPL (GNU General Public License).
It's worth reading.