QMK Basics

QMK (Quantum Mechanical Keyboard) is the most widely used open-source keyboard firmware. It runs on wired keyboards and supports extensive customization.

What QMK does

QMK handles everything between your keypress and your computer seeing a USB HID event. That includes: key mapping, layers, macros, tap-dance, combos, lighting, OLED displays, and more.

How to configure

There are three ways to configure QMK:

1. VIA / Vial — A GUI app that lets you remap keys in real-time without reflashing. Your keyboard must have VIA support enabled. 2. QMK Configurator — A web-based tool that generates firmware files. Simpler but less flexible. 3. Direct code editing — Edit `keymap.c` and `config.h` in your keyboard's QMK directory. Most flexible, steepest learning curve.

Key concepts

Layers: Like transparent sheets stacked on top of your base layout. Hold a key to activate a layer, and all keys temporarily change function.

Macros: Record a sequence of keypresses and trigger them with a single key.

Tap-Dance: One key does different things depending on how you tap it. Tap once for Escape, tap twice for Caps Lock, hold for Ctrl.

Combos: Press two keys simultaneously to trigger a third action. Like pressing J+K to send Escape.

Flashing

To install QMK firmware: 1. Put your keyboard in bootloader mode (usually by pressing a reset button or a key combination) 2. Use QMK Toolbox or the command line to flash the .hex or .bin file 3. The keyboard restarts with the new firmware

On Pro Micro clones, you may need to double-tap the reset button. On RP2040 boards, it appears as a USB drive — just drag the .uf2 file.