Read Me

#   Linux driver and utility for CH Products MFP
#   Copyright (C) 2011 Alain H. Dubost
#
#   This program is free software: you can redistribute it and/or modify
#   it under the terms of the GNU General Public License as published by
#   the Free Software Foundation, either version 3 of the License, or
#   (at your option) any later version.
#
#   This program is distributed in the hope that it will be useful,
#   but WITHOUT ANY WARRANTY; without even the implied warranty of
#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#   GNU General Public License for more details.
#
#   You should have received a copy of the GNU General Public License
#   along with this program.  If not, see <http://www.gnu.org/licenses/>.
#
#   Please visit http://sourceforge.net/projects/chmfp/ for queries and support



GENERAL DESCRIPTION
===================

1) What is this about
---------------------

The CH Products Multi-Function Panel (MFP) is a highly customizable keyboard.
It allows for positionning up to 50 keys anywhere on a transparent surface.
Moreover, green / red led button allow to toggle for 100 keys in total.
It is in fact a revamp of the Ergodex DX1. Principle is based upon radio-signal
keys that you stick on the surface. Device decodes signals and transmits key
events through USB to the host. Unfortunately, it does not register as a
HID-compliant device but relies on a proprietary protocol. And, of course,
only Windows drivers are available.

I give credit to Richard A Burton for his linux Ergodex DX1 "driver" designed
in 2007. Unfortunately, principle of the CH MFP is different protocol-wise
from that of the DX1 :
- DX1 has internal memory to store key mappings, whereas this is done at
  software level in CH MFP
- DX1 registers two USB endpoints (one for control and one HID-compliant),
  whereas CH MFP only one

Therefore, I could not resort to using the Ergodex DX1 linux software and
had to build my own.

This software allows to use the CH MFP as a keyboard / mouse / joystick,
with reprogrammable keys, taking into account the green / red toggle
(therefore a maximum of 100 keys). Chorded input is possible, up to 6
simultaneous keys from a hardware perspective according to CH Products
(not verified). Support for mouse movements is implemented, along with macro
execution, and joystick axes, and the possibility of one modifier key to
bring up the equivalent number to 200 totally programmable keys.

This is a userspace application, based on libusb and uinput, with full
graphical user interface (based on GTK).

I have no relationship with CH Products company whatsoever, apart from
being a satisfied customer. This software refers to CH Products brand
for identification purposes only. Usage of their name does not imply any
endorsement whatsoever. My development work was carried out as personal
commodity only and the only analysis performed has been on the USB protocol
communication with my host computer. I have chosen to release this software
to the opensource community lest it would be useful to anyone, under the
GPL v3 license, WITHOUT ANY WARRANTY; without even the implied warranty
of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.



TECHNICAL INSIGHT
=================

2) Supported device
-------------------

The supported device is the CH Products MFP, latest firmware (so-called
"green logo"). I have no reason to believe that the original firmware
version (so-called "white logo") would not work, but I have not tested it.
To make it very clear, this software will NOT function with the Ergodex
DX1 ; instead, you should use the ergo software created by Richard A Burton
in 2007 (http://ergodex.hydraproductions.com/wiki/downloads).

USB characteristics (only one device is registered) :

Bus xxx Device yyy: ID 068e:00f0 CH Products, Inc. 
Device Descriptor:
  bLength                18
  bDescriptorType         1
  bcdUSB               1.10
  bDeviceClass            0 (Defined at Interface level)
  bDeviceSubClass         0 
  bDeviceProtocol         0 
  bMaxPacketSize0        64
  idVendor           0x068e CH Products, Inc.
  idProduct          0x00f0 
  bcdDevice            1.00
  iManufacturer           1 
  iProduct                2 
  iSerial                 0 
  bNumConfigurations      1
  Configuration Descriptor:
    bLength                 9
    bDescriptorType         2
    wTotalLength           34
    bNumInterfaces          1
    bConfigurationValue     1
    iConfiguration          3 
    bmAttributes         0x80
      (Bus Powered)
    MaxPower              500mA
    Interface Descriptor:
      bLength                 9
      bDescriptorType         4
      bInterfaceNumber        0
      bAlternateSetting       0
      bNumEndpoints           1
      bInterfaceClass       255 Vendor Specific Class
      bInterfaceSubClass      0 
      bInterfaceProtocol      0 
      iInterface              4 
      ** UNRECOGNIZED:  09 21 00 01 00 01 22 15 00
      Endpoint Descriptor:
        bLength                 7
        bDescriptorType         5
        bEndpointAddress     0x81  EP 1 IN
        bmAttributes            3
          Transfer Type            Interrupt
          Synch Type               None
          Usage Type               Data
        wMaxPacketSize     0x0008  1x 8 bytes
        bInterval               1



3) Principles
-------------

