Soarer's 101-#2: Remapping & Macros

In this second part of my Soarer's 101 guide, I will be describing how you can utilise Soarer's Converter's remapping and macro functionality to allow you to get the most of your vintage keyboard.

As a quick recap, remapping allows you to make a given key act like another key and macro support allows you to make a given key perform multiple keypresses/key events to form a more complex function. As Soarer's is independent of any host computers, you have complete control over every key and thus you can customise to your heart's content!

Prep

Before we hit the ground running, let me introduce to you some basic concepts that you should know about before writing your Soarer's code file (especially if you're unfamiliar with any coding terms).

File type

Firstly, we of course need to create a file for our code. The file type for Soarer's Converter code language is .sc, so just create a blank file with .sc at the end of the file name with your favourite plain-text capable editor (such as Notepad, gedit, etc.). Note: I will be referring to these files as either code files or config files throughout this guide.

Case sensitivity

Soarer's code is case insensitive, so you can write your files in all lowercase, all uppercase, or a mixture of the two.

Block structures

If you're familiar with defining functions in computer programming (especially subroutines in Visual Basic), this concept is something you've come across before. Simply put, the things you want to do with remapping and macros are grouped together in a structure that has a start and end declaration. For this part of the guide, you'll get familiar with the remapblock and the macroblock structures, which look like:

When you want to add any instructions to your Soarer's code, more often than not, they will need to be inside those (relevant) blocks. You can define multiple blocks of the same type, which can be especially useful for organising large files.

Code comments

As with most programming languages, you can leave descriptions of what your code does with a comment declaration (ie, a line of code that is ignored by a compiler). In the case of Soarer's code, a comment is denoted with a # (number sign) symbol at the start of the line. Comments will be useful for describing what your code does, for example:

Typically, comments are useful for describing what parts of your code are doing for future reference or for aiding future readers you choose the share the code with. Another common commenting practice is making a multi-line header (as shown on the first two lines of the example above) at the top of the code to briefly describe what the entire code is for and to specify your authorship of the file.

Including separate files

If you plan to reuse some code across multiple config files for different keyboards, using the include command is a useful thing to remember. With it, you can put reusable code in its own .sc file and then use that command to indicate that you want that code pasted in at the command's position when the code is compiling.

You can include as many files as you like, which also makes this a useful tool for organising code too. Another benefit when using this practice for reusable code across multiple configs is that you only need to make tweaks or rewrites to such code once from its own file, instead of needing to repeat those changes in every separate keyboard config file you may have.

Remapping

Remaps are a very basic but useful thing to do since they can let you change your layout or add basic functionality that your operating system as standard wouldn't allow or recognise. Continuing with the scenario I mentioned in the first instalment, I will be remapping the key that is labelled SysRq/Attn on my 122-key Model M to function as an Esc key. Since I now know that key returns the scancode EXTRA_F2:

It's honestly that simple! For each line inside a remap block, you just need to first specify the key you want to replace and then the key it should behave as. You can indent and space the two words however you like - I personally do a single tab indentation and then a three-tab space between the two scancodes so that any scancode no matter how long should be uniformly spaced.

Now with that understood, it's time to play around a little bit. This is what I came up with for my M122's 10-key function bank:

Macros

Many crave having keys that can do more than one thing when you press them. Whether its for automating the input of usernames, addresses, letter format, inputting commonly used code structures on the fly or automating moves for the games you play, macros can automate a lot of repetitive tasks for you. Soarer's can indeed pull this off with the use of the macroblock and macro structures. These macro structures contain the commands to run when a certain key is triggered, and multiple macros can be sorted within a macroblock. Each macro will need to be told what key it should bind do, which is denoted by using the name of a key one space after the writing "macro". Like this:

Inside each macro, you can declare a few types of commands. The ones we're checking out are PRESS, MAKE and BREAK. Starting with PRESS, writing this command followed by the name of a key will simply press that key as if you physically pressed it yourself. You can input as many of these commands as you like, so the following would output "hello world" minus the quotes:

As we've said before, Soarer's code is case insensitive, so you may notice that despite the above letters being uppercase, the output was lowercase unless you have caps lock on. To make an output print in a specific case, you will also need to trigger shift as well, which you can do via MAKE and BREAK commands. To an OS, every keypress is seen as two events; a key down and a key up. When you use shift to make a given letter uppercase, the act of holding shift only triggers the key down event and thus lets the OS know that you want to combine keys. Thus, MAKE triggers an individual key down event and BREAK triggers an individual key up event to allow you to combine key presses. So, to get "Hello World" as the output of our macro, you can do this:

You can have multiple MAKES and BREAKS after each other too, so writing a macro to automate Ctrl + Alt + Delete is a possibility:

So, you now know the basic building blocks for your Soarer's macros. However, now let's explore some more advanced triggering options for macros than just simply the name of the key it should be bound to. After stating what key the macro should be bound to, you can specify the names of the modifier keys that should be held down to trigger the command. You use the same names as their keys (like LCTRL, etc.) or you can remove the L or R at the start (eg, CTRL) to specify that both left and right versions of the key should be triggers. So, say I want a macro that only works when LSHIFT is held down, it would look like this:

Note that the macro will still run if you hold any other modifiers down. If you want a macro to run only when a given modifier isn't held down, you can add a '-' symbol in front of the key's name. For example, if I want that same macro as before but want to stop it working if any of the control keys are held down:

The last thing to look out for when using trigger conditions is that you need to order them a certain way if you're wanting to set up different macros for the same key. When you press a key that has multiple macros defined for it, Soarer's will only run the first one it finds that has its triggers matched. As such, the general rule of thumb is that macros that have more trigger conditions than others should be placed above the ones with fewer. For example, if we want a key that has three different macros depending on various conditions:

And that's pretty much it for the basics of Soarer's code. Remaps and macros as described here should allow you to implement quite a bit of functionality for your vintage keyboards. However, there's indeed more you can do. Soarer's 101-#3 (due Q1 2022) will describe how to use layers and ifselect commands to further enhance the utility of your keyboard.