The RevXL is a maximalist Reviung-inspired ergonomic keyboard with per-key RGB LEDs, an OLED display, a rotary encoder, and a breakaway arrow cluster. It’s powered by a wired RP2040 microcontroller with QMK and Vial handling things on the firmware side. At its core, the RevXL is designed to be an on ramp to the ergonomic mechanical keyboard space. It shows off the scene’s most catchy bells and whistles while still providing a few creature comforts of more traditional layouts.

This design is a bit of a throwback for me. My journey into this strange world of ergonomic mechanical keyboards started with building a kit of the oft-praised Sofle Choc. It's a split keyboard which features RGB LEDs, an OLED Display, and a pair of rotary encoders. Noticing some similarities here? Once I was ready to start making designs of my own, I leapt straight into the world of wireless ZMK-powered keyboards with the ChonkV and the Type Boy. As much as the flashy lights and enticing knobs drove me to the Sofle, I never actually learned how to build a wired keyboard with RGB LEDs. This keyboard is a chance to backfill some of those PCB design skills I skipped over while taking the Reviung layout for a spin.

Sponsored By PCBWay

Speaking of PCB design, this project is sponsored by PCBWay. They're the internet's premier PCB fabricator and are a one-stop-shop for all your prototyping needs. They offer PCB fabrication services, 3D printing with a variety of materials, and even PCBA assembly services for those of you who prefer not to solder their own projects. If it can be represented as a design file, you can probably upload it to PCBWay and receive it a few days later in the mail.

PCBWay did a great job manufacturing the RevXL PCB. The order shipped quickly, and all of the PCBs arrived safe and sound inside of a well packed box and vacuum sealed bubbled wrap. My thanks to PCBWay for helping to make this keyboard a reality.

The RevXL Layout

This keyboard is a very longwinded answer to the question, "Wait, those low profile keyboards of yours have clicky switches too?" That's right, the RevXL design is technically a Homer. After seeing me build a set of increasingly elaborate keyboards, my husband finally got low profile mechanical keyboard curious. His initial design ask had three parts: Clicky Choc switches, per-key RGB LEDs, and the layout had to have an arrow cluster that wasn't buried on a secondary layer.

As much as I like designing keyboards from scratch, Keeb.io's Cepstrum sounded like a solid fit for these design priorities. It's a split row-staggered 65% keyboard with low profile switches and per-key RGB LEDs. Unfortunately, Choc v1 switches are still relatively niche in the custom keyboard building space. There are more keycap options now than their used to be, but there are literally no shine-through options for the larger row-staggered keys. Your 1.75u Caps Lock, 2.25u Enter, and 2.75u Shift all have to go without any labels on the keys. Keeb.io's made the best of this situation by providing some near-matching blank keycaps for these modifiers, but it's a less than ideal situation aesthetically speaking.

That left us in a bit of a lurch. The obvious next steps were to either ditch the row-staggered layout, or look beyond the Choc v1 switches into the world of MX-stemmed keycaps.

FK Customs does offer low profile shine-through keycaps in the form of their new LPF profile keycaps. Paired with some Choc v2's and we'd be all set to go. I'd also just be making another 65% keyboard at that point however. Having just come off of the 65 Crimes build, I was hoping to do something a little different. I had to broach the ergonomic question.

"Just how weird can I get with this layout?"

I've been happily typing along on unusual bespoke ergonomic mechanical keyboards for the last two years. When you get into a niche hobby like this, you have to be weary that you don't delve too far off the deep end and become a weird keyboard pusher. I was all ready to accept that going beyond row stagger would be a red line for this build. To my surprise, after spending a day experimenting with my old Sofle, my husband decided to give an ergonomic layout a try. The previous ask for some dedicated arrow keys remained however. With those updated parameters in place, I got to work creating a potential layout.

I decided to use the Reviung layout as the basis of my inspiration for this build. I've always liked the striking look of Reviung keyboards, and the unibody layout would make the logistics of dealing with the RGB LEDs a bit simpler. I was already tackling some new technologies in this build. Omitting the dual microcontrollers, reversible footprints, and TRRS cable would help manage the scope of this project.

Reviung variants have featured a variety of thumb key configurations over the years. I'm particularly fond of Pete Johanson's revxlp's split spacebar design, so I shamelessly copied that for the RevXL. I'm still a sucker for dedicated number keys, and this design is supposed to be for a beginner friendly keyboard anyways, so I added a number row onto the basic Reviung41 layout.

At this point I'm awfully close to 42Keebs' Rev57LP design. They've even added RGB LEDs to the latest revision of this keyboard. If you're looking for a big low profile Reviung, it's probably a much more straightforward option. They even have some nice acrylic cut cases options. The RevXL needed arrow keys however, so I was firmly in the realm making a custom design.

Arrow keys aren't completely unheard of in ergo mech circles. The hillside52 and Atalante have found room to sneak arrow keys into a traditional split ergonomic keyboard layout, and designs like the articulation70 have dabbled in adding entire clusters. My largest inspiration came from Afternoon Lab's Breeze keyboard however. It too is designed to be an introductory ergonomic split keyboard. It features a layout very similar to the Lily58, but with a breakaway arrow key cluster added onto the side. I always liked the idea of physically being able to "graduate" to a smaller keyboard, and the aesthetics of the optional module are pretty nice.

With those inspirations in tow I hopped into Ergogen and got to work. Thankfully this keyboard is fairly similar to the design I created in my Ergogen tutorial series. Ergogen has you break a keyboard down into a group of "points" which are used to define where the key switches and other parts should go. From there you define an "outline" which is used to create the shape of the board, and then finally the "pcb" and the 3D "case" files. This particular build doesn't have many tricks that should be unfamiliar for folks who read that series. The most substantial wrinkle is the amount of point groups I created. There's a dedicated definition for the main key groups, the modifiers, the layer keys, the spacebars, and the arrow cluster.

The biggest deviation from the influences I just rattled off is the PCB's overall shape. Most Reviung derivatives have a PCB outline that hugs fairly tightly to the key layout. That would work here, but then the more organic shape would just sort of be bolted onto the rounded rectangle of the arrow cluster. Instead I decided to lean into the more square shape of the arrow cluster and expanded it out to cover the rest of the Reviung layout. As you can see the rectangle doesn't quite cover all of the main keyboard, but it does so in a way that actually looks pretty nice. The top and bottom keys poke out of the keyboard's basic outline ever so slightly. It maintains the travel-friendly rectangular shape while providing just enough character to the RevXL. You almost get the sense that the keyboard's trying to break outside of the conventional box.

I usually don't write this much about a keyboard's basic layout. I drew inspiration from a lot of existing designs for this build however, and it's always good to show your work. Hopefully that bit of extra backstory will explain the maximalist character of this particular board.

RGB LEDs

The per-key RGB LEDs were one of the largest drivers of this board. QMK features all sorts of dazzling lighting effects. Strobing rainbows, green Matrix rain, velocity matched heat maps, the list goes on and on. It's a sight to behold, and thanks to the introduction of the RP2040, QMK-compatible microcontrollers now have much more storage space to contain these light shows.

The RevXL uses SK6812 MINI-E LEDs. SK6812 is the generic name for Adafruit's NeoPixels if you're familiar with that product line. The SK6812 is available in several different form factors with frustratingly different pinouts. Make sure you buy the right ones if you're working with these LEDs. The "MINI-E" variant has long legs which are more easily hand-solderable. They sit on the underside of a PCB and shine up through a hole in the PCB. Choc v1 switches have a small transparent hole in the top half to let LEDs shine through and light up the bottom of a keycap.

SK6812 LEDs operate off of a one-wire serial protocol. (The practice is affectionately known as "Bit Banging".) They're wired together in a series similar to Christmas tree lights. Each SK6812 has a Digital-In pin, a Digital-Out pin, as well as a power and ground pin. The first LED connects its input pin to your microcontroller. Then it uses its output pin to connect to the input pin of the second LED. The second LED connects its output pin to the input pin of the third LED, and you continue the chain until you get to the last LED. On the software side of things, the microcontroller is able to say, "LED 8 needs to be green right now." Each LED in the chain reads the message and determines if it has instructions for it to act on. If LED 8 reads the message, it will update its color. Otherwise it just disregards the message and passes it along the chain for the correct LED. It's a simple setup and only needs one extra data pin from your microcontroller.

The complexity comes in the wiring. Keyboards traditionally have a matrix of columns and rows. On most builds, it's not too difficult to fall into a pattern of wiring your row pins on one side of the keyboard, then placing the column routes on the reverse side of your keyboard. They generally stay out of each other's way and you can have nice repeatable patterns in your wiring. Then your LEDs get in the way and start snaking across the matrix in a complicated S-shaped pattern. Sometimes it's going left and right, other times it needs to drop down to the next row, and all the while every key now needs access to power and ground.

The trick to keeping this all neat and organized on your keyboard is, uh... You don't?

Your wiring's going to be a bit of a mess. Unfortunately your Ergogen config will be as well. (If you're not interested in how these are configured in Ergogen, feel free to hop onto the next section.)

Ergogen was designed to have nice minimalist code. You can easily specify "The far left column will all connect to Pin8" and "the middle row will all connect to Pin4." LEDs don't work like that. They need to know, "I'm LED32, I connect to LED31 and LED33." In the world of Ergogen, that means you're going to have to create an entry for every key on your keyboard.

To accomplish this, let's first start with the footprint definitions. I've included the switch, diode, and LED definitions here so you can see how they're placed in relationship to one another. (Some parameters have been committed with [...], check out the Github repo for the full code.)

footprints:
  # Hotswap Choc keys.
  choc_hotswap:
    what: switch_choc_v1_v2
    where: true
    params:
      [...]
      from: "{{column_net}}"
      to: "{{colrow}}"
    adjust:
      rotate: 180
  # SMD Diodes
  diode:
    what: diode_tht_sod123
    where: true
    params:
      from: "{{colrow}}" 
      to: "{{row_net}}"
    adjust:
      shift: [-8.275, 1]
      rotate: -90
      resist: true
  # LEDs
  sk6812:
    what: led_sk6812mini-e
    where: true
    params:
      P2: "{{key.led_next}}" #DOUT 
      P4: "{{key.led_prev}}" #DIN
    adjust:
      shift: [0, 5]

The SK6812 footprints are from Ceoloide's excellent ergogen-footprints repository. Since I was already importing some footprints from that repo, I'm also using his Choc and diode footprints as well.

The rotate: 180 parameter in the Choc switch ensures that the LED is shining through the top of the key. The to: and from: switch and diode parameters are unchanged from their usual configuration.

The LED footprint contains four pins. P1 maps to VCC by default, P3 maps to GND, and P2 and P4 are initially undefined Digital-Out and Digital-In pins. In this Ergogen config, we've specified a slightly unusual {{key.led_next}} and {{key.led_prev}} variable definitions. As discussed in my Ergogen tutorial, these are not fixed keyword properties in Ergogen. These are variable names that we've created ourselves. They could just as easily be called {{key.led_dout}}. All these configurations are saying is, "Look at the key: property for each point. There should be a property called led_next: and led_prev: which define the nets for this footprint."

This is where the tedious needing-to-configure-every-switch step comes in. Up in your points: definition, each column area will look like this:

points:
  zones:
    matrix:
     [...]
     columns:
       outer:
         key:
           column_net: col0
         rows:
           bottom:
             key:
               led_prev: LED23
               led_next: LED24
             mirror.key:
               led_prev: LED34
               led_next: LED35
           home:
             key:
               led_prev: LED12
               led_next: LED13
             mirror.key:
               led_prev: LED45
               led_next: LED46
           top:
             key:
               led_prev: LED11
               led_next: LED12
             mirror.key:
               led_prev: LED46
               led_next: LED47
          [...]

Inside of each columns: section we need to create an intersecting rows: definition. This is where our key: property with the led_prev: and led_next: variable will live. Here we're able to define that matrix_outer_top has a key property of led_prev: LED11 and led_next: LED12. The next LED in the chain is matrix_outer_home with led_prev: LED12 and led_next: LED13. This continues all the way around the keyboard, including on the mirrored side with the mirror.key: properties you can see in the above example. (If it's not clear, the [...] ellipses are just truncating parts of the config.yaml file which aren't relevant for this LED example.)

The LED order is a little tricky to follow in the above example. My LEDs travel up and down each row, so in the column definitions the numbers jump pretty significantly between keys. These are the definitions for keys 12, 13, and 24 in the diagram below.

Hopefully that's enough to help you get going. It makes for a bit of a bloated config. If you have a preview of your PCB in another window, it's thankfully not that hard to define every key. I have my LED chain snake back and forth every column starting from the top left.

Screen & Rotary Encoder

The SSD1306 display is back! This OLED screen is used commonly in mechanical keyboard builds. There's nothing too fancy here. I have a different image I'm showing for each layer in the keymap config. I haven't had a chance to kick the tires much with the screen in QMK too much, but it'll be nice to experiment with in the future.

The rotary encoder is also your bog standard EC11 encoder with pushbutton action. The pushbutton is wired into the keyboard matrix with a diode like any other switch on the board. The actual rotation pieces need an additional two pins. I hadn't done much shopping for knobs before laying out the rest of the keyboard. It turns out most options are either 20mm or 25mm. The gap between the keys is closer to 24mm, so I ended up going with one of the nicer 20mm knob options.

The Breakaway Arrow Cluster

PCBs are manufactured from large sheets of FR-4 fiberglass composite and copper. Your PCB is typically manufactured on the same FR-4 sheet as several other designs. Manufacturing services will silently "panelize" a PCB before sending it through the fabrication process so that your small PCB can be cleanly snapped off from the larger sheet.

There are a variety of techniques to create these breakaway tabs. They typically use a pattern of small drill holes to weaken the structure of the PCB near the edge you need to break off. This has lead to them receiving the affectionate name of PCB "mouse bites". Sparkfun has published an entire white paper on the design of these perforated tabs.

Nothing's to stop you as a designer from including your own breakaway tabs. (Except for perhaps your PCB fab's manufacturing policies.) One interesting design option with mouse bites is that you can often send traces between perforated holes. As long as your circuit doesn't need to be a complete loop, you can include optional components on the far side of breakaway tabs. If you need those parts of the board, you can keep them intact. If you don't need those components, you can snap them off without disrupting the electronics on the main part of your circuit.

Thanks to the chain-like nature of the RGB LEDs, that means we can snap off the last 10 keys without disrupting the rest of the circuit. The keyboard matrix likewise doesn't mind the last two columns being unceremoniously snapped off. Even if this ergo mech experiment ends up being a bust for my husband, I'll still have a nice traditional Reviung board for my own use.

I'm not going to lie, part of me just likes the aesthetics of the breakaway section. I might keep the arrow keys intact even if I end up daily driving one of these boards. Flexibility in one's keyboarding is always nice. I definitely didn't follow the best practices here. I'm using large 2mm drill holes for my mouse bites similar to the Breeze keyboard. They're more like... Capybara Bites? It worked well enough for me, but it might be worth searching out some other examples if you're serious about panelization.

If you do take this same route, I highly suggest using flush cutters rather than actually snapping the PCB. Fiberglass shards can do really nasty things to the inside of one's lungs. Avoid using Dremel or sandpaper as well. Or maybe just wear eye protection and a spare KN95 you've got laying around.

Keycap Considerations

Hang on. We went over this in the layout section. This keyboard only uses 1u keycaps. We just need a copy of MBK Glow and we're good to go. Next section!

Err...

Right. So it turns out that in my haste to recreate the four arrow keys and the six other cluster keys, I never actually checked to see if the MBK Glow keycap set contained an Insert, Home, End, Page Up, or Page Down key. I'm all set with Delete, but the other arrow cluster keys would need to leverage one of the keycap set's more generic symbols.

The whole point of this layout was trying to make an aesthetically uncompromised keyboard. Whoops. No problem. I can still fix his. FK Caps has their FK Custom service! I can just print a few keycaps to round out the set. No problem!

Small problem. It turns out FK Custom has a $40 minimum purchase limit. That means you need to manufacture over custom 30 keys in a single order. Well drat. I would need to design an entire new keycap set to make it worth printing out a few extra keys.

I Designed An Entire New Keycap Set To Make It Worth Printing Out A Few Extra Keys

I think I may be starting to lose the plot of this particular build. I started looking into FK Custom, and the got the ball rolling on a back burner idea I've had in my head for a while. I've always liked the idea of keycap glyphs which are inscrutable at first glance, but actually start to make sense if you stare at them long enough. I had a couple of false starts down this path, but settled on a minimalist low resolution pixel look.

Moonbase has an excellent blog post exploring the readability of low resolution pixel fonts. 3x3 pixels is just enough resolution to start cobbling together letters. Some fare better than others. A and T are clear enough, but you have to use your imagination a bit with W and E. Some symbols rely more on context. S and 5 are both made up of the same curved few pixels. As Moonbase detail in their blog, 3x4 is when things start getting really legible. If you were building a real font, you probably wouldn't want X, %, and ⌘ to all use the same glyph. The brutalist inscrutability is the point here though, so I held off on increasing the resolution any further.

I was always planning on building one of these RevXL boards for myself. Now I'll have some visual flair for it and any other backlit RGB keyboards I make in the future. I've gotten a few asks to try this font out, so I cobble together a TrueType font based off the .svg files I made for the keycap set. Say hello to Threebee everyone. Be nice.

Assembly

There's nothing too outside the ordinary on this build. The RevXL is designed for Choc v1 switches using Choc hotswap sockets. It uses surface mount 1N4148 diodes for the keyboard matrix. The SK6812 "MINI-E" RGB LEDs are also surface mount. Use some reverse action tweezers on the SMD components and you should be fine. It also has a lil' 2-pin 6mm x 3mm reset switch to make flashing new firmware easier. Outside of that, there's just the microcontroller stack. The RevXL takes advantage of an RP2040 in an Arduino "Pro Micro" form factor. Stacked on top is a typical 128x32 pixel SSD1306 OLED screen.

The RP2040 is the microcontroller featured in the Raspberry Pi Pico. It's designed to be a modern low cost alternative to the aging Arduino's AVR platform. The Pico is a relatively large micro controller, so the DIY community has standardized on  repackaging the RP2040 in the old faithful Arduino Pro Micro form factor. The Pro Micro is about the size of two square keycaps, so it's a nice fit for mechanical keyboard builds. The RP2040 variant takes after the Elite-C microcontroller and includes a few extra pins. The extra pins make wiring up the optional components a bit easier, but we're actually here for the 16mb of onboard memory. QMK's firmware starts hitting the Arduino's memory ceiling when you add a few different RGB programs, so the RP2040 gives is a nice overhead to play around with its fancier functionalities.

When working with a microcontroller, it's a good idea to "socket" it. Rather than soldering the microcontroller directly onto the PCB, you solder some header sockets onto the PCB, and then some header pins onto the microcontroller itself. It allows you to more easily replace the microcontroller if something goes wrong.

The mechanical keyboard community commonly likes working with "machine pin headers". These sockets are unusually low profile, but I've personally never had any luck working with them. The small pins you solder onto the microcontroller have always been a little fragile for my liking. I decided to stick with standard "DuPont" header pins this time around, but I at least found a set on Aliexpress that's only 3.5mm tall.

Originally I soldered the header pins onto the microcontroller with the small black plastic protector on the bottom of the microcontroller. It made the RP2040 a little taller than usual, but it was still shorter than a Choc switch with a keycap.

Unfortunately it turns out that I had positioned the microcontroller a bit too close to the 3 key. Depending on the size of the USB-C cable you use, it can brush up against the key switch and stop it from pressing smoothly.

So I ended up going back to a modified machine pin header approach using the standard square pins. First I used pliers to pop off all of the pins from a set of headers.

Then I laid a row of temperature-resistant Kapton tape on top of the soldered headers. It's pretty easy to poke the individual headers through the tape. You may need to rotate them a bit since they're square shaped.

Finally you can carefully lay your RP2040 on top. (The second time I did this I realized it was easier to lay the RP2040 down first and feed the pins through it.) Now you can solder the headers into place. The Kapton tape stops you from accidentally having solder drip down and permanently fuse your microcontroller to the headers. The end result is a slightly shorter Pro Micro. You'll need to trim the excess pins off the top of the microcontroller with some angle cutters. (Scissors that cut a bit more flush than your standard pair.)

The OLED screen needs to be a bit taller than the Pro Micro, so you can use the same 3.5mm headers while keeping the plastic piece in place. You'll want to solder the OLED screen's pins in place slotted into the keyboard's actual OLED header using the Kapton trick again. It barely fits over the RP2040, and there's a chance it could be angled awkwardly in the air if you soldered it on a breadboard.

The Case

The RevXL uses a "tray" style 3D printed case with heat set inserts. It's exactly the same design featured in my Ergogen tutorial. The parametric nature of Ergogen allowed me to copy the case code over, adjust a few variables, and pop out a finished case design with very few adjustments. Score one for reusable code!

Due to how wide this particular keyboard is, the case doesn't fit on my 3D printer as a single piece. It's been split down the middle to allow it to be printed as two parts. Hence some of the interior mounting holes on the PCB. I also used the same heat set insert trick with the screws holes as discussed in the tutorial.

The Firmware

The short version of this section is that the RevXL uses the Vial fork of the QMK open source keyboard firmware project. I've previously worked primarily with the ZMK wireless keyboard firmware, but it doesn't have as robust as support as QMK for per-key RGB lighting. Vial meanwhile is an open source fork of QMK inspired by the Via project. It adds support for using a GUI on your computer to update your keyboard's keymap and settings in real time without the need to re-flash your computer.

The long version of this section is: What the heck happened to QMK?

QMK is the grandfather of modern open source keyboard firmwares. It's the longest running project with support for a dazzling amount of hardware features. While there are newer projects like ZMK targeting wireless keyboards and FAK targeting keyboards based off the CH55X chip, QMK's still the gold standard when it comes to working with wired keyboards. It's the software that companies like Keychron and Drop target when they want to try and sway mechanical keyboard folks from going the DIY route.

Working with QMK has always been a little cumbersome for reasons that are largely not their fault. The project originally targeted some of the earliest Arduino hardware. The AVR platform runs on low-level C code, and there's only so many layers of GUI niceties you can put on top of the flashing process. Once you get your head around it though, the project's not that hard to work with.

To define a matrix, you pull up the Config Options documentation, hop into config.h and set:

#define MATRIX_ROW_PINS { GP29, GP28, GP27, GP26, GP22, GP21, GP16, GP15, GP14, GP13 }
#define MATRIX_COL_PINS { GP10, GP0, GP1, GP4, GP5, GP6, GP9, GP12 }

Then you just browse over keymap.c and put the right keycodes into an array. Toss together some ASCII art of your layout in the comments and you're off to the races, right?

Well... not quite.

It's been about three years since I've used QMK. In the intervening time, the project realized that managing keyboard firmware C files written with a variety of community conventions was becoming unwieldy. They decided to move most functionality (but not all) into more structured .json files.

Well alright then. Let's pull up the info.json Reference, create an info.json file, and set out matrix definition there.

{
	[...]
    "matrix_pins": {,
        "rows": ["GP29", "GP28", "GP27", "GP26", "GP22", "GP21", "GP16", "GP15", "GP14", "GP13"],
        "cols": ["GP10", "GP0", "GP1", "GP4", "GP5", "GP6", "GP9", "GP12"]
    },
    [...]
}

Cool, everything's hunky dory now, right? Nope! QMK decided that info.json should describe common aspects of a family of keyboards. What you really need is a device specific keyboard.json file. It's a superset of info.json with a few more hardware fields.

The background and purpose of this keyboard.json file is mentioned in the 2024 May 26 Changelog, and it is referenced on the Porting Keyboards page.

That's it.

The Porting Keyboards page tells you to go to the Device Driven Configuration page for more details. This page does not mention keyboard.json once. It outlines the background of info.json and links to the info.json Reference, but it's not immediately clear what this file's relationship is to keyboard.json. I guess you're supposed to know that "There are a lot of options that can be placed in that file, too many to list here" is supposed to mean, "keyboard.json files can use info.json properties."

I know I've moved onto full on kvetching at this point. Managing open source projects the size of QMK is a difficult prospect. Writing thorough and understandable documentation is a skill unto itself. QMK's not only having to deal with keyboard designers like myself, but also beginner users who have bought a prebuilt QMK keyboard and just need assistance walking through updating their keymap. I'm fine dealing with spotty documentation if there's enough information available to get to your goals. Ergogen v4 for example still has some incomplete docs.

As it exists now however, QMK's documentation is a land mine field of outdated information. The Basic QMK Structure page is missing files. The Understanding QMK page had a guide on how to define non-standard matrix structures, something I desperately needed for my build, but it will throw depreciation errors if you actually try and implement its suggestions in your keyboard today. If you'd like to implement a rotary encoder and navigate to the Encoders page, you have made a mistake. The actual modern documentation is on the info.json Reference. Just be warned that the documentation fails to mention that the configuration won't do anything unless you add "encoder": true to the "features": section.

As a relative outsider to the QMK scene, wrapping your head around the project as it currently exists is a bit of a mess. Maybe I missed some obvious resource or example repo and this is mostly on me? I just feel like I suddenly understand why the ZMK team is working on improving their wired keyboard support. Googling for QMK answers is unfortunately also a risky proposition given the age of the project. I don't know if bumping things up to a full new "QMK 2" name would have made any of this more clear, but make sure any post you're referencing is relatively recent. Your best bet is to find a recent configuration of a keyboard with similar features to yours and copy that.

Once my QMK configuration was finally up and running, adding Vial support was nice and straightforward. Their site had step by step documentation, and they walk you through the most commonly requested features like rotary encoder and LED support. It is a bit humorous to have to build your keyboard layout out in Keyboard-Layout-Editor.com after having initially designed it in Ergogen, but the process is nice and straightforward.

Once you get Vial up and running, you can use their GUI as either an offline application or a Chrome web app to re-map your keyboard's layout on the fly. It's a nice way of letting beginners dabble with QMK, and it exposes a lot of features you might not even realize are there. If I work with QMK again, I'll definitely be taking the time to add Vial support as well.

Build of Materials

Conclusion

