Wired Build

Connection

TRS/TRRS Cable between Split

Click this video for demo.

  1. Connect the Keyboard Halves Use the TRS/TRRS cable to connect the left and right halves of your keyboard. Ensure the cable is fully inserted without forcing it.

  2. Connect the USB-C Cable Insert a USB-C cable into either the left or right side, depending on your split keyboard's configuration. For example, for the Keyball keyboard, connect the USB-C cable to the trackball side.

  3. TRS/TRRS Compatibility

    • The TRS or TRRS cable is included with your keyboard.

    • If you need an alternative, a 3.5mm to 3.5mm audio cable can be used.

    • Note the difference between TRS and TRRS cables:

      • TRS is typically used for keyboards like the Sofle or Corne series.

      • TRRS is required for keyboards like the Keyball, Piantor, and BastardKB series.

Avoid hot-plugging or unplugging the TRS/TRRS cable while the keyboard is powered. Doing so may brick the MCU, requiring a replacement.

Type-C Cable between Split

Click this video for demo.

  1. Connect Keyboard Halves Use the provided Type-C cable to connect the left and right sides of your keyboard.

  2. Connect the USB-C Cable Attach the USB-C cable to either the left or right side, depending on your keyboard model and firmware requirements.

  3. Hot Plugging While Type-C connections between splits generally support hot-plugging, it is best practice to:

    • Connect the left and right halves first before powering the keyboard.

    • Disconnect the left and right halves last when powering off.

USB-C Cable

The cable used to connect your keyboard to your PC is typically not provided. You can use any of the following options, depending on the port you wish to connect to on your PC:

  1. Type-C to Type-C Cable Ensure the cable supports data transmission.

  2. USB-A to Type-C Cable This is another common option for connecting your keyboard to your PC.

Important Notes:

Always use a cable that supports data transmission. Ensure the port you are connecting to on your PC can transmit data, as some ports (e.g., power-only USB ports) may not support keyboard functionality.

Do not connect the extra port on the split keyboard to other devices, such as a pendrive. Do not connect cable from pc to the port between the split keyboards.

Software Key Remapping

Our keyboards are exclusively compatible with Vial. To remap your keys, download the Vial software or use the Vial web interface available at https://get.vial.today/.

Vial automatically detects compatible keyboards and supports Windows, Linux, and Mac. It is a real-time key remapping software that eliminates the need for code compilation or loading JSON files.

Please note that we use Vial, not Via.

Use Vial, Not Via Ensure you are using Vial (download here) and not Via (check Via here). These are distinct tools, and using the wrong one may result in unexpected behavior. Avoid Running Multiple Applications Launch only one remapping application at a time to prevent software conflicts.

Web Vial does not support keymap saving/loading. You need to load or save keymaps through the Vial desktop application installed on your device.

Vial on MacOS

This is useful if you want to use the keyboard across different operating systems, especially Windows and macOS.

  • Open System Settings

  • Go to Keyboard

  • Click Modifier Keys

  • Swap Control and Command etc.

  • Click Done

Now on Windows, if you register LCTL(KC_B), it will send Control + B. But on macOS, it will send Command + B instead.

MacOS Compatibility

Installation

Cmd+space, go to Setting, Privacy & Security. Under Security, Open Anyway.

For Vial, there are no special macOS-specific keycodes. Instead, the standard Windows keycodes are used, which can be remapped to suit macOS as needed. You can adjust the following keycodes in Vial:

  • LGUI / RGUI: Maps to the Command (⌘) key.

  • LALT / RALT: Maps to the Option (⌥) key.

    • RALT may also function as AltGr for international layouts.

  • LCTL / RCTL: Maps to the Control (⌃) key.

  • LSFT / RSFT: Maps to the Shift (⇧) key.

For a full list of keycodes and their functions, refer to the Keycodes Overview.

Firmware Compilation

This section provides a general guide for compiling firmware for the wired keyboards we produce. Most of our boards are ported to Vial, which is built on top of QMK. Please note that Vial is not entirely equivalent to QMK.

The source code we provide is based on Vial, not QMK.

Setting Up QMK Firmware (macOS)

