×

Soarer's 101-#1: An Introduction

Perhaps one of the most daunting things about getting into the vintage keyboard hobby is figuring out how you're supposed to use your Model F/XT or Model M122 in today's age. For some of the pre-PS/2 era stuff like those aforementioned keyboards, this can be a mission. But for IBM keyboards, a Soarer's Converter can have your back. This multi-part guide is going to be pretty comprehensive, covering what a Soarer's Converter is, its capabilities and whether you really need one, to showing you how to bind a macro to any key you want via Soarer's Converter! This guide will assume little prior knowledge of the subject.

This first part will cover details about the Soarer's Converter, figuring out if you need one, where you can procure them from, and a run around the included software tools to help get you familiar with them. To help with context, I will be using a set keyboard - a 122-key Model M - as an example.

Understanding terms

Inevitably, the use of technical terms will arise during the course of these tutorials. To help in such cases, I maintain a Keyboard Dictionary where most of such technical terms are defined. If after checking the dictionary you're a still stuck, feel free to contact me with any relevant questions (contact details are on the About page).

What can Soarer's do

In the most simple terms, the Soarer's Converter is an active converter for keyboards. 'Active' in that there are electronics inside that translate a given protocol into a different one without involving the host computer. In this case, it's taking the scancodes of non-USB compliant keyboards and turns them into USB HID codes that a modern personal computer will understand. Four protocols are supported by Soarer's:

  1. Set 1/XT
  2. Set 2/AT
  3. Set 2 Extended (aka, PS/2)
  4. Set 3/Terminal

For more details on each of the protocols, see my Keyboard Connections topic. But sufficed to say, the support of these four protocols means Soarer's can handle converting the vast majority of obtainable Model F and Model M keyboards and potentially a lot of clone PC keyboards of the period too. Soarer's Converter also grants numerous bonus features that go beyond mere conversion for your keyboard. These include:

Do I need Soarer's?

Whether it is the cost of buying a complete one or the time required to assemble one yourself, there is some sort of cost involved. To help you make sure that you absolutely need or want one, here are some scenarios for you to consider. If you have already made up your mind, please skip this.

I want to make use of my XT or terminal keyboard

Ignoring the inherent remapping and macro features you get, a Soarer's is a good choice for converting your Model F/XT or M122 (for example) to run on a modern machine. Passive adapters or simpler/cheaper active converters for XT and terminal standards are not really a thing.

I simply want to make use of an AT or PS/2 keyboard

If you are not going to require remapping or macros nor require the converter for any XT keyboards you might have, save some money with a simpler active converter from AT or PS/2 to USB. If you are wondering what converter to get instead, see the "I want to use my vintage PS/2 keyboard with a modern PC - how?" answer in my Keyboard FAQ.

My keyboard is already USB but I want hardware remapping and macros

Firstly, USB to USB Soarer's Converter do exist (see "Where to buy") but not every USB keyboard is compatible. USB keyboards typically come in either HID-only or HID with PS/2 compatibility mode flavours. If a keyboard advertises itself as PS/2 compatible, having n-key rollover via PS/2 or came with a USB to PS/2 adapter as standard, then it is the latter and 'reconverting' it via Soarer's is a viable thing. Unfortunately for the former, Soarer's cannot handle HID to HID so you will have to look into alternatives like AutoHotkey to achieve your goals.

Where to buy

Presently, there are two established and trusted places to buy commercial Soarer's Converters from; orihalcon @ eBay and tinkerBOY. Both vendors always sell the following:

On occasion, orihalcon has sold USB to USB Soarer's Converters too. If you are unsure on which one you need, try searching your part number (the 7-digit number on the back of your IBM, Lexmark or Unicomp keyboard) in my keyboard database to see what connector name you got or ask on r/ModelM for assistance.

Getting started with the tools

Once you have received your converter or built your own, it is time to download the supporting software to get into this! There are two official download locations which you should only use:

From either of those, download and extract the following compressed files:

  1. Soarer_Converter_v1.10.zip

