Ledcontrol 0.5.2
----------------

NOTE: There are brand-new shiny man pages included. The stuff written
here should still be correct, but it's (hopefully) easier to read the
man pages. You can read them without installing with for example:
   man ./ledd.8
This manual will probably be removed in the future.



This is the manual for ledcontrol version 0.5.2. Ledcontrol is a
program to show different information on the normally-unused LEDs on
your keyboard. As it is configured by shell scripts, you can configure
it to show virtually any TRUE/FALSE condition accessible. Included are
a few useful scripts. Features include blinking LEDs, priority levels,
animations, arbitrary number indication, GTK+ program to test features
etc.

Ledcontrol works both on a text console and in X. All lock-keys
function normally, just their light are changed. All unused lights
function as usual (but see section Troubles below).

Ledcontrol consists of several programs, at the moment namely ledd,
gled and ledcontrol (a shell script).

Please note that ledcontrol is still under development and the whole
configuration may change in the future (as it changed from 0.1.0 to
0.2.0). The basic design, however, is final (ledd just sets the LEDs
the way other programs tell it to).


NOTE: You should read the section Troubles for a short list of the
major bugs/shortcomings of this release.



The compulsory stuff...
-----------------------

Ledcontrol is distributed under the terms of the GNU GPL license
version 2 or (at your choice) any later version. The program comes
with ABSOLUTELY NO WARRANTY. For details, see the file COPYING.


Installation
------------

Basically you should be able to install ledcontrol by just the
commands

./configure
make
make install

This installs everything to their default locations. The default
location of the configuration file for ledd is (I assume the default
prefix is /usr/local) /usr/local/etc/ledd.conf. The defaults are quite
good and you shouldn't need to edit this except for special
purposes. The configuration of the LEDs is done in
/usr/local/etc/ledcontrol.conf. It is sources by the default startup
script, startup.sh, which executes the checks for ledd. See the
default file for a lot of examples etc.

It also checks for a sysvinit-system and if found installs a
sysv-initscript. By default ledd is disabled on all runlevels, but
this can be changed afterwards of by the configuration option
--enable-sysv-levels. See section Sysvinit below for more info.

You probably have to run it as root, as only root usually has access
to the required device files. Do NOT, however, install it as suid root
as this might allow any user to specify their own configuration file
and execute any program with root access. Ledcontrol has not at least
yet been made safe enough for that.

