ledd - scriptable LED control daemon
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
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
ledd work both in X and on a text console.
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).
Fork into background at startup. This option overrides all
"daemon" commands in the configuration files (see ledd.conf(5)).
Do not fork into background. This option overrides all "daemon"
commands in the configuration files (see ledd.conf(5)).
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
3-7 levels for normal configuration
8-9 reserved for outside programs
Commands consist of a command keyword and arguments, separated by
whitespaces. Currently there are three types of commands: "set", "anim"
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
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
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
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
set n4 on
Set level-4 Num Lock on.
set n4 normal
Set level-4 Num Lock to normal. (Removes effect of previous
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
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!
Ledcontrol and all its pieces (including ledd) are distributed under
the GNU General Public License (GPL).
default configuration file for ledd
default startup script
configuration file for startup.sh
ledcontrol(1), startup.sh(8), ledd.conf(5), ledcontrol.conf(5),
Ledcontrol was written by Sampo Niskanen <firstname.lastname@example.org>. You
can get the latest version of ledcontrol from
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
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.