How to Port a Keyboard to Vial

Updated

To port a keyboard to Vial, follow the two-stage process documented in the Vial manual: first create a JSON description file for your keyboard, then port the keyboard to Vial. Vial's documentation lists these as separate build-support guides ("Build support 1 - Create JSON" and "Build support 2 - Port to Vial"), so treat them as sequential steps. This path is for keyboard designers and enthusiasts who want their board recognized and configurable in the Vial GUI; if your keyboard already ships with Vial-compatible firmware, you don't need to port anything—the GUI detects it automatically.

What porting actually means

Vial is an open-source, cross-platform (Windows, Linux, Mac) GUI and a QMK fork for configuring a keyboard in real time. Porting means making your keyboard's firmware Vial-compatible so the GUI can detect it and expose its layout, layers, and features for live configuration. The Vial project is fully open, with sources for all components publicly available on GitHub.

Step 1: Create the JSON description

The first build-support guide is "Create JSON." This file describes your keyboard to Vial—its layout and related definitions—and is the foundation the porting step builds on. Complete this before moving to the port itself; the manual presents it as build support step 1 for a reason.

Step 2: Port to Vial

The second guide, "Port to Vial," covers the actual porting work. Work through it after your JSON description exists. The manual's sidebar also links related build-support topics you may need depending on your board's hardware, including:

  • Rotary encoder support
  • Backlight and RGB lighting
  • MIDI support
  • Custom keycode
  • Selecting Vial GUI features (for size)

These are supporting references, not prerequisites for every keyboard—consult the ones that match your hardware.

Verify the port

Once a Vial-compatible firmware is installed on the keyboard, the Vial GUI detects it automatically. That auto-detection is your practical check that the port succeeded: install the firmware, open the GUI, and confirm the keyboard is recognized and configurable.

Where to go next

  • User manual: linked from the Vial site; read the entries in the left sidebar for usage and porting details.
  • Download Vial / Start Vial Web: entry points on the site for the desktop GUI or the web version.
  • Community: the project runs a Discord server for questions.
  • Feedback: feature suggestions go to the dedicated feedback website.

If you get stuck, the manual's porting guide and the related build-support pages are the authoritative references; the Discord server is the place for problems the docs don't cover.