MXK
===

MXK is an input rewriting server for Linux. MXK provides
functions beyond the capabilities of conventional keyboard
mapping infrastructure.

MXK is released under the terms of the GNU GPLv3, see the
file COPYING.

Prerequisites
-------------

MXK runs on linux 2.6 or newer kernels. It does not require any kernel 
patches.

MXK does require a kernel built with evdev and uinput support
and the corresponding device files. On most distributions the 
evdev and uinput modules should be available. It is recommended
that you ensure that they are loaded with the command

# modprobe uinput ; modprobe evdev

In some cases it may be necessary to create the associated 
device files /dev/input/event? and /dev/{misc/,input/,}uinput
At the time of writing, uinput can be created like this

# mknod /dev/input/uinput c 10 223

while the event? files can be created like this

# i=0 ; while [ $i -lt 8 ] ; do mknod /dev/input$i 13 $[64+i] ; i=$[i+1] ; done

However, in most cases these files have already been created 
by the /dev/MAKEDEV script or various hotplug subsystems. 
The location of uinput has changed a couple of times.

Install
-------

$ make
# make install

Checking (optional) 
-------------------

To check if evdev support is available, run mxk as root
without any options and type

  list-sources

when you see the ready message. This command should list
available input devices. To check if uinput is in a usable
state, type

  start-target
  list-sources

The new list should contain an extra input source called MXK. 
Then type

  halt

to stop mxk

Scripts
-------

The install should copy a number of example script files to
/etc/mxk. These can be run with the -p option, like this

# mxk -p /etc/mxk/dvoqwe.mxk

The following scripts are available:

braille.mxk     - an initial attempt at an ascii/braille chording system
dvoqwe.mxk      - fast dvorak to qwerty switcher using the capslock key
faster.mxk      - adjust autorepeats at any time using keypad / and *
fmacro.mxk      - interactively record macros on function keys
gesture.mxk     - simple gestures: moving mouse pointer clockwise emits alt-tab
hjklarrow.mxk   - use hjkl as arrows 
joyweb.mxk      - browse the web using a joystick 
key2mouse.mxk   - use the keypad as a mouse
mousearrow.mxk  - use mouse movements to generate arrow keypresses
external.mxk    - invokes external programs
morsetoy.mxk    - emit dots and dashes using the keypad enter key
smstoy.mxk      - use the keypad to enter text as if using a cell phone

At startup the scripts print brief usage instructions. However, 
it is recommended that you read the scripts, as they
may not identify all input sources correctly or contain
device specific assumptions. In particular, ACPI button
devices may be confused as keyboards. Use the command
list-sources to view the input devices available on your
system, and file-source, caps-source or name-source to
select the proper one.

Notes
-----

The help command will list all available commands.

The manual page documents a subset of the commands.
The manual page can be rendered to postscript and pdf using the
command:

$ groff -mandoc -Tps mxk.8 > mxk.ps && ps2pdf mxk.ps mxk.pdf

Not all keyboards are created equal. Some are incapable of
reporting larger number of simultaneous keypresses. Sadly 
USB keyboards have worse limits than PS2 ones. This
means that bigger chord combinations (eg used by the
braille module) will not be interpreted correctly. In some
circumstances this will render a keyboard useless until
mxk exits. In some cases mxk may detect a flaky keyboard
and will indicate this in the output of the used-sources
command. The used-sources command will also report all keys
which are currently reported as pressed by the operating
system, this will show stuck keys. It is unclear if this
is a problem of the hardware, drivers or if there is a
bug in mxk.

Use the halt command to stop mxk. The quit command (and
in some cases control-C) merely disconnects from mxk and
may leave a running daemon.

Input sources are opened with the name-source, caps-source
or file-source command. The used-sources commands lists
the state and capabilities of opened sources.

The lock-source command will grab an input device
exclusively. The alternatives are activate-source which
enables non-exclusive use and bypass-source where mxk does
not use the source at all. Note that bypass-source is the
default state of a newly opened source.

The exclusive use of a source makes the input device
inaccessible to other parts of the operating system. This
may leave the system console unusable, so it is advisable
to have alternate means of shutting down mxk, such as
remote shell access.

Thanks
------

Nathan Tolbert     -  for describing the hjklarrow.mxk script,
                      chord debugging work and encouragement
Raimer Doeffinger  -  for finding and fixing a number of bugs 
                      in the absolute target, functionality which
                      was not even documented
