← More about keyboards

Certain topics come up pretty regularly on r/olkb, so I’ve collected some thoughts here. Each section includes a section link 🔗 for easy sharing.

If you don’t find what you are looking for here, try also the Keymap FAQ in the QMK documentation and Links about keyboards.

Meta: How to ask for help

🔗 Link

r/olkb and r/MechanicalKeyboards are great places to ask for keyboard troubleshooting help. Here are some suggestions to make it easier for others to help you:

Instead of saying something “doesn’t work,” be specific about what steps produce the problem (say, a certain sequence of button presses), and clarify what you want to happen vs. what actually happens. Or alternatively, state what is your goal and what is the problem.

Include details and any research. When troubleshooting QMK keymap code, of course, share the relevant part of your keymap. If possible, share a link to your full keymap as well. An easy way to do this is as a GitHub Gist.

How long to get used to a split columnar keyboard?

🔗 Link

It took me a couple weeks of use to adapt to typing on a split columnar keyboard. Others have reported similar experience. My first such keyboard was a Dactyl Ergodox, which in addition to being split and columnar is also concave.

Dactyl Ergodox

I was fumbling at first. It took practice and patience to develop the right muscle memory. Additionally, if there are non-standard quirks to your typing habits, you might need to correct for that. I initially wanted to type the key in Y QWERTY position with my left hand, but on a split keyboard that cross-hand jump becomes a big one!

But it’s definitely worth it. A columnar split keyboard makes it easier to keep wrists straight while typing with hands at a relaxed shoulder width apart. It’s the most effective change I’ve made for my typing comfort.

Should I use a wrist rest?

🔗 Link

Wrist rests are not necessary for good ergonomics. I don’t use them myself. If anything, a wrist rest should support the heel or palm of the hand, not the wrists. Pressure on the soft area of the wrist puts pressure on the tendons and nerves.

From Ergonomic Usage of Wrist Rests and Palm Supports:

In the vast majority of cases, wrist rests do not provide any significant ergonomic benefit and in fact will usually increase the number of risk factors for injury in your computer workstation. The reason is that if you ‘rest’ your ‘wrist’ on any type of support, be it foam, gel, webbing, cloth, etc. you are applying pressure to the underside of your wrist which will compress the tissues, resulting in decreased blood flow. More specifically, you can compress the carpal tunnel and possibly pinch the median nerve, which can lead not only to long term injury, but short term symptoms such as tingling, numbness or coldness in the hands, and finger muscles which fatigue quicker due to reduced circulation.

OSHA on Wrist/Palm Supports:

Potential Hazards

Possible Solutions

Related reading:

Should I learn how to touch type?

🔗 Link

Do you want better speed, accuracy, and typing comfort? Then the answer is yes. Learning proper touch typing technique helps all of that.

Touch typing is a style of typing. The eight fingers are placed along the home row, and each finger has designated keys that it can reach. This systematic method lets you type each key with little motion and by sense of touch alone, enabling you to type faster and more efficiently. Additionally, it reduces neck strain and improves posture by keeping your eyes on the screen, not constantly glancing at the keyboard to find the keys.

Resources to learn touch typing:

Related reading:

Pressing a key sometimes types it twice

🔗 Link

When you press a key once, does it sometimes type twice (or more)? A common cause is contact bounce (or chatter) in the key switch. Electrical contacts are usually springy material. When the switch is pressed, the contacts bounce, making and breaking contact for some milliseconds before settling to a steady contact. So rather than a clean 0 to 1 transition, the raw digital reading bounces between 0 and 1.

