Skip to main content

QMK & VIA Firmware Guide: Program Your Keyboard

8 min read

QMK & VIA Firmware Guide

Programming your keyboard unlocks its full potential. With QMK and VIA, you can create custom layers, macros, and personalized layouts without coding knowledge.

What Is Keyboard Firmware?

Firmware Explained

Definition: Firmware is software embedded in the keyboard that translates physical keypresses into computer input.

What It Controls:

  • Key mapping (which key does what)
  • Layers (multiple layouts on one keyboard)
  • Macros (shortcuts and automated sequences)
  • RGB lighting
  • Special features (tap dance, combos, mouse keys)

QMK Firmware

What Is QMK?

QMK (Quantum Mechanical Keyboard): Open-source keyboard firmware offering ultimate customization.

Features:

  • Custom key mapping
  • Multiple layers (up to 32!)
  • Macros and shortcuts
  • Tap dance (different actions for tap vs. hold)
  • Mouse keys (control mouse with keyboard)
  • Combos (press multiple keys for action)
  • RGB control
  • Audio (piezo speaker support)

Compatibility:

  • Most custom keyboards
  • Some prebuilt keyboards (Keychron Q-series, GMMK Pro)
  • DIY keyboard kits

Programming Method:

  • Edit code (keyboard firmware files)
  • Compile firmware
  • Flash to keyboard

Difficulty: Moderate - requires some technical knowledge but well-documented.

QMK Pros and Cons

Pros:

  • Ultimate customization
  • Open-source (free, community-driven)
  • Constantly updated
  • Massive feature set
  • Supported by most custom keyboards

Cons:

  • Requires compiling firmware (technical)
  • Steeper learning curve
  • Flashing process can be intimidating
  • Need to edit code (keymaps)

VIA

What Is VIA?

VIA: Graphical user interface (GUI) for QMK firmware. Makes programming easy without coding.

Features:

  • Real-time key remapping (no compiling/flashing!)
  • Drag-and-drop interface
  • Layer management
  • Macro creation (GUI-based)
  • Lighting control
  • Instant changes (live preview)

Compatibility:

  • Keyboards with VIA-enabled QMK firmware
  • Keychron Q-series, GMMK Pro, Mode keyboards
  • Many custom keyboards

Programming Method:

  • Open VIA app or website
  • Plug in keyboard
  • Drag keys to remap
  • Changes apply instantly

Difficulty: Easy - no coding required, visual interface.

VIA Pros and Cons

Pros:

  • Beginner-friendly (no coding)
  • Real-time changes (instant feedback)
  • Visual interface
  • No compiling or flashing
  • Saves settings on keyboard (persistent)

Cons:

  • Limited to keyboards with VIA support
  • Fewer features than full QMK
  • Some advanced QMK features unavailable

QMK vs. VIA Comparison

FeatureQMKVIA
Ease of UseModerate (requires coding)Easy (GUI)
CustomizationUltimateExtensive
Real-time ChangesNo (must flash)Yes
Macro CreationAdvanced (code-based)Simple (GUI)
Layer SupportUp to 32 layersUp to 4 layers (typical)
Advanced FeaturesTap dance, combos, etc.Limited
Flashing RequiredYesNo (once VIA-enabled)

Verdict:

  • Use VIA if you want easy, real-time remapping
  • Use full QMK if you need advanced features

Getting Started with VIA

Step 1: Check VIA Compatibility

Does your keyboard support VIA?

  • Check manufacturer website
  • Look for “VIA support” in specs
  • Search keyboard model + “VIA” online

Popular VIA Keyboards:

  • Keychron Q-series
  • GMMK Pro
  • Mode Sonnet/Envoy
  • KBDfans keyboards (many)
  • Most custom keyboards

Step 2: Download VIA

Options:

  1. Web version: https://usevia.app (no installation)
  2. Desktop app: Download from https://github.com/the-via/releases

Recommended: Web version is easiest (works in browser).

Step 3: Connect Keyboard

  1. Plug in keyboard via USB
  2. Open VIA (web or app)
  3. VIA should auto-detect keyboard
  4. Keyboard layout appears on screen

Troubleshooting:

  • If not detected, check if keyboard has VIA firmware
  • Try different USB cable/port
  • Restart VIA application