The principle used is equivalent to that of the CH Control Manager software
on Windows. Basically, the driver sits in between the hardware and the
input event interface :
- Driver receives hardware events and interprets them
- Driver converts to a valid input event according to programmable
  key mapping
- Driver passes input events to the input interface
- Driver registers in Windows as a virtual HID-compliant keyboard and mouse

I have chosen to build this linux driver on the same model, basically
capturing hardware events using libusb, doing the translation according to
a key mappings file and passing the input event to the kernel using uinput.



4) Protocol information
-----------------------

Listening to USB port provides with all information on USB data transfers.
Basically, protocol is very straightforward, with only a device-to-host
endpoint (no transmission to the device from the host). All transfers
are 8 bytes long. Obviously, we have no possible action on leds.

Each key pressed / released triggers one bit (1 / 0) in the 8 bytes
message, they are cumulative (logical OR). Red / green led status is
provided by bit 3 of byte 8. Red / green button press events are also
recorded on bits 2 / 1 of byte 8.

Following is the table of bytes versus key number :

Key    Byte sequence (hex)             Key    Byte sequence (hex)

1      01 00 00 00 00 00 00 00         25     00 00 00 01 00 00 00 00
2      02 00 00 00 00 00 00 00         26     00 00 00 02 00 00 00 00
3      04 00 00 00 00 00 00 00         27     00 00 00 04 00 00 00 00
4      08 00 00 00 00 00 00 00         28     00 00 00 08 00 00 00 00
5      10 00 00 00 00 00 00 00         29     00 00 00 10 00 00 00 00
6      20 00 00 00 00 00 00 00         30     00 00 00 20 00 00 00 00
7      40 00 00 00 00 00 00 00         31     00 00 00 40 00 00 00 00
8      80 00 00 00 00 00 00 00         32     00 00 00 80 00 00 00 00
9      00 01 00 00 00 00 00 00         33     00 00 00 00 01 00 00 00
10     00 02 00 00 00 00 00 00         34     00 00 00 00 02 00 00 00
11     00 04 00 00 00 00 00 00         35     00 00 00 00 04 00 00 00
12     00 08 00 00 00 00 00 00         36     00 00 00 00 08 00 00 00
13     00 10 00 00 00 00 00 00         37     00 00 00 00 10 00 00 00
14     00 20 00 00 00 00 00 00         38     00 00 00 00 20 00 00 00
15     00 40 00 00 00 00 00 00         39     00 00 00 00 40 00 00 00
16     00 80 00 00 00 00 00 00         40     00 00 00 00 80 00 00 00
17     00 00 01 00 00 00 00 00         41     00 00 00 00 00 01 00 00
18     00 00 02 00 00 00 00 00         42     00 00 00 00 00 02 00 00
19     00 00 04 00 00 00 00 00         43     00 00 00 00 00 04 00 00
20     00 00 08 00 00 00 00 00         44     00 00 00 00 00 08 00 00
21     00 00 10 00 00 00 00 00         45     00 00 00 00 00 10 00 00
22     00 00 20 00 00 00 00 00         46     00 00 00 00 00 20 00 00
23     00 00 40 00 00 00 00 00         47     00 00 00 00 00 40 00 00
24     00 00 80 00 00 00 00 00         48     00 00 00 00 00 80 00 00

