QMK Firmware — Open-Source Keyboard Firmware for Custom Keyboards

Introduction

QMK (Quantum Mechanical Keyboard) Firmware is the standard open-source firmware for custom mechanical keyboards. It powers hundreds of keyboard PCBs and gives users programmable layers, tap-dance keys, macros, and per-key RGB control.

What QMK Does

• Provides a fully programmable keymap system with up to 32 layers per keyboard
• Supports tap-hold behavior, leader keys, combos, and one-shot modifiers
• Drives per-key RGB LEDs and underglow with dozens of built-in animation modes
• Handles pointing devices like trackballs, trackpoints, and encoders alongside keys
• Compiles via CLI or the online QMK Configurator without writing any C code

Architecture Overview

QMK is built on top of ChibiOS or LUFA depending on the microcontroller (ARM or AVR). The firmware scans a key matrix at high frequency, processes the keymap through a layered state machine, and sends HID reports to the host. Features are modular: users enable only what they need via rules.mk to keep firmware size within flash limits.

Self-Hosting & Configuration

• Install the QMK CLI via pip; it manages toolchains for AVR and ARM targets
• Each keyboard has its own directory under keyboards/ with hardware-specific pin definitions
• Keymaps live in keymaps/<username>/keymap.c and override defaults
• config.h and rules.mk control feature toggles like RGB, audio, and mouse keys
• Flash via QMK Toolbox (GUI), qmk flash (CLI), or supported bootloaders directly

Key Features

• Over 1,500 keyboards supported in the official repository
• QMK Configurator provides a visual drag-and-drop keymap editor in the browser
• VIA and Vial support allow live keymap changes without reflashing
• Tap Dance lets a single key perform different actions based on tap count
• Audio support on boards with speakers for feedback beeps and music mode

Comparison with Similar Tools

• ZMK — wireless-first firmware for BLE keyboards; QMK focuses on wired boards with broader feature support
• KMK — CircuitPython-based firmware; easier to modify but slower scan rates than QMK's compiled C
• TMK — QMK's predecessor; QMK adds layers of convenience and a larger community
• Via/Vial — GUI configurators that run on top of QMK firmware for real-time remapping
• Kaleidoscope — Arduino-based firmware for Keyboardio boards; QMK supports a wider range of hardware

FAQ

Q: Do I need to know C to use QMK? A: No. The QMK Configurator web tool lets you build keymaps visually. C knowledge helps for advanced features like custom macros or tap-dance logic.

Q: Can QMK run on wireless keyboards? A: QMK has experimental BLE support, but ZMK is generally recommended for wireless builds due to better power management.

Q: How do I add my custom keyboard to QMK? A: Create a directory under keyboards/ with your pin matrix, config files, and a default keymap. Submit a pull request to have it merged upstream.

Q: Does QMK support macOS, Windows, and Linux equally? A: Yes. QMK sends standard HID reports that work on all operating systems without drivers.

Sources

• https://github.com/qmk/qmk_firmware
• https://docs.qmk.fm