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 keyboards/<keyboardname>/keymaps/via.

In our case and for a Planck keyboard if previously we were using:

<folder>/qmk_firmware/keyboards/planck/keymaps/<github_username>

Now we will use:

<folder>/qmk_firmware/keyboards/planck/keymaps/via

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 rules.mk file:

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 <folder>/qmk_firmware/keyboards/planck/config.h.

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:

planck_rev6_drop_via.bin

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:

planck_rev6_drop_via.bin

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:

qmk flash

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 via-1.3.1-mac.dmg

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! 🎉