Step-By-Step Guide To Setting up VIA for the Planck on macOS
(Part 2 of Step-By-Step Guide To Configuring Your Planck Using QMK, VIA and Vial on macOS)
These instructions assume you have followed Step-By-Step Guide To Setting up QMK for the Planck on macOS.
You can read the detailed instructions from the VIA site
If you don’t intend on editing the source or using this setup to install Vial, and your keyboard is supported, you can simply download the VIA firmware for your keyboard from their site: Firmware Downloads.
This guide is organized in four parts:
- Part 1 — Setup the VIA keymap directory
- Part 2 — Build the VIA firmware
- Part 3 — Flash the VIA firmware
- Part 4 — Edit the keymap with VIA
Part 1 Setup the VIA keymap directory
1.1 Create a VIA keymap directory
We need to crate a new
via folder exclusively to use with VIA in the location
In our case and for a Planck keyboard if previously we were using:
Now we will use:
In the case of the Planck keyboard the QMK repo already has this folder and its contents are:
keymap.c readme.md rules.mk
Here are the preset contents of the
VIA_ENABLE = yes LTO_ENABLE = yes # Not enough USB endpoints CONSOLE_ENABLE = no
The contents of the
keymap.c file are similar to those in the previous default keyboard folder but the number of layers and content is much more simplified.
If QMK’s repo doesn’t already have a
via folder for your keyboard follow the next two steps to create the files within, otherwise you can skip them.
If your keyboard folder already contains the via keymap directory you might notice that there is no
config.h file within. This is because the settings required for VIA should be put in the keyboard directory. In our case
1.2 Create a rules file
In this folder create a
rules.mk file and add the following line:
VIA_ENABLE = yes
Per the official docs: “This will enable dynamic keymaps, raw HID message handling and bootmagic lite.”
1.3 Create a keymap file
You must create a
keymap.c in the
via keymap directory with a number of preset layers initialized to sensible default keycodes. This areCreate a KLE for VIA the layers to be used for loading the dynamic keymaps.
You can create a blank layout for your keyboard via KLE. Read how to create Layouts in VIA documentation, with Simple and Advanced examples.
Part 2 Build the VIA firmware
If you have followed the previous setup for QMK, your keymap defaults should be set. You can compile VIA by doing:
qmk compile -km via
You might see output like this:
Creating binary load file for flashing: .build/planck_rev6_drop_via.bin [OK] Creating load file for flashing: .build/planck_rev6_drop_via.hex [OK] Size after: text data bss dec hex filename 0 41292 0 41292 a14c .build/planck_rev6_drop_via.hex Copying planck_rev6_drop_via.bin to qmk_firmware folder [OK] (Firmware size check does not yet support cortex-m4 microprocessors; skipping.)
Here is the generated file:
Part 3 Flash the VIA firmware
Follow the same process as if flashing any other QMK firmware. You can see full details at [[⤒ Post 3 - Setting up QMK in macOS]].
3.1 Enter bootloader mode
With our Planck keyboard we press key combo
raise+lower+q (or press the reset button). With the QMK Toolbox open we can see status logs.
*** STM32 DFU device connected: STMicroelectronics STM32 BOOTLOADER (0483:DF11:2200)
3.2 Open the VIA Keymap Firmware with QMK Toolbox
Open the VIA firmware file in QMK Toolbox. It can be found on the root
/qmk_firmware/ folder. In my case:
3.3 Flash Your Keyboard
Click the “Flash” button in QMK Toolbox.
Here is my output in all it’s glory:
*** Attempting to flash, please don't remove device [...] Erase done. [...] Download done. File downloaded successfully Transitioning to dfuMANIFEST state *** STM32 DFU device disconnected: STMicroelectronics STM32 BOOTLOADER (0483:DF11:2200)
Alternatively you can also flash your keyboard from the terminal like this:
Part 4 Edit the keymap with VIA
That’s it for setting up VIA. Now we are ready to use the visual GUI to edit the keymap. Have fun.
4.1 Download the VIA editor
Download the GUI from their repo: the-via/releases. For mac the file is
As of September 2021, the latest release 1.3.1 is over a year old (Jun 18, 2020). This is another reason folks are moving to Vial.
4.2 Open the VIA app
In macOs you will run into a security alert. You will have to go to your security settings to open the app. (Always make sure you trust and understand what you download from the internet.)
VIA already recognized the keyboard I have connected and shows the configuration on screen.
4.3 Configure your keyboard
Any changes you do in the VIA app will reflect right away in your keyboard. No compilation and no flashing. Really, really convenient for testing and optimizing your layouts.
Have fun! 🎉