Free Standard Shipping in the US on orders over $99

Using Vial to Program Your Macro Pad

Apr 12, 20236228 VIEWS

Okay, so you got a new macro pad, it’s working fine, but now you want to customize the keymap/layout a bit. Where do you even start?

Image credit: @HoffmanMyster

Remapping Keys “Mapping” refers to the relational ‘map’ between the physical keys on a keyboard and the signals sent to the computer or device when a key or key combination is pressed. For most non-mechanical keyboards, this mapping is rigid and cannot be modified. Custom keyboards and most popular mechanical keyboards can be remapped using keymapping software—sometimes proprietary, especially for the latter category of brands like Logitech or Razer. We are more interested in custom boards and other offerings that do support more keymapping customization. Arguably the “default” and most common software solution for custom keymapping is QMK, with QMK Toolbox as their software interface to flash custom mappings. QMK is incredibly powerful, but it does have two fairly major drawbacks—it’s not newcomer-friendly, and it requires re-flashing the firmware to make any changes. There is no GUI; all custom mapping is done in a text editor, and installation is carried out through the terminal. If you want to tinker around and see how a handful of configurations work, you’ll be going through the remap and flash process each time you make a change. Great for power users and those familiar with these processes, not so much for the average user. Remapping With Visuals, on the Fly For everyone else, there are two main options aside from using QMK and QMK Toolbox. VIA and Vial offer fully-fledged graphical interfaces to remap compatible keyboards, with changes applied immediately when adjusted in the software. This makes for a very powerful tool for anyone curious to try different layouts or frequent little tweaks to find the perfect settings for them. Between the two options available, VIA is currently the more prevalent choice, so you’ve probably seen that name floating around discussions online. Vial operates very similarly to VIA, and can effectively be used interchangeably (more on Download VIA Definitions below). VIA has a more elegant interface and is probably more friendly to the novice user. Recently(ish), however, VIA became a Chrome webapp-only application, which caused concern for some users about security—ultimately it is up to the user to make the call here. I personally use Vial, so the remainder of this article will walk through the process using Vial. (Note that VIA and Vial protocols are compatible with each other, possibly excepting encoders/knobs, so this is not a permanent decision to be made between the two programs)

Using Vial After downloading and installing Vial, you can get started almost immediately. In many cases, the keyboard you’re trying to use will automatically be recognized by Vial and can be remapped without any additional steps. Download VIA Definitions In some cases, the keyboard will have a VIA-compatible firmware installed that isn’t natively recognized by Vial. If your keyboard doesn’t show up in Vial when you plug it in, the software will prompt you to Download VIA Definitions in the File menu “in order to enable support for VIA keyboards”.

Sideload VIA JSON If your keyboard still is not recognized after loading the VIA definitions (and you know that it is compatible with VIA—if not, you will need to flash a compatible firmware first), then you can manually sideload the VIA JSON file from the File menu -> Sideload VIA JSON. json files are the link between keyboard and software; they inform VIA and Vial of the matrix of keys as it exists physically on the keyboard, and they also define a starting point for keymapping of those keys. Without this file and information, the software has no idea how many keys the keyboard has or what each of them should be doing.

Remapping with Vial After the device is auto-detected or the .json file is sideloaded, modifications can be made to the keymapping using the Vial interface and all changes will be applied immediately and saved to the device. After closing the software the custom keymapping will be retained on the device, even after unplugging and replugging. The one thing to keep in mind is that if you had to sideload the .json file in order to remap, that .json file will need to be sideloaded every time you want to remap the keyboard using Vial (not every time you use it, only if you want to change the keymap). Keep the file around and handy for when that time comes. (Note that this is the case for using VIA in addition to Vial if sideloading is needed) Programming the Megalodon Macro Knob Pad The Macro Knob Pad, our example device for this article, falls into the last category described above—it is compatible with VIA, but does not exist in the repository to be automatically detected upon connection. We will need to sideload the VIA .json file into Vial in order to remap the keys and knob. Sideload the JSON File The .json file used for the Macro Knob Pad can be found at keebmonkey’s wiki site, direct link here. After sideloading the .json file for the macro pad, we see the layout below. Vial always defaults to displaying the “Layer 0” mapping, which is the default layer. For most keyboards it will be fairly obvious which positions in Vial correspond to which physical keys, but some of the odd layout boards or small macro pads can be a little less clear (all four keys and the knob are shown in a row here, despite the knob actually being in the “second row” of the pad). Default Mapping Layer 0 default mapping for the Macro Knob Pad is shown below:

