Dear GMMK community and fans,
Here is my step-by-step guide for installing QMK firmware and setting your own keymap on GMMK 2 Compact.
Context
- This guide is applicable to Ubuntu based Linux distros like Pop!_OS 22.04, the one I’m using for years.
- QMK CLI is used, since it’s reliable and on Linux QMK Toolbox is not available.
Intro
- After spending some hours, I managed to have it working. Now, let me share all my notes while discovering features, issues, and solving them.
- I’m writing this using my newest acquisition, the GMMK 2 Compact
- Now it has QMK firmware since this allows me to have my own keys, as you’ll see below.
- I’m using the lovely Pop!_OS linux distro on my machines, so this guide is based on this setup.
- I gain some “experience” doing this while setting QMK firmware on my GMMK Pro keyboards, although there the process is way smoother than this one.
The main structure follows the “official” GMMK 2: QMK Installation Guide blog post. I’m just adding here some missing parts and additional details.
In the example outputs included below, I tend to skip the unrelevant details by including a ... (ellipsys symbol) to illustrate that some content is omitted. Like this:
one line
...
another line
Setting Up
Prerequisites
As stated in Prepare your build environment section, install:
- The prerequisites using
sudo apt install -y git python3-pip - QMK CLI using
python3 -m pip install --user qmk
(to reinstall it, usepython3 -m pip install --ignore-installed --user qmk)
The CLI is the qmk utility that get’s installed in ~/.local/bin/qmk path (aka /home/{your-user}/.local/bin/qmk). Therefore, make sure that $HOME/.local/bin exists in your PATH env var. Check that’s applicable by simply running qmk -V for example. At the time of this writing (2022-07-18 23:20), version 1.1.0 should be reported.
QMK Setup
Before running it, make sure you don’t have (remove if it exists) the qmk_firmware folder in your home dir (use rm -rf ~/qmk_firmware just to be sure).
Run qmk setup GloriousThrall/qmk_firmware. Basically, we’re telling to CLI to use Glorious specific parts (not yet included in the official QMK repo).
$ qmk setup GloriousThrall/qmk_firmware
☒ Could not find qmk_firmware!
Would you like to clone GloriousThrall/qmk_firmware to /home/dxps/qmk_firmware? [y/n] y
Cloning into '/home/dxps/qmk_firmware'...
Updating files: 92% (31259/33900)
...
Submodule path 'lib/vusb': checked out 'bdb53e4c043d089279d9891b68bea77614cb97ee'
Ψ Successfully cloned https://github.com/GloriousThrall/qmk_firmware to /home/dxps/qmk_firmware!
Ψ Added https://github.com/qmk/qmk_firmware as remote upstream.
Ψ QMK Doctor is checking your environment.
Ψ CLI version: 1.1.0
Ψ QMK home: /home/dxps/qmk_firmware
Ψ Detected Linux.
Ψ Git branch: master
Ψ Repo version: 0.15.25
Ψ All dependencies are installed.
Ψ Found arm-none-eabi-gcc version 10.3.1
Ψ Found avr-gcc version 5.4.0
Ψ Found avrdude version 6.3-20171130
Ψ Found dfu-util version 0.9
Ψ Found dfu-programmer version 0.6.1
Ψ Submodules are up to date.
Ψ QMK is ready to go
$
And then:
$ cd qmk_firmware
$ git checkout glorious_gmmk2
$ make git-submodule
Verify Setup & Initial Build
Now it’s time to validate that this setup is fine by trying to build this QMK locally with the default keymap for the keyboard (again, GMMK 2 Compact in this case) using qmk compile -kb gmmk/gmmk2/p65/ansi -km default
$ qmk compile -kb gmmk/gmmk2/p65/ansi -km default
Ψ Compiling keymap with gmake --jobs=1 gmmk/gmmk2/p65/ansi:default
QMK Firmware 0.15.25
Making gmmk/gmmk2/p65/ansi with keymap default
arm-none-eabi-gcc (15:10.3-2021.07-4) 10.3.1 20210621 (release)
Copyright (C) 2020 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Compiling: keyboards/gmmk/gmmk2/src/eeprom_flash.c [OK]
...
Compiling: lib/chibios-contrib/os/hal/src/hal_opamp.c [OK]
Linking: .build/gmmk_gmmk2_p65_ansi_default.elf [OK]
Creating binary load file for flashing: .build/gmmk_gmmk2_p65_ansi_default.bin [OK]
Creating load file for flashing: .build/gmmk_gmmk2_p65_ansi_default.hex [OK]
Size after:
text data bss dec hex filename
0 43428 0 43428 a9a4 gmmk_gmmk2_p65_ansi_default.bin
Copying gmmk_gmmk2_p65_ansi_default.bin to qmk_firmware folder [OK]
(Firmware size check does not yet support WB32F3G71; skipping)
$
Cool! The compilation works fine. Next steps could be either just flashing this QMK firmware with default keymap, or first customize a bit the default keymap (which at the time of this writing has some wrong keys mapping in it).
Customizing the Keymap
As mentioned in the official guide, we can customize the keymap. As I wanted to use pretty much the same keys setup that I’m using in my other GMMK Pro keyboards, I had to do it. My OCD won’t let me live without it…
Opening keyboards/gmmk/gmmk2/p65/ansi/keymaps/default/keymap.c file (while still being in qmk_firmware folder, ofc), I updated as follows:
#include QMK_KEYBOARD_H
// Each layer gets a name for readability, which is then used in the keymap matrix below.
// The underscores don't mean anything - you can have a layer called STUFF or any other name.
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = LAYOUT(
KC_GESC, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_BSPC, RGB_TOG,
KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS, KC_PGUP,
MO(1), KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_ENT, KC_PGDN,
KC_LSFT, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RSFT, KC_UP, KC_DEL,
KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_RALT, MO(1), KC_LEFT, KC_DOWN, KC_RGHT),
[1] = LAYOUT(
KC_GRV, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, _______, RGB_MOD,
_______, _______, _______, KC_BSPC, _______, _______, _______, _______, _______, _______, KC_CAPS, RGB_HUD, RGB_HUI, _______, RGB_VAI,
_______, KC_WREF, _______, KC_DEL, RGB_SPD, RGB_SPI, KC_LEFT, KC_DOWN, KC_UP, KC_RGHT, KC_END, _______, RGB_VAD,
_______, _______, KC_UNDO, KC_CUT, KC_COPY, KC_PSTE, RGB_VAD, RGB_VAI, KC_HOME, KC_VOLD, KC_VOLU, KC_MUTE, _______, KC_PGUP, KC_INS,
_______, _______, _______, RESET, _______, _______, KC_HOME, KC_PGDN, KC_END),
[2] = LAYOUT(
_______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______,
_______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______,
_______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______,
_______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______, _______,
_______, _______, _______, _______, _______, _______, _______, _______, _______)
};
Here are some notes to understand what’s all about it:
- Each key has a code (that’s why you see mainly the
KC_prefix).
There are also some key codes for other functions, such as RGB lighting (thoseRGB_values).
The meaning of these codes can be found here. - Layer 0 (the one that starts with
[0] = LAYOUT() represents what keys are used by default.
a. Here, for example, I moved the Delete key from top right near the arrows.
That helps me to navigate using the arrows and quickly delete some character, if needed).
Or, I’d use Fn with the arrows to have go Home, End, and Page Up, Page Down. - Layer 1 (the one that starts with
[1] = LAYOUT() represents what keys are used whenFnis pressed.
Some very important “shortcuts” to me are:
- Having
Fninstead ofCaps Lock.
This is very handy (kinda influenced by HHKB approach). - Using
Fnplus (vilike options) i, j, k, l to navigate.
Instead of having to go to the arrow keys, these “shortcuts” are easily reachable.
I’m also usingFn + mfor Home andFn + ;for End.
And with these, I really don’t have to reach the arrows keys.
I’m also using some other goodies like:
-
Fn + afor (browser) Refresh (seeKC_WREF) -
Fn + dfor Delete (seeKC_DEL) -
Fn + efor Backspace (seeKC_KC_BSPC)
Having this done, we have to recompile QMK again. Same as before, using qmk flash -kb gmmk/gmmk2/p65/ansi -km default.
If the compilation fails, most probably, you missed some comma (,) or have a typo in the codes (in this case, the compiler could give you some helpful hints).
Flashing the QMK Firmware
This phase includes some tricky parts. But I manage to get rid of them, so you can do it as well …
Update and Apply udev rules
In order to be able to access the (keyboard) device as a non-root user, some udev rules need to be applied. We have them already defined in qmk_firmware/util/udev/50-qmk.rules file. But there is no definition for this GMMK 2 Compact device.
Update this file by appending at the end of it the following line:
## GMMK 2 Compact
SUBSYSTEMS=="usb", ATTRS{idVendor}=="342d", ATTRS{idProduct}=="dfa0", TAG+="uaccess"
Then install and have them applied using:
sudo cp qmk_firmware/util/udev/50-qmk.rules /etc/udev/rules.dsudo udevadm control --reload-rules && sudo udevadm trigger
Without doing these, you’ll encounter errors like the following during flashing:
Cannot open DFU device 342d:dfa0 found on devnum 50 (LIBUSB_ERROR_ACCESS)
Install wb32-dfu-updater_cli
Next, there is one more thing to have (at least that was my experience). When trying to flash (as we’ll see in a minute), you might get an error about some wb32-dfu-updater_cli not found.
``
To have this utility available, do the followings:
git clone https://github.com/WestberryTech/wb32-dfu-updater.gitcd wb32-dfu-updater-
./bootstrap.sh install
I guess I was impatient at this time and I usedsudo ./bootstrap.sh install.
But I think it can be installed withoutsudo.
Put the Keyboard into Bootloader Mode
Before flashing the firmware, you have to put the keyboard in bootloader mode. Depending on which firmware you have, different shortcuts must be used before plugging it into your system.
If you have the Glorious Core firmware, use the Space + b shortcut.
If you have QMK firmware (a relevant case if later you’d like to update the keymap and apply it, or just switch back to Glorious’ firmware), use the Esc shortcut.
So, keep these keys pressed before and while connecting the keyboard.
Physically, when the keyboard starts in this mode no lights are on. But that’s not sufficient to me, so I generally watch the syslog using sudo tail -F /var/log/syslog.
There the confirmation exists:
$ sudo tail -F /var/log/syslog
...
Jul 18 21:32:48 codebox kernel: [1639145.833698] usb 1-4: new full-speed USB device number 50 using xhci_hcd
Jul 18 21:32:48 codebox kernel: [1639145.983140] usb 1-4: New USB device found, idVendor=342d, idProduct=dfa0, bcdDevice= 1.00
Jul 18 21:32:48 codebox kernel: [1639145.983153] usb 1-4: New USB device strings: Mfr=1, Product=2, SerialNumber=0
Jul 18 21:32:48 codebox kernel: [1639145.983158] usb 1-4: Product: WB Device in DFU Mode
Jul 18 21:32:48 codebox kernel: [1639145.983162] usb 1-4: Manufacturer: Westberry Tech.
Jul 18 21:32:48 codebox mtp-probe: checking bus 1, device 50: "/sys/devices/pci0000:00/0000:00:14.0/usb1/1-4"
Jul 18 21:32:48 codebox mtp-probe: bus: 1, device: 50 was not an MTP device
Jul 18 21:32:48 codebox mtp-probe: checking bus 1, device 50: "/sys/devices/pci0000:00/0000:00:14.0/usb1/1-4"
Jul 18 21:32:48 codebox mtp-probe: bus: 1, device: 50 was not an MTP device
Flash the QMK firmware
Finally, flash the previously compiled (recall that qmk compile -kb gmmk/gmmk2/p65/ansi -km default was used at that time and), this time using:
qmk flash -kb gmmk/gmmk2/p65/ansi -km default
Example:
$ qmk flash -kb gmmk/gmmk2/p65/ansi -km default
Ψ Compiling keymap with gmake --jobs=1 gmmk/gmmk2/p65/ansi:default:flash
QMK Firmware 0.15.25
Making gmmk/gmmk2/p65/ansi with keymap default and target flash
arm-none-eabi-gcc (15:10.3-2021.07-4) 10.3.1 20210621 (release)
Copyright (C) 2020 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Size before:
text data bss dec hex filename
0 43428 0 43428 a9a4 gmmk_gmmk2_p65_ansi_default.bin
Size after:
text data bss dec hex filename
0 43428 0 43428 a9a4 gmmk_gmmk2_p65_ansi_default.bin
Copying gmmk_gmmk2_p65_ansi_default.bin to qmk_firmware folder [OK]
----------------------------------------
.build/gmmk_gmmk2_p65_ansi_default.bin file opened
----------------------------------------
Found DFU
Opening DFU capable USB device ...
Device ID 342d:dfa0
----------------------------------------
The device bootloader version: 0.3
Chip id: 0x3A50A980
Flash size: 128 KBytes
Sram size: 28 KBytes
----------------------------------------
Start Download ...
Download block start address: 0x08000000
Download block size: 43428 Bytes
Writing ...
OK
Download completed!
$
Unplug the keyboard. Plug it back in and there you have it! QMK with a lot of freedom …
Pending Issues
I am pretty sure all of these will be solved, and none of them is major, imo.
-
In the default (Glorious’) firmware, there is a nice RGB on/off toggle using
Fn+zthat turns on or off the keys and side lighting, both of them or just one of them.
This is currently not possible - again, at the time of this writing - withRGB_TOGkeycode. See before in the keymap that I’m setting this accessible by default (layer 0, without having to useFn) on top right, instead of Delete key, that has a different position(s). -
“Shortcuts” for Undo, Cut, Copy, and Paste are currently not working.
Based on what is documented, available also in QMK Configurator, and used in my other GMMK Pro cases (one such example),KC_UNDO,KC_CUT,KC_COPY,KC_PSTEkey codes are not working as expected.
The desire is to useFn(CapsLock in this case) plus the standard z, x, c, v keys, instead of trying to reach to Ctrl key.
That’s quite a story, long, but hopefully helpful for this community and Glorious team itself to improve the official docs on the subject.
Take care and enjoy life and your keyboard(s)!
