holykeebs

Appearance

Firmware ​

QMK is a popular free and open-source keyboard firmware. All of our keyboards are supported by QMK.

This page covers how to flash your microcontrollers with QMK.

INFO

Fully built keyboards already come flashed and tested. You can use these instructions to customize it, e.g. add scrolling mode, adjust the pointing device, OLED and more.

DANGER

Avoid connecting / disconnecting the TRRS cable when the keyboard is powered. This can short the GPIO pins of the controllers.

Source Code ​

The source code for all keyboards can be found on the holykeebs-master branch of https://github.com/idank/qmk_firmware. This repo is periodically kept up to date with main QMK.

There's no requirement to use this repo, it is also possible to copy the relevant pieces to your own clone: the changes are contained to users/idank and the specific keyboard you're flashing for. Look at the changes by running this in your clone:

shell
$ git remote add idank https://github.com/idank/qmk_firmware
$ git diff idank/master...idank/holykeebs-master

Precompiled ​

Precompiled firmwares for all possible configurations are available here. Each file is named according to its configuration, e.g.:

  • crkbd_rev1_via_oled_trackball_left.uf2 is for a Corne, VIA, OLED and trackball on the left.
  • idank_spankbd_via_trackball_trackpoint_left.uf2 is for a Span, trackball on the left, trackpoint on the right and should be flashed pn the left half (idank_spankbd_via_trackball_trackpoint_right.uf2 should be flashed on the right).

To flash, we need to get into the bootloader and copy the firmware file into the USB drive called RPI-RP2. After copying, the drive should disappear and the firmware will have updated.

Entering the bootloader:

  • On a Sea Picro, press the reset button for ~1 second.
  • On an RP2040 Pro Micro, there are two buttons on the components side of the controller: hold the BOOT button and then press the RESET button next to it. If your controller is already flashed with a QMK firmware, you can simply double tap the reset button.

The commands.txt has a list of file name to the make command that produced it and can be used as a reference.

DANGER

Avoid connecting / disconnecting the TRRS cable when the keyboard is powered. This can short the GPIO pins of the controllers.

Compiling ​

Since many of our keyboards share common features such as OLED / Pointing Devices, these are supported via the Userspace feature: this allows the logic to be separated from a specific keyboard / keymap. See the files in users/idank.

Start by setting up a development environment per QMK instructions. Clone the repo above and not the main QMK repo:

shell
# It's also possible to use qmk setup instead of git clone: qmk setup idank/qmk_firmware
$ git clone --recurse-submodules https://github.com/idank/qmk_firmware -b holykeebs-master
$ cd qmk_firmware

Building ​

The basic structure of the build and flash command is:

shell
make <keyboard>:via[:flash] -e USER_NAME=idank [-e feature1=value1]...

The value for <keyboard> should match the keyboard you are flashing for:

KeyboardValue
Cornecrkbd/rev1
Lily58lily58/rev1
Reviung41reviung/reviung41
Sweepidank/sweeq
Spanidank/spankbd
Keyball39keyball/keyball39
Keyball44keyball/keyball44
Keyball61keyball/keyball61

INFO

For Keyball, please see the dedicated section as the options below don't apply.

The table below lists the possible flags that control what feature to turn on in the firmware.

FlagDescription
-e POINTING_DEVICE=tps43
          trackpoint
          trackball
          cirque35
          cirque40		enable pointing device
-e POINTING_DEVICE_POSITION=left
      right
      thumb_inner
      thumb_outer
      middle		specify pointing device position
-e OLED=yesenable OLED screen
-e OLED_FLIP=yesswaps the left and right OLED roles
-e TRACKBALL_RGB_RAINBOW=yesenable a rainbow color animation on the trackball LED

An example command might look like this:

shell
make \
    crkbd/rev1:via:flash \
    -e USER_NAME=idank \
    -e POINTING_DEVICE=trackball \
    -e POINTING_DEVICE_POSITION=right \
    -e TRACKBALL_RGB_RAINBOW=yes \
    -e OLED=yes \
    -j8

Breaking this down:

  1. crkbd/rev1:via:flash flashes for a Corne with VIA. Omitting :flash would just build the firmware without flashing.
  2. -e USER_NAME=idank to also pull code from users/idank.
  3. -e POINTING_DEVICE=trackball configures the trackball.
  4. -e POINTING_DEVICE_POSITION=right configures the trackball to the right side of a split keyboard.
  5. -e TRACKBALL_RGB_RAINBOW=yes configures the rainbow effect on the trackball.
  6. -e OLED=yes enables the OLED.
  7. -j8 parallizes the build process.

::: Details gcc error If the make command fails with gcc: error: unrecognized command-line option ‘-mthumb’, you can try this alternative command:

