Customize DZ60 Firmware with QMK Configurator

#nerdalert

One day my custom mechanical keyboard suddenly got weird: option and command keys are swapped. Pressing one button triggered another, and vice-versa. It happened just like that. Other keys were working fine.

Like a typical Mac keyboard, the orange is set to `alt` and the pink is set to `cmd` on my keyboard. But they were swapped.

This can be an easy fix in MacOS’ System Preferences › Keyboard › Modifier Keys settings where I can swap modifier option and command keys like so:

But then it’s not a real fix — just a workaround. With a custom mechanical keyboard, I shouldn’t have to rely on the settings via software. The keyboard should just work.

Anyway. Blah blah.

My first attempt was re-flashing the keyboard’s old firmware. Using the same steps I took note last time. It didn’t work out.

I googled around for alternatives and found this video: QMK Tutorial: QMK Configurator Preview (Creating Keymaps/Hex)

QMK configurator is basically a similar tool to qmkeyboard.cn I used earlier, but (in my opinion) is easier to use than qmkeyboard.cn.

Unfortunately, the custom keymap JSON file created with qmkeyboard.cn is not compatible with QMK configurator app. So I had to start from scratch and saved the layout into a new JSON file for QMK configurator app.

This is how I did it using my customized firmware.

1. Go to https://config.qmk.fm
2. In Keyboard option, select dz60
3. Select Import Keymap and select a JSON file downloaded from this gist. If there is more customization needed, select a button in Keymap: section and choose from available keys in Keycodes: section below it.
4. Select compile and wait for a few seconds until Download Firmware button is available.
5. Select Download Firmware to download the .hex file
6. Use QMK Toolbox app to flash the new firmware. (described here)

Off-topics

I made a few mistakes while I was trying to fix the keyboard.

Mistake #1: Forget the Reset key

When I customized the firmware for the first time (creating firmware#1), I didn’t add the Reset key into a layout as I thought the Reset button should always be the same and cannot be changed.

I was wrong.

A custom mechanical keyboard lets us customize any button on the keyboard, including ones we shouldn’t customize: a very important one like a Reset button, for example.

My keyboard then was not able to enter bootloader mode. I needed to press the Reset key but it was already gone. That means I could not re-flash another firmware anymore!

I googled around for some time and lucky enough, I found this video: How to reset your dz60 by Bill Liang, showed me that there is actually a Reset button (or rather holes) at the back of the PCB that can only be pressed physically by a tweezer.

The undocumented reset button

So I did that. My keyboard could enter bootloader mode and I could re-flash a new firmware again (firmware#2). This time with the Reset button.

Mistake #2: Disregard LED keys

Even though the DZ60 comes with pretty fancy backlight LEDs built-in, I don’t use any of them and always turn them off.

Same story with the Reset key: I don’t use backlights so I thought 🤔 I might not need buttons to control the backlight functionalities (toggle/turn on/off) on my keyboard. I didn’t put them in the layout editor.

Flashed the firmware (#2). Bam. The LEDs went back to the factory-default state: full red (super red 🔴 exactly like in the video above). And I could not switch to softer lights or turn them off because there was no buttons to do so. The lights just stayed red all the time.

A smaller failure this time, but still a failure.

I created another firmware again (firmware#3). This time with LED controls AND the Reset button. Flashed it again and the keyboard worked as expected. I could turn off the backlights.

Oh and the swapped option and command keys were also fixed.