December 30, 2022

Step-By-Step Guide To Setting up Vial for the Planck on macOS

(Part 3 of Step-By-Step Guide To Configuring Your Planck Using QMK, VIA and Vial on macOS)

You need to setup VIA for macOS as described in the previous posts in order to get Vial up and running.

This guide is organized in four parts:

(The official full detailed instructions can be found in the Vial user guide: Porting a VIA keyboard to Vial)

Part 1 Setup the Vial keymap directory

1.1 Clone the Vial QMK fork

Start by forking your own copy of Vial repository https://github.com/vial-kb/vial-qmk via github’s interface.

Clone your fork of the Vial repo. You will need the HTTPS url (eg: https://github.com/<github_username>/vial-qmk.git).

git clone --recurse-submodules https://github.com/<github_username>/vial-qmk.git

1.2 Create a new vial keymap

Copy the existing keymaps/viafolder from <folder>/vial-qmk/keyboards/planck/keymaps/via to <folder>/vial-qmk/keyboards/planck/keymaps/vial.

1.3 Enable Vial

In your <folder>/vial-qmk/keyboards/planck/keymaps/vial/rules.mk, after the line VIA_ENABLE = yes add the following:

VIAL_ENABLE = yes

1.4 Create a KLE for VIA

via: https://get.vial.today/docs/porting-to-via.html#3-create-a-kle-for-via

For the planck this is what that looks like:

["0,0","0,1","0,2","0,3","0,4","0,5","0,6","0,7","0,8","0,9","0,10","0,11"],
["1,0","1,1","1,2","1,3","1,4","1,5","1,6","1,7","1,8","1,9","1,10","1,11"],
["2,0","2,1","2,2","2,3","2,4","2,5","2,6","2,7","2,8","2,9","2,10","2,11"],
["3,0","3,1","3,2","3,3","3,4","3,5","3,6","3,7","3,8","3,9","3,10","3,11"]

1.5 Create a JSON for VIA

Fill out the following JSON template:

{
    "name": "",
    "vendorId": "",
    "productId": "",
    "lighting": "none",
    "matrix": {
        "rows": 0,
        "cols": 0
    },
    "layouts": {
        "labels":
        "keymap":
    }
}

See details at Vial site Create a JSON for VIA

In the case of a Planck this would seem to be the layout of the keys

[
 ["0,0","0,1","0,2","0,3","0,4","0,5","0,6","0,7","0,8","0,9","0,10","0,11"],
 ["1,0","1,1","1,2","1,3","1,4","1,5","1,6","1,7","1,8","1,9","1,10","1,11"],
 ["2,0","2,1","2,2","2,3","2,4","2,5","2,6","2,7","2,8","2,9","2,10","2,11"],
 ["3,0","3,1","3,2","3,3","3,4","3,5","3,6","3,7","3,8","3,9","3,10","3,11"]
]

However the true layout of the keys is closer to this:

[
   [ "0,0", "0,1", "0,2", "0,3", "0,4", "0,5",
     "4,0", "4,1", "4,2", "4,3", "4,4", "4,5" ],
   [ "1,0", "1,1", "1,2", "1,3", "1,4", "1,5",
     "5,0", "5,1", "5,2", "5,3", "5,4", "5,5" ],
   [ "2,0", "2,1", "2,2", "2,3", "2,4", "2,5",
     "6,0", "6,1", "6,2", "6,3", "6,4", "6,5" ],
   [ "3,0", "3,1", "3,2",
     "7,3", "7,4", "7,5", "7,0", "7,1", "7,2",
     "3,3", "3,4", "3,5" ]
]

Here is the final vial.json file including two alternative layouts for the bottom row:

{
 "name": "Planck",
 "vendorId": "0x03A8",
 "productId": "0xA4F9",
 "lighting": "none",
 "matrix": {
  "rows": 8,
  "cols": 6
 },
 "layouts": {
  "labels": [
   ["Bottom Row", "1x2uC", "4x12", "2x2u"]
  ],
  "keymap": [
   [
    { "c": "#aaaaaa" },
    "0,0",
    { "c": "#cccccc" },
    "0,1", "0,2", "0,3", "0,4", "0,5",
    "4,0", "4,1", "4,2", "4,3", "4,4",
    { "c": "#aaaaaa" },
    "4,5"
   ],
   [
    "1,0",
    { "c": "#cccccc" },
    "1,1", "1,2", "1,3", "1,4", "1,5",
    "5,0", "5,1", "5,2", "5,3", "5,4",
    { "c": "#aaaaaa" },
    "5,5"
   ],
   [
    "2,0",
    { "c": "#cccccc" },
    "2,1", "2,2", "2,3", "2,4", "2,5",
    "6,0", "6,1", "6,2", "6,3", "6,4",
    { "c": "#aaaaaa" },
    "6,5"
   ],
   [
    "3,0", "3,1", "3,2",
    "7,3",
    { "c": "#777777" },
    "7,4\n\n\n0,0",
    { "c": "#cccccc", "w": 2 },
    "7,0\n\n\n0,0",
    { "c": "#777777" },
    "7,1\n\n\n0,0",
    {"c": "#aaaaaa" },
    "7,2",
    "3,3", "3,4", "3,5"
   ],
   [
    {"y": 0.25, "x": 4, "c": "#777777" },
    "7,4\n\n\n0,1",
    {"c": "#cccccc" },
    "7,5\n\n\n0,1",
    "7,0\n\n\n0,1",
    { "c": "#777777" },
    "7,1\n\n\n0,1"
   ],
   { 
    "x": 4, "c": "#cccccc", "w": 2 },
    "7,5\n\n\n0,2",
    { "w": 2 },
    "7,1\n\n\n0,2"
   ]
  ]
 }
}

