How to use your keyboard's LEDs for something out of the ordinary

[Midnight]

How? With Ledcontrol, of course! Here's how!


Index

   0.0 DISCLAIMER
      0.1 The formal one
      0.2 In plain English
   1.0 Introduction
      1.1 The software
      1.2 What it does
      1.3 Configuration
   2.0 Installing
      2.1 Setup
      2.2 Example Config
      2.3 Using the software




0.0 DISCLAIMER


0.1 Disclaimer

I DO NOT TAKE RESPONSIBILITY FOR ANY DAMAGE OR PROBLEMS TO COMPUTER EQUIPMENT OR SOFTWARE INSTALLED ON THE READER'S COMPUTER THAT IS CAUSED AS A RESULT OF READING AND/OR ANY ACTION TAKEN BY THE READER BECAUSE OF WHAT IS DESCRIBED WITHIN THIS DOCUMENT. NOR DO I TAKE ANY RESPONSIBILITY FOR ANY PERSONAL DAMAGE, BE IT PHYSICAL OR MENTAL, THAT IS CAUSED AS A RESULT OF READING AND/OR DOING ANYTHING DESCRIBED WITHIN THIS DOCUMENT. NOR DO I GUARANTEE THAT ANYTHING DESCRIBED WITHIN THIS DOCUMENT WILL ACTUALLY WORK IF TRIED ON ANY OTHER PERSON'S COMPUTER. BY READING THIS DOCUMENT, YOU AGREE TO THIS, AND THUS AGREE THAT IT IS YOUR OWN FAULT IF ANYTHING OF A BAD NATURE HAPPENS. THE ACTIONS ARE SOLELY DONE AND WISHED FOR BY THE READER, AND I, THE AUTHOR, SHALL THUS NOT BE HELD RESPONSIBLE FOR ANYTHING, INCLUDING, BUT NOT LIMITED TO, LOSS OF DIGITAL DATA, DESTRUCTION OF ANY PART OF THE READER'S COMPUTER EQUIPMENT, OR BURNT COFFEE.

IN ADDITION, THE AUTHOR OF THE SOFTWARE THAT IS DESCRIBED WITHIN THIS DOCUMENT, TAKES NO RESPONSIBILITY, AND HAS RELEASED THE SOFTWARE UNDER THE GNU GENERAL PUBLIC LICENSE. IT IS RECOMMENDED THAT YOU, THE READER, ALSO DO READ THIS DOCUMENT OF LICENSE, IN ORDER TO FULLY UNDERSTAND WHAT RIGHTS YOU HAVE, AND WHAT RESPONSIBILITIES THE AUTHOR OF THE SOFTWARE HAS NOT WISHED TO KEEP.


0.2 Plain English

I do not take any responsibility whatsoever for any actions taken or problems resulting from reading this document. No, you cannot email me with a sue claim. No, I will not refund your broken computer. No, I cannot rescue the data that was lost due to trying to follow this document. No, I cannot do anything with your burned coffe, or with your car that crashed right after you read this document. I am free of any responsibility whatsoever. By reading this document, you agree to this, and that it is your own fault that things go boom if you try out the methods described within this document.

For more information on the Software's license, please read the GNU General Public License.



1.0 INTRODUCTION

Installing, testing and using Ledcontrol on a Slackware-based system.
Written by Midnight of the Wolvix community. Software by Samp Niskanen, see section 1.1.


1.1 The Software

The Ledcontrol package includes several applications and scripts. This includes `ledd', the LED daemon, which does the hardware interaction, `ledcontrol', a script which interacts and sends commmands to `ledd', and `gled', which is a GTK+ application for testing the features of `ledd'. All the software was created by Sampo Niskanen <sampo.niskanen@iki.fi>, and is available under the GNU GPL. The software resides at [http://www.iki.fi/sampo.niskanen/ledcontrol/].


1.2 Usage

