Building my ultimate keyboard ★

First print

For my first print I mostly wanted to print it out and test how a keyboard with a standard curvature felt. I also wanted to try to place a trackball somewhere.

I ended up removing a regular thumb key (I’ve used two thumb keys with my keyboard layout) to make it fit and I added a “mouse thumb key” that I plan to use as a left mouse button when I’m operating the trackball. It was tricky to place the trackball as I wanted to operate it with my index + middle finger, not my thumb.

Another tweak I made was to reduce the spacing between the keys to be closer to the Choc spacing. Choc spacing seems to be 18.6 x 17.6 mm, but I used 19 x 18 mm spacing—the attraction to round numbers is real.

Pressing the top right key with the ring finger

Most of the keys on the keyboard felt fine but I had one major annoyance: I have a habit of using the ring finger to press the top right key instead of the pinky but with the curvature on the keyboard this just wasn’t possible anymore.

You might wonder, why don’t I just create a new habit and use the pinky as you’re supposed to? The simple answer is that I hate it. To my fingers that feels beyond terrible and I’d rather remove the key and only have two keys in the outermost column. As it happens, pressing the key with my ring finger (on a flat keyboard) feels good so I’d rather adjust the key than remove it.

I also added an extra mouse thumb key and lowered the pinky column a bit.

Adjust mouse keys and increase tenting

Pressing p with my ring finger feels great. Pressing the thumb normal thumb key feels awful because the mouse thumb keys are in the way when I relax my hand.

Adjustments made:

Rounded base and pinky tweak

Thumb keys adjustments

More tweaks and the left half

Although I said I wanted to have a 3x5 grid, the generator included an easy option to include a small bottom row with 2 extra keys (for the ring and middle finger) that I wanted to try out for the left side. They’re… Okay I guess. Not crazy uncomfortable but not quite comfortable enough that I want to have common keys there.

Beta V3

At this point the Beta V3 of configurator is out and in it there’s several improvements, most notably:

I had to redo most of the configuration and I think I made some minor changes that I didn’t keep track of, but I made two larger ones:

Small tweaks to pinky and thumb keys

Trackball mounting types

When I started this project Cosmos only supported a single type of trackball mount: roller bearings. They worked quite poorly for me as the ball was spinning well in one direction but poorly in others.

Luckily new options were added and as I’m writing this there’s 4 different ways you can mount the trackball:

1. Roller bearings (the old option)
2. BTU (7.5mm or 9mm)
3. Static ball bearings (3.175mm)

Because I was burned with the bad experience (and I didn’t want to rebuild the keyboard yet again) I made small prototypes of the three different options:

The BTUs had the least friction and it felt really easy to spin the ball but they were also distressingly loud. The static ball bearings had more friction than the BTUs and less than the roller bearings while being completely silent, so I chose to go with the ball bearings.

While they don’t feel nearly as good as the Kensington SlimBlade they’re decent enough. I try not to use the mouse that much and having the trackball so much closer is worth it compared to having a separate trackball unit besides the keyboard.

Remove mouse keys

After having used the keyboard for real I realized that the three keys dedicated to mouse buttons would have to go. There were two major issues with them:

So I had them removed and I rewired the right half for the 3rd time. Sigh.

I think the lesson is that it’s not enough to print a prototype and press switches pretending to type, you have to build and use the keyboard a bunch before you can evaluate some of the design decisions.

Cosmos reference

Wrist rests

Magnet attachments

The wrist rests didn’t come with any sort of attachment to the case, so they just always drifted away. I tried to combat this by gluing magnets inside the case and outside the wrist rest, making them stick together just enough to stay together during normal use, while being easily removable.

I ended up not using the wrist rests

Despite my efforts, I haven’t been using the printed rests as I reverted to the ”squishy” ones I’ve used before:

The printed felt too uncomfortable and I couldn’t find an angle I liked more than the gel rests. Oh well.

Microcontroller holder

There’s a holder to fasten the microcontroller to the case that I use. I had to manually make a hole to make the Boot button accessible, which was easily accomplished when slicing the model.

Bottom plate

One problem with the Ferris was that it would sometimes slip on the table. I counteracted this by using an old Netrunner playmat but I wanted another solution.