Step 4: Remap Keys

How to Remap:

  1. Click key you want to change (on virtual keyboard)
  2. Click new key from bottom panel
  3. Key instantly remaps!

Example:

  • Click Caps Lock key
  • Select “Backspace” from panel
  • Caps Lock is now Backspace

Step 5: Create Layers

What Are Layers? Multiple keyboard layouts accessed with a layer key.

Why Use Layers?

  • Access more functions on compact keyboards
  • Create specialized layouts (gaming, coding, media)
  • Eliminate need for function row on 60% keyboards

How to Add Layer:

  1. Click layer number at top (Layer 0, 1, 2, 3)
  2. Remap keys for that layer
  3. Assign layer toggle key (MO(1), TG(1), etc.)

Example:

  • Layer 0: Default typing layout
  • Layer 1: Media controls, arrow keys, function keys
  • Access Layer 1 by holding Fn key

Step 6: Create Macros

What Are Macros? Automated key sequences triggered by one key.

Uses:

  • Common phrases (“Best regards,”)
  • Code snippets
  • Application shortcuts
  • Passwords (use cautiously!)

How to Create Macro in VIA:

  1. Go to “Macros” tab
  2. Click empty macro slot
  3. Type text or key sequence
  4. Assign macro to key on keyboard

Example Macro:

  • Macro: “Best regards, [Your Name]”
  • Assign to unused key
  • One keypress types entire phrase

Getting Started with QMK (Advanced)

Step 1: Set Up QMK Environment

Prerequisites:

  • Basic command line knowledge
  • Text editor (VS Code recommended)
  • Git installed

Setup:

  1. Install QMK Toolbox (for flashing)
  2. Clone QMK firmware repo: git clone https://github.com/qmk/qmk_firmware.git
  3. Install QMK CLI: python3 -m pip install qmk
  4. Set up environment: qmk setup

Alternative (Easier): Use QMK Configurator (web-based): https://config.qmk.fm

Step 2: Find Your Keyboard

In QMK Firmware:

  1. Navigate to keyboards/ folder
  2. Find your keyboard brand/model
  3. Locate keymaps/ folder

Example: For Keychron Q1, go to: keyboards/keychron/q1/keymaps/

Step 3: Edit Keymap

Keymap File: Usually keymap.c in your keyboard’s keymap folder.

Basic Keymap Structure:

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    [0] = LAYOUT(
        KC_ESC,  KC_1,    KC_2,    KC_3,    // Row 1
        KC_TAB,  KC_Q,    KC_W,    KC_E,    // Row 2
        // ...
    ),
};

Key Codes:

  • KC_A to KC_Z: Letters
  • KC_1 to KC_0: Numbers
  • KC_ENT: Enter
  • KC_BSPC: Backspace
  • KC_SPC: Space

Full list: https://docs.qmk.fm/#/keycodes

Step 4: Add Layers

Layer Syntax:

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    [0] = LAYOUT( /* Base layer */
        KC_ESC,  KC_1,    KC_2,    MO(1),   // Hold 4th key for layer 1
    ),
    [1] = LAYOUT( /* Layer 1 - Media */
        KC_MUTE, KC_VOLD, KC_VOLU, _______,  // Media controls
    ),
};

Layer Keys:

  • MO(1): Momentary layer (hold to activate)
  • TG(1): Toggle layer (tap to switch)
  • LT(1, KC_SPC): Tap for space, hold for layer 1

Step 5: Compile Firmware

Command:

qmk compile -kb <keyboard> -km <keymap>

Example:

qmk compile -kb keychron/q1 -km default

Output: Compiled .hex or .bin file in qmk_firmware/ root.

Step 6: Flash Keyboard

Using QMK Toolbox:

  1. Open QMK Toolbox
  2. Load compiled .hex or .bin file
  3. Put keyboard in bootloader mode:
    • Press reset button on PCB, OR
    • Hold Esc while plugging in, OR
    • Use assigned reset key
  4. Click “Flash” in QMK Toolbox
  5. Wait for completion
  6. Keyboard reboots with new firmware

Common QMK Features

Tap Dance

What It Is: Different actions for tap vs. hold vs. double-tap.