1.6 Save the new vial.json file

Place the generated VIA JSON under <folder>/vial-qmk/keyboards/planck/keymaps/vial/vial.json so that Vial build process can find it.

This file is the KLE compatible layout configuration that is stored directly in the keyboard.

1.7 Create a new config.h file

Start by generating a unique keyboard ID as follows. From the root of <folder>/vial-qmk/, run the following command to generate a unique Vial keyboard ID:

python3 util/vial_generate_keyboard_uid.py

Copy the generated output. Eg:

#define VIAL_KEYBOARD_UID {0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX}

Next create a new file config.h inside <folder>/vial-qmk/keyboards/planck/keymaps/vial/. Add the following contents to it (the last line must match the output generated above)

/* SPDX-License-Identifier: GPL-2.0-or-later */

#pragma once

#define VIAL_KEYBOARD_UID {0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX}

1.8 Set up secury lock

In order to protect your keyboard from an attach coming from a machine it is connected to, Vial requires the user to unlocks the keyboard the first time it is connected to a computer.

This security feature can be disabled, but it is easy enough to setup and use so we will leave it in.

Pick a combo of at least 2 keys, and take note of the key location on your keyboard.

In my case I’ll choose Esc (located at [0, 1]) and Return (located at [2, 11]) on my planck.

Add the following lines to your config.h file right below the VIAL_KEYBOARD_UID line:

#define VIAL_UNLOCK_COMBO_ROWS { 0, 1 }
#define VIAL_UNLOCK_COMBO_COLS { 2, 11 }

Part 2 Build the Vial firmware

If you have followed the previous setup for QMK and VIA this should be straighforward.

You can compile Vial by doing:

qmk compile -kb planck/rev6 -km vial

or

make planck/rev6:vial

You might see output like this:

Creating binary load file for flashing: .build/planck_rev6_vial.bin                                 [OK]
Creating load file for flashing: .build/planck_rev6_vial.hex                                        [OK]

Size after:
   text    data     bss     dec     hex filename
      0   49396       0   49396    c0f4 .build/planck_rev6_vial.hex

Copying planck_rev6_vial.bin to qmk_firmware folder                                                 [OK]
(Firmware size check does not yet support cortex-m4 microprocessors; skipping.)

Here is the generated file:

planck_rev6_vial.bin

Part 3 Flash the Vial firmware

Follow the same process as if flashing any other QMK firmware. You can see full details in the previous guide: Step-By-Step Guide To Setting up QMK for the Planck on 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_vial.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)

Part 4 Edit the keymal with Vial

That’s it for setting up VIAL. Now we are ready to use the visual GUI to edit the keymap.

4.1 Download the Vial editor

Download the GUI from their site: Download Vial. For mac the file is Vial-v0.4.1.dmg

4.2 Open the Vial app

As with VIA macOs will likely throw you a security alert. Go to your security settings to open the app. (Always make sure you trust and understand what you download from the internet.)

The connected keyboard should load. If it doesn’t click the Refresh button.

4.3 Configure your keyboard

From here on out the workflow is the same as with VIA. Any changes you do in the UI app will reflect right away in your keyboard. No compilation. No flashing.

Keep in mind that you can’t use VIA and Vial at the same time.

Enjoy and have fun! 🥂

December 30, 2022



Previous:Step-By-Step Guide To Setting up VIA for the Planck on macOS
Next:Don’t Be Afraid to Mark Up Your Books: Why Underlining and Annotating Is Actually a Good Thing