[KC = Knob Click, KR = Knob Right, KL = Knob Left] Key code “MO(1)” is the “function” key that enables the second layer when pressed. “MO” means Momentary, and “(1)” means it takes you to Layer 1 (the second layer) when pressed. If desired, you could swap this with a Toggle function (“TG(1)”) or a variety of other functions found in the “Layers” tab of the Vial interface below the device layout. Because the function key is a momentary function key, Layer 1 cannot have any key defined for that position (the furthest right key on the macro pad). This “transparent” or blank keymap is shown by the down-facing triangle in the Layer 1 keymapping. However, upon close inspection of the Layer 1 map below, we see “Hue +” in the Key 4 position… For some reason, Layer 1 is showing our keys in a different position than Layer 0 and the physical translation to our device. The default mapping of Layer 1 for the Macro Knob Pad is shown below:

I have no idea why Layer 1 is jumbled around like this, nor why the default knob behavior is to increase volume when turning left if holding the function key. The jumbling of keys might be something with Vial (the .json only defines the key positions, it does not define the positions per layer), but the odd default mapping is from the manufacturer. Your guess is as good as mine. Regardless of the reasoning—coming across inconsistencies like this can be frustrating and confusing to newcomers and veterans alike, and figuring it out requires a resource or trial and error. Changing the Keymapping To change the keymapping of the macro pad (or any device), first click on the key position in the device map view in the top portion of the window. This tells the program which key you want to remap. Then, click the new key code in the code selection window at the bottom of the screen to assign a new code to the key. This could be a simple letter or modifier, or something more complicated like accessing another layer, media controls, mouse bindings, or macros. In the below example, you can see that I remapped the knob to function as a mouse wheel, scrolling down when turned right and scrolling up when turned left. Pretty useless in practice, but my audio interface doesn’t let the computer control volume, so I was playing around with some novelty configurations.

Side Note—Programming the Megalodon Triple Knob Macro Pad I won’t be going into detail on this here, but wanted to share an update from Keebmonkey regarding the Megalodon Triple Knob Macro Pad. Keebmonkey posted this guide with instructions to flash an updated firmware to the triple knob macro pad as well as a guide by Keebmonkey Discord member epid#8098 bringing native Vial support (no sideloading necessary) to the macro pad. Both resources are worth looking into if you have the triple knob macro pad and want to enjoy the latest and greatest firmware options available. Other Uses The sky is really the limit with macros and complicated keymapping functionality. You could program a macro pad as an editing interface, using knobs to scroll a timeline and keys to cut footage with the blade tool, etc. What configurations do you use with your macro pads, knobs, or other keys? Is there anything missing from this guide that could use some more attention? Let us know in the comments!

100% upvoted

6.2K

Sort by: Newest

Apr 13, 2023

Hot damn! You solved at least four of my setup frustrations of my 38% Megalodon in one article than I've found in an hour of Googling (slight exaggeration, but you get my point ;) )

May 17, 2023

Partial update for now: the firmware updates are still in process of being added to VIA, so no formal communication has happened so far. However, there have been some updates to the Keebmonkey wiki page which detail a lot of that progress and the current status; I haven't tested any of the new firmwares out yet myself, but it's good to see movement on things like this. AFAIK Keebmonkey will share a larger update as soon as everything works its way through VIA for approvals.