I built a keyboard PCB and wrote firmware for it in Rust

Hey all! New to the hobby, I'm stuck at home with covid, but I'm excited and wanted to share my story from the past month.

tl;dr - Got sucked into this hobby a couple months ago and now I have my first custom PCB and firmware working. You can check out the source files here.

A month or two ago, a friend took me to Yushakobo in Akihabara to look at keyboards. I'm a software developer so of course I had known about mechanical keyboards, but I had never really gotten into it before as I know it's a hobby you can really get sucked into. Looking at the signs listing specs for the keyboard, I had no idea what they meant. I was just touching keys on as many keyboards as I could.

Well, the keyboards they had on display were too nice, I was especially drawn to one with PBT keycaps and gateron oil king switches. I had never typed on a keyboard so smooth, and so satisfying. At that point I knew I was missing out. I write code every day, and now I can make it even more enjoyable! I decided though, that I would do more research, and avoid the impulse buy. There were too many unknowns.

I was really into a clicky one as well, but I subconsciously stayed away because I know my wife would go mad with that in the house. Linears seemed great, anyway.

With great restraint, I left the store without buying anything. The whole next week, I couldn't stop thinking about that keyboard.

A week later I go back to the shop, and my favorite keyboard is still there, thankfully. I type on it, and it's just as good as I remembered. But sitting across the table was another keyboard which caught my eye. Like every other keyboard in the shop, I typed a bunch of random words on it to see how it felt. This one was also really satisfying. It turned out to have gateron pro silver switches, and I liked the layout even more. I realized later this was a 75% form factor, which I think is more my style as I like using FN keys and having arrow keys.

It didn't have a price on it, so I asked the staff roughly how much it would be to make one of them. Keep in mind, I knew very little about the hobby at this point, I barely even knew all the components needed to make a keyboard, and I let them know as much. The staff member estimated it would be about 50,000 yen (sadly, around $370 with the current exchange rate). That stopped me pretty quickly in my tracks. There's no way I could justify spending that on my first keyboard when I knew so little about the hobby.

I've done a bit of PCB design before, so from that point I decided if I was going to spend a lot of money on this, I was going to build things myself. I know I know, "time is money", but let's be honest, I'd be on reddit or youtube more if I wasn't building this anyway.

I stopped pursuing the black and red keyboard, bought 10 hot-swap sockets and 10 gateron pro silver switches, then left the shop. This was probably very confusing for the sales staff.

Over the next month or so I researched and gathered info on building boards:

• How does keyboard firmware detect so many independent button presses, given the keys outnumber the GPIO pins? (answer: a keyboard matrix circuit)

• What thickness PCB is most common? (answer: 1.6mm seems most common)

• What are considered the "best" type of stabilizers? (answer: I went for screw-in stabilizers, but this is maybe more opinion-based)

• How far apart are standard 1U keycaps? (answer: 19.05mm)

• What firmware do people use in most boards (answer: QMK)

• Is there a standard set of screw positions for mounting in a case (I still don't know...)

• What switch footprints should I be worried about? Is there some "universal" footprint I can slap into a PCB, or do I need to pick one? (answer: go with cherry MX for now)

The Keyswitch Kicad Library ended up being invaluable in exploring some of these questions.

I drew up a simple diagram of what I thought would be the ideal layout for myself. I use a macbook at work so it was based heavily on that, while removing keys I don't typically use. At first I was worried about it being too specific to me, but I quickly realized everyone has super different preferences for keyboards and there's no point trying to cater to as many as possible. For example, I never use the right shift, ctrl, or alt key while typing. So I just removed those, and that conveniently made space for the arrow keys to go right under the enter key. I also wanted to try having 4 modifier keys in the bottom left cluster, so I modeled that after my macbook's keyboard.

Over the course of a couple weeks, I drew a schematic and placed the components for the PCB. Instead of making something based on the pro micro, I decided to put the microcontroller directly on the board. I would have normally chosen an STM32 as I had previous experience writing Rust firmware for that, but this time I decided on the RP2040 because it's cheap, widely available, seems very powerful for its price range, and comes with plenty of IO.

The youtube channel Phil's Lab was incredibly helpful here in learning how to properly wire up the RP2040, along with the RP2040 Hardware Design Guide.

There was also one more reason I chose the RP2040 - I saw quite a few RPi Pico boards at Yushakobo, including one called RustyKeys. The firmware for that board showed me how simple it could be to write my own keyboard firmware and was a major source of inspiration. Just knowing that something can be done makes it a lot easier to do it.

I had never routed so many GPIO lines before, so it took some trial and error to learn the best way to get things done. I went through many iterations of key placement, where to place the edges of the board, where to place the microcontroller, and how to sanely route the matrix lines.

This article was especially helpful on reassuring myself that my USB data lines would be okay, and how to best manage all those matrix lines (hint: the particular order of pins isn't sacred, swap them around if it's convenient for routing!).

I ended up with this:

PCB

3D View Front

3D View Back

I ordered the PCB via JLCPCB, and used their assembly service. You can see the cost breakdown here. It was $57, plus $21 shipping. This was for 5 boards, 2 of which are assembled. Everything would be populated on the board except for the hot-swap sockets and the debug header pins. They even handled the USB C connector! I could have paid for their "standard" assembly service instead of their "economical" assembly service to get the sockets soldered on, but those are easy enough to do by hand. The "standard" service also would have doubled the price, so not worth it in my eyes. Remember, I'm cheap and don't mind paying with my time on occasion.

The first version of the board arrived a few days ago:

Front

Back

Component Assembly Closeup

Side Shot

You might have noticed, but this board is slightly curved unfortunately. I should have balanced out the copper more between the two layers of the board. I'll fix that in the next revision.

One of the cool things about the RP2040 is its factory bootloader acts as a USB mass storage device where you can drag-and-drop firmware to it. When the PCBs arrived, I was able to literally take them out of the box, plug them into my computer, and see the RP2040 mass storage drive show up on my desktop! Of course, I tested the board for electrical shorts before that, but how cool is that?

With the PCB working, I finally allowed myself to buy switches and keycaps to celebrate. I went with the gateron pro silvers from before, and some cheap PBT keycaps from amazon because 1.) I'm in quarantine, and 2.) This is a prototype board so I don't need to go fancy. I also had to order stabilizers, of course.

