Qmk Configurator Json To Keymap.c
Stephaine Zitzow
I made an app that converts the .json file exported from the QMK configurator into the code for the keymap.c file in your QMK settings. This is so you can use the configurator to create your layout but then add additional features to your keymap before compiling it.
The first step to creating a keymap is going to be identifying the keyboard it is for. I am going to use the 1up60hse, which does make things just slightly more complicated than the NK65. To explain what I mean by that, you need to understand the structure within the "qmk_firmware" folder, at least mildly. I only understand it mildly, but it is enough to know that all of the QMK supporting keyboards are found in the "keyboards" directory. That is hardly surprising, but you may notice that while there is an NK65 folder, and within it are various files necessary for compiling its firmware, but there is not one for the 1up60hse, or rather not on that level.
1Up Keyboards has all of its devices collected in a 1upkeyboards folder, so you will need to enter it to find the 1up60hse folder, and then the keymaps beneath it. This is important because QMK needs to be told to look inside of the 1upkeyboards folder in order to find the keymaps.
Once inside the 1up60hse folder, you will see a number of files that, largely I would say you do not want to touch. You can definitely open them up in a text editor and have a look, but do not edit them because you could really break something if you do. Fortunately you are able to override the contents of these files with files in the keymap folders, which are under the "keymaps" folder.
There should be three folders there to begin with, named "default," "via," and "vosechu" as these are the three in the QMK GitHub repository. That third one is someone's personal keymap that was added, so we do not need to be concerned with it, but the other two are of interest.
I have mentioned a few times that as an exercise I have been trying to maintain custom keymaps that will reflect the changes I have made in VIA to the keyboards. My intention here is to go through such an exercise in this article first. After that I will cover adding the OBS Studio hotkeys as something a little better than hotkeys directly written into the keymap, and then how to enable the KC_LOCK feature. Unfortunately VIA does not support KC_LOCK, so we will lose that, but the process of enabling this feature is something I believe worth covering. Lastly I will cover how to set up Lighting Layers, which will engage the underglow RGB LEDs based on the currently active layer as well as the status of Caps Lock. This last customization is easily the most complicated of these to do, especially as some of the others will probably just take a short paragraph or two. Still, the Lighting Layers customization is clear enough in how it works, and I will try to explain it clearly as well, that it can still be approachable.
Something true for each of those customizations, is that you need to make a new keymap first, and there are a couple easy ways of doing that. The first way will be to just make a copy of one of the already present keymap folders. If your intention is to keep VIA support, I would suggest copying the "via" folder. You will want to name the folder something readily identifiable, and preferably without spaces in it, such as "via_custom." The second method is to have QMK create it through the Linux terminal:
This command works by copying the "default" keymap, which does not support VIA, so you will need to enable that. That is very easy to do, but you can always just copy the contents of the "via" folder into this one too. (At first I was having some issues with just copying a keymap folder, but it occurs to me now I may have just been writing the name incorrectly when trying to compile it. I use dashes and underscores and sometimes switch them accidentally.)
However you create the new keymap, I strongly recommend going to its folder with Explorer in Windows, so you do not need to rely on the Linux terminal to manage the files, and also that way you can use your text editor of choice to manipulate the files. Inside the folder will be three files: keymap.c; config.h; and readme.md. The "readme.md" file describes the keymap and links to an image of the default keymap as well, so in a GitHub repository people know a little more about this, but for our purposes, it is irrelevant. The "keymap.c" file is what sets the mapping of keys on a keyboard, and it can do other things too, so we will be working with it. The "config.h" file is fairly powerful and while I will cover things you can do with it, for now it can be left alone.
To enable VIA support we need to create a "rules.mk" file (or copy it from the "via" folder), which controls build options for the keymap, such as enabling support for VIA as well as mouse keys, NKRO, backlighting, RGB lighting, and more. The "rules.mk" and "config.h" files in the keymap folders act to override the default versions set in the keyboard's folder, so the "1upkeyboards/1up60hse" folder in this case. Examining those is not a bad idea eventually, but is not needed for now.
It really is that easy, at least once the work necessary behind this single line has been done, which it has for the 1up60hse. That work is beyond what I have tried and what I would attempt to share if I had attempted it. The file in the "via" folder also contains:
I am unsure of why these additional lines are there, especially as mouse keys are already disabled according to the default rules, but I have a thought. Enabling VIA support increases the size of the firmware, and disabling features, like mouse keys, decreases the size of the firmware. Looking at the documentation for the "rules.mk" file, it says this is Link Time Optimization and while it does disable some legacy features, it also reduces the size of the compiled firmware. My guess is those other rules are to ensure there is enough space for the firmware, and indeed, the firmware file with just the keymap changes I made is 98% the capacity of the controller, leaving just 528 bytes free (QMK knows this and reports it as a warning).
Now when the keymap is compiled, there should be VIA support, so we can move on to changing the "keymap.c" file. There are two approaches to this, and while both work fine, I prefer one to the other. My lesser preference is to visit the QMK Configurator and build the keymap you want there. Because this still very useful tool does not allow for various advanced functions, like changing compile options, we cannot just have it compile the firmware and maintain VIA support. However, we can use the json2c feature of QMK to convert a configurator's keymap into a proper QMK keymap.
To do this, first make the keymap and then export it. Using a name without spaces will make it easier to work within in the Linux terminal, but quoting it should also work. I will assume it is "via_custom," like the keymap name. Place the JSON file somewhere the Linux terminal can reach, such as in the "keymaps" folder, like this:
It is necessary for QMK to know where to find the JSON file, so I wrote this example assuming you are still in your user directory, but if you change directories to the "keymaps" folder, the command is much shorter:
The "-o" flag is to tell QMK where to save the output for the conversion, and you will want to do that. Without using the output flag, QMK will just print out the conversion result in the terminal. If you wished, you could have the output named "keymap.c," allowing you to use it directly, once it is in the "via_custom" folder, but there is a reason I would recommend against this, and it is something you can easily see by looking at the keymap file already there (from either the "default" or "via" folder).
The structure of the keymap files involves more C than I really understand, but simply put each keymap is just a list of keycodes or commands, and that is all QMK produces from the conversion. Looking at the pre-existing keymaps you will see there is an image of the keyboard printed out as comments for the first three keymaps. Additionally, the keymaps are not just a straight list of keycodes, but have line breaks matching the change in rows on the keyboard. Both of these things have no impact on QMK but do make it much easier to find and change specific keys, which is what we will be doing next. This is also why my preference is not to use json2c but to directly edit the "keymap.c" file.
By the way, QMK does not care about spaces in the list of keycodes, so you can also use those to align the keycodes to match the layout of the physical keyboard. This has not be done for the 1up60hse, but was for the NK65.
The next step is to edit the keymap, and while I do not recommend using json2c, this is something the QMK Configurator can still help with. If you mouse over a keycode or command in the configurator, you will get a pop-up along the bottom of the screen giving you the QMK code. This way you can know what to type into the correct place.
If you started with the "default" keymap, then there is one more step to do. By default VIA has a maximum of four layers, and if not all four layers are assigned in the firmware to start with, it gets confused. One simple solution is to copy the fourth layer from the "via" folder's keymap file, but another is to just make it fresh in your newly edited keymap.
Hopefully you have noticed the lists of keycodes are set equal to a number surrounded by brackets. This number corresponds to the layer, so you can take one of the other layers, copy it, and change the number to 3 and will be good to go. As there is no means to access this fourth layer, it does not matter what the keycodes are, but taking the time to set them all to "KC_TRNS" for transparent keys is not a bad idea. Just make sure you have all 61 keys assigned.
With that, you are basically done. Provided there are no typos, you can compile the firmware and after you flash it you will be able to see this keymap in VIA and edit it, if you wish to. Compiling the firmware is quite easy as you just need to tell QMK the keyboard and keymap, like this:
64591212e2