Help with Soarer's Converter programming

I recently got ahold of an IBM Space-Saving Keyboard Model M, and it had a USB cable with the integrated Soarer’s Converter Teensy controller. I’ve been trying to understand how to program the board using Soarer’s documentation, but frankly I’m in a bit of a loss.

Would anyone be kind to help me out?

3 Likes

I am also curious…I have one of orihalcon’s cables and I can’t figure out how to use the Soarer’s programming utilities.

Oh boy, something I actually know how to do.


First you’ll want to download the Soarer_Converter_v1.10.zip from the Soarers’ GMK thread. Should be at https://geekhack.org/index.php?topic=17458.0 along with the 1.12 update, but that can be dealt with later.


Inside this zip are the configs, docs, firmware, and tools folders. Docs is important because it has the html docs that help with using Soarers’, but for now we’re interested in tools.


Inside you’ll want to extract the win32 sctools folder.


Once inside, the file you want to pay attention to is the scaswr.bat file. This is the batch file that will allow you to flash your updated keymap to the Soarers’ converter.


This is a basic remap file. The important bits are the remapblock at the beginning and endblock at the end. Anything starting with # is just a note and isn’t paid attention to. The way the remapping works is you take the keycode that the key you want to remap currently sends and the keycode you want it to send and just put them on a tabbed line together. For example, I have my key that normally sends EXTRA_F1 remapped to send MEDIA_VOLUME_DOWN. To find what keycodes are currently being sent through the converter by any key you can download hid_listen from https://www.pjrc.com/teensy/hid_listen.html open it, and just press keys to see the codes. Then, you can open codes.html back in the docs folder to look for the code you actually want it to send.


After saving your remap.sc file, just drag it on top of scaswr.bat with the converter plugged in to compile the map and then upload it to the converter.


If you want to update to 1.12 you can just download the 1.12update zip, extract, then using either Teensy.exe or QMK Toolbox flash the appropriate .hex onto the converter.

Hopefully this is clear enough, it’s been a bit since I’ve messed with it so hopefully I got everything right.

Edit: A quick thought, you might want to start with a remap.sc file that’s blank besides remapblock and endblock first to reset any remappings that the previous owner might have set. The remap won’t work unless you’re using the keycodes that are originally being sent by those specific keys.

7 Likes

Thank you so much, @donutcat!

This helped a bunch. So it’s kind of weird, but I actually couldn’t use any of the Windows tools properly for some reason.

  • My PC would detect Soarer’s Keyboard Converter when the keyboard was plugged in and the default keymap (the keys as they are printed) was working fine.
  • When I tried the HID_listen tool, it was stuck on “Listening…” and nothing would happen when I typed keys while the terminal was open!
  • I wanted to update the controller to the v1.12 ATMega32u hex file, but I couldn’t get the Soarer’s to Bootloader mode (scboot would run and give me “ok” but it wouldn’t actually do anything to the controller, and the keyboard would still function normally).
  • In the end, I tried everything I could, even installed the Arduino IDE and Teensy tools, but I just couldn’t get it to work on PC.

So I got the same tools on Mac, created my keymap, and remapped it via the Terminal on Mac. HID Listen would work fine there, and the remapping was successful, fortunately. I’m still at a loss as to why Soarer’s wouldn’t be detected properly by the sctools and HID Listen on my PC though… even though it seems I have all the right drivers.

I had some issues with tools on Windows 10 but works just fine on Windows 7. I’m using my own XT / AT Soarer’s Converter at www.tinkerboy.xyz

Hi, LightningXi, I am new to Soarer’s, and have been looking for Macintosh instructions. Your post implies that it is possible to reconfigure via Terminal rather than downloading various programs (that I do not understand). If you have time to explain how this works, I would be most grateful. Many thanks! jmolinarius

Thanks for the post! I recently picked up a Terminal Model M (Part #1392595, I.D. #5101301) and Soarer’s converter but to be honest, I’m a bit of a lunkhead and have had issues learning how to use it. Thanks to this post, I was able to remap a couple of keys and for that I am thankful.

My Model M has some Funky keys.
Where “NumLock” should be, I have “JUMP”
My Numpad has the numbers, but also has what looks to be tools for drawing box menus.

here is what I used:

remapblock
#extra_function_keys
EXTRA_F1 MEDIA_VOLUME_DOWN
EXTRA_F2 MEDIA_VOLUME_UP
EXTRA_F3 MEDIA_CALCULATOR
EXTRA_F4 PRINTSCREEN

PAD_PLUS PAD_ENTER
PAD_MINUS PAD_PLUS
PAD_ASTERIX PAD_MINUS
LALT LALT

endblock

Anyway, I still have so much to learn, but I’m off on a good start. I just need to figure out how decipher what I see in HID_Listen …

In the “docs” folder of your Soarer’s download you should see a file called “codes.html”. Open that and it’ll give you every code you should see in HID_listen and what key it pertains to.

Just as a follow up, here is my finished product for my M122 keyboard. I made sure to give credit to Depletes Vespene for the examples I found and used as learning material.

Soarer Converter’s configuration for an IBM Model M122 (1394167) keyboard.

Author: Weston Wills.

Date: 20190904.

Version: 2.0.

Shout out to Depletes Vespene. Without his sample code, I was lost in the wilderness

The IBM Model M122 doesn’t have the double size PAD_PLUS key so I remapped the TWO keys that held that spot on the NUM_PAD.

BEGIN

remapblock
SCROLL_LOCK PAD_ASTERIX
NUM_LOCK PAD_SLASH
PAD_PLUS PAD_ENTER
PAD_MINUS PAD_PLUS
PAD_ASTERIX PAD_PLUS
LALT LALT
PAD_1 PAD_1
ESC NUM_LOCK

EXTRA_SYSRQ PAD_MINUS
EUROPE_1 BACKSLASH
EXTRA_F1 ESC
EXTRA_F4 RALT
EXTRA_F5 UNASSIGNED
EXTRA_F6 UNASSIGNED
EXTRA_F7 UNASSIGNED
EXTRA_F8 UNASSIGNED
EXTRA_F9 LGUI
EXTRA_F10 APP
F13 MEDIA_MUTE
F14 MEDIA_VOLUME_DOWN
F15 MEDIA_VOLUME_UP
F16 SELECT_1
F17 MEDIA_PLAY_PAUSE
F18 MEDIA_PREV_TRACK
F19 MEDIA_NEXT_TRACK
F20 MEDIA_STOP
F21 NUM_LOCK
F23 PRINTSCREEN
F24 PAUSE

endblock

Thanks for this! I am in the middle of a M122 refurb.

Question: Has anyone successfully compiled the Soarer utilities on a recent version of MacOS?