Warum sollte ich VIAL nutzen wollen?⌗

Vial ist eine Alternative zum eher bekannten VIA, bietet aber mehr Funktionalität und ist unabhängig davon, ob das Keyboard auch im VIA Repository aufgenommen wurde. Im Hintergrund gibt es auch noch ein paar “politische” Hintergründe, die für die Verwendung von VIAL sprechen, aber das weiter aufzudröseln tut wenig zur Sache und dafür reicht auch mein Hintergrundwissen nicht ganz aus. Für mich stehen die Unabhängigkeit und der Funktionsumfang im Vordergrund. Zusätzlich sind mir einige Anpassungen bei VIA in der Vergangenheit ein Dorn im Auge, u.a. der Wechsel auf die neuen V3 Definitionen, mit dem alte Firmwares teilweise unbenutzbar wurden.

Mit VIA habt ihr die Möglichkeit, Teile eurer QMK Konfiguration on the fly in einer GUI anzupassen. Das beschränkt sich bei den meisten auf die reine Keymap. Themen wie Tapdance, Timeouts, Combos etc. sucht ihr hier vergeblich. In den Anfangszeiten von VIAL war das auch die einzige Möglichkeit, die Encoder Belegung in der GUI zu verändern. Damit VIA(L) weiß wie euer Keyboard aufgebaut ist, wird ein JSON File benötigt, das die Position der Tasten auf der Matrix beschreibt. Bei VIA wird dieses File vom VIA Client aus dem Repository geladen, oder alternativ von euch selbst hochgeladen. VIAL geht hier einen anderen Weg, das JSON-File liegt hier mit auf dem Microcontroller und ist Teil der Firmware. Ein Nachteil davon ist der erhöhte Speicherbedarf, gerade MCUs wie der ATM32U4 kommen hier sehr schnell an ihre Grenzen.

VIAL unterstützt ansonsten quasi das komplette QMK Portfolio. Autoshift, Combos, Macros, Tap-Hold, Tapdance, alles könnt ihr bequem per GUI und on the fly ändern und anpassen. Gerade 40s und Split Nutzer kommen hier voll auf ihre Kosten.

Bauen einer Vial Firmware⌗

Wenn ihr Glück habt, gibt es für das Board eurer Wahl bereits eine fertige VIAL Firmware. Je nach verwendetem MCU sind aber ggf. manche Funktionen deaktiviert um Speicher zu sparen. Dazu findet ihr mehr Informationen direkt beim VIAL Team. Wir gehen einmal davon aus, dass es für euer gewähltes Board schon eine QMK gibt und im besten Fall auch schon eine VIA Keymap, dann könnt ihr den einfachen Weg gehen.

VIA Keymap als Grundlage⌗

Gibt es bereits eine VIA Keymap, steht auch schon eine der angesprochenen JSON Dateien zur Verfügung.Allerdings ist hier das Format von VIA und VIAL unterschiedlich

If your keyboard already is ported too and works with VIA, that shares a lot of the same properties, and you can download your keyboard definition from the VIA repository and use that as a starting point for the files needed in Vial. However as VIA have added more and more functionality in newer versions, and that data is stored in their version of this file, you will need to strip out VIA specific code that Vial cannot interpret.

Um euch hier das Leben noch einfacher zu machen, hat der gute okin das Tool pour geschrieben. pour nimmt eine bestehende VIA JSON und baut diese in das benötigte Format für VIAL um. Zur Installation verweise ich euch mal an das Repository, bei mir unter Arch lief das absolut problemlos.

Mit einer Zeile zieht sich pour dann die passende JSON von einer VIA Keymap, erstellt eine eigene VIAL Keymap im Ordner des Keyboards und legt auch gleich alle weiteren benötigten Dateien an. Dafür müsst ihr zuerst in euer VIAL Verzeichnis wechseln. Dann macht ihr folgendermaßen:


pour --keyboard mechlovin/infinity88 --json-file https://github.com/mechlovin/qmk_firmware/blob/master/keyboards/mechlovin/infinity88/info.json

--keyboard mechlovin/infinity88 gibt hier das Board an in welchem Verzeichnis gearbeitet wird

--json-file ist der Link zu der VIA JSON die ihr als Basis benutzt

pour wird euch dann noch fragen, ob ihr eine eigene Unlock-Combination anlegen wollt. Wenn nicht, wird trotzdem eine angelegt, ihr bekommt keine Firmware ohne. Danach bekommt ihr sogar noch den Befehl angezeigt, mit dem ihr die neue Firmware kompilieren könnt. Im besten Fall läuft der Vorgang dann problemlos durch. Habt ihr einen MCU wie den ATM32U4, kann es aber sein, dass nicht genug Speicher zur Verfügung steht. Dann könnt ihr als ersten Versuch schauen, dass ihr Features in der Firmware deaktiviert um Speicher zu sparen.


