Soarer's page updates

[micmil]

The Soarer's Converter page on the wiki is woefully inadequate for something that's so intrinsic to the frippery around here, so I'm rewiring it. I don't mind adding a few things here and there but for a massive rewrite (or, given the current state of the page, WRITE) like this I want to get community feedback before committing anything to the wiki. Mainly because my working knowledge of Soarer's is minimal. All I have so far is a few paragraphs giving a short overview of what it is and a cursory explanation of usage.

OVERVIEW
Soarer's Converter is a closed-source converter firmware for boards based on ATmega32u4, AT90USB1286, AT90USB646, and ATmega16U4 microcontrollers. It is one of the primary tools for easily adapting XT, AT, PS/2, and terminal connections to USB. Commercial adapters utilizing Soarer's firmware are readily available for all of these connectors. The firmware includes a number of advanced features such as remapping, macros, and layers.

The project is no longer in development following Soarer's departure from the community. Despite this it has maintained, and even grown, its popularity due to the ease of use and ready availability of premade hardware. Soarer himself described the last release, v1.12, as "pretty much feature complete." (1)

USAGE
Using Soarer's Converter is typically simpler than using other firmware such as QMK or TMK. While those general-purpose firmwares are far more flexible, Soarer's Converter focuses on specific protocols and has built-in mappings that will work with most keyboards that adhere to the standards of each out of the box. The firmware is first flashed to the hardware using the appropriate software (PJRC's Teensy Loader, avrdude, or similar) before configuration files can be loaded. Most, if not all, commercial converters come preloaded with the firmware. The user then creates a configuration file based on the built-in command set

Soarer created a variety of command line tools to simplify the process of assembling and loading configuration files onto the hardware.

*THIS WILL BE A TABLE I AM TOO LAZY TO MAKE RIGHT NOW*
scas - Assembles text configuration files into binary
scids - Dissasembler for binary configuration files
scwr - Writes the binary configuration file to the converter
scrd - Reads the binary configuration file from the converter
scboot - Jumps to the bootloader, used when flashing new firmware
scinfo - Displays version and memory information
scaswr - A Windows-only batch file that combines the functionality of scas and scwr, assembling and uploading the configuration file in one step

Once the firmware is on the hardware, the user then creates a text file with the desired configuration. This can be anything from simply swapping a couple of keys (switching the location of CTRL and CAPS LOCK as in a Unix layout, for example) to complex configurations with multiple layers and macros. Once the desired configuration is created the text file is then converted to a binary file using scas. This binary file is then written to the converter using scwr. On Windows systems the user can simply drag and drop the text configuration file onto the scaswr batch file to compile and upload the binary automatically.

The plan, for now, is to have the main [wiki]Soarer's Converter[/wiki] page as the general overview and description of usage then break out into one page for the tools and another for configuration. If you have any suggestions or comments, bring them on. This is all first-pass rough draft stuff and is by no means anywhere near complete.

[depletedvespene]

Count me in!

[Muirium]

Instead of completeness, I’d prioritise some quick how tos. A lot of people are just fine with a Soarer running no config at all, simply default keymap. Tell them how and just tease the good stuff at the end, when they want it.

Another common use is to do some very simple remapping, especially mods. No need to explain layers let alone macros to folk who just want to move around some keys.

Perhaps I should write the bit about selects. Took me years to understand those. Above even macros on the hierarchy. I know macros pretty solid too (and I miss them most of all on QMK!) if you find you need me.

[micmil]

Instead of completeness, I’d prioritise some quick how tos. A lot of people are just fine with a Soarer running no config at all, simply default keymap. Tell them how and just tease the good stuff at the end, when they want it.

Another common use is to do some very simple remapping, especially mods. No need to explain layers let alone macros to folk who just want to move around some keys.

Perhaps I should write the bit about selects. Took me years to understand those. Above even macros on the hierarchy. I know macros pretty solid too (and I miss them most of all on QMK!) if you find you need me.

This is what I'm intending to do. The configuration page will absolutely start with basic functionality and work up from there, with a very clear delineation between "basic" and "advanced" features to make it clear that you don't need to know all of this to get it working. Basically, the exact opposite of the existing docs that start with something it tells you up front you'll likely never need to use (force).

If you could write even a cursory explanation of selects that would be amazing. I have literally no idea WTF they are. It kind of sounds like they're... permanent layers that change everything? Maybe? Like loading in a different configuration on the fly? The docs tell you how to use it without even explaining what it is. I mean...

Groups of settings can be toggled by using the ifselect command and defining remaps or macros that output the SELECT_0 to SELECT_7 codes.

There's only like nine different ways to understand that depending on your definition of groups, settings, toggle, defining, remaps, macros, and to.

[diazel]

This excites me. I got myself a Soarers for my F122 and M122 but to date I have yet to figure out how to modify it to remap some keys. I've screen shots of people doing it but I haven't a clue what the full "workflow" is, if you will. Since it mostly worked out of the box, not a huge deal to me but would love to make my arrow cluster work (only up and down arrows register proper arrow keys strikes) and maybe even create a few other convenience keys.

Thanks for the effort!