Note that this program has to-date only been tested on an i386 Linux
system running a 2.2 kernel. I cannot guarantee it working on any
other system (hey - I don't guarantee anything!), but you may try
it. I am always open to any suggestion on this part (see the end of
this file).


Sysvinit
--------

The configure script attempts to detect a sysvinit-system and if
found, it installs a sysv-initscript for ledd. Most current
distributions support sysvinit, but some (for example Slackware)
don't use it by default. In these cases the configure script won't
probably recognize it and wouldn't install the initscript. You can
override this with the option --enable-sysv-init given to configure.

By default ledd is set to be off on all runlevels. This can be changed
later by renaming /etc/rcX.d/K05ledd to /etc/rcX.d/S95ledd (where X is
the runlevel) or with some configuration program designed for the job
or at compile-time as shown below.

./configure --enable-sysv-init=TYPE	Tell configure to install the
					sysv-initscript even if it
					doesn't find sysvinit. TYPE is
					one of "debian", "redhat",
					"generic" or "none", and it may
					also be omitted. ledd is still
					disabled on all runlevels.

./configure --enable-sysv-levels=345	Install the sysv-initscript
					and enable it for runlevels 3,
					4 and 5. The list can contain
					numbers from 1 to 5.

./configure --enable-sysv-dir=DIR	Some distributions use
					different directories for
					sysv. This option gives the
					base directory (which contains
					the directories rc?.d and
					init.d)

./configure --disable-sysv-init		Do not install the
					sysv-initscript.


Configuration
-------------

All default configuration files are well-commented, and basically you
should be able to configure them just by looking at them.


LEDD

As stated above, you probably don't need to edit the actual
configuration file of ledd, as the defaults are quite good. Please see
part STARTUP below for instructions of setting the LEDs to show
different things.

The configuration file has lines consisting of simply a command and an
argument (plus blank and comment lines, starting with '#'). Several of
the configuration options can also be overridden on the command line
(see part Command line).


tty DEVICE
	Specify ledd to set the LEDs on DEVICE. The configuration file
	may include several such lines, each determining one
	device. The default is to use /dev/console. This should
	probably not be changed, as this may cause problems with X.

	Example:	tty /dev/tty7

fixtty DEVICE
	Specify which TTYs will be set to normal operation on exit.
	Each TTY must be specified separately, though wildcards may be
	used. There is no need to fix the TTY on which X is on, it
	wouldn't help anyway.

	Example:	fixtty /dev/tty[1-6]

daemon {TRUE|FALSE}
	Determines whether ledd should fork into the background. The
	default is FALSE. This can be overriden on the command line.

	Example:	daemon TRUE

log TYPE
	Define where logging is to be done. Currently TYPE can be one
	of "syslog", "stderr" or "none" for logging via syslogd,
	printing to standard error and no logging, respectively.

pipefile FILE
	Define pipes that will be used as a communication pipes
	between the programs (not the startup scripts) and ledd.
	Several pipes may be defined, one per line. No pipefiles need
	to be defined for the scripts to work. More pipes can be
	defined on the command line.

	Example:	pipefile /tmp/ledd-pipe

startup SCRIPT
	Define scripts and/or other programs to execute on startup.
	Everything the programs write to STDOUT will be parsed as
	commands to ledd and everything written to STDERR will be
	logged at a warning logging level (eg. with syslog). More
	scripts can be defined on the command line.

	Example:	startup	/usr/local/share/ledcontrol/startup.sh

pidfile FILE
	Define which file to store the PID in. It is recommended to
	use a file as this prevents starting two ledd's at once (which
	leads to crazy LEDs). Only one pidfile may be defined. Note
	that some sysv-initscripts ignore this by overriding it on the
	command line.

	Example:	pidfile /var/run/ledd.pid


STARTUP

The default startup script, startup.sh, parses the file
ledcontrol.conf as a shell script. It defines how the LEDs are to act
in differing conditions. Configuration is done by setting environment
variables. Also user-made functions may be defined in this file.

STARTUP_ANIM		Set this to YES if you want a short (about one
			second) animation flashing the LEDs right to
			left at startup. This is done in background,
			so it does not affect the speed of system
			startup. It is automatically disabled if ledd
			is started from X, as this might leave the
			LEDs in incorrect states.

DEFAULT_SETTINGS	These are set at the beginning, the "default
			values". They should probably set level 1 of
			the used LEDs off.

MINIMUM_DELAY		Number of seconds that the script sleeps after
			checking all conditions. This is the minimum
			time it sleeps between checks.

USE_BACKGROUNDING	If this is set to YES, then slow checks (for
			example ping check when remote side is not
			responding) are executed in the background. This
			might cause a bit more CPU/memory consumption
			and/or disk access. This is automatically
			disabled if bash 2.xx.xx is used due to a bug
			in bash.

COMMAND_n	Command to execute with command line options
DELAY_n		How many seconds are at least waited before
		re-executing the command.
SUCCESS_n	Command to give ledd in case of success (return code 0)
FAILURE_n	Command to give ledd in case of failure (return code != 0)
		The commands are described in the section Commands below.

n is a number that goes from 1 up to as much as you need (the numbers
must go in order).

COMMAND_n can be any command available on the system. There are some
functions pre-defined for your convenience.


led_file <FILES>
		Returns true if ALL of <FILES> exist. <FILES> may
		include normal command-line wildcards.

led_ping <HOST>	Returns true if <HOST> responds to a ping packet. Uses
		backgrounding if available.

led_ppp		Returns true if output of ifconfig contains a
		definition for a ppp line (ppp0 to ppp9)

led_size <FILE> <MIN> [<MAX>]
		Returns true if size of <FILE> is greater or equal to
		<MIN> and (if <MAX> is given) less or equal to <MAX>.
		This can be used, for example, as a mail check (check
		file /var/spool/mail/username).
		Wildcards are NOT accepted.

