ledd(8)

NAME

ledd - scriptable LED control daemon

SYNOPSIS

ledd [OPTIONS]...

DESCRIPTION

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 ledd should function as normal.

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.

ledd work both in X and on a text console.

OPTIONS

-h, --help: Show short help message.
-v, -V, --version: Show version information.
-c FILE, --config FILE: Read configuration from FILE instead of default configuration file. Several files may be given by repeating the option.
-p FILE, --pipe FILE: Use FILE as an additional pipe to read commands from. ledd will create a pipe with the name and everything written to it will be parsed as commands (see COMMANDS below).
-s FILE, --startup FILE: Use FILE as an additional startup program to read commands from. Everything the program writes to standard output will be parsed as commands (see COMMANDS below). Everything written to standard error will be logged on a warning level (eg. with syslog).
-d, --daemon: Fork into background at startup. This option overrides all "daemon" commands in the configuration files (see ledd.conf(5)).
-D, --no-daemon: Do not fork into background. This option overrides all "daemon" commands in the configuration files (see ledd.conf(5)).

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 COMMANDS).

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.

A reasonable configuration of levels might be as follows:

0 reserved for an outside program's lowest level

1 default values of LEDs (normally the LEDs which are used are set: "off" here)
3-7 levels for normal configuration
8-9 reserved for outside programs

COMMANDS

Commands consist of a command keyword and arguments, separated by whitespaces. Currently there are three types of commands: "set", "anim" and "nop".

The "set" command sets the basic states ("normal", "on", "off" and "blink") for the LEDs. It is further discussed below.

The "anim" command sets an animation sequence to play. The animation overrides all other settings. It is further discussed below.

The "nop" command simply ignores all arguments and does nothing.

Arguments for 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.

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:

blink TIME1 [TIME2]...: Makes a blink sequence in which the LED is first TIME1 milliseconds on, then TIME2 milliseconds off, TIME3 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.
dutycycle CYCLE MIN MAX VALUE: Makes a two-part blink sequence which in whole is CYCLE milliseconds long. How much time the LED is on depends on VALUE. If VALUE is less than MIN or greater than MAX, the LED is totally off or on, respectively. Otherwise the time on is linearly interpolated. If MIN is greater than MAX, then the setting is inverted. MIN, MAX and VALUE may be floating-point numbers.
frequency MIN FREQ1 MAX FREQ2 VALUE: Makes a two-part blink sequence in which the time on and off are equally long and the time is determined by VALUE. If VALUE is less than MIN, then the LED is off. Otherwise the length of one part is interpolated between FREQ1 and FREQ2 milliseconds (if VALUE > MAX, then FREQ2 is used). This generates a feeling of the LED blinking more and more frantically as the value grows. MIN, MAX and VALUE may be floating-point numbers.

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

Numbers are taken as delay times, the value's amount of milliseconds is waited.

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.

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.

GIVING COMMANDS TO LEDD

ledd takes commands in two ways. First, it has pipe files from which it reads the commands. These commands are normally given with the ledcontrol(1) program or written directly to the pipe. Secondly, on startup 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 syslogd).

There also exists a graphical front-end for ledcontrol(1), gled(1), which is useful for testing commands and experimenting.

EXAMPLES OF COMMANDS

Examples of some commands for ledd:

set s0n0 off: Set lowest-level Scroll Lock and Num Lock off.
set s5 blink 300 100: Set level-5 Scroll Lock blinking with 0.3 seconds on and 0.1 seconds off.
set n4 on: Set level-4 Num Lock on.
set n4 normal: Set level-4 Num Lock to normal. (Removes effect of previous example.)
set s5 dutycycle 1000 0.8 1.9 xxx: Set level-5 Scroll Lock to indicate value xxx. 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.
set s5 frequency 0.8 1000 1.9 100 xxx: Set level-5 Scroll Lock to indicate value xxx. 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.
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.
anim Stop any current animation.

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: - show ppp-link with a steady light and remote machine responding with the same LED blinking
- Any suggestions? Please mail me!! Wild ideas are always welcome!

LICENSE

Ledcontrol and all its pieces (including ledd) are distributed under the GNU General Public License (GPL).

FILES

/etc/ledd.conf: default configuration file for ledd
/usr/share/ledcontrol/startup.sh: default startup script
/etc/ledcontrol.conf: configuration file for startup.sh

AUTHOR

Ledcontrol was written by Sampo Niskanen <sampo.niskanen@iki.fi>. You can get the latest version of ledcontrol from http://www.iki.fi/sampo.niskanen/ledcontrol/

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.

You should have only "/dev/console" as a tty in ledd.conf 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.

The default startup script may cause a disk-access every few seconds. See startup.sh(8) for more info.

docs.sk

comprehensive documentation repository

See also