.\" Made by Sampo Niskanen
.TH ledd 8 "January, 2001" "ledcontrol @VERSION@"
.SH NAME
ledd \- scriptable LED control daemon
.SH SYNOPSIS
.B ledd
[OPTIONS]...
.SH DESCRIPTION
.B ledd
is part of the ledcontrol package, which allows you to show arbitrary
information on the normally-unused keyboard LEDs. It is fully
scriptable, so you can show any TRUE/FALSE condition accessible or
indicate an arbitrary value. It supports blinking LEDs with priority
levels and animations. The LEDs not used by
.B ledd
should function as normal.
.PP
.B ledd
itself is the daemon that sets the LEDs the way other programs or
scripts tell it to. It has to be running before the other programs can
be used.
.PP
.B ledd
work both in X and on a text console.
.SH OPTIONS
.TP
\fB\-h\fR, \fB\-\-help\fR
Show short help message.
.TP
\fB\-v\fR, \fB\-V\fR, \fB\-\-version\fR
Show version information.
.TP
\fB\-c\fR \fIFILE\fR, \fB\-\-config\fR \fIFILE\fR
Read configuration from \fIFILE\fR instead of default configuration
file. Several files may be given by repeating the option.
.TP
\fB\-p\fR \fIFILE\fR, \fB\-\-pipe\fR \fIFILE\fR
Use \fIFILE\fR as an additional pipe to read commands from.
.B ledd
will create a pipe with the name and everything written to it will be
parsed as commands (see
.B COMMANDS
below).
.TP
\fB\-s\fR \fIFILE\fR, \fB\-\-startup\fR \fIFILE\fR
Use \fIFILE\fR as an additional startup program to read commands
from. Everything the program writes to standard output will be parsed
as commands (see
.B COMMANDS
below). Everything written to standard error will be logged on a
warning level (eg. with syslog).
.TP
\fB\-d\fR, \fB\-\-daemon\fR
Fork into background at startup. This option overrides all "daemon"
commands in the configuration files (see
.BR ledd.conf (5)).
.TP
\fB\-D\fR, \fB\-\-no\-daemon\fR
Do not fork into background. This option overrides all "daemon" commands
in the configuration files (see
.BR ledd.conf (5)).
.SH "LED STATES"
The LEDs have four different basic states (excluding animation):
"normal" ie. what the LED would normally show; "on" and "off", which
are self-evident and "blink" in which the LED blinks according to a
given blink pattern (these are discussed further in section
\fBCOMMANDS\fR).
.PP
Each LED (Num Lock, Caps Lock and Scroll Lock) has furthermore ten
priority levels of these basic states, 0 (lowest) to 9 (highest). The
highest priority level which is not set to "normal" is used to
determine how the LED acts. For example, if you want a LED to light up
when a ppp-link is up and blink when some host on its other side
responds, you might set level 1 "off", level 4 "on" or "normal"
depending whether a ppp-link is up and level 6 "blink" or "normal"
depending on whether the remote machine answers.
.PP
A reasonable configuration of levels might be as follows:
.TP
0
reserved for an outside program's lowest level
.TP
1
default values of LEDs (normally the LEDs which are used are set "off"
here)
.TP
3-7
levels for normal configuration
.TP
8-9
reserved for outside programs
.SH COMMANDS
Commands consist of a command keyword and arguments, separated by
whitespaces. Currently there are three types of commands: "set",
"anim" and "nop".
.PP
The "set" command sets the basic states ("normal", "on", "off" and
"blink") for the LEDs. It is further discussed below.
.PP
The "anim" command sets an animation sequence to play. The animation
overrides all other settings. It is further discussed below.
.PP
The "nop" command simply ignores all arguments and does nothing.
.SH "Arguments for set"
.\" TODO: How do I get quotes around set?
The first argument of a "set" command tells which LEDs and which
levels is sets. It is a string consisting of the letters `n', `c' and
`s' for Num Lock, Caps Lock and Scroll Lock, respectively. Each letter
can be followed by a number indicating the priority level to set. For
example, ``n4n6s9'' would set Num Lock on levels 4 and 6 and Scroll
Lock on level 9.
.PP
The second argument can be "normal", "on", "off", "blink", "dutycycle"
or "frequency". The first three are self-evident and no other
arguments may follow. The other three are all internally "blink"
types. "dutycycle" and "frequency" are meant to express arbitrary
values by the blink sequences they make. They are explained below:
.TP
\fBblink\fR \fITIME1\fR [\fITIME2\fR]...
Makes a blink sequence in which the LED is first \fITIME1\fR
milliseconds on, then \fITIME2\fR milliseconds off, \fITIME3\fR
milliseconds on, and so on. Normally the list should contain an even
number of values, but this is not enforced. For instance, "blink 500"
and "blink 500 500" are equivalent.
.TP
\fBdutycycle\fR \fICYCLE\fR \fIMIN\fR \fIMAX\fR \fIVALUE\fR
Makes a two-part blink sequence which in whole is \fICYCLE\fR
milliseconds long. How much time the LED is on depends on
\fIVALUE\fR. If \fIVALUE\fR is less than \fIMIN\fR or greater than
\fIMAX\fR, the LED is totally off or on, respectively. Otherwise the
time on is linearly interpolated. If \fIMIN\fR is greater than
\fIMAX\fR, then the setting is inverted. \fIMIN\fR, \fIMAX\fR and
\fIVALUE\fR may be floating-point numbers.
.TP
\fBfrequency\fR \fIMIN\fR \fIFREQ1\fR \fIMAX\fR \fIFREQ2\fR \fIVALUE\fR
Makes a two-part blink sequence in which the time on and off are
equally long and the time is determined by \fIVALUE\fR. If \fIVALUE\fR
is less than \fIMIN\fR, then the LED is off. Otherwise the length of
one part is interpolated between \fIFREQ1\fR and \fIFREQ2\fR
milliseconds (if \fIVALUE\fR > \fIMAX\fR, then \fIFREQ2\fR is
used). This generates a feeling of the LED blinking more and more
frantically as the value grows.  \fIMIN\fR, \fIMAX\fR and \fIVALUE\fR
may be floating-point numbers.
.SH "Arguments of anim"
The animation sequence takes a list of arguments, which can be either
numbers, strings consisting of the characters ``scnSCNx'' or
commands. There can be only one animation acting at one time, so
multiple animations will override each other. Note also that the
animations override all other priority levels and the basic states are
only used when the animation sets a LED to normal (all LEDs are set to
normal at the beginning and end of the animation).
.PP
Numbers are taken as delay times, the value's amount of milliseconds
is waited.
.PP
The strings define what LEDs to set. `N', `C' and `S' turn Num Lock,
Caps Lock and Scroll Lock on, respectively, `n', `c' and `s' turn them
off and `xn', `xc' and `xs' set them to normal.
.PP
The only command at the present time is "loop". It specifies that the
rest of the animation is to be looped indefinitely. It is only stopped
when another animation (perhaps a blank one) is given.
.SH "GIVING COMMANDS TO LEDD"
.B ledd
takes commands in two ways. First, it has pipe files from which it
reads the commands. These commands are normally given with the
.BR ledcontrol (1)
program or written directly to the pipe. Secondly, on startup
.B ledd
will start a given amount of subprocesses (given in the configuration
files or on command line) and parse everything they write to standard
output as commands. Everything the programs write to standard error
will be logged at a warning level (eg. with \fBsyslogd\fR).
.PP
There also exists a graphical front-end for
.BR ledcontrol (1),
.BR gled (1),
which is useful for testing commands and experimenting.
.SH "EXAMPLES OF COMMANDS"
Examples of some commands for \fBledd\fR:
.TP
set s0n0 off
Set lowest-level Scroll Lock and Num Lock off.
.TP
set s5 blink 300 100
Set level-5 Scroll Lock blinking with 0.3 seconds on and 0.1 seconds
off.
.TP
set n4 on
Set level-4 Num Lock on.
.TP
set n4 normal
Set level-4 Num Lock to normal. (Removes effect of previous example.)
.TP
set s5 dutycycle 1000 0.8 1.9 \fIxxx\fR
Set level-5 Scroll Lock to indicate value \fIxxx\fR. Below 0.8 the LED
is off, over 1.9 it is on, in between the ratio is linearly
interpolated. One blink sequence always takes 1 second.
.TP
set s5 frequency 0.8 1000 1.9 100 \fIxxx\fR
Set level-5 Scroll Lock to indicate value \fIxxx\fR. Below 0.8 the LED
is off, at exactly 0.8 it blinks 1 second on, 1 second off, at and
over 1.9 it blinks 0.1 seconds on, 0.1 seconds off. Between 0.8 and
1.9 the length is linearly interpolated.
.TP
anim NCS 200 ncs 200 NCS 200 ncs 200 N loop 100 Cn 100 Sc 100 Cs 100 Nc
Flashes all LEDs twice and then an "emergency" flashing along the LEDs.
.TP
anim
Stop any current animation.
.SH "EXAMPLES OF USE"
The LEDs can be used to indicate any condition available. Built in
possibilities include showing system load, network load, mail
presence (can be detected with the led_size command), etc. If some two
conditions are dependant (eg. a remote machine does not answer if the
local machine is not connected to the Internet), they often can be
shown on the same LED. Here are a few not-so-trivial suggestions:
-\" TODO: How can I make a nice list?
.br
- show ppp-link with a steady light and remote machine responding with
the same LED blinking
.br
- Any suggestions? Please mail me!! Wild ideas are always welcome!
.SH LICENSE
Ledcontrol and all its pieces (including \fBledd\fR) are distributed
under the GNU General Public License (GPL).
.SH FILES
.TP
\fI@sysconfdir_int@/ledd.conf\fR
default configuration file for
.B ledd
.TP
\fI@datadir_int@/startup.sh\fR
default startup script
.TP
\fI@sysconfdir_int@/ledcontrol.conf\fR
configuration file for \fIstartup.sh\fR
.SH "SEE ALSO"
.BR ledcontrol (1),
.BR startup.sh (8),
.BR ledd.conf (5),
.BR ledcontrol.conf (5),
.BR gled (1),
.BR syslogd (8)
.SH AUTHOR
Ledcontrol was written by Sampo Niskanen <sampo.niskanen@iki.fi>. You
can get the latest version of ledcontrol from
.I http://www.iki.fi/sampo.niskanen/ledcontrol/
.SH BUGS
Some anomalies may be encountered with the LEDs in X. Namely, setting
the LEDs to a normal state does not change the LED state. This can be
overcome by pressing some Lock-key twice. Normally you don't want to
set the LEDs back to their normal state, so this shouldn't be much of
a problem.
.PP
You should have only "/dev/console" as a tty in \fIledd.conf\fR if you
want the LEDs to be set both in X and on the text consoles. Otherwise
the LEDs probably won't work in X.
.PP
The default startup script may cause a disk-access every few
seconds. See
.BR startup.sh (8)
for more info.