linux driver and utility for CH MFP Code
Status: Beta
Brought to you by:
adubost
# 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