XD87 TKL Keyboard kit – QMK firmware

I already went through the customization of the XD87 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.

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.


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:

This is my layer 0, pretty basic

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.

My layer 1, with shortcuts for media, LED backlight and RGB underglow controls

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).

3 easy steps

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.

QML Toolbox shows the flashing progress

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

Published by


Web developer, geek, car enthusiast, photographer, DIYer, video gamer... I like many things, maybe too many?

Leave a Reply

Your email address will not be published. Required fields are marked *