How to Use Custom Keyboard Mapping

As of version 1.7.2 of this VoodooPS2Controller.kext, I have added the capability to remap the keyboard based on scan codes as the keys are received. This keyboard mapping happens deep within the interrupt service routine of the driver, so it only works for the PS2 keyboard, not other keyboards (such as USB keyboards). If you wish to have a more general keyboard remapping service, use a program like KeyRemap4MacBook, available at: http://pqrs.org/macosx/keyremap4macbook. I use both techniques.

First of all, there are two different kinds of remapping included with this version:

• Remapping by translating one PS2 scan code into another PS2 scan code.
• Remapping by changing how PS2 scan codes are mapped into Apple ADB codes.

Each of these options is controlled by a section in the Info.plist located at VoodooPS2Controller.kext/Contents/PlugIns/VoodooPS2Keyboard/Contents/Info.plist. If you are looking at the kext from Finder, you can right-click and choose "Show Package Contents."

Of particular interest is this section of Info.plist:

		<key>Custom PS2 Map</key>
		<array>
			<string>;Items must be strings in the form of scanfrom=scanto</string>
			<string>;The following 12 items map Fn+fkeys to fkeys</string>
			<string>e05f=3b</string>
			<string>e012=3c</string>
			<string>e017=3d</string>
			.
			.
			.
			<string>57=e022</string>
			<string>58=e019</string>
		</array>

This section is where scan codes representing the Fn+fkeys and normal fkeys are swapped. Each string in the array maps one scan code to another. Scan codes are written in hex, and correspond exactly to scan codes you see if you run the debug version of the voodoo kext. This section is using the PS2 to PS2 scan code mapping feature. It could have been implemented using the PS2 to ADB mapping feature as well, but ADB codes are a little difficult to obtain, unless you can read the source code... In a case like this, where we are just mapping one key to another, it makes the most sense to do it with PS2 to PS2 scan code mapping.

Take a look at the mapping for the first item: e05f=3b. Each map entry follows the pattern, scanFrom=scanTo. Scan code e05f corresponds to Fn+F1 on the HP 4530s keyboard. Other keyboards may vary. Scan code 3b corresponds to F1. So this entry maps Fn+F1 to F1. Entries that start with a semi-colon are considered comments. Scan codes can be normal scan codes or extended. Extended scan codes always begin with 'e0'. So, 'e05f' above is an extended scan code. When scan codes are delivered to the driver, they are delivered one byte at a time, so an extended scan code comes over first as a 'e0', then follows with the specific scan code associated with that extended key. When you examine the debug output, you will see these scan codes come in as separate items.

The last entry in the snippet above is mapping the F12 key to Fn+F12.

If you wanted to remove any of these mappings, you just remove the lines from the Info.plist. It is best to do all editing of the Info.plist to a copy of the entire kext located outside of /System/Library/Extensions. When you are done editing, save the Info.plist to that location, then re-install the entire kext. Edits to the Info.plist can be made in place while the kext is installed, but doing so is beyond the scope of this guide. If you know how to do it, go ahead... If not, stick with my suggestion above.

You can edit the Info.plist with a text editor or a plist editor. If you use a text editor you must be careful to maintain proper syntax for XML files. Apple's Xcode development environment includes a plist editor and I'm sure there are other free plist editors available.

In addition, there is PS2 to ADB mapping available. This mapping is available in the 'Custom ADB Map' section:

		<key>Custom ADB Map</key>
		<array>
			<string>;Items must be strings in the form of scanfrom=adbto</string>
		</array>

This map is very similar to the 'Custom PS2 Map' except in this case, PS2 scan codes are mapped to ADB codes. For example, here is a section which would have the effect of mapping the 'World' button to just to the left of the WiFi button on the 4530s keyboard to OS X Launchpad:

		<key>Custom ADB Map</key>
		<array>
			<string>;Items must be strings in the form of scanfrom=adbto</string>
			<string>e032=83</string>
		</array>

The ADB code for Launchpad is 83. And the scan code for the 'World' button is e032. In the debug version of the keyboard driver only, you can generate any ADB code you want. To do so, hold down Alt, then type the ADB code with the numpad number keys (0-9). The resulting code is sent after you release the Alt key. This was how I discovered the ADB code for the Launchpad is 0x83 (Alt-down, 1, 3, 1, Alt-up).