Jonas HietalaModify

Why a domain?

If you ever want (or need) to change email providers it’s very nice to have your own domain. For instance, Veronica has a hotmail.com address but she can’t bring that with her if she moves to Fastmail.

Worse, what if she gets locked out of her Outlook account for some reason? It might happen if you forget your password, someone breaks into your account, or even by accident.

In almost all cases, your email is your key to the rest of your digital life. The email address is your username and to reset your password you use your email. If you lose access to your email you lose everything.

When you control your domain, you can point the domain to a new email provider and continue with your life.

Why pay for email?

One of the first things Veronica told me when I proposed that she’d change providers was that she didn’t want to pay. It’s a common sentiment online that email must be cheap (or even free).

I don’t think that email is the area where cost should be the most significant factor. As I argued for in why you should own your email’s domain, your email is your most important digital asset. If email is so important, why try to be cheap about it? You should spend your money on the important things and shouldn’t spend money on the unimportant things.

Paying for email gives you a couple of nice things:

• Human support.

  It’s all too easy to get shafted by algorithms where you might get banned because you triggered some edge case (such as resetting your password outside your usual IP address).

• Ability to use your own domain.

  Having a custom domain is a paid feature at most email providers.

• A long-term viable business.

  How do you run an email company if you don’t charge for it?
  (You sell out your users or you close your business.)

Why a password manager?

The best thing you can do security wise is to adopt a password manager. Then you don’t have to try to remember dozens of passwords (leading to easy-to-remember and duplicate passwords) and can focus on remembering a single (stronger) password, confident that the password manager will remember all the rest.

“Putting all your passwords in one basket” is a concern of course but I think the pros outweigh the cons.

Why a YubiKey?

To take digital security to the next level you should use two-factor authentication (2FA). 2FA is an extra “thing” in addition to your password you need to be able to login. It could be a code sent to your phone over SMS (insecure), to your email (slightly better), a code from a 2FA app on your phone such as Aegis Authenticator (good), or from a hardware token (most secure).

It’s easy to think that I went with a YubiKey because it’s the most secure option; but the biggest reason is that a YubiKey is more convenient than a 2FA app.

With a 2FA app you have to whip out your phone, open the 2FA app, locate the correct site, and then copy the TOTP code into the website (quickly, before the code changes). It’s honestly not that convenient, even for someone like me who’s used this setup for years.

With a YubiKey you plug it into a USB port and press it when it flashes. Or on the phone you can use NFC. NFC is slightly more annoying compared to plugging it in as you need to move/hold it in a specific spot, yet it’s still preferable to having to jump between apps on the phone.

There are hardware keys other than YubiKey of course. I’ve used YubiKey for years and have a good experience. Don’t fix what isn’t broken.

Password management with Bitwarden

The first thing we did was setup Bitwarden as the password manager for her. I chose the family plan so I can handle the billing.

To give her access I installed Bitwarden as:

1. An app on her phone
2. A browser plugin on her computer

I gave her a YubiKey and registered it with Bitwarden for additional security. As a backup I also registered my own YubiKeys on her account; if she loses her key we still have others she can use.

Although it was a bit confusing for her I think she appreciates not having to remember a dozen different passwords and can simply remember one (stronger) password. We can also share passwords easily via Bitwarden (for news papers, Spotify, etc).

The YubiKey itself is very user friendly and she hasn’t run into any usability issues.

Email on Fastmail

With the core security up and running the next step was to change her email:

1. Gave her an email address on Fastmail with her own domain (<firstname>@<lastname>.com).

   She has a basic account that I manage (there’s a Duo plan that I couldn’t migrate to at this time).

2. I secured the account with our YubiKeys and a generated password stored in Bitwarden.

3. We bolstered the security of her old Hotmail account by generating a new password and registering our YubiKeys.

4. Forward all email from her old Hotmail address to her new address.

With this done she has a secure email account with an email address that she owns.

As is proper she’s been changing her contact information and changing email address in her other services. It’s a slow process but I can’t be too critical—I still have a few services that use my old Gmail address even though I migrated to my own domain more than a decade ago.

Notes on recovery and redundancy

It’s great to worry about weak phishing, weak passwords, and getting hacked. But for most people the much bigger risk is to forget your password or lose your second factor auth, and get locked out that way.

To reduce the risk of losing access to her accounts we have:

• Multiple YubiKeys for all accounts.
• The recovery codes for all accounts are written down and secured.
• My own accounts can recover her Bitwarden and Fastmail accounts via their built-in recovery functionality.

Base

• The repeat key is used to output the last pressed key.
• I shift keys using auto shift (see long press) and CAPSWORD.
• The letters Z and Q, together with a bunch of other keys, are on combos.
• The keys for F2, F12 and FUN are just extras and aren’t in a comfortable enough position to warrant anything more common.

Swedish overlay

When I want to write Swedish I activate this layer that replaces ()_ with åäö, or I use combos from any layer.

Symbols

I typically use combos to output symbols (following the same layout pattern as the symbols layer). The symbols layer is mostly used to roll symbol pairs like {} or #[.