49     00 00 00 00 00 00 01 00         Green  00 00 00 00 00 00 00 01
50     00 00 00 00 00 00 02 00         Red    00 00 00 00 00 00 00 02

No button pressed and green led status        00 00 00 00 00 00 00 00
No button pressed and red led status          00 00 00 00 00 00 00 04



5) Around the program : uinput
------------------------------

kernel 2.6 with evdev, uinput support and libusb >= 1.0 are necessary to
compile and execute. If using GTK (optional), version >= 2.12 is required.

if uinput is built as a kernel module, it must be loaded before launching
the application (modprobe uinput). Make sure you autoload the module if
your distro does not by default, this is distro-specific (in gentoo :
/etc/modules.autoload.d/kernel-2.6 or /etc/conf.d/modules in baselayout-2).

/dev/input/uinput device requires read/write access for user running the
application, you can perform chmod 666 /dev/input/uinput if permissions are
not appropriate. A better automatic solution is to use udev rules, a sample
is provided with this package. Copy sample file to /etc/udev/rules.d/ (or
another path depending on your distro) and reload udev rules (or reboot).
Sample provided assumes you have created a uinput group and have assigned
your user(s) to it, you can change to another group if you so wish.

Note that for some distros (such as Ubuntu Maverick), uinput is built in
the kernel (hence no module loading) and default device is /dev/uinput

On execution, chmfp creates a pid file to avoid multiple instances running.
This pid file is created in /var/tmp/ as a default directory, you can
change this in <chmfp.h>. This directory requires read/write access for
user executing the application.



FEATURES
========

6) General application features
-------------------------------

Using the above information, driver captures the USB data, determines
which events have happened since last USB interrupt transfer (key press /
release, possibly simultaneous), translates those into input events
according to key mapping defined by the user in keymap file (loaded
at startup), and passes them on to the kernel using uinput.

Current possibilities and limitations :

* Technical
    - Key mappings are read only once at startup and cannot be changed
      dynamically
    - Simultaneous events are passed to the kernel with no limitation
      other than hardware
    - Leds cannot be operated from the application (hardware limitation)
    - Application expects to find CH MFP connected on startup, if not
      user is given a number of timeout retries to connect
    - Application will loop indefinitely, unless error detected
      (including MFP disconnect) or until process is killed: use -t
      option to terminate (all such exits should be graceful)
    - Application will detect if a previous instance is running and
      will safely abort
    - Several connected MFP's are supported, up to 16 simultaneously by default

* Functional
    - Key press and release events are both detected and passed
    - Sticky keys are possible at user's choice (press once to hold, once
      more to release)
    - Red / green toggle status is taken into account for a maximum of
      100 buttons
    - Modifier key functionality allows to program 2 different actions for
      each button (for each green / red led state), bringing up a maximum
      of 200 programmable actions
    - Application does not rely on X and can be run from terminal (no need
      for xmodmaps, but can be used also if you want)
    - Since 0.6, full GUI is available, CLI (command line interface) remains
      possible either at user's choice or as the fallback solution



7) Keyboard events
------------------

When programmed with key actions, each CH key pressed will mimic the key for
which it is programmed, meaning that press / release events are both detected.
Any key can be programmed, including left-shift, right-shift, left-ctrl,
right-windows,... A special key can be programmed ("modifier key"), which
works as a kind of "shift" key that does not report a "shift" to the kernel
but provide a different mapping to the other key pressed simultaneously.
This allows for up to 4 actions per button (2 for green led status, 2 for red
led status).

Care must be taken about the keyboard layout. I use an AZERTY layout... and
I have already found that in some games, I have to swap Q and W, etc. The
keymap file creation utility takes this into account, but trial-and-error
might be necessary... By the way, the Windows CH Control Manager software
does the same confusion in test mode.