While waiting on the switches and keycaps, I started writing the firmware. I started with my rp2040-template I made recently, and drew heavy inspiration from the Rustykeys project I mentioned before.

With the keyboard in USB bootloader mode, I could simply run cargo run --release from the terminal and my firmware gets built and deployed to the board, quickly and easily. I haven't even felt the need to use the debug port yet, but it's there if I ever need it.

There's not a lot to say about the firmware - it's very barebones, supporting just the keys on the board, with no aims at being anywhere near as flexible as QMK. BUT it's like 200 lines of code, in reasonably understandable Rust code. I'm standing on the shoulders of giants with the libraries I'm using, of course.

I've shifted to Rust for almost every piece of software I write, and it was really cool that I was able to write keyboard firmware in it, then deploy it effortlessly onto a PCB I designed. The really wild part was that it worked on the first try. I deployed it, and was soon after greeted by this MacOS dialog. And there it was, in the USB device list as well!

There was a bug though that Rust didn't catch - I forgot to specify the GPIO pin for the entire bottom row of the keyboard. That was easy enough to catch later when I realized every single key on the bottom row wasn't working.

The switches, keycaps, and stabilizers arrived today. I soldered the hotswap sockets in, and hurriedly installed everything else.

Well...I knew I'd probably need a plate, and after putting everything together, I can now tell that I definitely need a plate. 3 pin switches installed directly on a PCB with kailh hotswap sockets does not make for very secure or correctly oriented keys. Lesson learned! I didn't want to fuss with a plate until I saw the whole build in person anyway.

Here are some pics of the "final" build. Of course this is still the exploratory prototype version so nothing is final, and it's quite janky in many places.

Switches installed

Keycaps installed

PCB Back with sockets installed

Plugged in and working!

Aside: You might have noticed in the last picture I have a filco keyboard. A friend sold it to me a few years ago, and I knew it was a mechanical keyboard, but I didn't know it was in the same ecosystem of switches as cherry MX and friends. I also had never taken the keycaps off until after I visited Yushakobo. I learned it had Cherry MX brown switches, and I ended up desoldering those and replacing them with a mix of oil kings and pro silvers, but that's another story.

So I didn't end up with a product equivalent to the nice keyboard I was initially eyeing, of course. But let's see roughly how much I spent, in my cheapness:

(costs are for one board)

• PCB + parts assembly - ~$20 (remember I got 5 boards, with 2 assembled, for a total of $78)

• Stabilizers - 2750 yen = ~$20

• Kailh hotswap sockets - 1600 yen = ~$12

• 75x Gateron pro silver switches - 5120 yen = ~$38

• PBT Keycaps - 3899 yen = ~$29

• Engineering Time - $0

Total - $119

Not bad! I need a case too, but I could probably build a cheap acrylic one with some M2 standoffs for next to nothing. With cheaper switches and keycaps you could easily get this below $100.

With all the pristine and aesthetic keyboards posted here, this one is almost comically bad, possibly disturbing for those who get really into the details of a board. I've already taken note of several issues I need to fix. I'm still actively working on the firmware. It's kind of amusing that I'm now using this keyboard to write firmware for itself. It's like some weird form of compiler bootstrapping.

Despite how janky the board is right now, it actually works, and I typed this entire post on it!

Here's the world's shittiest sound test, performed with the board on my lap, if you're interested. Though of course it changes sound every time I put it on a new surface so it's not really indicative of much.

Anyhow, the repository with PCB designs and firmware can be found here:

https://github.com/bschwind/key-ripper

There are production files I used to order at JLCPCB which you can find on the releases page. It's still a work in progress, currently no top-level README, sorry!

I tried to make the license as non restrictive as possible, so feel free to learn from it, mod it, order it, or anything else. Though you may want to wait until I fix some initial issues like the curving PCB, or the fact that the F5 key is incorrectly spaced...

Thanks for reading this far! Happy to answer any questions :) I'm still deciding if I like this layout or not. The case is my biggest worry, I'll have to make a custom one unless I go with a standard size like 75%.