Soarer's 101-#1: An Introduction

Not all keyboards are USB or even PS/2, something especially true for some vintage keyboards. Perhaps one of the most daunting things about getting into the vintage keyboard hobby is figuring out how you're supposed to use your vintage keyboard that doesn't use one of these natively supported (or at least, easy to convert) standards. Even fairly common vintage keyboards such as IBM PC and PC/XT Model Fs or pre-Unicomp 122-key Model Ms can't simply be used through USB or converted with a cheap store-bought converter. However, a Soarer's Converter may just 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.

Contents

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 still stuck, feel free to contact me with any relevant questions.

What is Soarer's and what can it do?

In the most simple terms, the Soarer's Converter takes output data of a connected keyboard and translates it to USB's standard - the human interface device (HID) class. The important components of that data are the scancodes, which are the codes reported when a key has been pressed. The fact it translates scancodes makes Soarer's Converter an active converter, with 'active' referring to the fact there are electronics inside that process data without involving the host computer. In this case, it's taking the scancodes of non-USB compliant keyboards and turning them into HID scancodes that a modern personal computer will understand. Three main (plus a variant of) scancodes are supported by Soarer's:

To learn more about these base scancodes, see my Keyboard Scancodes topic (though knowledge of them is not required for this guide). But sufficed to say, the support of these scancode sets 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 PC/XT or terminal keyboard

Ignoring the inherent remapping and macro features you get, a Soarer's is a good choice for converting your XT or 122-key keyboard (for example) to run on a modern machine. Passive adapters or simpler/cheaper active converters for set 1 and set 3 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 QnA.

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.

Update 2022-02-08: it seems USB to USB Soarer's Converters are no longer made and haven't been commercially available in a while. As such, the closest substitute would be the TMK-based Hasu USB to USB Controller. However, it's an extremely expensive device. As such, I'd recommend settling for a software-based solution with AutoHotkey on Windows or xmodmap on Linux to achieve your goals.

How do I get a Soarer's?

Presently, orihalcon @ eBay is the most established place to get premade Soarer's Converters from. They typically sell the following:

If you are unsure on which one you need, try searching your part number - the typically 7-digit number on the back of your IBM, Lexmark or Unicomp keyboard - in my Keyboard Part Number Database to see what connector your keyboard is supposed to have. If you're still unsure (or if the information looks wrong), you're welcome to give me a shout or post on r/ModelM.

Getting started

Once you've obtained a Soarer's Converter, it is time to download the supporting software to get into this! There are two official download locations that you should only use:

From either of those, you'll notice that there are multiple files you can download. For commercially bought Soarer's, they typically have firmware version 1.10 flashed onto them by default. In such a case, you'll need to download Soarer_Converter_v1.10.zip. If you had someone else make one for you, you've probably got the absolute latest firmware, 1.12. In such a case, you'll need to download Soarer_Converter_v1.12_update.zip as well as the Soarer_Converter_v1.10.zip files. Once you've downloaded the one or two zip files, you'll need to extract them to a folder. If you also need the 1.12 files, simply extract and replace the 1.10 files with the same names. The basic folder structure you'll be greeted with is the following:

Documentation

The documentation comes in the form of an offline website that you can access by 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 (configquickref.html) and Codes (codes.html) pages are the ones you want to pay attention to. The QuickRef page describes in brief all of the code syntax that you will use to specify what you want your converter to do - don't worry, this is explained in the next chapter (101-#2). The Codes page is basically your key-code dictionary, specifying all the possible keys Soarer's can handle.

Software commands

The Tools (tools.html) page in the docs folder explains describes the function of all of the executables you get, but scas (Soarer's Converter Assembler) and scwr (Soarer's Converter Writer) are the only two you need for routine operation on all operating systems. scas is used for compiling your code into the .scb binary format expected by the Soarer's hardware, and scwr writes the compiled code to the converter.

To have a quick and safe practice 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 at the start a "./" (Linux/macOS), ".\" (Windows PowerShell) or neither (Windows Command Prompt), 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\Soarers\tools> .\scas empty.sc empty.scb
scas v1.10
No errors. Wrote: empty.scb

PS C:\Users\Shark\Soarers\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.

Identifying your keys

As you'll soon see in the next part of the guide, remapping or assigning macros to keys requires you to know the specific key-code name. These key-codes you will be using are of Soarer's modified HID codeset that I briefly referred to in "Getting started" - you can view the entire codeset usage table by opening the codes.html file in the docs folder you extracted from the downloaded zip files. They're roughly based on the official USB HID usage tables, but Soarer used a bit of 'artistic license' to make life easier for 122-key users (such as myself) as you'll soon see. The purpose of the codeset is to enumerate raw HID scancodes in a human-readable fashion.

In basic operation, you could refer to the modified HID codeset and use simple logic to figure out what key-codes you want/need to use. However, there are limitations with this approach:

With those points in mind, it's prudent to familiarise yourself with the process of identifying key-code names from raw scancodes yourself. So, how do we find these scancodes for given keys? Since most Soarer's Converters use an ATmega32U4-based chip as their base, you can use PJRC's HID Listen program to figure out the scancode of a pressed key. Despite being made for use with Teensy microcontrollers, it will also work with commercial Soarer's Converters and self-assembled ones that use Pro Micro or Elite-C microcontrollers. It is available for Windows, Linux and macOS. Once you've downloaded it, simply run the program whilst your Soarer's is connected to your computer and start pressing keys.

For the output example shown, I pressed the SysRq/Attn key on my 122-key keyboard twice, and for each time I did so, I got two sets of raw scancodes; the key register (+B8) and the key release (-B8) code. If you refer to Soarer's modified HID codeset, you'll see that the key-code name for scancode B8 is EXTRA_F2. In case you're already familiar with the official HID codeset, you'll note the differences I implied before since B8 is specified to be "Keypad {" instead¹. Anyway, this should be all you need to know to progress forward into remapping and making macros!

Sources

Corrections & changes