Using NixOS/Linux to update my AnnePro2 to QMK - Written: 29 October 2022
I wanted my AnnePro2 keyboard to be more customisable. How did I do it on a computer running NixOS?
Hello!
I use the AnnePro2 mechanical keyboard as my main keyboard and I decided to install QMK on it in order to have more control over the device and use more advanced features than ObinsKit (the proprietary software used to control the keyboard).
The first step I took was to google ‘anne pro 2 install qmk’ and I came across this video that used Windows Subsystem for Linux to compile annepro2-tools as well as the QMK firmware for the annepro2. In the video, Pear Crew follows this guide which became my reference for the rest of this project.
Installing annepro2-tools
The first step in the guide is to compile and install annepro2-tools using rust’s cargo tool in order to flash the keyboard with our firmware of choice. I attempted to compile annepro2-tools using nix, however one of the required libraries (hidapi-rs) had a hard-coded reference to a /etc/ directory, which meant it was impossible to compile inside of nix without some sneaky tricks. Luckily, OpenAnnePro provides a Jenkins page to download premade builds without having to put in all the effort to compile it yourself. Despite the latest builds appearing to fail, they still produce linux artifacts, even though the other runs for mac and windows do not.
In order to run annepro2-tools, I created a nix flake to run the latest version of annepro2-tools that simply downloads the linux build from Jenkins and then runs it with the appropriate runtime libraries. You can run it yourself using nix shell github:headblockhead/nix-annepro2-tools.
Compiling QMK
Now that I had access to annepro2-tools, the next step inside the guide is to compile the QMK firmware for the annepro2. Thanks to the brilliant contributers of QMK, there is a shell.nix file for the make environment which makes building quite simple.
First, I cloned the github repo.
git clone https://github.com/OpenAnnePro/qmk_firmware.git annepro-qmk --recursive --depth 1
cd annepro-qmk
Then, I opened the nix-shell.
nix-shell
After that, I changed some of the lines in the code so it built without errors.
in keyboards/annepro2/annepro2.c,
wait_ms(ANNEPRO2_LED_MCU_WAKEUP_DELAY);
was changed to
// wait_ms(ANNEPRO2_LED_MCU_WAKEUP_DELAY);
wait_ms(20);
Finally, I ran the Makefile, specifying the revision of the keyboard. (In order to compile the right firmware for your keyboard, you need to know which revision it is. Thankfully, it is as simple as checking the underside of the keyboard. If the text in the middle of the circle on the back reads ‘Anne Pro’ then your keyboard is the C18 version and if the text reads ‘ObinsLab’ then your keyboard is the C15 version.)
# For C15 Revision
make annepro2/c15:default
# For C18 Revision
make annepro2/c18:default
After the make you should see a .bin file, either:
annepro2_c18_default.bin
or
annepro2_c15_default.bin
These are the files to be flashed to the keyboard.
Flashing QMK
While inside my nix flake (nix shell github:headblockhead/nix-annepro2-tools), I used annepro2-tools to flash my keyboard with the compiled QMK firmware after putting it into IAP mode (hold escape while plugging in)
sudo annepro2-tools ./annepro2_c18_default.bin
Compiling and flashing AnnePro2-Shine
Also while in my nix flake and in the QMK_firmware nix-shell, I cloned the annepro2-shine github repository, built it and then flashed it using annepro2-tools (again while in IAP mode). This allows for control over the RGB of the keyboard.
# Clone the repo
git clone https://github.com/OpenAnnePro/annepro2-shine.git --recursive
cd annepro2-shine
# Build it for C15
make C15
# or build it for C18
make C18
# or build it for both
make
# Then flash it to the annepro2
cd build
sudo annepro2-tools -t led ./annepro2-shine-C18.bin
# -t led targets the LED chip on the board.
Customization
Finally, the keyboard is ready for customization. I personally use The QMK Configurator which allows for saving and loading of keymaps via JSON. On the website, you can customize the keyboard to your liking, and then once you are satisfied you can press the ‘compile’ button which builds your customizations into a firmware file that can be flashed using annepro2-tools.
You can find my configuration in my dotfiles