Explain like I'm 5: Remap a key with a Soarer's converter

[dellmodelm]

So a few weeks ago I decided to buy a Model F AT keyboard. I'm not a stranger to most things IT-related, but I'd never used a Model F in any way, shape or form, so I figured this would be a fun little excursion into vintage computing. (I do have experience with Model M keyboards, for what it's worth.)

So at first I tried connecting the Model F AT to my new desktop PC using a passive adapter (DIN5 to PS2) with a cheap active converter to USB. Did not work (probably more voltage than the converter can handle). So I bought a new Soarer's converter and now the Model F AT works on my new computer.

Totally happy, except I have one key (SYSREQ) that does not work. I downloaded something called HID_Listen and sure enough, the key is sending out a signal... but Windows is ignoring it. So I got on "another keyboarding forum" and asked and the obvious answer is, program the Soarer's to send the signal to the key I want (my pick would be Left Windows/Super). A really helpful member gave me this code to use:

remapblock
EXTRA_SYSRQ LGUI
endblock

So I got into the Soarer's documentation to start my adventure of remapping this key, and... now it's 10 hours later. I've gotten no further than reading through a bunch of documentation (none of it makes any sense to me) and the Listen app.

I went back on the "other keyboarding forum" for more help and was told to, read the documentation again.

?????

I did find one YouTube video with a person in a vaguely similar situation, but the video is 20 minutes long, he spends the first half talking about the difference between PS2 and Terminal Model Ms (!), and then it turns out his OS is Linux (I'm Windows 11).

So, just wondering if someone can walk me through remapping one key (without changing anything else) on a Soarer's, like I'm 5?

Thank you so much.

[depletedvespene]

I don't have a Model F AT keyboard here right now, so bare with me. I'll assume you know the basics of how to "burn" .sc files into a converter.

Get an empty .sc file (a zero-byte file), flash it with scaswr.bat to the converter. That will clear up everything, so there will be no remapping.

On the command prompt, run hid_listen. Press the A key and then press SysRq. Share a screenshot of the output here.

[depletedvespene]

Scratch that.

I ran hid_listen here. I pressed the keys A, Esc and Caps Lock Backspace.

HL.png (21.38 KiB) Viewed 17079 times

The codes with that 'd' and 'u' are what you want. In this case: 0x04, 0x29, 0x2A.

Go to the Soared docs page codes.html and see the HID codes.

HM.png (42.11 KiB) Viewed 17088 times

Burn the empty .sc file into the converter, then run hid_listen. Look at the "dnn" code produced by the SysRq key.

[dellmodelm]

>> I'll assume you know the basics of how to "burn" .sc files into a converter.

No, absolutely no idea how to do that or what that means. Also everything else posted is like reading Klingon. Thank you for the steps, but I'm not even at that level. I really do need something basic. Like... kindergarten level.

[Wolfi77W]

Ok so I assume you're lost and don't know where to begin, so i'm just gonna layout all the steps to remap/reprogram your soarer's converter.

Also keep in mind that I am using Windows 10, the process for Windows 11 should be the same though as far as I know.

First you're gonna have to download soarer's firmware. Since you bought the converter it probably uses firmware v1.10. If you want to verify what firmware your soarer's has you probably have to ask the seller.

Anyways once you figure out the firmware version you need, just download the zip file for that version. You can get it from here: viewtopic.php?f=7&t=2510&start=

Once you've downloaded and unpacked the zip file, open the "configs" folder. There you'll find sample sc files with examples of scripts that you can make for soarer's converter.

Configs Directory.jpg (100.25 KiB) Viewed 16980 times

Open the Empty.sc file with either notepad or notepad++. It has no code in it whatsoever so just copy over the code provided from the other forum.

Making SC File.jpg (103.58 KiB) Viewed 16980 times

You can save it with a different name if you want. Just make sure to have ".sc" extension and save as normal text file.

Now head over to the "tools" folder. Inside you'll see some compressed files.

Since you're using windows you need to unpack "Soarer_sctools_v1.1X_win32.zip" (X Denotes final digit of firmware version, 1.10, 1.11 etc).

Extract Tools.jpg (119.13 KiB) Viewed 16980 times

Inside the unpacked folder from tools, you'll see among the contents of the folder "scaswr.bat".

Applying Remap Onto Soarer's Converter.jpg (171.05 KiB) Viewed 16980 times

Just drag and drop the .sc file you created on scaswr.bat and a window will pop up, showing the progress as the bat file "burns" the .sc file into the converter.

And that should be it, hope this helps!

[Muirium]

That's more like it!

Soarer's config file format is pretty straightforward. Here's how to remap Caps Lock to Control, for example:

Code: Select all

remapblock
layer 0
	caps_lock	lctrl
endblock

Layer 0 is the default layer. If you're not interested in layers, this is the only one you'll ever need.

Control is written lctrl because I’m using the left Control key. rctrl is the other one. Simple stuff is really just as simple as that. Throw your remaps inside a remapblock and they'll just work.

Here's some more, straight out of my own config file:

Code: Select all

remapblock
layer 0
	caps_lock	lctrl		#	Shift PC modifiers around
	lctrl		lalt
	lalt		lgui
	ralt		rgui
	rctrl		ralt
	printscreen	mute		#	Media keys where I expect them
	scroll_lock	volume_down
	pause		volume_up
endblock

You add them, one per line, just like that. # signs are for (optional) comments. Save the text file, and throw it at scas then scwr.

As for getting it on the converter: Wolfi's instructions are good. I'd advise instead of dropping your config file on scaswr.bat—which won't explain your errors?—try running scas yourself if you're at all comfortable with the command line. It'll tell you where you went wrong (we all do, sometimes) and what line number.

For example, I save my config above into a simple text file called Mu.sc then run:

Code: Select all

scas Mu.sc Mu
scwr Mu

Scas "assembles" your config into a binary file. (You can use any file names you like: I just call my config files .sc and leave the binary versions without.) Scwr "writes" that binary to your converter hardware.

Anyway, once you get the hang of this: Soarer's really shines. It's immensely powerful and really pretty easy, once you're used to it, like a bike. I’m not very technical really and yet I came up with this monster over the course of a few years of occasional tweaking. Insane! But they all start with just a couple of lines like above.

[depletedvespene]

Another thing to note, while we're at it, is an important difference between Soarer's Converter and TMK/QMK/etc.:

On TMK, QMK et al, you need to define a full map of the keyboard, "compile" an entire firmware (those .hex files you'll see) and then flash the compiled firmware into the controller's chip.

On Soarer's Converter, the firmware is already there on the chip inside the cable, with a default mapping that's quite cunning (to the point where you mostly don't need to care whether your Model F or Model M keyboard is meant for PCs or terminals) and then you only need to specify what you actually want changed from the default. The .sc file is more of a configuration file (although it needs to be converted from a text file to a particular binary format [the .scb file]) than an actual firmware; this is why the .sc file you were sent has three "measly" lines: you are remapping only one key.

[Muirium]

Soarer's is pretty much the (command line driven) Vial of its day.

I think what would be extra cool, and way more self-explanatory, would be a modern rethink using modern (not 8-bit!) hardware with the same excellent defaults as Soarer but maybe an onboard web page for configuration. I’m not technical enough to know if this is a terrible idea! (Grumble grumble web stack?) But tweaking layouts on any host system with a web browser seems the ideal user experience to me.

[Muirium]

Totally happy, except I have one key (SYSREQ) that does not work. I downloaded something called HID_Listen and sure enough, the key is sending out a signal... but Windows is ignoring it.

Definitely follow Vespene's instructions about blanking out any current remaps on your converter. That way you start from fresh defaults.

I'd advice this handy little app—QMK Toolbox—over hid_util and indeed firmware flashing utilities. Its main body shows the text output you sometimes need: it's essentially running hid_util all the time it's open.

As for your missing key: show us what happens when you press it. It will be sending press and release codes for some key or another. Soarer's can remap it back to one you can use. You just need to know those codes, then look up their name.

[Wolfi77W]

I'd advise instead of dropping your config file on scaswr.bat—which won't explain your errors?—try running scas yourself if you're at all comfortable with the command line. It'll tell you where you went wrong (we all do, sometimes) and what line number.

My experience with soarer's has only been firmware v1.10 and with this version, dropping .sc file with mistakes on scaswr.bat does mention the line that has the error, though it doesn't explain what the error is. So the issue where it doesn't give any indications of any errors might be limited to older firmwares.

Error.jpg (74.97 KiB) Viewed 16822 times

Yeah Soarer's can be a bit of a learning curve, but when you learn to apply all that it has to offer it truly is awesome to have. I have also tried Tinkerboy's converter where remapping is easier since all we need is vial, but I think that at that point we're only limited to that one layout and remap until you reset and redo the remapping in vial. Here with soarer's we can have different remaps, macros etc depending on keyboard id and at or xt protocol all in one converter.

The only issue I have so far is more of a limitation with windows or hid listen where they tend to give the same id for multiple keyboards. Which is kinda limiting if you want to have different remaps for a few different keyboards. I mean I do have a few different soarer's converters so I configure one for some keyboards and the other for some others, but still it'd be nice if I can just use one soarer's converter for all my keyboards and the soarer's adjusts acccordingly based on the keyboard id.

[AndyJ]

Ok so I assume you're lost and don't know where to begin, so i'm just gonna layout all the steps to remap/reprogram your soarer's converter.

Thank you, Wolfi; I also found your explanation useful.

[Muirium]

The only issue I have so far is more of a limitation with windows or hid listen where they tend to give the same id for multiple keyboards. Which is kinda limiting if you want to have different remaps for a few different keyboards. I mean I do have a few different soarer's converters so I configure one for some keyboards and the other for some others, but still it'd be nice if I can just use one soarer's converter for all my keyboards and the soarer's adjusts acccordingly based on the keyboard id.

Many keyboards do in fact report the same ID. Off the top of my head: AB83 is often the one. Conditional logic based on that won't work well in many cases.

Fortunately, Soarer has higher level functions to allow you to work around things like that. Namely: ifselect. Selects are like ifset but where you control the value yourself. What I did with that was assign a key to toggle between Winkeyless and modern layouts: shuffling the modifiers around differently on each, the way I like them. So whenever the converter couldn't tell which physical format of board I had plugged in, and the mods were wrong, I'd hit that and the logic would adapt live for me.

Thanks for the tip re: scaswr.bat by the way. Been surely 30 years since I last touched scripting on PC, and that was just autoexec.bat and config.sys for games.

[Wolfi77W]

Thank you, Wolfi; I also found your explanation useful.

Anytime! Glad it was helpful!

Many keyboards do in fact report the same ID. Off the top of my head: AB83 is often the one. Conditional logic based on that won't work well in many cases.

Fortunately, Soarer has higher level functions to allow you to work around things like that. Namely: ifselect. Selects are like ifset but where you control the value yourself. What I did with that was assign a key to toggle between Winkeyless and modern layouts: shuffling the modifiers around differently on each, the way I like them. So whenever the converter couldn't tell which physical format of board I had plugged in, and the mods were wrong, I'd hit that and the logic would adapt live for me.

Ahh so the issue with the keyboard id is more from the keyboard itself lol.

Thanks for suggesting ifselect, didn't read too much into it on the documentation until you suggested it and yes it' sounds like an excellent way to be able to use one soarer's across a wide variety of boards with different layouts. I'll try it out when I feel like going through my keyboard collection lol.

[depletedvespene]

Fortunately, Soarer has higher level functions to allow you to work around things like that. Namely: ifselect. Selects are like ifset but where you control the value yourself. What I did with that was assign a key to toggle between Winkeyless and modern layouts: shuffling the modifiers around differently on each, the way I like them. So whenever the converter couldn't tell which physical format of board I had plugged in, and the mods were wrong, I'd hit that and the logic would adapt live for me.

I use ifselect for other stuff — with a keystroke I can toggle the regular numpad and the hexapad (to write out hex numbers) and I can toggle the CONSTANT_NAMES_MODE, WHERE_I_WRITE_LIKE_THIS without touching the Shift key and the space bar producing the underscore.

There is indeed a LOT out useful stuff that can be done with Soarer's converter's current capabilities (some of it quite more easily than QMK and the lot).

[hellothere]

Saved this thread at archive.org and updated the "Internal Soarer's Converter from scratch (beginner friendly)" thread with a link here.

[dellmodelm]

Well... I finally got it to work. I want to thank Wolfi77W, Muirium and all of you for your help. I really, really appreciate it. I don't think I could have found this "level" (detail) of help on any other forum. Thank you all so much!