Once extracted, you will be greeted with four folders. The configs folder is handy for you to store your future code in. You will see that a number of examples fo Soarer's Converter remapping and macro code is available for you to use as a working reference too.

The docs folder will be your greatest ally in this endeavour (next to me). Soarer made some comprehensive documentation to go along with his firmware, including details about the hardware, coding syntax, quick references, and the modified HID scancode dictionary.

The firmware folder contains a few builds of Soarer's Converter firmware for different microcontrollers and their differing CPUs. If you are a using a commercial adapter, the firmware should already be flashed to it and thus ignore this folder for now.

The tools folder contains four subsequent archives; tools for Windows, macOS and Linux, and the source code for them. These tools are what you will use to compile your code and upload them to the converter.

Documentation

The documentation comes in the form of an offline website that you can access my opening index.html with your web browser of choice. Unless you are planning to more low-level things with the converter's hardware itself, the QuickRef and Codes pages are the ones you want to pay attention to. QuickRef describes in brief all of the code syntax that you will use to specify what you want your converter to do - don't worry, I will explain it later! Codes is basically your key code dictionary, specifying all the possible keys Soarer's can handle and send out.

Software commands

The "Tools" page in the documentation explains describes what all of the executables you get do, but scas (Soarer's Converter Assembler) and scwr (Soarer's Converter Writer) are the only two you need for routine operation. scas is used for compiling your code into the .scb binary format expected by the Soarer's hardware, and scwr writes the compilied code to the converter.

To have a quick and safe practise run with using these commands without needing to code anything, use the empty.sc file found in the configs folder as a 'test subject'. I just copied it into the same folder as the tools for convenience. Starting with scas, you type the executable's name with a "./" and type the file name of the config you want to compile and what the name of the output should be:

./scas empty.sc empty.scb

And now scwr - you will need to have your converter plugged in for this to work:

./scwr empty.scb

If everything goes to plan, you should get an output like this from both commands:

PS C:\Users\Shark\Soarer's\tools> ./scas empty.sc empty.scb
scas v1.10
No errors. Wrote: empty.scb

PS C:\Users\Shark\Soarer's\tools> ./scwr empty.scb
scwr v1.10
scwr: looking for Soarer's Converter: found
scwr: reading file: 6 bytes: ok
scwr: sending info request: ok
device: ok
protocol version check: converter=1.00, scwr=1.00: ok
settings version check: converter=1.01, file=1.01: ok
settings length check: max=1018, file=4 bytes: ok
scwr: sending write request for 4 bytes: ok
device: ok
device: ready
scwr: sending 4 bytes: ok
device: ok
device: complete

The empty file we used should not change anything and the converter should still be running as default.

A note for Windows users...

Windows users get an easier life when it comes to running these commands since Soarer's tools for the platform come with an additional file - scaswr.bat. This batch file will automate the execution of both commands described above, and the best part about it is that you can simply drag and drop your .sc file onto it and it will just run!

For Linux and macOS users, it should be noted that this functionality could be replicated using a Bash script, but you will need to make that yourself.

Identifying your keys

A screenshot of PJRC
An example of HID Listen's output

Before you can do anything with Soarer's, you are going to want to know how your computer sees your keys so that you can identify the keys that you want to remap or add macros to. Because the Soarer's Converter is based on Teensy (or other ATMEGA32U4-based) devices, you can use PJRC's HID Listen program to figure this out. It is available for Windows, Linux and macOS.

For the output example shown, I pressed the SysRq/Attn key on my keyboard twice, and for each time I did so, I got two sets of codes; the key register (+B8) and the key release (-B8) code. Be aware that Soarer's HID codes and the official USB standards ones do differ occasionally - if I was to refer to the official Universal Serial Bus HID Usage Tables, B8 is specified to be "Keypad {". However, Soarer's Codes documentation says otherwise. Soarer's modified HID codeset defines B8 as EXTRA_F2 instead. Whilst Soarer's HID codeset is roughly compliant with official HID for typical 101 to 105 key configurations, Soarer's made some redefinitions to make things easier for 122-key users like myself.