A similar bouncing problem occurs in the other direction when the key is released. The settling time depends on the kind of switch and may be different for press vs. release. Additionally, the settling time tends to increase as the switch is worn from use. Some keys are pressed more frequently than others (extreme example: E key vs. the [ key), so switches wear down at different rates. This can explain observing bouncing on some keys but not others, especially if you reused some switches.

Diagnosis: Go to the QMK Configurator test page and press each key (this works also for non-QMK keyboards). If any key events appear suspiciously fast, a message appears “CHATTER HAS BEEN DETECTED” and the key is highlighted red.

Software troubleshooting: It’s typical to apply filtering algorithms in software to “debounce” the button. (See the Related reading below for several algorithms.)

Hardware troubleshooting:

Related reading:

Home row mods are hard to use

🔗 Link

It’s not just you. Home row mods are tricky for most people. Configuration is critical, and on top of that it takes time to get used to it.

Home row mods are nontrivial to use reliably because of accidental mod triggers during fast typing. You might think of normal typing as pressing and releasing one key at a time like “T down, T up, H down, H up.” But fast typing is often sloppier than this like “T down, H down, T up, H up,” especially in “rolled” sequences of adjacent keys like io or ast in QWERTY. There’s also the complementary problem of failing to trigger a mod when it was intended.

If you haven’t already, read Precondition’s guide to home row mods. It explains a bunch of tap-hold configurations and variations to mitigate these problems.

Suggested settings:

In addition to good configuration, I suggest you may need a couple months to get used to home row mods. Everyone’s typing habits are a little different. I struggled badly when I started with accidental mod triggers, despite using Precondition’s recommended settings. But after a couple months of persistence, my typing adapted. Now I use home row mods with confidence.

Other tips:

Firmware is too large!

🔗 Link

A build error like “firmware is too large! X bytes over” means the compiled firmware is too large to fit in the microcontroller’s programmable flash memory. This is easily a problem on microcontrollers with less than 32KB flash space.

This suggestion may come too late, but when building a keyboard, it’s worth using a microcontroller with larger flash space to avoid this problem in the first place. Some QMK-compatible options with more space are Proton C (STM32F303xC) with 256KB flash, WeAct Blackpill (STM32F411) with 512KB flash, and Nice Nano (nRF52840) with 1MB flash. See also QMK Compatible Microcontrollers and ZMK Supported Hardware.

Otherwise, you need to reduce the firmware size. The main contributors to firmware size are enabled features. By “feature,” I mean a behavior that can be independently enabled, like Mouse Keys and Space Cadet Shift in QMK. Each enabled feature adds around 1000–4000 bytes, depending on what it is. So a good way to reduce firmware size is to cull unused and non-essential features.

Specific to QMK: Make sure to enable LTO (link-time optimization) in rules.mk:

LTO_ENABLE = yes

Firmware will take longer to build, but the result will be smaller. See Squeezing the most out of AVR (applicable also with non-AVR MCUs) for further tips.

Some keys are swapped (QMK)

🔗 Link

Magic keys: Magic keys and a related Command feature are capable of dynamically disabling GUI keys, swapping Ctrl ↔︎ Caps Lock, Alt ↔︎ GUI, and a few other similar such things. A common source of confusion is when these settings are changed unintentionally. Furthermore, magic settings are saved to EEPROM, so they stubbornly survive even when the keyboard is flashed with new firmware. The way to fix this is to clear the EEPROM, which resets any magic settings. Two ways to do that:

See also Some Of My Keys Are Swapped Or Not Working.

Non-US QWERTY host layout. The usual “KC_”-prefixed keycodes assume the host computer is configured to US QWERTY keyboard layout, see What Are the Default Keycodes. Configuring the computer to a different keyboard layout can result in swapped keys or some shifted keys producing unexpected results.

It’s not required that the keyboard itself is physically in QWERTY layout. You can arrange your QMK keymap to whatever you like. If you need to set the computer to a non-US QWERTY layout, you can include a header like #include "keymap_german.h" for alternative “DE_”-prefixed keycodes. See Additional Language Support. See also the next section regarding host layout and SEND_STRING().

Why is it like this? When making keyboards with other layouts, it is standard practice to reuse US QWERTY keyboard firmware and simply print different keycap labels. This mismatch is resolved by configuring the host computer to map key codes to the intended layout. From the Universal Serial Bus HID Usage Tables, section 10:

Where this list is not specific for a key function in a language, the closest equivalent key position should be used, so that a keyboard may be modified for a different language by simply printing different keycaps. One example is the Y key on a North American keyboard. In Germany this is typically Z. Rather than changing the keyboard firmware to put the Z Usage into that place in the descriptor list, the vendor should use the Y Usage on both the North American and German keyboards. This continues to be the existing practice in the industry, in order to minimize the number of changes to the electronics to accommodate other languages.

SEND_STRING doesn’t work (QMK)

🔗 Link

There are some gotchas with SEND_STRING():

What is this weird C syntax (QMK)

🔗 Link

QMK code is embedded code written in C11, the 2011 standard of the C programming language, with nonstandard GNU extensions. You may run into some unfamiliar syntax even if you are otherwise versed in C/C++:

← More about keyboards