IBM Model F 122-key Keyboard

A recent fad at work is for the vintage clickety-click of IBM's buckling spring keyboards. While some are content to buy modern versions of these (from places like Keyboard Co) I prefer to take the original route. To this end I grabbed an original IBM Model F 122-key keyboard (model 1390582) from the usual place. And what a monster!

This was originally used with something like a 3270 terminal, and some of the keys don't quite match with today's PC keyboard layout.

Now, of course, the problem with new computers is they no longer support the old keyboard connectors, especially not the custom 5-pin DIN connector on this IBM keyboard. You'll note that I put the blame on modern computers - how can you blame something that was around long before the laptop existed, eh?

The solution is simple.

Soarer's Adapter

Originally developed several years ago by some enterprising chap going by the internet handle of "Soarer". geekhack.

Now someone is selling ready-made converter cables on eBay. From the auction page:

Up for buy it now is a NEW custom USB Soarer's Keyboard Converter for Model F 122 Key terminal keyboards that have 5 pins in a 270 degree orientation. It is about 1ft in length. Each lot is for one adapter shown. It is plug and play, but the keyboard must be plugged into the adapter before plugging the adapter into the computer initially so that the adapter correctly senses the keyboard. The adapter will work as is, but it will plug in farther and more securely if the if the screw in shield is removed with a dremel from the original F122 cable. These cary a 30 day return period if you are unsatisfied for ANY reason. Soarer's Converter adds the ability to remap keys, add macros, add additional function layers, and be able to toggle different layouts by pressing a single key. All IBM Model F 122 Keyboards support full NKRO with this adapter.

Here's a simplified explanation of Soarer's Converter's main features:

Remapping - Assign any key to any other key, including ones that aren't on the keyboard, like media volume controls or the "Apple/Command/Windows" key which is not present on the Model F.

Macros - A single key press can "play back" a series of key presses. For example, you could set F12 to send Control-Alt-Delete or set one key to represent an entire shortcut like Alt-C for "copy" when doing copying and pasting. If there's a certain combination move in gaming, you could set one key to perform the entire combination.

Function Layers - Changes the behavior of other keys when the function key is held down. Think of this like adding extra "Shift" keys to add more functions to existing keys.

IfSelect - Press a key once and it permanently changes the function of any number of keys until that same key is pressed again. Think of this like "Num Lock" which completely changes what the number pad does. This is also useful if you are using multiple different operating systems or applications that you want different layouts from time to time. Pressing one key could change the function of "ALT" to the "Apple/Command/Windows" key. It also will allow you to have several different layouts programmed for different applications. You can even program in completely different keyboard layouts like Dvorak or Colemak and toggle between them with a single key press.

For more information on Soarer's Converter, please see check out the forum here: Soarer’s Converter thread on Geekhack

I've written some basic instructions for configuring the Soarer's Converter under Windows OS, which is still a work in progress. Be sure to read at these instructions BEFORE PURCHASE to see if it looks like something that you will be able to do: Simplified Soarer’s Converter Instructions. Instructions for programming with other operating systems can be found on the Soarer's Converter thread on Geekhack. Configuration is usually not needed for regular conversion to USB with key rollover preservation without the extra features like remapping, macros, etc.


Tools you’ll need to download before you start:

Soarer’s file set: http://geekhack.org/index.php?action=dlattach;topic=17458.0;attach=10519

HID Listen Utility (Identifies how to refer to keys while making your 
configuration file): https://www.pjrc.com/teensy/hid_listen.html



IMPORTANT: Plug the adapter into the keyboard FIRST, then plug the USB end into 
the computer.  The Soarer’s Converter may not work correctly if plugged into the 
computer before the keyboard is plugged into the Soarer’s Converter. 


Identifying how to name the keys while making your configuration file:

The USB HID table should be consulted to show how to name the keys that you want 
to configure.  If you are using a terminal keyboard with oddly marked keys or are 
unsure how to name a key for any reason, use the HID listen utility (linked at the 
top of this document). Run the HID listen utility with the keyboard and converter 
plugged in  and press and release the key that you want to identify.  It will 
output a string of letters and numbers.  Find the two digit number that has a “+” 
in front of it and look that number up in the HID chart in the “Codes” HTML file 
that is included with Soarer’s Fileset within the “docs” folder (linked at the 
top of the document).  You can ignore the “0x” part of the HID codes listed.  

For example, Pressing the “A” key while running HID listen will give an output of 
something like (which can vary depending on the keyboard protocol): 

r1C +04 d04 rF0 r1C -04 u04

The number we need is always preceded by the “+” which is “04” in this case.  
Consulting the HID code set list (and ignoring the “0x” part) from Soarer’s “docs” 
shows that the name used for this key is simply “A” as you might expect.  

