LinEAK


Linux support for Easy Access and Internet Keyboards
Documentation: Keyboard support HOWTO


 LinEAK - Linux support for Easy Access and Internet Keyboards
  Copyright (C) 2001,2002 Mark Smulders 
  Sheldon Lee-Wen 


  [ How to get your keyboard supported by LinEAK ]

If you are having problems with a USB keyboard, please see the note at the end
of this file.

So... you have an Internet or Multimedia keyboard, you came
 across LinEAK and thought "hell yeah, let's give it a shot"
 But, alas, your keyboard is not supported.

Okay, then here's what to do, step by step :-)

[UPDATE: please use the keynames as you would call them !!
         although lineakd 0.2 does not support "any keynames", I need
         them for adding them to the next version (0.3) which does.]


[ Step 1: gather information ]

 To fully support your keyboard I will need some general
 information about it, such as:
 - full name of the keyboard (eg. "Microsoft Internet Keyboard Pro")
 - a picture of it, which can usually be found at the manufacturer's
   website. Send me the URL and I'll be pleased too :)


[ Step 2: discover the keycodes ]

 To be able to use your special keys, I will need the keycodes
 generated by X. There are basically two ways to find them,
 but for now, stick with the first option...

 (option 1)
   - open an xterm
   - run 'xev'
   - then for each button: press it and watch a bunch of
     information appear in the terminal, something like:

     KeyPress event, serial 23, synthetic NO, window 0x5a00001,
         root 0x36, subw 0x0, time 2407465070, (146,-62), root:(719,272),
         state 0x0, keycode 234 (keysym 0x0, NoSymbol), same_screen YES,
         XLookupString gives 0 characters:  ""

     What you want is "keycode XXX". In the above example, the code
     would be 234.

   - Do this for every key, and make a list of the key/keycode pairs
     (eg. play 234, stop 223, internet 187, etc)


 (option 2)
   when xev does not react to the keys, there is one more
   possibility to get the codes.
   WARNING: this option may or may not work, and will be implemented
            in LinEAK in the future (but it is not, at this time)

   - configure lineakd for some other keyboard than you have
     take one with a lot of keys, such as the CIK18g.
     To do so, run:
                      lineakd -c CIK18g
     
   - then, run lineakd in verbose mode:  lineakd -v

   - punch your keys, and look at the output of lineakd, it might tell
     you what keycode was pressed.

   - if this works for some of the keys, but not all, try the above steps
     with some other keyboard types.
     
  - if this works for some of the keys, but not all, try the above steps
     with some other keyboard types.


 (option 3)
   if you don't see some keys at all, it might be that the kernel table
   does not know about this key. Here's how to find them

   - switch to the console (or take a look at dmesg)

   - press every key that did not show up so far

   - for every unkown key you should see something like:
   
   atkbd.c: Unknown key pressed (translated set 2, code 0x93 on isa0060/serio0).
   atkbd.c: Use 'setkeycodes e013 ' to make it known.
   atkbd.c: Unknown key released (translated set 2, code 0x93 on isa0060/serio0).
   atkbd.c: Use 'setkeycodes e013 ' to make it known.
   
   To find the keycodes that must be used, take a look at
   /usr/include/linux/input.h and find the number that corresponds to the
   label of the key. Next, do what the kernel told you and create a script
   that runs at system boot, or modify /etc/rc.sysinit if it exists. This 
   script will need to insert the keycodes into the kernel table by running
   a command or series of commands like this:
   
   setkeycodes e013 140  # This is the Calc key

   - Switch back to the console and check that there are no more unkown keys

   - go back to option 1 and look up the X11 keycodes etc.

 Alright, you got this far. Take a breath, a beer or other beverage maybe...
 so... feel any better now? Okay, we'll continue ...


[ Step 3: the keyboard definition ]

 With the information acquired above, we can now create the keyboard definition.
 Now,
 - take your favorite editor
 - copy one of the keyboard definitions from the existing lineakkb.def file
   (usually located in /usr/local/etc) to a new file.
 - think of a unique identifier for your keyboard, and put it in [TYPE]
 - change the "longname" to a description of your keyboard
 - change the "keys = { }" list so that it contains the names of the keys
   present on your keyboard. (note: only use names that exist in the
   existing file, if you make up new ones, the program will fail)
 - for each key, add the "key = keycode" pair.

 And you're done. Now,
 - Add the new definition at the bottom of the existing lineakkb.def
   (you will probably have to be root to do so)


[ Step 4: the final steps ]

 To check if your definition went alright, and no typo are present, run

    "lineakd -l"

 and check if your new keyboard type is listed.
 To create a new config file for your keyboard, run

    "lineakd -c TYPE"

 where TYPE is the identifier you thought of.
 To verify the definition is correct with your hardware, run

    "lineakd -v"

 now lineakd runs in verbose mode, so go ahead and punch your keys, they
 should register correctly in the output of lineakd.
 Press Ctrl-C to quit again.
 Now you are set to add your own commands to the keys, by using lineakconfig,
 or to manually edit

    $HOME/.lineak/lineakd.conf

 it should be quite self-explanatory.
 When you're done, you can start lineakd into the background and start using it.

    "lineakd &"

 NOTE: please share your newly supported keyboard with the rest of the world
       by e-mailing the new keyboard definition to the mailing list lineak-devel@lists.sourceforge.net
       Thanks!

[ Note for users of USB keyboards. ]

If you have a USB keyboard that you are trying to use with lineakd, and find that certain keys
do not generate any output from xev whatsoever, but you see messages from the kernel in the messages log
regarding unknown keys, you have a keyboard with keys that linux does not know how to handle.
This is likely a linux problem. 

In order for you to get your keyboard supported properly, you will have to contact the linux USB developers
via their mailing list. When you post, tell them the make and model of your keyboard.
As well, tell them the specific keys that do not work, and the corresponding scancodes that those keys
generate. You can find these scan codes by running showkey -s as root. You will likely see something like
this:
0xe0 0x5f 0xe0 0xdf
As the output. If you see two lines of output, like this:
0xe0 0x32
0xe0 0xb2
The first line is for the key press. The second line is from the key release. Make sure you include both, and specify which one is which, and again, for which key.

Alternatively, some users have reported success with using setkeycodes to bind these scancodes to keycodes at the
linux level. You can do that and put it in rc.sysinit, or rc.local. However, if you do that you will also
have to change the keyboard definition file as X will generate keycodes that are different from what may be
definined in the lineakkb.def file for your keyboard.