The short version: The Keychron V5 mechanical keyboard is fully capable of macros, including mouse operations (e.g., right-click). This is enabled by the use of QMK and the length of macros is only limited by the available flash memory in the keyboard’s microcontroller (unlike the Cooler Master ‘CK550 V2’). A showstopper may be that there isn’t any easy way of cancelling macros in progress (a missing feature of all QMK-based keyboards). It is possible to cancel macros in QMK, but it isn’t standard and requires significant programming effort (or maybe it already exists somewhere?).
As a 96% keyboard, it is also crippled by the missing PgUp, PgDn and context menu key keys; a workaround is presented here.
Another showstopper may be that very bright RGB light bleeds to the sides (from the so-called south-facing LEDs). This makes the RGB lighting almost useless: In order to see the legends on the keys (e.g., in darkness or in a low-light conditions), the brightness must be fairly high. But at the normal viewing angle, this bleeds so much light to the side (towards your eyes) that it blinds you. The only way to use it is to lower the brightness, so that the legends are very subtly visible, with the stray light not blinding too much. Or perhaps to make a modification to the keyboard to stop the stray light (this hasn’t been tried yet).
Introduction
The Keychron keyboards (Q and V series only, not the more common K series) are the only QMK-capable commercial keyboards which are widely distributed, that is, are possible to buy locally. There are a lot of specialised QMK keyboards (but getting them involves more hassle, higher cost, long waiting times, and credit card risks), and/or they are crippled by not being full-size keyboards.
QMK enables full programmability, incl. macros, keymapping, any keyboard layout you can imagine or dream up (e.g., Colemak), and full control of the RGB lighting. This can be done by raw C coding or by a number of solutions that hides/abstract it (at the cost of sacrificing some of the flexibility). For instance, there are web sites where you can design the keymap and get a firmware file as the result, without touching a single line of code (but the macro capability is completely absent). The only remaining step is then to get the firmware onto the keyboard. There are tools to hide that process as well, though it is as simple as a single command line to flash the firmware (e.g., using AVRDUDE (is installed with the Arduino IDE) for AVR-based keyboards or dfu-util for keyboards with ARM (like the V5 described here)).
The Keychron V5 is much more reasonably priced, and the assembled version is the way to go. Doing this piecemeal by getting an overpriced Q-series PCB-only keyboard and sourcing the switches and keycaps on your own is both expensive and troublesome. The selection of switches may or may not be limited anyway (only available from Keychron?).
Like most of the Keychron keyboards, the switches are hot-swappable.
Macros
Macros are not really a part of QMK. It is more like a convention enabled by the ability to override (in function process_record_user()) the processing of key presses and key releases. That is, there isn’t any explicit support for macros in QMK.
Mouse actions, e.g. right click
The action part of a QMK macro to open the link under the mouse cursor in Firefox (right-click and select “Open Link in New Tab” by pressing “T”):
SEND_STRING(SS_TAP(X_MS_BTN2));
SEND_STRING(SS_DELAY(400)); // Wait... This is crucial
// for this to work.
SEND_STRING(SS_TAP(X_T));
Using Via to prototype macros
Via enables a very quick turn-around for developing macros: Macros can be recorded, the timings between key presses and key releases changed, and they are applied immediately (if a keymapping has been created). But it can not be used for any serious use of macros, only for prototyping.
Drawbacks:
- Mouse actions (e.g., right-click) are not supported
- Definitions must be restored after every flash (e.g., from stored JSON files with the Via definitions). They are stored in (emulated) EEPROM and thus often wiped out.
- There is a maximum of 15 macros
- By default, there is very little memory for macros (as the default configuration is emulating traditional EEPROM memory with only 1 or 2 KB of memory). There is only space for about 150 key actions in total (both key presses, key releases, and modifier keys (both key presses and key releases) count). Though it can be changed to be essentially unlimited.
- The macros don’t have names, only numbers. And there isn’t any way to annotate them, e.g., to document their purpose. This must be done by some external means
Note: Via runs just fine standalone. It does not require a web browser (in particular, Google Chrome)
Note: The content of an existing macro is wiped out without warning if “RECORD KEYSTROKES” is pressed (it doesn’t append the new recording (or respect the user’s time defining the original macros)). But it is possible to append (or prepend) a new recording by this technique:
- First save off the source for the macro: Click on the “</>” icon and copy/paste the content.
- Go back to the original view by clicking on the icon to the left.
- Record. Stop recording. Save changes.
- Click on the “</>” icon and paste the saved content from step 1, e.g., prepending or appending. Press Save.
- Go back to the original view by clicking on the icon to the left.
Crippled by not being a full-size keyboard
I would recommend getting the full-size keyboard Keychron V6 instead, but availability may be a problem (e.g., a long wait time). This is a general statement about 96% (and less) keyboards, not just this one. The small-form factor cult never mentions the compromises and drawbacks.
The numbering scheme for the Keychron V series is confusing, but here is an overview:
- V4: 60%
- V2: 65%
- V8: 65% (Alice Layout, a la Microsoft Natural Keyboard)
- V7: 70%
- V1: 75%
- V10: 75% (Alice Layout)
- V3: 80% (TKL (tenkeyless))
- V5: 96% (“1800”). Covered in this blog post.
- V6: 100%
There isn’t any less confusion by the numbering scheme being completely different for the K series:
- K12 PRO: 60%
- K9 PRO: 60% (slim/low profile)
- K6 PRO: 65%
- K7 PRO: 65% (slim/low profile)
- K11 PRO: 65% (Alice Layout, a la Microsoft Natural Keyboard. Slim/low profile)
- K14 PRO: 70%
- K2 PRO: 75%
- K3 PRO: 75% (slim/low profile)
- K8 PRO: 80% (TKL (tenkeyless))
- K1 PRO: 80% (TKL (tenkeyless). Slim/low profile)
- K13 PRO: 85%??? (“numpad TKL”. Slim/low profile)
- K4 PRO: 96% (“1800”)
- K10 PRO: 100%
- K5 PRO: 100% (slim/low profile)
But at least the Keychron V5, being fully programmable, enables providing workarounds.
Missing PgUp/PgDn keys
PgUp and PgDn are very commonly used and must be available as dedicated keys. Having to use a modifier key is not acceptable.
I already had most keys on the numeric keypad part used for macro keys, but as a workaround/compromise, I used these:
- Numeric keypad ‘3’: PgUp
- Numeric keypad ‘.’: PgDn
This was first prototyped by key assignments in Via and then later put into QMK proper by changing the keymap.
A further compromise is moving the lesser used macros to the Fn layer. But it is not ideal. The whole point of macros is to save unnecessary keypresses, in particular modifier keys for the shorter key sequences.
Missing context menu key
To the right of the space bar, there is the extra Fn key, but as there are only three keys, the context menu key is missing. This is also heavily used. Other keyboards with an Fn key has four keys and the right Windows key can be used as the context menu key instead.
As a compromise, I repurposed the Num Lock key on the numeric keypad as the context menu key. I don’t use the numbers on the numeric keypad (I repurpose it as a macro pad), but a workaround is to use the Num Lock key on some other keyboard, e.g. a cheap wireless separate numeric keypad. Or an old (rubber dome) keyboard. For the former, it can be used as dedicated as such (though the keys may not be that great).
Blues setting up the default RGB lighting configuration in QMK
The factory RGB lighting defaults are very irritating: An animation. Like all other keyboards, the factory default RGB lighting settings ought to be a static / steady lighting mode with some acceptable colour, like green, blue, or white.
Manually changing the RGB lighting settings
Setting mode, colour, and brightness to get a steady green of not too high brightness:
- 18 times Fn + Q to get to a static mode (it is 10 times in the original version of the firmware). There are 22 lighting modes (the official version 1.1 (2023-05) of the firmware) in total (13 in the original version of the firmware).
- 10 times Fn + E (hue) for a green colour. The saturation can be changed with Fn + R / F (lower value is towards white).
- Change brightness by Fn + knob (or Fn + W/S)
Changing the default settings in QMK
Changing the QMK firmware to use the proper RGB lighting settings is the only long-term solution. Having to set them every time the firmware is updated, is too cumbersome.
However, this does not work by following the official documentation (overriding eeconfig_init_kb() and making the appropriate calls to change the (persistent) settings). It seems enabling Via (at compile time) interferes: Any (or most) changes to RGB settings seems to be overwritten. That is, using eeconfig_init_kb() does not have any effect (but it is actually called (see appendix B)).
The fix
It is probably due to some bug in QMK, but I found a workaround that works: Defer changing the RGB settings to function keyboard_post_init_user(). keyboard_post_init_user() is called once per powerup, but use a custom (persistent) setting to set a flag (so changing the RGB settings is only executed right after flashing, at the first powerup) in function eeconfig_init_kb(). Using this fix, these four calls enables the default settings of RGB lighting to be with a dim steady green colour:
rgblight_mode(0);
// <https://docs.qmk.fm/#/feature_rgb_matrix?id=rgb-matrix-effects>
rgblight_sethsv_noeeprom(85, 255, 60);
// Enable RGB lighting by default
rgblight_toggle();
rgb_matrix_toggle();
This is described in detail in Appendix B, incl. some techniques for debugging at startup time (where it seems the output of printf function is not possible to capture).
Cancelling macros in progress
QMK, and thus this keyboard, does not come with a mechanism to cancel macros in progress, but with a sufficient amount of programming, it is possible. Though only for custom macros; it is probably practically infeasible for Via macros.
Appendix A: Detailed information about the Keychron V5 keyboard
Switches
Keychron K Pro, for example, brown. Pre-lubed. Hot-swappable. MX stem compatible.
The PCB accepts 5-pin Cherry MX switches: “The Cherry MX switches are fully compatible with our Keychron keyboard mechanical (hot-swappable) versions”
Disclaimer: The information about compatible switches has not been confirmed. Buy at your own risk!
Some compatible switches: Gateron G Pro 2.0 (lubed), Gateron Phantom (not lubed), and Gateron Ink V2. For example, Gateron G Pro 2.0 Black (linear. 60 g), Gateron G Pro 2.0 Yellow (linear. 60 g), and Gateron Phantom Yellow (linear. 50 g).
May or may not be somewhat compatible (the RBG light may not be compatible): Cherry MX Silver (linear. 45 g).
Note that the LEDs are mounted on the PCB and are south-facing.
Keycaps
Material: PBT
Other features
Has a volume knob (can be repurposed for other things, using QMK).
Firmware
Official firmware (despite the misleading title. See near “Download the V5 firmware”). The latest is firmware version 1.1 (2023-05-01).
Microcontroller
STM32L432 (source). Datasheet.
128 KB flash memory. 64 KB RAM.
There isn’t any EEPROM memory (for storing persistent settings, like the Via configuration, incl. the macro definitions) on chip. It may or may not use a serial external EEPROM chip (using I²C to communicate), but QMK probably emulates EEPROM in flash memory.
Appendix B: Debugging the RGB lighting settings blues, likely caused by Via
Main debugging technique: As print debugging doesn’t appear to be working at startup time (at least not without having physical access to the microcontroller’s serial port I/O pins), this can be used instead:
A (calibrated) blocking busy wait (three nested for loops, each with less than a 65535 loop count) is used to get out the required information. We use the fact that the RGB lights come on after the startup has completed. If RGB lights are not on (but they are with the default firmware), we can instead tap a key very fast and time when it starts registering (presumably at the end of the startup period).
Or in other words, we insert delays of known length into functions to deduce whether they are actually called or not (e.g., depending on whether it is the very first powerup after flashing or subsequent powerups). The two functions eeconfig_init_kb() and keyboard_post_init_user are call-back functions (called by QMK) that we don’t have control over. eeconfig_init_kb() is supposed to be called only once, right after flashing and keyboard_post_init_user is supposed to be called for every powerup (both right after flashing and subsequent powerups).
For instance, if we insert a delay of 31 seconds in eeconfig_init_kb() and 7 seconds in keyboard_post_init_user, we expect the first startup to last 31 + 7 = 38 seconds and subsequent startups 7 seconds.
This can also be used to verify that eeconfig_init_kb() is only called once after flashing; in all subsequent powerups, QMK is only supposed to call keyboard_post_init_user(), not eeconfig_init_kb().
Strangeness observed: eeconfig_init_kb() could be called two times, based on an observed startup time after flashing of 31 + 31 + 7 = 69 seconds instead of the expected 38 seconds (depending on the calls it contained)! This behaviour may or may not also depend on whether Via is enabled at compile time.