You must use exactly what the HID table shows when referring to different keys 
throughout the making the configuration file. HID listen is often needed for terminal 
keyboards that have keys that aren’t normally found on modern keyboards, so HID 
listen is essential for naming these keys so that they can be re-configured to something 
useful. 

Go to the “configs” folder and go to the file called “empty.sc” and you may rename it 
to “TEST” or whatever you want and drag it to the Desktop.  This will be the file that 
you will type your custom configuration into.  There are several other pre-made 
configuration files that you can examine after getting an idea of what each function does.  

Go to the desktop and open the blank configuration file that you renamed “TEST.”






Concept #1: Remapping Keys

Remapping keys changes one key to a different key:

remapblock
	LALT LGUI
	F4 MEDIA_VOLUME_DOWN
	F5 MEDIA_VOLUME_UP
	
endblock

Starts off with “remapblock” on its own line, start a new line, tab over, type the 
name of the key that you want to modify, put one space, then type the name of the 
key that you want it to be remapped (re-assigned) to.  You may name as many keys as 
you want in this same way underneath the “remapblock” line.  In the above example, 
Left ALT (LALT) will be remapped to LGUI (which is the Windows/Command/Apple key).  
F4 will be set to decrease volume, and F5 will be set to increase volume.  The 
names of these were found in the same HID “codes” list found in the “docs” folder 
mentioned earlier that we used with HID listen.  When you are finished remapping 
keys, start a new line and type “endblock” 

SAVE YOUR CONFIGURATION FILE by going to the “file” menu and selecting “save.”




Concept #2: Uploading your configuration

Now would be a good time to upload that configuration “as-is” to see that you’ve 
made progress and so you’ll know how to upload later.

I am writing the configuration upload instructions assuming that you are using 
Windows because it is easiest to explain.  For other operating systems, you can 
read Soarer’s provided documentation from the fileset. 

Open “Soarer_sctools_v1.10_win32.zip” from within the “tools” folder within the 
original Soarer’s file set initially downloaded. 

Locate the “scaswr.bat” file within the new folder but do not click on it. Position 
the folder window that contains “scaswr.bat” so that you can see the “TEST” file 
(or whatever you named your configuration file) that is on the desktop and the 
“scaswr.bat” file on your computer screen.  DO NOT REMOVE the “scaswr.bat” file 
from the folder that it is in since it relies on the other files in that folder to 
function!  Drag and drop the “TEST” file into “scaswr.bat” and the configuration 
file will be uploaded to the Soarer’s Converter. If you see any errors in the 
terminal window that shows progress, then something is mistyped or missing in your 
“TEST” configuration file and it will tell you what line from the top that the 
problem is on. 

If all went well, you should be able to try out what we’ve done so far.  Pressing 
the Left ALT key on the keyboard that the Soarer’s converter is being used with 
will now be re-assigned to the Windows/Apple/Command key, F4 will decrease the 
computer speaker volume, and F5 will increase the speaker volume. 

From now on, you can try any of the following techniques by modifying your 
configuration file, saving it, and uploading the modified configuration to 
the Soarer’s converter by dragging the updated configuration file into “scaswr.bat” 
like you just did.  Please note that each time a configuration file is uploaded, it 
will overwrite/replace the previous configuration stored on the Soarer’s converter 
completely.  




Concept #3: Macros 

Macros are like a recording of a combination of keys held down or pressed in a 
certain order like CTRL-ALT-DELETE or outputting a string of characters like a 
password or website address.  Can be used to make keyboard shortcuts initiate by 
pressing only one key such as copy, paste, find, go to next tab, save, bold, and 
countless others.  

macroblock
macro ESC 
	MAKE LCTRL 
	MAKE LALT 
	MAKE DELETE
	BREAK LCTRL
	BREAK LALT 
	BREAK DELETE
endmacro
endblock

When Escape is pressed, the keyboard emulates the holding (make) of Left Control 
(LCTRL), Left Alt (LALT), and DELETE, then releases each one (BREAK Command for each).  
So the end result is that pressing escape performs a CTRL-ALT-DELETE which would be 
useful for login or getting into the task manager.  The software requires that L or R 
be added in front of CTRL to indicate if it is the left or the right control key that 
is being pressed.  Does not matter for any of these examples whether right or left is
used.


Usage starts with “macroblock”, new line, then “macro”, then a space, then the name 
of the key or key combination that you want to trigger the macro separated by spaces.  
Next lines are the macro commands in the order that you want them to be followed.  
New line, then “endmacro”, new line and “endblock”

Macros are also useful for common keyboard shortcuts like select all (CTRL-A)
 copy (CTRL-C), paste (CTRL-V), moving to the next tab (CTRL-TAB), etc. In the example 
 below, F1 is set to Select All, F2 is set to Copy, F3 is set to Paste, and F4 is set 
 to Next Tab.   This can be done with any other keyboard shortcut like Save, Print, Undo, etc. 

