QMK keymap tutorial for custom/DIY keyboard using QMK Firmware Builder

QMK keymap tutorial for custom/DIY keyboard using QMK Firmware Builder

1. Introduction:

• QMK Firmware is a firmware for the most powerful custom/DIY mechanical keyboards today.
• QMK Firmware Builder is a web-based application that can automatically generate firmware files for the keyboard based on user-provided information, instead of users having to manually code in C to create firmware files. Firmware Builder supports about 90% of QMK's features (the remaining 10% users need to code themselves based on the documentation).
• Website: KBfirmware.com and QMKeyboard.cn
• Documents about QMK: https://docs.qmk.fm/
• Firmware Builder target: custom/DIY keyboards using ATmega32U2, ATmega32U4, AT90USB1286 controllers. In particular, the following keyboard models have presets available for users to directly keymap, skipping the step of drawing circuit diagrams:
  • At KBfirmware: GH60, GH60 Satan, Minivan, Planck, S60-X RGB,...
  • At QMKeyboard: KBD75 (R3 onwards), TINA (DZ60), NIU/Mechmini2 (DZ40)
• Some keyboards that do not have presets on the website but have QMK firmware ported by users include: Tada68 (.json file in comment), Whitefox, XD60, B.mini,...

2. Website usage process:

Includes 3 steps:

Step 1: Create a keyboard layout in 1 of 3 ways:

• Upload configuration: when using the website to keymap, in addition to creating a firmware file, users can save all customizations to a .json file. The Upload section allows uploading a .json file on the computer for further customization.
• Import: for keyboards that do not have a layout available on the web, users can create a key layout in KLE , then paste Raw Data into this section and select Import to bring the layout into customization.
• Choose a preset: choose a layout available on the website.

Note: presets are flexible, meaning a preset can be used for many different layouts as long as it supports enough buttons, the size of the buttons in the preset does not have to be exactly the same as the layout the user soldered onto the keyboard. For example: all presets for DZ60 are divided into 3 spaces, but if the user only uses 1 normal space (size 6, 6.25 or 7 is the same), then only need to care about the keymap space in the middle of the preset. The same goes for the right Shift, Backspace keys,...

B2: Edit key features from the main interface

• Wirings and Pin tabs for editing key matrix.
• Keymap and Lightning cards to assign functions to each button.
• Macros tab to create/edit/delete macros. Macros are assigned to keys using the keycode M() in the Keymap tab.
• Quantum card adjusts the connection interface for split keys.
• Settings tab edits general information such as key names, number of LED lights, and number of LED levels.

B3: Export firmware from Compile card to flash to the key

III. Website usage instructions:

1/Wirings and Pins

• If you initially choose to upload a json file or load a preset, you can skip these two items.
• If you choose to create a layout from KLE, the website will create a symbolic circuit diagram (because when importing from KLE, it only loads the number of buttons and the button positions in the layout, there is no circuit diagram). You need to use these 2 items to edit the circuit diagram as desired.
  • Wirings: select the number of rows and columns in the circuit diagram. When selecting a button, you can customize which row/column this button connects to.
  • Pins: select each row, each column, Numlock light, Capslock light, LED strip,... to connect to which pins of the control chip.

2/ Keymap:

This section is to set the function for each button. When selecting any button, the current keycode of that button will appear, for example KC_B, clicking on the keycode will display the following adjustment interface:

Select the top layer, starting from 0.

a/The Primary card, in addition to the features commonly found in the 60% cluster of the keyboard, also includes the following functions:

• NUHS: # key in ISO layout
• NUBS: \| key in ISO layout
• TRNS (Transparent). For example, a key in layout 1 is B, layout 2 is TRNS. When holding FN to switch from layout 1 to 2 and pressing that key will still output B.
• NO: ignore, no keymap.
• RESET: put the key into DFU mode to flash the firmware.

b/The Secondary and Keypad tabs contain the features of the TKL cluster, numpad, media functions such as sound adjustment, song adjustment, and power off.

c/ Lightning card contains features to adjust background LED and underbody LED:

• 5 row 1 features to adjust the background led: TOGG to turn on/off; DEC/INC/STEP to increase/decrease brightness, BRTG to turn on/off breathing mode.
• 6 row 2 features: automatically adjust the color of the LED under the hood to 6 preset colors.

• 10 features row 3: TOG to turn on/off, MOD to change the underbody led effect. Because QMK has a total of 35 effect levels divided into 8 categories, there are 8 more features behind to quickly jump to each of those categories.
• 6 row 4 features: manually increase or decrease the value of RGB underbody led according to HSV color space ( illustration ):

