LinEAK


Linux support for Easy Access and Internet Keyboards
Documentation: lineakd README


                
      Lineakd - The Linux Easy Access Keyboard Daemon

      This is a quick guide to lineakd. 
	  
      by Sheldon Lee-Wen 

   History
   -------
   
Lineakd was originally written by Mark Smulders. However, at around version 0.4 Mark 
became too busy to continue to maintain and develop lineakd. At about that time, I 
was already adding functionality to lineakd, enough so that I had a fairly decent 
grasp on the code base. As Mark dropped off, I picked up the slack, but at the 
expense of my own project, klineakconfig, a GUI configuration tool for lineakd.

Since version 0.4 the code base has been completely rewritten in order to be more flexible
(for better or for worse). Since version 0.8 the main funtionality of lineak has been
moved into a library for use by other programs (mostly GUI configurators) to be able
to reuse code that already exists. 0.8 also brought major changes by allowing a plugin
architecture for macros and display plugins.

   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 e-mail me.

    
   Usage
   -----

Below is the usage message of lineakd:

Usage: lineakd [options...]
Valid options are:
    -l,        --kbd-list           Show all supported keyboard types
    
    This option will list all of the keyboards that lineakd can find in lineakkb.def files. 
    It will print out these keyboards by unique identifier and then a description. Eg:
 
 [TYPE]         [Full name]

 ACEAKV12       Acer AirKey V (12 keys)
 APK7           Apple Pro Keyboard (7 keys)
 BTC5107        BTC 5107
 BTC5113RF      BTC 5113RF MultiMedia
 BTC5126T       BTC 5126T
 BTC9000        BTC 9000

    The unique identifier is necessary when asking lineakd to generate a config file, 
    and must be present in the config file in a 
       KeyboardType = IDENTIFIER
    directive.
    
    -L,        --plugin-list        List the loaded plugins and their 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
    
    These options allow you to specify the paths to the config and defintion files.
    
    -d DEVICE, --cdrom-dev=DEVICE   Specify the CDROM device
    -m DEVICE, --mixer-dev=DEVICE   Specify the mixer device
    
    These options allow you to specify the devices to use for the CDROM and mixer. 
    These are only used when the default plugin is also used.
    
    -c TYPE,   --config=TYPE        Create a new lineakd.conf file for keyboard TYPE
                                      (warning: old one will be overwritten!)
    
    This options tells lineakd to generate a config file in the users ~/.lineak/ directory. 
    The name of the file will be lineakd.conf and it will contain default configuration directives. 
    TYPE must be the unique identifier of a keyboard definition. These can be gotten by running 
    lineakd -l or lineakd --kdb-list
    
    -v,        --verbose            Print verbose messages
    -vv,       --very-verbose       Print very verbose messages				      
				      
    If you use this option, lineakd will print out a lot of debugging messages that are very informative.
    
    -h,        --help               Prints the usage message.
    
    -r,        --reload             Reload the configuration files.
    
    This tells lineakd to reload the configuration and keyboard definition files. It will 
    not however reload plugins. If you have added or removed a plugin, you must stop and 
    start the daemon.
    
    -z         --sleep              Disable handling of keyboard events
    -k         --awaken             Enable handling of keyboard events
    
    These options disable (-z) and enable (-k) the processing of events. When the daemon 
    is disabled events will stiil be seen, but no commands will be executed until lineakd 
    is run with the -k or --awaken option.
    
    -x,        --exit               Tell the daemon to exit.
    
    This option will cause lineakd to exit.
    
    -n,        --display-font          Set the font the on-screen display will use. It 
                                       must be in X format.
                                       i.e. -bitstream-charter-black-r-normal-*-*-240-*-*-p-*-iso8859-1
    -o,        --display-color         Set the color of the on-screen display. It must be 
                                       given as a color code. i.e. #0aff00
    -t,        --display-timeout       Set the amount of time that the on-screen display 
                                       keeps it's text on screen.
    -p,        --display-pos           Set the vertical position where osd will display.
                                       Valid values are: top, middle, bottom
    -a,        --display-align         Set the horizontal alignment for the on-screen display.
                                       Valid values are: left, center, right
    -y,        --display-hoffset       Set the horizontal offset from the alignment (see above).
    -w,        --display-voffset       Set the vertical offset from the position (see osd-pos above).
    -s,        --display-soffset       Set the offset for the shadow behind displayed text.

    These options allow one to specify on the command line, or override what is specified 
    in a config file, various display preferences for the on screen display. These are only 
    useful when using a display plugin such as the lineak_xosdplugin
    


   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 file:
	
[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             = 
MixerDevice             = 
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 file:
	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.


   Notes
   ------

How to kill lineakd
-------------------

In the event that lineakd hangs (which it probably will at some point), you have to kill all of 
the processes manually. You can do this by executing the following command:

	kill -9 `ps -ef | grep lineakd | grep -v grep | awk ' { print $2 }'`

Then, after a hang or crash (or segfault, etc) you should clean up the shared message queue.

Execute:

	ipcs -q

To see any queues that are hanging around. You'll see something like this (but be relatively sure 
it's not part of another process, if unsure, look at which queues are there before you run lineakd, 
or just forget about this step):

	------ Message Queues --------
	key        msqid      owner      perms      used-bytes   messages
	0x0000050c 884736     sheldonl   640        0            0

To get rid of the queue, type:

	ipcrm msg 

so, for the example type:

	ipcrm msg 884736

If you have a keyboard defined in lineakkb.def that has a toggle key like the one for the LTCDP keyboard, please update the file with the new key format and send it back to me.

Known bugs
-----------

Linux 2.6 can cause changes in how the keycodes are interpreted. 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 key(s) that is/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, etc. Then somewhere in your startup scripts (at the end of /etc/rc.sysinit for example). Try binding those scancodes to keycodes with the setkeycodes command. If in doubt just use the keycode from your /etc/lineakkb.def file. Then X should produce a keycode for the key. You'll still have to follow the steps under the procedure 1 above to get lineak to recognize the keys, but it'll work.
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 thre relevant part of procedure 2 above. If not, see 4.
4) 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. :(

USB keyboards may not work or just partially. If possible, use PS/2 for the time being. If this isn't 
possible, email the X.org development or Linux USB mailing list. Tell them the make and model keyboard you have, and what scancodes are not generating events. Use:
     showkey -s 
    while running as root to see what scancodes a key produces.

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.

Not everything may be platform independant. There may be some things specific to linux or an X11 version.


Cheers, Sheldon.