shell
qmk flash \
    -e USER_NAME=idank \
    -e POINTING_DEVICE=trackball \
    -e POINTING_DEVICE_POSITION=right \
    -e TRACKBALL_RGB_RAINBOW=yes \
    -e OLED=yes -j8 \
    -kb crkbd/rev1 -km via

:::

Flashing ​

Run the command you built in the previous step, with :flash after the keymap name to also flash after building.

If the command succeeded, you should be seeing this at the end:

shell

 _           _       _             _
| |__   ___ | |_   _| | _____  ___| |__  ___
| '_ \ / _ \| | | | | |/ / _ \/ _ \ '_ \/ __|
| | | | (_) | | |_| |   <  __/  __/ |_) \__ \
|_| |_|\___/|_|\__, |_|\_\___|\___|_.__/|___/
               |___/

Pointing Device: trackball
OLED: yes
Keyboard main side: right

WARNING! Avoid connecting / disconnecting the TRRS cable when the keyboard is powered. This can short the GPIO pins of the controllers.

Flashing for bootloader: rp2040
Waiting for drive to deploy...

TIP

Make note of the Flashing for bootloader line: if you're not seeing this at the end of the output, you are not on the correct branch.

Connect the controller to the computer. Sometimes it will go into bootloader if it hasn't been flashed before.

If not, enter bootloader manually:

  • On a Sea Picro, press the reset button for ~1 second.
  • On an RP2040 Pro Micro, there are two buttons on the components side of the controller: hold the BOOT button and then press the RESET button next to it. If your controller is already flashed with a QMK firmware, you can simply double tap the reset button.

On split keyboards, repeat the flashing process for the other controller.

DANGER

Avoid connecting / disconnecting the TRRS cable when the keyboard is powered. This can short the GPIO pins of the controllers.

Dual Pointing Devices ​

When using multiple pointing devices, the pointing device specification turns to -e POINTING_DEVICE=<left>_<right> where left and right take one of tps43, trackball, trackpoint, cirque40 or cirque35. The -e POINTING_DEVICE_POSITION flag can be omitted since it's implied by the pointing device configuration.

Additionally, if each side is using a different pointing device, we now need to specify the side we're flashing with -e SIDE=right or -e SIDE=left because we need a different firmware to be flashed on each side.

Example:

shell
make \
    crkbd/rev1:via:flash \
    -e USER_NAME=idank \
    -e POINTING_DEVICE=trackball_trackpoint \
    -e SIDE=right \
    -j8

The example above flashes the right side, which should be the side with the trackpoint (since it appears on the right of POINTING_DEVICE).

The left side would be flashed as follows:

shell
make \
    crkbd/rev1:via:flash \
    -e USER_NAME=idank \
    -e POINTING_DEVICE=trackball_trackpoint \
    -e TRACKBALL_RGB_RAINBOW=yes \
    -e SIDE=left \
    -j8

Keyball ​

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 exists here.

DANGER

Avoid connecting / disconnecting the TRRS cable when the keyboard is powered. This can short the GPIO pins of the controllers.

While on the holykeebs-master branch, flash both sides using:

shell
make keyball/keyball44:via:flash -j8

USB cable can be connected to either side of the keyboard.

Testing ​

  1. On a split keyboard, connect the halves when none of the sides are powered.
  2. On a split keyboard, the output of the build/flash command will say which side needs to be connected to the computer.
  3. On first use, a dialog from the OS may open to configure a new keyboard, go through that.
  4. Go to test that all of the keys work. Some keys (usually on the thumb clusters) don't generate a regular key. Try pressing those in combination with another key. It's also possible to use VIA's test matrix tab.

If one of the keys do not work, head over to Troubleshooting.

Community Keymaps ​

This section is dedicated to keymaps written by community members, describing the special aspects that were implemented:

@R4_Unit's firmware: 4 layers accessed through a pair of thumb keys. The trackball is different on each layer.

Details

Layer 0: Trackball scrolls the page. For me, my most common mouse action was scrolling in a web browser etc, so this is the default. Works perfectly for this task.

Layer 1: Trackball presses arrow keys. I also really like this for moving inside text fields and it feels really good with the clicks of the trackball. This is how it was used on older mobile phones, and it is really good at this.

Layer 2: Trackball is mouse. Out of the box, the pimoroni is a pretty bad mouse, needing you to drag it edge-to-edge about 5 times to move across your screen. If you just up the sensitivity then it isn’t accurate enough to do things like select individual buttons. I’ve added nonlinear response to mine, so that moving it twice as fast doesn’t just move it twice as far, but actually 4x as far (3x as fast, 9x as far, etc.). This gives you the best of both worlds, and if you use like a Mac trackpad, you are already used to this behavior.

Layer 3: Trackball is app switcher. Again this feels nice as a slightly better version of alt-tab.

I also have a variety of dedicated shortcut keys for things like: screenshot, switch tabs in a browser, basic window arrangement (left-half, right-half, etc.)