Prepare your build environment accordding to Setting Up Your QMK Environment | QMK FIrmware.

  1. Launch Terminal by CMD+Space, key in Terminal.

  2. Paste /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" and press Return.

  3. Paste three lines suggested by homebrew.

  4. Next, brew install qmk/qmk/qmk.

  5. qmk setup

Setting Up Vial

To get started, refer to the official guide: Porting to Vial.

Setting Up Vial (macOS)

  1. Close the previous Terminal that you just setup for Qmk firmware.

  2. Launch new Terminal, and paste git clone https://github.com/vial-kb/vial-qmk

  3. cd vial-qmk

  4. make git-submodule

Notes

The source codes we provide already include Vial support, so you can edit the code and compile it within the Vial environment. Copy our source code to Vial repo, and compile using qmk compile -kb xxxx -km vial.

While some original boards were designed for the ATmega32u4 microcontroller, we have upgraded all our boards to use the RP2040. This change provides more memory and functionality. If you are using the original QMK repository, you must convert it to be RP2040 compatible.

Modifications at Your Discretion

The primary reason for making our keyboards compatible with Vial is to simplify usage for end users. Features like QMK settings, tap dance, and combo keys are already well-developed in Vial, so most users can avoid firmware compilation entirely.

If you decide to edit the source code, please do so at your own risk. We do not provide support or advice for source code modifications or compilation. For troubleshooting and advanced discussions, we recommend joining the Vial or QMK Discord communities to learn from others and explore solutions.

RP2040 Flashing

Prerequisites

Before you begin, ensure that you have the compiled firmware (UF2) ready. If you have customized your keymap, save it in Vial before proceeding.

Step 1: Prepare the Firmware

Ensure you have the appropriate UF2 firmware file ready. This could either be the one provided by us or a custom version that you have compiled.

Step 2: Connect USB to Left Split

Start by connecting the USB cable to the left half of your split keyboard. You dont need to disconnect the cable between split while flashing.

Step 3: Reset the Board

  • To enter bootloader mode, double-press the physical reset button.

  • This button is typically located between the OLED screen and TRS jack, or underneath the board.

If the board does not enter bootloader mode after pressing the reset button, try double-pressing the reset button more quickly. Please also note that you need to double-press, not single-press, the button.

Step 4: Remap the Reset Key (If Necessary)

If your board does not have a reset key, or if the reset key doesn't work as expected, you will need to remap it in Vial:

  • Open Vial and go to the "Quantum" tab.

  • Remap the reset key to a convenient key of your choice.

  • After remapping, double-press the newly assigned reset key to trigger the reset.

Step 5: Flash the Firmware

Drag and drop the UF2 firmware file into the new window to begin the flashing process.

Verify the appearance of the new drive in the sidebar of My Computer. In some cases, the drive may not be displayed as a visible folder but may appear as a device instead.

Step 6: Wait for Flashing to Complete

  • Wait for approximately 5 seconds while the firmware is flashed.

  • You can verify the successful flashing by checking the firmware name in Vial.

Step 7: Flash the Right Split

  • After flashing the left half, unplug the USB cable from the left side and connect it to the right half of the keyboard.

  • Follow the same flashing steps for the right half of the keyboard.

Ensure that you use the same UF2 file to flash both sides of the keyboard. If two separate UF2 files are provided, flash the left.uf2 to the left side and right.uf2 to the right side. It is crucial to flash both sides, not just one.

Step 8: Load Your Keymap

  • Once the flashing is complete, reconnect the USB to the correct side (left or right, depending on your keyboard).

  • Open Vial and load your saved keymap to apply your custom layout.

  • If the keymap doesn't load successfully, try to click on Layer 1, then return to Layer 0. The keymap should load correctly.

Keymap Mirror

If you experience an issue where plugging the USB into the left split shows a mirrored keymap, follow these steps:

Plug your USB into the left split and remap EEH_LEFT under the Quantum tab. Press the left split’s long thumb key, and replugging should work.

  1. Plug in USB to Left Split:

    • Connect the USB cable to the left split of the keyboard.

  2. Remap EEH_LEFT:

    • In Vial, go to the "Quantum" tab and remap EEH_LEFT.

    • Press the left split’s long thumb key and replug the USB cable. This should resolve the mirroring issue.

PreviousTroubleshootingNextWireless Build

Last updated