Final note : key events are the same as if coming from another keyboard, so
if they have no event associated with them from the keyboard, same behaviour
will occur from the MFP (e.g. keyboard multimedia keys). You will have to
deal with them in your application, or with xmodmaps in X for instance.

Current possibilities and limitations :

* Technical
    - Unspecified keys in mappings file have no action
    - By default, keys 51 to 100 are identical to keys 1 to 50, unless
      specified in mappings file, and all keys have same action when
      "modifier" key is pressed, unless specified in mappings file
    - You can forcibly define a key action to do nothing by specifying
      NULL as the key code (useful to disable a key in red or "shift" status)
    - Led button events can also be programmed
    - If you only own 25 keys, no problem, just don't program keys 26 - 50

* Functional
    - All key events can be simulated, including multimedia keys, joystick,
      gamepad and mouse buttons, and joystick hats (see axes)
    - Any keyboard keys can be mapped, including shift, ctrl, scroll-lock,
      multimedia, etc.
    - CH keys mimic exactly the assigned key, so press / release are
      interpreted as if coming from the keyboard, mouse, joystick device
    - Only one modifier key can be implemented (but several CH keys can
      trigger it)
    - Sticky keys are possible at user's choice (press once to hold,
      once more to release)



8) Mouse events
---------------

Each CH key can also be programmed with mouse axis movement and programmable
speed. When key is pressed, mouse will move in the set direction and the set
speed, until key is released. Since this is handled in the application as a
separate thread, you can press and action other keys at the same time
(including another mouse axis).



9) Joystick events
------------------

Each CH key can be programmed as a joystick axis. Up to 8 axes can be
programmed, and one key will increment the joystick value at a rate programmed
by the user, as long as key is pressed. You probably want to have one key
for + and one key for - for each axis (can be different speeds though). Other
actions can be performed simultaneously, similar to mouse movements, including
mouse or other axis movements.

You can also program for each axis a key to center (0 value) the axis.

As opposed to mouse and key events, you might not see immediate action from
a joystick axis. This is normal, as mouse X & Y axes are not associated to
joystick X & Y axes in X server by default (ignores absolute axes if
relative axes are present). However, a new joystick device will be created
(such as /dev/input/jsX) and can be used from any application using joystick
axes.

Joystick hats are also possible... you just need to know that according to the
linux kernel which respects hardware specs, joystick hats are viewed as axes.
There are flaming wars about whether this is correct or not, the rationale is
the following: they look like buttons, but on the same axis you cannot press
up and down at the same time, so you might think of them as being discrete
axes. Windows just seems to translate them in most drivers and have them appear
as buttons again... Anyhow, chmfp respects the axes implementation, and one
hat button has two axes (horizontal and vertical). If you (or your application)
don't like that, you can use jhat on the top, which was built for this purpose.



10) Macro events
----------------

Each CH key can also be programmed to action a macro. A macro is defined in
a file, as a set of actions to perform once triggered. As for the mouse and
joystick axes, as this is handled in a separate thread, you can press and
action other keys during the macro execution, including keyboard, mouse and
joystick axes movement actions.

Macros are limited to key events (they cannot trigger mouse movements, axes,
hats or other macros). Timings and distinction between press / release can
be made, as well as calling for mouse / joystick buttons. Different CH keys
can call the same macro.

Once started, a macro will continue until its completion, but it can be
interrupted if you have programmed a key to act as "stop macro". You
cannot trigger another macro until the previous one has completed or has
been interrupted.

Bear in mind that each key pressed reproduces exactly what the user would
do - so, to get a shifted character to input text, you should program shift
(hold) also before your key (and shift release after) - think about caps
lock state ! Interrupting a macro in progress might also interrupt when a
key is pressed and before it is released - resulting in a key staying
continuously pressed (press the same key to cancel). Therefore, using the
stopmacro key should be done sparingly, and is only really useful for long
duration macros anyway.