While this software might mostly be used for fun, it is also usable for some more serious things. I, for example, have used it for making my Scroll Lock LED blink if I lose Internet connection. Another simple usage is load indication. But due to some features, it is possible to include this software in many scripts and usages, by for example making it look for a file. If the file exists, then you can make the LEDs show a certain state, while if it is nonexistant, you are free to make the LEDs look otherwise. In addition, it is possible to add own scripts for `ledd' to use, which would then add even more functions.


1.3 Configuration

The Ledcontrol software uses two configuration files, `/<etc-dir>/ledd.conf', and `/<etc-dir>/ledcontrol.conf'. The location of these files may be changed upon compilation, or upon execution of the programs (via the `-c' switch).

In `/<etc-dir>/ledd.conf', no changes are usually required. The standard values should work well enough, but feel free to take a look at the configuration. It includes, among other things, the location of the pipe/FIFO to be used by `ledd' and `ledcontrol' (more on that later).

`/<etc-dir>/ledcontrol.conf' contains the configuration related to the LED lighting and the scriptings of how to light the LEDs. Here you will find some standard configurations, and it is recommended that you take a look here, and view the possibilities that are made available with this software. You can achieve quite some things by simply hacking this file a little, and screwing around with the standard commands.

If the package is compiled with a Wolvix buildscript, the <etc-dir> will be `/etc'. Thus, the location of the files will be `/etc/ledd.conf' and `/etc/ledcontrol.conf'. Upon usage of other variables at compilation time, other locations may and will result.



2.0 INSTALLATION


2.1 Setup

I have created a Slackware package of Ledcontrol 0.5.2, which is the latest version available as of this document's date of creation (2009.03.12). Please note that the software is most likely dead, and thus 0.5.2 will most surely be the latest version no matter at what date this document is read. This package was created on and for Wolvix 2.0.0-build23, a pre-beta release of Wolvix 2.0.0. Because of the build computer's configuration, I find it best for people to build their own package, with or without buildscript.

For people not having access to, or not wanting to utilize, a buildscript, the knowledge that the build process is fairly simple, should be spread. The Ledcontrol package complies to the Slackware standards, and after unpackaging the compressed archive in which the software source is located, the folder `ledcontrol-x.x.x' should be revealed. The `-x.x.x' represents the version number; in this case, 0.5.2. The compilation process itself consists of running `./configure', `make', and then, as root, `make install'. Note that these are the commands for making a standard install to your own machine; you may want to append additionaly switches and options to `./configure' in order to make the software installation fit your system setup.

After installation of the package, or compilation and installation of the source, the software is ready to be tested, tweaked and used.

If you upon testing find that the message "No suitable pipefile found" shows up, this is because you have not created the FIFO pipefile that `ledd' and `ledcontrol' are configured to use. By default, this pipefile is named `/var/run/ledd-pipe'. This location may, as earlier noted, be changed within the configuration files.

In this case, you will need to (as root) run the command `mkfifo /var/run/ledd-pipe', in order to create the FIFO pipefile. Normally the permissions that are set at creation are suitable for usage.


2.2 Example Config

I have made a simple and dirty hack of the standard configuration file `/<etc-dir>/ledcontrol.conf', in the purpose of making my Scroll Lock indicate loss of Internet connection. This file reads as follows.

Code:

# This file is sourced by the default startup script of ledcontrol.
# It is used to control the LEDs.

# If you wish to add your own functions, you can add them here or add
# a file named <name>.sh in the script directory (usually
# /usr/share/ledcontrol or /usr/local/share/ledcontrol). Don't forget
# to mail me your scripts! :)

# Here are a few examples of the commands that can be given to ledd:
#
# set s0c0 off Set lowest-level Scroll Lock and Caps Lock off
# set s5 blink 300 100 Set level-5 (overriding level-0) Scroll Lock
# blinking 0.3 secs on and 0.1 secs off.
# set n4 on Num Lock level-4 on.
# set n4 normal Num Lock to normal state.
# set s5 dutycycle 1000 0.8 1.9 Arbitrary number indication starts blinking
# at 0.8, is totally on at 1.9 (last option
# omitted - will be added by command)
# set s5 frequency 0.8 1000 1.9 100 Another number indication - starts
# blinking at 0.8 and increases frequency
# until 1.9 (last option omitted as above)
# nop Do nothing.
#
# More info can be found in the file MANUAL.

###
# Give a short (~1sec) animation when starting up. Automatically
# disabled if started within X as that might leave LEDs in wrong
# setting.

STARTUP_ANIM=YES

###
# Place slow tasks (eg. led_ping when host is not responding) onto the
# background. This is automatically disabled if using bash 2.xx.xx, as
# it has a bug causing startup.sh to crash. It's safe to leave this on.

USE_BACKGROUNDING=YES

###
# Minimum delay between checks. Low values give rapid response, but
# also increase the load more. You'll probably get a disk-access every
# MINIMUM_DELAY seconds, see file MANUAL for details.

MINIMUM_DELAY=5

###
# Default settings, set at startup. You probably want to blank the
# near-lowest priority level of all LEDs you'll use (level 0 shouldn't
# be used - some other software might want it).

# The default setup only uses Scroll Lock:
DEFAULT_SETTINGS="set s1 off"

###
# The tests themselves. Each is defined by four variables:
#   COMMAND_n Command to execute. Can be internal function (see below)
# or external command.
#   SUCCESS_n Command to give ledd on successful return value (0).
#   FAILURE_n Command to give ledd on failed return value (non-0).
#   DELAY_n     Test is run so often. May be a bit more due to
# MINIMUM_DELAY.
# n is a number, starting from 1 up.

# The default is to show the load average on Scroll Lock. If you run
# Seti@Home, rc5des or similar, you want to increase the numbers
# below, as your "unloaded" system load is 1.
### COMMENTED OUT; NOT USED - COMMAND_1 FURTHER DOWN
##COMMAND_1="led_load" # Command to give
##SUCCESS_1="set s5 frequency 0.8 1000 1.9 100"
# Starts blinking at 0.8, very frantic at 1.9
##FAILURE_1="nop" # Not used, but must be present
##DELAY_1=10 # Test every 10 seconds


# Another example: Put Caps Lock on if a ppp-link is present. If ping
# can reach somehost.example, then make it blink slowly. (Assumes
# that if ppp-link not found, host cannot be reached.)
#
#COMMAND_2="led_ppp"
#SUCCESS_2="set c4 on"
#FAILURE_2="set c4c6 off" # Assumes link down -> host not reached
#DELAY_2=5
#
### Edited command for indicating loss of Internet connection
### Simple command created by Midnight of the Wolvix community
COMMAND_1="led_ping www.google.com"
SUCCESS_1="set s6 off"
FAILURE_1="set s6 blink 300"
DELAY_1=10


# The current internal commands are the following (the ones starting
# with NUMBER must have an arbirary number indication in SUCCESS_n):
#
#   led_file <FILE(S)> TRUE if every one of <FILE(S)> exists (may
# contain wildcards)
#   led_load NUMBER - Current system load (1 min avg)
#   led_netload <IF> <TYPE> NUMBER - Current network load on
# interface <IF>. <TYPE> can be IN, OUT or BOTH
# indicating what kind of traffic is monitored.
# Number is given as kB/s. The longer DELAY_n
# is, the more accurate the average is. Returns
# FALSE if no such interface exists.
#   led_ping <HOST> TRUE if <HOST> replies to ping.
#   led_ppp TRUE if a ppp-link is active.
#   led_size <FILE> <MIN> [<MAX>] Returns TRUE if <FILE> exists
# and its size is greater or equal to <MIN> and
# optionally less than <MAX>.

# That's all folks! Send me a note about what you're doing with
# ledcontrol to sampo.niskanen@iki.fi!

As you can maybe see, there have been done few modifications. But they work. Note that the server I use as a reference, is Google.com. This may be changed upon preference; I only chose one that is well known for being online always, and for being reliable.


2.3 Using the Software

One important notice should be made firstly; this software must be run as root. This is because of some needed permissions for interacting with lower leveled parts of the system. Namely `/dev/console' and `/dev/tty[1-6]', among others. Thus you must either run it manually with `sudo /usr/sbin/ledd' (notice that `ledd' is present in `/usr/sbin'), or automate the process somehow.

In the Xfce DE, it is possible to automate application executions upon login by using the 'Autostarted Applications' option from the 'Settings' menu. Most surely, something similar is present on Gnome and KDE. The negative side of doing this, is that it will only affect the user whom adds it to their autostart configuration, and it will not start until the login has taken place.

To avoid this, and make `ledd' run system wide, and make it start even before anyone logs in, you will have to hack some rc.d (bootup) scripts. In Slackware/Wolvix/Slax, these are present in `/etc/rc.d/'. Upon examining my rc. scripts, I found that I was best fit putting the code snip in the file `/etc/rc.d/rc.local', which is a file containing, you guessed it, extra bootup executions and settings specific to the local machine. The code that I added, was:

Code:

# Start ledd / ledcontrol with its script for a blinking ScrLck LED if
# Internet connection is lost.
if [ -x /usr/sbin/ledd ]; then
    /usr/sbin/ledd
    echo -e "Starting ledd..."
fi

This should be all that is needed for making the Ledcontrol package get up and running for you. It is however recommended that you screw around with the configurations and possibilities yourself. You probably have other needs than making Scroll Lock blink whenever ping does not reach Google.com. Maybe it should instead ping your own website's server, so that you're warned when your website is down? The sky's the limit.