A few months ago, after a full year of waffling, I bought my first custom keyboard. During the setup process, I felt like most of the tutorials I was finding were geared towards people knowledgeable about keyboards and less familiar with programming in general. I'm exactly the opposite of this -- over 10 years' cumulative experience programming, but little knowledge of keyboards and their workings.

Because of this, I kept notes as I customized my keyboard layout. Here's what I did, and I hope it helps you get started with your own custom setup 🤓

Why a Custom Keyboard?

I became interested in custom keyboards for aesthetic reasons. I was used to toggling between a chunky dark grey keyboard (when on a PC) or a slim silver one (for a Mac). Either way, keyboards were uniform and. Learning that there was another path -- of personal investment, care, and customization -- was intriguing to me.

Cost was my largest blocker to actually buying a keyboard. The first custom keyboards I was linked to ran about $400; the kit I actually bought totaled $340. This is a lot of money, but I planned to use the keyboard for work. $400 for a tool I would use 40+ hours per week, I figured, was actually a reasonable expense when all was said and done.

The Kit

On the advice of a coworker, I bought a Tofu65 assembled keyboard from KBDFans.com.

I chose Cherry Silent Black switches (to be considerate to officemates -- what innocent times those were). For keycaps, I found a pink-and-white Maxkey set that would be a joy for me to use every day.

The keyboard took about two months to arrive; using it was as simple as plugging it into my computer's USB port. The shipment included a little wire tool for lifting keycaps off of the board, so physically rearranging keys was also trivial. The other side of this process -- configuring the keyboard firmware to send the correct signals to the computer -- would be more difficult.

A coworker advised me that getting set up to configure firmware would take a while, but would be worth the time. So I cleared my calendar one Saturday morning, poured myself a big cup of coffee, and got to work.

Creating the Custom Layout

Here's the process I followed to create and load a custom keyboard layout. This is what was useful to me, so some of these steps diverge from what you might find in other walkthroughs that assume more familiarity with keyboards in general.

Download and configure the QMK Toolbox

My keyboard, like most others from KBDFans, is compatible with QMK firmware. Several of these next steps are paraphrases from the QMK docs.

Start by installing QMK with Homebrew:

brew tap qmk/qmk
brew install qmk

This may take a while if Homebrew needs an update (which it always seems to??). Don't walk away for too long, though, since there are some interactive prompts to install dependencies of QMK.

Next, fork the QMK Toolbox repo on Github and run the QMK setup command using this remote URL:

qmk setup <your_github_username>/qmk_toolbox

Finally, follow QMK's customization instructions to save yourself a lot of typing.

Design the layout

I did all of my layout editing in the online QMK Configurator tool. The drag-and-drop interface was simple to use, especially since I don't know much about the underlying processes. QMK has a good video intro to the configurator; I'll deviate from it in that I used QMK from the command line, not from a GUI.

Select the keyboard

Choose your keyboard type from the dropdown at the top of the configurator.

In my case, my keyboard (kbdfans/kbd65) isn’t actually in the list of available keyboards in the QMK Configurator, but it is supported under the name kbdfans/kbd67. This keyboard defaults to the LAYOUT_65_ansi layout which matched my keyboard perfectly.

Design the layout map

This is the fun part! Drag and drop keys to where you actually want them. I won't get into using multiple layers, or any actual C programming 😅 It's very 1337 but not what I needed my first time around.

Download the layout

Since you already have the keyboard firmware installed, once you have your map made in the QMK Configurator, you can hit the Download Keymap.json button without compiling the layout. From now on you’ll be working completely in the command line, but keep this browser window open for follow-up tweaks to the layout.

Flash the layout onto the keyboard

Your keymap needs to be compiled in order to be flashed onto the keyboard. Locate the JSON file downloaded from the QMK configurator, and run:

qmk compile <path/to/downloaded/layout>.json

If successful, QMK will output a .hex file into its root directory. For me, this was at Users/<my_username>/qmk_firmware.

Next, the keyboard needs to be put into DFU/Bootloader mode in order to be flashed. While in Bootloader mode, it will not send inputs to your computer like it normally does. If your keyboard underlight is on, the light will turn off when the board goes into Bootloader mode.

Keyboard vary in how they can be sent into Bootloader mode. QMK has instructions on different ways to do this — the first time I flashed my keyboard, the Spacebar+B strategy worked. Subsequent times, this didn’t work, but unplugging my keyboard and plugging it back in with the ESC key pressed did send it into Bootloader mode correctly.

With your keyboard in Bootloader mode, run qmk flash on the command line to send your layout onto the keyboard. Don't unplug the keyboard until you get a message that the flash has completed. Now your keyboard is using your custom layout! 🎉

You can flash your keyboard as many times as you want to. I flashed mine about ten times during that session as I honed what I actually wanted my keyboard to do.

The result

In the end, I have a keyboard that is completely tailored to what I want, and it feels glorious. In addition to a full keyboard, I have dedicated play/pause and volume up/down buttons. The volume buttons also let me skip tracks when paired with a modifier key 💅🏻 And, naturally, I have a couple of keys dedicated to toggling the keyboard underlight.

All in all, the time and money I've invested in this keyboard has felt worth it -- because it has truly felt like an investment. I love having tools that feel good to use, that work well, that feel familiar to me. I've been using this keyboard for about a month now; it's a little puff of wind in my sails whenever I sit down to work, and I look forward to many years with it.

Thank you

First, thanks for reading this far, and I hope it's been helpful!

Thanks to Jordan Egstad for being an endless font of keyboard inspiration & knowledge. Also, thank you for letting me borrow your "starter keyboard" for 😅 months 😅 as I decided what I was actually going to buy.

Thanks also to Angela Riggs for additional keyboard intel, such as encouraging me to take my time setting up my dev environment.