QMK Configurator Tutorial

By Xah Lee. Date: .

QMK is open source software for configurating keyboards. It is one of the most powerful firmware to program the keys. And is the most popular tool in Do It Yourself keyboards.

Here's how to use the QMK Configurator to create your keyboard keymap and layouts.

We'll use the gergo keyboard as example.

gergo keyboard 20200121 zgxyd-s353x177
Gergo 50
gmk configurator gergo 2020-06-23 p9z28
qmk configurator for gergo 2020-06-21

Goto the site https://config.qmk.fm/#/gergo/LAYOUT_gergo

WARNING: be sure the keyboard selection is gergo keyboard. If you clicked the link, the gergo keyboard will be selected.

Drag and drop keys to how you like it.

Press the Compile button. Takes about 1 minute.

When done, click Firmware to download it. You'll get a “.hex” file.

qmk hex file 2020-06-13 ttvzh
qmk hex file

Download the qmk toolbox at https://github.com/qmk/qmk_toolbox/releases Open it.

qmk toolbox 2020-06-13 5mncw
qmk toolbox 2020-06-13

On Mac, if system says cannot open it for security reasons, goto your system preference, click the “Security and Privacy”, General tab, click Allow.

Unplug the Gergo keyboard. Now, hold the key on the lower right of the right keyboard (normally the Right shift position on traditional keyboard). Then plug Gergo in to computer. This will set the keyboard to Device Firmware Upgrade mode. You'll see the toolbox display “*** DFU device connected”.

In toolbox app, in the “Local file” popup, select the hex file you just downloaded. Click “Flash” button to update the firmware in keyboard. You are done.

“no device present” error

On Microsoft Windows, you may get

dfu-programmer: no device present.

in qmk toolbox.

qmk toolbox no device present 2020-06-23 sp3pv
qmk toolbox error message: no device present

here's what to do. Basically, you need to install the driver for the bootloader.

Here's the doc:


Go download zadig. Install it. Open it.

Unplug the gergo.

plug in the gergo while holding the right side lower right key down.

The zadig should show:

zadig ATm32U4DFU 2020-06-23 464f8
zadig ATm32U4DFU 2020-06-23

Now, select “libusb-win32” on where the green arrow points to.

then click insall driver.

Now, back in qmk toolbox. Now, unplug gergo and replug in the gergo while holding the right side lower right key down.

you'll see the proper driver message:

DFU device connected: Atml Corp. ATm32U4DFU (03EB:2FF4:0000)

qmk toolbox ATm32U4DFU 2020-06-23 bhxs9
qmk toolbox ATm32U4DFU 2020-06-23

Now, go ahead and click Flash.

If you have a question, put $5 at patreon and message me.