Configure your Layout

Wired

Familiarize yourself with your layout in the Vial App, and make any initial changes to it. These changes will be instantly stored in your Cyboard (in the central half) and will stay active among devices as long as you use the same central. Once you're satisfied with your layout, keep Vial open for the next step (it'll help to have a map to add your keycaps!)

Wireless

Cyboard Studio (recommended)

Cyboard Studio lets you edit your keymap and configure your trackballs point-and-click, right from the browser — no repositories or firmware builds needed.

Connect the central (left by default) half of your Cyboard to your computer via USB, navigate to studio.cyboard.digital in Chrome or Edge, and start making changes — Studio walks you through connecting and unlocking. Changes are applied instantly and stored on your keyboard, so they stay active across all your devices.

note

If Studio says your keyboard needs a firmware update, follow the Cyboard Studio Firmware Update guide first, then come back here.

Advanced: Manage your own Firmware Repository

Most users won't need this — Cyboard Studio covers everyday configuration. But if you want full control over your firmware (custom behaviors, editing the keymap source directly, features Studio doesn't expose), you can build your own firmware from our template.

warning

Layouts made in Cyboard Studio can't be exported into firmware source files, and flashing your own firmware replaces what's stored on the keyboard — including Studio's trackball configuration features, which aren't available in self-built firmware. Pick one workflow and stick with it.

Configuration Repository Setup

1. Create your configuration GitHub Repository from our template
2. Replace config/imprint.keymap and config/info.json with the appropriate default from config/default keymaps/ based on the physical layout of your board.
3. Commit and push the changes, and verify that the default firmware builds successfully (green checkmark).

ZMK Keymap Editor

1. Navigate to nickcoutsos.github.io/keymap-editor/
2. Sign into github and link to this repository.
3. Make changes to the layout more information can be found here
4. Press Save. GitHub will automatically run an Action to build your firmware when you push changes. this takes approximately 2 minutes for most changes.
5. Once the Action is successful, there will be a firmware Artifact in the Action which you can download and unzip.

Apply Changes (Flash Firmware)

1. Connect the central (left by default) half of your Cyboard to your computer via USB.
2. Put your Cyboard in bootloader mode by double tapping the reset button next to the USB C port.

tip

The switch puller that comes with your Cyboard will fit in the reset hole!

3. Copy imprint_left-assimilator-bt-zmk.uf2 file into the USB device named ASSIMILATOR.
4. Repeat on the right side, using imprint_right-assimilator-bt-zmk.uf2. This is not necessary for many changes like simply updating the keymap, but some features do require re-flashing the right side as well.
5. You're done! You can now disconnect your Cyboard from your computer.