11) List of actions
-------------------

As for the CH Control Manager, you can program a key to trigger a list of
actions, that is, pressing once will trigger "H", once again will trigger
"E", etc. This is viewed also as a macro, simply stating that delay is to
wait for next key press (of the same key). This is done by rotation, so
getting at the end of the list will start over from the beginning. This
also allows to implement a toggle key, by defining two such actions.

This can be combined with a macro sequence, so you could also program a
toggle macro, etc. Different "list" keys can also be mixed, program will
keep track. Finally, the "stopmacro" key described above will also perform
a "reset" of all lists, as this can be useful.



12) Multiple MFP's
------------------

Several MFP's can be handled by the application (up to 16 by default).
Nothing special is to be done, application will detect all connected MFP's,
but this will be done at startup only, additional MFP's connected after
will need a restart of chmfp.

In the case of multiple connected MFP's, the key mapping configuration
files will be numbered, appended by the device id. For instance, if two
devices are connected, application will expect to find (default) chmfp_keymap-0
and chmfp_keymap-1. If you were to connect only one of the MFP's, then it would
expect to find chmfp_keymap. If you expect such scenarios, you might find it
useful to link / copy configutation files, or prefer to use -g (see below).

MFP's will always be assigned id number based on the same order of USB bus /
address. It is not possible to identify by serial number or other unique id,
as MFP does not report any. This means that if you swap USB ports when
connecting MFP's, you might end up with swapped id's also. So, please keep
same USB ports to avoid such surprise !

Finally, two modes are possible. Default mode is to create one uinput
device per MFP. This means that all key, mouse, joystick events will come
from a different device for each MFP. Pro = more flexible and no limitations
in terms of number of axes, Con = the application needs to be able to handle
several keyboard, mouse, joystick devices. You can change this behaviour
with the -u option, in that case all MFP events will come to the same uinput
device. Pro = only one device for keyboard, mouse, joystick to handle,
Con = there are limitations e.g. only 8 axes cumulated between all MFP's, etc.



USAGE
=====

13) Using the application - GUI mode
------------------------------------

Default application mode is now to run using graphical user interface. This
allows for a totally new user experience.

You will run directly in graphical mode by typing :

     chmfp        to run the application with graphical user interface

If any argument is provided, command line interface will be used. One
exception is the option -x, which is provided to start the application
in graphical mode but prevents automatic startup of MFP as a background task;
this option is mainly useful if you have chosen to autostart with no tray
icon, and wish to grab control back and/or change options (if tray icon is
active, you can invoke chmfp via the tray icon).

     chmfp -x     do not autostart background process (overrides user option)


Key features are listed below, you are invited to browse on the project
homepage listed at the top of this file for more details (obviously pictures
tell more about a GUI than text !).

- The main window is the keymap editor and allows to fully edit mappings,
  offering all capabilities (keyboard, mouse, joystick... and special codes)
- Full macro editor is also available, offering all editing capabilities
- CCM map file conversion can be performed directly
- MFP can be started or stopped from the main window
- A test mode is available, to check that all MFP keys are operational
- All settings and options mentioned in this README can be changed by the user
  and are remembered by the application
- Application can run in the background with optional tray icon and optional
  automatic startup

A new file chmfp.ini is used to store all settings, and is created upon first
run. This file is ignored when using CLI terminal mode; conversely, if any
command-line options are called when invoking chmfp, application will
automatically use CLI terminal mode.



14) Using the application - CLI mode
------------------------------------

Since 0.6, default mode has changed, and application defaults to using GUI
when started with no arguments :

     chmfp        to run the application with graphical user interface

If any problem occurs with GTK initialization (GTK not installed, or X11 not
started,...), chmfp automatically falls back to CLI terminal mode. If any
arguments are provided (except -x), chmfp will automatically start without
GUI, read on.

