XD87 TKL Keyboard kit – QMK firmware

I already went through the customization of the XD87 (HS) keyboard via TMK using a layout from KLE in this blog post (along with general information about keyboard layout customization). The XD87 now has QMK support. That firmware is based on TMK, so it has the same principles but is a bit different in multiple aspects. Let’s look at them and see how to flash QMK on the XD87 (HS).

The difference between TMK and QMK as an end user aren’t really significant as they offer pretty much the same features. However, the path that leads to your flashed and ready keyboard is quite different.

Before going any further: Per key backlight is buggy (LEDs brightness isn’t steady). If bothers you, use the TKG firmware instead. See this blog post.

A note about the XD87 HS: HS is for hot swap, it’s the hot swap version of the XD87 that was released later. The main difference is the hot swap sockets (no kidding…) and a slightly less flexible layout. A reader of the blog confirmed that the version of QMK is compatible with the XD87 PCB.

Keymap

We’ll not be using KLE this time, nor TKG website. QMK has its own tool to generate keymaps and firmware which is pretty neat. It also gives access to internal QMK features.

Go to https://config.qmk.fm, choose the xd87 in the keyboard dropdown, and then choose your layout (ansi or iso). The full layout is for people that soldered the extra switches (1 between escape and F1, and 1 on each side of the ↑ key.

Once you picked your layout, start creating your keymap. Drag’n’drop a keycode onto a keyboard key, or select a key and click on the keycode. You should be able to get to this stage:

My layer 0 is really basic. The only “special” key is MO 1. It’s a momentary toggle to access the layer 1: hold the key to activate layer 1, release the key and you’re back to layer 0.

Now, onto the layer 1.

I use the arrow keys as media keys, enter as play/pause. BL+/- are for controlling the per key backlight, and on the other side, controls for RGB underglow. The escape key is Reset to flash the keyboard. The EEPROM Reset if for resetting the internal memory of the keyboard, in case something’s wrong. All the other keys are KC_TRNS, they act as “transparent” and when pressed, they fallback to the layer below.

Here’s my keymap json file, if you want to start from there: download the file (right click, save as…). You can import it in the layout tool so you won’t have to manually set all the keys.

Once you’re done, I suggest you download your keymap.json file as well. You’ll be able to re-import it later if you want to change it or even look at it if you forgot a key or anything.

Now click Compile. Wait for it to finish.

From here, there are 2 options:

• download the compiled firmware and flash it (download this file for use with QMK Toolbox)
• download the source (either keymap only and entire source code), compile it yourself and flash it

Flashing the keyboard

The QMK documentation has an entire section dedicated to keyboard flashing. That section doesn’t really explain how to flash a keyboard once you have the .hex file, it just tells you to use QMK Toolbox with no further information, or use the command line.

Flashing with QMK Toolbox

We’re going to use QMK Toolbox to do this, as recommended. Download it from the official release page: https://github.com/qmk/qmk_toolbox/releases (.exe for Windows, .app.zip for MacOS). It’s not compatible with Linux, sadly (see ticket on Github).

Open up the app. Click “Open” to select your keyboard firmware file (1). The firmware file is always a .hex file. Make sure the micro-controller is set to “atmega32u4” (2). Check the “Auto-Flash” box (3).

Now, reset the keyboard (make a short between the holes that are located between the delete and end keys). QMK Toolbox should detect that the keyboard is in flash mode and start the flashing process automatically.

Note: in my layout, I’ve set fn + Esc as a Reset key. This allows me to set the keyboard in flash mode without the need of shorting the 2 holes. Very handy.

And that’s it, you’re ready to try your new layout. Happy flashing!

Flashing via the command line

From the QMK repo

If you have cloned QMK repo on your machine, then it’s pretty easy. I’ve done it using a Linux machine though, it’s way easier to get all the tools working.

First, you need to get all the commands and package to compile a QMK firmware via the command line. Checkout out the requirements list in QMK doc. And if you’re too lazy to click:

• build-essential
• gcc
• unzip
• wget
• zip
• gcc-avr
• binutils-avr
• avr-libc
• dfu-programmer
• dfu-util
• gcc-arm-none-eabi
• binutils-arm-none-eabi
• libnewlib-arm-none-eabi
• git

Once you have all of those installed, run the compile command with :dfu at the end. Something along those lines (modify it depending on your layout name):

This will compile the firmware, then wait until it detects a device in bootloader mode, then it’ll flash it. So, you guessed it, run the command, wait for it to compile, switch your XD87 to bootloader mode, it should get flashed automatically, and you’re done. Easy peasy.

From .hex file via dfu-programmer

If you look at the command output in both QMK Toolbox and QMK compile + dfu flash, you can actually see what’s going on. We can easily reproduce that and use it to flash a .hex file on a keyboard.

First step is to erase the flash memory

then flash the firmware

and finally, reset the keyboard so it boots into the new firmware