The keyboard is generated with a bottom plate that’s used to hide and protect the internals. I printed it in TPU, a flexible and rubbery material, that gives enough grip to stay relatively still when I’m typing.

Matrix

One of the first things you need to do when wiring up a custom keyboard is to plan out a matrix. I guess you could directly wire every switch directly to the controller too, but that’s not feasible if you have a larger amount of keys, so the usual thing is to use a matrix.

What a matrix means is you should wire together all keys in a row and connect that to a pin on the controller, and to the same with the columns.

It might look something like this:

You should also use diodes in the matrix (for either rows or columns, I chose the rows). Pay attention to the diode direction.

The wiring is horrible, I know.

I only lost one microcontroller due to a short… With my wiring prowess I consider that a success!

Controller wiring

Basic setup

The folder structure for the keyboard looks like this:

cybershard
├── keyboard.json
├── rules.mk
├── halconf.h
├── mcuconf.h
└── keymaps
    └── default
        ├── config.h
        ├── keymap.c
        ├── rules.mk
        └── ...

(Cybershard is the name I eventually settled on for the keyboard.)

The most important part is keyboard.json that defines (almost) everything we need for a new keyboard in QMK.

First you need to set the processor, bootloader, and usb values. The Liatris microcontroller uses the RP2040 MCU, and I just picked some vendor- and product identifiers:

{
    "keyboard_name": "cybershard",
    "processor": "RP2040",
    "bootloader": "rp2040",
    "usb": {
        "device_version": "0.0.1",
        "pid": "0x0002",
        "vid": "0x0361"
    },
}

Then we need to define the matrix (with the pins we soldered) and the layout (how we’ll configure the keymap in keymap.c):

{
    "diode_direction": "COL2ROW",
    "matrix_pins": {
        // We need to use a `GP` prefix for the pins.
        "rows": ["GP26", "GP27", "GP22", "GP20"],
        "cols": ["GP3", "GP4", "GP5", "GP6", "GP7"]
    },
    "layouts": {
        "LAYOUT": {
            "layout": [
                // First physical row
                { "matrix": [1, 0], "x": 0, "y": 0 },
                { "matrix": [0, 1], "x": 0, "y": 0 },
                { "matrix": [0, 2], "x": 0, "y": 0 },
                { "matrix": [0, 3], "x": 0, "y": 0 },
                { "matrix": [0, 4], "x": 0, "y": 0 },

                // Second row
                { "matrix": [2, 0], "x": 0, "y": 0 },
                { "matrix": [1, 1], "x": 0, "y": 0 },
                { "matrix": [1, 2], "x": 0, "y": 0 },
                { "matrix": [1, 3], "x": 0, "y": 0 },
                { "matrix": [1, 4], "x": 0, "y": 0 },

                // etc...
            ]
        }
    }
}

Note that we can pick whatever physical pins we want as we can move around and configure them in software. The LAYOUT macro is what we use in keymap.c to define our keymap. When defining it we can choose to skip certain keys and reorganize it to be easier to define; for example, there’s no switch at 0,0 in my keyboard so I skip that.

The above LAYOUT can then be used like this:

LAYOUT(
 SE_J,    SE_C,    SE_Y,    SE_F,    SE_P,
 SE_R,    SE_S,    SE_T,    SE_H,    SE_K,
 SE_COMM, SE_V,    SE_G,    SE_D,    SE_B,
          SE_A,    SE_B,
                            // Thumb keys
                            FUN_CLR, MT_SPC,
),

Flashing

With the above setup we should be able to flash the keyboard by first entering the boot loader and running:

qmk flash -kb cybershard -km default

Now the process of updating the firmware is quite nice and unless I screw up I don’t need to connect another keyboard to do it.

1. Start flashing with qmk flash (it will wait until it finds a flashable target).
2. Press the QK_BOOT combo (the keyboard becomes unresponsive).
3. Wait until the script finishes and the keyboard is available again.

Split keyboard

To get the split keyboard feature to work I had to set the SERIAL_DRIVER option in rules.mk:

SERIAL_DRIVER = vendor

And add the split configuration to keyboard.json and modify the LAYOUT macro:

