Utilities for defining and creating keyboard files for the iPAQ.

This directory contains scripts for generating keyboard files as well
as binary images of common keyboard libraries and tools generated by
the normal Linux "console-tools" package.


Keyboard scancode handling
==========================

Each microkeyboard generates some internal scancodes that are read by
the serial port (using h3600_microkbd).  Keyboards can run at
different baud rates and generate different numbers of scancodes per
keypress/release, so individual "process_character" functions are
required for each type of keyboard.  For convenience, the
h3600_microkbd drive creates a /dev entry for each type of keyboard
that it supports (currently /dev/microkbd, /dev/snapntype).

To simplify processing and guarantee a sane starting condition, the
h3600_microkbd driver maps the raw scancodes from the keyboard to an
common internal "SKEY" scancode, defined in <linux/h3600_keyboard.h>.
This common mapping guarantees that sane keystrokes will be generated
without having to modify the kernel's scancode-to-keycode mapping.  So
your keyboard should be able to generate the normal alphabetic
characters without doing any work.

For example, the "a" key on the SnapNType keyboard generates internal
scancode 0x61, which is mapped to SKEY_A (0x1e).


Handling Overloaded Keys
========================

Microkeyboards overload their keys with a special Function or Symbol
key to provide access to alternate characters.  For example, Symbol-A
on the SnapNType gives you an "@", whereas Function-A on the Compaq
Microkeyboard gives you an "*".  

We support overloading by using the kernel and X-windows built in
functionality to provide various modifiers.

The Linux kernel uses the "loadkeys" program load a keymap.map file.  We
map the Symbol/Function key to "AltGr" and provide suitable AltGr
definitions for each possible keycode.

The X-Windows system uses the "xmodmap" program to load a modmap.dk
file.  We map the Symbol/Function key to "Mode_switch" and define
appropriate mode_switch functions in the modmap.  Note that this
limits our possible key overloading to really just Keycode,
Keycode+Shift, Keycode+AltGr, and Keycode+Shift+AltGr.


Generating Mapping Files
========================

The raw scancodes generated by a keyboard are defined in a "*.raw"
file (e.g. "snapntype.raw").  The keys in this file are name using the
Linux console key names (see console-tools, file "ksyms.c").

The "makekernelmap.py" Python script is used to generate suitable .map
or .dk files from .raw file. It also can generate c-code suitable for
including in the kernel to perform the raw-scancode to common-scancode
mapping.



Making things work
==================

If you wish to rebuild any of the console-tools binaries (loadkeys,
dumpkeys, showkey), you will need to make appropriate modifications to
the ksyms.c file to include all of the custom XFXXXX definitions.

Make sure that you modify the Makefile to point to your Linux kernel
source directory.  The makekernelmap.py script needs to extract the
h3600_keyboard.h file from the Linux kernel source (that is where the
SKEY_LETTER definitions are located).


-------------------

 Andrew Christian
 6 March 2002 