Some common symbol sequences (like ->, != , or ```) exists as combos and others as long press.

Numbers

While I can activate the number layer persistently (using leader sequences) I typically use combos for single digits (like 0), or NUMWORD for larger numbers (like 1984).

NUMWORD makes the number layer smart, so it will deactivate when certain keys are pressed. It’s used to type numbers in text or code and for relative movement in Neovim, where 17J would move 17 lines down and then turn off the number layer. Jumping directly to a line in Neovim with 12G is also made convenient.

If I want to enter the layer without it turning off I can either use leader sequences to activate it persistently or hold the NUMWORD combo (hold both thumbs). The layer won’t release until both thumb keys are released, so Space can be tapped with the left thumb without leaving the number layer.

@u is there to easily activate macros in Neovim. For example 7@u in the number layer would run the u macro 7 times and then turn off NUMWORD.

Function keys

• The function keys follow the same layout as the numbers layer.
• The trackball DPI can be lowered and raised at runtime.

Navigation layers

• Keys with Gui are used in xmonad.

  • Gui + W, Gui + E and Gui + R are used to switch between monitor.
  • Gui + J/Gui + K to switch windows.
  • Gui + ,/Gui + . to add/remove windows from the “master” area.

• This layer is commonly used in conjunction with the trackball, giving access to mouse keys.

  For instance, Shift + Left Mouse can be used to drag, Ctrl + A to select, and Ctrl + C to copy.

• Tabbing is for switching browser tabs and the Back / Fwd mouse buttons goes backwards and forwards in history.

• Ctrl + arrow is used to switch windows in Neovim.

• Ctrl + D and Ctrl + U are used in Neovim to scroll half a screen (compared to PgUp/PgDn that scrolls an entire screen).

• The workspace layer is triggered by first holding Space, and then holding the right thumb key (WNAV).

This layer exists for the rare occasions I want to navigate using only the left hand. The keys on the right side is there just because and are rarely, if ever, used.

Workspace layer

This is used for all window and workspace management in xmonad. Some common operations are also on the navigation layer. Auto shift works and can used to send a window to another workspace (Gui + Shift + 2).

Windows layer

This is purely to enable window switching using Alt-Tab and Ctrl-Alt-Tab, without releasing Alt.

Mouse layer

I generally prefer to use the navigation layer, where the mouse buttons are on the left side, but in some cases I’d like to only use my right hand.

Special characters

The dead keys add diacritic to any letter. For example, to get é you can use the dead key ´ then e, and the operating system will merge them together. (É also exists as a combo.)

Modifiers

I typically use long press for shift and combos for other modifiers, this layer is a fallback for when those aren’t enough (the layer is mostly used for Right Alt).

Gaming layer

I’m not a heavy gamer by any means but this layer allows me to play Core Keeper with my kid. By necessity this layer disables auto shift.

Neighbour combos

These combos are made by keys next to each other, either horizontally (pressed with two fingers) or vertically (pressed with one finger in the middle of two keys).

• Some combos have a separate hold behaviour; for instance holding Escape activates the symbols layer, allowing me to output [] easily.
• vsplit splits a window vertically in Neovim and hsplit splits it horizontally, and Close Window closes a window in Neovim (<C-w>q).
• Clear resets all states; sets the base layer, releases modifiers, stops CAPSWORD and NUMWORD, and clears other persistent states.
• Ctrl + Shift + M is the shortcut to mute/unmute in Teams.

• SWE activates the Swedish layer, and if prefixed with ()_ it will replace that with åäö and vice versa. So for example if I typed hall( I would press SWE to get hallå, with the Swedish layer activated.
• Ctrl W is used to close tabs in Firefox.

• Save Neovim is a 4-key combo that saves the buffer in Neovim.

Split combos

These split combos uses the ring and index finger.

Combos over keyboard halfs

• Tapping T + A once activates CAPSWORD, tapping again makes it persistent (CAPS LOCK), and a third tap to deactivate CAPS LOCK.
• Tapping Space + E activates NUMWORD and tapping them again activates the number layer persistently.

The repeat key works with the above, making them easier to double-tap.

• Swaps _ and -.

• Access the specials layer with the ring fingers.

Thumb key combos

I have a bunch of 2-key thumb + key combos:

The logic here is that same-side thumb + key = symbol and opposite-side thumb + key = digit, following the placements of the numbers, symbols and swedish layers. They’re used if I want to just type a single character, without having to activate a layer first.

I have similar combos for the function keys.

QMK boot

The keycode QMK_BOOT enters boot mode for the microcontroller connected via USB, making it easy to update the keymap on the keyboard. These two 5-key combos (one for each half) are almost impossible to trigger accidentally while being easily accessible.

Long press

Most keys have a different behaviour when tapped compared to a long press. Most commonly I use this to produce shifted keys (called auto shift). So tapping the A key will output a as normal and if it it A will appear instead.

There are a bunch of special cases as well (many on top of combos):

Leader sequences

I use the combo l + ) as the leader key. This will wait for a sequence of key presses (in contrast to combos where keys must be pressed at the same time). I use this with mnemonics for rarely used outputs:

CAPSWORD

CAPSWORD is a “smart caps lock”. It works like a regular caps lock, except it automatically turns off after certain keys are typed (most commonly space).

It will not turn off on letters, numbers, _ - Backspace and the Repeat keys.

NUMWORD

NUMWORD is a “smart layer”. It’s similar to CAPSWORD, except it activates and then turns off the numbers layer instead of caps lock.

It will not turn off on these keys: 0-9 % / + * - _ . , : = x Backspace Enter and the Repeat keys.

Repeat key

The repeat key simply repeats the previous key. So to type fall I can type f a l Repeat, using four different fingers instead of pressing l twice. It can also repeat things like Ctrl-c or Delete, and unlike regular keys that use auto shift the Repeat key can be held.

Trackball

The trackball is normally configured to move the mouse as a regular trackball.

There are different modes that alters the behavior of the trackball:

1. Lower the DPI when Space or _ are held (the mouse moves slower when the navigation layer or the mouse layer are active).
2. Raise the DPI when the MOD combo is held (the mouse moves faster).
3. Scroll instead of moving the mouse when the SYM combo is held.

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.