Keyball
Keyball is a family of keyboards that feature a 34mm thumb trackball with the widely used PMW3360 sensor. In partnership with Yowkees of Shirogane Lab, the creator of this wonderful integrated trackball design, we're happy to bring Keyball to a wider audience.
The trackball sits in an injected molded housing with 3 ceramic bearings. The ball slides snuggly into the housing and moves smoothly in all directions thanks to the bearings.
Buyer's Guide
Most of the general purpose Buyer's Guide applies to Keyball lineup of keyboards as well, it stands out in a few ways described below.
First, it's worth noting that our Keyball differ from the one sold by Yushakobo / Shirogane Lab. In terms of cosmetics, we use black PCBs, different thickness acrylic plates and different M2 screws. Additionally, we use RP2040 controllers with ample storage so firmware size is not an issue. The rest is identical.
34mm Trackball
Keyball uses a 34mm trackball that's not included in your purchase. There are many color options to choose from, and the ones made by Perixx are a popular choice.
Thumb Cluster
Keyball has a unique thumb cluster that allows either Kailh's choc low profile or MX switches. Whether you're buying a kit or a prebuilt one, you will get choc hotswap sockets. This option lets you also add choc switches and keycaps to your order.
Build Guide
Please refer to the canonical Keyball guide below:
Come back to this page when you're at the firmware step, as it differs from the guide above.
For build help that's not specific to Keyball, you're welcome to visit the Keyboard guide in these docs.
Firmware
Keyball's firmware is maintained in a dedicated repository by the designer of the keyboard and is written for Pro Micro controllers. A port of the firmware for RP2040 controllers is available in this holykeebs repository. It's recommended to use the precompiled firmware.
DANGER
Avoid connecting / disconnecting the TRRS cable when the keyboard is powered. This can short the GPIO pins of the controllers.
If you'd like to compile your own firmware, see the Firmware page on setting up the environment.
Once you have your own clone, while on the hk-master branch, flash both sides using (adjust the name to the Keyball you have):
make keyball/keyball44:via:flash -j8USB cable can be connected to either side of the keyboard. If your trackball doesn't work, try switching the cable to the side with the trackball.
Custom Keycodes
Keyball comes with custom keycodes that provide access to Keyball features without needing to compile your own firmware. These features are accessible through the following Special Keycodes that can be assigned when using Remap:
| Keycode | Value on Remap | Description |
|---|---|---|
KBC_RST | Kb 0 | Reset Keyball configuration |
KBC_SAVE | Kb 1 | Save Keyball configuration to memory (EEPROM) |
CPI_I100 | Kb 2 | Increase pointer speed by 100 CPI (max 12000) |
CPI_D100 | Kb 3 | Decrease pointer speed by 100 CPI (min 100) |
CPI_I1K | Kb 4 | Increase pointer speed by 1000 CPI (max 12000) |
CPI_D1K | Kb 5 | Decrease pointer speed by 1000 CPI (min 100) |
SCRL_TO | Kb 6 | Toggle scroll mode |
SCRL_MO | Kb 7 | Enable scroll mode (while held) |
SCRL_DVI | Kb 8 | Decrease scroll speed (max D7 = 1/128) |
SCRL_DVD | Kb 9 | Increase scroll speed (min D0 = 1/1) |
AML_TO | Kb 10 | Toggle automatic mouse layer |
AML_I50 | Kb 11 | Increase automatic mouse layer timeout by 50ms (max 1000ms) |
AML_D50 | Kb 12 | Decrease automatic mouse layer timeout by 50ms (min 100ms) |
SSNP_VRT | Kb 13 | Lock scroll direction to vertical only |
SSNP_HOR | Kb 14 | Lock scroll direction to horizontal only |
SSNP_FRE | Kb 15 | Disable scroll direction lock (free scroll) |
If you wish to have your current configuration persist across reboots, use the KBC_SAVE keycode to save it to memory. Please note that each half of the Keyball has separate memory, so if you wish to have same behavior regardless of which half is plugged in, you will need to repeat the configuration for each half.
Keyball61+
The Keyball61+ is an improved version of the popular Keyball61. It comes with two horizontal encoders on each side, replacing the switch below the controller. Each encoder is clickable so in total there are still 61 keys. The encoders remove the need for drag scrolling with the trackball (if you prefer that, you can map the encoders to something else). Additionally, the Keyball61 doesn't come in kit form, only soldered or assembled. This allows us to offer it at a lower price point than normal.
The firmware is built on the holykeebs userspace, the same one our other pointing device keyboards use, rather than the Keyball firmware described above. What that means in practice:
- The custom keycodes are the
HK_*keycodes documented on the Firmware page, not the Custom Keycodes listed above. - Due to popular demand, the firmware is compatible with Vial.
While on the hk-master branch, build it with (append :flash to also flash):
make holykeebs/keyball61plus:via -e USER_NAME=holykeebs -e OLED=yesUse :vial in place of :via for the Vial firmware. See the Firmware page for environment setup and the full feature reference.
Building Your Own Firmware
Please see the Firmware guide.