[daniel@fs0ciety vial-qmk]$ pour --keyboard mechlovin/infinityce --json-file https://github.com/mechlovin/qmk_firmware/blob/master/keyboards/mechlovin/infinityce/info.json
Received an URL for the JSON file... attempting to download it
✔ Keymap dir already exists - should we remove or abort? · Replace
Removing the keymap directory...
✔ Do you want to setup a custom unlock combination? · No
That's it - everything is ready for building a firmware now.
See if the build works:
qmk compile -kb mechlovin/infinityce -km vial
[daniel@fs0ciety vial-qmk]$ ls keyboards/mechlovin/infinityce/keymaps/vial/
config.h  keymap.c  readme.md  rules.mk  vial.json

Hat eure Firmware dann erfolgreich kompiliert könnt ihr diese auf euer Board flashen (hier ist der Vorgang auch wieder je nach MCU und Bootloader unterschiedlich). Der Klassiker für ATM32 MCUs wäre hier die QMK-Toolbox, sofern ihr unter Windows unterwegs seit. Mit Linux nutze ich hier in der Regel direkt die dfu-utils. Bei RP2040 Boards flasht ihr sowieso komplett ohne extra Tools. Die fertige Firmware liegt dann direkt in eurem vial-qmk Verzeichnis.

keine VIA-Keymap, nur QMK⌗

Kommen wir zum eigentlichen spaßigen Part, das bauen einer Firmware noch komplett ohne VIA-Vorlage. Hier bleibt euch erst einmal nichts anderes übrig, als auch die nötige JSON-Datei selbst zu erstellen. Der Vorgang wird auf der VIAL-Website auch schon beschrieben, bei der Hexatana habe ich das auch einmal selber durchgespielt. Noch einmal kurz zusammengefasst:

  1. baut das Layout im Keyboard Layout Editor nach
  2. Keys im KLE bekommen dann als Top-Legend die Position in der Matrix
  3. die Matrix Positionen bekommt ihr aus den QMK-Files
  4. export des KLE Layouts als RAW JSON
  5. erstellt eine VIAL.json im Keymap Ordner und fügt hier dann das KLE Layout ein

Um mir die Arbeit mit dem KLE einfacher zu machen und auch die Zuweisung zur Matrix zu bekommen, habe ich mir die Daten aus der info.json geholt


"layout": [
{ "matrix": [0, 0], "x": 0, "y": 0 },
{ "matrix": [0, 1], "x": 2, "y": 0 },
{ "matrix": [0, 2], "x": 4, "y": 0 },
{ "matrix": [0, 4], "x": 6, "y": 0 },
{ "matrix": [0, 5], "x": 8, "y": 0 },
{ "matrix": [0, 6], "x": 0, "y": 3 },
{ "matrix": [1, 0], "x": 1, "y": 0 },
{ "matrix": [1, 1], "x": 3, "y": 0 },
.....

Das KLE Layout das ihr damit bekommt, kommt dann neben weiterer Infos wie Beleuchtung, Informationen zur Matrix, in die /keymaps/vial/vial.json. Ist eure vial.json fertig, könnt ihr diese einmal testweise in VIAL laden.

Damit seit ihr dann auch schon fast fertig. In der offiziellen Doku erstellt ihr jetzt erst euren Ordner für die VIAL Keymap, aber das könnt ihr natürlich auch schon vorher tun. Als Ergänzung zur offiziellen Doku noch etwas aus meiner Vorgehensweise

  • die keymap.c könnt ihr direkt von der default Keymap übernehmen
  • zum testen könnt ihr auch ohne eine Unlock Combination bauen, müsst das aber auch in der rules.mk zulassen
  • wenn ihr euch mit der Matrix nicht sicher seit, baut erst einmal ohne den Secure Unlock. Gerade wenn ihr die QMK nicht selbst erstellt habt, ist hier die Chance groß, dass es teilweise noch Unstimmigkeiten gibt

Wer sich einmal die Files ansehen möchte mit denen ich dann am Ende gearbeitet habe, kann sich gerne meine VIAL-Firmware für die Hexatana ansehen. Alle Files hier noch einmal darzustellen erspare ich euch mal. Euer Keymap Ordner sollte am Schluss so aussehen

..../
    keyboard/
    └── keymaps/
        └── vial/
            ├── config.h
            ├── keymap.c
            ├── rules.mk
            └── vial.json

Das ganze kompiliert ihr dann einmal, hier im Beispiel mit qmk compile -kb purox/hexatana -km vial und flasht das ganze auf euer Board. Viel Spaß mit eurer eigenen VIAL Firmware! ⌨️