VIA Version 3 Changes

Introduction

In VIA Version 1, the UI and the keyboard definitions were entirely self-contained (i.e. hard-coded). Adding new keyboards requires changing code and rebuilding/releasing the app.

VIA Version 2 moved the keyboard definitions into externally defined files, which are stored in a GitHub repository. The keyboard definitions are served to the VIA client at runtime. This allowed anyone to add new keyboards to VIA without requiring changing the source and rebuilding/releasing the app.

VIA Version 2 keyboard definitions include layout options and control of lighting, but definitions were restricted to the existing UI elements.

VIA Version 3 is a refactoring of how the UI works in VIA, to allow fully customized UI within VIA to control firmware parameters like lighting, but also any custom feature implemented in the firmware, either in QMK Core or at the keyboard level. It works by defining what UI elements VIA should show, and binding those UI elements to IDs, which VIA will use in communication with the firmware.

This page documents the historical transition from V2 to V3 definitions and VIA protocol 11. For capabilities added after the original V3 release, see Changes Since VIA Version 3.

Keyboard Definition Changes for VIA V2 to V3

This describes the changes made between V2 and V3.

Lighting

The lighting element is deprecated and replaced by specifying one or more of the following in the menus element:

"qmk_backlight"
"qmk_rgblight"
"qmk_backlight_rgblight"
"qmk_rgb_matrix"

and/or defining the custom UI in the menus element.

Example:

"menus": [ "qmk_rgb_matrix" ]

Additionally, a lighting keycode module can be added to the keycodes element. New definitions should select the module that matches the QMK lighting subsystem.

Example:

"keycodes": [ "qmk_rgb_matrix_keycodes" ]

The explicit modules are qmk_backlight_keycodes, qmk_rgblight_keycodes, qmk_rgb_matrix_keycodes, and qmk_backlight_rgblight_keycodes. The older qmk_lighting value remains as a compatibility fallback and must not be combined with an explicit module. See Keycodes for protocol-specific behavior.

The menu and matching keycode module are all that is required to expose the stock QMK lighting controls and keycodes.

Menus

The menus element is new in V3 and is used to define the UI (also known as menus) in VIA. It replaces how lighting control is defined and allows other runtime parameters of keyboard firmware to be configured.

For example, a keyboard definition for a keyboard that uses the QMK RGB Matrix feature would have the following menus element:

"menus": [ "qmk_rgb_matrix" ]

However, the menus element can contain a complete definition of custom UI, allowing full customization of the lighting page, or other custom feature requiring control by VIA.

For example, the item "qmk_rgb_matrix" in the menus element can be replaced with the equivalent custom UI definition to control the QMK RGB Matrix feature, such as:

