QMK Firmware is a pretty good software for those who build mechanical keyboards and want to customize and load firmware for their mechanical keyboard. The following article will guide you through the basic use of QMK Firmware for those who are new to keyboard playing.
1. Settings required for basic use
1.1 Install a code editor: you can use notepad, notepad++, Microsoft visual basic or any similar editor.
1.2 Install the build environment
For Windows users:
- Download and install MSYS2 here: https://www.msys2.org/
2. There are 2 ways to download firmware to your device in many ways, the 2 popular ways are as follows.
2.1 Download source code directly here:
https://github.com/qmk/qmk_firmware/releases
And continue reading from section 3
2.2 Create a github account and fork the code to your github (recommended).
- Go to github.com and create an account
- Download and install Github Desktop at: https://desktop.github.com/
- After logging in, access qmk on github at the link: https://github.com/qmk/qmk_firmware
- Click on Fork (red box) to automatically create a copy (1) to your github account:
- Start Github desktop and log in.
- In the program window, select File -> Clone Repository… (shortcut Ctrl+Shift+o)
- In the Clone a repository menu, select the folder you want to create a copy of (1') on your computer and then click Clone.
After 1' has been downloaded, to make it easier to change the firmware, create a copy of 1' (1'') - also known as a branch - for easy editing without affecting the main copy (1').
To create a branch. In the main window, make sure to select the copy (1') you want to create a branch on. Click Branch -> New Branch… (shortcut Ctrl+Shift+N)
A new window appears, name the branch you want to create.
Note to choose a name that is easy to remember, for example if you want to create a new key named ht75, you should name the branch dev_ht75 or mechlovin-dev_ht75.
3. Creating the compilation environment and first initializations
3.1 Create a compilation environment.
After creating the branch, launch MSYS2, point to the util folder in qmk on the machine
For example, on a computer that is saving the qmk folder at drive E:\Firmware\qmk_firmware, type the following characters in the terminal window:
cd e:/Firmware/qmk_firmware
cd util
Run the qmk_install.sh file to install the libraries:
bash qmk_install.sh
The computer will automatically install the environment to compile code into machine language.
After installation is complete, carefully close all windows and save any other work in progress, restart your computer.
3.2 First Initializations
Start MSYS2 pointing to the util directory in qmk (command in section 3.1)
To create code for new keyboard (pcb, wiring circuit) run file new_keyboard.sh D
At Keyboard Name, name the keyboard. Note that no characters are capitalized, and letters and numbers can be separated by underscores.
At Keyboard Type select avr or ps2avrgb (for the bootmapper client key)
Code creator name: enter anyone's name
After selecting, the program will automatically generate the code for the new keyboard in the qmk_firmware/keyboards/ht75 folder.
4. Create the keyboard layout you want to use
4.1 Create layout on KLE:
Access KLE at: http://www.keyboard-layout-editor.com/#/
Create a layout you want to use, the example below takes the pre-made layout keycool84
Copy all data in Raw Data tab
Open a new browser tab, go to kbfirmware.com.
You will see a text editing box, paste all the raw layout data into this box and click import
After clicking import, in the wiring tab, enter the correct number of rows and columns of the keyboard and the exact row-column position of each button so that it matches your matrix.
Then at the pins tab, select the correct pinout (only supports Atmega32u4 microcontrollers) that matches your key
After selecting on the computer the same matrix and pinout on the pcb and on the wiring board, select the settings tab and choose save configuration.
5. Edit directly on the code.
- After saving the file from kbfirmware.com, go to https://noroadsleft.github.io/kbf_qmk_converter/ and load the file from kbfirmware and you will get the result as shown.
- Access the ht75 folder created from 3.2 open the entire folder in the pre-installed code editor (recommended ms visual code)
- Copy all data on KBFirmware Json to QMK Parser and overwrite each corresponding file in ht75 folder
- Data in config.h is overwritten with config.h file in ht75
- rules.mk is overwritten with rules.mk in ht75
- keyboard.c is overwritten with ht75.c
- keyboard.h is overwritten with ht75.h
- keymap.c is overwritten with default/keymap.c
- After pasting all data, open msys window and go to qmk folder, then compile:
- make ht75:default
- command after compiling and uploading code to pcb:
- make ht75:default:dfu
- Vu Quang Nguyen – VKG Viet Nam Keyboard Group
