Configuring QMK

Overview

VIA communicates with compatible firmware over USB and stores dynamic keymaps, macros, layout options, and other supported settings in the keyboard's non-volatile memory.

Adding an officially supported QMK keyboard to VIA now involves three repositories:

1. The keyboard implementation must be merged into QMK Firmware.
2. Its via keymap must be merged into VIA's QMK Userspace.
3. Its keyboard definition must be merged into VIA Keyboards.

VIA keymaps are no longer accepted in the main QMK Firmware repository. They are maintained and built from VIA's external QMK userspace instead.

Create the VIA keymap

Fork VIA's QMK Userspace and create:

keyboards/<keyboard_name>/keymaps/via/

The keyboard path must match the path already merged into QMK Firmware.

rules.mk

At minimum, add:

VIA_ENABLE = yes

The value yes must be lowercase. Keep VIA_ENABLE at the keymap level; the keyboard's default firmware should not enable VIA automatically.

Some optional, keymap-specific features still belong here. For example, a VIA keymap with configurable encoders uses:

ENCODER_MAP_ENABLE = yes

To make QMK console output available to VIA's optional HID Console tab, enable:

CONSOLE_ENABLE = yes

Enabling the console increases firmware size and consumes USB endpoint resources on some controllers, so enable it only when it is useful.

keymap.c

Add a keymap.c containing a complete, usable default keymap. Use the most complete LAYOUT_*() macro exposed by the keyboard so every electrical switch position that VIA may configure is represented.

VIA initializes its dynamic keymap storage from this keymap the first time the firmware runs. Later changes to keymap.c will not appear until the keyboard's EEPROM is cleared.

By default, VIA provides four dynamic layers. QMK fills any unspecified positions with KC_TRNS, so the source keymap does not need filler layers purely for VIA.

If the keyboard has encoders, define an encoder map with the same number of layers configured for the dynamic keymap. See Layouts: Rotary Encoders.

Configure the keyboard in QMK info.json

Hardware configuration belongs in the keyboard's QMK info.json. Prefer QMK's data-driven properties over equivalent legacy config.h defines or keyboard-level rules.mk options whenever a JSON property exists.

USB identity

VIA uses the keyboard's USB vendor and product IDs to find its definition:

{
  "keyboard_name": "WT60-D",
  "usb": {
    "vid": "0x6582",
    "pid": "0x0001",
    "device_version": "1.0.0"
  }
}

Do not add the legacy VENDOR_ID, PRODUCT_ID, DEVICE_VER, or PRODUCT defines to config.h. QMK derives those values from usb and keyboard_name.

The VID/PID pair must uniquely identify keyboards that require different VIA definitions. Hardware revisions may share the same pair when their VIA-visible matrix, layouts, and configurable features are compatible.

Matrix and layouts

Define matrix pins, diode direction, and layouts in info.json. The matrix dimensions generated by QMK must match the matrix.rows and matrix.cols values in the VIA definition.

The VIA layout should use a QMK layout that exposes every configurable switch position. Layout macros and physical layout data can also be generated from QMK's data-driven layouts property instead of being maintained manually in a keyboard header.

Bootmagic

If the keyboard's Bootmagic key is not at matrix position [0, 0], configure it in info.json:

{
  "bootmagic": {
    "enabled": true,
    "matrix": [3, 4]
  }
}

Use a position that is present in every supported physical layout, normally the top-left key. Holding it while connecting the keyboard resets EEPROM and enters the bootloader.

Encoders

Encoder hardware should also use QMK's data-driven configuration:

{
  "encoder": {
    "enabled": true,
    "rotary": [
      {"pin_a": "B12", "pin_b": "B13", "resolution": 4}
    ]
  }
}

ENCODER_MAP_ENABLE remains a keymap-level option because it changes how that particular keymap handles the encoder.

Dynamic layer count

The default is four layers. Configure another count in info.json only when required:

{
  "dynamic_keymap": {
    "layer_count": 6
  }
}

The encoder map and default keymap must remain compatible with this count. More layers consume additional non-volatile memory; fewer layers can save memory and firmware space.

Link-time optimization

If firmware size is tight, enable link-time optimization through info.json:

{
  "build": {
    "lto": true
  }
}

This is the data-driven replacement for adding LTO_ENABLE = yes to a keyboard-level rules.mk. Test the resulting firmware on the target controller.

VIA-specific firmware settings

Not every VIA setting has a data-driven QMK equivalent. Put these advanced overrides in the VIA keymap's config.h only when required.

VIA_FIRMWARE_VERSION

VIA_FIRMWARE_VERSION is an unsigned 32-bit keyboard firmware version exposed through the VIA protocol. It defaults to 0.

#define VIA_FIRMWARE_VERSION 5

Use it when one VID/PID must support firmware revisions with different custom controls. A V3 definition can test the value with showIf, for example:

"showIf": "{id_firmware_version} >= 5"

See Firmware-version conditions.

VIA_EEPROM_LAYOUT_OPTIONS_SIZE

This controls the number of bytes reserved for layout options, from 1 to 4, and defaults to 1. Increase it only when the definition's layout choices require more than eight bits in total.

VIA_EEPROM_CUSTOM_CONFIG_SIZE

This reserves non-volatile storage for keyboard-specific configuration and defaults to 0. Keyboard code can use VIA_EEPROM_CUSTOM_CONFIG_ADDR as the beginning of the reserved region. Ensure the region does not overlap dynamic keymaps or macros.

Protocol and QMK keycode versions

Current QMK automatically reports both the VIA protocol version and its QMK keycode version. VIA uses these values to select the correct keycode dictionary.

• VIA protocol 12 and earlier use the legacy unified RGB_* lighting keycodes.
• VIA protocol 13 uses the current separate UG_* RGBLight and RM_* RGB Matrix keycodes.
• A protocol-13 keyboard with a missing, malformed, or unsupported QMK keycode-version response is reported on VIA's Errors page and is not initialized for remapping.

Firmware based on current QMK does not need a custom handler for the keycode-version value.

EEPROM memory usage

VIA uses non-volatile memory in this general order:

1. QMK core data
2. VIA metadata and layout options
3. Optional VIA custom configuration
4. Dynamic keymaps, including encoder maps when enabled
5. Dynamic macros

Exact addresses depend on the controller and enabled features. If the firmware does not fit, first reduce dynamic_keymap.layer_count, macro storage, or optional features. Increase custom configuration storage only after checking the resulting memory layout.