• • HU=Hue: the color range runs in a circle from red -> yellow -> blue -> purple -> red.
  • SA = Saturation: the higher the increase, the darker the color.
  • VA = Value: the higher the value, the brighter the color.
  • I = increase, D = decrease.

d/ The FN tab is where advanced keymap features are gathered:

• The phrase LCTRL() to ALTG(): apply the corresponding modifier button to the keymap. For example, to create a keymap CTRL+C, select LCTRL(), then select the C button in the sub-branch. Allow nesting of multiple modifiers, for example, to create a keymap CTRL+ALT+DEL, the corresponding code is LCTRL(LALT(KC_DEL)).
• The phrases LT() to MT() are layer switching features, hold the modifier key:
  • MO( layer ): The simplest FN, moves to the layer in brackets when holding the key, only allows going up the layer (eg can run MO(2) from layer 1 but cannot run MO(1) from layer 2). Note that the key used to switch layers must set the TRNS keymap in the target layer, otherwise it will not be possible to return to the old layer when releasing FN.
  • TG( layer ): FN toggle, press once to change layer, press twice to return to old layer. Also only allows going up like MO.
  • LT( layer, key ): FN dual mode, move to layer when holding, and type key when pressing. For example LT(1, space) will move to layer 1 when holding, and normal typing will give space. Only allows going up layer.
  • TO( layer ): go to a layer, make that layer active . Allows going up or down a layer. For example, you can run TO(2) while on layer 4.
  • TT( layer ): FN dual mode. Hold this key to switch to layer , similar to MO, but pressing this key (default 5 times in a row) will jump to that layer, similar to TO.
  • DF( layer ): set layer to default when starting/plugging the keyboard into the computer.
  • OSM( modifier ): change the modifier for the next press. For example, press (not hold) OSM(Lshift) then press b to get B, but press a again to get a. If you hold this button, it will still get Shift as usual. This feature is very suitable for those who hate holding Shift but releasing it too quickly or slowly, so typing No will get no or KHon.
  • MT( modifier , key): will output modifier key when held, and key when pressed. For example, MT(LCTRL, CAPS) in capslock position will output capslock but capslock+A will output Ctrl+A. The modifier section can hold multiple mod keys at the same time.
• The phrases CTL_T() to ALL_T() are some shortcuts for the MT function above. For example CTL_T(KC_A) will output A when pressed, LCTRL when held, LCAG_T(KC_A) will output A when pressed, and simultaneously output LC TRL A LT G UI(Win).
• M( macro ): Macro. Define Macro from macro tag then assign order number to keymap here.
• Tricky_ESC: smart ESC key commonly found on 60% keys: press to get ESC, Shift+ESC to get ~.

e/OTHERS tag allows users to type keymap directly into the frame, serving some keymaps that the website does not support out of the box such as OSL.

See more advanced keymaps here .

3/ Macros:

Where to assign macro strings. The number of macros that the website supports is unlimited, but in reality, if you assign too many macros + long macros, it is easy for the controller to run out of memory -> error when flashing firmware.

• Add action: add events like press, hold, release, wait,..
• Record macro: save what the user types until this button is pressed again to stop recording (Does not save delay between events, if delay is needed, combine with Add Macro).
• Clear : clears all events of this macro.

After completing the creation of the Macro, go back to the Keymap tab -> FN -> M() to assign the created macro to the key. For example: Select a macro to modify, if you have selected 1, in the next step, assign M(1) to the desired position.

4/ Quantum:

This section is for split keyboards (eg Lets Split) allowing the matrix code to receive signals between the two keyboard parts. Ignore this for single-piece keyboards.

5/ Settings:

Some additional options such as key name (this will be the name of the config file as well as the firmware file), Bootloader size (default 4096kb), WS2182 LEDs (number of RGB LEDs), Backlight levels (number of brightness levels of the background LED).

• Backlight level should be set from 2 (off and on maximum brightness) or higher. Setting only 0 or 1 will make the light always off or always on. 3 or higher will insert intermediate brightness levels in between.
• In case the layout lacks basic keys or soft reset keys, the settings section will display an error as shown below:

Finally, press the Save Configuration button to save all settings to a json file for later reuse.

6/ Compile

Includes 2 sections:

• Download .hex to flash firmware file directly to the key
• Download .zip to download the source code folder, for editing additional advanced features, then from this folder run the MAKE command to create the .hex firmware file.

1. Flash firmware to the key

Use one of the following 3 tools:

1. QMK Toolbox , All in One instant noodle tool, supports both Mac ( .zip file ) and Win ( .exe file ).
2. Atmel FLIP , a dedicated tool that only supports Windows, supports both flashing and debugging Atmega circuits in case of holes.
3. dfu-programmer , a dedicated tool that supports mainly Mac and Linux, requires users to be familiar with Terminal operations.