The macro SECTION of programming needs to start with “macroblock” and end with “endblock”. 
Each individual macro starts with “macro” and ends with “endmacro”


macrolock
macro F1
	MAKE LCTRL
	MAKE A
	BREAK LCTRL
	BREAK A
endmacro

macro F2
	MAKE LCTRL
	MAKE C
	BREAK LCTRL
	BREAK C
endmacro

macro F3
	MAKE LCTRL
	MAKE V
	BREAK LCTRL
	BREAK V
endmacro

macro F4
	MAKE LCTRL
	MAKE TAB
	BREAK LCTRL
	BREAK TAB
endmacro
endblock  

The command below shows how text can be input as macros, so you could do this for 
passwords or other commonly used strings of text.

Putting a “-“ in front of something on the macro line means that the key must not 
be pressed for the macro to trigger.  So in the example below, if you hold “T”, F6, 
and Left Shift, this macro will not trigger.  This is useful when you want to have 
similar macro enabling scenarios, but don’t want them to overlap.

macroblock
macro F6 -T LSHIFT
	PUSH_META CLEAR_META all
	Press A
	Press A
	Press A
	SET_META LSHIFT
	Delay 5
	Press A
	Press A
	Press A
	POP_ALL_META
endmacro
endblock

Above produces “aaaAAA” when pressing Left Shift and F6, but only if “T” is not 
pressed (because of the “-T” added)

Normal key (F6) needs to be listed before the meta, in this case meta is LSHIFT.  
If all characters don’t show up in testing, do a 5 millisecond delay every so many 
lines.  I found that after 3 presses or after each meta set, it needs a 
5 millisecond delay

Please note that the non-modifier key needs to be listed first, so in the above 
example, F6 needs to be listed first.  Keys like shift alt, option, and command 
are modifiers which Soarer will also refer to as “metas.”  





Concept #4: Function Layers


Think of the function layer like the “shift” key on a regular keyboard.  When 
pressed, it changes the behavior of other keys while HELD DOWN.  So numbers 
like 4 become symbols like $ and the normal “.” key becomes “>” while shift is 
held down.  

You can have up to 8 different function keys (FN’s) that can be used and each 
must be named first.  So in this example, FN1 is assigned to be layer “1.” 

layerblock
	FN1 1			
   	FN2 2
endblock

remapblock
    	F11 FN1
    	F12 FN2
endblock

remapblock
    	layer 1
    	Q P
	A Z
endblock

remapblock 
    	layer 2
    	Q Y
	B T
endblock


Each FN key (1 through 8) needs to be defined as an actual key that can be 
pressed to activate the layer, so remapblock is used for this.  In the example, 
“F11 Key” is assigned to FN1 which we defined as “Layer 1” on the second line 
“FN1 1” and “F12 Key” is assigned to be FN2 which we defined as “Layer 2.”  
Pressing the F11 key causes us to move into “layer 1” which will be the same 
as the regular keyboard layout except for any keys that we redefine will now 
be different while the specified function key is held down.  So in layer 1 
(activated by holding down F11), pressing Q instead produces P, but while holding 
down F12 (which we assigned to layer 2), pressing Q instead produces Y.  If 
neither function key is pressed down, Q produces Q as normal.




Concept #5 - Ifselect

If you want to toggle something on and off more permanently without needing to 
hold down the activating key, like remapping the ALT key to the Apple/Command/Windows 
key when using a Mac versus a PC, “ifselect” should be used. 

Up to 7 different ifselects are supported and must be named 1 through 7 and 
is formatted: SELECT_1, SELECT_2, SELECT_3, etc.

Ifselect is used by specifying what changes should be made when you press 
the activating key. The same key that activates it will deactivate it as well.  
Any code following “ifselect” applies to that selection number until the next 
“ifselect” in the text document.  If you want to go back to modifying the base 
layer, you can put “ifselect any” meaning that it doesn’t matter what selection 
you are in and the code following it will always apply.


ifselect 1
remapblock
	Q P
	A Z
endblock

ifselect any
remapblock
	F10 SELECT_1
endblock


In the above example, F10 has been remapped to activate SELECT_1 which is 
defined above it.  The reason for this is that we always want to be able to 
activate or deactivate the selection no matter what selection we are in.  The 
code to activate it is written below and after “ifselect any” so that the 
converter knows that we are done defining changes for ifselect 1, which includes
everything between each ifselect written in the code. 


As a final example of this, this is how you would toggle the swapping of ALT keys 
for the Apple/Windows key using ifselect.  We will make this the Select 2 and 
assign the key to activate Select 2 to be F9:

ifselect 2
remapblock 
	RALT RGUI
	LALT LGUI
endblock

ifselect any
remapblock 
	F9 SELECT_2
endblock