You can also specifically request to start in CLI terminal mode with :

     chmfp -n     to run the application in CLI terminal mode anyway

If you are just wanting to run in the background with prepared configuration
files, prefer using terminal mode to avoid any useless graphical overhead.
You would then use :

     chmfp -s &   to run as a silent non-graphical forked process, as a user

This launches the application and you should not need worry about it any more.
The application checks that no previous instance is running, otherwise exits.

    chmfp -a      changes this behaviour to cancel any previously running
                  instance of chmfp and force execution of the new instance

You could also run in a terminal window, application will continue until
window is closed. If you disconnect the CH MFP, the application should
terminate gracefully. Same if it receives a SIGINT (CTRL-C at terminal),
SIGTERM (kill or shutdown) or SIGHUP (terminal shut) signal. Another way
of graceful termination is by using :

     chmfp -t     to terminate the existing instance of chmfp process

Default verbose setting is moderate speech, you should get limited output
except on errors or if using an interactive command. You can change this with :

     chmfp -v     (or -vv for even more) to get more output messages
     chmfp -s     silent mode, no output except errors

Default file locations can be changed for the called session, as follows :

     chmfp -d <device name> (default uinput device is /dev/input/uinput)
     chmfp -f <filename> (default key mapping file is ~/.chmfp/chmfp_keymap)
     chmfp -m <filename) (default macro files are ~/.chmfp/chmfp_macro-X, where
                          X is 1, 2,...)
     chmfp -g <filename> uses a global file for both key mappings and macros
     chmfp -G same, with a default global mapping file ~/.chmfp/chmfp_globalmap

Interactive commands (used in conjunction with options) bring up helper
functions, to help the user in generating key mappings or macro files.
Some limitations exist for key codes and advanced file creation would require
editing directly the files  (which are well documented) or use GUI :

     chmfp -k     to create a key mappings file in a terminal window
     chmfp -p     to create a macro file in a terminal window

A conversion utility is also available, in order to convert an existing
key mapping file created with CH Control Manager (under Windows) to a
chmfp-compatible file. Some limitations exist, which are described below.

     chmfp -c <filename> to create a key mappings file from CCM .map file

If using multiple MFP's, default is to create one uinput device per MFP. You
can change this behaviour and create a unique uinput device cumulating all
MFP events :

     chmfp -u     to create a unique uinput device with multiple MFP's
                 (ignored otherwise)

Finally, you can get this information by typing :

     chmfp -h     usage information

Note : language is set at compile time and is based on the LANG environment
variable value - so it should cater for your language. Currently only French
and English are supported. If you want to change this behaviour, you should
compile using make LANG=en_US.UTF-8 if you want English from a French-locale
system, or conversely make LANG=fr_FR.UTF8 if you want French from a
non-French system. This impacts only messages and keyboard layout display to
the user, not the core program.



15) Configuration files : key mappings
--------------------------------------

The configuration file for key mappings is a tab-separated value format.
You can edit this file directly, in any text editor. Alternatively, the
chmfp program allows you to generate your own configuration.

