(Thank you so much to https://twitter.com/eddible for this guide!)
The KC60 and Satan boards, handily, have seen a lot of support from the community and so flashing them is a fairly easy process. This guide will go through flashing the QMK firmware to either a KC60 or Satan board. I’ve used QMK as it offers the most flexibility and options. I’ve tried to make the guide as clear as possible so that everyone can follow along but please ask questions in the comments and I’ll do my best to answer them.
Setting up the TKG-Toolkit
First thing you need to do is download the TKG-Toolkit. This is a command line tool (don’t worry, it’s really easy to use) that allows you to flash your board with your firmware.
If you’re comfortable with Git, you can clone the repository:
git clone https://github.com/kairyu/tkg-toolkit
If you’re not familiar with Git or using the command line, you can simply download the zip file:
Get the zip file extracted and take a quick peek inside. You should see a few folders:
As you’ve probably already guessed, these folders contain OS-specific versions of the toolkit.
I’m using a Mac so I use the ‘osx’ folder. Scroll below the image to find the Windows instructions. Unlike on Windows, the script files in the ‘osx’ folder are not executable by default (at least they weren’t for me) so we need to do that first. I’d also assume this is the same for Linux users.
- Open a Terminal window (Easiest way is to open Spotlight, and just search for Terminal. Otherwise it is located in your Applications folder, in the Utilities folder down the bottom.
- We need to change into the directory where the TKG-Toolkit files are located. The ‘osx’ folder we looked at earlier.
- In your terminal window type the letters ‘cd’ (without the apostrophes) and a space (don’t hit return just yet)
- Then, in your Finder window, navigate to the folder containing the TKG-Toolkit you extracted earlier (most likely in your Downloads folder.)
- Open the folder, then drag and drop the ‘osx’ folder into the Terminal window.
- You’ll see the full folder path populate in the Terminal window. Hit return and you’ll have cd’d (changed directory) to the TKG-Toolkit OSX folder.
- If you now type ‘ls’ and hit return, you should see all the contents of the ‘osx’ folder listed in the Terminal window.
- Now type, again without the apostrophes, ‘chmod a+x *.sh’
- This command makes all the files in the folder that end in .sh executable so we can run them as applications. The asterisk is a wildcard to do all the sh files in one go rather than separately.
- Don’t close the terminal window, you’ll need it in the next step.
If you’re on Windows, you won’t need to do the above, the .bat files in the Windows folder should execute when double clicked.
We now need to tell TKG-Toolkit a bit about our board. In Windows, if you double click setup.bat, you should find a command prompt will pop up. For OSX and Linux users, in the terminal window we were using before (so we’re still in the osx/linux folder) we just type ‘./setup.sh’ and hit return.
- For the Satan board, we need to select option 2, RevCHN (Revision China). If you’re following this guide for a KC60, you need to select option 3, GHPad (Thanks to Keychatter for that info).
- Make your choice then hit return. It will ask if you wish to reselect, the default is no (as shown by the capital N) so just hit return
- For the next choice, we want to keep with the Default firmware. It should default to 1, if not type 1 and then hit return.
- For the bootloader, again, we want to select 1 (the atmel_dfu) and hit return.
You should receive confirmation that your config has been saved and it’ll either exit or just return you to the command prompt.
At this point, we have told TKG-Toolkit about our board so that it knows what to do when it comes to flashing the firmware. For now, we can stop here as we need to prepare some firmware to run on it.
A brief look at the firmware
The QMK firmware is certainly the most difficult part of creating your board. However, don’t let that put you off, it just takes a bit of reading, a decent starting point and you’ll understand how it works.
Best thing to do is get over to this github page:
This isn’t the original version of the QMK firmware, but a fork by a0-c that includes support for the Satan PCB as well as a very in-depth keymap.
At the top, we can see the folder structure of the firmware:
and a few other files, including the all important README.md. Github automatically picks up on these and displays it so as you scroll down, you’ll see the incredibly expansive README.md file which explains the ins and outs of the QMK firmware.
For now, click into the ‘keyboard’ folder, then again into the Satan folder then once more into the folder called ‘keymaps’
Assuming nothing has changed since I wrote this, there should be a single file called keymap_yang.c. Click it and it’ll load.
Don’t worry too much about the various lines of code, but take note of the way the document is laid out. There are visual diagrams of each layer (the human-readable ones are commented out so they’re just there purely to make it easier for you to understand) then directly below, is the code that generates your keymap. I encourage you to read through the file and notice how things are linked together, and how the FN layers are being defined. If you’re using an ANSI layout, you shouldn’t need to make any changes to this file unless you have specific customisations. For everyone else, it will need modifying. How to modify it is beyond the scope of this guide, as mentioned previously, read the README.md file to understand all the options you have available.
For the sake of testing your board, I’d stick with the default keymap for now, then you can spend time later learning how to customise it.
Before we go to the next section, you’re going to want to download the firmware. Once the zip file has downloaded, get it extracted somewhere easy to get to.
Setting up a build environment
The keymap file is essentially a set of instructions, and we need to feed these instructions into a compiler to produce the ‘hex’ file that is actually flashed to your keyboard. In order to do this, we need a build environment to compile the script. Luckily, the QMK firmware has some great instructions on how to do this:
I’ve taken the liberty of testing the Windows instructions and they work without issue, just download what they say and install them as explained. For Mac OS you can use homebrew to install the needed files. You’ll notice a section about using something called a Vagrantfile to make compiling more simple. I’ve tried and it isn’t worth the effort, it’s far quicker and easier to use the other methods.
Build the firmware
Once you have your build environment sorted (that is, you’ve reached the end of the instructions at the above link), we can have a go at building your firmware.
- You’ll need to be back at either the command prompt on Windows (search for cmd and it’ll appear) or the Terminal in Mac OS (either use Spotlight or it’s in your Applications folder under Utilities)
- Type ‘cd’ then a space into the Terminal/Command prompt.
- Open up Finder/Windows Explorer and navigate to the folder you extracted the firmware to earlier.
- Open ‘keyboard’
- Now, if you place the Finder/Explorer window next to your Terminal/Command Prompt (it should still have the ‘cd ‘ line typed in, you can just drag and drop the appropriate folder. For Satan users, drag the ‘satan’ folder onto the Terminal/Command Prompt. KC60 users, you’ll want the kc60_v2 folder instead.
- Hit return.
- Type ‘make’ and hit return again. All being well, you won’t get any errors and your firmware will be ready to be flashed to your board.
Still with me? It’s finally time to flash your board!
- If you haven’t already, get your board plugged in with a mini USB cable
- On Mac OS, you’ll want to follow the instructions from earlier to ‘cd’ into the ‘osx’ folder of TKG-Toolkit. On Windows, you’ll want to open the ‘windows’ folder in explorer.
- Once you’ve cd’d in, type ./reflash and hit the space bar – but don’t hit return.
- In another finder window, navigate to the satan folder we dragged across in the previous step when you typed ‘make’. Open it up, you should see a file called satan.hex. You need to drag and drop it onto the Terminal window where you’ve typed ./reflash.sh – then hit return.
- On Windows, you’ll need to open another Explorer window, navigate to the folder you dragged across before before you typed Make, and find the file ending in .hex. You’ll then want to drag and drop this on top of the reflash.bat file in the TKG-Toolkit Windows folder.
- TKG-Toolkit will ask you to confirm what you’re doing. Say yes!
- It will then wait for the boot loader of the keyboard. Your PCB has a small button it, press and hold that button for about 7 seconds. Let go, and it should start flashing the board.
The above process of running the make command and flashing the board will need to happen whenever you make an edit to the keymap file so be attentive to the process.