The following built-in functions require SUCCESS_n to be either a
"set xx frequency" or "set xx dutycycle" command with the last
argument left out (they specify the value).

led_load	Sets the last argument to be the 1 minute load
		average. This doesn't use the FAILURE_n variable.

led_netload <iface> <type>
		Sets the last argument to be the network traffic on
		interface <iface>. <type> can be one of IN, OUT or
		BOTH, giving data receiver, transmitted and total
		traffic, respectively. Value is set as kB/s. If the
		interface is not found FAILURE_n is set.

Note that several of these require the proc filesystem to be mounted
under /proc (most systems have).

If you want to make own scripts, please read the file SCRIPTS.

Included is also a script 'ledcontrol', that can be used to set the
LED states from command line. You can get a short help of options with
"ledcontrol --help".


Commands
--------

The commands are of the form "command arguments". There are three
types of commands at the moment, "set", "anim" and "nop". The ones you
are interested in are "set" and "anim".


set <leds> <options>
	This command simply sets the status of the LEDs. <leds>
	describe the LEDs to set. It is a string forming of 'c', 's'
	and 'n' for caps-lock, scroll-lock and num-lock,
	respectively. Each of them can be followed by a priority level
	from 0 (lowest, default) to 9 (highest). It can specify
	several LEDs and several priority levels at the same time.

	<options> tells ledd what the do with the LEDs. "on" and "off"
	set the LEDs simply on and off. "normal" sets the LED to the
	real state of the lock or a state given by a lower
	priority. "blink" is followed by a list of numbers of which
	the first one tells how many milliseconds the LED is kept on,
	the second how many milliseconds off, the third on again and
	so on. It is looped after finishing. It should have an even
	amount of numbers, but it is not required, so that simple
	0.5sec/0.5sec blinking can be achieved with "blink 500".

	"dutycycle <time> <min> <max> <value>" sets the LED blinking
	in such a way that the total time on and off is <time> and the
	ratio is set by the other arguments. If <value> is less or
	equal to <min>, then the LED is totally off and similarly if
	<value> is greater or equal to <max> then the LED is totally
	off. Other values are linearly interpolated. If you use a
	too-short <time>, then the jump between totally-off and
	marginally-on will seem large, so I suggest about 1000 for 1
	seconds. If <min> is greater than <max> then the whole scale
	will be reversed giving you more time on with a smaller
	<value>. <time> is in milliseconds, <min>, <max>, and <value>
	can be floating point numbers. When using these with the
	built-in functions led_load and led_netload omit the last
	argument.

	"frequency <min> <freq1> <max> <freq2> <value>" gives you a
	type of blinking which is more "frantic" the larger <value>
	is. Below <min> the LED is off, between <min> and <max> the
	time is interpolated. <freq1> and <freq2> tell how long is one
	state of a LED is (so when <value> = <min>, it is the same as
	"blink <freq1>". Okay, they are not frequencies, but they
	correspond them).

	The LEDs are set according to the highest priority setting
	that is not "normal". Thus if c0 is "off", c3 "blink 0.5", c7
	"on" and all others "normal", then caps-lock is lighted (c7).

	A good configuration would set the 1 priorities to the default
	wanted state (0 may be used by other programs) and then
	changes higher priorities "on"/"off"/"blink"/etc. to signal
	something and "normal" for no signal.


	Examples:

	set scn off		Set all LEDs off unless higher
				priority overrides it (priority 0).
	set s5 blink 1000 1000 500 500 250 250
				Set scroll-lock priority 5 to a
				blinking that gets faster.
	set n0c0c1c2 normal	Set num-lock priority 0 and caps-lock
				priorities 0, 1 and 2 to a "normal"
				state.
	set s5 frequency 0.9 1000 1.8 100 1.2
				Interpolate the blinking frequency. Use
				this without the last argument as a
				SUCCESS_n option for led_load to get a
				nice load meter.