The first statement must be the following :
[MFP-0]
where 0 is the number of the MFP (0 if you only ever use one).
Any line before will be ignored, as well as any line following the next [

File contains TAB separated values in the form:
CH=<key>	type=<type>	value=<value>	comment=<comment>

<key> can be a number from 1 - 102, positive or negative, in any order
    1 to 50 are normal CH keys (green led) - no action if unfilled
    51 to 100 are CH keys with red led mode
    (keys 51 to 100 default to green led value if unfilled)
    101 is for green led button press
    102 is for red led button press
    negative value means a different action if modifier key pressed

<type> has a value from 1 to 7, or 11 to 18, 21 to 28 or 31 to 38
    1 is for button press (keyboard, mouse, joystick,...)
    2 is the same but sticky key (press once to hold, once more to release)
    3 is for horizontal X-axis mouse movement (+ means right)
    4 is for vertical Y-axis mouse movement (+ means down)
    5 is for macros
    6 is for stopping any running macro
    7 means this key is a modifier key (type of local-shift)
    11 to 18 are the joystick axes (resp. X, Y, Z, RX, RY, RZ, THR, RUD)
    21 to 28 are for setting to zero (centered) each joystick axis
    31 to 38 are for joystick hats: odd for X-axis and even for Y-axis
        4 hats are possible, so hat 1 X-axis = 31, hat 4 Y-axis = 38

<value> is a value depending on the type specified
    if type is 1 or 2, then it is the uinput event code (see below)
    (use 0 for key to do nothing, useful to avoid red / shifted defaults)
    if type is 3 or 4, then it is the value of pixels to move mouse
    (positive / negative values apply, default speed is nb pixels per 5
      millisecond)
    if type is 5, then it is the number of the macro to execute
    if type is 6 or 7, this value is ignored
    if type is 11 to 18, then it is the joystick axes value to move
    (positive / negative values apply, default speed is 10 per
      millisecond)
    if type is 21 to 28, this value is ignored
    if type is 31 to 38, positive value means right/down, negative left/up

<comment> is an optional free text, only used in GUI


See <input.h> for all uinput event codes, most common key codes are
listed in files provided as sample configuration. These are NOT the
USB scan codes. Beware also these are QWERTY-based, AZERTY keyboards
will have to adapt (most common switches includes A <> Q, Z <> W and
M <> ,   ). Events include keyboard, mouse or joystick buttons, among
others (multimedia keys can also be mapped).
 
Numbers must be specified in decimal. Blanks lines and lines starting
with '#' are ignored



16) Configuration files : macros
--------------------------------

The structure is similar to key mappings files, but it is a set of
files : name is appended with number of macro (e.g. ch_macro-1, ch_macro-2,
ch_macro-3,...).

The first statement must be the following :
[MACRO-1]
where 1 is the number of the macro.
Any line before will be ignored, as well as any line following the next [

File contains TAB separated values in the form:
key=<key>	action=<action>	delay=<delay>

<key> is the uinput event code (see ch_keymaps for details)

<action> has a value from 0 to 2
    0 is for button release
    1 is for button press
    2 is for normal button press / release action

<delay> is the time to wait until next macro action is processed
default unit is in 1/100 seconds, 0 means no wait time, 1 is normal value
negative value means wait defined time and stop, resume with next (same)
key press

Numbers must be specified in decimal. Blanks lines and lines starting with
'#' are ignored



17) Configuration files : global
--------------------------------

The previous files can all be combined into one global file, containing both
key mappings (for all MFP devices) and macros. In this case, each section is
prepended with [MFP-0], [MFP-1],... and [MACRO-1], [MACRO-2],...

You can use any file created with -f or -m, and combine them into one global
file. If you only use one MFP device and no macros, this behaviour will be
identical to the previous anyway.

There are pro's and con's to using this option : Pro = you have all your
mappings and macros in one file, easier to manage. Con = you cannot readily
reuse your macros in another mapping, you have to copy/paste the same macro
into the second global file also.



18) Conversion of CCM .map files
--------------------------------

The application provides a utility for converting key mappings files
created using CH Control Manager (CCM) to key mappings files usable by
chmfp.

First of all, this is the opportunity to compare functionalities between
chmfp and CCM, and to list the limitations in file conversion :


* Difference in the core handling of CH keys :

  => CCM will handle the CH keys either in "direct" mode, and in that case
     will pass events as DirectX or mouse key presses ; either in
     "programmed" mode, and in that case allows to program an event for
     CH key press, and another for CH key release - each event can be
     either a key press, or a set of key presses ("macro") or a list.

  => chmfp will handle each CH key as if it were an actual key of any
     device, i.e. keyboard, mouse or joystick. In the two latter cases,
     we have the same behaviour as CCM. In the case of the keyboard, press
     the key and the programmed key will be pressed, release it and it
     will be released. In other words, chmfp will not produce events from
     different keys for press and release of a CH key. However, macros and
     lists can be assigned (the latter being considered a special case
     of the former). You may consider that all keys are in "direct" mode.

