Skip to content

README.md

Latest commit

 

History

History
61 lines (48 loc) · 2.71 KB

README.md

File metadata and controls

61 lines (48 loc) · 2.71 KB
Raw

OLKB Planck Oryx Converter

This repository contains tools to convert ZSA Oryx source code to firmware compatible with the OLKB Planck Rev 6 (and 6.1) keyboard, with full Vial support.

Problem Statement

The OLKB Planck Rev 6 uses a "folded" electrical matrix (8 rows x 6 columns) which is fundamentally different from the visual 4x12 grid layout. ZSA Oryx exports code assuming a linear 4x12 layout, which causes keys to be scrambled when flashed directly to an OLKB board. Additionally, standard ZSA exports lack the necessary configuration for Vial (dynamic remapping).

Solution

The script scripts/oryx_to_olkb.py automatically:

  1. Transposes the Matrix: Splits the 4x12 visual grid into two 4x6 halves and maps them to the correct Planck Rev 6 matrix rows.
  2. Preserves Logic: Retains your macros, tap dances, and custom keycodes from the Oryx export.
  3. Enables Vial: Generates rules.mk and config.h with the required settings (VIAL_ENABLE, VIAL_KEYBOARD_UID, unlock combos).
  4. Fixes Conflicts:
    • Disables ZSA's matrix_scan_user using #if 0 ... #endif to avoid muse/audio conflicts.
    • Disables conflicting features (LTO, COMBO, KEY_OVERRIDE) for stable compilation.
  5. Generates Vial Definition: Creates a vial.json file for manual sideloading if auto-detection fails.

Usage

  1. Export from Oryx: Download the source code for your layout from ZSA Oryx.

  2. Place Source: Copy the keymap.c file from the download into the zsa_oryx_source/ folder.

  3. Run Script:

    python3 scripts/oryx_to_olkb.py

  4. Deploy: The script generates 4 files in olkb_firmware/:

    • keymap.c
    • rules.mk
    • config.h
    • vial.json

    Copy the build files to your QMK keymap folder:

    cp olkb_firmware/keymap.c olkb_firmware/rules.mk olkb_firmware/config.h qmk_firmware/keyboards/planck/keymaps/vial/

  5. Compile:

    qmk compile -kb planck/rev6 -km vial

Troubleshooting

Vial doesn't recognize the keyboard

Because this uses a custom VIAL_KEYBOARD_UID, the Vial app might not automatically download the layout definition.

  1. Open the Vial desktop app.
  2. Go to File > Sideload Keyboard JSON....
  3. Select the vial.json generated by the script.

EEPROM reset

If behavior is inconsistent after flashing:

  1. Unplug the keyboard.
  2. Hold Space + Backspace.
  3. Plug the keyboard in while holding.
  4. Wait ~5 seconds, then release.

Tap dance + Vial note

This project uses QMK tap dance from your converted keymap (TAP_DANCE_ENABLE = yes). If you later decide to use Vial's dynamic tap dances, you'll need a different approach because QMK introspection expects tap_dance_actions to be defined.