anim <anim_sequence>
	Do an animation sequence. It contains strings and numbers,
	where the strings define what LEDs to put on/off/normal and
	the numbers the time to wait at that point in milliseconds. It
	may also contain the string "loop" which makes the rest of the
	animation loop until another animation is given. In the
	strings 'n', 'c' and 's' set num-lock, caps-lock and
	scroll-lock OFF, 'N', 'C' and 'S' set then ON and 'xn', 'xc'
	and 'xs' set them to NORMAL. When the animation is finished,
	the LEDs return to normal functioning (to stop a blinking
	animation, use eg. "anim ncs").

	Note that animation sequences override ALL other LED settings.

	Examples:

	anim S 1000 C 1000 N 1000 s 1000 c 1000 n
				First set all LEDs on, one by one
				(note that they aren't turned off
				first) and then off (not normal) one
				by one.

	See file ANIMATIONS for more samples.


nop
	Does nothing. Ignores all following arguments.



Command line options
--------------------

Many of the options in the configuration file can be overridden on the
command line.

   -h        --help          Short help message.
   -v   -V   --version       Print version information.
   -c FILE   --config FILE   Read configuration from FILE instead of
                             the default configuration file.
   -p FILE   --pipe FILE     Define additional command pipes.
   -s FILE   --startup FILE  Define additional startup programs.
   -d        --daemon        Fork into background (overrides
                             configuration files).
   -D        --no-daemon     Do not fork into background (overrides
                             configuration files).
             --pidfile FILE  Use FILE as a pidfile (overrides
                             configuration files).


gled
----

gled is a program with which you can easily test different kinds of
blinkings, animations, etc. with ledd. It requires GTK+ 1.2.0 or
better to compile (http://www.gtk.org/). It's use should be quite
intuitive, so go ahead and try it. Note that you have to have
privileges to use ledcontrol to use gled (ie. you probably have to be
root). Many of the maybe-not-so-trivial options have associated
tooltips on their labels.


Troubles
--------

Here is a list of the most important bugs, shortcomings etc. that a
user should be aware of:


If a LED is set on or off in X (it works in a text console) and then
set to "normal", it still incorrectly shows the previous set state
instead of the state of the lock. This can be corrected by pressing
some lock key as this relights the LEDs. Because of this you probably
should set the "default" state of all used LEDs to something.

You should leave the "tty" line using ONLY /dev/console, otherwise
ledd probably won't work correctly in X.

You will probably get a disk-access every MINIMUM_DELAY (in
startup.sh) seconds. If the noise bothers you, see section Silencing
below.


More moanings about bugs and things to do are in the files TODO and
PROBLEMS.


Silencing
---------

You will probably get a disk-write every MINIMUM_DELAY (defined in
ledcontrol.conf) seconds. This is caused by the ext2-filesystem
updating the access-time of several programs. You can disable this by
mounting the devices with the option "noatime".

DON'T TRY THIS UNLESS YOU KNOW WHAT YOU'RE DOING!!! You can add the
command to /etc/fstab to have them mounted this way by default. This
has the downside that that filesystem will not have any access-times
stored (I disabled them as I have never had any use of access-times).
The programs and libraries mainly used normally reside in /bin,
/usr/bin and /lib (perhaps /usr/lib and something from /usr/local).

If you don't want to remove all access-times you can always make a
separate partition (or file mounted with the loop-device) with the
used programs and libs and set PATH and LD_LIBRARY_PATH in startup.sh.

You may also be able to disable the atime on only the neccessary files
on an ext2fs filesystem using "chattr". I haven't tried this, though.


Contact
-------

I will gladly accept any patches, suggestions, criticism, donations,
praise and all other kind of contact you can think of (excluding
flames). If you find this program useful, please let me know. Don't
hesitate to contact me.

I'd also like to hear what you are using ledcontrol for. I'm going to
add a SUGGESTIONS file soon to suggest uses of ledcontrol. Wild ideas
are very welcome! :)

My contact info is:

Name:	Sampo Niskanen
Email:	sampo.niskanen@iki.fi
WWW:	http://www.iki.fi/sampo.niskanen/

More contact info available on my homepage.

You can always get the latest version of ledcontrol from
http://www.iki.fi/sampo.niskanen/ledcontrol/