I recently wanted to update my keyboards layout and thought it was a good opportunity to come with a guide since many friends keep asking me how to flash their keyboard on Linux. In this case I am requiring an Atmel-based PCB as we’re using DFU-Programmer which is developed for Atmel-Microcontrollers. But there is a good chance, that you have one in your keyboard as well since they are the most popular manufacturer for micro controllers.

Install prerequisites:

sudo pacman -S python python-pip python-wxpython  dfu-programmer

First of all we need to come up with our layout, which we use easykeymap.sh from the EasyAVR package for. It also generates a .hex file which we later use for flashing. In order to run easykeymap.sh we need to clone the project from GitLab.

git clone https://gitlab.com/ChuckN408/EasyAVR.git && cd EasyAVR
sudo ./easykeymap.sh

Firstly you need to create a new layout file and select your board accordingly. In my case it’s a GH60. There is also an option that lets you roughly determine the keyboard layout. In my case I selected ISO here as it’s the standard here in Europe. Now you can either further modify your selected layout in easykeymapper itself or use one from an external source. For example you can generate layout files online by using the [keyboard-layout-editor(https://keyboard-layout-editor.com).

To map the keys select the key you want to remap and click on the white rectangle beneath the scan code in the context menu. Now a virtual keyboard assists you in finding the correct key. In order to use function layers, you need to define a key as Fn1, Fn0 will not work. If you finished your layout you can go ahead and save it now in .json format for later modifications.

Now you need to export the .hex file, that we will going to flash on to the keyboards microcontroller. To program your board you can either choose the “Build & Program” option or use dfu-programmer manually. I prefer the by hand method for security reasons since it doesn’t require you to open easykeymapper as root user. But keep in mind that you first need to put your board into boot mode by either pressing a reset button at the back of your PCB or use a predefined boot button.

The programming steps are as follows. If you’re board uses a different microntroller than the atmega32u4 simply replace the name. But keep in mind you need to use a second keyboard to enter the commands. Alternatively you can use a script as well.

Using the script:

wget https://gist.githubusercontent.com/alexanderstephan/655e9fc4ab07f268af271c4084c19fef/raw/bee744308b81e524557fde6ad2890ba4a74414da/gh60.sh -O gh60.sh
chmod +x gh60.sh
sudo ./gh60.sh

Or just do it manually, if you only do it once in a while.

dfu-programmer atmega32u4 erase --suppress-validation
dfu-programmer atmega32u4 flash <filename>.hex