Welcome to the chordhack readme, This document was called "README" but has changed to "INSTALL" with the 2.4 kernel version. It originates at http://www.cs.vassar.edu/~priestdo/chordhack/chord/INSTALL and that is were the most recent version will live. DISCLAIMER I have been using this or an earlier version of this hack since Oct. 1999. However, I did not create. I have an agreement with its author/writer that it will be posted publicly. WHAT IS IT? This is a group of files which when built into the linux kernel allow you to toggle between normal keyboard operation and a 7 key chording emulation. Mouse operation is not effected. I currently use this with linux kernel 2.4.22 By using this hack you can turn any 7 keys on your keyboard into a chording keyboard. With this it becomes inexpensive to build a chording keyboard. All that is required is a cheap conventional keyboard which is cannibalized for the small circuit board that is inside it, 7 keys and something to mount them on. The circuit board is tested to find 7 key presses that share a common line on the keyboard matrix. The scan codes for these 7 keys are entered into the scancodes.h file correlating them to the 7 keys in the chording sequence. This allows you to make a chording keyboard by soldering 8 wires. That is all. This is a good beginner soldering project as if somehow you do manage to fry the chip, you are only out $5 or $6 bucks for a new cheap keyboard to rip apart. WHAT YOU NEED OTHER THAN THE FOUR FILES IN THE CHORD DIRECTORY You will need to rebuild your kernel to use this hack. It is beyond the scope of this document to guide you through the process of rebuilding your kernel. It is not a difficult thing to do, so do not panic. The README file in the top of the kernel source tree always served me well, the Linux Kernel HOWTO is another good source or ask your favorite uber-geek. How ever you do it, just make sure you you have the source for your kernel and what ever you need to compile it installed before you proceed. KNOWN PROBLEM Some svgalib programs do not like the hack. Most notably svncviewer and svga-quake. In both of these programs some(svncviewer) or most(svga-quake) keys work but others do not. In both cases toggling out of chording provides you with a working keyboard zgv has no problems, saber(svga) has no problems. I have not looked into fixing this problem. ODDS AND ENDS There is a 6 key version (where you only have 2 thumb buttons and you press them togethe to make the middle thumb press in the 7 key version) write me if you want it. There is a usb version but I do not use it. Write me if you want it. NUFF PREAMBLE, LETS GET TO IT There are four files here (other than this INSTALL and the README) chord.h.2002.10.13 pc_keyb.c.chording.2.4.20 scancodes.h.7key chord.map.txt Chord.h.2002.10.13 and scancodes.h.7key are needed by pc_keyb.c.chording.2.4.20. Pc_keyb.c.chording.2.4.20 is a replacement for pc_keyb.c in the linux source drivers/char directory. You should rename your existing pc_keyb.c pc_keyb.c.orig or pc_keyb.c.pre.chordhack, something so you will remember what it is if you need it. Place all three files in the drivers/char directory under your kernel source directory. Then create links as follows: ln -s pc_keyb.c.chording.2.4.20 pc_keyb.c ln -s scancodes.h.7key scancodes.h ln -s chord.h.2002.10.13 chord.h The file chord.map.txt is a description of the chording sequences implimented by the hack by default. These files will make it possible to emulate a 7 key chording system similar (but not identical) to what is implemented on the BAT. Recoding for any other 7 key chorder should be possible. This system uses one key for each of the four fingers and three for the thumb. The middle thumb key (gray) is the "home" position, the inner thumb key (red) is for numbers and symbols, the outer thumb key (blue) is for shift and movement (including return, delete, up, down, page up, page down etc.) This hack allows you to map any seven keys on your keyboard to the seven keys used in this system which we call pinky, ring, middle, index, thumb_red, thumb_grey and thumb_blue. Of course you could expand or modify the mappings. If you examine chord.h you will notice that we were working on a plan to make the keyboard with only 6 keys, using the two thumb keys pressed together as equiv. to the grey thumb key. As it stands, this hack will allow you to use your conventional keyboard as a chording keyboard of this type. However, the real fun begins when you take apart a cheap keyboard and use the small circuit board inside, to make a seven key keyboard. Then build a kernel that uses those seven keys as pinky, ring, middle, index, red, grey and blue. In this way, for $12 to $25, you can make your own chording keyboard. I have done this several times now and have been using this hack or an earlier version of it as my primary input system since October of 1999. In the past I mounted an RJ45 connector on the circuit board and connected the thing with the 7 keys on it to that. I no longer recommend doing it that way as the rj45 connectors add $5 to the cost and since I can get keyboards for $6.50 it hardly seems worth it. I suggest that you just build the circuit board right into the 7 key thing or mount it a short distance from it. There are some drawbacks to using this on an unmodified conventional keybaord. Most notable of these is that the position of your hand and the amount of force required to press the keys. I have no problem using my home made keyboards for my primary input device, however a few minutes of chording on a conventional keyboard and I find my wrist starts to fatigue. I also find that I get a farily high number of mistyped chords when there are 4 or 5 keys being depressed. This does not happen on the home made keyboards with the light keys. The bottom line is, play with it on a conventional keyboard but it will work far better on something with much lighter keys. HINT: if you are having trouble with 4 and 5 key chords, try rolling your fingers on to the keys in stead of pressing them simultaneously. This is the only way I can get an old IBM keyboard to see "num lock", "caps lock" and "o" (all 5 key chords). A picture of an early keyboard circuit board modified with an rj45 plug can be seen at http://www.cs.vassar.edu/~priestdo/image/chord.hack.top1.jpg Pictures of my current keyboard are at http://www.cs.vassar.edu/~priestdo/wearable.pics.html#LeatherKeyboardFour REQUIRED USER MODIFICATIONS You will need to edit a few lines of scancodes.h. These are lines numbered 194 - 208. They look like this: #define PINKY_MAKECODE 0x18 #define RING_MAKECODE 0x21 #define MIDDLE_MAKECODE 0x23 #define INDEX_MAKECODE 0x03 #define THUMB_RED_MAKECODE 0x10 #define THUMB_GREY_MAKECODE 0x25 #define THUMB_BLUE_MAKECODE 0x27 #define PINKY_BREAKCODE 0x98 #define RING_BREAKCODE 0xa1 #define MIDDLE_BREAKCODE 0xa3 #define INDEX_BREAKCODE 0x83 #define THUMB_RED_BREAKCODE 0x90 #define THUMB_GREY_BREAKCODE 0xa5 #define THUMB_BLUE_BREAKCODE 0xa7 You will need to change the values at the end of these lines to the values for the keys you want to use for these fingers. For example, if you want to practice chording on a conventional keyboard with your right hand, you might want to use the keys ";lkjn b" pinky = ";" ring = "l" middle = "k" index = "j" red = "n" grey = " " (space) blue = "b" Look up the make and break codes for each of these keys in scancodes.h. "B" can be found on lines 4 and 5: #define B_Make_SK "\x30" #define B_Break_SK "\xb0" SPACE can be found on lines 54 and 55: #define SPACE_Make_SK "\x39" #define SPACE_Break_SK "\xb9" "N" on lines 28 and 29: #define N_Make_SK "\x31" #define N_Break_SK "\xb1" Look up each of the 7 keys you will be pressing for your chording keyboard. Replace the appropriate values on lines 194 - 208 of scancodes.h. So in the above example, to use the SPACE for the grey key you would change line 199 to #define THUMB_GREY_MAKECODE 0x39 and line 207 to #define THUMB_GREY_BREAKCODE 0xb9 this would use the space for the grey thumb. Note the difference in representation "\x39" becomes 0x39. Once you have your seven keys entered in to scancodes.h save it, and (this is important ) touch pc_keyb.c.chording then rebuild and test your new kernel. By giving the command "touch pc_keyb.c.chording" you will force the rebuild of pc_keyb.o, if you don't do that, just changing scancodes.h will not necessarily cause the keyboard part of your kernel to be rebuilt. Alternatively you could remove pc_keyb.o as this will will force the rebuild as well. The default is to come up in chord mode. Pressing the three thumb keys together will toggle back to normal keyboard (in this example "B+N+SPACE"). Pressing the three thumbs again will restart the chording emulation. If you get stuck and don't know what chord mode you are in, press the three thumb keys 2 times. That will clear what ever state you are in and leave you in chord mode. BUT I DON'T WANT TO MAKE ANYTHING... As described above, with only the kernel hack and your existing keyboard you can still do a lot. You can pick any seven keys you like and make them into your chording keyboard, in this way you can practice and learn the chord sequences before you build any hardware. I also suspect, though I have not tried it, that you could use an external numeric keypad as a chording device and in that way have a small keyboard without having to do any hardware hacking (with a nod to Doug Plat). If you do this, please let know me so I can let others know as well. In the long run however, you will most likely want to build a keyboard yourself. If you want to build a 7 key keyboard I suggest you get the lightest keys you can find. Pressing 3,4 and 5 keys at the same time is harder on your hands than only pressing 1 or 2 as on conventional keyboards. It is important to get good keys. You will be pressing them a lot. I need to write a separate document on building the hardware side of a simple chording keyboard. Until I do that here are some notes on the process: Go and buy a cheap keyboard, cheaper the better, buy two while you are at it. By purchasing at the same time you increase your chance of getting two that are the same inside and so will let you use the same codes for your keys. Once you have them, open them up. Throw out everything but the little pc board inside and cable that goes from your machine to the pc board. You may want to have a look at the traces on the plastic sheets in there. From those you could get an idea on where to start testing. On the pc board is a chip. If this chip is large enough you can solder right to it, if it is too small to permit that you can solder to the tabs on the board that carried the signals from the keyboard matrix. You only need to solder 8 lines to it, one that is common to all your keys and one that goes to each of your seven keys. What you are going to do is find one line of this matrix and use it to build a chording keyboard from. To do this you need a short piece of wire and a working machine to plug the little board in to. Boot your machine with a regular keyboard attached. On paper make a sketch of the chip on the pc board with the pins numbered. Once the machine has booted log in and open up a text editor. Unplug your full keyboard and plug in the little pc board you pulled out of a keyboard. Using a small wire touch two pins on the chip till you see keys being generated on the screen. Do this systematically and keep records as you go! (pin 1 to pin2, pin 1 to pin 3, ... pin 19 to pin 20...) If your touch does not generate a key move on quickly. Your goal is to find one common pin that you can keep one end of the wire on and 7 other pins that generate keys when touched. These will be the locations you solder wires to. You can stop as soon as you have this. Alternatively you can do a little research on the web and find the keyboard matrix for that particular chip. I know it can be done that way, I use the wire method though so you are on your own for the web search. Either way, once you know what 7 keys you are going to map to the 7 buttons of your chording keyboard, follow the directions above and modify scancodes.h to reflect your key choices. Your "common" line goes to one pin of each key, you can go from the circuit board to one key and from there to the next key down the line. The other pin of each key will go the the appropriate pin on the chip. I have also found it usefull to have a way to turn off the keyboard. I do that with a toggle switch the cuts the common line between the keys and the circuit board. In that way pressing the keys has no effect. It makes putting on jackets and sweaters less likely to generate a bunch of characters if you are wearing a keyboard on your hand. OUTTRO As you have figured out (if you have gotten this far) there is a lot of room for improvement of this document. I very much want to share this information but had not intended to be the person writing it up. In the meantime, here it is and it does work. Please let me know if you get it working with newer kernels. If you want the hack for older kernels let me know and I will dig it up. If you modify this code in some useful way I would be happy to post your modifications here. If you like it so much you want to help document it - all the better. If there is interest I would be happy to host a discussion/developers list for folks using this hack, again, let me know if you are interested. Hope you find this helpfull, Greg Priest-Dorman Sept. 15 2000 lightly revised Oct. 16 2002 and again Oct. 26 2003