NAME
lineakd - GUI configurable support for multimedia keyboards
SYNOPSIS
lineakd [options...]
DESCRIPTION
LinEAK, Linux support for Easy Access and Internet Keyboards, features
X11 support, windowmanager independence, ability to configure all keys
through GUI or .conf file, volume control and sound controls.
lineakd is the daemon that runs in the background of an X session and
listens to incoming events from multimedia buttons.
OPTIONS
The programs follow the usual GNU command line syntax, with long
options starting with two dashes (‘-’). A summary of options are
included below.
-l, --kbd-list
Show all supported keyboard types.
-L, --plugin-list
Show all plugins and macros.
-D, --directives-list
Show all of the default, implicit configuration directives.
-f FILE, --conffile=FILE
Specify the .conf file.
-e FILE, --deffile=FILE
Specify the .def file.
-d DEVICE, --cdrom-dev=DEVICE
Specify the CDROM device.
-m DEVICE, --mixer-dev=DEVICE
Specify the mixer device.
-c TYPE, --config=TYPE
Create a new lineakd.conf file for keyboard TYPE (warning: old
one will be overwritten!).
-x, --exit
Tell the daemon to exit.
-r, --reload
Reload the configuration files.
-z, --sleep
Stop the daemon from processing keyboard events.
-k, --awaken
Resume processing of keyboard events.
-v, --verbose
Print verbose messages.
-vv, --very-verbose
Print very verbose messages. Mostly for debugging purposes.
-h, --help
Show summary of options.
NOTE
if -f, -e, -d, or -m parameters are used in conjunction with -c, please
make sure you specify those BEFORE -c !
QUICK SETUP
For those who want to setup their configuration quickly, here are the
steps:
run ’lineakd -l’ to see a list of available keyboards.
run ’lineakd -c TYPE’ to create a standard configuration file for the
keyboard with an identifier of TYPE that you found by running lineakd
-l
The configuration file will be $HOME/.lineak/lineakd.conf
Edit the config file to specify commands for the keys. The commands
will initially be empty. This file can be modified to suit your needs.
Do NOT, however, add extra keys or keynames! You can only change the
values of the keys that are already present! If you have a key on your
keyboard that is not in the file, please post it on the mailing list
lineak-devel@lists.sourceforge.net
CONFIGURATION
Lineak uses two types of configuration files: lineakkb.def files and
lineakd.conf files.
lineakkb.def
lineakkb.def files contain keyboard descriptions that map key
and button names, to keycodes and button codes respectively. A
lineakkb.def file can be placed either in a system directory, or
in a users home directory (in the .lineak/ subdirectory). The
lineakd daemon will first read the system lineakkb.def file,
usually at /etc/lineakkb.def and then read the
~/.lineak/lineakkb.def file. It will attempt to reconcile the
entries, using the local entries to override the system entries.
Here is an example of a keyboard definition from a lineakkb.def
[LTCDP]
brandname = "Logitech"
modelname = "Cordless Desktop Pro"
[KEYS]
Sleep = 223
Internet = 178
Mail = 236
[END KEYS]
[BUTTONS]
Thumb = 2
[END BUTTONS]
[END LTCDP]
The structure is important. Adding a new keyboard is as easy as
determining the special keys that you keyboard has, using
something like xev, and writing your own definition file. Note
that the daemon will only register keys that you also have
defined in your lineakd.conf file.
lineakd.conf
lineakd.conf files can live either in a system directory, or in the
users home directory under the .lineak subdirectory. lineakd will
attempt to load a users config file before looking for a system wide
configuration file.
Directives
Lineakd supports various configuration file directives. Plugins also
can specify their own directives. The standard directives that are
supported follow with their defaults:
KeyboardType =
CdromDevice = /dev/cdrom
MixerDevice = /dev/mixer
Display_plugin = internal
Display_font = -adobe-helvetica-bold-r-normal-*-*-240-*-*-p-*-*-*
Display_color = 0aff00
Display_timeout = 3
Display_pos = bottom
Display_align = center
Display_hoffset = 0
Display_voffset = 50
Display_soffset = 1
keystate_capslock =
keystate_numlock =
keystate_scrolllock =
KeyboardType is the only mandatory defintion. If KeyboardType is not
defined, the daemon will not function properly.
The CdromDevice and MixerDevice settings specify the device files to
use. These are only useful when used in conjunction with a plugin that
requires them. One such plugin is the defaultplugin.
The Display_* directives control the functioning of the on screen
display.
Display_plugin specifies with of the installed display plugins to
use. Currently the only OSD plugin is the xosd plugin.
Display_font specifies which font name to use for the on screen
display. Currently the xosd plugin requires font names in X format.
Display_color specifies the color of the font. As xosd currently
requires the color in a numeric format, that is the default. You can
use something like kcolorchooser or the gimp to get color values for
you.
Display_timeout specifies the amount of time the display should
remain on screen. After this number of seconds the display will be
removed.
Display_pos specifies the vertical position for the OSD. Possible
values are bottom, middle and top.
Display_align specifies the horizontal position for the OSD.
Possible values are left, center and right.
The keystate_* directives control modifiers. By default, lineakd does
not pay attention to the modifiers NumLock, CapsLock and ScrollLock.
Set these directives to "enable" to use modifiers. (Note: as of beta3,
these options do nothing. We automatically use modifiers if they are
defined on a per command basis.)
TOGGLEABLE KEYS
lineakd supports toggle keys. A toggleable key is one that can have a
various number of states for each push of the key. For example, on many
keyboards the Play and Pause keys are the same. When you push the key
once it plays, the next time it pauses. The same thing goes for the
Mute key. You must define a toggle key as key1|key2 in the definition
(lineakkb.def) file. We can define a single action for this key in the
config file by specifying the keyname in the form key1|key2 - this
effectively treats the toggleable key as a normal key. It tells lineakd
that we don’t want to use this a a toggleable key, maybe because the
command we are going to bind to it supports the notion of toggling. We
can also specify seperate actions for the Play and Pause states by
assigning actions to key1 and key2. eg.
On the LTCDP there is the key ’Play|Pause’ In my
config file I can specify either:
Play|Pause = /usr/bin/xmms -t
To treat this as a normal key, or, if I want seperate functions
for the play and pause states:
Play = /usr/bin/xmms -p
Pause = /usr/bin/xmms -u
Note that there can be more than two states for a toggleable key. For
example key1|key2|key3 could be defined.
MODIFIERS
lineakd now supports a variable number of modifiers to a key. However,
this only applies to non-toggleable keys so a key such as Play|Pause
will not work with modifiers if you use it as a toggleable key by
putting entries like this:
Play = something
Pause = something else
In your config file. However, if you use the key as a non-toggleable
key, i.e. like this:
Play|Pause = something
Then it becomes possible to use modifiers.
Currently we support the following modifiers:
control
alt
shift
mod2
mod3
mod4
mod5 To use a modifier, we do something like this in the config
Sleep+control = something
Sleep+alt = something different
Sleep+shift = something more different
Sleep = sleepiness
etc.
Modifiers to buttons, if they are defined in the lineakkb.def file,
work the same way.
ON-SCREEN DISPLAY
lineakd supports custom on screen display messages through the
configuration file. However, some plugins may choose to disregard
custom on screen display messages if they feel it does not apply.
Currently you specify the on screen display message for a command by
placing it within square brackets at the beginning of the line. E.g.
[On Screen Message] Go = some command
[Another Message] Home+alt = some command
[Boring Message] Home = some command
PLUGINS
The lineakd daemon does not contain any internal macros or actual on
screen display functionality. This functionality is implemented in
plugins that are loaded when the lineakd daemon is first run. NOTE:
Restarts of the daemon with lineakd -r will not reload plugins, or load
new plugins.
The previous functionality that existed in versions of lineakd up uptin
0.8 has been moved into two plugins: lineak_defaultplugin, which
contains all of the EAK_* macros and lineak_xosdplugin which contains
all of the XOSD on screen display functionality. There is now also a
lineak_kdeplugin plugin that brings with it a total of 23 macros or
more for handling KDE funtionality via dcop. Some of these macros
themselves take arguments which expands their functionality. See the
respective plugin packages for more information on MACRO usage.
HELPER APPLICATIONS
The lineakd package now installs two helper applications,
send_to_keyboard and evtest.
evtest: Allows you to see the event layer events your keyboard is
generating. This is for debugging to help you determine if indeed your
keyboard is sending events, and which events it is sending. It uses the
new event layer.
send_to_keyboard (only for arm, x86 and x86_64): This is a simple
program which, for now is just for the IBM keyboards. It allows you to
send actual control codes to the keyboard device to enable or disable
certain functions. For example, some of the IBM keyboards require:
send_to_keyboard ea 17
in order to enable the extra keys. This helper application is actually
used from lineakd. Within your lineakkb.def file you can specify a
configuration option after the keyboard and model name to initialize
the keyboard with. As requirements for this sort of thing increases
I’ll enable the handling of different options. So far we only look for
INITIALIZE.
e.g.
[IBMRA7993]
brandname = "IBM"
modelname = "Rapid Access Keyboard"
RAWCOMMAND[INITIALIZE] = "ea 71" # <--- lineakd will at this point
fork and execute: ‘send_to_keyboard ea 17‘
[KEYS]
WWW = 178
WorldBook = 151
Option = 176
Help = 166
Standby = 165
AudioMute = 146
AudioStop = 164
AudioPlay|Pause = 153
Back = 163
Forward = 161
AudioLowerVolume = 158
AudioRaiseVolume = 160
Custom1 = 174
[END KEYS]
[END IBMRA7993]
KNOWN BUGS
Linux 2.6 can cause changes in how the keycodes are interpreted from
the 2.4 version of the kernel. In some cases, keys that use to work, no
longer work at all. If this happens to you try the following:
1) Run xev and see if X reports any keycodes for the keys that are not
working. If there are keycodes being produced, you’ll have to update
the lineakkb.def file (usually in /etc) with the correct keycodes for
your keyboard.
2) If xev does not report any keycodes for one or more of your keys,
then try looking in /var/log/messages. If you have error messages in
that file from atkbd.c about unknown scancodes then try binding those
scancodes to keycodes with the setkeycodes command as root. If you are
in doubt over which keycode to bind it to just use the keycode from
your /etc/lineakkb.def file. If X then produces keycodes for that key
then put those setkeycodes commands somewhere in your startup scripts
(at the end of /etc/rc.sysinit for example) so that they run at boot
time. You’ll notice that X produces a different keycode for the key
that what you set it as. Follow the steps under the procedure 1 above
to get lineak to recognize the new keycodes.
3) If you see nothing in your /var/log/messages, and xev produces no
keycodes, you can try running showkey -s as root and see if the
keypresses show any scancodes. If they do, follow the setkeycodes part
of procedure 2 above. If not, see 4.
4) If still nothing happens, try the evtest command included in the
package. You’ll have to run it as root, but it can tell you if it sees
any events at all. If not, it is likely that your keys may require a
low level command to be sent to the keyboard (like in the example of
the IBM Rapid Access Keyboard above.) You can check this website:
http://www.win.tue.nl/~aeb/linux/kbd/scancodes.html to see if there
is any further information.
5) If none of the above work, send an email to the linux-usb mailing
list (if your keyboard is USB) or to the atkbd.c maintainer and pray
they do something about it. Otherwise your screwed. Take your POS
keyboard back to the store and get a supported one. :(
The EAK_SLEEP action has no functionality yet.
Due to the fact that not all IDE CD-ROM drives provide status info on
the tray position, the following can occur:
If lineakd is started with the cdrom tray in open position, the
eject button has to be pressed twice the first time to close it.
If you opened the cdrom tray with the eject button and let the tray
close automatically after a while (hardware timer), the eject button
has to be pressed twice to open it again.
FILES
/etc/lineakkb.def
Keyboard definitions file.
$HOME/.lineak/lineakd.conf
Personal configuration file.
$HOME/.lineak/lineakkb.conf
Personal keyboard configuration file.
SEE ALSO
lineakconfig(1), lineak_defaultplugin(1), lineak_xosdplugin(1),
lineak_kdeplugins(1).
AUTHOR
lineakd was written by Sheldon Lee-Wen <leewsb@hotmail.com> and Mark
Smulders <Mark@PIRnet.nl>.
July 27, 2003