* chmfp will not handle advanced scripting (CMS)

* chmfp will not handle other hardware, currently only CH MFP is supported.

* All other functionalities can be handled by chmfp, including the
  so-called "shift" key, macros and lists, and in addition will simulate
  mouse / joystick axes / hats. Differences between key press / release
  events could in most cases be circumvented by using sticky keys, toggle
  keys (a list of 2 events) or macros.

* All macros can be handled by chmfp, including all keywords defined in
  CCM, such as KEYS + -, HOLD, CHARDLY, CTL, SHF, ALT, NULL,... the only
  exception being DIRMODE, which does not make sense for chmfp. You can
  also include macros in lists,...

* CMC command files are also handled by chmfp. Be cautious about how the
  path is specified in the mappings file, you might need to specify an
  absolute path or conversely make your conversion in the appropriate
  directory.

* Limitation of the conversion utility : CMS scripting, ClickStart enable,
  DIRMODE, specific programmed key/macro on release, and mode control are not
  supported.


The end result of the conversion is a keymap file (as usual, defined with
the -f or -g switch, or the default value), and possibly a set of macros, in
the case the original CCM .map file had defined lists or macros. Consequently,
to use the newly-created mapping file, you would need to also use the
macro files (if you are not using -g or -G, you must then use -m switch,
non-default name set is created by appending -macro to the keymap file). You
can edit further these files if you need to complete.

Since 0.6, conversion results are stored in a file chmfp.log, which is stored
in /var/tmp/ directory, and displayed to the user. This allows for further
reference if required.



APPLICATION DEVELOPMENT
=======================

19) Further enhancements
------------------------

This is a relatively simple program, yet provides powerful and flexible
functionalities. There are a lot of possible enhancements though, but since
I am not sure the linux userbase for CH MFP is significant, I would be
interested to receive suggestions and contributions. As for my own needs, I
do not feel a compelling missing feature that would require further efforts
(and I might not have too much time, either).

Quite possibly, adapting this software for other hardware (including
keyboards) is reasonably easy.

Please bear in mind I am not a professional C programmer, so many
optimizations are probably desirable. Including English, since this is not
my native language.


Proposed potential further enhancements :

User interaction
- Translate into other languages (easy with chmfp-lang.h, if you speak it...)

Keys
- Add more modifier keys as we only have one (but does one really need more
  than 200 keys ? CCM only defines one, anyway)
- Implement dynamic key re-mapping (sounds complicated from a usability
  perspective) or mode control setting

Macros
- Add a possibility to generate mouse / axes movements and other macros
  from a macro (but would this really be useful and usable ?)
- Add a possibility to trigger another macro before the running macro
  finishes (same comment)

Hardware support
- Allow application to auto-detect connection of MFP (difficult from
  user-space, would need polling)
- Implement support for other similar input devices (such as G13, etc.)



20) Release Notes
-----------------

v0.6 - 13 May 2011
- developed GTK-based full graphical user interface
- other minor changes but GUI was more than enough to keep me busy !

v0.5 - 4 Apr. 2011
- added CMC file conversion utility
- added support for joystick hats
- added NULL character possibility
- modified configuration files structures and management
- full code revision

v0.4 - 18 Mar. 2011
- added support for multiple MFP's
- built multi-language support and French translation
- added "list" functionality as part of macros

v0.3 - 07 Mar. 2011
- added sticky key functionality
- added joystick axes functionality
- more bug hunting

v0.2 - 02 Mar. 2011
- added functionality for mouse axis movements
- added functionality for macros
- added functionality for modifier key
- added user input helper functions for file creations
- numerous bug fixes

v0.1 - 25 Feb. 2011
- initial version