Example:

  • Tap: E
  • Hold: Ctrl
  • Double-tap: Esc

Use Case: Maximize functionality on compact keyboards.

Mouse Keys

What It Is: Control mouse cursor with keyboard keys.

Use Case: Navigate without mouse (keyboard-only workflow).

Keys:

  • KC_MS_U: Mouse up
  • KC_MS_D: Mouse down
  • KC_BTN1: Left click
  • KC_BTN2: Right click

Combos

What It Is: Press multiple keys simultaneously for action.

Example:

  • Press J + K together = Esc

Use Case: Home row shortcuts, reducing pinky strain.

Auto Shift

What It Is: Hold key longer to get shifted version (no Shift key needed).

Example:

  • Tap A = a
  • Hold A (200ms) = A

Use Case: Reduce Shift key usage.

Layer Examples

Example 1: 60% Keyboard with Function Row Layer

Layer 0 (Base):

  • Standard QWERTY layout
  • No F-row or arrow keys

Layer 1 (Fn Layer):

  • Number row becomes F1-F12
  • WASD becomes arrow keys
  • Media controls on right side

Access: Hold Fn key to activate Layer 1.

Example 2: Gaming Layer

Layer 0 (Typing):

  • Standard layout

Layer 1 (Gaming):

  • Caps Lock → Crouch
  • Tab → Inventory
  • Q/E → Lean left/right
  • Media controls disabled (prevent accidental press)

Access: Toggle Layer 1 with Fn+G.

Example 3: Numpad Layer for 60%

Layer 0 (Base):

  • Standard layout, no numpad

Layer 1 (Numpad):

  • Right side of keyboard becomes numpad
  • 7 8 9 → Numpad 7 8 9
  • U I O → Numpad 4 5 6
  • J K L → Numpad 1 2 3

Access: Hold Fn to activate numpad layer.

Macro Examples

Example 1: Email Signature

Macro:

Best regards,
John Doe
john.doe@example.com

Use: One keypress types full signature.

Example 2: Zoom Controls

Macros:

  • Macro 1: Ctrl+Alt+A (mute/unmute audio)
  • Macro 2: Ctrl+Alt+V (start/stop video)
  • Macro 3: Ctrl+Alt+H (hand raise)

Use: Quick Zoom controls without remembering shortcuts.

Example 3: Code Snippets

Macro:

for (int i = 0; i < ; i++) {

}

Use: One keypress inserts common code structure.

Troubleshooting

Keyboard Not Detected in VIA

Solutions:

  • Check VIA compatibility
  • Update VIA firmware
  • Try different USB port/cable
  • Restart VIA application

QMK Compile Errors

Solutions:

  • Check syntax errors in keymap.c
  • Update QMK firmware: qmk update
  • Verify keyboard path is correct
  • Check QMK documentation for key codes

Flashing Fails

Solutions:

  • Ensure keyboard is in bootloader mode
  • Try different USB port (preferably USB 2.0)
  • Check .hex/.bin file path is correct
  • Verify QMK Toolbox has correct MCU selected

Keys Not Working After Flash

Solutions:

  • Reflash with known-good firmware
  • Check keymap for errors
  • Verify matrix pin configuration
  • Test with default keymap first

For 60% Keyboards

Layer 0: Standard typing Layer 1: Arrow keys (WASD), F-row (number row), media Layer 2: Numpad (right side) Layer 3: RGB control, reset, system functions

For 65% Keyboards

Layer 0: Standard typing (has arrows already) Layer 1: F-row, media controls Layer 2: Numpad, macros Layer 3: System functions

For 75% Keyboards

Layer 0: Standard typing (has F-row and arrows) Layer 1: Media controls, macros Layer 2: Advanced functions, RGB

Resources

Official Documentation

Community Resources

Takeaway

VIA is best for:

  • Beginners
  • Real-time remapping
  • Simple macros and layers

QMK is best for:

  • Advanced users
  • Complex features (tap dance, combos)
  • Ultimate customization

Start with VIA: Easy to learn, instant results.

Graduate to QMK: Once you need advanced features.

Programming transforms keyboards: Unlock efficiency, personalization, and workflow optimization.

Next Steps