"menus": [
  {
    "label": "Lighting",
    "content": [
      {
        "label": "Backlight",
        "content": [
          {
            "label": "Brightness",
            "type": "range",
            "options": [0, 255],
            "content": ["id_qmk_rgb_matrix_brightness", 3, 1]
          },
          ...

The use of "qmk_backlight", "qmk_rgblight", "qmk_backlight_rgblight" and "qmk_rgb_matrix" in the menus element causes VIA to use the default UI definition that matches the firmware that is built when enabling these features. Firmware authors can replace these with custom UI definitions that are identical, and then change them to match changes made to the firmware.

The built-in UI definitions are located in the repository here.

The complete documentation for custom UI is here.

Firmware Version

"firmwareVersion": 0

firmwareVersion was introduced as metadata for versioning custom UI definitions. It defaults to 0 when omitted.

Current VIA also reads VIA_FIRMWARE_VERSION directly from the connected keyboard. When custom controls differ between firmware releases, use the firmware value in a showIf expression:

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

This lets one definition support old and new firmware safely instead of requiring another VID/PID or definition. See Firmware-version conditions.

VIA_FIRMWARE_VERSION is different from the VIA protocol version (VIA_PROTOCOL_VERSION in QMK). The protocol version describes the shared VIA command format; the keyboard firmware version describes revisions of one keyboard's features.

QMK Changes for VIA V2 to V3

VIA V2 definitions are used for QMK firmware built with VIA Protocol 10 or less. VIA V3 definitions are used for QMK firmware built with VIA Protocol 11 or greater.

VIA will continue to function with existing firmware that was built with VIA Protocol 10 or less, by using the VIA V2 definition.

All V2 definitions were converted to equivalent V3 definitions in the repository, so that firmware built using VIA Protocol 11 will function as expected.

The following describes the changes in QMK between VIA Protocol 10 and 11.

Commands

The commands for setting/getting lighting values have been replaced with commands for setting/getting "custom" values. Custom values can be for lighting or any other feature.

This in VIA Protocol 10:

enum via_command_id {
    ...
    id_lighting_set_value                   = 0x07,
    id_lighting_get_value                   = 0x08,
    id_lighting_save                        = 0x09,
    ...
}

Is now this in VIA Protocol 11:

enum via_command_id {
    ...
    id_custom_set_value                     = 0x07,
    id_custom_get_value                     = 0x08,
    id_custom_save                          = 0x09,
    ...
}

The "arguments" for these commands have changed between VIA Protocol 10 and VIA Protocol 11.

In VIA Protocol 10, the id_lighting_set_value and id_lighting_get_value commands were followed by the ID of the value to set/get (which could be of enum via_lighting_value), then followed by the value data.

In VIA Protocol 11, the id_custom_set_value and id_custom_get_value commands are followed by a channel_id, then followed by the ID of the value to set/get, which could be of:

enum via_qmk_backlight_value
enum via_qmk_rgblight_value
enum via_qmk_rgb_matrix_value
enum via_qmk_audio_value
enums for other features in QMK
enums defined at the keyboard level

channel_id serves two main purposes.

First, it acts as a qualifier to value_id, allowing multiple enums with overlapping integer ranges to be used, rather than a single enum that must be the superset of all values for all features, which was a limitation of VIA Protocol 10. This makes it modular and extendable. When a new feature is added to QMK which could be controlled by VIA, a new default channel_id value can be defined, a new enum of possible value_id can be defined, set/get value command handlers implemented, and default UI defined in VIA, all without affecting the existing ID ranges and command handlers.

Secondly, it supports easy routing of set/get value commands for a feature to appropriate handlers for that feature. This allows firmware authors to easily use any of the default handlers with no extra coding required, and optionally use channel_id value to route some commands to the default handler, and some commands to a custom handler at the keyboard level. For example, a keyboard with RGB lighting and an OLED display can use the default handler for QMK RGBLIGHT, and route commands for OLED control to a custom handler at the keyboard level.

In the VIA keyboard definition, when defining UI controls in the menu element, each UI control has a content element which binds that control to a channel_id and value_id.

"label": "Backlight",
"content": [
    {
    "label": "Brightness",
    "type": "range",
    "options": [0, 255],
    "content": ["id_qmk_rgb_matrix_brightness", 3, 1]
    },

In this example, 3 is the channel_id (which matches the channel in QMK) and 1 matches enum value id_qmk_rgb_matrix_brightness in enum via_qmk_rgb_matrix_value. The string "id_qmk_rgb_matrix_brightness" is the value_key, used by VIA as a unique key.

Keyboard Values

Keyboard values are used for getting/setting core VIA features like layout options. In VIA Protocol 11, two new values were added:

enum via_keyboard_value_id {
    ...
    id_firmware_version    = 0x04,
    id_device_indication   = 0x05
};

id_firmware_version returns VIA_FIRMWARE_VERSION to VIA. Current VIA also exposes it as id_firmware_version in custom-UI showIf expressions.

id_device_indication is set by VIA to allow the device to indicate that it is being configured. This is a refactoring of how VIA V2 would cause a keyboard with RGB backlighting to flash on/off when it became the keyboard being configured, which was done by sending id_lighting_set_value commands. This feature was refactored to be device agnostic. The default handler via_set_device_indication() will toggle any enabled QMK lighting feature and/or trigger audio playback. It can be overridden and customized at the keyboard level.

Introduction​

Keyboard Definition Changes for VIA V2 to V3​

Lighting​

Menus​

Firmware Version​

QMK Changes for VIA V2 to V3​

Commands​

Keyboard Values​