This was an incredibly satisfying keyboard build. Despite working with RGB LEDs and the RP2040 for the first time, I managed to design the PCB without any routing issues on my first try. (Something I've not always been lucky within the past.) I'm overall really happy how this project came together. If I had to make some adjustments for a v2 design, I would give the microcontroller a bit more space, and maybe consider adding a few more switch footprints to the arrow cluster. A few kind folks pointed out that if I fill in the 5 gaps in the current design, you would have the option of including a small numpad area in addition to an arrow cluster.

I was going to end this post with a joke about how I'd post my husband's impressions as soon as he finished learning how to type on a Choc-spaced column-staggered keyboard. He's actually taken to the RevXL like a fish to water. The cozier Choc spacing takes a bit of time to get used to, but he's already been toying with lighting patterns and updating the keymaps. Mission accomplished.

This is a 65% keyboard with the heart of a 40% keyboard. Nothing here is standard. It's not ergonomic. I have to be breaking some sort of keyboard law here. Welcome to the 65 Crimes.

The 65 Crimes is my take on a small row-staggered keyboard design. I've been getting into retro computing a bit more lately, and I wanted a non-ergonomic non-split keyboard design that didn't rely on a ton of layers. The 65 Crimes can play TiE-Fighter with the F1-F12 keys being the only thing you need to hold Fn down for. I still wanted the keyboard to be compact and tweet however, so there's a few odd quirks going on here. The left row has been shaved down by half a key width. Tab, Caps Lock, and Left Shift all get downgraded from 1.5u to 1u, 1.75u to 1.25u, and 2.25u to 1.75u. Much more striking however is the number row. Rather than sticking with the popular compact 65% keyboard block design, I gave the number row a bit of breathing room. It's spaced out similar to a traditional function row. It makes it a little odd to type on, but the end result is a 65% keyboard that looks like a 75% keyboard at first glance.

I tackled a few personal firsts on this keyboard design. It's my first row-staggered keyboard, my first keyboard with spacebar stabilizers, my first keyboard with an onboard microcontroller, and my first time working with the FAK keyboard firmware. Everything worked out in the end, but there were a lot of layered learning experiences here.

The Ergogen Layout

This one's going to take some explaining.

Ergogen is a keyboard layout generator designed to make ergonomic keyboards. It's right there in the name! It's designed to make "column staggered" keyboards where all of the keys in a column (QAZ, WSX, etc.) are aligned together. This is a traditional "row staggered" keyboard. It's ostensibly less ergonomic. It's also something Ergogen is really not designed for.

To design the 65 Crimes keyboard I decided to get a little creative. The Ergogen config file for this board literally turns it on its head. Everything is rotated 90 degrees so that it just looks like an excessively tall column staggered keyboard. Rather than a 15 column, 5 row keyboard, Ergogen thinks it's designing a 5 column, 15 row keyboard.

The approach takes a bit to wrap your head around. X becomes Y, length becomes width, and straightforward becomes tedious. This is definitely a case of, "When you have a hammer, everything looks like a nail". If you're familiar with Ergogen then this approach is still probably faster than learning another tool. If you're looking to learn Ergogen to make a row-staggered keyboard however, you're probably better off looking at some of the other tools out there. There are also some Ergogen keyboards examples out there which manage a row-staggered layout without this rotation approach. This is just what happened to work for me.

Update: After experimenting a bit more, the "Rotate everything by 90 degreess" method is probably a bit more trouble than it's worth. I've made a few example row staggered Ergogen configs in this pain-rectangles repo. You make every row into a dedicated point zone so the columns don't inherit the various shifts and adjustments. The catch is you'll need to be a lot more explicit when it comes to defining your nets.

The PCB

At its core, the 65 Crimes keyboard was an excuse to learn more about building keyboards with built in microcontrollers. The Arduino Pro Micro, RP2040, Nice!Nano, and XIAO boards are great, but it's hard to beat some of the minimalist designs you can build when you're not trying to hide a large postage stamp sized microcontroller somewhere. I briefly explored some of the options out there for built in microcontrollers, but they all seemed to have a level of complexity I wasn't ready to dive into. I got fairly far along looking at STM32-based designs, but the programming headers just seemed like a headache I didn't want to deal with.

Enter the CH55X line of chips. These budget microcontrollers became popular during the Covid era chip storage. They're not going to win any performance contests, but they're cheap, easy to source, and have onboard USB support. The later is naturally beneficial for keyboard builders, but there's a few other nice touches here. CH55X chips have fairly simple circuit designs. You only need two resistors, two capacitors, two buttons, an ESD protection chip, and a USB port to get these chips up and running. These chips are also completely hand-solderable if you'd like to skip an expensive PCBA assembly step. Even the basic flashing is nice and straightforward. The same USB port you use for connecting to the keyboard is used for flashing the firmware. (Similar to an Arduino Pro Micro.) Instead of tapping the reset button twice, you simply need to add and hold down a dedicated "Boot" button.

The majority of keyboards with CH55X chips are using the smaller CH552T chip. It has a nice hand-solderable 0.65mm pitch chip package. Unfortunately, it doesn't have enough pins for the 65 Crimes large 67 key layout. Thankfully the CH559L has more than enough pins for this design. Things get a little trickier on the hand soldering front however. The CH559L has a tighter 0.5mm pitch. It's nothing a little flux can't deal with, but you may want to buy a few spares if this is your first time working with SMD soldering.

Again, this is my first time working with an onboard microcontroller or the CH55X family of chips. All of the pinouts and component choices are shamelessly copied from semickolon's Partycrasher Micro microcontroller design.

The Firmware

One slight catch with the CH55X chips is that they can't run most of the popular keyboard firmwares. QMK and ZMK won't run on this particular microcontroller. Instead, the 65 Crimes leverages the relatively new FAK keyboard firmware.

I didn't dive deep into its capabilities, but my first impression of FAK has been great. It's a declarative keyboard firmware that should be familiar for anyone who's worked with ZMK. It's nice having a purely functional firmware which throws errors at compile time if you've accidentally made an issue with your keyboard config.

FAK can be built locally on your computer, but they also offer a preconfigured Github Codespace as a build environment. It makes things nice and simple to get your first firmware up and running. The only package you need to run locally is the flashing utility wchisp, which offers precompiled binaries for Windows, Mac, and Linux.

The keymap for 65 Crimes can be found in this repository's /fak-config folder. I haven't used any FAK features other than layers to enable a basic Fn key. For more advanced ergo keyboards however, FAK supports all the usual macros, combos, encoders, split keyboards, mouse keys, sticky layers, and tap dancing you're accustomed to. Their Discord was incredibly welcoming and patient with all my questions.

The Switch Plates

The 65 Crimes keyboard is also the first time I've designed a keyboard layout that uses stabilizers. These are those small metal bars which help wide keys press down evenly without any wobble. They're ubiquitous in the world of row staggered MX keyboards, but a bit less common in the Choc space.

Choc stabilizers require a switch plate. The plastic anchors need to be sandwiched between two layers of PCB (or other stiff material) to seat correctly. Thankfully Ergogen makes it pretty straightforward to make a switch plate. Fire up your PCB's outline, cut out a 14mm hole on each switch, add the stabilizer cutouts, drop in some mounting holes, and bam you're done. Unfortunately the 65 Crimes is a somewhat large keybaord by split ergonomic standards. JLCPCB wanted another $15 USD for the full switch plate.

I experimented with making a cheaper stabilizer "shim". This was a smaller piece of PCB material that only covered the spacebar keys and the left and right modifiers next to them. The idea was that you could print off this smaller piece and save a few bucks during your prototyping.

The actual stabilizer footprints come from a design put together by FKCaps. The cutout isn't symmetrical with the key switch and is aligned closer to the top edge. This resulted in the shim having a relatively thin piece of PCB material. JLCPCB wanted an extra $7 USD to make sure the hole was routed properly. Rather than iterating on this design further, I went ahead and just printed out the full switch plate. The switch plate worked great the first time thankfully, but I'm leaving the shim designs in here for anyone who's interested.

For this particular build I went with Chosfox's CFX WoB Keycap Set. I wanted a keycap set with legends, and this layout used a few odd sized 1.25u and 1.75u keycaps for the modifiers, tab, and enter key. This left Chosfox as pretty much the only game in town. The keycap set is split into an Alpha, Ergo, and Extras kit. I was barely able to squeak by with just the Alpha and Ergo kits.

The Ergo CFX kit comes with two 2u spacebar keys. It also comes with a 2u key labeled "Shift". There are also two bright orange 3u spacebar keys. I asked around online and didn't get many strong opinions when it came to using three 2u spacebars or two 3u spacebars.

My final design went with three 2u spacebars. This mostly came down to parts sourcing. It turns out the 3u Choc stabilizers are really hard to source right now. I ended up getting five 2u Choc stabilizers from LowProKB.ca for about $5 USD plus $7 USD shipping. I could have purchased 3u stabilizer wires from CannonKeys for $4 USD plus $4 USD shipping if I really wanted to use the larger 3u CFX keycaps. Instead, I just ended up purchasing three MBK 2u convex spacebars from LowProKB for an extra $3 USD. It sounds a little silly to say I went with three 2u spacebars to save $5 USD, but I already happened to have a matching purple Esc key from an earlier FK Custom order.

It's worth noting that these Chosfox keycaps use their "CFX" spacing only on their 1u keycaps. These CFX keycaps have become popular for minimally spaced keyboards. Standard MBK keycaps are 18mm x 17mm, while the CFX keycaps are a square 17mm x 17mm. That's a free 14mm of saved width on a keyboard like this. Unfortunately the other 1.25u, 1.5u, 1.75u, and 2u keycaps stick to their standard MBK spacing. (That is to say the 1.5u keycap is 18mm * 1.5 = 27mm wide.) For that reason this keyboard sticks to standard Choc spacing.

The footprints folder contains several custom footprints. Getting the spacing right on this was tricky, so I created a full line of choc-Xu footprints to show their exact spacing on the PCB. The choc-stab-2u and choc-stab-2u-cutout footprints are based on footprint designs by FKCaps.

The Case

After all the other experimentation with this keyboard, I stuck with what has worked for me in the past with the 65 Crimes case design. It uses my standard "Tray" design. The PCB and switch plate have mounting holes, and the case has standoff legs with heat set inserts. The only thing I did different this time was splitting the case in half to fit on my printer, and making the sides of the case a bit taller on the top and sides for aesthetic purposes. I also decided to fire up Cura's "Fuzzy Skin" setting.

The Build (and Lessons Learned)

No long build guide this time unfortunately. There were a few false starts and fiddling with this keyboard, so I don't have step-by-step pictures to share. Overall the build went smoothly. The CH559L was the trickiest piece to solder. You need to line it up precisely, apply a bit of solder flux to one side, then quickly apply a bit of solder while the chip is still aligned. Once one of the legs is soldered properly, you can drag-solder the rest as you would with any other SMD component. The same approach goes for the USB-C port. The ESD protection chip, two capacitors, and two resistors should be a bit more straightforward.

This wasn't my first rodeo when it came to working with SMD parts. Thankfully the TypePak has similar sized components with just as tiny pitches. One slightly embarrassing learning experience was to not trust the orientation of text on SMD packages. I totally fried some of the ESD and CH559L chips by having things oriented the wrong way.

The "rotate everything 90 degrees in Ergogen" trick also nearly came back to bite me. It turns out swapping the col and row pinout definitions wasn't enough to compensate for its rotated definition. All of the diodes on this keyboard are technically "backwards" from how I typically build them. Thankfully it didn't lead to anything more complicated than needing to swap the "ColToRow" variable in the FAK firmware to "RowToCol".

Overall the 65 Crimes was a great learning experience. Row staggering with Choc spacing has taken me a bit more getting used to than I expected. The function row styled number keys have been a fun novelty, but they're a little tricky to use in practice. The keys one would use from gaming on the left side of the keyboard aren't too hard to build some muscle memory for, but I almost always tap the wrong number when dealing with 7, 8, or 9. I've still got a few CH559L chips I managed not to try, so I'm looking forward to doing a bit more experimenting with FAK in the future!

Build of Materials

There’s a new web search in town. No, it’s not a re-skin of Bing results. No, it’s not an AI powered tool chasing this particular moment of Large Language Model (LLM) hype. Kagi is an honest to goodness general purpose search engine with a simple proposal:

Pay us $10 USD a month and we’ll provide you with good search results.

A few of you just got very excited, and some others just closed this tab. Kagi is a very unusual product in 2024. The tool isn’t without its quirks, but it’s the sort of service you can easily write a few thousand words discussing. If you’re interested in technology and the web, it’s worth signing up and kicking their tires.

Kagi’s been building buzz for the last year, but I’d been dragging my heels on making the switch. It turns out the way to keep New Year’s tech resolutions is to replace your app defaults. Here’s my assorted thoughts after a January, February, and March without Google and Safari.

Paying For Search

It’s hard not to talk about the state of the web as a whole when discussing search engines. The internet’s having a bit of a moment. Longstanding websites like Twitter and Reddit are making antagonistic moves against their user bases. Google and Amazon are dealing with a floor of affiliate links and search engine optimized sludge. Looming on the horizon, LLM outputs threatens to swallow the web whole.

Out of all of this comes Kagi. On the face of it, they’re yet another subscription looking to monetize some small silver of your daily life. If you take a step back however, some interesting things happen when you pay for search.

Kagi describes themselves as “user-centric search”. You’re paying them directly for the service they’re rendering. This has two significant and immediate effects: Kagi doesn’t need to show you ads, and their search has to be good.

Not having ads always makes for an enjoyable browsing experience. As cable TV has proven time and time again, paid services and advertising aren’t completely incompatible which one another. For the time being however Kagi is happy to be one of the increasingly few internet oases that isn’t actively trying to sell you something every time you interact with it.

This has substantial benefits on the privacy side of things. Since you’re the customer and not the product, Kagi doesn’t need to integrate extensive surveillance and tracking technologies into their tool. They don't log searches, associate searches with your accounts, and they even spell out, in plain English, the intent of the 5 cookies they use.

The privacy angle is nice, but Duck Duck Go has also been around for a bit. They offer an anonymized ad-supported privacy-focused search. Building a successful web service at scale purely off of ad revenue has become increasingly tricky however, so Duck Duck Go’s search results are largely a proxy for Microsoft’s middling Bing search. (Sorry Bing.)

The exciting thing about Kagi is that you’re paying them for search. If it’s not good, no one’s going to subscribe for a second month. The company actively pitches the aligned incentives that come from being an ad-free, paid search tool. They get their money from building a good search engine. They don’t benefit from driving traffic to sponsored links, affiliate vendors, or vertically integrated products. Kagi’s search is pretty good as a result.

Kagi Search

It’s tricky to objectively judge something like the quality of search results. (Although there are some good attempts to do so.) When search results are good, you hardly notice them. When they’re off, it’s immediate and apparent. Not to harp on Bing again, but everyone’s had that experience of searching on a new work computer or public terminal and struggling to find what they’re looking for before realizing they’re not using Google.

Web search quality is vibes based. And the vibes are off. People have been whinging for a while now about whether or not Google Search results are getting worse. While drafting this blog post, Google themselves admitted they need to make some significant changes to their search results to filter out AI generated spam and SEO reputation laundering.

All of this is to say that I’ve been satisfied with the search results Kagi provides. They “pass the vibe check” so to speak. While testing Kagi I rarely (if ever) experienced that mental whiplash of viewing “off” search results only to realize I’m “that other search engine”. Kagi’s search is good. It’s not a party trick. It’s not situational. It’s good search. You should give it a try.

When searching for a question online, Kagi does a good job of surfacing results from human-centric discussion sites like Reddit or Stack Overflow. When searching for cooking recipes, I notice a slightly more diverse set of food blogs then with Google Search. Comparison shopping or searching for information about a mainstream product does seem to fall down some of the same SEO pitfalls that Google has. This feels more like an artifact of the current state of the web then a particular search engine deficiency however.

The actual browsing experience with Kagi is pleasant. It sticks with the established Google-style search results page. It delivers links with blurbs, sub-links, and embedded rich content. If you search for something with significant video or image results, Kagi has a familiar strip of thumbnails inviting you to pivot over to one of those dedicated search views. It’s a very familiar search experience you can transition into easily. Kagi’s focus is on the search engine itself, and they’re not trying to be cute with unusual user interface innovations.

That’s not to say Kagi doesn’t have some unique touches of its own however. Once you’ve gotten familiar with the initial search experience, there’s a lot of additional functionality you can start taking advantage of within Kagi.

On the search side, Kagi lets you adjust the ranking of pages within your personal search results. If your recipe searches are anything like mine, that might involve bumping up SeriousEats.com links. If you’ve been burned by one too many AllRecipes.com recipes, you can even go as far as hiding all pages in that domain from your search results.

If you’re a web search power user, Kagi’s Lens functionality may be of particular note to you. If you find yourself frequently searching for programming support for example, you can narrow down Kagi’s view of the web to just the handful of official documentation sites and support forums for the language you’re working with. It’s a bit of a brute force approach to cutting out blog spam, but you were probably scrolling down to the StackOverflow.com or Dev.to links anyways, right? This tool’s a bit more situational, but it’s nice seeing some thought put into how to push the search experience forward.

There’s just something comforting about using opinionated software that doesn't feel like it has gone through eight code reviews and six departmental presentations. Kagi’s clearly built by a team who cares about search. When searching for an image, Kagi provides you with links to go to the page the image is on and a direct link to the image itself. No more having to right click and fiddling around for the “Open Image In New Tab” option! Fancy that. These nice touches range from quick shortcuts all the way to letting users upload a custom CSS user theme for the site.

If you’re hesitant to make the full time switch to Kagi, the “Bang” functionality they borrowed from Duck Duck Go is of particular note. If you prefix a search with !g, Kagi will instead forward that search query over to Google. !r sends you to Reddit’s internal search instead. !yt is a direct link to YouTube search, etc. Duck Duck Go has cataloged thousands of these integrations.

I didn’t find myself needing a Google escape hatch that often. When I did, it was mostly when searching for local businesses. Kagi has integration with Apple Maps and Yelp for finding nearby restaurants, but Google Maps remain notably strong in that one area. I use the !g shortcut maybe once a week on the unlimited plan, but they’re instrumental when working with Kagi’s lower priced tiers. Speaking of which;

Don’t Bother With Kagi’s $5/Month Search Tier

Kagi’s updated their pricing a few times throughout the life of the product, so go check and make sure this section is still relevant. Their initial offerings were focused on providing a few different metered tiers. Deciding between 300, 500, and 700 search queries a month harkened back to the days of paying for individual SMS messages. And not in a good way.

Luckily Kagi’s prices have been coming down. They now offer two main tiers: $5 USD per month for 300 searches, and $10 USD per month for unlimited searches. (There’s also a $25 USD per month tier with early access to upcoming features for super-fans.) Kagi will give you 100 free searches when you sign up that are time unconstrained. If you’re interested in seeing just a few sample search queries, feel free to open a new tab and run some test searches now. You don’t need to set aside a week to give the tool a proper test the moment you sign up.

Ten dollars per month is a lot to ask for search when an several ad-supported alternative exists. The five dollar tier sounds like a good compromise on paper, but I found it not worth the effort after having used it throughout January.

It’s hard to overstate just how often technology-minded folks search throughout the day. I apparently do about 45 Kagi searches a day on average. In reality this shakes out to about 30 searches on a weekday, and 60 searches on the weekend when I’m deep diving into side projects. This doesn’t include the Google searches I still perform during the day on my work computer. Just to drive this point home, I managed to perform over 600 searches on an unlimited plan during the month of March while out of the country and completely disconnected from the internet for a week.

Limiting myself to ten high quality Kagi searches a day in January actually wasn’t too difficult. The !g Google shortcut doesn’t count against your Kagi search total. However, there’s a lot of mental overhead in deciding which search engine to use. Looking for programming help? That’s a job for Kagi. Just looking for Local Pizza Brewpub Menu? That’s a job for Google.

You can technically get through a month on the $5 plan. I ran out of searches a day and a half before next month’s auto-renewed batch of 300 searches. (Kagi doesn’t start billing you per-search. You just get an upsell notice and an option to go back to Google or Bing.) The 300 search plan unfortunately just isn’t a very pleasant experience. I’d find myself wincing any time I accidentally typed a query I already knew the result of  like Serious Eats Channa Masala into Kagi’s search during my metered month.

If you want to experiment with Kagi after your 100 free searches, do yourself a favor and jump straight into the $10 USD per month plan. You’ll get a better feel for Kagi’s search results by the end of your experimentation month if you’re not frequently trying to remember to use the !g shortcut for menial searches throughout the day.

That’s my big takeaway for this blog post. Hopefully Kagi’s prices continue to come down to the point where they don’t need to offer a metered plan period. This critique may not be accurate anymore by the time you read it. If your spouse is also into tech, the cost may work out a bit better for you on their $14 USD per month two seat “Duo” plan.

Kagi & AI

Kagi has been exploring the Large Language Model and AI tools space along with most of Silicon Valley. Their core offering is a model known as FastGPT. It’s a ChatGPT 3.5-style LLM with the ability to perform web searches. The answers it provides are citation-heavy, similar to Microsoft’s Bing Chat / Copilot.

FastGPT is available as a standard interactive chat experience, but Kagi also exposes it a few other ways. They have a “Summarizer” web app which takes web page URLs and can provide short summaries or a bullet point list of key moments. The Summerizer tool also provides a conversational interface to further interrogate the context of a particular web page.

Finally, Kagi’s most prominent FastGPT integration is its “Quick Answers” functionality. At the top of every search result page is a “Quick Answers” button you can tap to get a brief 2-3 sentence answer to your query. The response appears inline in a new panel at the top of the search results page. As its name implies, FastGPT is designed to begin typing its response nearly instantaneously.

Quick Answers is a nice way to begin dabbling in large language models. You don’t need to remember, “Oh right, I can have a conversation with a chatbot about this question.” It’s just always right there at the top of the page if your query seems like one of those things that should be trivial for “the internet” to answer. Kagi will also save you the tap and automatically generate a Quick Answer response for some queries that it detects are in the form of a question.

Overall FastGPT responds about as well as other consumer LLMs. It does unfortunately produce occasional hallucinations depending on the query. Kagi as a company has a history with AI technology, so these experiments most likely will not be flashes in the pan. Overall the company seems to be taking a balanced approach when using these tools to help users search and interrogate documents further, rather than just using them as search engine replacements. These LLM experiments aren’t as core to the product as, say, the Arc browser or Brave Search. All of the AI functionality can be disabled if you don’t want to use LLM-based tools. An unlimited number of interactions are included with Kagi’s $10 USD per month unlimited search plan, so you can think of it as a bonus functionality if you’re still in the experimental phase with AI tools and don’t want to spring for an OpenAI or Microsoft Copilot premium offering.

The Orion Browser

Speaking of browsers, Kagi has one! Wait wait, don’t close the tab yet! Orion’s not Chromium based!

All kidding aside, there’s been a trend as of late of companies announcing a “new” browser which is essentially a re-skin of Google Chrome leveraging the same underlying Chromium rendering engine. They’ll sometimes have new functionality which couldn’t fit within the framework of a traditional browser extension, or some novel UI layer justifying the separate product. The core experience is largely still dictated by Chromium’s foundation however.

The consolidation of rendering technologies and the risk browser monopolies propose to the open web is a bit outside of the scope of this blog post. Rest assured though, Orion’s not Chromium based.

It’s Webkit based!

Orion uses the same rendering engine Apple uses for its Safari web browser. (Incidentally, Orion is only available on macOS and iOS.) Webkit was the basis for Chromium, so this may be splitting hairs a bit. They’re important hairs though.

For those not familiar with the current state of the browser scene on macOS, there's generally two paths you can take. You can go with Apple's relatively basic but power efficient Safari web browser, or you can use a more feature rich but battery hungry web browser like Google's Chrome or Mozilla's Firefox. (This isn’t a perfect characterization in all contexts, but it’s a good enough rubric.) I was personally a happy Safari user, but Chrome is useful for a few resource intensive web applications like Google Docs or browser-based video conferencing.

One of Chrome’s largest selling points over Safari is its extensive 3rd party extension support. Safari technically has 3rd party extensions as well, but they’ve never quite caught on as much as the Chrome or Firefox ecosystems. Safari’s APIs aren’t as robust, and unlike its open source peers you need a paid Apple developer account to publish Safari extensions.

Put simply, Orion is Safari’s browser technology with Chrome and Firefox’s extension support grafted onto it. That’s not a metaphor. Orion’s developers have added support for approximately 70% of the WebExtensions API onto Orion. The end result is that you can use Chrome or Firefox's UBlock Origin, Bitwarden, and LastPass extensions on a Webkit-based browser. It's an impressive technical feat and it works surprisingly well.

The rest of Orion is largely what you’d expect. There’s a few UI flourishes such as the option for vertical tabs, but they’ve largely stuck with what worked in Safari. It’s a fast snappy browser that’s not going to drain your battery life. It has all the usual password management, tab syncing, focus reading modes, and other modern touches you’d expect.

Speaking of syncing, Orion also has a mobile version for iOS. Its development started after the macOS version, and it can occasionally feel like it had less time in the oven so to speak. (It’s the only app in recent memory I’ve had actually crash the iOS Springboard.) It’s still probably the best Safari alternative I’ve tried on iOS... but Safari on iOS is the platonic ideal of mobile web browsing. Any rough edges are going to stick out like a sore thumb.

The biggest benefit of using both the macOS and iOS versions of Orion is tab syncing and Apple’s Continuity functionality. Using only the desktop app can feel a bit disjointed when suddenly your phone’s trying to open Hand Off links in Safari. Dealing with the occasional rough edge on your phone helps keep the overall experience a bit more seamless. That alone may be a hard sell, but there’s one other piece of functionality both the desktop and mobile apps have which may keep you around.

Despite supporting the well regarded UBlock Origin, Orion also has ad blocking built in by default. This is mostly pitched from a privacy and performance perspective. Browser ads do have a measurable impact on battery life while on the go, and there are an absurd amount of advertisers looking to track you around the web.

Online advertising pays for the news sites you read, the social media you browse, and the videos you watch. Still, they’re obtrusive and dangerous enough that even the US’s FBI is recommending ad blockers for your own safety. If you’re part of the one third of all web citizens who use an ad blocker, Orion’s got you covered out of the box. It’s just a little odd to see a company openly brag about blocking YouTube ads and supporting Picture-In-Picture and background audio without a YouTube Red subscription.

Interestingly for a modern browser, Orion isn’t open source. This logistically makes sense given the size of the development team. There are still ways of checking some of their privacy-oriented claims (a packet sniffer can verify that it’s zero telemetry for example), but it’s worth pointing out given their otherwise privacy-focused posture. Safari isn’t fully open source either, so that may not be a sticking point for most macOS and iOS users.

Kagi & Other Browsers

If you decide to skip Orion, you can still use Kagi as your default search engine in other browsers. In most cases, you just need to dig into the search preferences and set https://kagi.com/search?q=%s as your default search provider. Chrome or Firefox will insert your query in the place of the %s when you enter search terms into your address bar and you’ll be all set from there.

Frustratingly, Apple didn’t get the memo on user-definable search providers. Safari is hardcoded to Google, Bing, Yahoo (Bing-powered), Duck Duck Go (powered by a variety of search sources including Bing), and Ecosia (a Bing-powered search that uses its ad revenue to plant trees). Hopefully Kagi will get added to Safari’s search engine list if it gets popular enough. Google's currently paying Apple $18 billion dollars to remain the default search engine in iOS, so we'll see what happens.

In the meantime, Kagi has a Safari browser extension for both the desktop and mobile clients which allow you to fake Kagi as your default search provider. The extension sees a search sent to one of the Safari default providers, parses the URL, grabs your search term, and then instantly redirects you to the Kagi search page for that term. In my limited testing it appears to perform the redirect imperceptibly fast. The extension doesn’t prevent you from visiting Google if you need to either. You can still use the !g override to get back to Google Search. If you do encounter flakey behavior, you can set the extension to only work on a specific search engine like Duck Duck Go or Ecosia if you run into trouble with accidental redirects. Apparently it was buggier in earlier versions, but it appears to have worked out the issues.

Doing The Mental Calculus

I’m not quite sure what to make of Kagi after my first three months with it. It’s really good search. Is it $10 USD monthly search? That’s the tougher question.

There’s some amount of mental calculus involved when deciding to make the switch to a paid service like Kagi. I’m not personally looking for a zero tracking search service or seeking to completely de-Google my life. I care about privacy, but I still own a smart speaker or two. I’ve got an iPhone, but Google still manages my email.

I’m on the fence about spending a bit more time with Kagi as my default search engine. The gaps in local search aren’t that egregious, but in its current state it still feels like a $50 USD per year indulgence rather than a $100 USD per year splurge. Maybe try to find a friend to go halfsies on with a Duo plan?

One last factor to consider is Kagi’s recent partnership with Brave Search for use of their search index. Brave is a relatively new browser company helmed by Mozilla’s ousted CEO Brendan Eich. Since his departure from Mozilla, Eich has continued to defend his homophobia, spread Covid misinformation, and generally introduced a slew of scammy crypto functionality within Brave.

After pushback from their userbase about this partnership, Kagi’s CEO responded that the company is not yet in a position to be able to take moral stands.

I understand that this has affected many of you in a negative way, creating a sense of betrayal that's against the very ethos of Kagi. I want to address this and be crystal-clear: any semblance of support for discrimination is completely against our principles. The rationale behind our choice was purely based on technological merits and business strategy, including the quality and cost-effectiveness of the service, as well as a critical need for redundancy and diversification in our data sources. The decision was treated the same as getting results from Google or Yandex (to which different groups of users in our userbase object to for various different reasons).

Kagi is currently not in the position to be fully independent. Searching the web is incredibly hard and Microsoft spent 20 years and billions of dollars building Bing, and it is still, let's say, suboptimal. Definitely not at the level people would pay for it. It is very hard for a small startup with many orders of magnitude less resources to crawl/index/rank the entire web and for it to be so good that people would pay for.

...

Choosing to focus on our mission to provide the best search results in the world is the only practical position we can have. This is not because we are ignorant to issues impacting societies across the globe, but because it is impractical for us to deal with them all. We cannot solve all of the world’s problems, human rights issues, conflicts and wars, but we have instead devoted our passion and energy to solving one problem that we believe is within our grasp, and that is the problem of web search, which is what Kagi is known and loved for. We intend to do that to the best of our ability.

Man, this sucks.

404 Media also recently reported on Kagi's stance when it comes to manually manipulating search results in their service. The hypothetical discussed in the Kagi forums was whether or not the search engine should present suicide hotline information when someone searches for self harm-related topics. The company pushed back on this proposal saying they do not have any "moral, political, religious, social or any similar kind of bias" they want to explicitly code into their algorithms.

Arguing that Kagi "does not have any implicit bias built by us that is not search quality based" is a remarkable comment to hear from a CEO in 2023. Particularly when the company is eager to explore the burgeoning AI space. Everyone brings their own biases to the table when building a product. The best anyone can do is be aware of their blindspots and be open and honest about where they're coming from.

Kagi as a company likes to discuss their moral stances when there's only an upside. They frequently advertise their aligned incentives, and they bragged about going "hard mode on" when searching for an ethical t-shirt vendor. When it comes to more nuanced or messy topics however, Kagi's default approach appears to be hoping that not engaging with a topic is the same as not having a stance on the topic. I can't see this position being tenable forever.

Closing Thoughts

I’ve been dragging my heels wrapping up this blog post. Originally this was supposed to be a two month evaluation of Kagi. I needed a bit more time to get screenshots for this blog post though, so I decided to give myself an extra month to gather my thoughts on the tool.

I continue to be impressed by the search experience on Kagi. The results are solid, and the search page is pleasant to browse. Throughout the month I kept stumbling on nice touches. I recently discovered a website I was searching for was down, only to be delighted to find an Archive.org link in the result’s kebab menu. These folks know how people interact with the web and want to make a great search experience.

The one thing I struggle with Kagi is to identify who its core user base is. For all the talk of Kagi’s aligned incentives with their customers, I can’t shake the feeling that I don’t know who they’re targeting. Duck Duck Go currently handles some amount of general privacy or Google-specific search concerns. So... Tech enthusiasts who would pay for a premium search experience, but aren’t turned off by LLM integrations? Orion is a privacy focused browser for people with strong opinions about Chrome’s Manifest v3 API transition who also don’t mind closed sourced tools?

There’s an unusual tension running throughout Kagi. They’ve had to hedge their bets throughout the development of the product. Maybe we’re just in a particularly compromising moment in tech. But that pragmatism can cut both ways.

After this three month experiment, I'm pausing my Kagi subscription. I might hang on to the Orion browser for a little bit longer. $10 USD is a lot to pay per month for search. That's more than the entry tier for most streaming services. I could see myself hopping back onboard once Kagi gets their prices down to $5 USD per month.

It'll be a pragmatic technology decision though. Tool X has a better experience than Tool Y justifying Z Cost.

Kagi is the type of service that would really benefit from a clearly defined user base who pays for the service not just because of the functionality of the tool, but because it's the type of search they'd like to see in the world. I'm a sucker for that type of narrative. I’m interested in any company that foregoes traditional venture capital funding and attempts to align their incentives with their customers. Kagi truly does appear to be trying their best, but I feel they've already had a few moments that peel back that early adoptor zeal.

Maybe it'll resonate more with you. Kagi's technology is good enough that it should be on your radar. So my final takeaway is: Try it! Kagi gives you a hundred free searches to kick its tires. See how things go. If you do want to give it a proper try after that, please just do yourself a favor and jump straight into the unlimited plan.

Huh. So it’s been an interesting few months.

Last Fall I published my writeup on the TypeBoy Keyboard & The TypePak Cartridge. It’s a split ergonomic keyboard with a twist: The keyboard’s microcontroller and battery are housed on a daughterboard built into a Game Boy Advance cartridge. It was a fun nostalgic indulgence, and I was happy to see it featured on the always delightful Keyboard Builder’s Digest. The next thing I knew, it was popping up on The Verge’s storystream and Ars Technica was reaching out for a comment. I’m still floored with all of the positive coverage and feedback.

Getting featured in two of my favorite tech blogs probably would have been the highlight of my 2023 had I not been getting married a few weeks later. Needless to say I’ve been a little busy.

But I’m back with a new keyboard design! It’s... very similar to my previous keyboard design. That’s right folks, I’ve achieved one of the elusive milestones of hobbyist electronics: I created a cost saving reusable design and actually reused it in a followup project.

Introducing the Mark II

The TypeBoy MkII is another TypePak-compatible 58-key split ergonomic keyboard. If you didn’t get a chance to read my initial writeup, the TypePak is a small cartridge containing all of the electronics needed to drive a mechanical keyboard. It houses a Bluetooth XIAO microcontroller, a LiPo battery, a shift register, and a Sharp Memory Display. (If you manage not to accidentally crack it while assembling things.) The TypePak allows you to quickly move a microcontroller between keyboards, but a large part of its appeal is just the aesthetics. The TypePak cartridge slot takes up a bit more space than a typical Pro Micro header stack, but it’s certainly a head turner.

While I was overall incredibly happy with how the initial TypeBoy design turned out, there were a few small issues that needed addressing. The largest impetus for making a new keyboard was a mistake in the routing of the original TypeBoy's power switch. The oversight left the right half permanently stuck in the "on" position. It worked fine in day to day usage, but I logged in on one too many Mondays to discover my keyboard’s battery had died over the weekend.

Rather than doing a straight revision on the initial design, the Mark II experiments in a few areas. The largest deviation from the original TypeBoy is the case design. The original TypeBoy used a 3D printed case loosely inspired by the GEIST Totem. It was fine, but my aging printer gave me a surprising amount of trouble for that build. A bit more tinkering probably would have solved the rough spots I was having with it, but I decided to try a different approach.

The TypeBoy MkII instead uses a take on the “PCB Sandwich” design. The keyboard’s switches, cartridge connector, and other hardware are all attached to the main PCB. If you’d like to make this keyboard, you technically only need to fabricate the main PCB. Underneath the main board however are 2mm worth of hotswap sockets and exposed key switch pins. It’s not strictly necessary to cover these up, but most people like having a flat protective bottom for their keyboard.

To protect the underside of the Mark II, I skipped my usual 3D printed route and instead had a pair of inert PCBs made to completely cover the bottom. They feature silkscreen line art inspired by the Game Boy and Game Boy Advance. They’re a little minimalist as far as PCB art goes, but it was something I didn’t have too much trouble whipping together in Figma in an afternoon. To keep the nostalgia trend going, they’re loosely based on the line art design of the original Japanese Game Boy box.

I could have stopped there, but this is a sandwich, right? I wanted to include a top piece as well. The TypeBoy Mark II is still using the bright red Choc Red Pro switches from my old ChonkV build, and I wanted something purple to cover them up.

Many traditional keyboard builds will use what’s known as a “Switch Plate”. This is a layer of the case which as a square cutout for every key that the switch is designed to snap into. It provides a lot of extra stability to keyboard builds using MX switches, but it’s less necessary for Choc switch keyboards. They rest fairly sturdily in their hotswap sockets already, and the switch plate only sits 0.5mm above the main PCB.

The TypeBoy Mk II eschews a full switch plate and instead just has a small PCB running around the border of the keys. This not only obscures the bright red housing of the switches, but it also covers the right angle power switch, reset button, and rotary encoder. It rests a full 4.5mm above the main PCB.

All three parts of this PCB sandwich are held together by a 12mm long M2 screw and matching nut. A set of spacers go between each layer to provide a bit more rigidity to the build.

As silly as it sounds, one of my priorities for the TypeBoy MkII was to make the cartridge slot more symmetrical. It was aligned nicely with the keys on the initial TypeBoy PCB, but I hadn’t considered how things would look once I added the case. The Mark II has a nice balanced design, in part to the keyboards new layout.

The original TypeBoy used a modified Sofle layout. I’m still a sucker for 58-key boards, and I was curious to try out a Choc-spaced Sofle configuration. Somehow the tweaked layout never fully clicked for me. I still use my original Sofle on a daily basis, and my hands just never managed to get used to the more compact layout on the TypeBoy. I did experiment with a bit of pinky splay on it, so maybe I’ll chalk it up to that.

In the end I decided to go back to a straitlaced ortholinear layout. I couldn’t resist adding a bit of row stagger to the modifiers, if only to make the spacebars frame the cartridges a bit more pleasantly. My thumbs still occasionally get confused between the layer key and the command key, but overall it’s been a much more pleasant typing experience. I’m certainly up for trying some gentle column stagger in the future, but for now I’m happy being one of those row and column aligned ortholinear weirdos.

Between the new case design and the updated layout, the TypeBoy MkII’s already checked one of my biggest boxes for this refresh. The ergonomically shaped plastic design of the initial keyboard was a little awkward to travel to and from the office with. This new PCB sandwich approach resulted in a keyboard that’s surprisingly solid. There’s very little flex or give to it, and it seems to do a better job handling a ride in my backpack.

The rest of the TypeBoy Mark II’s hardware is pretty straightforward. I’m still a  fan of right angle power switches and pushbuttons for these types of mechanical keyboards. Originally I had the reset button and power switch together on the top of the long edge of the keyboard. It wasn’t until about halfway through the routing of this board that I realized there was plenty of room for the power switch next to the cartridge on the short edge of the keyboard. The new placement really helps lean into the Game Boy vibes, and I’m glad I caught it before I sent this design off to the fab.

The final piece of hardware is the low profile rotary encoder. The SIQ-02FVS3 is back! I’m frankly a little obsessed with the idea of using a volume-style encoder wheel on keyboards. It’s always struck me as a little silly to put so much effort into having the lowest profile possible on a mechanical keyboard, only to add a knob that sticks out 5mm on top of everything else. The SIQ-02FVS3 even has a push button action like most knob-style rotary encoders!

Of course, if you read the original TypeBoy writeup, you know I have a love hate relationship with this particular encoder. Now seems as good a time as ever to get into the Mark II’s flaws.

Room for Improvement

I still can’t get the dang SIQ-02FVS3 encoder to work consistently! On the original TypeBoy I eventually gave up and tried using the SLLB510100 slide wheel. I had a few SIQ-02FVS3 wheels leftover after the build however, and some original TypeBoy PCBs with compatible footprints. After a bit of trial and error, I eventually managed to get one of the encoders working with the TypeBoy’s ZMK firmware.

The design of the rotary encoder is nice enough that I gave the SIQ-02FVS3 one more chance in the Mark II. The end result is that it works fine on the left half of the keyboard, but it refuses to send any signals on the right half. I’m pretty sure I have the right side / back half of the PCB routed correctly. The best I can tell, these parts just have a shockingly high failure rate. They’re unfortunately surface mount components, so the encoders are not exactly easy to breadboard and test before you solder them.

The one encoder I got working feels really nice to use. It’s poking out from the PCB a perfect amount, and it’s easy to just casually run your thumb across. Still, given my experience with this part on my last two builds, I may have to eventually give up my dream of using these little wheels for future keyboards. Hopefully I can find a similar part out there.

The last few goofs are thankfully smaller in nature. The TypeBoy Mk II has a very particular 150mm x 100mm shape. While I was considering updating the TypeBoy, the fine folks over at SplitKB.com started experimenting with the idea of offering a generic machine milled aluminum keyboard case with DIY Ergogen projects in mind. Typically premium keyboard cases are molded to fit a specific keyboard, but their upcoming Zenestra concept just provides you with a 150mm x 100mm blank slate to design around. The Zenestra’s rounded rectangle was a fun design constraint to work within, and my intention was to have the Mark II be compatible with it if the case does eventually go up for sale.

Unfortunately, somewhere in my design process I got some wires crossed and accidentally used M2 screw holes instead of M3 screw holes. This is fine for my current PCB sandwich TypeBoy Mark II build, but it does mean that I’ll need to run another revision whenever the Zenestra comes out if I decide to try out their case. Whoops.

My original plan in the meantime was to use some nice purple M3 washes in-between the PCB layers. I would have left the gaps of the keyboard exposed as an aesthetic choice. Unfortunately I honestly ended up scrambling to find some M2 screws of the proper size I could get shipped out quickly to wrap this project up. I ditched the washer idea and created a simple quick 3D printed insert for the two layers. It doesn’t have quite the same industrial look I had originally planned, but it did make the overall build a bit more sturdy. Every time I try to get out of 3D printing, they pull me back in.

The last flub’s a minor one. I swear I measured-twice and then measured-twice again before cutting fabricating these PCBs. Somehow the silkscreen for the Game Boy Advance inspired bottom piece has the button callouts place on the opposite side of the board. Arg! I also was experimenting for the fist time with specifying a placement of JLCPCB’s order number watermark and hiding the info off somewhere tasteful on the silkscreen. Unfortunately I forgot to check the box to actually enable that option on my order. Ah well.

If you're interested in creating your own TypeBoy Mk II, the M3 screw size and silkscreen issues have been updated in the GitHub repository.

Build of Materials

The triple-PCB setup was a bit of a splurge for this build. The shipping ramps up after the first PCB, so it's only about $20 USD if you want to skip the PCB sandwich. It seems silly to own two sets of completely insert PCBs, but I really do feel they helped improve this design. I’m not sure if I’ll be able to justify the extra cost in the future, but they were a nice Christmas gift last year.

Overall I’m really happy to see the TypePak design philosophy pay off. Once you have the microcontroller situation squared away, a set of keycaps you like, and some key switches on hand, creating another keyboard variant is a relatively cheap affair. You just need to buy a new set of hotswap sockets, fabricate a few PCBs, and order a new pair of Game Boy cartridge slots.

Conclusion

I’m trying to keep this writeup short and sweet. Despite the 2,500+ words at this point, the Mark II really is an iterative update. I didn’t touch on the firmware much in this writeup, but that’s because I hardly needed to touch my original ZMK configuration. Even the key matrix definition stayed the same between these two updates.

If you're interested in learning more about the TypePak, I've got all the details and some build photos in the original post about it. It shouldn’t go unsaid that the Mark II is another keyboard created with the Ergogen keyboard layout generator. My guide of Ergogen is miraculously still up to date and relevant if you’re curious what goes into building a keyboard like these. If you’re interested in the purple Game Boy inspired keycaps, I did a whole writeup about FK Caps’ custom key printing service last year as well.

That’s all for now. The TypeBoy MkII’s Ergogen config files, KiCAD PCBs, and ZMK config are all up on GitHub. Likewise, the TypePak has its own repository. If you’ve got any questions, comments, or general shout outs, feel free to hit me up on Mastodon.

Welcome to my latest keyboard design! The TypeBoy is a fairly standard split ergonomic keyboard with a very non-standard microcontroller setup. Your eyes don't deceive you: This is a keyboard that needs a Game Boy Advance cartridge to function.

More specifically, it needs a TypePak! I've been spending a lot of time in the Ergogen keyboard layout generator lately, and I recently finished building a Sanni Open Source Cartridge Reader. These two worlds collided in my head and it dawned on me that a keyboard's microcontroller stack could probably fit in the shell of a Game Boy cartridge. A bit of tinkering in KiCAD later, and suddenly this monstrosity the TypePak was born.

The TypePak

The TypePak is a custom keyboard controller PCB housed inside of an aftermarket Game Boy Advance cartridge shell. It features Bluetooth connectivity, ZMK support, a low-power monochrome display, a built in LiPo battery, 9 GPIO pins, and 8 dedicated output pins. Simply slot the TypePak into a keyboard with a compatible Game Boy cartridge slot, flip the power switch, and you've got yourself a working wireless keyboard. (After flashing the appropriate firmware and keymap, naturally.)

To little surprise, this is all pulled off thanks to the nRF52840 system on a chip. The nRF52840 is the heart of the popular Nice!Nano microcontroller, and boasts support for the wireless keyboard firmware ZMK. While the TypePak technically could have used a bare nRF52840 module, that would have required building out a decent amount of support hardware such as a USB-C port and battery charging circuitry. Instead, I opted to leverage the petite Seeedstudio XIAO nRF52840 microcontroller. (Affectionally called the "XIAO BLE" by folks who don't feel like memorizing a random five digit number.) This compact microcontroller has everything you need for a keyboard built into one small package, and it almost fits inside of a Game Boy Advance cartridge.

One of the downsides of the XIAO nRF52840 over the Nice!Nano is its relatively small number of exposed GPIO pins. The XIAO has just enough pins to power a small split keyboard, but the TypePak would be limited in the context of larger split boards or unibody builds. To rectify this, the TypePak also includes a 74HC595 shift register. This provides the TypePak with 8 dedicated output pins to use for columns in a keyboard matrix. Pair that with 9 free GPIO pins on the XIAO BLE, and you've got plenty of room for rows, columns, and other ancillary hardware.

The other prominent component on the TypePak is a LS011B7DH03 Sharp Memory Display. This is the same 160x68 monochrome "transflective LCD" used on the Nice!View. There's not quite enough space in the cartridge for a proper Nice!View module, so the TypePak instead provides a ribbon cable connector and acts as a breakout board for a raw LS011B7DH03 display.

Finally, the TypePak has a 401020 LiPo battery soldered directly underneath the PCB. (Fun fact, the model number of these batteries tells you the dimensions. The 401020 is 40mm x 10mm x 20mm.) This battery is slightly smaller than the batteries you usually find tucked underneath an Arduino Pro Micro. It has 80 mAH of power compared to the typical 110 mAh LiPos. Thankfully these smaller batteries still have enough power to be reasonably useful. The main half of the TypeBoy gets about a week of battery life, while the secondary side of the keyboard should last you about two months. Just plug the left side in on Sunday nights and you should be fine.

All of these components are held together by a small custom PCB. The Game Boy cartridge slot expects PCBs to be between 0.8mm and 1mm thick. Building a 0.8mm thick PCB gives you a tiny sliver more room when building your keyboard, but some PCB manufacturers charge extra for non-standard colors on thin boards. Thankfully 1mm boards work just as well if you're going for a particular aesthetic. The 1mm PCBs also help provide a bit more friction to keep the cartridge in the slot a little better than the 0.8mm PCBs if you're planning on doing a lot of traveling with the TypeBoy.

The TypePak Pinout

A Game Boy cartridge has 32 pins on its edge connector. The XIAO nRF52840 and the shift register have a total of 26 pins. (This includes the reset and NFC pins on the underside of the XIAO nRF52840.) Rather than leave twenty precent of the TypePak's cartridge pins unused, several of the important pins are exposed on both ends of the cartridge's edge connector. The battery output, power pins, reset pins, and a few others are duplicated so that you can more easily route some of the support hardware on your keyboard PCB.

Speaking of which, the TypePak does not have a built in power switch or reset button of its own. (Technically the XIAO does have a reset button, but it's underneath the cartridge's plastic casing.) You'll need to create out these components on the keyboard itself. The whole idea of this setup is to evoke the stylings of a classic Game Boy, so a large chunky power switch is honestly a welcome addition.

This does give the TypePak a slight quirk. The battery isn't physically attached to the microcontroller unless the cartridge is plugged into a keyboard and its power switch is set to the on position. If you'd like to charge the keyboard, you can't just dangle the TypePak off of a USB outlet.

Every pin on the microcontroller is broken out onto the TypePak's edge connector. This includes pins that are used for components such as the Sharp Memory Display. If you decide not to include the display, or want to try adding on additional SPI devices, you shouldn't have any trouble getting to MISO, MOSI, SCK, and the LCB's CS pin.

The cartridge slot is easy enough to add to a keyboard design. Rather than adding two rows of through hole pins, you add one row of surface mount pads. The only quirk is on reversible PCB layouts. On the left keyboard the cartridge will be inserted with the first pin oriented towards the top of the PCB. On the right side of the keyboard, the last pin will be oriented towards the top of the PCB. The solution to this is to create a rainbow of via traces connecting the front pads to their mirrored counterpart on the back side. Thankfully the cartridge slot's width gives you a good amount of otherwise unused board space to trace these routes.

Building A TypePak

Assembling the TypePak PCB is a bit of an interesting challenge. The PCB needs to sit flush on the bottom cartridge shell, so this was my first PCB design to fully use surface mount components. I had experience with small surface mount diodes in the past, so the microcontroller and display capacitors weren't too much of an issue. Even the shift register isn't too tricky if you have steady hands. The display connector however...

This component is not a beginner-friendly soldering job. It has 0.5mm wide pins with a 0.5mm gap between them. If you haven't used solder flux and solder wick in the past, this project will teach you their usefulness.

Solder flux helps promote bonding between wires and pads. It prevents solder from clumping up, and lets you move excess solder around more easily. Even then, you're likely to get some bridging between pads.

That's where solder wicks come in. They can help remove excess solder from a board and clean up uncooperative shorts.

After some patient soldering, wicking, re-soldering, and additional wicking, you should be able to get the display connector situated cleanly. Honestly, I'm a little upset with myself for not getting on board with solder wicks sooner.

Besides taking it slow, the most important part of soldering the display connector is making sure all of it's pins are aligned. It has two mounting pads on the side, so you can solder one of those pads into place before tackling the actual data pins. JLCPCB and some other PCB fabs also have the display connector in their parts library. If it's not prohibitively expensive, I may look to just have my PCB fab deal with these connectors in the future. Once you've got everything soldered, make sure you use a continuity tester to make sure the pins aren't bridged anywhere.

After dealing with the display connector, the XIAO, capacitors, and shift register shouldn't be any issue. A bit of solder flux can help the shift register as well. Just solder one of the pins to anchor the rest into their properly aligned position. Everything else is just standard smd soldering. Maybe invest in some reverse action tweezers along with the flux and solder sick.

One you have everything but the battery soldered into place, you can start contemplating the cartridge shell. The side of the plastic shell will need a cutout for the TypePak's USB-C port, but we actually need to go a bit further than that. When I first mentioned the XIAO nRF52840, I said it almost fit in a GBA cartridge. Between the TypePak cartridge and the XIAO's PCB, the USB-C port is just a millimeter or so too tall. We'll also need to carve out some additional headroom for the USB-C port while creating a cutout for it.

That's right, this is a project requiring some power tools.

There's probably a few different ways of tackling this sort of cutout, but I personally opted for a Dremel and a clamp. Grab a face mask and protective eyewear for good measure. You're going to be kicking up a lot of plastic dust. The easiest way to keep track of what parts you need to remove is to make small scoring marks with a hobby knife while the PCB's in the case.

Remove the PCB, clamp one half of the cartridge shell down, sand a bit of the material away, unclamp the case, and reseat the PCB to see if it fits.

You'll want to repeat this process a half-dozen times. You can't add plastic back to the shell, so it's better to drill away too little than too much.

Once you've got the PCB sitting flush in the bottom piece, it's time to work on the top half. Drilling a side cutout for the USB-C port isn't enough here.  You'll quickly find that the two halves of the case don't have enough room close.

My first instinct was to simply make a large rectangular cutout in the top of the cartridge shell. (You can see an example of this a bit later in this writeup.) Rather than completely taking the top off of the cartridge however, it's enough to simply shave off some of the plastic from inside the case. The cartridge is just thick enough that you can carve out the inside of the shell without actually disturbing the exterior of the shell.

It's a tricky process and will require a few rounds of shaving, re-fitting, and shaving away again. In my experience, the end result hasn't been a perfect fit. The two halves are held together with two small plastic tabs on each side of the cartridge. After enough drilling, you should at least be able to get all four tabs to remain comfortably in place.

The center of the cartridge may bow out a bit, but there's also a screw that can help hold the cartridge together. There's a small gap in the cartridge if you know where to look, but it's not very noticeable on the transparent cartridge cases.

At this point we can go ahead and add the battery and close the cartridge up. In my experience however, it's pretty easy to accidentally leave a pin not fully soldered or have an accidental bridge somewhere. Rather than opening and closing the cartridge several times as you troubleshoot, now would be a good time to go and build your keyboard itself. The TypePak fits in a cartridge slot with the top half of the cartridge missing, so you can properly test everything over USB before continuing. If something doesn't work, it'll be easier to run some continuity tests before closing everything up.

Once you're happy that the keyboard and the TypePak are working, you can go ahead and solder the LiPo battery into place.

After that, carefully attach the Sharp Memory Display ribbon cable. Flip the latch up, slide the ribbon in over the top of the gray flap, and then push it back down.

Actually assembling the cartridge is... really tight. You need to slot the cartridge into place, slot the battery in beside it, and then do your best to fold the ribbon cable over so that the screen is pointing up at the cartridge's clear window. The process is a little tricky to photograph.

You might not get the screen 100% aligned with the window. I tried taping the screen down to the top shell, but that made it nearly impossible to actually attach the ribbon cable. In addition to needing to worry about the display while closing the two halves of the cartridge, you need to be mindful of the battery's position inside of the case. The LiPo battery has a tendency to slide up all the way to one side of the cartridge. The plastic lip of the battery likes getting pinched by the case as you try to close it.

Once you get the two pieces together, you have a nice compact cartridge of keyboard computing. Hopefully. The first cartridge I built ended up crushing the display between the cartridge shell and the top of the XIAO. It cracked the display instantly before I even had a chance to feel any resistance. Your milage may vary, but thankfully the second cartridge came together a bit easier. You really only need one display for a split keyboard, so I just left the second display out for this particular build. Hopefully things go a bit smoother for you. Just take things slow and be mindful of the stress you're putting on the different components.

Now that we've got the TypePak built, we can turn our attention towards the TypeBoy.

The TypeBoy

The TypeBoy is a fairly standard split keyboard with a 6x4+5 column staggered layout. If it looks familiar, that's because this is essentially a split version of the keyboard I designed for my Let's Design A Keyboard With Ergogen v4 series. I've fallen into a little bit of a rut with 58 key boards, but what can I say, I'm a sucker for dedicated number keys.

The most striking aspect of the TypeBoy is naturally the large Game Boy cartridge slot on the side. This component replaces the standard microcontroller stack, and takes up slightly more PCB space than your standard Pro Micro or Nice!Nano setup. The cartridge slot has two plastic mounting legs, so aligning and soldering the pins is a breeze. Well, it's a breeze after that display connector at least.

The keyboard building scene has several low profile slide switch and pushbutton options, but I was able to take advantage of some taller components on this particular build. Since the hardware's going to be nestled up against the already tell cartridge slot, I was able to use nice chunky power switches and reset buttons. Both of them are of the right angle variety. The right angle reset button is a bit anachronistic for a Game Boy, but the power switch hits all the right nostalgia notes.

Finally, mechanical keyboards often include rotary encoders. These knobs can't do anything that a hotkey on your keyboard couldn't handle, but they're popular for quickly adjusting the volume on one's PC. Wouldn't you know, there's one last piece of Game Boy hardware that we can pay homage to. Nintendo's handhelds have had a variety of volume wheels and contrast knobs over their lifetime. I did some digging and tried to find a low profile encoder that would be suitable for the TypeBoy.

I originally tried working with the SIQ-02FVS3 rotary encoder. It's a true spinning wheel, but retains a push action so you can still send three signals like a traditional rotary encoder. Unfortunately I couldn't quite get it working with ZMK. I may have just had a bad batch of encoders, but I eventually swapped it out for a SLLB510100 thumb switch. Instead of a fully spinning knob, this thumb switch allows you to slide it to the left or right by several degrees, or to push in on the center of the switch. It's similar to controls you may have seen on 90s CD players or early 00s MP3 players. It's not a perfect fit for the Game Boy aesthetic, but it's close enough. They're also just a nice touch on low profile keyboards in general. I'll be experimenting a bit more with these in the future.

That's it for the hardware. The rest of the TypeBoy is a fairly standard Choc-spaced Sofle derivative with some splay on the last two columns for a bit of flair. Adding the cartridge slot and the thumb switch was more than enough experimentation for one build. You may have noticed a bodge wire in some of the pictures. There was one last wiring issue which I've already resolved in the files hosted on the TypeBoy's GitHub repository, but I didn't want to wait for another batch of PCBs to fix it.

Now that I've got a working keyboard, the last part of this build was to create an enclosure for it. (Note to self: Take more pictures during the bare PCB step!)

The TypeBoy Case

My previous two keyboards have both used a "tray" style 3D printed case. These cases are great for adding a bit of color to your keyboard and protecting the hotswap sockets, but I wanted to do something a little different this time around.

I knew I was going to be leaning specifically into the Game Boy Advance aesthetic. In addition to the whole cartridge thing, I also just picked up some some custom retro purple keycaps from FK Caps. (You can learn more about them in my recent writeup.) With this in mind, I also wanted to try and obscure the Choc Red Pro switches I was re-using from my last keyboard build. The ChonkV leaned into the red accents, but they'd clash a bit here.

To that end I took some inspiration from GEIST's full-height low-profile keyboard cases. Having the edges of the case come right up to the top of the keycaps is a striking look and it would do a good job of mostly obscuring the bright red switches.

This case design is a little more complicated than what Ergogen can output on its own. I re-learned Autodesk Fusion 360 and ended up building the board in two pieces: The standard bottom tray and a single piece for the top. The top piece needed to be printed upside down for a variety of structural reasons, which means that the portion the keys slot into was left a little gnarly from the temporary supports. You don't see most of these rough spots when the keyboard's finally built.

I'm not completely sure how I feel about the end result here. I knew my TypeBoy's PLA case wouldn't look as nice as the resin-printed cases GEIST used on the Totem keyboard, but the current Texas heat wave gave me a lot more trouble than I expected while printing off this case design. I ended up giving the TypeBoy a duo-tone look with a gray bottom piece for the simple reason that I ran out of purple PLA during my prototyping. Thankfully this is the easiest to swap out component if I decide I'd like to try and take another go at it. I'd still like to experiment with this full-height low-profile case style in the future, but I might also take a break from 3D printing and try some FR4 PCB sandwiches next time. Stay tuned.

Tricky printing aside, the TypePak and TypeBoy are officially done! Now all that's left is to program it.

The Firmware

After all the sturm und drang about cartridge slots and edge connectors, the firmware for the TypePak is relatively standard. It leverages ZMK since this is a wireless keyboard, but otherwise it's not pulling any unusual software tricks. As far as the firmware is concerned, it doesn't know that it's living on an odd removable daughterboard.

In case you're trying to build a keyboard with similar hardware, there's a few noteworthy aspects of this particular firmware build. First of all, it leverages a 74HC595 shift register to give the microcontroller a few extra pins. Next, it has the same LS011B7DH03 display as the Nice!View, but it doesn't actually actually use the Nice!View's wrapper. From the best I can tell, the Nice!View code is designed to pair with the Nice!Nano microcontroller, and things don't map up perfectly if you try running it on a different board.

Both of these bits of code are just serial device definitions. The screen uses ZMK's built in display support. The shift register meanwhile isn't too tricky to work with. Once you define the register, you can use it's pins as columns in a matrix just like you would with a standard microcontroller GPIO pin.

The only other piece of hardware on the TypeBoy is the thumb switch. It's wired up like three standard pushbuttons with a common ground, so it's not hard to get running in ZMK. You just define a "Composite" key scan driver that uses a standard keyboard matrix for the keys themselves, and then a direct wiring setup for the thumb switch "buttons".

ZMK is pretty well documented in the site's getting started guide. If you'd like to poke around any of the aforementioned code, you can check out the TypePak's ZMK config on GitHub.

With that, we've finally got a fully functioning keyboard! Which begs a question.

Why Go To All This Trouble?

Surely there must be some reason I'm going to all these lengths, right? The TypePak and TypeBoy must offer some sort of benefit that you don't get from your standard mechanical keyboard build?

Not particularly? The XIAO BLE and a bare Sharp Memory Display module are cheaper than a Nice!Nano and Nice!View, but it's a wash when you factor in the other support hardware. The classic Pro Micro stack just needs some header pins. The TypePak needs a custom PCB, a cartridge shell, a cartridge slot, a display connector, a shift register, and several surface mount capacitors. Depending on the shipping fees of your suppliers, the TypePak and the Nice! combo cost roughly the same amount.

The components inside of the TypePak occupy a space that's roughly comparable to the traditional microcontroller stack, but the cartridge connector and the TypePak itself takes up considerably more room. It's fine for designs where the cartridge can hang off the side of the keyboard like the TypeBoy, but it might not fit every build.

One of the strengths of the TypePak is how easy it is to move from one keyboard to another. The mechanical keyboard community is particularly fond of machine pin headers, but I personally feel like I'm going to break them every time I try inserting or removing a microcontroller that's using diode legs. This ease of moving a TypePak between keyboards is nice, but it's slightly hampered by the reality of firmware logistics. If you move from a 6x4+5 split keyboard to a 5x3+3 split keyboard, or from a split keyboard to a unibody build, you're most likely going to need a different keymap. The act of slotting the TypePak in will take two seconds, but you'll still have to re-flash the microcontroller for the new layout.

So... That mostly just leaves aesthetics and the hardware challenge. 3D printed case issues aside, I'm really happy with how the TypePak and TypeBoy turned out on the aesthetics front. The cartridge slots in exactly how you'd want it to, and the window on the TypePak is the perfect size for the display. The transparent cartridge really leans in nicely to those early aughts vibes, even if you don't go for the Atomic Purple version.

I'm looking forward to leveraging these TypePaks for my next few keyboard builds. Now that the TypePak is actually built, it's just a couple of dollars per-keyboard for a new Game Boy cartridge slot.

TypePak Build of Materials

The above table represents the parts needed to construct a single TypePak. You'll need to double everything except for the PCB order if you plan on making two. (JLCPCB fabricates PCBs in groups of 5 as a minimum.) If you're building two TypePaks, it's probably worth bumping the capacitor and ferrite bead orders up to 10. You don't want to have your entire project get stalled if you misplace one of the small components, and the bulk ordering pricing makes buying 4-6 units approximately the same cost as 10.

There's a variety of aftermarket Game Boy Advance cartridges available online. They primarily come in two varieties: Ones with small plastic dots on the inside of the label window, and those that don't. Make sure you get the version with the completely clear window. So far I've tested the TypePak with the gray "smokey" clear, Atomic Purple, and standard clear casings. The Sharp Memory Display is clearly visible through all of them. I assume they'd be similarly visible through the transparent red and transparent blue cases on the market.

One small note, most cartridge vendors mention that they're designed for "bootleg" PCBs. Authentic Game Boy Advance cartridge PCBs and shells have two small tabs on the inside to hold the PCB in place. These tabs aren't completely necessary, and they take up space that you could otherwise use for parts. The TypePak uses the "bootleg" PCB footprint and won't fit inside of an authentic cartridge. Don't be a monster and try to drill into a functioning Game Boy cartridge. These cartridge shells are cheap, widely available, and come in plenty of different colors.

TypeBoy Build of Materials

As I mentioned earlier, I've generally found machine pin headers a bit too fiddly for my taste. The dream of DIY mechanical keyboards is that you can just move the expensive parts from socket to socket and keep your build costs low. Despite this, my Pro Micros have stayed put on my original Sofle, and my Nice!Nano is firmly planted on my ChonkV. The TypePak seems much more likely to see some movement between boards however.

If that dream becomes a reality, one of the TypePak based keyboards should run you about $50 USD when all is said and done. You still need to drop about $80 USD on the TypePaks, between $30-50 USD on switches, and another $50-70 USD on keycaps. Once you've done that upfront cost however, iterating on designs and rapid prototyping should be a bit less taxing on one's budget. More or less, depending on your access to a 3D printer and how many bumpons you've got clogging up your project drawer.

Acknowledgements

The TypeBoy isn't the first mechanical keyboard which takes microcontroller cartridges. mujimanic's Giga40 keyboard design and it's Famicom cartridges helped prove a low-profile Game Boy-centric version of this idea was worth pursuing.

The TypePak's display connector circuit is based off of karnadii's Sharp Memory Display breakout board design. The TypePak's PCB is based off of templates from djedditt's kicad-gamepaks library. The Game Boy cartridge slot KiCAD footprint was used from Martin Refseth's Game Boy KiCad Library.

As usual, thanks to the Absolem Club Discord and their #Ergogen channel for answering my endless onslaught of questions. Particularly special thanks to Pete Johanson for assisting with some ZMK troubleshooting when the low profile rotary encoders were giving me trouble. The ZMK firmware is heavily influenced by previous configs by GEIST, Pete Johanson, and JonMuller.

This keyboard is another derivative of Josef Adamčík's original Sofle Keyboard layout. I need to start experimenting with other layouts at this point, but it's hard to beat that thumb cluster.

Finally, another shout out to GEIST, Freya, Bubbleology for their work on the TOTEM keyboard's case. It was a big inspiration for this build, and they pulled the concept off way better than I did.

Conclusion

I still can't believe this worked. Right up until it started typing, I felt like I bit off a bit more than I could chew with this particular design. It was my first XIAO BLE build, my first LS011B7DH03 breakout board build, my first time experimenting with thumb wheels, and my first time trying to cram everything inside of a Game Boy cartridge. I'm a little astonished it all managed to come together. Part of me was worried this would just get written off as some dead end surface mount soldering experience.

A few people have asked me if I'm going to try and establish the TypePak as a "standard" of some sort that designers build a keyboard around. We'll see how much interest there is in this particular build, but right now I think this is probably going to be relegated to exceptionally nostalgic do it yourselfers. The Dremel step of, "Carve away plastic until it feels about right" is a little too vague for a true guide at the moment, and right now these cartridges have a 50% rate of accidentally smashing the most expensive $15 USD part in the build. We'll see where things go in the future.

For now I'm happy to get some typing in on my new keyboard. You can bet I'm already thinking about where I'll take things next. Until then, you can view all of the KiCAD files, Ergogen configs, and ZMK keymaps for the TypePak and TypeBoy on GitHub. As always, feel free to give me a shout out on Mastodon if you liked this project!

If you've built a low profile keyboard, you're most likely already familiar with FK Caps. They're the team behind the popular MBK keycaps for Kailh Choc v1 switches. These keycaps make up the bulk of keycap options for Choc switches, and provide a few different avenues for expressing yourself.

The original MBK keycaps were blank, legend-less keys. They were available in a variety of injection molded and dyed colors, and let you build any sort of keyboard you could imagine... as long as you were a good touch typist. Then the aptly-named MBK Legends keycap set burst onto the scene. They offered a variety of alpha keys, text modifiers, and icon-based legends designed by tectonicplate. The initial run of MBK Legends provided aspiring keyboard builders with white, black, gray, and red keycap options. While stock of this initial print run is dwindling, FK Caps is planning on releasing a new extended MBK Legends set this year which will swap out the red accented keys for a new blue set.

Not satisfied there, FK Caps also released the popular MBK Legend Glow keycap set. This set is a must-have for any low profile keyboard with per-key LED backlighting, and is available in black or white.

For the last few years, this has generally been the state of low profile keycaps. You can either eschew key legends and create a color-coordinated board with blank keycaps, or you pick up set with legends and embrace the monochrome or lean into the red accents. I did the later with my ChonkV keyboard. But now FK Caps has come out with a new option for keyboard design.

FK Custom

FK Caps' new FK Custom service is a laser engraving keycap service. Instead of having to choose between a stock set of legends or a blank set of keys, you can now print off exactly the keys you want for your next build. (Just in case you don't make it to the end of this article: You can get an extra 10% off your order with the FlatFootFox affiliate code.)

I'm not going to bury the lede here: You can now make a low profile keyboard with purple legend keys.

Okay, that might not be everyone's priority. Let's back up a bit. FK Custom allows you to create custom-legend keys across 7 different keycap types. In the low profile Choc arena you can create three different types of MBK keycaps, while the full size MX crowd can make keys with Cherry, DSA, or MDA profiles. These keycaps come in a variety of colors (White, black, purple, red, orange, and black shine-through in the case of MBK keycaps.) The keycaps can be adorned in any text, international characters, icons, or vector graphics that you'd like.

FK Custom does a good job walking you through all the characteristics of each switch type. Their white MBK keycap offering feels similar to their classic MBK Legends keycaps, while the MBK (PU) keycaps have a polyurethane coating similar to the MBK Glow keycaps. If you're trying to match the look and feel of an existing keycap set, they do a good job steering you in the right direction.

Once you pick your keycap type, FK Customs sends you through an interactive keycap design tool. Rather than having to start with a blank slate, FK Custom has gone ahead and created templates for some of the most popular ergonomic mechanical keyboards. If you're looking to outfit a Ferris or a Corne, it's as simple as selecting your board and moving onto the next step. If you're looking to build a keycap set for a custom board, you can drag and drop keys to build your custom layout.

To start things off, FK Custom lets you select the language of your board. This applies a standard set of alpha letters to your board. The international crowd will be happy to see a wide variety of local letters and accent marks available within the customizer. (It's also worth noting that FK Custom has worldwide shipping for $9 USD.)

Once you've picked your language, you can adjust the font of the alpha keys. The tool defaults to the legible Noto Sans, but you can mix things up with Helvetica Rounded, Roboto, and even some retro pixel fonts. You can also upload your own custom font file if you're looking for something a bit more bespoke.

In addition to these keyboard-wide changes, you can also make individual adjustments to each keycap. You can enter text on a keycap, use a built-in icon, or upload your own vector.

Text keys support a variety of sizing and placement options. You're able to switch the font on a per-key basis, allowing you to do things such as having different fonts for your alpha keys and your text-style modifiers.

Icon keys allow you to select an icon from a variety of icon sets. You can select any of the icons from the custom MBK Legends icon set, as well as use icons from a variety of open source libraries such as Icofont, Font Awesome, Bootstrap, and Framework7.

If the glyph you're looking for isn't in any of those icon sets, you can also upload your own custom .svg vector icons. These can come from other external icon sets, or can be your own creation from free tools like Inkscape or Figma.

All of these key types allow for different scaling options. I used a variety of built in icons and uploaded .svg files in the icon set I purchased from FK Custom.

The final summary screen gives you a nice breakdown of your shopping cart. Keys are listed by size and profile, so it's easy to spot if you accidentally selected a concave key, or put the wrong legend on one of your home row homing keys. FK Custom charges a separate price for customized and blank keys, which makes it easy to toss in a few blank keys to your order in case your design sensibilities change over time.

The Finished Product

FK Custom had quick turnaround and shipping in the United States. Their 6-14 day shipping means these keycaps probably won't be the long pole in the tent for your new custom build. The keys arrive in a small shipping box, and are vacuum sealed during shipping to keep them safe and scratch free.

I'm incredibly happy with how these keycaps turned out. I was satisfied with the existing alpha keys in my MBK Legend set, but was eager to introduce a splash of color onto my keyboard with a new set of modifiers. I created a few keys with the existing MBK Legend set, as well as a few keys with custom vector designs from .svg files I uploaded.

The laser engraved legends look good. My next board is going to have a gaming influence, and the laser engraving process was able to handle the pixelated sharp edges of the icons I uploaded without any problems. (Random aside: It's a fun weekend project to try and get vector graphics applications to output convincingly squared off pixels.) FK Custom's laser engraving also did a good job of handling the smooth lines of my FlatFootFox icon.

I purchased a few 1.5u keys, some concave keycaps, and a pair of new homing keys. They all turned out equally as well as the standard 1u convex keys. The "J" is just as legible on the homing key, and the icons I printed on the concave keys came out just as well as on the convex keys. If you're familiar with the other MBK keycaps, you basically know what to expect here.

It feels silly 1,300 words into this review to suddenly walk away with the conclusion of, "Yup, they're keycaps", but that's largely the takeaway here. 10/10, no notes. FK Custom lets you easily create a set of high quality custom-legend keycaps for your low profile mechanical keyboard. The next time you start an ergonomic mechanical keyboard build, make sure to budget a few keycaps from FK Custom. FK Caps has started up an affiliate program, so feel free to use the code FlatFootFox for an extra 10% off.

All good things must come to an end! We've come far since the introductory post! In Part 1 we created our keyboard's layout by leveraging points, in Part 2 we gave our board an outline, in Part 3 we discussed microcontrollers and created the basis for our PCB, and in Part 4 we imported external footprints and designed a keyboard case. We've reached the end of our journey with Ergogen.

The final steps of building a keyboard all take place outside of Ergogen. The biggest missing piece is actually creating the routes for our board in KiCAD. After that we need to create a custom firmware for the new keyboard, and finally there's the matter of actually sourcing the parts and assembling the keyboard.

This section is going to be a bit less click-by-click and line-by-line than the previous chapters. The remaining tools we need to leverage all have useful documentation and tutorials of their own, so the remainder of this guide is going to be giving some Ergogen-related tips and tutorial recommendations.

What a CAD!

The "CAD" in "KiCAD" comes from the term "Computer Aided Design". CAD itself is an offshoot of EDA, or Electronic Design Automation. This isn't just a stroll down memory lane (although fun fact, KiCAD is a portmanteau of the name of the lead developer's friend "Ki" and CAD), but it will hopefully be some useful context.

CAD software is old. Like, has its roots in the 1960s old. The most popular commercial CAD software today is EAGLE EDA. (I swear this series isn't a subtile plug for Autodesk, they've just acquired a ton of applications at this point.) If EAGLE's all-caps German acronym name wasn't enough of a hint, this app has been around for 35 years. It started off as a 16-bit DOS application.

This is all to say that CAD software, including KiCAD, has some very odd historical quirks. The conventions of this space were codified at a time when designers had arrow keys and trackballs. There's an unusually heavy reliance on hotkeys, and a "modality" you don't see in many modern apps.

CAD software is difficult to "feel" one's way around. Case in point, the simple act of drawing a line is unlike any image manipulation app you've ever worked with. Instead of clicking and dragging where you'd like to draw a trace, you click on a start point and then drag your mouse along the path where you'd like the trace to go. Once you've reached the final point, you click a second time exit the routing mode. It's a few steps removed from opening up Photoshop, clicking on the blurry-looking icon, and then clicking and dragging the blur tool around experimentally.

I cut my teeth on KiCAD with Brian Benchoff's excellent HackADay Creating A PCB In Everything series. It served as a general survey of various popular CAD softwares at the time, and walked readers through creating a KiCAD schematic (something we didn't need to do thanks to Ergogen creating our nets), designing a footprint from scratch (useful, but something that doesn't come up as often in the Ergogen community), and finally routing everything together (the last step we need to do here today).

At the time of writing this post, KiCAD 7 is hot off the presses. KiCAD goes through the usual incremental upgrades between versions, but any guide you find for KiCAD 4, 5, or 6 should still be somewhat useful to you. KiCAD 4 had some significant UI changes over KiCAD 3, but things have been much more subtile since then.

As far as additional resources go, KiCAD manages some recommendations themselves. This includes their own KiCAD Getting Started guide. Rene Poschl and Nate from Sparkfun also both have well regarded KiCAD 5 and KiCAD 4 guides. Ben Vallack also has a good keyboard-specific KiCAD video. Apologies for not having solid personal recommendations for more contemporary resources.

Routing Basics

Printed circuit boards are made out of an epoxy fiberglass composite known as FR-4. They're, you know, flat boards, and have a copper layer on each side to connect your components together. When working with PCBs, it's important to remember that you're dealing with a two sided object that has a defined front and back.

This isn't completely universal. You can save a dollar and get copper only one side of your board. You can also pay three times as much and get a four layer PCB that's a sandwich of multiple copper and FR-4 layers. In most situations however it's not worth saving a buck to deal with making a single layer board, and whatever issue is nudging you towards considering a four layer PCB can be likely be solved with some clever rearrangement of parts and traces. For the most part almost any PCB you design or interact with will be a two layer PCB.

The copper line between two components on a PCB are known as a "Trace". The verb for defining a trace on your PCB is "Routing". Sometimes a trace will be referred to as a "Route". They're also occasionally known as "Tracks". The big last step we have in our keyboard design process is to route these traces on our empty PCB.

KiCAD draws traces on the front of the PCB as red lines. They're part of the F.Cu layer. (AKA "Front.Copper")

Traces on the back of the PCB are drawn in blue lines. They're part of the B.Cu layer. (AKA "Back.Copper".) In this primitive example, what would happen if we try to connect these two far left and far right pins together?

Our line gets stuck! KiCAD won't let us draw two red lines intersecting on top of one another. What if we switch to the B.Cu layer?

This time we managed to go over the F.Cu trace, but we got stuck again at the B.Cu trace.

This isn't software. We can't just cheat across intersections. If you want to draw a front trace over another front trace... you can't. You need to go around. A big part of PCBs is getting smart about where you place components.

Sometimes we don't have the option of being smart however. If our board was a bit more narrow, we couldn't just sneak across the top. So what are we supposed to do in a situation like this?

The one Get Out of Jail Free card we have when it comes to routing is the "Via". Vias are physical holes drilled in our PCB that allow traces to move from one side of the broad to the other. Sometimes our layout is just too complicated and there's no better way to get around an existing trace.

There's a variety of factors impacting the cost of a PCB. The primary cost comes from the side of the circuit board. You pay per square millimeter. The larger your keyboard, the more it's going to cost. Secondary to that is how long it takes to fabricate your keyboard. If the PCB manufacturer has to spend an inordinate amount of time working on your PCB, they'll usually charge you a bit extra. Vias are physically drilled into your PCB, and drilling takes time. It's usually a good idea to limit the number of Vias you use when designing a keyboard. If you need to use a dozen of them to get your microcontroller wired up, fine, but it's not something you really want to use on a per-key basis.

One last note on routing basics is the difference between "surface mount device" SMD pads and "through hole" pins. SMD pads are only exposed on one side of the board, so your trace needs to connect to it on the same side. In the above screenshot, our hotswap sockets need to connect to the blue pads on the back, while the reset button has red pads on the front. Through hole pins are physically drilled through a PCB and are exposed on both sides of the board. You can start your trace from either the front or the back when working with through holes components.

I'm generally a fan of SMD diodes for keyboards. They're a little more fiddly, but you don't have to worry about the trimmed through hole leads getting in the way of anything. SMD diodes are also shorter than the hotswap sockets we're working with, so they don't introduce any new design considerations there Despite all this, I kept the dual SMD and TH diode footprint on our example keyboard design. Having at least one through hole component on each key switch allows us to more easily hop back and forth from the front and back of the keyboard.

Routing A Keyboard

Enough theory! Let's route our keyboard. If you haven't already, download KiCAD and open the PCB file Ergogen created earlier. I had been using KiCAD 6 in all of the screenshots I had taken up till now, but I suppose I really should hop on the brand spanking new KiCAD 7. There shouldn't be too much that changed between the versions, but I don't want new users to get caught up on the names of settings and preferences if there's any small differences.

Speaking of which, let's start with a quick preference tweak. Navigate to File -> Settings, or press Cmd-, if you're on a Mac. Navigate to the Editing Options section. Change the "Step for rotate commands:" option from 90 degrees to whatever value you had set the rotate: value to your mirrored halves in your Ergogen config. In our case, that's 20 degrees.

Now if we tap the r or Shift-r key while working with a part, KiCAD will rotate it 20 degrees instead of 90 degrees. This is useful for pivoting between the different halves of the board and keeping all of our traces straight. To rotate the board, simply tap Cmd/Ctrl-a to select every component in your design, then r or Shift-r to rotate it.

My general approach when routing a board is to route the keyboard matrix and then figure out how to connect it to the microcontroller. To start with, let's figure out how we want to wire up an individual key.

Hover your cursor over one of the through holes and press the x key to begin routing. You can also select the "Route Tracks" tool from the right side of KiCAD and click the pin or pad you want to start routing from. We've immediately run into a problem here though. Our track is on the red F.Cu layer, and we're trying to connect to a blue B.Cu pad.

To switch sides of the board, tap the v key. You can also manually change front and back layers by using the panel on the right. Traces are always routed on the F.cu and B.cu layers, but you can use the other tools (lines, arcs, circles, text, etc.) to add elements to the other layers. Anything on the F.Silkscreen and B.Silkscreen layers will be drawn as a graphic on your board, and Edge.Cuts defines the physical edges of your PCB.

You may have noticed that your traces are really clunky. They're snapping to an almost absurdly large grid for the PCB we're working with. Let's fix that.

The Grid: drop down at the top of the page is defaulting to 0.2540mm. (In other words, 0.01 of an inch.) We need something considerably smaller. I personally like working with 0.2mm. It's small enough that you can flexibly route your board, but still on enough of a grid that aligning things doesn't become a nightmare. Feel free to experiment and see what works best for you.

Most of the measurements we're working with here make more sense in terms of millimeters. (Sorry my fellow Americans.) If KiCAD starts suddenly displaying property screens to you with five digit decimal inch measurements, you probably accidentally changed your units somewhere along the way. Thankfully you can quickly get back to millimeters by clicking the small "mm" icon on the left side of the screen.

Now that we're familiarized ourselves with KiCAD, onto the actual routing.

This particular diode footprint has SMD pads on the front and back. To start with, wire the front pads to the through holes. To do this, hover over one of the pads, press the x key to start routing, and then click the lit up pin next to the pad. Repeat this process for the other pin and pad.

Flip to the back layer with v and wire up the rear pads. Again, x to start routing, click to stop. Yes, this is going to get a little tedious doing it on the front and back for 58 keys.

Next, wire up the through hole pin on the right to the pad on the right. When you're actively dragging the line, the two should be lit up so you know where to draw.

KiCAD has a bit habit of sometimes jumping to a gap you didn't quite expect. If this happens I haven't found a good fix other than wiggling the mouse a bit or tapping Esc to cancel routing and remove the line. Sometimes you just need to try drawing the route a few times. Starting from the opposite end can also sometimes help.

Repeat this process for 9 different switches. (Naturally you don't have to stick to this design exactly, but having a repeatable per-switch footprint does make your board look nice.) Now that we have several adjacent keys, we need to figure out how to wire them together.

Pressing x over a pin will show us everything it's supposed to connect to. If we do it on the right side of a side, we can see it's connected to the right side of the SMD diode pad, and the right side of our hotswap pad.

If we do this on the left side of the diode, we can see the entire row light up. Now we're in business! Use your new routing skills to wire together three keys in a row.

While routing, you can click your mouse to lay down the trace you've routed so far. If you like the first part of a path, clicking lays that part down so you can start using it as the anchor for the rest of your routing. Now that we have a row set, let's take a look at a column.

Well shoot. The columns are all connected together by the SMD pads on the left side of our hotswap socket. All of these pads are blue, which means they can't cross over the rows we just routed. We could start using vias to hop the rows here, but let's try to be a bit more smart about it. The columns are forced to use the blue SMD pads as their start and end points, but rows start and stop at through hole pins. We should go back and re-do those rows as front traces. Thankfully KiCAD supports Cmd/Ctrl-z.

There we go! We now have a nice repeatable pattern we can use to wire up every key. The left side of the hotswap sockets are all connected together in a single column. The right side of the hotswap socket connects to the right side of our diodes. The left side of our diodes are all connected together in a single row. When a user presses on a key, the left and right pads of the hotswap socket will be connected together. They'll form a single circuit, passing through the diode on the way back to the microcontroller.

Now that we've got the base pattern down, it's time to apply it to the rest of this side of the keyboard.

Looking good so far! The top four rows have all been traced using the steps we covered before. Hopefully you've figured out KiCAD's slightly wonky mouse wheel scrolling by now. (It zooms in on wherever your mouse is hovering when you scroll.) The only big routing piece to call out here is the modifier keys on the bottom. Their columns are all shifted over by one, so we have to be a bit careful how we wire those up.

I've also gone ahead and routed the two thumb keys. This is a good example of what happens when you don't rotate the PCB before routing.

Those are some gnarly traces. Let's go back to the Preferences and set the "Step for rotate commands:" to 15 degrees.

There we go. That's marginally cleaner. Now we can set the rotate step back to 20 degrees.

With that, we're done with the left side of the keyboard! Press Cmd/Ctrl+a to select all of the parts, and then Shift+r twice to rotate things over to the right side of the board.

Time to do all those routing steps all over again. You've got this, right?

Yeah, you've got this. Alright, we have the two halves of our keyboard matrix wired together. What next?

In Part 3 of this guide, we touched briefly on keyboard matrix theory. This keyboard is using a "western duplex" matrix. The columns are technically stretched out to cover both the left and right side. If we start routing from one of our left hotswap pads, we can see both parts of the keyboard light up.

Things are going to get a little tight, but we should be able to run a set of traces along the bottom of our keyboard. Start from the outside and work your way in.

You don't need to finish the routes all in one go. In this screenshot, I've routed a trace for the outer, pinky, and ring columns along the bottom of the board. I like working on one side of the board, leaving a half-finished trace, and then coming back to it later after you've routed the board. Unfinished traces will work just like pins and pads on your board, and will have their associated nets pointing off of them.

When routing traces closely together, KiCAD will show a small transparent area next to your route. This is a minimum buffer area between the traces to keep them from interacting with one another. The KiCAD's default distance should be fine for our keyboard.

There's all six! It's not the prettiest group of lines, but it'll do the job.

You may need to get creative with your rotation angles when routing around some of these corners. Changing your Grid settings may also help.

If you routed everything properly, the nets should match up when these two groups of lines come together.

Holy cow that actually worked. Connecting all the lines took a bit of fiddling, but they came together in the end.

Okay. So. Microcontroller time. I like routing the OLED screen and Reset button to start with so that the nets are a little more readable.

You generally want to keep all of the microcontroller accessory routes inside of the microcontroller's footprint. We'll need the space to the left and right to route the rows and columns in a minute and- Ugh. Hold on.

There we go. Routing these things takes a lot of trial and error. Give yourself time to figure out the best layouts for things, and don't be afraid to back up and do sections over if you need to.

As a random aside, you'll notice all of the GND ground pins routed together here. They're technically connected together internally on the microcontroller, so these traces are strictly necessary. However, I've totally botched a header pin on a microcontroller in the past, so it's always nice to not have to rely on a single pinout if you don't need to.

Our traces are a bit more readable now. The column traces are mostly pointing straight down, but we can see the row traces reaching out. Let's connect those now.

These traces are admittedly a little messy. They get the job done though. Feel free to rotate things back and forth as you route if you haven't been already.

When routing a PCB, it's important to remember that the F.Cu traces are the ones you're more likely to see. We can be a bit more clean for the next step.

The majority of our board is routed using back traces. The only piece of our matrix using front traces are the left-to-right row traces. This makes things a bit easier to get across the length of the board. Let's start our column routes off with some red F.Cu traces.

Now there's a nice trace. Nice symmetrical straight lines framing our Arduino. That should look good on the front of the board. Once we start routing under the keys, we don't have to worry as much about all our traces being perfectly aligned.

Finishing off these routes marks the first appearance of vias in our keyboard. The F.Cu traces made it easy to travel this far across our keyboard, but in the end we still need to connect to a pad on the back of the board.

Okay, time for my coffee break. Do that again but on the other side-

Wait, what do you mean there's a trace in the way? Right, our board's symmetrical, but these key switch footprints are not. The column traces on the left side of the switch are in the way if we want to use the same row routes as before. Is there any way we could get them out of our way? Hmm...

Routing through diode footprints is a little cheeky, but it'll work in a pinch. Just be careful when soldering that column of diodes and you should be fine. Probably. The good news is we can route our rows now.

There we go. Now we just have three more columns to route. Thankfully these don't have to go as far.

Three more traces, three more vias, and we're done.

Wait a second. We're done! Look at that! A shiny new keyboard, all routed and ready to send off to the fabricator. Go us! We're finished with KiCAD now, right? Well, not quite.

Design Rule Checker (DRC)

Chances are you made a mistake somewhere in your board. (It's okay, this is a judgement free zone.) Rather than having to meticulously scrub through every trace however, KiCAD has what are known as "Design Rules". They're a set of configurations that stop us from making easy-to-spot mistakes like laying two footprints right on top of one another, or leaving a pad un-routed.

To access the DRC tool, click it's icon on the top navbar. Then click Run DRC in the modal that appears.

Oh jeez. That's a lot of errors. I was expecting one or two. Not over a hundred. Did I mention I upgraded to KiCAD 7 at the start of this guide? Hopefully this is just a quirk of the new version or some side effect from upgrading. Still, I'll keep the resolution of these issues in the guide if only for demonstration purposes.

Let's start with the easy warnings. Clicking on an error moves your window to that portion of the PCB. Zoom in on your board, then click the error in the DRC window to get a better look.

KiCAD's router can sometimes leave small orphan fragments on your board. If you click where the arrow is pointing, you'll get a dropdown asking you which trace you're trying to select.

Pick the small stray segment and delete it. You can delete traces with backspace on your keyboard.

If you fixed the issue correctly, you'll see [Deleted Item] in place of the track definition. The arrow will linger around until you re-run DRC however. (Or until you click the "Delete All Markers" options.

The other error had a similar chunk of trace left at a corner.

I honestly have no idea what's going on with the next error. Apparently the footprint has an incorrect attribute? Let's double click on the switch and figure out what's going on. If you double click on a component of the footprint (a pad, drill hole, etc.), you'll get the properties of that component. We want the properties of the entire footprint, so double click on some of the whitespace in between. You can also right click and select Properties... if you're having trouble finding some clickable whitespace.

This appears to be our culprit. Change "Footprint type:" to SMD. While we're here, it's worth remembering this "Position" section of the Properties screen. It can help you align footprints or tracks when laying out a PCB. You can also toggle the checkboxes in the "Show" column to enable or disable some silkscreen markings on your board.

Changing the "Footprint type:" on all of our Choc footprints and the diode footprints appears to have resolved this error. The next group of warnings has me stumped though. Hopefully this is just a side effect of updating KiCAD halfway through a tutorial? Or maybe it's something about Ergogen's footprints that KiCAD 7 just doesn't like. Either way, these are just warnings. Thankfully we can clear these out rather quickly.

Right click on one of the warnings and then chose the Ignore all 'Footprint not found in libraries' violations option.

That cleared out all of our errors and warnings. There's still a few issues under the "Unconnected Items" tab however.

Alright, here's the feature of DRC I actually wanted to show. The Unconnected Items tab is great for finding diodes you forgot to wire together on one side of the board.

The stock Ergogen footprint has two through holes, and then two sets of surface mount SMD pads. Both the red pads on the front and the blue pads on the back need to be connected to the through holes next to them. If you run DRC and get a number of errors that is close to 2x the number of keys on your keyboard, you've probably forgotten to connect the SMD pads on the back side of your keyboard to the through holes.

Looks like I missed a hotswap trace too. You can actually see this mistake in the 6th from the last screenshot in the routing section of this guide. Let's pretend I left it here as a learning example. Running DRC at the end of your routing process is vital for picking up small but critical mistakes like this.

Once you've finished correcting all the issues, run DRC one last time to verify that your PCB doesn't have any errors. Looks like we're good to go.

Surely we're done with our board now, right? Well... Let's take one last look at things. It seems fine, but humor me and select View -> 3D Viewer from the file menu.

Tada! Here's a render of our board in all its 3D glory. This view can be good for one last double check. You can make sure the layout of your footprints makes sense, and that there's not an unsightly silkscreen you hadn't noticed.

You can spin the board around with your mouse, but there's also a button on the navbar to quickly flip it over.

For an added bit of fun, you can click the Raytracing button in the top left corner and watch your system perform a ray-traced render of your board in real time.

Now we're done. That was quite the journey, but we're ready to send our PCB off to be fabricated.

Fabulous Fabs

KiCAD and other software generally use their own propriety file formats. While some PCB manufacturers will allow you to upload a KiCAD or EAGLE file, most prefer it you instead use "Gerber" files. Gerbers have been the common standard for plotting and drilling machines since time immemorial. They're plain text files that are conceptually similar to PDFs. The trick with Gerber files is that's it's Gerbers. Plural. Each layer of your PCB needs its own specific Gerber file. In practice this isn't too tricky. Each layer has a specific file name convention which KiCAD does for us automatically. All you have to do is point KiCAD at a folder and then zip the exports afterwards. Because nothing's every completely straightforward in KiCAD, there's also a separate "Drill" file you need to include in the zip. Thankfully these aren't hard to export either, but it is an extra step.

Once you've triple-checked everything on your PCB, head over to KiCAD's file menu. Hover over "Fabrication Outputs", and then select "Gerbers".

You should be able to stick with the default options here. The Included Layers section will show which layers of your PCB will get exported. F.Cu and B.Cu are your copper layers, F.Paste and B.Paste are used for creating SMD pads, F.Silkscreen and B.Silkscreen contains the text and icons that get printed on your board, F.Mask and B.Mask is the protective coating on non-exposed parts of your board, and Edge.Cuts is where the tool mills away the edge of your board.

The one change you should make on this screen is to specify an Output directory. By default KiCAD will dump your Gerbers in the same folder as your PCB file. Specifying ./keyboardname-gerbers will create a folder called keyboardname-gerbers in the same location as your PCB file, and then store all of your outputs there. Click "Plot", and KiCAD will create all the specified Gerber files.

One last step. Next to the "Plot" button, click "Generate Drill Files...". This opens up a "Generate Drill Files" modal. This one last step is needed to tell the machine where to physically drill our through hole pins. You can stick with all the defaults. The drill modal should have inherited your Output directory location from the previous screen. Click "Generate Drill File" and you should be good to go.

Forgetting to create a drill file is a very common step. If you get a message from your PCB fabricator that your upload appears to be missing it's drill file, it's because you forgot to do this last step. Don't worry, it happens to the best of us.

Finally, create a .zip file from your keyboard-gerbers folder. Your operating system's basic compression functionality should be fine.

At this point our PCB is ready to fabricate! That's the verb for creating a PCB by the way. The manufacturer of PCBs are known as "Fabricators", or Fabs for short. There's a few popular options out there. JLCPCB and PCBWay are the two large fabricators in China. JLCPCB is known for having competitive prices, particularly if you're making a PCB smaller than 100mm x 100mm. (Not super common for keyboards, but folks have pulled it off.) PCBWay is also another popular Chinese fab. Stateside, OSH Park has made a name for themselves with strikingly purple PCBs. They're a bit more expensive then their overseas counterparts, but they do have a faster turnaround time.

If you decide to create an account with JLCPCB, consider using this URL: https://jlcpcb.com/?from=ERGOGEN It doesn't provide any additional discounts currently, but it'll let JLCPCB know that Ergogen is sending folks their way. If you decide to go with PCBWay, you can use the coupon code ERGOGEN to get 5% off your order. I'm not affiliated with either of these codes, but am more than happy to pass on the Ergogen dev's promo codes.

Whichever fab you go with, the process of getting your PCB manufactured is pretty straightforward. Log into the site, upload your Gerbers (and drill) zip, and then click the buy button. Tutorial finished. Have a great day.

Okay, but seriously. The default options on these sites are fine. You want a 2 layer PCB, a board that's 1.6mm thick, and you can pick whichever color you'd like. There are additional options such as the surface finish that you can adjust for an additional cost, but for your first PCB, you don't need to tweak anything.

One thing worth noting here is that most PCB fabs require a minimum order size. Usually it's around 3-5 PCBs. For this particular example board, JLCPCB will manufacture 5 copies of our PCB for $18 USD, and shipping to the US will cost an additional $15 USD. That's not bad all things considered. Many off the shelf keyboard PCBs run in the $25-35 range. By fabricating your own PCBs, you get some spares in case you have a soldering mishap, or you can share the extras with friends. The manufacturing and shipping of your PCB will take about two weeks, which leaves you just enough time to buy the rest of the parts.

Part Picker

Ordering parts for a keyboard can feel like a balancing act at times. Prices will vary between vendors, but the more places you shop from, the more you'll end up paying in shipping fees.

For the keyboard we built, there's a few different parts we need. There's the pre-key components: The Choc switches, the keycaps, and the diodes. There's the microcontroller components: The Arduino Pro Micro, the headers, and the header pins. The OLED screen needs it's own set of pins and headers as well. Finally, there's the ancillary hardware such as the reset button. You'll also need a USB cable if you don't have one already.

Naturally the types of parts you need will vary based on what you're building. If you're making a split keyboard, you'll need a cable to connect the two halves and sockets for the cable to plug into. If you're making a wireless keyboard, you'll need batteries. Looking around at other people's keyboard designs and seeing which designs worked for them can help here.

When shopping around, there's a few different stores you can hit up. There's a surprising number of mechanical keyboard vendors out there these days. Companies like 42Keebs, Little Keyboards, and Boardsource are a good place to source keycaps and other keyboard-specific hardware. Electronics component supplies like DigiKey and Mouser are useful resources for picking up the occasional odd button or switch, although their website designs are not beginner friendly. It helps if you know the part number of what you're looking for, and you generally need to be able to read data sheets to double-check you've found the right component. Amazon is always an option as well, although you may not find the best deals there. It's not really worth it to list anything on the site for less than $7-10 USD, so rather than being able to buy a reset button, you may have to buy a bag of 100. Depending on what you need though, it can save you from needing to hit up yet another vendor. Finally, there's Aliexpress. This site is similar to a Chinese version of Amazon's seller marketplace. If you don't mind a two week lead time, you can get some good deals on Choc switches and hotswap sockets there. Your PCBs will take about that long to fab anyways.

After building your keyboard, you may have the realization that your USB cable isn't as spiffy and color coordinated as the ones you see on /r/mechanicalkeyboards. Welcome to your next rabbit hole. If you feel confident enough to solder your own USB cord, Zap Cables can get you the parts needed to make your own custom cable for under $20 USD.

Here's an example part list for our tutorial keyboard. These are also often referred to as a "Bill of Materials", or BOM. All told, you're going to be looking at about $200-300 USD depending on how fancy you want to get with your new keyboard. Hmm, maybe I should have lead with that in the introduction. Surprise? If this isn't your first rodeo, reusing keycaps or leveraging hot swap sockets can at least take some of the sting out.

Firmware Options

Now that all our parts are in the mail, it's time to start thinking about firmware options. DIY mechanical keyboards have a few different firmware options at this point depending on which type of microcontroller you end up using. Most wired Arduino Pro Micro and RP2040 based keyboards use the popular QMK firmware. Meanwhile, wireless keyboards leveraging the Nice!Nano microcontroller typically employ ZMK instead. There are some differences between the two firmwares, but they're both philosophically very similar.

QMK's documentation has a dedicated section for porting your keyboard to QMK. They also have some excellent additional background information on keyboard matrixes. Meanwhile, ZMK's documentation has their own guide for how to create a "shield" configuration for your keyboard. Both of these firmwares rely on you defining the pins used for your rows and columns, and then creating a configuration that outlines the physical arrangement of those keys. From there, you can start programming macros to your heart's content. Both of these firmwares also have support for additional hardware such as the OLED display we created a footprint for earlier. (Although you probably don't want to use an OLED screen on a wireless battery operated keyboard. There's some low power alternatives for those keyboards.)

The two firmwares have slightly different approaches when it comes to compiling your firmware. QMK has instructions on how to compile your new keyboard firmware locally on your computer, while ZMK has a process using GitHub Actions to streamline the compilation of your firmware.

Once you have your firmware compiled, you need to "flash" it onto your keyboard. To start the flashing process, you need to double tap the reset button on your keyboard or microcontroller to reboot the microcontroller into a flashing mode. After that, you need to send the firmware from your computer onto the microcontroller. For sending QMK to an Arduino Pro Micro, this relies on using lower-level commands to send the compiled firmware to the microcontroller. Thankfully the QMK Toolbox utility wraps these functions in a straightforward GUI. ZMK is a bit more straightforward. Double tapping the reset button will mount the Nice!Nano microcontroller as a storage device on your computer. You simply need to drag and drop your compiled firmware onto the microcontroller with your computer's file browser to kick off the flashing process.

Both of these firmwares are well documented with their own community Discords. I might do an article on writing your own QMK or ZMK configuration in the future, but for now their documentation and the row, column, and microcontroller pin background we went over in this guide should be enough to set you down the right path.

Assembling Your Team

Hopefully by the time you've got your first attempt at a custom firmware compiled your parts will have arrived. All that's left is to finally build your keyboard.

Keyboard designs can vary, but the actual act of building them is fairly universal. If this is your first rodeo, find a keyboard with similar functionality to your own and see if it has a build guide. Brian Low did an excellent job outlining the build process for the Sofle Choc for instance. The venerable Corne keyboard has variants for nearly every type of key switch and hotswap socket configuration, so it's also a useful resource for assembly tips. Finally, as much as I've enjoyed writing out this long-form text guide, YouTube does have a place when it comes to soldering tips.

In general, measure twice and solder once. Make sure your parts are oriented properly before you bond it to your PCB with liquid hot metal. You can solder a lot of these parts in any order, but starting with the per-switch components like diodes and hotswap sockets allow you to lay the board flat on your work surface for the first few steps.

You never want to look up nine months after a keyboard build and realize your microcontroller has somehow gone bad, so socket your microcontrollers. It adds a tiny bit onto the cost, but it's worth having the flexibility in the long run. If you get bit by the keyboard building bug, you can even move microcontrollers between keyboards and save yourself a bit of additional cost with each new build.

If you ask a friend to 3D print a case for you, buy them a six pack of their beverage of choice. If you're feeling particularly generous (or are having to iterate through multiple designs), you could even offer to buy your friend a $20 USD spool of 3D printer plastic. It's roughly the cost of mailing away for a piece, and you get to pick your case color rather than dipping into their available supply.

After building your keyboard and gathering the parts for the case, make sure to test your keyboard thoroughly before assembling the case. Enviably you'll notice one lose joint the second you've painstakingly socketed every part and screwed down every piece.

At this point, you should have a brand spanking new keyboard. Thanks for sticking it out through all five parts of this guide! Hopefully you picked up a thing or two!

A Brief Disclaimer

This guide was a fun excuse to learn Ergogen v4. If you'd like to look at any of the config files or outputs from this guide, they're uploaded on Github now. However, I've never actually built this example keyboard. The techniques and methodologies I used in this series are based off of the very similar ChonkV keyboard I made with Ergogen v3. Since they're so similar to one another, I haven't actually sent this particular tutorial PCB design off to get fabricated. There may be a short in the wiring somewhere, or the case may be slightly too snug, or the thumb keys may be brushing up against each other. If you were planning on dropping the Gerbers onto a PCB fab and ordering the parts, just be warned that this hasn't been fully tested in the real world just yet.

If you're not interested in learning Ergogen but like the idea of a Choc-spaced unibody keyboard similar to the Sofle, you're in luck! Josef Adamčík is working on the Stáňa unibody keyboard. It's a more polished, refined take on the style of keyboard that was featured here.

Conclusion

Congratulations, you now have a custom bespoke DIY keyboard unlike any other input device in the world! Happy typing! If you'd like to test your new WPM, MonkeyType is always a popular online typing test.

I sincerely hope you found this guide useful. The world of custom low profile ergonomic mechanical keyboards has been fun to explore, and I hope this series serves as a useful on ramp for those looking to get into the hobby. Even if I didn't cover exactly what you're looking to build here, you hopefully have a better sense of what to Google now. If you designed your own keyboard with this guide, we'd love to hear about it in the Ergogen Discord, or feel free to send me a picture of it on Mastodon! If you're feeling extra generous, I've got a Cash App tip jar over at $ItsAStu.

Welcome back! We're in the home stretch now. Well, home-ish stretch. If you need catching up: The series introduction introduced us to the world of Ergogen, Part 1 created the points that define out layout, and Part 2 created some useful outlines for our keyboard. In Part 3 we created the basis of our keyboard's PCB, defined the footprints for our parts, and connected them all together with nets. If you're familiar with KiCAD, you can probably run off and trace the routes on your own at this point. Slap some rubber feet on the bottom of the keyboard and call it a day!

In the interest of completeness however, I'd like to take a side trip over to the last few Ergogen topics I haven't touched on just yet. Chief among these is the "Cases" section. Ergogen has functionality to export outlines as 3D objects with a depth component. The web implementation of Ergogen doesn't support exporting these files just yet however, which gives us an excuse to dabble in the world of a locally installed, offline Ergogen.

Even if you don't own a 3D printer and aren't interested in creating a case for your keyboard, running a local copy of Ergogen allows you to import custom footprints from outside of the main Ergogen GitHub repository. This chapter will use that functionality to import a mounting hole footprint, but the same theory could apply to a different microcontroller, toggle switch, or rotary encoder. Part 4 still has something for everyone.

Update: Thanks to the updates Ceoloide has made to Ergogen, much of what Part 4 covered can now be performed in the ergogen.xyz web view. It now supports integrating external footprints, and has experimental support for KiCAD previews. Working with Ergogen locally can still be useful for certain workflows, so I'm keeping this part in the guide. Just know that if all you need to do is drop a single mounting hole footprint in, there's a much more straightforward approach these days.

Commanding the Line

Installing Ergogen locally on your computer is thankfully a fairly straightforward process. Ergogen is written in the popular cross-platform NodeJS scripting language. As the name implies, Node leverages the Javascript, making it easily adaptable to Windows machines, Mac laptops, or Linux setups. As we saw earlier, it's also what makes it easy to create a web implementation for Ergogen.

Node install instructions vary over time and by platform. Your best guess is to mosey on over to NodeJS.org and follow their instructions there. If you're on a Mac or Linux system, you may also want to look into the Node Version Manager application if you haven't already. nvm can save you some versioning headaches in the long run if you start using Node more regularly.

Installing Node nets you more than just the scripting environment. You also get the Node Package Manager. Rather than having to fiddle with a bunch of application files and install scripts, npm lets you easily download and install Node packages from npmjs.com. These packages can be installed in one or two ways: Locally or Globally.

A local package install works like most software. It creates a folder in a specified location on your hard drive, and to use that package you need to navigate to that folder. This is useful for programs that have very isolated contexts, or apps that you may install multiple instances of.

In Ergogen's case, we don't want a single isolated instance of the tool. We want to be able to run it inside of any of our future keyboard project folders like a standard command line utility. This means we should perform a global install for Ergogen. This installs Ergogen to a Node system folder, and allows us to call the utility from anywhere on the command line.

Enough command line background, let's get to it! Assuming your NodeJS install is up and running, open a command line and run:

npm i -g ergogen

npm calls the Node Package Manager, i is short for install, -g is the global flag, and ergogen is the name of the package we want to install. Easy peasy.

Now that we've got Ergogen installed, go ahead and do whatever it is you usually do when starting a new coding project. In my case, I'm creating a new folder inside of ~/pcb on my system called /tutorial. This is where my Ergogen config will live, and where all the outputs will be placed. I'm also running a quick git init to create a local git repository in case I accidentally screw something up and want to roll back to an earlier state. Finally, create a file called config.yaml inside of your project folder and copy the contents of your ergogen.xyz config into it.

Now's the moment of truth. Let's run Ergogen!

ergogen config.yaml

ergogen is the name of our command, and config.yaml is the name of your config file. If everything goes smoothly, Ergogen will create an outputs folder and put our finished files inside of it. If you'd like to use an outputs folder with a different name, you can use the -o output_folder_name option to specify your own.

With that, we should be back to where we were with the web UI. We've got all of our .dxf outline files, as well as the .kicad_pcb file.

So far running things locally hasn't gotten us anything astounding yet. The web UI is useful for generating points and outlines, while the local instance can make constantly reloading new KiCAD files a bit easier. There are a few tricks up the local install's sleeve however. Let's first take a look at loading external footprints.

Expanding The Footprint Clan

Ergogen comes with a useful assortment of component footprints. At some point however you'll most likely want to add something a bit custom to your keyboard. In the old Ergogen v3 era you would need to fork Ergogen, add your additional footprints, and then run your new custom fork locally.

Thankfully in Ergogen v4, there's now a dedicated method for referencing external footprints. As of the time of writing this guide, this technique only works on local instances of Ergogen. The code's already there to handle bundled .zip footprint collections however, so it's only a matter of time until the web instance gets updated as well.

For this external footprint example, I'm going to use MvEerd's M2 mounting hole footprint. Creating your own custom footprint is a bit outside of the scope of this tutorial, but they're written in fairly straightforward javascript files. If you need to make a small tweak to an existing footprint, it shouldn't be too difficult to fumble your way through it. There are a lot of community footprints at this point, so poke around Github to see what else is out there, or hit up the Ergogen Discord.

Go ahead and download the M2 mounting hole footprint. ("M2" is metric shorthand for a screw with a 2mm diameter.) If you haven't downloaded individual files from GitHub before, you'll need to right click on the Raw button and download it to your computer. Make sure it keeps the mountinghole.js name. Some browsers like adding .txt onto the end of .js.

Create a new folder inside of your project folder called footprints. Place mountinghole.js inside of it.

This screenshot shows the current structure of our project file. There's a few things to note here when working with external footprints. Ergogen has historically allowed you to use any file name for your .yaml config. If you named your config tutorial.yaml, all you would need to do is call ergogen tutorial.yaml for Ergogen to parse the file.

That's not the case here. When working with external footprints, it's required that you use the filename config.yaml for your Ergogen config. Secondly, we need to change how we call Ergogen. Instead of the usual ergogen config.yaml command, we need to pass our entire folder to Ergogen.

This can be accomplished easily enough. But first, let's add an example mounting hole to our config.yaml file.

units: ...
points: ...
outlines: ...
pcbs:
  tutorial:
    outlines:
      main:
        outline:
          board
    footprints:
      choc_hotswap: ...
      diode: ...
      promicro: ...
      oled: ...
      reset: ...
      holeTopLeft:
        what: mountinghole
        where:
          ref: [matrix_outer_num]

This should be pretty standard at this point. holeTopLeft: is the name of our footprint. what: mountinghole indicates that we'd like to use mountinghole.js for the footprint. where.ref: [matrix_outer_num] places the footprint smack dab in the middle of the top left key.

The trick here is that mountinghole.js isn't in the Ergogen GitHub repository. It's part of our local project folder. Thankfully we don't need to use any special syntax as long as we place the footprint files in the correct location. Without further ado, let's fire up Ergogen and provide it with our project folder.

ergogen .

That's a bit of an anticlimax. On command lines, a single dot is shorthand for "the current folder that I'm in. By calling Ergogen this way, we're telling it that it needs to look at both the config.yaml file and all of the .js files inside of the ./footprints folder.

There's our mounting hole! You need to make sure all your ducks are in a row, but working with external footprints is a huge step up in Ergogen v4. I cannot stress enough that you need to call Ergogen with ergogen . instead of ergogen config.yaml

There's a ton of examples and documentation online for v3 with the config file explicitly called out. Don't get tripped up!

Mounting Holes

Mounting holes are a convenient way of attaching a case to a PCB. Our custom footprint is honestly a bit overkill. We could have just created a few circle outlines and drilled them out of our PCB as edge cuts. (You'll see this from time to time if you go poking around Github.) But now that we've got a properly drilled mounting hole, let's go ahead and add a few more.

units: ...
points: ...
outlines: ...
pcbs:
  tutorial:
    outlines:
      main:
        outline:
          board
    footprints:
      choc_hotswap: ...
      diode: ...
      promicro: ...
      oled: ...
      reset: ...
      holeTopLeft:
        what: mountinghole
        where:
          ref: [matrix_outer_num]
      holeTopInnerLeft:
        what: mountinghole
        where:
          ref: [matrix_index_num]
      holeBottomInnerLeft:
        what: mountinghole
        where:
          ref: [matrix_index_mod]
      holeTopRight:
        what: mountinghole
        where:
          ref: [mirror_matrix_outer_num]
      holeBottomRight:
        what: mountinghole
        where:
          ref: [mirror_matrix_outer_bottom]
      holeTopInnerRight:
        what: mountinghole
        where:
          ref: [mirror_matrix_index_num]
      holeBottomInnerRight:
        what: mountinghole
        where:
          ref: [mirror_matrix_index_mod]

Things are looking good so far, but we've got the classic issue of having placed out footprints directly inside of one of our key switches. Let's add some shifts to move these mounting holes over.

units: ...
points: ...
outlines: ...
pcbs:
  tutorial:
    outlines:
      main:
        outline:
          board
    footprints:
      choc_hotswap: ...
      diode: ...
      promicro: ...
      oled: ...
      reset: ...
      holeTopLeft:
        what: mountinghole
        where:
          ref: [matrix_outer_num]
          shift: [0.5kx, -0.3ky]
      holeBottomLeft:
        what: mountinghole
        where:
          ref: [matrix_outer_bottom]
          shift: [0.5kx, -0.3ky]
      holeTopInnerLeft:
        what: mountinghole
        where:
          ref: [matrix_index_num]
          shift: [0.5kx, -0.4ky]
      holeBottomInnerLeft:
        what: mountinghole
        where:
          ref: [matrix_index_mod]
          shift: [0.5kx, -0.35ky]
      holeTopRight:
        what: mountinghole
        where:
          ref: [mirror_matrix_outer_num]
          shift: [0.5kx, -0.3ky]
      holeBottomRight:
        what: mountinghole
        where:
          ref: [mirror_matrix_outer_bottom]
          shift: [0.5kx, -0.3ky]
      holeTopInnerRight:
        what: mountinghole
        where:
          ref: [mirror_matrix_index_num]
          shift: [0.5kx, -0.4ky]
      holeBottomInnerRight:
        what: mountinghole
        where:
          ref: [mirror_matrix_index_mod]
          shift: [0.5kx, -0.35ky]

There we go! Our mounting holes have been nudged over between the keys, and shifted down slightly so that they're tucked away between the diodes. This design might be a little tight if you're using through hole diodes, but it should work fine for smd diodes.

That wraps up our last big change to the PCB. The important thing to note here is that we can use these same where: values when constructing our PCB to know exactly where each of these mounting holes go.

Making A Case

3D printing is an art form of its own. People familiar with CAD tools most likely have some idea of the type of case they'd like to design. This section isn't going to be an exhaustive treatise on keyboard case design. We're going to quickly slap something together in Ergogen to cover the bottom of our keyboard and give it a bit of color.

Let's define a simple 3D model now.

units: ...
points: ...
outlines:
  raw: ...
  keys: ...
  board: ...
  combo: ...
pcbs: ...
cases:
  bottom:
    - name: board
      extrude: 1

After everything we just went through with the PCB, cases are surprisingly straightforward. The cases: section is similar to the outlines: section of our Ergogen config file. Instead of creating flat .dxf files, it creates 3D files with depth.

The bottom: entry is a name we gave this particular 3D model. - name: board refers to the outline we defined earlier. Finally, extrude: 1 tells Ergogen to create a 3D model that is 1mm tall.

Ergogen v3 previously exported cases files in the .stl lingua franca format of 3D printing. Due to some technical issues with the .stl file creation library, Ergogen v4 exports cases as .jscad files. If you'd like to convert these into .stl files, you can use sites like openjscad.xyz or their NPM package. We're already working on the command line, so let's leverage their command line package.

npx @jscad/cli@1 output/cases/bottom.jscad -of stla -o bottom.stl

This line uses the Node Package Manager's npx command to run JSCAD as an executable. It's a whole topic worth looking into on its own, but the short story is that the above command will convert a .jscad into an .stl files for us.

If we want to run both Ergogen and JSCAD with one terminal command, we can string them together with:

ergogen . && npx @jscad/cli@1 output/cases/bottom.jscad -of stla

This will only match the one part name of bottom.jscad however. If we'd like to get real fancy, the following command will process your Ergogen files and then convert every .jscad file in your outputs folder. Sometimes it's hard to beat a good old fashioned for loop. (The output name is implicitly understood to be the same as the input name here.)

ergogen . && for i in output/cases/*.jscad; do npx @jscad/cli@1 "$i" -of stla; done

After all that, we've got a 1mm thick version of our bottom outline. Hurray?

Let's see if we can add some walls to our case design. First up, we need an outline of our board that's a few mm larger than the actual PCB design.

units:
  # Proxy Spacing Variables
  kx: cx
  ky: cy
  # Padding Variables
  px: kx + 4
  py: ky + 4
  # Double Padding Variables
  dpx: kx + 8
  dpy: ky + 8
points: ...
outlines:
  raw: ...
  keys: ...
  board: ...
  xlBoard:
    - what: polygon
      operation: stack
      points:
        - ref: matrix_outer_num
          shift: [-0.5dpx,0.5dpy]
        - ref: matrix_ring_num
          shift: [-0.5dpx,0.5dpy]
        - ref: matrix_middle_num
          shift: [-0.5dpx,0.5dpy]
        - ref: matrix_middle_num
          shift: [0.5dpx,0.5dpy]
        - ref: matrix_inner_num
          shift: [0.5dpx,0.5dpy]
        - ref: matrix_inner_top
          shift: [0.5dpx,0.5dpy]
        - ref: mirror_matrix_inner_top
          shift: [0.5dpx,0.5dpy]
        - ref: mirror_matrix_inner_num
          shift: [0.5dpx,0.5dpy]
        - ref: mirror_matrix_middle_num
          shift: [0.5dpx,0.5dpy]
        - ref: mirror_matrix_middle_num
          shift: [-0.5dpx,0.5dpy]
        - ref: mirror_matrix_ring_num
          shift: [-0.5dpx,0.5dpy]
        - ref: mirror_matrix_outer_num
          shift: [-0.5dpx,0.5dpy]
        - ref: mirror_matrix_outer_bottom
          shift: [-0.5dpx,-0.5dpy]
        - ref: mirror_matrix_ring_mod
          shift: [-0.5dpx,-0.5dpy]
        - ref: mirror_thumbs_layer_cluster
          shift: [-0.5dpx,-0.5dpy]
        - ref: mirror_thumbs_space_cluster
          shift: [-0.5dpy,-0.5dpx]
        - ref: mirror_thumbs_space_cluster
          shift: [0.5dpy,-0.5dpx]
        - ref: thumbs_space_cluster
          shift: [0.5dpy,-0.5dpx]
        - ref: thumbs_space_cluster
          shift: [-0.5dpy,-0.5dpx]
        - ref: thumbs_layer_cluster
          shift: [-0.5dpx,-0.5dpy]
        - ref: matrix_ring_mod
          shift: [-0.5dpx,-0.5dpy]
        - ref: matrix_outer_bottom
          shift: [-0.5dpx,-0.5dpy]
      fillet: 2
    combo: ...
pcbs: ...
cases:
  bottom:
    - name: board
      extrude: 1
  xlBottom:
    - name: xlBoard
      extrude: 1

Our good buddy units is back! Our original board outline used the px and py padding variables to make a board that was 2mm wider than it absolutely needed to be. dpx and dpy are adding another 2px onto the outside of our new xlBoard outline. Just as before we were able to create a 1mm case file called xlBottom.

...okay. So we have a slightly bigger bottom board. Does that get us anything? Well, cases can be added and subtracted to just like we did with the combo outline in Part 2. If we subtracted board from xlBoard, we'd start getting something that resembles a wall.

cases:
  bottom:
    - name: board
      extrude: 1
  xlBottom:
    - name: xlBoard
      extrude: 1
  _outerWall:
    - name: xlBoard
      extrude: 4
  _innerWall:
    - name: board
      extrude: 4
  wall:
    - what: case
      name: _outerWall
      operation: add
    - what: case
      name: _innerWall
      operation: subtract

Now that's starting to look like a case! We even got to introduce a bit more syntactic flare to our config. Prefixing an outline or case with an underscore will signal to Ergogen that it doesn't need to export a particular asset to our outputs files. It can still be referenced by other cases however, which is exactly what we did here.

_outerWall and _innerWall were 4mm repeats of what we've seen before. wall is a bit new however. Instead of creating a new case object, we combined two together. The what: property defaults to an outline when working with cases, so we had to be explicit here that we wanted to refer to one of our earlier case files. name: tells Ergogen which case files we'd like to reference. operation: meanwhile tells Ergogen what we'd like to do to those particular case file. add is the default implicit option, but in this case we wanted to use operation: subtract to remove the inner option of our larger outline.

cases:
  bottom:
    - name: board
      extrude: 1
  xlBottom:
    - name: xlBoard
      extrude: 1
  _outerWall:
    - name: xlBoard
      extrude: 4
  _innerWall:
    - name: board
      extrude: 4
  wall:
    - what: case
      name: _outerWall
      operation: add
    - what: case
      name: _innerWall
      operation: subtract
  case:
    - what: case
      name: xlBottom
      operation: add
    - what: case
      name: wall
      operation: add

One more quick addition, and now we've got a nice stable base with some sturdy looking walls. This case piece should make a good basis for the rest of our build. Now we just need to address those mounting holes.

units:
  # Proxy Spacing Variables
  kx: cx
  ky: cy
  # Padding Variables
  px: kx + 4
  py: ky + 4
  # Double Padding Variables
  dpx: kx + 8
  dpy: ky + 8
  # Defaults to M2 Screws
  screwSize: 1
points: ...
outlines:
  raw: ...
  keys: ...
  board: ...
  xlBoard: ...
  combo: ...
  mounting:
    - what: circle
      radius: screwSize
      where:
        ref: [matrix_outer_num]
        shift: [0.5kx, -0.3ky]
    - what: circle
      radius: screwSize
      where:
        ref: [matrix_outer_bottom]
        shift: [0.5kx, -0.3ky]
    - what: circle
      radius: screwSize
      where:
        ref: [matrix_index_num]
        shift: [0.5kx, -0.4ky]
    - what: circle
      radius: screwSize
      where:
        ref: [matrix_index_mod]
        shift: [0.5kx, -0.35ky]
    - what: circle
      radius: screwSize
      where:
        ref: [mirror_matrix_outer_num]
        shift: [0.5kx, -0.3ky]
    - what: circle
      radius: screwSize
      where:
        ref: [mirror_matrix_outer_bottom]
        shift: [0.5kx, -0.3ky]
    - what: circle
      radius: screwSize
      where:
        ref: [mirror_matrix_index_num]
        shift: [0.5kx, -0.4ky]
    - what: circle
      radius: screwSize
      where:
        ref: [mirror_matrix_index_mod]
        shift: [0.5kx, -0.35ky]
pcbs: ...
cases:
  bottom: ...
  xlBottom: ...
  _outerWall: ...
  _innerWall: ...
  wall: ...
  _holes:
    - name: mounting
      extrude: 4
  case:
    - what: case
      name: xlBottom
      operation: add
    - what: case
      name: _holes
      operation: add
    - what: case
      name: wall
      operation: add

Another giant code block, but most of this should start to look a little familiar. To start with I added a new unit called screwSize: 1 to use as the radius of our screws. I then created a new outline called mounting: which reused the where.ref: and where.shift: values from our mounting holes on the PCB. (This mounting outline is a good example of including multiple shapes within a single outline by the way.) Finally, I created a new case called _holes and added it to our final case part.

You could keep going with this approach and create a basic plastic standoff design to slot onto the PCB, but we can get a much sturdier design by introducing a few extra pieces of hardware.

Threaded screw inserts are small pieces of metal with a screw hole in the middle. They're designed to let you add a sturdy mounting point on wooden or plastic components. They're 3.2mm wide, and 3mm tall. All you need to do to add them to your design is create a hole that's 3mm in diameter and 3mm tall. Then you use a soldering iron to warm up the screw insert and melt the last 0.2mm of plastic. Once they're in place, you just need a standard M2 laptop-style flathead screw to hold the keyboard in place.

To add support for these threaded screw inserts to our design, we need to define a second set of slightly larger mounting holes, and then subtract the inner holes from the outside holes like we did for the wall part. The outer walls will be 5mm thick, with a 3mm hollow inside.

Incidentally, these threaded screw inserts are why I had been using 4mm for some of the heights in the case section. 1mm for the base of the case plus 3mm for the standoff height is 4mm. You could get a little thinner without the standoffs, but the hotswap sockets are already 2mm thick. This design is only making the case 2mm thicker than the bare PCB itself.

Double-checking all the number just now made me realize I had undershot the wall height. The walls currently come up to the bottom of the PCB, but I want it to be flush with the top. We need to add the 1.6mm height of the PCB to the walls. Let's build our threaded screw insert standoffs and fix those heights.

units:
  # Proxy Spacing Variables
  kx: cx
  ky: cy
  # Padding Variables
  px: kx + 4
  py: ky + 4
  # Double Padding Variables
  dpx: kx + 8
  dpy: ky + 8
  # M2 Screw Inserts
  screwSize: 1.5
  standoffSize: 2.5
points: ...
outlines:
  raw: ...
  keys: ...
  board: ...
  xlBoard: ...
  combo: ...
  mounting
  standoff:
    - what: circle
      radius: standoffSize
      where:
        ref: [matrix_outer_num]
        shift: [0.5kx, -0.3ky]
    - what: circle
      radius: standoffSize
      where:
        ref: [matrix_outer_bottom]
        shift: [0.5kx, -0.3ky]
    - what: circle
      radius: standoffSize
      where:
        ref: [matrix_index_num]
        shift: [0.5kx, -0.4ky]
    - what: circle
      radius: standoffSize
      where:
        ref: [matrix_index_mod]
        shift: [0.5kx, -0.35ky]
    - what: circle
      radius: standoffSize
      where:
        ref: [mirror_matrix_outer_num]
        shift: [0.5kx, -0.3ky]
    - what: circle
      radius: standoffSize
      where:
        ref: [mirror_matrix_outer_bottom]
        shift: [0.5kx, -0.3ky]
    - what: circle
      radius: standoffSize
      where:
        ref: [mirror_matrix_index_num]
        shift: [0.5kx, -0.4ky]
    - what: circle
      radius: standoffSize
      where:
        ref: [mirror_matrix_index_mod]
        shift: [0.5kx, -0.35ky]
pcbs: ...
cases:
  bottom: ...
  xlBottom: ...
  _outerWall:
    - name: xlBoard
      extrude: 5.6
  _innerWall:
    - name: board
      extrude: 5.6
  wall: ...
  _holes:
    - name: mounting
      extrude: 4
  _standoffs:
    - name: standoff
      extrude: 4
  case:
    - what: case
      name: _standoffs
      operation: add
    - what: case
      name: _holes
      operation: subtract
    - what: case
      name: xlBottom
      operation: add
    - what: case
      name: wall
      operation: add

The threaded screw insert standoffs are looking great! With that, our case is finished! We've got slightly more than a minimum viable case without ever having to leave Ergogen.

If you've got something a bit more complicated in mind, it may be worth pivoting to CAD software at some point. There are beginner friendly options like Autodesk's TinkerCAD software, or more high end suites like Autodesk Fusion 360 for creating impressive beveled edges. Even if your end product isn't created from Ergogen alone, the .dxf and .stl files generated by it provide great starting points. For a more focused guide on keyboard case design theory, check out Sadek Baroudi excellent KBD News article on the topic.

It's worth noting that if you're building a unibody keyboard like the one we designed in this tutorial, there's a good chance your keyboard will be larger than your 3D printer's print area. This case design is 273mm wide, while my printer bed is only 200mm wide. You'll probably need to split your case into at least two pieces. Each half of this design has four well-spaced standoffs, so we should be fine here.

End of Part 4

units:
  # Proxy Spacing Variables
  kx: cx
  ky: cy
  # Padding Variables
  px: kx + 4
  py: ky + 4
  # Double Padding Variables
  dpx: kx + 8
  dpy: ky + 8
  # Defaults to M2 Screws
  screwSize: 1.5
  standoffSize: 2.5
points:
  zones:
    # The primary 6x4 key matrix, plus 3 modifiers.
    matrix:
      # Position in center of KiCAD workspace.
      anchor:
        shift: [100, -100]
      # Choc spacing
      key:
        padding: 1ky
        spread: 1kx
      columns:
        # Hide the first two mods and the last mod.
        # Provide a Sofle-like column stagger.
        outer:
          rows.mod.skip: true
          key.column_net: P14
        pinky:
          rows.mod.skip: true
          key.column_net: P16
        ring:
          key:
            stagger: 5
            column_net: P10
          rows.mod.column_net: P16
        middle:
          key:
            stagger: 2.5
            column_net: P7
          rows.mod.column_net: P10
        index:
          key:
            stagger: -2.5
            column_net: P8
          rows.mod.column_net: P7
        inner:
          rows.mod.skip: true
          key:
            stagger: -2.5
            column_net: P9
      rows:
        # Four main rows, one partial row.
        mod:
          row_net: P15
          mirror.row_net: P6
        bottom:
          row_net: P18
          mirror.row_net: P5
        home:
          row_net: P19
          mirror.row_net: P4
        top:
          row_net: P20
          mirror.row_net: P0
        num:
          row_net: P21
          mirror.row_net: P1
    # Thumb cluster for Layer and Space keys.
    thumbs:
      # Choc spacing
      key:
        padding: 1ky
        spread: 1kx
      # Place thumbs where the inner mod would go.
      anchor:
        ref: matrix_inner_mod
        shift: [2, -2]
      columns:
        # Fan thumbs out by -15 degrees.
        layer:
          key:
            splay: -15
            column_net: P8
        # Spacebar uses a 1.5 wide key.
        space:
          key:
            width: 1.5kx
            splay: 75
            shift: [2.5,-3.25]
            column_net: P9
      rows:
        # Thumbs only have one row.
        cluster:
          row_net: P15
          mirror.row_net: P6
  # Mirror keyboard halves with a moderate rotation.
  rotate: -20
  mirror: &mirror
    ref: matrix_inner_num
    distance: 2kx
outlines:
  # Pure key outline.
  raw:
    - what: rectangle
      where: true
      size: [px, py]
  # Key outlines with 0.5mm removed to show key overlaps.
  keys:
    - what: rectangle
      where: true
      size: [kx-0.5,ky-0.5]
  # PCB board outline.
  board:
    - what: polygon
      operation: stack
      points:
        - ref: matrix_outer_num
          shift: [-0.5px,0.5py]
        - ref: matrix_ring_num
          shift: [-0.5px,0.5py]
        - ref: matrix_middle_num
          shift: [-0.5px,0.5py]
        - ref: matrix_middle_num
          shift: [0.5px,0.5py]
        - ref: matrix_inner_num
          shift: [0.5px,0.5py]
        - ref: matrix_inner_top
          shift: [0.5px,0.5py]
        - ref: mirror_matrix_inner_top
          shift: [0.5px,0.5py]
        - ref: mirror_matrix_inner_num
          shift: [0.5px,0.5py]
        - ref: mirror_matrix_middle_num
          shift: [0.5px,0.5py]
        - ref: mirror_matrix_middle_num
          shift: [-0.5px,0.5py]
        - ref: mirror_matrix_ring_num
          shift: [-0.5px,0.5py]
        - ref: mirror_matrix_outer_num
          shift: [-0.5px,0.5py]
        - ref: mirror_matrix_outer_bottom
          shift: [-0.5px,-0.5py]
        - ref: mirror_matrix_ring_mod
          shift: [-0.5px,-0.5py]
        - ref: mirror_thumbs_layer_cluster
          shift: [-0.5px,-0.5py]
        - ref: mirror_thumbs_space_cluster
          shift: [-0.5py,-0.5px]
        - ref: mirror_thumbs_space_cluster
          shift: [0.5py,-0.5px]
        - ref: thumbs_space_cluster
          shift: [0.5py,-0.5px]
        - ref: thumbs_space_cluster
          shift: [-0.5py,-0.5px]
        - ref: thumbs_layer_cluster
          shift: [-0.5px,-0.5py]
        - ref: matrix_ring_mod
          shift: [-0.5px,-0.5py]
        - ref: matrix_outer_bottom
          shift: [-0.5px,-0.5py]
      fillet: 2
  # Extra Large PCB board outline.
  xlBoard:
    - what: polygon
      operation: stack
      points:
        - ref: matrix_outer_num
          shift: [-0.5dpx,0.5dpy]
        - ref: matrix_ring_num
          shift: [-0.5dpx,0.5dpy]
        - ref: matrix_middle_num
          shift: [-0.5dpx,0.5dpy]
        - ref: matrix_middle_num
          shift: [0.5dpx,0.5dpy]
        - ref: matrix_inner_num
          shift: [0.5dpx,0.5dpy]
        - ref: matrix_inner_top
          shift: [0.5dpx,0.5dpy]
        - ref: mirror_matrix_inner_top
          shift: [0.5dpx,0.5dpy]
        - ref: mirror_matrix_inner_num
          shift: [0.5dpx,0.5dpy]
        - ref: mirror_matrix_middle_num
          shift: [0.5dpx,0.5dpy]
        - ref: mirror_matrix_middle_num
          shift: [-0.5dpx,0.5dpy]
        - ref: mirror_matrix_ring_num
          shift: [-0.5dpx,0.5dpy]
        - ref: mirror_matrix_outer_num
          shift: [-0.5dpx,0.5dpy]
        - ref: mirror_matrix_outer_bottom
          shift: [-0.5dpx,-0.5dpy]
        - ref: mirror_matrix_ring_mod
          shift: [-0.5dpx,-0.5dpy]
        - ref: mirror_thumbs_layer_cluster
          shift: [-0.5dpx,-0.5dpy]
        - ref: mirror_thumbs_space_cluster
          shift: [-0.5dpy,-0.5dpx]
        - ref: mirror_thumbs_space_cluster
          shift: [0.5dpy,-0.5dpx]
        - ref: thumbs_space_cluster
          shift: [0.5dpy,-0.5dpx]
        - ref: thumbs_space_cluster
          shift: [-0.5dpy,-0.5dpx]
        - ref: thumbs_layer_cluster
          shift: [-0.5dpx,-0.5dpy]
        - ref: matrix_ring_mod
          shift: [-0.5dpx,-0.5dpy]
        - ref: matrix_outer_bottom
          shift: [-0.5dpx,-0.5dpy]
      fillet: 2
  # Combination preview showing outline and keys.
  combo:
    - name: board
    - operation: subtract
      name: keys
  mounting:
    - what: circle
      radius: screwSize
      where:
        ref: [matrix_outer_num]
        shift: [0.5kx, -0.3ky]
    - what: circle
      radius: screwSize
      where:
        ref: [matrix_outer_bottom]
        shift: [0.5kx, -0.3ky]
    - what: circle
      radius: screwSize
      where:
        ref: [matrix_index_num]
        shift: [0.5kx, -0.4ky]
    - what: circle
      radius: screwSize
      where:
        ref: [matrix_index_mod]
        shift: [0.5kx, -0.35ky]
    - what: circle
      radius: screwSize
      where:
        ref: [mirror_matrix_outer_num]
        shift: [0.5kx, -0.3ky]
    - what: circle
      radius: screwSize
      where:
        ref: [mirror_matrix_outer_bottom]
        shift: [0.5kx, -0.3ky]
    - what: circle
      radius: screwSize
      where:
        ref: [mirror_matrix_index_num]
        shift: [0.5kx, -0.4ky]
    - what: circle
      radius: screwSize
      where:
        ref: [mirror_matrix_index_mod]
        shift: [0.5kx, -0.35ky]
  standoff:
    - what: circle
      radius: standoffSize
      where:
        ref: [matrix_outer_num]
        shift: [0.5kx, -0.3ky]
    - what: circle
      radius: standoffSize
      where:
        ref: [matrix_outer_bottom]
        shift: [0.5kx, -0.3ky]
    - what: circle
      radius: standoffSize
      where:
        ref: [matrix_index_num]
        shift: [0.5kx, -0.4ky]
    - what: circle
      radius: standoffSize
      where:
        ref: [matrix_index_mod]
        shift: [0.5kx, -0.35ky]
    - what: circle
      radius: standoffSize
      where:
        ref: [mirror_matrix_outer_num]
        shift: [0.5kx, -0.3ky]
    - what: circle
      radius: standoffSize
      where:
        ref: [mirror_matrix_outer_bottom]
        shift: [0.5kx, -0.3ky]
    - what: circle
      radius: standoffSize
      where:
        ref: [mirror_matrix_index_num]
        shift: [0.5kx, -0.4ky]
    - what: circle
      radius: standoffSize
      where:
        ref: [mirror_matrix_index_mod]
        shift: [0.5kx, -0.35ky]
pcbs:
  tutorial:
    outlines:
      main:
        outline:
          board
    footprints:
      # Hotswap Choc keys.
      choc_hotswap:
        what: choc
        where: true
        params:
          keycaps: true
          reverse: false
          hotswap: true
          from: "{{column_net}}"
          to: "{{colrow}}"
      # Through Hole or SMD Diodes
      diode:
        what: diode
        where: true
        params:
          from: "{{colrow}}"
          to: "{{row_net}}"
        adjust:
          shift: [0, -5]
      # Face Down Arduino Pro Micro
      promicro:
        what: promicro
        params:
          orientation: "down"
        where:
          ref.aggregate.parts: [matrix_inner_home, mirror_matrix_inner_home]
          shift: [0,0]
          rotate: -90
      # OLED Screen
      oled:
        what: oled
        params:
          side: "F"
          SDA: P2
          SCL: P3
        where:
          ref.aggregate.parts: [matrix_inner_home, mirror_matrix_inner_home]
          shift: [-6,-19]
          rotate: 90
      # Four Pin Reset Button
      reset:
        what: button
        params:
          from: GND
          to: RST
        where:
          ref.aggregate.parts: [matrix_index_mod, mirror_matrix_index_mod]
          shift: [0, -1]
          rotate: -90
      # Mounting Holes
      holeTopLeft:
        what: mountinghole
        where:
          ref: [matrix_outer_num]
          shift: [0.5kx, -0.3ky]
      holeBottomLeft:
        what: mountinghole
        where:
          ref: [matrix_outer_bottom]
          shift: [0.5kx, -0.3ky]
      holeTopInnerLeft:
        what: mountinghole
        where:
          ref: [matrix_index_num]
          shift: [0.5kx, -0.4ky]
      holeBottomInnerLeft:
        what: mountinghole
        where:
          ref: [matrix_index_mod]
          shift: [0.5kx, -0.35ky]
      holeTopRight:
        what: mountinghole
        where:
          ref: [mirror_matrix_outer_num]
          shift: [0.5kx, -0.3ky]
      holeBottomRight:
        what: mountinghole
        where:
          ref: [mirror_matrix_outer_bottom]
          shift: [0.5kx, -0.3ky]
      holeTopInnerRight:
        what: mountinghole
        where:
          ref: [mirror_matrix_index_num]
          shift: [0.5kx, -0.4ky]
      holeBottomInnerRight:
        what: mountinghole
        where:
          ref: [mirror_matrix_index_mod]
          shift: [0.5kx, -0.35ky]
cases:
  bottom:
    - name: board
      extrude: 1
  xlBottom:
    - name: xlBoard
      extrude: 1
  _outerWall:
    - name: xlBoard
      extrude: 5.6
  _innerWall:
    - name: board
      extrude: 5.6
  wall:
    - what: case
      name: _outerWall
      operation: add
    - what: case
      name: _innerWall
      operation: subtract
  _holes:
    - name: mounting
      extrude: 4
  _standoffs:
    - name: standoff
      extrude: 4
  case:
    - what: case
      name: _standoffs
      operation: add
    - what: case
      name: _holes
      operation: subtract
    - what: case
      name: xlBottom
      operation: add
    - what: case
      name: wall
      operation: add

That's it for Part 4! We configured Ergogen to run locally on the command line, imported some custom external footprints, and created a basic case file. Not bad for less than 500 lines of configuration.

With that, we're also done with Ergogen in general. We've walked through all four of the main sections of an Ergogen config, and have created an unrouted PCB and case file for our new keyboard. For the final chapter, I'll give a brief overview of the non-Ergogen steps required to build a custom keyboard. We need to route our PCB, export the circuit board files to a PCB fab, create a firmware for the keyboard, and actually build the dang thing. Time to wrap this up with Let's Design A Keyboard With Ergogen v4: KiCAD, Firmwares, & Assembly (Finale)!

Congratulations, you've made it to Part 3! If you've been following along with this series so far, you should have an Ergogen config file with defined units, a keyboard layout specified by points, and a board shape created from an outline. If you're just joining us and this all sounds like gibberish, feel free to hop back to the introduction.

Before we dive straight into discussing how to design a PCB, we need to have a brief side discussion about microcontrollers and keyboard matrixes. I promise I'll try to keep this short.

What's a Microcontroller?

It's a controller but... micro?

Okay, in all seriousness, a microcontroller is a small reprogrammable chip designed to work in embedded applications. It differentiates itself from more powerful computing devices by generally lacking a traditional operating system. Microcontrollers get flashed with a single program, and will run that script every time it powers up until you flash it with a new program. Microcontrollers also generally have hardware designed to interact with low level hardware components. Instead of focusing on powering a single screen and running a variety of apps, microcontrollers can power LEDs, read sensor states, and drive small motors.

The most popular and hobbyist friendly microcontroller platform has been the Arduino family of boards. Custom mechanical keyboards have been leveraging the Arduino Pro Micro for years now, although different variant boards also exist. Microcontrollers like the Elite-C have Arduino compatibility while offering slightly different hardware capabilities. More recently, Seedsudio's XIAO line of boards and the Raspberry Pi foundation's RP2040 boards have also made inroads into the mechanical keyboard scene.

No matter which board you're working with, they all tend to behave in the same way. If you ever played with electric circuit kits as a kit, you should have a rough idea what's going on here. Microcontrollers have a variety of "pins" on them, all with their own specific purpose and usage type.

The most basic pins are "Ground" and "VCC". These pins are essentially the positive and negative end of a AA battery. If you connect the positive pin of an LED to VCC, and the negative end to Ground (GND), then congratulations. You've got light.

The majority of pins on an Arduino are known as "General Purpose Input/Output" pins. These are pins that can be controlled via software for you guessed it, general input or output tasks. If you connected the positive end of your LED to GPIO 1 and the negative end to your GND, your LED wouldn't light until you sent a software command which says, "Turn on GPIO 1".

Conversely, we can also use this same basic setup for wiring inputs. If instead of an LED we put a basic switch in between GPIO 2 and GND, it's possible to tell your software, "Perform this action when you detect someone closing the circuit between GPIO 2 and GND."

This sort of functionality is perfect for keyboards. We just need to wire up all of our switches between a GPIO pin and ground, and then write a keyboard firmware that says, "When switch 38 is flipped, type the 'A' key." Only, uh oh, the Arduino Pro Micro only has 18 GPIO pins. What do we do now?

Microcontrollers like the Arduino do have a few other tricks up their sleeves. They have analog pins which can send or receive signals that aren't a binary "on" or "off". This is useful for things like detecting light levels, but isn't exactly useful for a keyboard. We can also get into more technical ways of sending a signal. The Arduino supports I²C ("Eye-Squared-C") and SPI serial protocols for more advanced communication between devices, but this is generally only reserved for more advanced accessories like a keyboard's OLED screen.

To power a large keyboard with a handful of GPIO pins, we don't need to get a more advanced microcontroller. We need to leverage more basic electronics principles.

Enter the Matrix

Working with microcontrollers is an interesting change of pace for a lot of traditional programmers. Instead of being able to work in a purely digital world, you suddenly have to start accounting for a bunch of squishy real world physics limitations. Sometimes we can use this to our advantage though.

You probably have some passing familiarity with some basic electronics components. You've got LEDs to provide light, wires to hook things up, and resistors to... make electricity somehow less uh, electric. They resist things, right?

Diodes are one of those components everyone's heard of, but may be less clear on the details. They're a small piece of electronics that allow circuit designers to ensure that electricity is only flowing in one direction. The full details of why this is desirable is better left to full electronics engineering texts, but in short, it allows us to design circuits with very predictable and measurable flows of signals.

In all the GPIO examples I mentioned earlier, the circuits were wired with the GPIO pin generally going where the "positive" end of a battery would be, and the Ground pin was where the "negative" end of a battery would be. This isn't strictly required. We can wire a switch going from GPIO 1 to GPIO 2 and still detect in software when the button is pressed. When you introduce diodes into the picture, we can start getting very creative about wiring up multiple keys to the same GPIO pins.

Enter the keyboard matrix. This is an ancient design that essentially turns our keyboard into an intersecting grid of columns and rows. Turns out that terminology wasn't just useful for arrangement purposes. We get to leverage it here as well. If you design a keyboard matrix correctly, you can have several GPIO pins acting as the "columns", and several other GPIO pins acting as the "rows". With diodes acting as the electricity's traffic cop, we can design a circuit in which the only way GPIO 4 and GPIO 10 would both be receiving a signal is if key "A" was being held down.

The PCB section in our Ergogen config file isn't just dedicated to where the microcontroller goes on our keyboard. It also defines how the keyboard itself is wired.

Designing a Matrix

Before we actually jump into the Ergogen config, let's quickly sketch out the matrix we want to build so everyone's on the same page.

If we were building an Ortholinear keyboard, this guide would be ludicrously simple. Your up down keys are the columns, your left right keys are your rows. If our keyboard reports that Col1-Row2 is being pressed, we know it's the Z key. The unibody Sofle in this design isn't as aligned, but we can make it work.

Tada, a 14 column, 5 row matrix for our Sofle. The thumbs having their own dedicated columns is a little silly, but as we saw in the Ortholinear example's spacebar, you don't have to have every matrix be the exact same size. Now that we've got the basic matrix defined, let's go back to our Arduino Pro Micro diagram and look at what the pinout for this keyboard may look like.

Welp. We've done goofed. We've got 19 rows and columns and only 18 pins. Pack it up everyone, it's been a great tutorial.

...or we could just be a little smarter about how we handle those thumbs.

By treating the thumbs as part of the inner-most columns, we can save two column pins. The mod row is essentially just shifted over by one. When the time comes to define our PCB config, we can use this layout to demonstrate how to do one-off key wiring overrides.

If we were designing a very basic keyboard, we'd be good to go at this point. However, the original Sofle Choc had support for an OLED screen. What if we wanted to add a screen to our design? The most popular OLED screen module for mechanical keyboards requires the use of the two I²C pins. Which means we're once again one pin short. Is there some way we could potentially squeeze one more pin out of our matrix?

Keyboard matrixes use an amount of pins equal to the number of columns plus the number of rows. This means that the more square your keyboard design is, the fewer number of pins you need. For example, 10 columns and 2 rows can support 20 keys across 12 pins, but 5 columns and 4 rows can support 20 keys across 9 pins.

But our layout is pretty fixed, right? We can't just magically somehow make it more square. We could free up some pins by doing something drastic like ditching the number row, but what if we could somehow just... fake a more square design? Right now we've got a 12x5 keyboard. Is there any shape that would get us closer to a square?

Huh. Okay. This is interesting. If you can't tell what's going on here, I took the two pieces of our keyboard and stacked them on top of each other. Gone is the nice rotate: -20 degree angle. This is an absurd keyboard bent completely in on itself. But this configuration does give us one benefit: It has 6 columns and 10 rows. 6+10=16, and would you look at that, we've managed to shave a pin off our 12+5=17 layout.

Of course, we need to figure out how to fit this into our existing wiring.

Tada! Our finished keyboard matrix!  This is what's known, slightly confusingly, as a "Duplex" matrix. Essentially we "bend" the columns back on each other and double the number of rows. (This doubling is where the "duplex" term comes from.) It can often help create a slightly better board geometry and save you a pin or two.

There's a completely unrelated "duplex matrix" which leverages diodes arranged in alternating directions. It requires slightly different key scanning code than traditional keyboard matrixes. KBD News has a full rundown of the difference between these two matrixes. The double row, bent column design was popularized by ai03 on the English speaking web, while the alternating-diode duplex matrix primarily took off in Japan. Due to this, they're often referred to as a "Western Duplex Matrix" and a "Japanese Duplex Matrix". "Duplex" as a communication term implies a bi-directional system, so the western duplex matrix is unfortunately a bit of a misnomer. Regardless of what term you use for it, these matrix designs can be useful when creating large unibody layouts.

Defining the PCB

Alright, back to Ergogen! Previously we've defined several top level sections in our Ergogen config. units: let us set the global variables for our project. points: defined the overall layout of the keys on our board. outlines: allowed us to create a border for our PCB. Finally, pcb: is going to allow us to define the circuit board and its related support hardware.

units: ...
points: ...
outlines: ...
pcbs:
  tutorial:
    outlines:
      main:
        outline: board

Here we've defined the top level pcb: section. Just like the outline section, we can define multiple PCBs if we'd like. We're just creating one here and naming it tutorial. Inside of our tutorial PCB, we've defined an outlines: section to specify which outlines we'd like to use for this board. I'm honestly not sure what the benefit of getting to name our own main: section inside of the PCB's outline section, but that's what some of the v4 examples use and sometimes you just need to roll with what works.

You'll also notice a different preview here. We've transitioned from Ergogen's web preview into KiCad. (KiCAD 7 came out while this series was being written. These screenshots are of KiCAD 6, but there shouldn't be any significant difference.) You can still use the web version of Ergogen to generate these files if you'd like. Just be aware you actually need to start clicking the "Generate" button instead of waiting for the preview to automatically re-render.

One oddity here is that our PCB outline is way outside of KiCAD's default sheet. We can fix this with a quick tweak in the Points section.

units: ...
points:
  zones:
    matrix:
      # Fix placement on KiCAD sheet.
      anchor:
        shift: [100, -100]
      ...
outlines: ...
pcbs:
  tutorial:
    outlines:
      main:
        outline: board

That was simple enough. But our board's still completely unpopulated. In the earlier parts of this guide we defined where each key switch was going to go, but we haven't defined the actual switches themselves yet. In KiCAD terms, we need to define the "Footprint" of the switches.

units: ...
points: ...
outlines: ...
pcbs:
  tutorial:
    outlines:
      main:
        outline: board
    footprints:
      choc_hotswap:
        what: choc
        where: true
        params:
          keycaps: true
          reverse: false
          hotswap: true
          from: "{{column_net}}"
          to: "{{colrow}}"

Now it's starting to look like a PCB! There's a lot going on here. Let's break down everything we just added. The footprints: section is naturally where we're going to add our part footprint definitions.

The first footprint we're going to define will be for the key switches themselves. We're leveraging Choc v1 switches in this design, and are going to be supporting "hotswap" sockets, so we've given it the creative name of choc_hotswap:.

The what: property specifies which footprint we're using. The Ergogen GitHub repository has a list of the default available footprints. We want to use the choc.js footprint, so these switch footprints are set as what: choc. The where: property allows us to specify where this footprint should apply. Ergogen has a tagging property we haven't touched on before, allowing you to flag certain keys to get certain footprints or properties applied to them. This could allow you to create some pretty unusual designs, hypothetically letting us set up MX switches for the main keys and Choc switches for the thumbs, etc. This board is using the same footprint for every key, so we're just going to use where: true.

In the params: section, we can adjust various settings of the footprint. If you open up the GitHub repository's choc.js file, you can see a list of available parameters at the top of the file. The keycaps: true property shows a box outline around the edges of where a 1u Choc keycap would be fit. The reverse: false property allows us to specify if we want the footprint to appear on the top and bottom of a PCB. This is a single-side unibody design, so we've set this to false. Finally, hotswap: true specifies that we'd like to use the hotswap socket footprint instead of the through-hole switch design.

At the end of the footprint we've got the from: and to: properties. These control the "Nets" of the PCB. It's a larger topic that we'll cover in a bit, but we're adding them now so Ergogen doesn't throw any errors.

units: ...
points: ...
outlines: ...
pcbs:
  tutorial:
    outlines:
      main:
        outline: board
    footprints:
      choc_hotswap:
        what: choc
        where: true
        params:
          keycaps: true
          reverse: false
          hotswap: true
          from: "{{column_net}}"
          to: "{{colrow}}"
      diode:
        what: diode
        where: true
        params:
          from: "{{colrow}}"
          to: "{{row_net}}"
        adjust:
          shift: [0, -5]

Next we need to define the diodes used in our keyboard matrix. We've set up another entry in the footprints: section, cleverly named diode:. This footprint contains what: diode to refer to Ergogen's diode.js file. This footprint supports both surface mount smd diodes as well as through hole diodes, and doesn't have any parameters other than those mysterious from: and to: attributes. We have made one other adjustment however.

The where: true attribute places this diode footprint at the center of every point on our keyboard. This worked well for our choc footprints, but we don't want the diodes to be literally right on top of the key switch. Adding adjust.shift: [0, -5] moves the diode down beneath the key footprint.

Now that we've got our keys and our diodes set, let's do a very ham-fisted approach of trying to place the Arduino Pro Micro.

units: ...
points: ...
outlines: ...
pcbs:
  tutorial:
    outlines:
      main:
        outline: board
    footprints:
      choc_hotswap: ...
      diode: ...
      promicro:
        what: promicro
        params:
          orientation: "down"
        where:
          ref: matrix_inner_top
          shift: [0,0]
          rotate: 0

You're starting to see a trend here. We've named our microcontroller's footprint promicro:, and the what: is a reference to promicro.js. The orientation: "down" parameter specifies whether or not the pinout for the Arduino should be with the microcontroller facing "up" or "down". Arduino Pro Micros aren't symmetrical, so you need to pick how you'd like it to be oriented. Most header pins are tall enough that they can fit the USB port in either configuration, so boards commonly use a face-down configuration for aesthetic reasons and to give the OLED screen something flush to sit against.

For the placement in where:, I set the reference to the matrix_inner_top key on the left side of the keyboard. It's one of the closer keys to the center of the board. From here we could try to shift: the key closer to the center, and give it a rotate: so that its pointing up instead of aligned with matrix_inner_top, but there's a new method we can use here.

units: ...
points: ...
outlines: ...
pcbs:
  tutorial:
    outlines:
      main:
        outline: board
    footprints:
      choc_hotswap: ...
      diode: ...
      promicro:
        what: promicro
        params:
          orientation: "down"
        where:
          ref.aggregate.parts: [matrix_inner_top, mirror_matrix_inner_top]
          shift: [0,0]
          rotate: 0

The ref.aggregate.parts: method allows you to specify location between two points. In this case, I specified a reference location between the matrix_inner_top left on the left, and the mirror_matrix_inner_top key on the right. Earlier versions of Ergogen would have just used ref: [matrix_inner_top, mirror_matrix_inner_top], but v4 makes things a bit more explicit what's going on.

units: ...
points: ...
outlines: ...
pcbs:
  tutorial:
    outlines:
      main:
        outline: board
    footprints:
      choc_hotswap: ...
      diode: ...
      promicro:
        what: promicro
        params:
          orientation: "down"
        where:
          ref.aggregate.parts: [matrix_inner_top, mirror_matrix_inner_top]
          shift: [0,0]
          rotate: -90

One quick application of rotate: -90 later, and things are starting to look good. Surprisingly good actually.

Real talk. When I created Part 1 of this guide I had assumed I had spaced the two halves of the keyboard too far apart. The placement of this Arduino looks almost perfect. I was planning on demonstrating how you can always go back and adjust earlier properties like points.mirror.distance: 2.5kx later on while building your config. Just for demonstration purposes, let's see if we can't make a better use of this space. Or at least arbitrarily different use.

units: ...
points:
  zones:
    matrix: ...
    thumbs: ...
  rotate: ...
  mirror: &mirror
    ref: matrix_inner_num
    distance: 2kx
outlines:
  raw: ...
  keys: ...
  board:
    - what: polygon
      operation: stack
      points:
        - ref: matrix_outer_num
          shift: [-0.5px,0.5py]
        - ref: matrix_ring_num
          shift: [-0.5px,0.5py]
        - ref: matrix_middle_num
          shift: [-0.5px,0.5py]
        - ref: matrix_middle_num
          shift: [0.5px,0.5py]
        - ref: matrix_inner_num
          shift: [0.5px,0.5py]
        - ref: matrix_inner_top
          shift: [0.5px,0.5py]
        - ref: mirror_matrix_inner_top
          shift: [0.5px,0.5py]
        - ref: mirror_matrix_inner_num
          shift: [0.5px,0.5py]
        - ref: mirror_matrix_middle_num
          shift: [0.5px,0.5py]
        - ref: mirror_matrix_middle_num
          shift: [-0.5px,0.5py]
        - ref: mirror_matrix_ring_num
          shift: [-0.5px,0.5py]
        - ref: mirror_matrix_outer_num
          shift: [-0.5px,0.5py]
        - ref: mirror_matrix_outer_bottom
          shift: [-0.5px,-0.5py]
        - ref: mirror_matrix_ring_mod
          shift: [-0.5px,-0.5py]
        - ref: mirror_thumbs_layer_cluster
          shift: [-0.5px,-0.5py]
        - ref: mirror_thumbs_space_cluster
          shift: [-0.5py,-0.5px]
        - ref: mirror_thumbs_space_cluster
          shift: [0.5py,-0.5px]
        - ref: thumbs_space_cluster
          shift: [0.5py,-0.5px]
        - ref: thumbs_space_cluster
          shift: [-0.5py,-0.5px]
        - ref: thumbs_layer_cluster
          shift: [-0.5px,-0.5py]
        - ref: matrix_ring_mod
          shift: [-0.5px,-0.5py]
        - ref: matrix_outer_bottom
          shift: [-0.5px,-0.5py]
      fillet: 2
  combo: ...
pcbs:
  tutorial:
    outlines:
      main:
        outline: board
    footprints:
      choc_hotswap:
        what: choc
        where: true
        params:
          keycaps: true
          reverse: false
          hotswap: true
          from: "{{colrow}}"
          to: "{{col_net}}"
      diode:
        what: diode
        where: true
        params:
          from: "{{colrow}}"
          to: "{{row_net}}"
        adjust:
          shift: [0, -5]
      promicro:
        what: promicro
        params:
          orientation: "down"
        where:
          ref.aggregate.parts: [matrix_inner_home, mirror_matrix_inner_home]
          shift: [0,0]
          rotate: -90

Alright, things are looking a bit more snug now! I went ahead and updated the points.mirror.distance: value from 2.5kx to 2kx. The Pro Micro's anchor reference has also been updated to use matrix_inner_home and its mirrored counterpart instead of matrix_inner_top. Finally, I added four new points to our outline. The outline now drops down from matrix_inner_num to matrix_inner_top before jumping across to the mirrored half. Similarly, the thumb keys linger on the thumbs_space_cluster for two additional points that shifted up to the top of the switch.

This is a fairly arbitrary change, but it's useful to show that none of the design decisions are set in stone. It's also important to remember that you pay per square inch when fabricating a PCB, so these sorts of small improvements can add up over time.

units: ...
points:
  zones:
    matrix: ...
    thumbs: ...
  rotate: ...
  mirror: &mirror
    ref: matrix_inner_num
    distance: 2kx
outlines: ...
pcbs:
  tutorial:
    outlines:
      main:
        outline: board
    footprints:
      choc_hotswap: ...
      diode: ...
      promicro: ...
      oled:
        what: oled
        params:
          side: "F"
          SDA: P2
          SCL: P3
        where:
          ref.aggregate.parts: [matrix_inner_home, mirror_matrix_inner_home]
          shift: [-6,-19]
          rotate: 90

We're wrapping up the parts now. Next is the footprint for the OLED screen. The what: oled portion refers to oled.js, and the where: parameters should be starting to look a little familiar. This footprint has an awkward shift: [-6, -19] on it. For whatever reason, the anchor point for the footprint itself isn't centered on the screen's pins.

The params: section has a few attributes we haven't seen before. side: "F" specifies that we're dealing with the front of the OLED screen, but what's SDA: and SCL:? That's an excellent question. One I'm not going to answer just yet.

units: ...
points: ...
outlines: ...
pcbs:
  tutorial:
    outlines:
      main:
        outline: board
    footprints:
      choc_hotswap: ...
      diode: ...
      promicro: ...
      oled: ...
      reset:
        what: button
        params:
          from: GND
          to: RST
        where:
          ref.aggregate.parts: [matrix_index_mod, mirror_matrix_index_mod]
          shift: [0, -1]
          rotate: -90

The last component we're dealing with is a reset button for the microcontroller. This allows you to reset the Arduino Pro Micro and put it into a flashing state for applying new firmware. This footprint is defined by button.js, and we're once again seeing those unusual from: and to: parameters. Let's wrap up the PCB layout section and finally tackle what's going on with those net parameters.

It's worth noting that this is a pretty barebones PCB. It's a unibody design, so we didn't need to use trrs.js to define a headphone jack to connect the two sides of a split keyboard. We're also not using a Nice!Nano wireless microcontroller, so we don't need to worry about a lipo battery and its jstph.js battery header.

Casting a Net

If you've been following along with this guide, you may have noticed some unusual things about the PCB file that Ergogen is creating. First of all: None of these parts are connected. There's just a blank void with several part footprints outlined by the edge of our board. Most PCBs you've looked at generally have thick lines connecting the parts together.

Furthermore, you may have noticed that when we placed the OLED screen and reset buttons, small thin white lines started appearing on our PCB. These don't look like normal PCB lines though. They're just shooting diagonal across the board between different pins. The clever ones among you may have started getting a sinking feeling when they noticed that the VCC pin on the OLED screen has a thin white line pointing to the VCC pin on the Arduino Pro Micro.

That's right. It's our job to make all of these connections. Welcome to the fun world of routing traces. A "trace" on a PCB is a small strip of metal connecting two parts on the board. It's similar to connecting components together with a jumper cable on a breadboard. The catch here is that the PCB only has two sides: A front and a bottom. I connected the VCC and GND pins with red traces on the front of the board, but needed to connect the P2 and P3 pins with blue traces on the backside of the board so they could pass under the red traces.

This is a manual and time consuming process. Worst yet, if you notice an error in your Ergogen config, you need to generate a new blank PCB and start all over again. Defining nets can help aid in this process considerably however. If we weren't able to specify that the OLED's left pin connected to the Arduino's 17th pin, we'd be left constantly flipping back and forth between part documentation, our schematics / config files, and the PCB itself. By defining in Ergogen which parts connect to one another, Ergogen can force us to wire things correctly.

When you're in the process of actively connecting two parts together, KiCAD will highlight the pins that your Ergogen config has specified that it would be alright for you to wire them to. You can see this behavior in this mid-routing screenshot where the two P2 pins are lit up like a Christmas tree.

So the next big step in our Ergogen config is defining all of these nets. We've seen a few of these definitions already in our file. Those from: and to: lines I skipped over earlier? We're finally getting back to those now.

The footprint file in Ergogen's Github repository defines the attribute name for a pin. from: and to: are conventions that footprint authors commonly use when a component only has two pins, but it's not a hard and fast rule.

params: {
  designator: 'B', // for Button
  side: 'F',
  from: undefined,
  to: undefined
}

Here's the top section of the reset button we defined earlier. It has some metadata fields like designator: and side:, and then these undefined from: and to: fields. If we don't override the designator or the side it will use these defaults, but we have to define from: and to:

params: {
  designator: 'OLED',
  side: 'F',
  VCC: {type: 'net', value: 'VCC'},
  GND: {type: 'net', value: 'GND'},
  SDA: undefined,
  SCL: undefined
},

Jumping back to the OLED footprint, we can see a slightly different configuration. The OLED screen on the keyboard needs power, and it also requires several pins to communicate with the Arduino. VCC is the term for regulated power coming from a microcontroller, and we also need a GND pin to complete the circuit. This OLED screen is powered by I²C serial communication which uses pins commonly defined as SDA and SCL.

Rather than arbitrarily coming up with new names for these pins, this footprint users the industry standard. VCC and GND are such common abbreviations that the footprint goes ahead and defines those pins for us. It doesn't know which SDA and SCL pins we'd like to use however, so we still need to define those.

In our Ergogen config, we referenced this OLED footprint with SDA: P2 and SCL: P3. This tells Ergogen, "If you see anything with a P2 pin on it, then this OLED screen's SDA pin is okay to connect to it. Our Arduino Pro Micro footprint has such a P2 pin, so lets look at its definition now.

  params: {
    designator: 'MCU',
    orientation: 'down',
    RAW: {type: 'net', value: 'RAW'},
    GND: {type: 'net', value: 'GND'},
    RST: {type: 'net', value: 'RST'},
    VCC: {type: 'net', value: 'VCC'},
    P21: {type: 'net', value: 'P21'},
    P20: {type: 'net', value: 'P20'},
    P19: {type: 'net', value: 'P19'},
    P18: {type: 'net', value: 'P18'},
    P15: {type: 'net', value: 'P15'},
    P14: {type: 'net', value: 'P14'},
    P16: {type: 'net', value: 'P16'},
    P10: {type: 'net', value: 'P10'},
    P1: {type: 'net', value: 'P1'},
    P0: {type: 'net', value: 'P0'},
    P2: {type: 'net', value: 'P2'},
    P3: {type: 'net', value: 'P3'},
    P4: {type: 'net', value: 'P4'},
    P5: {type: 'net', value: 'P5'},
    P6: {type: 'net', value: 'P6'},
    P7: {type: 'net', value: 'P7'},
    P8: {type: 'net', value: 'P8'},
    P9: {type: 'net', value: 'P9'}
  }

Woah! That's a lot of pins! You can see all of these pins are predefined here. For our OLED screen, the VCC pin automatically matched up with the Arduino's VCC pin since they were defined to the exact same value. In the case of the data pins, the SDA: P2 pin has a thin white line leading to the Arduino Pro Micro because we defined it as such.

The P1-P21 pins seem a little generic at first, but let's go back and take a look at the Arduino screenshot and our Pro Micro footprint.

The Arduino footprint is oriented face down, so you need to mentally mirror these two diagrams. Once you do that however, you can see the same pattern of RAW, GND, RST, VCC, 21, 20, 19, etc. Pin numbers are a tricky thing on Arduinos. The ATmega32U4 processor has its own internal pin numbering, and on top of that pins can have multiple definitions. 2 is also the SDA pin, and 21 is also the A3 analog pin. In general however, most Arduino-based projects will discuss their wiring in terms of "Arduino" pins, or sometimes "Digital" pins. That's what this footprint has done here. They've just tacked P for "Pin" in front. (These pin names are also treated as a text string. P9 and P09 are considered two different pin labels, so don't go adding leading zeroes to your pin config.)

So at this point we understand how footprint nets are defined, and we've seen it in action on the few small footprints that we've added. We still don't have any nets going from our key switches to the Arduino however. Let's back up a minute and look at the existing key and diode definitions.

pcbs:
  tutorial:
    outlines:
      main:
        outline: board
    footprints:
      choc_hotswap:
        what: choc
        where: true
        params:
          keycaps: true
          reverse: false
          hotswap: true
          from: "{{column_net}}"
          to: "{{colrow}}"
      diode:
        what: diode
         where: true
        params:
          from: "{{colrow}}"
          to: "{{row_net}}"
        adjust:
          shift: [0, -5]

These footprints have had from: and to: definitions this entire time, and sure enough, you can see some nets in between the switch and the diode at every key.

The choc_hotswap: and diode: sections are using a new syntax we haven't seen yet. The from: "{{colrow}}", to: "{{col_net}}", and to: "{{row_net}}" properties have introduced curly brackets to our config file. (If you're looking at older Ergogen v3 configs, you'll instead see from: =colrow with an equal sign instead.)

This curly bracket syntax allows us to set "key-level attributes". Unlike the OLED screen on the Reset button footprints, we don't want to just straight wire every key on our keyboard to GND or VCC. We need to build out the matrix, and these key-level attributes are part of that.

In the next step of this guide, we'll be running those column and row lines we outlined back in the matrix section. The row lines will connect to one side of our switch, and the column lines will connect to the other side of the switch. It would be nice and simple, but we've also got the diodes to hook up.

The from: {{colrow}} parameter inside of choc_hotswap: and diode: signal to Ergogen that every key's switch needs to be wired up to every key's diode. They share this internal wiring because they both use {{colrow}} as a key-level net name.

The other properties are another one of those slightly confusing community naming convention vs. fixed Ergogen property name topics. The col_net and row_net (or sometimes column_net and row_net) properties you frequently see online in other people's Ergogen configs are just inherited from the original Absolem days. col_net and row_net are just popular conventions. colrow on the other hand is a function built into Ergogen. It's an aliased variable to the column-row intersection at that particular key.

All you really need to know here is that this is the portion of our code responsible for wiring up the diodes at each key. As long as you stay consistent in your use of col_row, row_net, and colrow you should be fine. Let's finally move on to creating our matrix.

(It's probably also worth pointing out at this point that our diode footprint has both options for through hole and surface mount device footprints. You can use a diode with legs that need to be soldered through the holes, or smaller smd diodes that only need to be soldered onto the pads. For reasons we'll cover later, having at least one pair of through hole components on this board helps us out a bit. If you're wondering why a pair of pads are connected so closely with those small through holes, there's your explanation.)

units: ...
points:
  zones:
    matrix:
      anchor: ...
      key: ...
      columns:
        outer: ...
        pinky: ...
        ring: ...
        middle: ...
        index: ...
        inner: ...
      rows:
        mod: ...
        bottom:
          row_net: P1
        home: ...
        top: ...
        num: ...
    thumbs:
      key: ...
      anchor: ...
      columns:
        layer: ...
        space: ...
      rows:
        cluster: ...
  rotate: -20
  mirror: ...
outlines: ...
pcbs: ...

Wiring up our keyboard matrix's nets requires us to go all the way back up into the points: section of our config. I've hidden most of the properties we added during Part 1, but you can see the newly added bottom.row_net: P1 attribute.

This does pretty much what you expect. You can see a net coming from the Arduino's P1 pin connecting to all of the keys in the bottom row.

units: ...
points:
  zones:
    matrix:
      anchor: ...
      key: ...
      columns:
        outer: ...
        pinky: ...
        ring: ...
        middle: ...
        index:
          key:
            stagger: -2.5
            column_net: P0
        inner: ...
      rows:
        mod: ...
        bottom:
          row_net: P1
        home: ...
        top: ...
        num: ...
    thumbs:
      key: ...
      anchor: ...
      columns:
        layer: ...
        space: ...
      rows:
        cluster: ...
  rotate: -20
  mirror: ...
outlines: ...
pcbs: ...

The column_net: property works the exact same way, just for columns instead of rows. Just note that you need to put it inside of the key: property of each column.

Before we continue, mosey on over to the Editing Options section of your KiCAD Settings. There's an option for Step for rotate commands:. Change that to match whatever rotate: attribute to inside of the points: section. In our case, 20 deg.

Now if you go back to your KiCAD window, you can select the entire board with Ctrl/Cmd-a, and rotate the two halves back and forth with r and Shift-r.

Ah, that feels better.

This tutorial isn't going to be a full KiCAD guide. Thankfully you don't need to get deep into this software in order to make a keyboard. KiCAD actions are very "modal", and are usually triggered by discrete clicks or key commands. Unlike a drawing application like Paint or Photoshop, you create traces by clicking where you want to start drawing a line, dragging the line to where it needs to go, and then clicking a second time to stop drawing.

Let's go ahead and wire up our row now.

Here's our row.

And here's our column. (Shout out to my CMS stretching the image out a bit.)

Oof. I did not think through which pins I used for these columns and rows, huh? Those row and column traces are having to reach over to the far side of the keyboard in order to get hooked up. Let's see if we can more intelligently map out these pins.

units: ...
points:
  zones:
    matrix:
      anchor: ...
      key: ...
      columns:
        outer:
          rows.mod.skip: true
          key.column_net: P14
        pinky:
          rows.mod.skip: true
          key.column_net: P16
        ring:
          key:
            stagger: 5
            column_net: P10
        middle:
          key:
            stagger: 2.5
            column_net: P7
        index:
          key:
            stagger: -2.5
            column_net: P8
        inner:
          rows.mod.skip: true
          key:
            stagger: -2.5
            column_net: P9
      rows:
        mod:
          row_net: P15
        bottom:
          row_net: P18
        home:
          row_net: P19
        top:
          row_net: P20
        num:
          row_net: P21
    thumbs:
      key: ...
      anchor: ...
      columns:
        layer: ...
        space: ...
      rows:
        cluster: ...
  rotate: -20
  mirror: ...
outlines: ...
pcbs: ...

We are almost there. We've set all of the column nets, but we still need to define the row nets for the right side of the keyboard. Thankfully, Ergogen provides a syntax to specifically target mirrored sections of the board.

rows:
  mod:
    row_net: P15
    mirror.row_net: P6
  bottom:
    row_net: P18
    mirror.row_net: P5
  home:
    row_net: P19
    mirror.row_net: P4
  top:
    row_net: P20
    mirror.row_net: P0
  num:
    row_net: P21
    mirror.row_net: P1

There we go! All of our nets are now set up!

Except wait, the thumbs aren't connected to anything. Right, we were going to nudge all of those net definitions over by one. Let's clean that up real quick. Key level overrides to the rescue!

units: ...
points:
  zones:
    matrix:
      anchor: ...
      key: ...
      columns:
        outer:
          rows.mod.skip: true
          key.column_net: P14
        pinky:
          rows.mod.skip: true
          key.column_net: P16
        ring:
          key:
            stagger: 5
            column_net: P10
          rows.mod.column_net: P16
        middle:
          key:
            stagger: 2.5
            column_net: P7
          rows.mod.column_net: P10
        index:
          key:
            stagger: -2.5
            column_net: P8
          rows.mod.column_net: P7
        inner:
          rows.mod.skip: true
          key:
            stagger: -2.5
            column_net: P9
      rows:
        mod:
          row_net: P15
          mirror.row_net: P6
        bottom:
          row_net: P18
          mirror.row_net: P5
        home:
          row_net: P19
          mirror.row_net: P4
        top:
          row_net: P20
          mirror.row_net: P0
        num:
          row_net: P21
          mirror.row_net: P1
    thumbs:
      key: ...
      anchor: ...
      columns:
        layer:
          key:
            splay: -15
            column_net: P8
        space:
          key:
            width: 1.5kx
            splay: 75
            shift: [2.5,-3.25]
            column_net: P9
      rows:
        cluster:
          row_net: P15
          mirror.row_net: P6
  rotate: -20
  mirror: ...
outlines: ...
pcbs: ...

In this step we finished wiring up our thumb keys, and we also included some row level overrides in our column definitions. The rows.mod.column_net: P16 inside of column.ring: tells Ergogen that we want to override the rest of that column's column_net: P10 for just the mod key.

With that, we're finally done. There was a lot of theory talk here when it came to the nets, but our PCB configuration is finished!

End of Part 3

units:
  # Proxy Spacing Variables
  kx: cx
  ky: cy
  # Padding Variables
  px: kx + 4
  py: ky + 4
points:
  zones:
    # The primary 6x4 key matrix, plus 3 modifiers.
    matrix:
      # Position in center of KiCAD workspace.
      anchor:
        shift: [100, -100]
      # Choc spacing
      key:
        padding: 1ky
        spread: 1kx
      columns:
        # Hide the first two mods and the last mod.
        # Provide a Sofle-like column stagger.
        outer:
          rows.mod.skip: true
          key.column_net: P14
        pinky:
          rows.mod.skip: true
          key.column_net: P16
        ring:
          key:
            stagger: 5
            column_net: P10
          rows.mod.column_net: P16
        middle:
          key:
            stagger: 2.5
            column_net: P7
          rows.mod.column_net: P10
        index:
          key:
            stagger: -2.5
            column_net: P8
          rows.mod.column_net: P7
        inner:
          rows.mod.skip: true
          key:
            stagger: -2.5
            column_net: P9
      rows:
        # Four main rows, one partial row.
        mod:
          row_net: P15
          mirror.row_net: P6
        bottom:
          row_net: P18
          mirror.row_net: P5
        home:
          row_net: P19
          mirror.row_net: P4
        top:
          row_net: P20
          mirror.row_net: P0
        num:
          row_net: P21
          mirror.row_net: P1
    # Thumb cluster for Layer and Space keys.
    thumbs:
      # Choc spacing
      key:
        padding: 1ky
        spread: 1kx
      # Place thumbs where the inner mod would go.
      anchor:
        ref: matrix_inner_mod
        shift: [2, -2]
      columns:
        # Fan thumbs out by -15 degrees.
        layer:
          key:
            splay: -15
            column_net: P8
        # Spacebar uses a 1.5 wide key.
        space:
          key:
            width: 1.5kx
            splay: 75
            shift: [2.5,-3.25]
            column_net: P9
      rows:
        # Thumbs only have one row.
        cluster:
          row_net: P15
          mirror.row_net: P6
  # Mirror keyboard halves with a moderate rotation.
  rotate: -20
  mirror: &mirror
    ref: matrix_inner_num
    distance: 2kx
outlines:
  # Pure key outline.
  raw:
    - what: rectangle
      where: true
      size: [px, py]
  # Key outlines with 0.5mm removed to show key overlaps.
  keys:
    - what: rectangle
      where: true
      size: [kx-0.5,ky-0.5]
  # PCB board outline.
  board:
    - what: polygon
      operation: stack
      points:
        - ref: matrix_outer_num
          shift: [-0.5px,0.5py]
        - ref: matrix_ring_num
          shift: [-0.5px,0.5py]
        - ref: matrix_middle_num
          shift: [-0.5px,0.5py]
        - ref: matrix_middle_num
          shift: [0.5px,0.5py]
        - ref: matrix_inner_num
          shift: [0.5px,0.5py]
        - ref: matrix_inner_top
          shift: [0.5px,0.5py]
        - ref: mirror_matrix_inner_top
          shift: [0.5px,0.5py]
        - ref: mirror_matrix_inner_num
          shift: [0.5px,0.5py]
        - ref: mirror_matrix_middle_num
          shift: [0.5px,0.5py]
        - ref: mirror_matrix_middle_num
          shift: [-0.5px,0.5py]
        - ref: mirror_matrix_ring_num
          shift: [-0.5px,0.5py]
        - ref: mirror_matrix_outer_num
          shift: [-0.5px,0.5py]
        - ref: mirror_matrix_outer_bottom
          shift: [-0.5px,-0.5py]
        - ref: mirror_matrix_ring_mod
          shift: [-0.5px,-0.5py]
        - ref: mirror_thumbs_layer_cluster
          shift: [-0.5px,-0.5py]
        - ref: mirror_thumbs_space_cluster
          shift: [-0.5py,-0.5px]
        - ref: mirror_thumbs_space_cluster
          shift: [0.5py,-0.5px]
        - ref: thumbs_space_cluster
          shift: [0.5py,-0.5px]
        - ref: thumbs_space_cluster
          shift: [-0.5py,-0.5px]
        - ref: thumbs_layer_cluster
          shift: [-0.5px,-0.5py]
        - ref: matrix_ring_mod
          shift: [-0.5px,-0.5py]
        - ref: matrix_outer_bottom
          shift: [-0.5px,-0.5py]
      fillet: 2
  # Combination preview showing outline and keys.
  combo:
    - name: board
    - operation: subtract
      name: keys
pcbs:
  tutorial:
    outlines:
      main:
        outline: board
    footprints:
      # Hotswap Choc keys.
      choc_hotswap:
        what: choc
        where: true
        params:
          keycaps: true
          reverse: false
          hotswap: true
          from: "{{column_net}}"
          to: "{{colrow}}"
      # Through Hole or SMD Diodes
      diode:
        what: diode
        where: true
        params:
          from: "{{colrow}}"
          to: "{{row_net}}"
        adjust:
          shift: [0, -5]
      # Face Down Arduino Pro Micro
      promicro:
        what: promicro
        params:
          orientation: "down"
        where:
          ref.aggregate.parts: [matrix_inner_home, mirror_matrix_inner_home]
          shift: [0,0]
          rotate: -90
      # OLED Screen
      oled:
        what: oled
        params:
          side: "F"
          SDA: P2
          SCL: P3
        where:
          ref.aggregate.parts: [matrix_inner_home, mirror_matrix_inner_home]
          shift: [-6,-19]
          rotate: 90
      # Four Pin Reset Button
      reset:
        what: button
        params:
          from: GND
          to: RST
        where:
          ref.aggregate.parts: [matrix_index_mod, mirror_matrix_index_mod]
          shift: [0, -1]
          rotate: -90

We still need to wire this bad boy together, but before we wrap up this PCB, I'd like to take a trip over to the Cases section and wrap up a few of the smaller Ergogen topics. When you're ready, head on over to Let's Design a Keyboard With Ergogen v4: Offline Ergogen, External Footprints, & Cases (Part 4)!

Welcome back, again! In the introduction to this series we discussed the various parts of Ergogen, and in Part 1 we created a series of points defining the layout of our keyboard. Now in Part 2 we're going to focus on creating an outline for our board.

Outlines

Right now we've only defined the points. We know what layout our keys will take, but we need to give shape and structure to the actual board itself. This is done via "Outlines". They pretty much do what they say on the tin, and they can be defined a few different ways. Let's go ahead and try out the first method now.

units:
  kx: cx
  ky: cy
  px: kx + 2
  py: ky + 2
points:
  zones:
    matrix: ...
    thumbs: ...
  rotate: -15
  mirror: &mirror
    ref: matrix_inner_num
    distance: 2.5kx
outlines:
  raw:
    - what: rectangle
      where: true
      size: [kx, ky]

We've gone ahead and added a new top level section. Along with units and points, the outlines section will house all of our outline data. To start with, let's define a very simple outline. In this (user named) raw: section, we're going to put a border around every key on our keyboard. The - what: rectangle attribute tells Ergogen we're dealing with four sided shapes, and the where: true tells Ergogen we'd like to set this outline up anywhere we have points (keys). size: [kx, ky] tells Ergogen that we want these rectangles to have a standard Choc height and width. (We assigned cx and cy to kx and ky in the Units section of Part 1 so that we can easily re-define them later if we need to.)

Just a head's up, the - in - what: rectangle is YAML's way of indicating an item in a list. You may reciever errors from your config if your outline's - characters don't have the proper whitespace.

Anywhere that these rectangles overlap or have touch edges will be combined into the same shape. Our Choc spaced switches all overlap one another, so we get two slightly bumpy rectangles with the thumbs floating out by themselves.

points:
  zones:
    matrix: ...
    thumbs: ...
  rotate: -15
  mirror: &mirror
    ref: matrix_inner_num
    distance: 2.5kx
outlines:
  raw:
    - what: rectangle
      where: true
      size: [px, py]

We don't have to go with our usual size: [kx, ky] exactly Choc-sized switch outlines if we don't want to. Switching over to those padded px and py units we created at the start of Part 1 will allow us to add 1mm of padding on each side of our keys. Since the raw outline is combining these keys together, the extra padding on the interior of the shape won't matter. You can see our larger thumbs start to become part of the overall shape at this point.

From here there's a few approaches we could take. We can keep using this traced-style keyboard and do some tricks to incorporate the thumbs and bridge the two halves together, or we could define our own custom keyboard shape from scratch.

Before we get into that however, we should circle back on something we discussed in the Points portion of this guide. Our ergogen.xyz preview was limited to MX spacing, and we weren't able to get a clear view of our actual keyboard layout. Let's fix that now and create an outline that's just a preview of our keys.

points:
  zones:
    matrix: ...
    thumbs: ...
  rotate: -15
  mirror: &mirror
    ref: matrix_inner_num
    distance: 2.5kx
outlines:
  raw:
    - what: rectangle
      where: true
      size: [px, py]
  keys:
    - what: rectangle
      where: true
      size: [kx-0.5,ky-0.5]

This new keys: section is very similar to our earlier raw: shape. The only difference is that we've shaved half a millimeter off of each key so that we can more easily see any potential overlap between them.

points:
  zones:
    matrix:
      key: ...
      columns: ...
      rows: ...
    thumbs:
      key: ...
      anchor: ...
      columns:
        layer: ...
        space:
            width: 1.5kx
            splay: 75
            shift: [2.5,-3.25]
      rows:
        cluster: ...
  rotate: ...
  mirror: &mirror
    ref: matrix_inner_num
    distance: 2.5kx
outlines:
  raw:
    - what: rectangle
      where: true
      bound: true
      size: [px, py]
  keys:
    - what: rectangle
      where: true
      bound: false
      size: [kx-0.5,ky-0.5]

With a better view of the thumbs, I've decided to go back and adjust the points.zones.matrix.thumbs.columns.space section. The key is now shifted over shift: [2.5, -3.25]. It's still a visual eyeball, but it seems a little better positioned than before.

Update! ergogen.xyz now supports custom preview variables! You can set $default_width and $default_height in the units: section to adjust the demo.dxf preview. These variables only adjust the web preview, so the rest of this guide is still useful, but it's not strictly necessary to create the custom keys: preview anymore.

Now let's get onto the main event: Creating an actual outline for the keyboard.We want something that looks vaguely like this:

The trick is that we can't just arbitrarily draw lines on a blank canvas. We need to use the reference the points we've created to indicate where the line should be drawn.

points:
  zones:
    matrix:
      key: ...
      columns:
        outer: ...
        pinky: ...
        ring: ...
        middle: ...
        index: ...
        inner: ..
      rows:
        mod: ...
        bottom: ...
        home: ...
        top: ...
        num: ...
    thumbs:
      key: ...
      anchor: ...
      columns:
        layer: ...
        space: ...
      rows:
        cluster: ...
  rotate: ...
  mirror: ...
outlines:
  raw: ...
  keys: ...
  board:
    - what: polygon
      operation: stack
      points:
        - ref: matrix_outer_num
          shift: [0,0]
        - ref: matrix_ring_num
          shift: [0,0]
        - ref: matrix_middle_num
          shift: [0,0]
        - ref: matrix_inner_num
          shift: [0,0]
        - ref: mirror_matrix_inner_num
          shift: [0,0]
        - ref: mirror_matrix_middle_num
          shift: [0,0]
        - ref: mirror_matrix_ring_num
          shift: [0,0]
        - ref: mirror_matrix_outer_num
          shift: [0,0]
        - ref: mirror_matrix_outer_bottom
          shift: [0,0]
        - ref: mirror_matrix_ring_mod
          shift: [0,0]
        - ref: mirror_thumbs_space_cluster
          shift: [0,0]
        - ref: thumbs_space_cluster
          shift: [0,0]
        - ref: matrix_ring_mod
          shift: [0,0]
        - ref: matrix_outer_bottom
          shift: [0,0]

We've introduced a new type of outline here. The "polygon" outline allows us to create a many-sided shape. Each point needs a ref key to describe where it is, and can be adjusted with shift. In this particular polygon, I've started in the top left corner and walked around the board. This uses that same ref notation we discussed earlier, and has some actual examples of the mirror_ prefix. There's just one small problem: All of these points are referencing the center of the key. We need to shift the outline to the edge of the key.

outlines:
  raw: ...
  keys: ...
  board:
    - what: polygon
      operation: stack
      points:
        - ref: matrix_outer_num
          shift: [-0.5px,0.5py]
        - ref: matrix_ring_num
          shift: [-0.5px,0.5py]
        - ref: matrix_middle_num
          shift: [-0.5px,0.5py]
        - ref: matrix_middle_num
          shift: [0.5px,0.5py]
        - ref: matrix_inner_num
          shift: [0.5px,0.5py]
        - ref: mirror_matrix_inner_num
          shift: [0.5px,0.5py]
        - ref: mirror_matrix_middle_num
          shift: [0.5px,0.5py]
        - ref: mirror_matrix_middle_num
          shift: [-0.5px,0.5py]
        - ref: mirror_matrix_ring_num
          shift: [-0.5px,0.5py]
        - ref: mirror_matrix_outer_num
          shift: [-0.5px,0.5py]
        - ref: mirror_matrix_outer_bottom
          shift: [-0.5px,-0.5py]
        - ref: mirror_matrix_ring_mod
          shift: [-0.5px,-0.5py]
        - ref: mirror_thumbs_layer_cluster
          shift: [-0.5px,-0.5py]
        - ref: mirror_thumbs_space_cluster
          shift: [-0.75px,0.5py]
        - ref: thumbs_space_cluster
          shift: [-0.75px,0.5py]
        - ref: thumbs_layer_cluster
          shift: [-0.5px,-0.5py]
        - ref: matrix_ring_mod
          shift: [-0.5px,-0.5py]
        - ref: matrix_outer_bottom
          shift: [-0.5px,-0.5py]

Now that's a lot of points. I added a few additional refs as we walked clockwise around the keyboard. Most keys have a shift of 0.5px or -0.5px to shift to the left or right side of the key (with some extra padding), and 0.5py or -0.5py to move the line to the top or bottom of the key. The thumbs have a -0.75px shift since they're larger than the standard key.

This isn't an end-all-beat-all outline design method. It's just one example technique of using polygons to draw a shape that roughly outlines your board. Identifying which keys you want to be the outer edge of your outline and then figuring out how you need to shift those points to the edge can be a useful way of quickly create a rough outline of your board.

outlines:
  raw: ...
  keys: ...
  board:
    - what: polygon
      operation: stack
      points:
        ...
      fillet: 2

Now that we've got our outline, let's put a bit of polish on it. fillet: 2 will round the corners of the outline and give it less of a jagged look. A larger fillet value will give you a larger curve.

The last step here is to make sure everything actually fits. Let's create one last outline to do just that.

outlines:
  raw: ...
  keys:
    - what: rectangle
      where: true
      bound: false
      size: [kx-0.5,ky-0.5]
  board:
    - what: polygon
      operation: stack
      points: ...
      fillet: 2
  combo:
    - name: board
    - operation: subtract
      name: keys

The combo: outline has some new syntax. Rather than defining a new outline, we're going to combine two previous outlines. In this case, we've subtracted the keys shape from the inside of the board shape.

You can also use - operation: add to combine two outlines together. If we had decided to use the raw outline earlier, instead of creating our large board shape, we could have just defined a simplistic middle shape to bridge the gap between the two halves. Connecting matrix_inner_num, mirror_matrix_inner_num, mirror_matrix_index_mod, and matrix_index_mod probably would have done the trick. Ergogen v3 had a glue syntax to help streamline this process but it's been depreciated with v4.

units:
  kx: cx
  ky: cy
  px: kx + 4
  py: ky + 4

Our board outline is looking pretty tight. Err, not in the slang meaning of things. The edge of the PCB were really close to the switches. Now is where we can really let those units: values we set earlier shine. Changing px and py to +4 instead of +2 immediately gives our board a nice amount of buffer.

points:
  zones:
    matrix: ...
    thumbs: ...
  rotate: -20
  mirror: &mirror
    ref: matrix_inner_num
    distance: 2.5kx
outlines:
  raw: ...
  keys: ...
  board: ...
  combo: ...

Before we wrap up this section, I wanted to take a moment to highlight just how powerful the parametric nature of Ergogen is. We were just able to update the padding on the keyboard outline by updating just two lines of text.

All of this outline creation and key placement is something one could do with enough time and patience in KiCAD. However, since Ergogen boards are defined by an easily adjusted config file, we're not stuck with the layout that we currently have. Now that we've finished laying out our board, we might decide that we want a slightly sharper angle on the board. We could update points.rotate: -15 to points.rotate: -20, giving the board a much more significant angle to it. Just like that, our entire layout has shifted. Rather than needing to lasso a bunch of switches and rejigger a board edge, we just had to change one variable. That's hard to beat.

End of Part 2

units:
  # Proxy Spacing Variables
  kx: cx
  ky: cy
  # Padding Variables
  px: kx + 2
  py: ky + 2
points:
  zones:
    # The primary 6x4 key matrix, plus 3 modifiers.
    matrix:
      # Choc spacing
      key:
        padding: 1ky
        spread: 1kx
      columns:
        # Hide the first two mods and the last mod.
        # Provide a Sofle-like column stagger.
        outer:
          rows.mod.skip: true
        pinky:
          rows.mod.skip: true
        ring:
          key.stagger: 5
        middle:
          key.stagger: 2.5
        index:
          key.stagger: -2.5
        inner:
          rows.mod.skip: true
          key.stagger: -2.5
      rows:
        # Four main rows, one partial row.
        mod:
        bottom:
        home:
        top:
        num:
    # Thumb cluster for Layer and Space keys.
    thumbs:
      # Choc spacing
      key:
        padding: 1ky
        spread: 1kx
      # Place thumbs where the inner mod would go.
      anchor:
        ref: matrix_inner_mod
        shift: [2, -2]
      columns:
        # Fan thumbs out by -15 degrees.
        layer:
          key.splay: -15
        # Spacebar uses a 1.5 wide key.
        space:
          key:
            width: 1.5kx
            splay: 75
            shift: [2.5,-3.25]
      rows:
        # Thumbs only have one row.
        cluster:
  # Mirror keyboard halves with a moderate rotation.
  rotate: -20
  mirror: &mirror
    ref: matrix_inner_num
    distance: 2.5kx
outlines:
  # Pure key outline.
  raw:
    - what: rectangle
      where: true
      size: [px, py]
  # Key outlines with 0.5mm removed to show key overlaps.
  keys:
    - what: rectangle
      where: true
      size: [kx-0.5,ky-0.5]
  # PCB board outline.
  board:
    - what: polygon
      operation: stack
      points:
        - ref: matrix_outer_num
          shift: [-0.5px,0.5py]
        - ref: matrix_ring_num
          shift: [-0.5px,0.5py]
        - ref: matrix_middle_num
          shift: [-0.5px,0.5py]
        - ref: matrix_middle_num
          shift: [0.5px,0.5py]
        - ref: matrix_inner_num
          shift: [0.5px,0.5py]
        - ref: mirror_matrix_inner_num
          shift: [0.5px,0.5py]
        - ref: mirror_matrix_middle_num
          shift: [0.5px,0.5py]
        - ref: mirror_matrix_middle_num
          shift: [-0.5px,0.5py]
        - ref: mirror_matrix_ring_num
          shift: [-0.5px,0.5py]
        - ref: mirror_matrix_outer_num
          shift: [-0.5px,0.5py]
        - ref: mirror_matrix_outer_bottom
          shift: [-0.5px,-0.5py]
        - ref: mirror_matrix_ring_mod
          shift: [-0.5px,-0.5py]
        - ref: mirror_thumbs_layer_cluster
          shift: [-0.5px,-0.5py]
        - ref: mirror_thumbs_space_cluster
          shift: [-0.5py,-0.5px]
        - ref: thumbs_space_cluster
          shift: [-0.5py,-0.5px]
        - ref: thumbs_layer_cluster
          shift: [-0.5px,-0.5py]
        - ref: matrix_ring_mod
          shift: [-0.5px,-0.5py]
        - ref: matrix_outer_bottom
          shift: [-0.5px,-0.5py]
      fillet: 2
  # Combination preview showing outline and keys.
  combo:
    - name: board
    - operation: subtract
      name: keys

On that note, that's the end of Part 2! We created an outline for our PCB, and have demonstrated the utility of the Units section we created in Part 1. Now we can finally start defining our actual PCB. Join us for the next step over in: Let's Build A Keyboard With Ergogen v4: PCBs (Part 3)!

Welcome back! Hopefully by now you've read the introductory post to this series. If not: Howdy! We're walking through how to design a keyboard using the Ergogen ergonomic keyboard layout generator. In Part 1 of this guide we'll be defining some useful units for our keyboard and creating the points that comprise it's layout.

If you haven't already, navigate to ergogen.xyz and clear out the contents of the left side of the page. Go ahead and open up a text editor on your system and create a backup your-keyboard-name.yaml file. Each code block in this guide will iterate on the previous block. Feel free to follow along on ergogen.xyz. I'll post the current full Ergogen config file at the end of each part of this series.

Update: Ceoloide's done an incredible job of updating the web based version of Ergogen. It now features the ability to import external footprints, KiCAD previews, Github integration, and more. Previous versions of this guide referenced the ergogen.ceoloide.com version of the site, but all of his changes have been rolled back into the official ergogen.xyz site.

Set Up Your Units

Before we get into the config file proper, we should set up some useful variables. Ergogen uses the metric system and any number without a unit behind it is understood to be in millimeters. padding: 4 describes a key with 4mm of padding for example. (The one large exception to this is rotation properties, where numbers without units are describing degrees of rotation.)

There's a few magic numbers that are repeated frequently when designing a keyboard. Cherry MX keys are 19mm x 19mm, and Kailh Choc keys are 18mm wide and 17mm tall. There's nothing stopping you from using spread: 19mm throughout your config file, but Ergogen provides us with a few useful default units to reference these frequently used numbers. The lowercase u unit provides you a quick reference to the MX switch's 19mm, while a capital U represents 19.05mm for keycaps that need a bit more breathing room. Over on the Kailh side of things, Choc keys have cx and cy to quickly reference the 18mm width and 17mm height of these rectangular keys.

These units can be mixed with common math operations. spread: u defines a spread with a standard MX spacing, spread: 1.5u defines a spread of one and a half MX keys, and spread: u + 2 defines a standard MX spread with an extra 2mm of space.

u, U, cx, and cy come built into Ergogen by default, but we're not limited to just these units. The units: section at the top of your config allows you to create your own custom variables. Let's go ahead and create a units: section now and set up some proxy units.

units:
  # Proxy Spacing Variables
  kx: cx
  ky: cy
  # Padding Variables
  px: kx + 2
  py: ky + 2

Ergogen's built in units are great, but they're a pain to update if you realize you want to globally adjust some aspect of your board. If you'd like to take an MX spaced layout to a Choc spaced layout, you can't just find-replace the u character throughout your project. You can save your future self some trouble by creating a pair of "proxy" kx and ky variables pointing to whatever Ergogen default you'd like to leverage. We're designing a Choc spaced board today, so let's define our proxy variables to kx: cx and ky: cy. In the future if we want to adjust this board to an MX layout, all we need to do is update these variables to kx: u and ky: u.

We'll show off the power of units a bit later in this guide. While we're here though, let's go ahead and define some slightly padded values of our standard width and height. px: kx + 2 (20mm) and py: ky + 2 (19mm) will help us down the road when we're trying to come up with the outline for our PCB.

Get To The Point

Ergogen uses the concept of "Points" to describe where each key in a layout should be placed. A single "Point" describe the [x,y] coordinate at the center of where a key should be placed, as well as an r value describing that key's rotation. A group of points in Ergogen is known as a Zone.

The vast majority of ergonomic keyboards, including the one we're going to build today, leverage a "keyboard matrix". This is a set of rows and columns that allow us to use a dozen pins on our keyboard to read dozens of keys. In keyboard matrix parlance (and uh, general table nomenclature), the up-down groups of keys are a "column", and the left-right groups of keys are a "row".

Let's go ahead and define a few basic rows and columns now. The keyboard we want to build is a knockoff of the Sofle keyboard. It has four complete rows with six keys, a smaller modifier row with four keys, and a thumb. Setting aside the thumb key for the moment, let's build a simple 5 row by 6 column design to start with.

units:
  # Proxy Spacing Variables
  kx: cx
  ky: cy
  # Padding Variables
  px: kx + 2
  py: ky + 2
points:
  zones:
    matrix:
      columns:
        outer:
        pinky:
        ring:
        middle:
        index:
        inner:
      rows:
        mod:
        bottom:
        home:
        top:
        num:

This is about a simple a layout one can get in Ergogen, but let's break down exactly what just happened. The points: section indicates that we're defining the layout of the keyboard itself. The zones: section allows us to define several different "groups" of keys. These can be named anything you'd like. I've gone with matrix in this example since we're defining a keyboard matrix, but you could just as easily name it mykeyboard or steve. An Ergogen keyboard can have multiple zones. We've defined the basic keyboard matrix for now, but we'll come back and add a thumb zone later.

Inside of our matrix:, I've defined column: and row: sections. These are fixed names in Ergogen, and let our config file know how many up-down and left-right key groups we'd like.

The names of the rows and columns themselves aren't fixed. You're often see pinky, ring, middle, index, and inner in community Ergogen configs, but everyone's has their own preferences. I've called the column with my tab key the outer column, but just as often you'll find folks calling it pinky2, stretch, or something similar. Likewise, mod, bottom, home, top, and num are popular row terms, but you can define them as anything you'd like.

Let's create a completely different set of points just to drive this all home.

points:
  zones:
    da_board:
      columns:
        foo:
        bar:
        florp:
        pings:
      rows:
        tom:
        dick:
        harry:

If you're scouring the Ergogen documentation for some property that everyone seems to be using which you can't seem to find the definition of, it's probably a user-definable property name. It may take some time for you to get a feeling for what's a strict name and what's just a community convention.

Back to our original board definition, our matrix currently has a few too many keys. This 5x6 grid is perfectly symmetrical, but we don't want any keys underneath the Left Shift and Z keys. Let's rectify that now.

points:
  zones:
    matrix:
      columns:
        outer:
          rows:
            mod:
              skip: true
        pinky:
          rows.mod.skip: true
        ring:
        middle:
        index:
        inner:
      rows:
        mod:
        bottom:
        home:
        top:
        num:

There we go! We're still missing a thumb, but our weird ergonomic keyboard is starting to take shape. As you can see I- Wait, what the heck? I used two completely different methods of hiding those keys!

We're adding our first real property to this board and I'm already introducing some YAML shortcuts. As you can see with the outer: column, we've added a new rows: attribute. This tells the config, "Hey, I'm going to start defining properties pertaining to the intersection of the outer column and a specific row." Nesting mod: underneath rows: lets Ergogen know we're specifically targeting the key at the overlap of the outer column and the mod row. Finally we can get to the actual property at hand. skip: true lets Ergogen know that we'd like to skip adding an outer-mod key to our layout.

This one property takes up a decent amount of space in our config. We had to nest skip: true inside of mod: inside of rows:. Rather than having to type all that out and make an increasingly nested file, we can leverage YAML's dot notation. In the pinky: column, you can see that we simply use rows.mod.skip: true to achieve the same effect as all those indented attributes. You don't need to use dot notation if you prefer indentations, but it's important to know that folks didn't suddenly decide to use reallyLongVariableNames if you're reading other people's Ergogen configs.

We still need to add a thumb to our keyboard, but it's also looking rather square compared to the original Sofle. The Sofle keyboard has this neat "curl" effect where the keys in each column are slightly staggered to accommodate the shape of one's hand. Let's add a column stagger now.

points:
  zones:
    matrix:
      columns:
        outer:
          rows.mod.skip: true
        pinky:
          rows.mod.skip: true
        ring:
          key:
            stagger: 5
        middle:
        index:
        inner:
      rows:
        mod:
        bottom:
        home:
        top:
        num:

Our man's moving up in the world! And by "our man", I mean the ring column is shifted up 5mm. Remember, anything without units in Ergogen is understood to be millimeters.

You can use units in these properties as well. Let's send the middle column for a ride.

points:
  zones:
    matrix:
      columns:
        outer:
          rows.mod.skip: true
        pinky:
          rows.mod.skip: true
        ring:
          key:
            stagger: 5
        middle:
          key:
            stagger: 2ky
        index:
        inner:
      rows:
        mod:
        bottom:
        home:
        top:
        num:

Dang! Adding key.stagger: 2ky moved the middle column up two whole Choc key heights over the ring column. It's important to note that the stagger property is in relation to the column before it. middle is 2ky taller than our ring column, but our ring column was already 5mm taller than our pinky column. This means that middle is 2ky + 5mm taller than our pinky column. You can also see that index and inner are both in line with middle's last position. The index and inner columns are assumed to have a stagger of 0 right now, so they simply continue from middle's starting position.

Now that we've had our fun, let's create a slightly more reasonable layout.

points:
  zones:
    matrix:
      columns:
        outer:
          rows.mod.skip: true
        pinky:
          rows.mod.skip: true
        ring:
          key:
            stagger: 5
        middle:
          key:
            stagger: 2.5
        index:
          key:
            stagger: -2.5
        inner:
          key:
            stagger: -2.5
      rows:
        mod:
        bottom:
        home:
        top:
        num:

There's our familiar Sofle shape! (I just eyeballed these stagger values based off the existing Sofle keyboard PCBs.) It's worth noting that most properties in Ergogen accept negative values. You may have noticed all these stagger properties are inside of key: attributes. We could collapse these with the same dot notation as before, but our config's still pretty readable at the moment. Now then, before we get to the thumb keys, let's do a little bit of housekeeping.

Choc Spacing

Our board is going to leverage those Kailh Choc switches we mentioned in the units section. Ergogen defaults to using 19mm x 19mm MX switches by default, so we need to add a small change to our config in order to space our keys out correctly.

points:
  zones:
    matrix:
      key:
        padding: 1ky
        spread: 1kx
      columns:
      	...
      rows:
      	...

Tada! Our board looks... weird and cramped. In this step, we went ahead and added a new global key definition to our matrix zone. padding: 1ky defines the vertical space between each key, and spread: 1kx defines the horizontal space between each key. We set up these proxy units as copies of the Choc key sizes, so these attributes give each space 17mm of vertical space, and 18mm of horizontal space.

So why are the top and bottom edges overlapping, and the left and right edges are literally on top of each other? Unfortunately, ergogen.xyz only renders MX-sized 19mm x 19mm key switch as part of its demo.dxf preview. Things might look a little cramped at the moment, but we'll be able to verify our spacing during some of the later steps.

Update! Part 2 of this guide teaches you how to create custom outlines that let you better preview Choc-spaced keys. However, ergogen.xyz now supports custom preview variables! You can set $default_width and $default_height in the units: section to adjust the demo.dxf preview. These variables only adjust the web preview, so the rest of what I previewed in Part 2 is still useful!

Just a quick aside, Ergogen v3 lacked the global key: definition within a zone. The spread: property needed to be applied manually to every column. Just something to keep in mind when browsing old configs.

Splayed Out

The Sofle keyboard we're mimicking sticks to a traditional column stagger. For example's sake however, let's take a look at the popular splay: property.

points:
  zones:
    matrix:
      key: ...
      columns:
        outer:
          rows.mod.skip: true
        pinky:
          key:
            splay: -4
          rows.mod.skip: true
        ring:
          key:
            stagger: 5
        middle:
          key:
            stagger: 2.5
        index:
          key:
            stagger: -2.5
        inner:
          key:
            stagger: -2.5
      rows: ...

Splay allows you to angle an entire row of keys. In this case, we used key.splay: -4 inside of the pinky: column to angle it four degrees to the right. Again, you can use positive or negative degrees here. This property is traditionally used when angling pinky keys out to the side of the keyboard. Much like stagger, columns next to a splayed column will continue to be aligned to that angle.

points:
  zones:
    matrix:
      key: ...
      columns:
        outer:
          key:
            splay: 8
          rows.mod.skip: true
        pinky:
          key:
            splay: -4
          rows.mod.skip: true
        ring:
          key:
            splay: -4
            stagger: 5
        middle:
          key:
            stagger: 2.5
        index:
          key:
            stagger: -2.5
        inner:
          key:
            stagger: -2.5
      rows: ...

Ergogen makes it nice and easy to achive splayed out pinky nirvana.

points:
  zones:
    matrix:
      key: ...
      columns:
        outer:
          key:
            splay: 8
          rows.mod.skip: true
        pinky:
          key:
            splay: -4
          rows.mod.skip: true
        ring:
          key:
            splay: -4
            stagger: 5
        middle:
          key:
            stagger: 2.5
        index:
          key:
            stagger: -2.5
        inner:
          key:
            rotate: -4
            stagger: -2.5
      rows: ...

Another v3 to v4 migration note worth calling attention to is that v3's rotate property was renamed to splay. v4 has it's own new rotate property which works slightly differently. In Ergogen v4, splay rotates a column as a single group, and rotate curves the keys out in a fan like approach. You can see it in the inner.key.rotate: -4 section of this latest example.

Now that we've given a quick demonstration of splay, let's get back to our Sofle-inspired design. Once you've deleted the splay and rotate examples, we can finally tackle the thumbs.

Thumbs Up

Ergonomic mechanical keyboards will often include a section known as a "thumb cluster" or a "thumb fan". The Sofle layout doesn't have a significant cluster of keys around the user's thumb, but the layer key and the spacebar key do have a slight curve to them. In this section we'll be defining and aligning this new thumb cluster, but first a bit of house keeping.

points:
  zones:
    matrix:
      key:
        padding: 1ky
        spread: 1kx
      columns:
        outer:
          rows.mod.skip: true
        pinky:
          rows.mod.skip: true
        ring:
          key.stagger: 5
        middle:
          key.stagger: 2.5
        index:
          key.stagger: -2.5
        inner:
          rows.mod.skip: true
          key.stagger: -2.5
      rows:
        mod:
        bottom:
        home:
        top:
        num:

To start with, let's hide the inner column's mod key. This will give us room to place our curved thumb keys.

This config file's getting a little long now, so may haven noticed ... in the code blocks a few times now. That's just shorthand for collapsing something we covered in an earlier section. (The line numbering may get a little wonky, try not to worry about it too much.)

points:
  zones:
    matrix:
      key: ...
      columns:
        outer: ...
        pinky: ...
        ring: ...
        middle: ...
        index: ...
        inner: ..
      rows:
        mod:
        bottom:
        home:
        top:
        num:
    thumbs:
      key:
        padding: 1ky
        spread: 1kx
      columns:
        layer:
        space:
      rows:
        cluster:

Now this is interesting. I've gone ahead and defined a second zone of keys. thumbs: is another user-definable name. This is a particular small two-by-one group of keys. I've gone ahead and called the columns space and layer, and given the row a name of cluster. Technically with a one row layout like this you can omit the rows section entirely if you want to make your config a smaller. I've also added a key section with the same Choc spacing defaults.

I never told Ergogen where to put these keys, so it just defaulted to inserting them into the first free space it could find at the bottom left of the layout. It's a little hard to see which two keys are part of our cluster. Let's move them around for a better view.

points:
  zones:
    matrix:
      key: ...
      columns:
        outer: ...
        pinky: ...
        ring: ...
        middle: ...
        index: ...
        inner: ...
      rows:
        mod:
        bottom:
        home:
        top:
        num:
    thumbs:
      key:
        padding: 1ky
        spread: 1kx
      columns:
        layer:
        space:
      rows:
        cluster:
          shift: [0, -2ky]

Ergogen provides us some convenient methods for shifting keys around. In this most recent example, I moved the entire row two whole key heights lower than its default position. Now we can more easily see the thumb zone that we just defined. If we wanted to get it over towards the thumb area I could just use shift: [5kx,0] to move it over five key lengths, but Ergogen provides a better method of placing keys.

points:
  zones:
    matrix:
      key: ...
      columns:
        outer: ...
        pinky: ...
        ring: ...
        middle: ...
        index: ...
        inner: ...
      rows:
        mod:
        bottom:
        home:
        top:
        num:
    thumbs:
      key:
        padding: 1ky
        spread: 1kx
      anchor:
        ref: matrix_inner_mod
        shift: [2, -2]
      columns:
        layer:
        space:
      rows:
        cluster:

Here's a new property and a new syntax. The anchor property tells Ergogen where the starting point for this zone should be. ref: is pretty straightforward. It's a reference of where the anchor should be placed. matrix_inner_mod is something we haven't seen yet though. This is Ergogen's way of referencing a specific point (AKA a key) on our keyboard. The first part refers to the key's zone (matrix in this case), then the next part of the variable is the key's column, and finally the last section is the row. Keep in mind all three of these variables are user-definable, so if you see some underscore-separated variables in other people's configs with terms that you don't recognize, it's because they chose those names for their specific config. In this example, we've placed the anchor position for the thumb keys where our hidden matrix_inner_mod key would have gone.

points:
  zones:
    matrix:
      key: ...
      columns: ...
      rows: ...
    thumbs:
      key:
        padding: 1ky
        spread: 1kx
      anchor:
        ref: matrix_inner_mod
        shift: [2, -2]
      columns:
        layer:
        space:
      rows:
        cluster:

Let's give our thumbs a bit of breathing room for the next step. Ergogen properties can be used throughout your config where they makes sense. In this case, let's shift our anchor over 2mm and down 2mm.

points:
  zones:
    matrix:
      key: ...
      columns: ...
      rows: ...
    thumbs:
      key:
        padding: 1ky
        spread: 1kx
      anchor:
        ref: matrix_inner_mod
        shift: [2, -2]
      columns:
        layer:
          key:
            splay: -15
        space:
      rows:
        cluster:

Here we've added a -15 degree splay to our layer key. The space key continues off this new rotated position.

points:
  zones:
    matrix:
      key: ...
      columns: ...
      rows: ...
    thumbs:
      key:
        padding: 1ky
        spread: 1kx
      anchor:
        ref: matrix_inner_mod
        shift: [2, -2]
      columns:
        layer:
          key:
            splay: -15
        space:
          key:
            splay: -15
      rows:
        cluster:

This time we'll also add a -15 degree splay to the space key. It's looking good, but it's not quite aligned yet. There's a lot of overlap between these two keys.

points:
  zones:
    matrix:
      key: ...
      columns: ...
      rows: ...
    thumbs:
      key:
        padding: 1ky
        spread: 1kx
      anchor:
        ref: matrix_inner_mod
        shift: [2, -2]
      columns:
        layer:
          key:
            splay: -15
        space:
          key:
            splay: -15
            shift: [2,-2]
      rows:
        cluster:

There we have it! We'll need to double check when we have a true Choc layout preview later,  but this seems like a pretty good first draft. All the shift column needed was a quick shift: [2, -2] to shift the key over 2mm and down 2mm. We're just about there, but our spacebar doesn't look quite right just yet. The Sofle uses a 1.5 width key for the spacebars. Thankfully Ergogen has just such the property for us.

points:
  zones:
    matrix:
      key: ...
      columns: ...
      rows: ...
    thumbs:
      key:
        padding: 1ky
        spread: 1kx
      anchor:
        ref: matrix_inner_mod
        shift: [2, -2]
      columns:
        layer:
          key:
            splay: -15
        space:
          key:
          	width: 1.5kx
            splay: -15
            shift: [2,-2]
      rows:
        cluster:

Whoops. We've got 1.5 wide keycaps, but we need a 1.5 tall keycap here. It turns out the nice thing about working with rectangular components is that you can rotate them pretty easily. -15 degrees + 90 degrees is 75 degrees. Let's update that splay now.

units:
  kx: cx
  ky: cy
  px: kx + 2
  py: ky + 2
points:
  zones:
    matrix:
      key:
        padding: 1ky
        spread: 1kx
      columns:
        outer:
          rows.mod.skip: true
        pinky:
          rows.mod.skip: true
        ring:
          key.stagger: 5
        middle:
          key.stagger: 2.5
        index:
          key.stagger: -2.5
        inner:
          rows.mod.skip: true
          key.stagger: -2.5
      rows:
        mod:
        bottom:
        home:
        top:
        num:
    thumbs:
      key:
        padding: 1ky
        spread: 1kx
      anchor:
        ref: matrix_inner_mod
        shift: [2, -2]
      columns:
        layer:
          key.splay: -15
        space:
          key:
            width: 1.5kx
            splay: 75
            shift: [2,-2]
      rows:
        cluster:

There's our completed layout! We've gone from zero to ergonomic keyboard keyboard in under 50 lines of text. Of course, this is just one half of the keyboard. We still need to figure out where we're going to go from here.

To Split or Not To Split?

Split keyboards are popular in the ergonomic keyboard space. Since they're two separate pieces, you can pull them apart and place them wherever makes the most sense on your desk. There's a bit more complexity involved however. You need to bridge the two halves of the keyboard with a headphone-style TRRS jack or incorporate wireless capabilities into your design. Additionally, many split designs also rely on a "reversible" PCB design. This lets you use the same circuit board for both the left and right half of the keyboard, but introduces some complexity into routing all the traces on the board.

For simplicity's sake, I'm going to stick with a single piece unibody design for this keyboard. Each half of the keyboard be a part of the same PCB, with the microcontroller resting in the middle. This will make the rest of the examples a bit easier to follow, but that means we only have a single half of our keyboard at the moment. Let's rectify that.

points:
  zones:
    matrix:
      key: ...
      columns: ...
      rows: ...
    thumbs:
      key: ...
      anchor: ...
      columns:
        layer: ...
        space: ...
      rows:
        cluster: ...
  mirror: &mirror
    ref: matrix_inner_num
    distance: 2.5kx

Mirror mirror on the config, who's the fairest of them all? Adding a mirror section immediately creates a flipped copy of your board. The ref and distance properties are used for placement. In this case, the two matrix_inner_num keys are 2.5 key widths apart. Everything's looking good so far, but let's see if we can make the board a bit more ergonomic. That is ostensibly why we're here after all.

points:
  zones:
    matrix:
      key: ...
      columns: ...
      rows: ...
    thumbs:
      key: ...
      anchor: ...
      columns:
        layer: ...
        space: ...
      rows:
        cluster: ...
  rotate: -15
  mirror: &mirror
    ref: matrix_inner_num
    distance: 2.5kx

Adding rotate: -15 into our points section rotates our entire keyboard by -15 degrees. Since we've mirrored the keyboard, the other side has been rotated 15 degrees to match.

End of Part 1

units:
  # Proxy Spacing Variables
  kx: cx
  ky: cy
  # Padding Variables
  px: kx + 2
  py: ky + 2
points:
  zones:
    # The primary 6x4 key matrix, plus 3 modifiers.
    matrix:
      # Choc spacing
      key:
        padding: 1ky
        spread: 1kx
      columns:
        # Hide the first two mods and the last mod.
        # Provide a Sofle-like column stagger.
        outer:
          rows.mod.skip: true
        pinky:
          rows.mod.skip: true
        ring:
          key.stagger: 5
        middle:
          key.stagger: 2.5
        index:
          key.stagger: -2.5
        inner:
          rows.mod.skip: true
          key.stagger: -2.5
      rows:
        # Four main rows, one partial row.
        mod:
        bottom:
        home:
        top:
        num:
    # Thumb cluster for Layer and Space keys.
    thumbs:
      # Choc spacing
      key:
        padding: 1ky
        spread: 1kx
      # Place thumbs where the inner mod would go.
      anchor:
        ref: matrix_inner_mod
        shift: [2, -2]
      columns:
        # Fan thumbs out by -15 degrees.
        layer:
          key.splay: -15
        # Spacebar uses a 1.5 wide key.
        space:
          key:
            width: 1.5kx
            splay: 75
            shift: [2,-2]
      rows:
        # Thumbs only have one row.
        cluster:
  # Mirror keyboard halves with a moderate rotation.
  rotate: -15
  mirror: &mirror
    ref: matrix_inner_num
    distance: 2.5kx

That does it for Part 1 of this guide! You can see now how powerful Ergogen can be for rapidly iterating on custom keyboard designs. Adding or subtracting rows is as easy as tweaking a line of text, and unit variables provide us with a flexible design we can redefine over time.

Now that we've got the basic layout defined, stay tuned for: Let's Design A Keyboard With Ergogen v4: Outlines (Part 2).

Howdy and welcome to a new series on ergonomic mechanical keyboard design! Over the course of the next few articles, I'm going to walk through the process of creating an ergonomic keyboard design from scratch using the Ergogen keyboard layout generator. The end result will be a PCB design file we can finish in KiCAD before sending off to a PCB fabricator.

Ergogen is a one of those passion project that has really grow into its own. It began as a tool to aid Dénes Bán in the development of his Absolem keyboard. After aiding Bán in the creation of one specific keyboard, but he suddenly found himself in possession of a tool that could allow anyone to create any keyboard layout. Over the course of the next three years, Ergogen has evolved from an opinionated set of scripts for one user to a project with a dedicated following.

The keyboard designed in this series will be the second full keyboard I've created in Ergogen. I'm by no means as prolific as a Ben Vallack in this space, but I enjoyed the process of creating my first keyboard enough to put a bit of extra work in when it came to documenting the creation of this next one. This is by no means meant to be a set of comprehensive documentation for Ergogen, and is instead designed primarily to give readers a basic understanding of what the tool's like to use.

I have been planning writing this set of articles for a while now. Ergogen's a nice piece of software to work with, but it can have something of a rocky onboarding process. Depending on what you're looking to do, you often need to reference the tool's documentation, various YouTube guides, and an assortment of best-practice GitHub repos. I'm still carrying a torch for long form written how-tos, but what really lit a fire under me was the release of Ergogen v4.

Ergogen v4 made several breaking changes to Ergogen's syntax. Now in addition to piecing together the required info, you also need to parse those pieces through the v4 migration guide. It's a lot, and I know I would have appreciated an end-to-end example when getting started with Ergogen.

So here you go.

A Bit Of Background

Let's back up for a second. This series is a design guide for how to create your own custom ergonomic mechanical keyboard. If you're not quite sure what those are, I recommend taking a look at my review of the Sofle Choc keyboard. The review is ostencibly about one specific keyboard, but the writeup ballooned in scope and the first half serves as a general zero-to-ergonomic-mechanical-keyboards introduction.

Most importantly, it covered many of the aspects that seperate standard mechanical keyboards from their "ergonomic" counterparts. Ergogen is an opinionated tool, and it's designed primarily to create ergonomic "column stagger" layouts. That is to say, keyboards where all of the keys in a particular column (1-Q-A-Z, etc.) are aligned together in a straight line. You can technically force Ergogen to do a classic row stagger, but it's not what it was built for and other tools may be better suited for traditional keyboard layouts.

So if some of the terms used in this guide seem a bit confusing, I highly recommend going back and checking out that Sofle Choc review. Additionally, /r/ergomechkeyboards is a good resource to discover what's going on in this particular niche of clacky keyboards. Like most things in 2023, Ergogen also has an active Discord for specific questions.

So What Is Ergogen?

Whoops. I probably should have explained that earlier. Ergogen, as per it's Github page, "aims to provide a common configuration format to describe ergonomic 2D layouts and generate automatic plates, cases, as well as un-routed PCBs for them." In it's most simple form, Ergogen is a set of scripts designed to turn text files into keyboard design files. You give it a config file describing a keyboard, and it will output a trace-less PCB file and some .dxf / .stl files you can use to get started when creating a case. Ergogen is designed to get you out of graphical CAD tools and fiddly alignment controls, letting you focus on parametrically defining a keyboard layout down to the last millimeter.

Ergogen config files are based on YAML. For the uninitiated, YAML is a data-serialization language designed to allow actual human beings to author structured data without having to spend too much time fussing around with brackets and quotation marks. (You may know it as "Yet Another Markup Language", although they've recently pivoted to "YAML Ain't Markup Language" to emphasize its focused on structuring data instead of documents.) If you have familiarity with formats like JSON, you should feel right at home with YAML. Just know that in lieu of brackets, YAML uses indentation to indicate grouped blocks of data. If you start getting errors, make sure to double check your tabs or spaces.

Once you have your Ergogen .yaml file ready to go, you need some way to process it. Ergogen is a NodeJS based project, which means it's fairly straightforward to get it running locally on your machine. Once you have Node installed, you just need to run the Node Package Manger's install scrip on your local command line with npm i -g ergogen. After that point, you can parse your local Ergogen file with ergogen input.yaml -o output_folder.

If you don't have Node installed or are generally weary of command lines, there's also a web-based version of Ergogen. This site lets you paste in an Ergogen config file and then download the generated outputs right from your browser. Ergogen community member Cache and Ceoloide have done an excellent job of adding live previews to ergogen.xyz, letting you quickly itterate through layouts during the early parts of your design process. This site has been updated to Ergogen v4, so even longtime Ergogen enthusiasts are starting to make the pivot to the new syntax changes.

Update: Ceoloide's done an incredible job of updating the web based version of Ergogen. It now features the ability to import external footprints, KiCAD previews, Github integration, and more. Previous versions of this guide referenced the ergogen.ceoloide.com version of the site, but all of his changes have been rolled back into the official ergogen.xyz site.

The Anatomy of an Ergogen Config

Creating a new Ergogen config is as simple as opening ergogen.xyz and clearing the text on the left side of the screen. You can also open up your favorite text editor and create your-keyboard-name.yaml. (It's alright, I can give you a minute to think a good name for your new board.) Even if you're going to use the web versions, it's a good idea to save your files offline when you're done tweaking it. The web page will try to keep your edits stored locall in your browser, but you never want to lose hours of work if something goes wrong.

Ergogen has five primary sections:

Units (Covered in Part 1)

This is a short section of your Ergogen config where you can define custom units. If you find yourself constantly using the same numbers over and over in your config, this is where you can assign a variable to them.

Points (Covered in Part 1)

Points is where the real magic happens. A "Point" in Ergogen is the [x,y] position of a single key. So the "Points" section is the place where you actually get to define the custom layout of your keyboard. Rather than having to set an explicit [x,y] position for every key on your board, Ergogen has custom definitions for quickly creating entire columns, rows, and thumb clusters.

Points themselves aren't saved as an Ergogen export, but are used as references for the next few sections.

Outlines (Covered in Part 2)

The Outline section allows users to define the shape of their keyboard. This is done by creating a variety of vector shape definitions. These outlines can reference the points we created earlier, so it's simple to define a shape such as, "Draw a border around all my keys with a 3mm padding on each edge." The outlines defined in this section can be referenced later on by both the PCBs and Cases sections.

Outlines can also be exported by Ergogen as .dxf files that can be use in graphics or CAD applications.

PCBs (Covered in Part 3)

If Points are where the magic happens, PCBs are the star of the show. Creating a circuit board we can send off for manufacturing is the whole reason we're here after all. The PCB section has a few different things going on. First of all, you need to import an outline to give shape to the new PCB. Next you need to assign a variety of component footprints. The Points section defines where each key should go, but we still need to specify what sort of key switch footprint we need on the board. This is also where we can add component definitions and footprints for other parts like the microcontroller and its reset button. Finally, we'll need to define the "Nets" for our components. These are definitions used by the PCB to indicate that Key A needs to connect to Pin B.

PCBs are exported by Ergogen as a KiCAD PCB file. KiCAD typically uses a "Project" structure to organize files. These projects will often include a schematic file defining how components are designed to connect in addition to the PCB file. Since Ergogen has already handled defining these nets, it foregoes the project file and the schematic and only exports the KiCAD PCB file.

Cases (Covered in Part 4)

This last section is entirely optional. Many custom keyboard designs will rely on a bare PCB and apply rubber bumpers directly to the bottom of the circuit board. If you have access to a 3D printer though, it can be nice to add a bit of color and stability to your design. The Cases section allows you to add depth to any of your outlines. You simply define how tall you want the piece to be, and Ergogen will create the associated 3D model.

There are some basic operations for adding and subtract case parts from one another. For example, you can define the bottom plate of your case, define several screw holes, and then subtract the screw hole portions from the bottom plate.

Ergogen v3 previously exported cases files in the .stl lingua franca format of 3D printing. Due to some technical issues with the .stl file creation library, v4 is currently exporting cases as .jscad files. If you'd like to convert these into .stl files, you can use sites like openjscad.xyz or their NPM package.

What Ergogen Doesn't Do For You (Covered in the Finale)

At the end of this process, you'll have an unrouted PCB file. If you've never made a PCB before, routing is the process of drawing traces to connect two points on a circuit board. All those lines criss-crossing a PCB are physical electrical wires. Most importantly, they can't overlap or cross one another.

For geeks who typical work in code, the realities of physics placing limitations on one's project is a jarring discovery. Automatic routing tools exist, but they often come with their own issues or are part of paid CAD software. Connecting all of the components on one's keyboard is like trying to solve a hundred wandering salesmen problems on something slightly larger than an index card.

After Ergogen's done its work, you'll need to roll up your sleeves and start routing your circuit board in KiCAD. KiCAD is a capable piece of open source CAD software, but it's not without its own learning curve. If you used some early versions of GIMP or Inkscape, you'll have a rough idea for the sort of UI you're in for.

Once you've finished routing your board, you can send it off to a PCB fabrication service. KiCAD supports exporting to the industry standard Gerber file format, so you shouldn't have any trouble getting your new keyboard manufactured. Unless you really shell out for express shipping it will take about two weeks for you to receive your new PCBs. That time is in line with many keyboard part sellers, so you can order all the switches, microcontrollers, and keycaps you need at this time.

The last step is creating a keyboard firmware for your new board. The QMK and ZMK open source keyboard firmwares use the same column and row matrix approach as Ergogen so it shouldn't be too difficult to get your new firmware created. There's plenty of existing configurations to reference, and you've got plenty of time to tackle the firmware while your PCBs are waiting to arrive.

What I'll Be Building In This Guide

Good artists borrow, and great artists steal. In this guide, I'm going to be creating a keyboard loosely based off Josef Adamčík's Sofle keyboard. It's a 6x4+5 column staggered layout that I've grown quite fond of, and should be a useful layout to mimic when showing off Ergogen's features. While the Sofle Choc offers a Choc switch compatible version of this keyboard, there isn't a Choc spaced version of the Sofle yet. So this guide's a totally selfish excuse for me to recreate this board with Choc spacing and claim it was for site content. (Update: Adamčík's working on a unibody Choc-spaced Sofle variant now!)

Now that you know what we'll be tackling, let's hop into Ergogen and get started. I'll see you over in Let's Design A Keyboard With Ergogen v4: Units & Points (Part 1).

The ChonkV is a 58-key Choc keyboard based off Brickbot's excellent chocV keyboard. It adds a number row, an additional outer column, and thumb keys in the style of the Atreus keyboard.

This keyboard was designed largely as a way of learning the Ergogen keyboard layout generator software. I was pretty happy with my previous keyboard, the split Sofle Choc, but this new keyboard design allowed me to test a variety of concepts I'd been curious about experimenting with. The ChonkV has the same 58 key count as the Sofle Choc, but its unibody design makes it a bit more portable. This board also has true Choc spacing, and is my first time working with the Nice!Nano wireless microcontroller. While it's not a true ortholinear block, this is my first time dabbling with a board that drops the usual column stagger.

There's a few existing board designs that also may have checked these boxes. The keyboard community has putting out several interesting Reviung variants, and the Atreus also comes close to this design. I've always liked the look of the chocV however, and wanted to try my own spin at the design. This board's not nearly as smol, but I like it. It's chonky. It's a chonky chocV. The ChonkV.

Features

• 58 key layout featuring number rows, outer columns, three modifiers on each side of the keyboard, raise and lower keys, and Atreus-style thumb keys for enter and space.
• Kailh Choc v1 Switches.
• Supports through-hole switch sholdering or Kailh Choc hotswap sockets.
• Choc switch spacing. (Has been bested with MBK keycaps.)
• Designed for the Nice!Nano wireless Microcontroller.
• Also supports the Nice!View display. (Nice!View requires an additional wire to be run from the display's CS pin to one of the Nice!Nano's extra internal pins.)
• JST battery connector.
• RST pushbutton.
• Physical power switch.
• Includes designs for a Horizon/ChocV style PCB backplate as well as a more traditional 3D printed case.

Ergogen Files

Just an FYI for those looking to use this as a reference to learn Ergogen. This library leverages Ergogen 3, and several custom footprints that can be found in my fork repo. Ergogen 4 made several breaking changes to the syntax in December of 2022, so make sure you check which version you're using if you reference these config files for your own project.

chonkv.yaml

This is the main file for the ChonkV PCB. It is designed with choc spacing, and has a 3mm padding around the edge of the keyboard. The microcontroller is mounted in the middle of the keyboard, along with a reset button and JST header. There's a small bit of PCB art by the thumbs. Running this config file through Ergogen will generate the ChonkV PCB, the board's outlines, as well as some 3D printing .stl case files.

chonkv_case.yaml

This file was used in the creation of a fairly straightforward keycoard case. It uses 2M standoffs to support the PCB, and gives it a small border outside of the premiter. This config file is seperate from the main chonkv.yaml due to Ergogen limitations on "glue" outlines. It creates an outline that is a few mm larger than the main PCB file.

Unfortunately, since this case design is split between chonkv.yaml and chonkv_case.yaml, Ergogen can't put together all the finished pieces for us. You'll need to import them into some CAD software like TinkerCAD to get the final design output. Or you can just download it from this repo of course.

One thing you may notice is that the whole for the standoffs goes all the way through the 3D model. This is supposed to be a low profile case, so the metal standoffs are designed to sit flush with the bottom of the case.

chonkv_backplate.yaml

This was a largely failed experiment. The original chocV keyboard included designs for a second inert PCB that would screw onto the bottom of the main PCB to give the board some extra stability and shiled the exposed metal legs of the soldered components. I was always fond of this design, but it was limited to through-hole designs. I came up with some choc hotswap footprints with a cutout for the hotswap sockets, but the resulting cuts were large, complex, and covered most of the board. I haven't tried submitting them to a PCB fab, but I assume they'd try to include an extra charge this backplate. On top of that, the hotswap sockets stick out about 2mm on the bottom of a board, and most PCBs are about 1.8mm thick. I'd like to itterate on this concept some day (or just commit to a through-hole design), but I'm tabling this concept for now.

The backplate design wasn't a complete waste however. I was able to include the backplate design in the 3D printed case I created with chonkv_case.yaml, so the resulting 3D printed case is now a bit more sturdy and less echoy.

Finished Files

If you don't want to go through the build process yourself, you can always download the files found in the "outputs" folder on GitHub. It has a zipped Gerbers file, the complex case .stl, and a simplified case .stl. The .stl files have been split into left and right halves in case you have a 3D printer with a smaller print volume.

Build of Materials

You may be able to get some of the parts cheaper (or at least in bulk) on Aliexpress. 42Keebs has good prices on the Nice!Nano and the Nice!View, and you can pick up a lot of other parts while you're at it. Batteries you'll need to get domestically, and keycap avalability is subject to change. You should be able to build this keyboard for about $225 USD, give or take some shipping costs.

Custom mechanical keyboards have long been split into two camps: Wired keyboards running the open source QMK firmware, and closed source Bluetooth keyboards running a proprietary firmware. Bluetooth support introduces all sorts of messy power requirements, licensing issues, and other technical overhead that historically hasn’t meshed well with the barebones Arduino Pro Micro / ATmega32U4 infrastructure that powers the vast majority of QMK keyboards. There were always high-powered alternatives like the ESP32 microcontroller, but none of them really made inroads into the hobbyist keyboard space.

That is until the Nice!Nano burst onto the scene. It features a Nordic nRF52840 microcontroller with native Bluetooth support, and is low power enough to work in wireless keyboard contexts. The Nice!Nano shares a footprint with the Arduino Pro Micro, meaning it can be used by many of the existing DIY keyboard PCBs.

The one thing it couldn’t take advantage of however is QMK. The popular open source keyboard firmware does not have support for wireless connectivity, and most likely won't be adding it in the future due to a variety of architectural and licensing issues.. This has left wireless enthusiasts to turn to the alternative open source ZMK keyboard firmware. ZMK was built from the ground up with wireless support in mind, and philosophically very similar to QMK. It’s still a relatively new project however, so not every QMK feature has a direct ZMK equivalent.

If you use a ZMK keyboard on multiple operating systems, one such gap you may have run into is the ability to quickly switch your keyboard's hotkeys to match your operating system's paradigm.

OS Hotkey Differences

When Apple and IBM originally designed the keyboards for their systems, they made slightly different decisions when it came to the nomenclature and layout of keyboard modifier keys. IBM (and later every Window-based system) would use Control, Windows, and Alt, while Apple settled on Control, Option, and Command. These keys all send the same codes to the computer, Apple just swaps Alt for Opt, and Win for Cmd. In operating system agnostic instances (or when chatting with Linux folks), Win will sometimes be substituted for GUI or Super.

Besides the names, there's two small differences between systems. Windows machines order their modifier keys Ctrl, Win, Alt, while Macs order their keys Ctrl, Opt, Cmd. This isn't just a slight rejiggering of lesser-used commands either. On Windows machines, Ctrl is the primary hotkey for most common system tasks. On Macs, it's the Cmd key. So "Undo" on a Windows PC is Ctrl+Z, while on a Mac it's Cmd+Z.

Windows users rely on their pinkies for most shortcuts, while Mac users rely on their thumbs. Using Windows (somehow) on a MacBook keyboard is a non-issue, but trying to use MacOS on a Windows keyboard is a terrible experience. The muscle memory for all of your basic hotkeys is broken, and your thumb needs to make an awkward stretch over to the Windows key. It's not a great time.

To rectify this, most keyboard manufactures include some sort of software option or toggle switch which remaps the position of Win and Alt on keyboards. This is generally a great solution, although Windows users will inevitably mix up Cmd and Opt on the rare time they need to use Alt or Win on a Mac-style keyboard.

On ergonomic keyboards like the Sofle Choc I recently reviewed, you'll often find a slightly different situation. These keyboards will typically try to locate several useful modifier keys around the natural resting place for their thumb. If you're on Windows, you set it to Ctrl. If you're on MacOS, you set it to Cmd. If you're regularly switching between different operating systems, it's vital that you have some way of changing the modifier triggered by these thumb keys.

OS Hotkey Switching in QMK

QMK offers exactly this sort of hotkey-switching functionality. Both QMK and ZMK allow users to completely customize their keyboard's layout. If you know you’re going to be spending all of your time on one operating system, you can simply flash a Windows or MacOS style layout to your keyboard. If you’re regularly working with multiple operating systems on the same keyboard however, you need some way of toggling your modifier layout. QMK of course solves this through, what else, a hotkey.

QMK has a set of what it calls “Magic Keycodes” that can alter the current state of a keyboard’s setup. The MAGIC_TOGGLE_ALT_GUI (AG_TOGG) keycode switches the position of Alt and Win/Cmd. Meanwhile, the MAGIC_TOGGLE_CTL_GUI (CG_TOGG) keycode switches the position of Ctrl and Win/Cmd for ergonomic keyboards. Once you've assigned these keycodes to a key on your keyboard (or assigned it to a hotkey combination on a layer), all you need to do is tap the key and it will seamlessly toggle between these two behaviors.

These magic keycodes also come in “Swap” and “Unswap” varieties. Instead of toggling back and forth, these commands allow you to create dedicated “MacOS” or “Windows” hotkeys on your keyboard. The toggle behavior is usually enough for basic setups, by the swap and unswap behaviors can be useful for including in macros.

Overall it’s a nice straightforward piece of functionality. If you’re swapping systems frequently, working with cross-OS virtual machines, or using a KVM, these magic keycodes help keep your keyboard in line with your operating system. If your keyboard has a display, you can even reference its current state on the display.

OS Hotkey Switching in ZMK

ZMK currently does not have any out of the box support for hotkey switching. Thankfully it’s fairly easy to fake QMK’s magic keycode toggle behavior. What we’d like to do is be able to have the keyboard provide one set of modifier behavior, tap a single keycode, and then have the keyboard exhibit a different set of modifier behavior from that point forward. We can accomplish this by getting a little creative with layers.

keymap {
  compatible = "zmk,keymap";

  default_layer {
    bindings = <
      &kp GRAVE &kp N1 &kp N2    &kp N3   &kp N4   &kp N5                   &kp N6 &kp N7   &kp N8    &kp N9    &kp N0   &kp MINUS
      &kp ESC   &kp Q  &kp W     &kp E    &kp R    &kp T                    &kp Y  &kp U    &kp I     &kp O     &kp P    &kp BSPC
      &kp TAB   &kp A  &kp S     &kp D    &kp F    &kp G                    &kp H  &kp J    &kp K     &kp L     &kp SEMI &kp SQT
      &kp LSHFT &kp Z  &kp X     &kp C    &kp V    &kp B                    &kp N  &kp M    &kp COMMA &kp DOT   &kp FSLH &kp RSHFT
                       &kp LCTRL  &kp LALT &kp LGUI &mo 1  &kp RET &kp SPACE &mo 2  &kp RGUI &kp RALT  &kp RCTRL
    >;
  };

  lower_layer {
    bindings = <
      &trans &kp F1    &kp F2    &kp F3      &kp F4   &kp F5                 &kp F6    &kp F7   &kp F8    &kp F9    &kp F10  &kp F11
      &trans &kp N1    &kp N2    &kp N3      &kp N4   &kp N5                 &kp N6    &kp N7   &kp N8    &kp N9    &kp N0   &kp F12
      &trans &kp EXCL  &kp AT    &kp HASH    &kp DLLR &kp PRCNT              &kp CARET &kp AMPS &kp ASTRK &kp LPAR  &kp RPAR &kp PIPE
      &trans &kp EQUAL &kp MINUS &kp KP_PLUS &kp LBRC &kp RBRC               &kp LBKT  &kp RBKT &kp SEMI  &kp COLON &kp BSLH &trans
                       &trans    &trans      &trans   &trans   &trans &trans &mo 3     &trans   &trans    &trans
    >;
  };

  upper_layer {
    bindings = <
      &trans &trans  &trans    &trans      &trans &trans                 &trans    &trans   &trans   &trans    &trans &trans
      &trans &kp INS &kp PSCRN &kp K_CMENU &trans &kp SLCK               &kp PG_UP &trans   &kp UP   &trans    &trans &kp DEL
      &trans &trans  &trans    &trans      &trans &kp CLCK               &kp PG_DN &kp LEFT &kp DOWN &kp RIGHT &trans &trans
      &trans &trans  &trans    &trans      &trans &trans                 &trans    &kp HOME &trans   &kp END   &trans &trans
                     &trans    &trans      &trans &mo 3    &trans &trans &trans    &trans   &trans   &trans
    >;
  };

  mod_layer {
    bindings = <
      &bt BT_CLR  &bt BT_SEL 0 &bt BT_SEL 1 &bt BT_SEL 2 &bt BT_SEL 3 &bt BT_SEL 4               &trans &trans       &trans     &trans       &trans &trans
      &kp K_SLEEP &mac_bt      &win_bt      &trans       &trans       &trans                     &trans &trans       &trans     &trans       &trans &trans
      &tog 1      &trans       &trans       &trans       &trans       &trans                     &trans &kp C_VOL_DN &kp C_MUTE &kp C_VOL_UP &trans &trans
      &trans      &trans       &trans       &trans       &trans       &trans                     &trans &kp C_PREV   &kp C_PP   &kp C_NEXT   &trans &trans
                               &trans       &trans       &trans       &trans       &trans &trans &trans &trans       &trans     &trans
    >;
  };
};

For this example, let’s assume we’ve got a fairly standard multi-layer setup. The base layer is a straightforward QWERTY layer, then the user has a Symbol layer for special characters, a Navigation layer for arrow keys, and an Adjustment layer for things like managing Bluetooth profiles.

In this example, the user has set their keyboard with a Mac-style Ctrl, Opt, Cmd layout by default. First, let’s add a Windows-specific layer. Copy your base QWERTY layer and swap the Ctrl and Cmd hotkeys.

keymap {
  compatible = "zmk,keymap";

  default_layer {
    bindings = <
      &kp GRAVE &kp N1 &kp N2    &kp N3   &kp N4   &kp N5                   &kp N6 &kp N7   &kp N8    &kp N9    &kp N0   &kp MINUS
      &kp ESC   &kp Q  &kp W     &kp E    &kp R    &kp T                    &kp Y  &kp U    &kp I     &kp O     &kp P    &kp BSPC
      &kp TAB   &kp A  &kp S     &kp D    &kp F    &kp G                    &kp H  &kp J    &kp K     &kp L     &kp SEMI &kp SQT
      &kp LSHFT &kp Z  &kp X     &kp C    &kp V    &kp B                    &kp N  &kp M    &kp COMMA &kp DOT   &kp FSLH &kp RSHFT
                       &kp LCTRL  &kp LALT &kp LGUI &mo 2  &kp RET &kp SPACE &mo 3  &kp RGUI &kp RALT  &kp RCTRL
    >;
  };
      
  win_layer {
    bindings = <
      &kp GRAVE &kp N1 &kp N2   &kp N3   &kp N4    &kp N5                   &kp N6 &kp N7    &kp N8    &kp N9    &kp N0   &kp MINUS
      &kp ESC   &kp Q  &kp W    &kp E    &kp R     &kp T                    &kp Y  &kp U     &kp I     &kp O     &kp P    &kp BSPC
      &kp TAB   &kp A  &kp S    &kp D    &kp F     &kp G                    &kp H  &kp J     &kp K     &kp L     &kp SEMI &kp SQT
      &kp LSHFT &kp Z  &kp X    &kp C    &kp V     &kp B                    &kp N  &kp M     &kp COMMA &kp DOT   &kp FSLH &kp RSHFT
                       &kp LGUI &kp LALT &kp LCTRL &mo 2  &kp RET &kp SPACE &mo 3  &kp RCTRL &kp RALT  &kp RGUI
    >;
  };

  lower_layer {
    bindings = <
      &trans &kp F1    &kp F2    &kp F3      &kp F4   &kp F5                 &kp F6    &kp F7   &kp F8    &kp F9    &kp F10  &kp F11
      &trans &kp N1    &kp N2    &kp N3      &kp N4   &kp N5                 &kp N6    &kp N7   &kp N8    &kp N9    &kp N0   &kp F12
      &trans &kp EXCL  &kp AT    &kp HASH    &kp DLLR &kp PRCNT              &kp CARET &kp AMPS &kp ASTRK &kp LPAR  &kp RPAR &kp PIPE
      &trans &kp EQUAL &kp MINUS &kp KP_PLUS &kp LBRC &kp RBRC               &kp LBKT  &kp RBKT &kp SEMI  &kp COLON &kp BSLH &trans
                       &trans    &trans      &trans   &trans   &trans &trans &mo 4     &trans   &trans    &trans
    >;
  };

  upper_layer {
    bindings = <
      &trans &trans  &trans    &trans      &trans &trans                 &trans    &trans   &trans   &trans    &trans &trans
      &trans &kp INS &kp PSCRN &kp K_CMENU &trans &kp SLCK               &kp PG_UP &trans   &kp UP   &trans    &trans &kp DEL
      &trans &trans  &trans    &trans      &trans &kp CLCK               &kp PG_DN &kp LEFT &kp DOWN &kp RIGHT &trans &trans
      &trans &trans  &trans    &trans      &trans &trans                 &trans    &kp HOME &trans   &kp END   &trans &trans
                     &trans    &trans      &trans &mo 4    &trans &trans &trans    &trans   &trans   &trans
    >;
  };

  mod_layer {
    bindings = <
      &bt BT_CLR  &bt BT_SEL 0 &bt BT_SEL 1 &bt BT_SEL 2 &bt BT_SEL 3 &bt BT_SEL 4               &trans &trans       &trans     &trans       &trans &trans
      &kp K_SLEEP &mac_bt      &win_bt      &trans       &trans       &trans                     &trans &trans       &trans     &trans       &trans &trans
      &tog 1      &trans       &trans       &trans       &trans       &trans                     &trans &kp C_VOL_DN &kp C_MUTE &kp C_VOL_UP &trans &trans
      &trans      &trans       &trans       &trans       &trans       &trans                     &trans &kp C_PREV   &kp C_PP   &kp C_NEXT   &trans &trans
                               &trans       &trans       &trans       &trans       &trans &trans &trans &trans       &trans     &trans
    >;
  };
};

At this point, you should have the following layers:

• Layer 0: Mac
• Layer 1: Windows
• Layer 2: Symbol
• Layer 3: Navigation
• Layer 4: Adjust

Go ahead and update your Raise and Lower keys to skip over the Windows layer for now. The left thumb should go straight to Layer 2, and your right thumb should go to Layer 3. They're the &mo 2 and &mo 3 commands you see in the center of each keymap.

At this point, your keyboard should be working as it usually does. The Windows layer exists, but it’s being completely ignored. The Symbol, Nav, and Adjust layers are being applied on top of your Mac layer.

So what we need to do now is somehow swap out the base Layer 0 Mac layer with the Layer 1 Windows layer. Thankfully, ZMK has support for this. Its “Toggle Layer” keycode enables a layer until the layer is manually disabled. Critically however, this still allows you to use the standard “Momentary Layer” behavior to get to your Symbol, Nav, and Adjust layers.

Add a &tog 1 keycode to an unused key on your keymap. The `Tab` key on the Adjust layer is usually a good candidate. (You can see I already went ahead and did that on the earlier code embed.)

Now if you press Raise+Lower+Tab, your base layer will shift from Layer 0 to Layer 1. This can be used for much more advanced keyboard configurations (shifting from Qwerty to Colemak for instance), but in this case the only change we made between these two layers is the order of the modifier keys. Presto, we're now using Ctrl as our primary modifier instead of Cmd. The thumb keys are still configured to &mo 2 and &mo 3, so we can still enable the Symbol, Nav, and Adjust layers. To switch back to Mac-style keys, simply press Raise+Lower+Tab again.

This approach does have a few limitations over QMK. First and foremost, the keyboard will reset back to its default layer when you restart or unplug the device. On QMK, the magic keycodes persist after power cycling. Additionally, you need to create a unique layer to &tog to for each specific behavior you’re looking to implement. If you wanted to simulate bothAG_TOGG and CG_TOGG simultaneously, your layer definitions will start to balloon significantly.

Integrating OS Hotkey Switching With ZMK Bluetooth Profiles

This Raise+Lower+Tab approach works well for situations like virtual machines and KVMs, but what if you’re actually using the bluetooth capabilities of ZMK to switch between two physical Mac and Windows devices? You can press ZMK's &bt BT_SEL keycode and then our &tog command individually, but ZMK's macro capabilities can easily automate this process.

macros {
  mac_bt: mac_bt {
    label = "mac_bt";
    compatible = "zmk,behavior-macro";
    #binding-cells = <0>;
    bindings
      = <&macro_tap &bt BT_SEL 0>
      , <&macro_tap &tog 0>
    ;
  };
  
  win_bt: win_bt {
    label = "win_bt";
    compatible = "zmk,behavior-macro";
    #binding-cells = <0>;
    bindings
      = <&macro_tap &bt BT_SEL 1>
      , <&macro_tap &tog 1>
    ;
  };
};

Define a pair of macros at the top of your keymap file. Assuming your Mac is on BT 0 and your Windows machine is on BT1, you should easily be able to create a mac_bt and win_bt pair of macros to switch to each device. We'll use <&macro_tap> to activate the same exact keycodes as before.

You can replace the original Bluetooth profile hotkeys on your keymap with these macros, but my Adjust layer had plenty of spare keys for them. It's easy enough to slot the macro-version of those commands underneath the original keys. You can call the macros with &mac_bt or &win_bt. (Again, I didn't bother hiding these from our enhanced keymap up above.) You may still want to keep around the original OS toggle hotkey on Tab just in case things get out of sync.

Conclusion

In the absence of official ZMK support for OS modifier switching, these layer tricks should help you straddle the world between operating systems. Hope this helped someone in a similar situation to me!

Say hello to the Sofle Choc. This is Brian Low's low profile variant of Josef Adamčík's Sofle split mechanical keyboard. It features Kailh Choc switches, a staggered column layout, and QMK support. If it’s not already clear, I’ve officially fallen off the deep end of custom keyboards, and I’m dragging you along for the ride.

Mechanical keyboards are having a bit of a moment. There’s always been a passionate undercurrent of techy individuals with strong opinions on the input devices they use daily, but the internet’s finally done its thing and brought these people together. Communities like Reddit’s /r/mechanicalkeyboards and /r/ErgoMechKeyboards/ are more than happy to help ratchet up your level of keyboard nerdery, and there’s dozens of niche Discords for enthusiasts to discuss their latest builds. Even mainstream companies like Logitech and Razer have started to offer up their own takes the latest mechanical keyboard trends for the clacky curious who aren’t looking to lose afternoons to wiki pages and sticky posts.

So, how did we get here? More importantly, where did all my keys go?

The Basics

The subject of mechanical keyboard switches has been detailed extensively, so I’ll try to keep this brief. [Editor's Note: Whoops.] If you haven’t sought out an expensive aftermarket keyboard, you’re most likely typing on your laptop keyboard or whatever came with your last desktop computer in 2006.

Cheap keyboard typically use what’s known as "membrane" or “rubber dome” switches. The keyboard’s manufacturer prints a circuit board with dozens of contact pads on it, and then stretches out a thin piece of conductive rubber on top. When you push down on the plastic key cap, it squishes the rubber against the circuit board, the circuit is closed, and the signal is sent. It’s a cheap and effective way to build a keyboard, but it often feels “mushy”.  It’s not clear when the rubber is actually going to make contact, and it can take a while for things to bounce back.

On the laptop side of things, manufactures employ rather impressive “scissor switches” to build absurdly thin portable keyboards. They’re a marvel of modern industrial design, but they also are generally lacking in the physical feedback department. They key has such little distance between its resting state and its fully pushed position that it can be difficult to tell when a key has been let go and is ready to type again.

Mechanical keyboard switches eschew these cost cutting and miniaturization trends. They take inspiration from the keyboard designs of the early decades of computing and rely on discrete, chunky components. Each key has its own physical switch sporting a large spring mechanism and a noticeable amount of key travel.

The vast majority of mechanical keyboard switches mimic or outright clone the Cherry corporation’s perennial "MX" switch. These keyboard switches are now sold by dozens of manufacturers in a bewildering array of varieties, and choosing the right one for you can be a little intimidating for newcomers.

Mechanical keyboards are perhaps most famous for their “clicky” style key switches. These switches produce an audible "Click!" sound and send a small vibration through the key when the switch has been pushed enough to send its command. Interestingly, mechanical key switches don't require that you push the key down all of the way. Switches only require you push them down about half of their height before the command is actually sent. Once you hear the click, you know you can let go and get ready to press the key again. (Of course, there's nothing stopping you from pushing the key down fully if you'd like.) The immediate physical and audio feedback of clicky MX switches makes them particularly popular with PC gamers.

They are a little difficult to use in close proximity with other human beings however. It's hard to overstate just how loud a clicky keyboard can be once you get deep into a typing session. Most software development teams have a story about someone who tried to bring a clicky keyboard into an open floor plan office with disastrous results. Clicky keyboards are not exactly discrete, which is why the “tactile” switch is a popular alternative.

Tactile switches forego the audible click when the key is activated. Instead they attempt to recreate the physical sensation of the click without any actual noise. Once the key switch has been pushed halfway down, you'll feel a slight "bump" in the key letting you know that the signal has been sent and you can let go of the key. It provides a typing experience similar to a clicky key, but with significantly less noise. Trust me, your desk mates will thank you.

Finally, “linear” switches don’t have any specific behavior halfway through the keypress when the signal is sent. They just have a smooth continuous press, and are generally the most quiet of the bunch. The lack of any physical feedback isn't everyone's cup of tea, but for plenty of typists, just seeing the letter appear on the screen is more than enough. Their understated typing experience is often popular for users making the initial switch over to mechanical keyboards who don't want to adjust to too many changes at once.

Beyond this switch behavior, one needs to decide on how heavy an “activation force” they’d like their keys to have. Switches are usually built with physical springs, and those springs can offer up varying amounts of resistance to the user's key presses. The activation force simply describes how many grams of pressure it takes to overcome this resistance and push a key down. Most manufactures at a minimum offer a “heavy” and “light” option for their key switches. One switch may take 70 grams of force to press, while their lighter option may only takes 50 grams. The more bespoke manufactures will often offer up a wider gradient of weight options.

Those are the two big switch decisions you need to make when buying a mechanical keyboard. What type of behavior do you want your switches to have, and how much resistance do you want them to offer. Manufacturers occasionally will offer some variants based on how noise-dampened the switch is, but generally your decision will just revolve around those two different axis.

You’d be forgiven if things looked far more complicated than that however. Rather than directly printing a switch’s characteristic on the plastic itself, manufacturers typically chose to produce differently colored switch stems in order to tell their different types of keys apart. Blue stems are light and clicky. Clear stems are heavy and tactile. Red stems are light and linear. The myriad of switch color options out there are really just codings for those two more basic choices.

Keyboards are physical objects, and it’s difficult to describe via text or video the merits of one switch over another. When buying your first mechanical keyboard, it's worth trying out a few different key types before you make your decision. This is easy if you have some exceptionally geeky friends with a variety of switch tastes, but generally one just needs to bite the bullet and buy a switch tester with a variety of sample keys. Once you know which switch you’re going to go with, you'll then need to pick your keyboard layout.

Most desktop keyboards are based off a 40 year old IBM PC standard and feature over a hundred keys. (The exact number varies based on where in the world you happen to be.) There’s a lot of residual cruft that’s built up over the years, and there’s arguments to be made that you don’t really need a Pause / Break key on a modern keyboard.

There’s a variety of keyboard layouts which help slim down the classic design. The popular “Tenkeyless” design helps free up some desk space by dropping your keyboard’s number pad. (It doesn't have the ten number pad keys. Ten-key-less. Get it?) Things get a bit more drastic from there. “75%” keyboards take the tenkeyless design and usually pull the arrow keys in for a more compact block, and “65%” designs drop the Function row entirely. Finally, “60%” keyboards take the minimalism and get rid of the arrow keys entirely.

There's endless variety on these basic layouts. A few have been canonized like the tenkeyless, but your keyboard layout of choice will boil down to personal taste. Laptop users may be familiar with ditching the number pad, but a lot of users may be less comfortable with the idea of needing to rely on function keys and modifiers just to tap and arrow key.

There’s no need to do anything too drastic at first. Grab a key switch tester, think about how often you use certain keys, and then buy something prebuilt off the shelf from a company like WASD or Keychron. It’ll set you back about $150 to figure out if these sorts of keyboards are for you. If your starter board starts to go stale, you can even buy a set of cheap keycaps to liven it up.

Getting Geeky

At this point you’ve got a nice sturdy keyboard. It had a few more buying decisions than picking up a Logitech keyboard from Best Buy, but it’s suspiciously close to a standard consumer transaction. Where’s the hobby aspect come into play?

Well, you may have noticed me use the word “prebuilt” to describe the entry level keyboards in the last section. You can buy a keyboard that’s fully assembled and ready to go, but it’s also possible to buy and assemble a keyboard out of individual parts.

A mechanical keyboard is comprised of a few types of components. There’s the microcontroller at the heart of the keyboard, the actual PCB that houses all the keys, the individual key switches, the keycaps for the switches, and often a case for the keyboard.

The primary benefit you get from building your own keyboard from scratch is that you’ve got a much larger pool of switches to chose from. Most prebuilt manufactures only offer a half dozen key options from one or two brands. If you’re assembling your own keyboard, you can start dabbling with boutique key switch manufactures. Companies like ZealPC and Drop specialize in making exceptionally quiet or particularly clicky keys that can fit in any standard MX formfactor board.

The actual DIY boards themselves vary in complexity. Some of them are incredibly straightforward. Many large keyboard manufactures will offer switch-less versions of their most popular boards. You need to add the switches yourself, but everything else is already assembled for you. On the opposite end of the spectrum, boutique manufacturers and hobbyists will use the flexibility of small-batch runs to get experimental with the form factors and feature sets of their keyboards. These boards are usually a bit more barebones, requiring the builder to solder in an Arduino microcontroller and other ancillary support hardware. The scene now has a myriad of RGB LED lit keyboards, split keyboards, and even keyboards with integrated trackpads. As long as you can get past an exorbitant price tag, there’s probably a keyboard out there for you.

Speaking of prices, you know you’re in for trouble when you start hearing phrases like “Artisan Keycaps”. Keycaps are the component that’s the easiest to swap out on a mechanical keyboard, so there are countless keycap sets ready to meet whatever theme or aesthetic you’re going for.

…eventually. The hobbyist keycap scene often works on a group buy model. Buyers will pool their money together and preorder a keycap set before the manufacturing process has actually begun. Popular keycap sets will often go out of stock for the better part of the year, or occasionally only ever get one print run.

In addition to different color schemes, keycaps can also offer several different shape options for DIY keyboards. These "profiles" range from the familiar sloped shapes you've likely experienced the vast majority of keyboards you've encountered, to a more flat keyboard shapes for those looking to switch things up. (If you're trying to find your off the shelf keyboard's profile on the diagram, chances are you're on a Cherry or OEM board.)

Finally, many keyboards will offer a case. These can be simple pieces of plastic, machined aluminum, or even community 3D printed designs. Cases aren’t strictly necessary however. Some of the more custom keyboards will just put rubber feet on the bottom of the bare PCB.

Put this all together, and you’re ready to order parts from a half-dozen manufacturers. A typical hobbyist build could include around $100 USD in parts from Keeb.io to build their split Quefrency board, another $100 USD for quiet Zilent switches from ZealPC, and around $50 to $100 USD on a set of keycaps. Make sure to budget another $100+ USD for an acrylic case unless you’re happy with rubber feet or know someone with a 3D printer. After an evening of soldering, you’ll have a nice personalized keyboard worthy of running off and showing /r/mechanicalkeyboard.

Software Shenanigans

Keyboards aren’t known for their intelligence. The earliest keyboards simply knew how to send basic serial signals before making the switch to simple USB commands. Even some enthusiast keyboards continue this barebones tradition. WASD’s mechanical keyboards have a basic USB connection, and only offer customization by exposing a set of physical toggle switches on the bottom of the keyboard to adjust settings like Mac and Windows keymaps.

Increasingly however, keyboards are beginning to house some legitimate processing power. Managing RGB LEDs is not a simple task, and additional components like OLED screens require some real intelligence on the keyboard itself.

There’s two ways you can manage these newfound capabilities: Built into the keyboard, or with client side software drivers. Most mainstream gaming keyboards generally go with this later approach. Logitech and Razer have all sorts of over the top software suites letting you accomplish complex feats like syncing the backlights of your keyboard with your current hero in Overwatch. It’s a fine approach when you’re looking for deep integration between software and a keyboard, but it does introduce a few unusual edge cases when switching between machines or dealing with particularly finicky hardware or software comparability.

The enthusiast mechanical keyboard scene has generally gravitated towards keyboards that manage their unique functionality on the keyboard itself. Rather than needing to rely on a specific software driver, the user can simply leverage  built-in hotkeys to cycle through features like advanced RGB LED light patterns.

Conceptually this groks a bit better with the idea of a keyboard being a self contained peripheral. No matter which system you plug your keyboard into, it will behave the same. All of the fancy lighting and custom macros are obscured away from the host machine, and no matter how complicated your device is, it still just appears as a standard keyboard.

The downside of this approach is that it usually limits the amount of customization available to you. A Keychron keyboard for instance may have 20 different light patterns programmed into it, but you’re usually stuck with those preloaded patterns. If you were using software drivers on something like a Razer keyboard, you can go wild and say, create a backlight pattern where the letters of your partner’s name are colored differently. On keyboards with fixed firmwares, you're stuck with the out of the box experience.

To help mitigate this issue, enthusiast keyboards have just started integrating an entire reprogrammable microcontroller. It turns out there’s very few things in the embedded electronics world that can’t be solved by just strapping an Arduino to the side of it.

The Arduino Pro Micro and its ATmega32U4 microprocessor has become the de facto standard for hobbyist keyboards. Pair it with the open source QMK keyboard firmware, and you can get a mechanical keyboard to do just about anything. QMK can control RGB LEDs, manage LCD screens, and provide a myriad of macro key behavior. It can be a little intimidating edit C config files and compiling your own firmware binary, but thankfully tools like the QMK Configurator and VIA have provided useful GUIs for those who are only up for moderate amounts of tinkering.

Proprietary keyboard firmwares are becoming increasingly rare, but it’s still worth double checking that the wired keyboard you have your eye on runs QMK. Custom Bluetooth keyboard firmwares are still fairly common for prebuilt boards, but open source options have started to crop up on the DIY side. The Nice!Nano microcontroller is a drop-in wireless replacement for the Arduino Pro Micro, and its wireless ZMK firmware is philosophically similar to QMK.

Hot-Swap Fever

When looking at the overall cost of a mechanical keyboard, the key switches are always the deceptively expensive part. The board’s about $50 USD, the keycaps are around $50-100 USD, and the key switches are $5-12 USD for a pack of 10 switches. That’s not too bad, right? Well, most keyboards have between 60 and 110 keys. On the low end, you’ll be able to outfit a small board with standard Cherry MX red switches for under $50. If you have a larger board, or go for something a bit more expensive like the ZealPC Zilent switches, suddenly you’re spending $100+ USD on just the switches for your build.

And you might not even like them! As I mentioned earlier, you generally need to buy a key switch tester to get a feel for which type of key you may prefer. There’s a big difference between having one sample key to tap with your index finger and having an entire board to experiment with. You might spend hundreds of dollars on a build, solder the keys into place, and realize you don’t actually like them. It’s a harrowing proposition for both first time builders and experienced folks who just like to experiment.

Wouldn't it be great if you didn't need to commit to a switch type when building a keyboard? Well, it turns out you don't have to worry about permanently soldering switches that aren't your cup of tea anymore. In the past few years, keyboards have started to incorporate the option of including so-called "hotswap sockets". The sockets are small pieces of plastic and metal that act like Game Boy cartridge slots for your key switches. They slot completely into place via friction alone, and are easy enough to pull out if you're not satisfied with them. If you bought a bunch of Red switches and it turns out you’re more of a Blue fan, all you need to do is buy a new set of switches. You can skip the process and sunk cost of having to re-buy and re-solder an entire second keyboard.

Hotswap support isn’t universal on keyboard PCBs at the moment, but it’s becoming more common. It’s possible to create a keyboard with support for both soldering and hot swapping, although adding additional functionality like per-key lighting can become slightly more complicated. The hotswap sockets themselves cost about $15 USD for 100 sockets, so it’s not exorbitantly expensive to add this functionality to a keyboard who’s design you’re on the fence about. Even for enthusiasts who know exactly what switch type they prefer, it's still nice to invest in 100 solid key switches and move those around as you experiment with different board layouts.

Ridin’ Low

Alright, it's time for the real hardcore nonsense. Making a bespoke custom mechanical keyboard is great, but you know what’s even better? Making one that’s smol. Get enough nerds in an online community together, and eventually someone will try to optimize the living daylights out of that community's tech and put it in a tiny package. It happened with the small formfactor PC community, and it’s happened here too.

Low profile keyboards have switches that are somewhere between laptop keys and traditional mechanical keyboard switches. They still have a bit of travel to them, but not a ton. The activation force needed to push a low profile switch is usually less than that of a full sized keyboard as well, so they’re popular options with folks looking to minimize repetitive stress in their daily computing.

The most popular key switch for low profile keyboards is the Kailh Choc. This switch has both a v1 and v2 variety, and interestingly enough, the community has mostly championed the original v1 switch. The v2 switch has a similar design, but chose to use a cross-shaped MX style switch stem. This is great for maintaining compatibility with 99% of existing keycap sets… but you know what else is really tall? 99% of existing keycap sets!

Kailh Choc v1 keycaps are usually small, flat, and chiclet-style. There aren't a ton of options out there at the moment. If you like keycaps with legends, your options are: Black, white, gray, and black with shine through letters. That’s it. Blue’s coming later in 2023. For blank keycaps, you can at least purchase them in a variety of colors.

Despite the small ecosystem, these low profile keys are versatile enough to fit a variety of designs. The caps are available in the standard 1u square, as well as longer 1.5u and 2u sizes. The lack of legend options is a little frustrating, but most of these boards are small enough that it's not a dealbreaker. You’re already having to map the = key to Fn+Z. At a certain point you just need to start remembering which key does what.

Why The Sofle Choc?

Would you look at that! Three thousand words later, and we’re finally ready to discuss the keyboard we set out to talk about.

The Sofle is a split ergonomic keyboard design originally created by Josef Adamčík. There's a couple things to unpack there. Most obviously, this keyboard has two distinct halves connected by a headphone-style TRRS cable. People have found that typing with both of your arms pointed forward puts a bit less stress on your wrists than the typical typing posture of bowing your arms together at a 45 degree angle. This isn't the only ergonomic bit the Sofle has going on however.

A standard keyboard has rows that are slightly offset. The X key isn't directly below the S key for instance. There's a stagger to their rows. This can lead to odd hand twisting when a key doesn't obviously line up with any of your finger's normal resting position. Is it the responsibility of your ring finger to slide down from S to type X, or should your middle finger curl in from the D to tap the X?

Everyone’s heard that anecdote about modern keyboard layouts hailing from designs intended to slow down typing and stop typewriter jams, right?

Some keyboard enthusiasts have started moving away from this classic “Row Staggered” layout. “Ortholinear” keyboards like the Planck take this to the extreme, and have designs which perfectly align every key on a horizontal and vertical axis. There's no confusion about which finger should be sliding down to tap the X on this style keyboard layout.

The Sofle doesn’t go quite as far as an orthlinear layout, and instead opts for a “Column Staggered” layout. In this type of layout, all of the rows are lined up, so your X key is directly under your S key, but the columns have a slight stagger to them. This tries to acknowledge the natural curl of a human hand, hence the Sofle's ergonomic description. You still get the nice benefit of the X key being a quick slide of the finger under the S key, but you don't need to adhere to the Ortholinear's strict straight lines.

The original Sofle design has several variants. The Sofle Choc board we’re looking at today is a riff created by Brian Low. It introduces Choc hotswap sockets, and retains the per-key RGB LEDs first introduced in the Sofle RGB.

The Sofle Choc checked a lot of boxes for me. When I first started exploring building a new keyboard, I wanted something that was a significant enough departure from my earlier Keeb.io Quefrency build. It was a split keyboard too, but it had a traditional row stagger layout, and the backlight LEDs weren’t individually addressable. The combination of the Sofle’s new layout, the per-switch RGB LEDs, and the low profile Choc switches were enough to make me consider building another keyboard. It didn’t hurt that the Sofle Choc would also give me a good excuse to experiment with OLED screens on a keyboard.

Building The Sofle Choc

Outside of commissioning someone to build it for you, the Sofle Choc is only available as a DIY project. Whether you buy a full kit or source the parts separately, you’re in for a soldering project that will take up the better part of an afternoon.

Soldering is a bit of an intimidating skill to pick up. You’re working with temperatures that can melt metal, there’s a lot of stuff you need to buy, and you can brick your project if you make a mistake. It doesn’t take too much practice to gain a bit of confidence however, and introductory soldering irons are cheaper than you’d think.

Keyboards are actually a surprisingly good place to practice soldering. They usually don’t employ advanced soldering techniques (although the Sofle dabbles with one), and due to the nature of a keyboard, everything’s nice and spaced out. I wouldn’t recommend learning how to solder on a keyboard however. An intro soldering kit will set you back about $60 USD, and a simple “learn to solder” project with a few LEDs and buttons will generally cost about $10-20 USD. It’s worth the superfluous extra expense to get the hang of things before diving straight into your keyboard. Each half of the Sofle has 29 keys on it, and if you botch one of them, you’ll have to start dealing with cumbersome de-soldering or other hacks to try and salvage your board.

The complete ≈$140 USD kit for the Sofle Choc comes with: The PCBs, the hotswap sockets, diodes, LEDs, two Arduino Pro Micro controllers, two OLED screens, sockets for the microcontrollers and screens, rotary encoders and knobs, TRRS plugs, a TRRS cable, a reset switch, and some rubber feet. You need to purchase the Choc switches (≈$40 USD) and keycaps (≈$70 USD) separately.

Brian Low’s build guide for the Sofle Choc is one of the more thorough guides on the internet. He walks through every step in detail and includes plenty of pictures. He’s even got a few nice touches, like making sure your first step to label which side is “up” on your two identical PCBs.

The first step of building the Sofle may be one of the more intimidating on paper. The Sofle leverages SMD surface mount diodes in its keyboard design. Most beginner soldering focuses on “through hole” components. As the name implies, these are components with long “legs” that you slide through metal holes on a PCB. You then fill the hole with solder, and a circuit connection is made. Surface mount components are a bit more fiddly to work with. They instead only rely on small metal “pads” resting on the top of a keyboard. You lay the component down and then apply solder to the pad to make sure the diode lays flat.

I had previously avoided SMD soldering. It’s more precise, more fiddly, and usually requires a more expensive soldering iron with good temperature control. The surface mount diodes on the Sofle didn’t give me too much trouble however. If you’re a competent through hole solderer and are turned off by the idea of SMD components, try not to worry about it too much. Just make sure you have a good pair of reverse-action tweezers. These bad boys stay clamped shut by default, and make it way easier to work with diodes the side of a grain of rice.

Next come the hotswap sockets. These are also technically surface mount, but the pads you solder them to are comically large. It’s honestly difficult to use too much solder here. The sockets deal with some amount of physical stress, so you can have a heavy hand with your solder and give them a bit extra support.

The last surface mount component is the per-key LED backlighting. These are also another beginner-friendly SMD soldering experience. The SK6812 Mini-E LEDs have long legs on them, and the board has small holes cut out for the light emitting part of the LEDs. It’s obvious when they’re seated correctly or when something isn't quite right and needs fixing.

Next comes the microcontrollers. The Sofle Choc is designed around the Arduino Pro Micro. This is a board which has been cloned numerous times. You can use any Pro Micro compatible board, such as the popular Elite-C microcontroller. The Elite-C and some more recently manufacturers Pro Micros have USB-C instead of Micro USB on them, so think about what type of connection you’d like to use for your keyboard before you buy the microcontroller.

Microcontrollers can be soldered to the keyboard directly, but most people recommend “socketing” your controllers. This is a process of putting a female socket onto your keyboard itself, and a set of male pin headers onto the microcontroller. If something happens to your microcontroller and you need to replacer it, it’s much easier to remove a socketed controller and slot in a new one. Also, if you end up making more than one keyboard, you can move the relatively expensive microcontroller between boards instead of making redundant investments.

Brian once again has a good guide here. The community has standardized around “machine pin” headers due to their low height. When building a mechanical keyboard, just make sure you pay attention to the orientation of the microcontroller. The community typically mounts microcontrollers face down for aesthetic reasons, but the practice isn't universal. The OLED screens goes through a similar socketing process.

After that, you just need to solder a few simple through hole components. The reset switch, TRRS connector and encoders should all be pretty straightforward after all of those SMD components. Keeping a roll of blue painter’s tape around can help make sure the components continue to lay flat as you flip the board over.

At this point you can start slotting in the key switches. The Sofle Choc comes with a switch plate to add a bit of stability to the board, but it doesn’t have a traditional case. Instead they just give you a few rubber feet to apply to the bottom of the PCB. It's a bit minimal, but the keyboard is attractive enough to stand out on its own. If you have a 3D printer however, there’s a few options at your disposal. Lytedev on Thingiverse created a nice low profile case for the Choc variant of the Sofle, and I’ve got a fork with support for threaded screw inserts.

The last step is to flash the keyboard firmware to the microcontrollers. This will either be trivial or daunting depending on your prior experience with Arduinos. QMK is well documented and is easy enough to get compiling locally, but thankfully several precompiled builds also exist for the Sofle. GUI tools like the QMK Toolbox help streamline the process of uploading new images to one’s board. You can even skip fiddling with QMK config files and use a VIA image if you’d like to leverage the community’s burgeoning graphical key remapping tool.

Using the Sofle Choc

Even for folks who haven't fallen down the mechanical keyboard rabbit hole, it's hard not to notice that keyboards are getting smaller. Companies like Apple are shipping their desktop iMac computers with tenkeyless keyboards, and mainstream manufacturers like Logitech have more than a few "75%" layout offerings at this point.

My old Quefrency took things one step further. It’s 65% design dropped the Function row and squished the arrow keys and most of the navigation keys up against the right side of the keyboard. Thankfully keycap vendors have started to offer smaller shift keys to make these layouts a bit less cumbersome to build than they were in the past.

The next step always seemed like a doozy for me though. 60% boards like the Anne Pro or the Pok3r ditch the arrow keys entirely. The idea is that you hold down a laptop-style FN key in order to use the "superfluous" keys that their layouts dropped. Depending on the keyboard, your arrow keys would either become a WASD-style cluster over on IJKL, or they’d lean into an old school vi-style HJKL row.

It always looked like a cumbersome arrangement to me. Full disclosure, I’ve never owned one of these classic 60% keyboards, but if I was so nervous about 61-key layouts, how did I end up on a 58-key board?

Well, it all comes down to thumb keys and layers. On a classic small-scale keyboard designs, you’ll often need to hide certain keys behind an Fn key. If your laptop doesn’t have a Delete key for instance, you’ll need to rely on Fn+Backspace to achieve the same outcome. Most of the time these Fn keys are squished in with Ctrl, Alt, and Win / Cmd on one or both sides of the spacebar. (Update: It turns out the Pok3r lets you use Caps Lock as an Fn toggle, which does sound a bit more comfortable than the Fn key next to the left Alt.)

QMK-based ergo mech keyboards take this concept to the extreme. They’ll have multiple function keys. Rather than just referring to these keys as Fn1, Fn2, etc., QMK uses a "layers" metaphor. Keyboards can stack multiple layers of additional key functionality on top of the base layout depending on which Fn-style keys are being held down. The Sofle for instance has a "Symbol" layer, a "Navigation" layer, and an "Adjustments" layer. You get to these other key functions by holding down Fn-like keys that are usually referred to as Raise and Lower.

The documentation of QMK has the full details if you're interested, but suffice it to say, the Sofle has some well thought out ways of accessing the keys it has dropped. This was actually the impetus for the Sofle keyboard itself. Adamčík had tried using the popular 42-key Corne keyboard, and wanted a few more keys to make a more comfortable layout.

The Sofle puts the Raise and Lower layer keys where your thumbs naturally rest. Unlike a lot of laptop keyboards, you're not put in the awkward situation of remembering where they put the Fn key. It's not a clumsy, “Now did they put it between Alt and Win, or Win and Spacebar?” situation. They're just bam, right there, always under your left and right thumbs.

This basically solved my arrow key dilemma. The Sofle also uses IJKL for the arrow keys, but all you have to do to switch over to that mode is hold down the Raise key by your right thumb. Thanks to the keyboard’s column staggered layout, the arrows don’t even feel weird. The I and K keys are right on top of each other, so pressing "up" and" down" feels just as normal as a standard set of arrow keys. J and L are staggered slightly from the K key, but they're staggered in an equal amounts they still mirror each other. The act of moving around a document still feels familiar, you just have to adjust your "shift your right hand a few inches to the left before arrowing" muscle memory to "push your right thumb down before arrowing".

The switch took surprisingly little time to adjust to. If you’re interested in this style of split ergonomic keyboard but not quite ready to make the jump to an arrow-key free life however, you're not completely out of luck. The unusually asymmetrical Afternoon Breeze keyboard has a similar split ergonomic layout as the Sofle but it maintains a traditional navigation cluster. It doesn't have per-key RGB LEDs however, and in the end the light show won out. I’m happy with my choice, but the option’s still there if you’re on the fence.

Using a layer for some extended symbols and brackets took a bit of getting used to. I never appreciated just how much - and _ come up in my day to day life. That particular key quickly got promoted to the one unclaimed slot next to my 0 key, but most of the other math symbols have taken some time to adjust to. I only do a moderate amount of Excel work in my life, but any time I fire it up I need to take a half-beat to remember that = is Lower+Z and + is Lower+C. Brackets like { } and [ ] somehow took me less time to adjust to. It’s kind of nice having them symmetrically positioned near one’s index fingers.

The biggest shift when moving to one of these column staggered or ortholinear keyboards is that they usually don't have a great place for the Enter key. The bracket keys and special symbols like \ usually get shuffled around on a symbol layer, but ' and " have too engrained of a muscle memory to get shunted off the pinky row. This means the Enter key needs to find a new home, and more often than not it ends up as either the right Shift key or one of the spacebar-style thumb keys.

I went with this later approach for my Sofle layout. My left thumb is Enter, and my right thumb is Spacebar. There was definitely a transition period, but I started to feel at home on the Sofle after a week or two of continued use. I had a few amusing moments on work screen shares where I needed to type a character I had lost track of, but those moments went away pretty quickly. Just be careful when typing in an IM window during the transition period. There were more than a few IM messages that were sent a little early thanks to the new Enter key position. Before I knew it though, the Sofle was just another keyboard to me.

The one interesting aspect I was curious about (and maybe a little worried to be honest) was how had it would be to transition back to a traditional row-staggered keyboard layout. I’m still going to be on my laptop some of the time, and thankfully the Sofle hasn’t ruined portable computers for me. There seems to be enough working space in my head to manage at least two keyboard layouts without too much trouble.

So Is It Ergonomic?

Probably? I’m not a doctor, but I haven’t had as much wrist trouble after a long typing session with the Sofle as my older Quefrency keyboard. Despite the Quefrency’s split design, I’d often end up just pushing the two halves together. That’s not really an option with the Sofle, so I naturally let them stay further apart.

I made the classic "changing two variables at once" mistake when looking to improve my desk situation. Around the same time I switched to the Sofle, I also bought a large Kensington Expert trackball. I feel like it probably made more of an impact when it came to sitting at my desk for hours a day, but everyone will have their own personal solutions when it comes to improving their ergonomics.

Also: Hey, sit up straight!

I ended up liking the Choc switches a lot more than I thought I would. Their low-travel nature ties out my hands a bit less than my heavy Zilent switches on the Quefrency. If you're looking to reduce the stress on your hands, you can get some astonishingly light switch options. I’m not sure I’d recommend immediately jumping on the 35g Red Pro switches to start with, but they’re a bit like typing on air once you get used to them. If they're not your cup of tea, no harm no foul. This keyboard's got hotswap sockets, remember?

Bells & Whistles

I’ve mentioned several times now that I specifically bought the Sofle Choc due to the keyboard's per-switch RGB LEDs. It’s the entire reason I went with this board, and they’re fine.

That's it. RGB LEDs are fine. There's some neat cycling rainbow patterns one can enable, but they mostly just look nice in pictures. QMK has support for some really engaging interactive effects, such as strobing the lights in time with your current WPM typing speed, but if you're a touch typist you're not going to be staring down at your keyboard while you type. The interactive patterns are a hoot, but they also generally leave your keyboard unlit when you're not typing. With a few months of hindsight now, I mostly just leave my Sofle with a solid purple backlighting that matches the trim of the case.

The OLED screens on the keyboard likewise look nice, but I haven’t taken the time to investigate them as much as I should have. You need to get pretty in the weeds of QMK in order to do the more impressive readouts, so right now it’s mostly a verification that the keyboard’s plugged in. I’ve got my board set up to toggle between Mac and Windows modifier layouts, so it’s also nice being able to see which OS my keyboard’s currently set to. It’s my own fault for not leveraging these fully, but again, this is a keyboard and you don’t tend to look down at it too much.

Finally there’s the rotary encoders. AKA the knobs. The knobs were a must when I bought the Quefrency, and I wanted to carry that over into the Sofle. They’re knobs! On a keyboard! Come on!

Okay, I have to admit, they only get a moderate amount of use. Since my Quefrency days, I've had my rotary encoders mapped to my system's volume and media keys. They work well for this use case, but it turns out that the Sofle's default keymap also has pretty good volume and media hotkeys. Raise + IJKL give you quick access to the keyboard's arrow keys, and Adamčík decided to put the volume controls on Raise + Lower + IJKL. If you hold both of your thumbs and push "left and right", you raise and lower the volume. Shift your fingers down one row, and surprise, there's your media controls.

The Sofle Choc was a pretty maximalist build, and it helped me figure out what my priorities are for future keyboards. Rotary encoders aren’t the must-have I was making them out to be, and RGB backlighting is once again a nice to have. The advanced functionality that has honestly seen the most amount of use is the basic QMK support. I've gone ahead and created a few different macros for things like switching devices on my KVM. It's hard to deny how nice the MBK Glow keycaps look with the purple backlighting, but I may save some money on future builds and skip the per-key LEDs if the keycap ecosystem expands their aesthetic options.

Conclusion

I guess I should have seen this coming, but I never pictured myself becoming a Weird Keyboard Person. My first mechanical keyboard build was mostly a way to pass the time researching and building something during the early days of Covid. I fully expected the Sofle to be way too much and eventually retreat retreat back to my Quefrency.

I've been pleasantly surprised however. The Sofle Choc is a great keyboard! It's a wonderful entry point into this crazy world of low-profile ergonomic mechanical keyboards. I’ve definitely gotten bit by the mechanical keyboard bug, and I’m already pondering what my next move may be. I still use a decent number of number keys and modifiers in my day to day work, but the ultra-minimal 42 and 38 key keyboards do have some attractive compactness to them. I’m not sure if I’m ready to make that jump just yet, but it’s certainly within the realm of possibility in the way that it wasn’t before. Maybe I'll research designing my own custom keyboard PCB.

I hope this was a useful writeup! There are a lot of “Intro to Mechanical Keyboard” guides out there, and plenty of hyper-enthusiast forum posts and Github readme.md files floating around, but I feel like it can often be tricky to transition from the former into the later. I enjoy writing these brain-dump "How did I get here?" pieces to try and connect those dots. Hopefully this gave you a few new terms to Google if nothing else.

The Sofle Choc can be purchased as a full kit from Brian Low. The PCB and other components can also be purchased piecemeal from MKUltra in the US and 42Keebs in the EU.