How To Make A Keymap With QMK Configurator

How To Make A Keymap With QMK Configurator

Written By: Boardsource

Category: guides - easy

Tags: qmk, flashing


In this guide you will learn the ins and outs of flashing a keyboard using the QMK configurator. QMK is an open-source project and is really the cornerstone of the hobbyist keyboard community. Whereas “big brand” keyboards (think Corsair, Razer, etc.) ship with their own proprietary software to map keys, setup macros, and change lighting, that is a gargantuan task for your average keyboard-creator and maker. QMK offers the community a great way to centralize keyboard mapping and flashing, and the entire community has QMK to thank for so much. Additionally, the team behind QMK does an absolutely amazing job of reviewing what is included in QMK and that results in an incredibly fluid experience using it, where frustration is low, and things just work. I love QMK.

When you’re first starting out in the hobby, flashing a keyboard via QMK is a tiny bit intimidating, for some reason the words “flashing” and “keymaps” and just the acronym QMK alongside the jargon “Configurator” and “Toolbox” can be a bit much. However, trust me, when you break it down it’s quite simple, and after you do it once it will literally take you mere moments to flash keyboards from that point on. Furthermore, you will soon find that QMK offers FAR MORE options compared to other proprietary software shipped with big-box store keyboards. In fact, the features of QMK and what it allows you to do with your keyboard is really the main reason so many people want to use a custom keyboard. It’s not just about looks, it’s about the increased functionality and productivity the customization offers you.

In order to help you get a thorough understanding of the process of flashing a keyboard, I am going to outline some key terms you may have heard already heard or will definitely hear throughout the community.

Common Terms

QMK: An open-source project that allows creators to submit their keyboard into the project so that users/customers may use the QMK ecosystem to flash their keymaps to the keyboard and customize it as they see fit.

Keymap: A keymap is a file (code) that maps your physical keystrokes to an input. The keymap, hence the inclusion of the word map, tells your computer which key does what. Whether that is a simple key like the letter “A” or a more complex Macro or function key, it is included in the Keymap. Keymaps are sometimes referred to as a “Hex file” or a “.hex” because the file-type of a Keymap is “.hex or .uf2,” ex. (“sick_keymap.hex”).

QMK Configurator: A web-based application that allows you to create a Keymap in a visual way using Drag and Drop tiles (symbolizing keys), with pre-set Keymaps available for any keyboard in QMK. The QMK Configurator allows you to create a keymap without writing any code, and then simply hit a button to produce a completed (compiled) .hex or .uf2 file.

Flashing: The process of putting a piece of software onto a piece of hardware. In the world of keyboards, flashing simply means putting your Keymap (the .hex or .uf2 file produced by the QMK Configurator) onto the Micro Controller (generally a Pro Micro / Elite-C or Blok).

QMK Toolbox: A desktop application that allows you to take your Keymap (.hex or .uf2 file) produced by QMK Configurator and then flash it onto your keyboard.

With knowledge of what those terms mean and what they are referring to, you’re now ready to move onto actually creating a Keymap and flashing your board!

Step 1: Create Your Keymap (Part A)

The first step of flashing a keyboard is to create and download a Keymap (.hex or .uf2 file). Remember, the keymap is produced by the QMK Configurator so let’s head over there. The URL for the QMK Configurator is QMK Configurator.

You will see something similar to this, but depending on when you view the website in relation to when this article was written, it is possible it looks islightly different.

qmk configurator

For the purpose of this guide, we will pretend we are flashing a 3x4 Macro Pad By Boardsource. In order to create the correct keymap for the board we are working on, we need to select it from the dropdown list shown in the photo below.

All Boardsource boards that do not overlap with an existing keymap will be listed under “boardsource/NAME_OF_BOARD,” so the 3x4 Macro Pad is listed under “boardsource/3x4.”

Here is what the page will look like after you make your selection (although the preview of the keyboard layout should of course look like the keyboard you’re attempting to flash).


Step 2: Compile Your Keymap And Download Firmware

For the purpose of this guide we are using the default Keymap provided in the Configurator, which every single keyboard in QMK has. However, feel free to make any changes you want to the Keymap prior to Compiling.

After you are satisfied with your Keymap, simply hit the Compile button, and wait for the potato animation to complete. When the potato is done baking (the Keymap is done Compiling) you can click the Green “Firmware” button with a download icon next to it, and you completed .hex or .uf2 Keymap file will be downloaded.

After you have successfully downloaded the Keymap file (.hex or .uf2), you are officially done in the QMK Configurator, and the rest of the process is completed within the QMK Toolbox.

qmk configurator
compile qmk configurator compiling
potato qmk configurator compiling

Step 3: Flashing

Flashing your keyboard is the process of putting the keymap onto the keyboard. The whole time we have been working to produce a (.hex or .uf2) and it has not mattered so far. But now we will go down 2 paths to flash the keyboard.


If you just produced a .hex/.bin please follow this guide on using QMK TOOL BOX


Otherwise if you just produced a .uf2 please continue to this guide on how to flash a .uf2.