{
    "split": {
        "enabled": true,
        // The pin that signals if the current controller is the left (high)
        // or right (low) controller.
        "handedness": {
            "pin": "GP1"
        },
        // The TRRS data pin.
        "soft_serial_pin": "GP2",
        "matrix_pins": {
            "right": {
                // We can override the pins for the right controller.
                // Note that GP26 and GP27 are swapped compared to the left side
                // due to a mistake I made when soldering.
                "rows": ["GP27", "GP26", "GP22", "GP20"],
                "cols": ["GP3", "GP4", "GP5", "GP6", "GP7"]
            }
        },
        "transport": {
            "sync": {
                // We need to sync the matrix state to allow combos, mods, and
                // other stuff to work.
                "matrix_state": true
            }
        }
    },
    "layouts": {
        "LAYOUT": {
            // The rows 0 to 3 specifies rows on the left side and
            // 4 to 7 the rows on the right side.
            "layout": [
                // These 5 keys are the first row on the left side.
                { "matrix": [1, 0], "x": 0, "y": 0 },
                { "matrix": [0, 1], "x": 0, "y": 0 },
                { "matrix": [0, 2], "x": 0, "y": 0 },
                { "matrix": [0, 3], "x": 0, "y": 0 },
                { "matrix": [0, 4], "x": 0, "y": 0 },
                // These 5 keys are the first row on the right side.
                { "matrix": [4, 0], "x": 0, "y": 0 },
                { "matrix": [4, 1], "x": 0, "y": 0 },
                { "matrix": [4, 2], "x": 0, "y": 0 },
                { "matrix": [4, 3], "x": 0, "y": 0 },
                { "matrix": [4, 4], "x": 0, "y": 0 },

                // etc..
            ]
        }
    }
}

The LAYOUT macro is just a function with many arguments but with the right order it can be formatted to look similar to the physical keyboard. For example, this is how the base layer of my keyboard could look like:

LAYOUT(
 // Left side                                    // Right side
 SE_J,    SE_C,    SE_Y,    SE_F,    SE_P,       SE_X,    SE_W,    SE_O,    SE_U,    SE_DOT,
 SE_R,    SE_S,    SE_T,    SE_H,    SE_K,       SE_M,    SE_N,    SE_A,    SE_I,    REPEAT,
 SE_COMM, SE_V,    SE_G,    SE_D,    SE_B,       SE_SLSH, SE_L,    SE_LPRN, SE_RPRN, SE_UNDS,
          // The extra two keys on the left side
          SE_MINS, SE_PLUS,
                            // Left thumb keys   // Right thumb key
                            FUN_CLR, MT_SPC,     SE_E
),

Trackball

It took a long time for me to get the trackball working (admittedly, mostly because I soldered the pins wrong). There’s quite a lot of documentation for QMK but curiously enough I didn’t find anything that covered the whole setup. I arrived here by trial and error, trying to piece together parts from other keyboards into a setup that worked for me.

First we need to create the files halconf.h and mcuconf.h (they go in the same folder as keyboard.json) to enable the SPI driver:

#pragma once
#include_next <halconf.h>
#define HAL_USE_SPI TRUE

#pragma once
#include_next <mcuconf.h>
#undef RP_SPI_USE_SPI1
#define RP_SPI_USE_SPI1 TRUE

And enable the pointing device with the pmw3389 device driver in rules.mk

POINTING_DEVICE_ENABLE = yes
POINTING_DEVICE_DRIVER = pmw3389

Now we need to add the sensor pins to config.h:

// SPI1, matching mcuconf.h
#define SPI_DRIVER SPID1
// The pin connections from the pmw3389 sensor
#define SPI_MISO_PIN GP12
#define PMW33XX_CS_PIN GP13
#define SPI_SCK_PIN GP14
#define SPI_MOSI_PIN GP15

This should be enough to get the sensor going, but because we have a split keyboard we need to set that up too:

#define SPLIT_POINTING_ENABLE
// The trackball is on the right
#define POINTING_DEVICE_RIGHT

There are some additional tweaks that I had to play with to make the trackball work well:

// The trackball is quite sensitive to how
// large the liftoff distance should be.
#define PMW33XX_LIFTOFF_DISTANCE 0x10
// Sets the mouse resolution, up to 16000.
#define PMW33XX_CPI 1600
// The directions where messed up, this fixes it.
#define POINTING_DEVICE_ROTATION_270 1
#define POINTING_DEVICE_INVERT_X 1

With that I got the trackball moves the mouse as expected.