Repository files navigation

This repository offers pre-configured ZMK firmware designed forWireless Charybdis keyboards. It supports both Bluetooth/USB and Dongle configurations and uses the latest input listener and processors to act as a bridge between the trackball and the rest of the system.

If you want to customize things the repo is set up to build through GitHub Actions (just clone and run it), or you can use thecontainerized build script that will build all firmwares locally with a single command.

Download your choice of firmware from the Releases page. Choose a combination of format (Bluetooth/Dongle) and layout (QWERTY, etc.), then follow the steps below to flash it to your keyboard

1. Unzip the firmware zip
2. Plug the right half into the computer through USB
3. Double press the reset button
4. The keyboard will mount as a removable storage device
5. Copy the applicable uf2 file into the NICENANO storage device (e.g. charybdis_qwerty_dongle.uf2 -> dongle)
6. It will take a few seconds, then it will unmount and restart itself.
7. Repeat these steps for all devices.
8. You should now be able to use your keyboard

To see all the layers check out thefull render.

⌨️ Keyboard Layers

🏠 Home-Row Mods

🔗 Combos

⚙️ Other Highlights

• Hold-tap side-aware triggers: Each HRM key only becomes a modifier if the opposite half is active, preventing accidental holds while one-handed.
• Quick-tap / prior-idle: Tuned for faster mod-vs-tap detection.
• Timeless home row mods: On the BASE layer with balanced flavor on both halves (280 ms tapping-term, and quick-tap with prior-idle tuning).
• Thumb-scroll mode: Hold the left-most thumb button (K36) while moving the trackball to turn motion into scroll.
• Precision cursor mode: Double-tap, then hold K36 to drop the pointer speed, release to return to normal speed.
• MOUSE layer behavior: When activated, the left thumb cluster functions as mouse controls — K36 handles scroll and slow mode, K37 is left click, and K38 is right click. Pressing any other key exits the MOUSE layer and returns to BASE.
• Bluetooth profile quick-swap: Jump to the EXTRAS layer and tap the dedicated BT-select keys to pair or switch among up to four saved hosts (plus BT CLR to forget all).
• ZMK Studio: Supported on BT builds for quick and easy keymap adjustments. Dongle support will come soon.
• Patched the PMW3610 driver & other files: Removed linker and attribute warnings during build
• PMW3610 low power trackball sensor driver: Provided bybadjeff

This section will help you personalize your firmware. Everything—from keys and layers to advanced trackball behaviors—can easily be customized, even if you're new to ZMK.

By default both Bluetooth and Dongle formats will build firmware pairs for the QWERTY, Coleman DH, and Graphite keymaps. To save time and streamline your builds, you can build just a single keymap or shield that you're interested in:

Single keymap:Delete any.keymap files you don't need fromconfig/keymap/, leaving only your desired keymap(s). The build process specifically looks for a file namedcharybdis.keymap. If you prefer another layout instead of the default QWERTY, simply rename your chosen keymap tocharybdis.keymap.

Single shield format (Dongle or Bluetooth):Delete the shield directory (charybdis_dongle or charybdis_bt) from the config/boards/shields/ folder to build only the format you need.

ZMK Studio

ZMK Studio allows users to update functionality during runtime. It's currently only implemented on the Bluetooth builds.

To change the visual layout of the keys, the physical layout must be updated. This is the charybdis-layouts.dtsi file, which handles the actual physical positions of the keys. Though they may appear to be similar, this is different than the matrix transform file (charybdis.json) which handles the electrical matrix to keymap relationship.

To easily modify the physical layout, or convert a matrix transform file,caksoylar has built theZMK physical layouts converter.

For more details on how to use ZMK Studio, refer to theZMK documentation.

Keymap GUI

Using a GUI to generate the keymap file before building the firmware is another easy way to modify the key mappings. Head over to nickcoutsos' keymap editor and follow the steps below.

• Fork/Clone this repo
• Open a new tab to thekeymap editor
• Give it permission to see your repo
• Select the branch you'd like to modify
• Update the keys to match what you'd like to use on your keyboard
• Save
• Wait for the pipeline to run
• Download and flash the new firmware

Edit Keymap Directly

To change a key layout choose a behavior you'd like to assign to a key, then choose a parameter code. This process is more clearly outlined on ZMK'sKeymaps & Behaviors page. All keycodes are documentedhere page

Open the config/keymap/charybdis.keymap file and change keys, or add/remove layers, then merge the changes and re-flash the keyboard with the updated firmware.

The trackball uses ZMK's modular input processor system, making it easy to adjust pointer behavior to your liking. All trackball-related configurations and input processors are conveniently grouped in theconfig/charybdis_pointer.dtsi file. Modify this file to customize tracking speed, acceleration, scrolling behavior, and more—then rebuild your firmware.

You can easily build your firmware locally or leverage GitHub Actions:

Local Build (recommended for quick testing and debugging)

Clone this repo, then run these commands from the repo root:

cd local-builddocker-compose run --rm builder

See thelocal build README for additional details, including how to enable USB logging in the builds.

GitHub Actions

• Fork or clone this repo
• Push your changes to your GitHub
• GitHub Actions automatically builds your firmware and publishes downloadable artifacts under the Actions tab.

• If the keyboard halves aren't connecting as expected, try pressing the reset button on both halves at the same time. If that doesn't work, follow theZMK Connection Issues documentation for more troubleshooting steps.

• badjeff
• eigatech
• nickcoutsos
• caksoylar
• urob