man lineakd (1): 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 [email protected]

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

AUTHOR

lineakd was written by Sheldon Lee-Wen <[email protected]> and Mark Smulders <[email protected]>.