FAK-Firmware Github Guide
Date: 17.05.2024
What the FAK?
FAK is a Keyboard-Firmware by semickolon which runs on the super low cost CH55x series of chips.
There is also Discord server if you need more in depth help.
The Miao is a controller with this chip, designed by kilipan.
A good start for customizing your keymap is this example FAK Macropad config
QASS
You can find the config files for the QASS at Technofrikus Github
Guide
How to create your own Firmware via Github Codespaces. This is also described here, but I had some small problems to get it going. Thats why I made this guide.
FAK also can be installed on your local machine, the easier way is to use the nix packetmanager for that, which is a whole thing and creates a partition on your harddrive (at least on macOS) and cant be easily uninstalled (macOS). Read more about nix in general and on macOS here. You can also install it without nix, but thats a little more complicated and I havent tried it. Thats why I am using the other officially supported way: Github Codespaces.
0. How to create a keymap and keyboard
This is not the scope of this guide. Please check out the official Getting started guide
1. Fork Repo
Go to the offical repo and fork the official repo to your own Github account.
2. Create Codespace
Go to Github Codespaces. This is already the URL to create a codespace.
As the repository, select the just cloned fak-config (or however you named it). Leave everything else as it is. Create Codespace. This will take a while.
Then all the software will be installed automatically. Like in this screenshot. If this is not happening, just write nix develop into the terminal inside the codespace.
To test if everything is setup correctly, just type in fak. If it says unknown command then type the command one line above in. If it tells you how to use fak, then everything is fine.
Money
Running a codespace can cost money, but using it just a bit is free. Please check the current charges before using it too much.
3. Compiling
To test if everything works, type in:
fak compile -kb zilpzalp -km default
This compiles the firmware for the keyboard named zilpzalp with the keymap named default. It is the same syntax as QMK uses.
After some seconds the last line in the terminal should be:
Firmware copied to: .fak_cache/zilpzalp.default.central.ihx
You can then proceed to download the firmware:
Notes regarding compilation and download from semickolon himself:
.fak_cache is in the .gitignore so pushing it wouldn't push firmware files in the repo. But if you have Actions enabled then pushing triggers a compilation of all the keymaps. Then you'll get your firmware files in the automated release!
Though if you're iterating on your keymap, this process is the slowest. I'd recommend downloading the .ihx files in the codespace then flashing it on your local machine. That's a much faster feedback loop than pushing then waiting for 1-2 mins for the release to update. It compiles all keymaps too so it's a waste of time if you're just iterating on one keymap
4. Actions
To enable actions so all firmwares will automatically compile each time you push a change, do this:
5. Change files
To get files into the codespapce, you have to push your changes to your repo and then git pull inside the terminal of the codespace. The codespace is basically another computer accessing your repo. It is not integrated into the repo.
Warning
The codespace will be automatically deleted after some weeks of inactivity (Github will warn you by email). So its best to push the changes you made to the repo, then no data is lost. But you have to reinstall the codespace, if you want to change your keymap later.
6. Flashing
Bootloader
To put the Miao controller into bootloader mode (so you can flash the firmware on it): Hold down the left button while plugging the USB-C cable in.
To flash the downloaded firmware, you need to download one little tool.
Select the file for your platform, extract, put the wchisp in the same folder as the downloaded firmware (or vice versa) and in your local terminal do:
wchisp flash [keyboard].[keymap].central.ihx
If you just downloaded wchisp and did not properly install it, macOS (and probably other OSes as well) will not know the command, even when you are in the same directoy. You then have to type in for the Qass firmware:
./wchisp flash qass.default.central.ihx