1/ Put the key into DFU (Device firmware update) mode:

This is the first step to take when you want to flash the key. Depending on the type of circuit, you can use one of the following three ways:

• Press the reset button on the back of the circuit
• Hold Space+B then plug the usb cable into the keyboard
• Press FN+Backspace or FN+\| while the key is active.

Note:

• The DFU key is successful if pressing it no longer produces any characters.
• It is possible to install and use tools together without affecting the operation of the key.

2/ Using QMK Toolbox:

• Step 0: put the key into DFU.
• 1A: Click Open to navigate to the .hex file containing the downloaded firmware.
• 1B (sub-step, Support case the user's flash layout is wrong and needs to reload the original keymap): Download the keymap file from QMK's repository : select the circuit/keyboard name, select the keymap (mostly only include default keymap = default), then press Load to download to the address shown in the program window (eg C:\users\[user name]\Downloads\firmware name.hex). After step 1B, you still need to use 1A to open the downloaded .hex file.
• 2: select controller name (most circuits use atmega32u4)
• 3: Press Flash to flash the selected file into the key, press Reset to return the key to default (only used in case of flashing the wrong file)
• Reset EEPROM: reset the Bootmagic values ​​of the keys (see section IV. Appendix)
• List HID Devices: lists devices in DFU mode that can be flashed. If the key has entered DFU, the screen will display a message in the form: DFU device connected: controller name

3/ Using FLIP

• Install FLIP on your device.
• Turn off automatic driver search and update in Windows.
• Enter the key into DFU mode as instructed above, at this time in Device Manager will appear the device Atmel USB Deviced -> ATmega32U4 (or another name depending on the processor chip on the circuit).
• Right click on this device -> Update driver -> Browse My Computer... -> point to the USB subfolder in the FLIP installation folder -> OK. Wait for Windows to install the driver.
• Open FLIP, select the Settings -> Communication -> USB -> Open tab. If you have completed the above steps, FLIP will load the device and display 4 digital signatures (with 32u4 being 58 1E 95 87 ). Select the Load HEX file button as shown in the picture:
• Select the .hex file and press Run to flash it to the key, then unplug the key and plug it back in to use it normally.
  • For the next flash, just put the key into DFU mode and perform from the FLIP opening step, skip the driver installation part.

4/ Using dfu-programmer

• Installation requirements: the computer should have all the tools installed here . In addition, libusb may be needed ( sudo apt-get install libusb-dev for linux/ubuntu ; brew install libusb for Mac )
• Instructions for automatic installation from terminal: on Ubuntu/Debian: sudo apt-get install dfu-programmer ; on Mac: brew install dfu-programmer (for machines with Homebrew installed)
• Manual installation instructions: comes with README file, basically requires running 4 commands ./bootstrap.sh , ./configure , MAKE , sudo MAKE Install from the extracted folder. Installation is successful when running the dfu-programmer command from terminal.
• Key flashing instructions:
  • Put the key into DFU mode
  • Open Terminal, run the command sudo sudo dfu-programmer [chip name] erase to delete the current firmware on the key. The circuits/keys introduced at the beginning of the article all use the atmega32u4 chip.
  • Type the command sudo dfu-programmer [chip name] flash [path to .hex file] to flash the new firmware.
  • Type the command sudo dfu-programmer [chip name] reset to complete.
  • Illustration of 1-key flash using atmega32u4 chip as below:

Appendix: Bootmagic

A feature of QMK helps to quickly change the position of some keys, put keys into DFU,... without having to flash a new keymap file, similar to the hard DIP switch commonly found on Leopold, Filco, Ducky, Poker keyboards,...

By default Bootmagic commands are executed by holding the Space key + the corresponding key then plugging the USB cable into the key (these commands will not run if the combination is pressed after the key has been recognized by the computer). The commands include:

• Space+Esc: read Bootmagic default value
• Space+Backspace: reset bootmagic to default
• Space+B: enter DFU mode
• Space+LCtrl : reverses the position of left Ctrl and Capslock
• Space+Capslock: assign Capslock to control
• Space+LAlt: swap the positions of left Win and left Alt
• Space+RAlt: swap the position of right Win and right Alt
• Space+LGUI(Left Win): disable left Win
• Space+ ` : invert position ` and Esc
• Space+\|: invert the position of \| and Backspace
• Space+N: switch between 6KRO and NKRO
• Space+number from 0 to 9: assign layer from 0 to 9 as default layer

In case of key problems (some keys are reversed/disabled, layers jump, etc.), the first step is to reset bootmagic with the combination Space+Backspace then Space+Esc if the error persists.