## Planning

One of the first things I did was to check Wikipedia: Computer keyboard#Keyboard types. It also links the Keyboard Matrix Help page, which explains how those work.

I heard of DIY keyboards (such as atreus and ergodox) before, so looked those up, and searched for more articles on the topic. Found a nice "Build your very own PC keyboard" article, for instance, as well as the "How a key matrix works" page.

Apart from those, the "truly ergonomic mechanical keyboard" (which I'm usually using) and the space-cadet keyboard were inspirational.

Found that Cherry MX switches are often used by hobbyists, and that a mechanical keyboard is perhaps the easiest to build manually.

Got a rough plan on the first day: design a PCB and a metal plate, teach myself how to solder (and get the tools), order/buy all the components, assemble the keyboard, write the firmware.

I've also asked about those things on #emacs on Freenode/Libera.chat (because they know everything there), and got redirected to #geekhack, which was helpful along the way, as well as ##pcb and #hackvana. And I've poked a few people, including fellow programmers, who are familiar with electronics; received plenty of advices and information that way.

## Software

If you thought that programming-related software is bad, there's a whole new level of misery awaits in hardware. And it's probably even worse further from engineering.

As it usually is, there is PCB design software that is supposed to be newbie-friendly, but not usable even by newbies. Then there is some proprietary software that makes RMS sad. And there is KiCad, which is quite awkward (especially at first), but works, and apparently it is often used by hobbyists. Not recalling the details now, but I've ended up installing its old version via Nix to get it on CentOS.

For the metal plate, there is LibreCAD, which is surprisingly nice. Some laser cutting companies accept SVG, but DXF seems to be more common, and LibreCAD supports it.

## Controller

Before designing a PCB, I needed to choose a controller (the switches were chosen already). Apparently there are some open-hardware controller projects, but they are DIY. For others it may be tricky to find existing KiCad libraries (and I wasn't confident in using it at all at that stage), so I've ended up picking Teensy 3.2: it's small and has plenty of digital I/O pins. Could have picked something cheaper, but it's a relatively cheap part of this project anyway, and the delivery cost makes the cost of the controller itself less significant. I thought of using A-Star 32u4 Mini and Arduino Leonardo or Micro, but for some reason didn't pick those.

By the way, around Arduino, there are many plug-and-play components to build devices like a lego constructor. Not as flexible as the usual way, but maybe has its uses.

## Schematics and PCB design

On the fifth day, I've composed initial schematics and layout. Here are some links on the topic: Getting Started in KiCad, KiCAD-Keyboard-Tutorial, KiCAD keyboard PCB design guide. I've also checked ergodox and atreus, and took the schematics and footprints for switches from ergodox.

Having little to no idea on how to solder, I was afraid to screw things on that stage (e.g., bridge the tracks), so tried to make the PCB as easy for soldering as I can: keeping tracks far from holes, yet not too close to each other (because I also had no idea how that would work out). But a keyboard PCB is large, so there is plenty of space, and apparently I didn't screw anything in the end.

The standard tracks are 0.254 mm wide, I've tried to keep at least 0.254 mm between them, and at least 0.5 mm between bypassing tracks and holes. I've also ended up getting rid of the vias, because it seemed more simple without them, and they were not necessary.

I've considered using surface-mount diodes, and thought that they may be easier to solder, but apparently it's not the case, and it's easier to just use through-hole for everything.

Another option is just to use wires instead of a PCB, but that'd be rather messy.

## Mechanical layout

From the beginning I wanted a lot of modifier keys, and just 5 rows, but then I've started thinking of the exact mechanical layout. Tried to figure where my fingers would lay if they are simply relaxed, thought of making the keyboard particularly ergonomic, but then decided that it may be too much for the first project, and an easy way to introduce additional issues: for instance, using even a slight angle for columns would lead to a space loss, unless one has special keycaps, and it makes routing a little more complicated. But probably the hardest part is to measure what exactly would be handy, and it would be unfortunate to find out that a weird custom layout is not handy – so I've just slightly staggered the keys symmetrically. It took me a few days to decide this.

For the modifier keys, I've used 1.75x keys; initially thought of 2x, but apparently those require stabilizers (additional work and components). 1.75x are fine, and more of them fits in the same space.

I've also left a bit more space than required between the buttons, just to be safe. Square keycaps usually take 17.3 to 18.2 mm on each side, switches themselves – 15.6 mm (but don't use it as a reference; one should check the specifications for exact dimensions).

## Metal plate blueprint

This was a fun and easy part: exporting the corresponding layer from KiCad (the switches had the required outlines attached), opening it in LibreCAD, and just drawing something around the switch holes.

In less than two weeks, the design was ready, and I've learned the very basics.

## Obtaining the components

This was a slow and unpleasant process.

A warning for ordering equipment from Russia (which wasn't an issue for me with the keyboard, but ran into it later): rather surprisingly, various meters and detectors can't get through the customs as personal use items (see Категории товаров, не относящихся к товарам для личного пользования, position 12, and ТН ВЭД ЕАЭС codes for those, particularly 9024, 9027, 9030, 9031), and apparently can be received by non-human legal entities only. Though UPS still tries to get it through the customs for human legal entities, but I've failed to do all the paperwork in time, so an item didn't even reach the customs (so, it's a good idea to hurry, check email regularly, and not waste time on printing/scanning documents properly if there's no equipment at hand, if one attempts to order various meters anyway).

A metal plate was the hardest to get (guessing that it would be, I've started with it). I've targeted aluminium, and perhaps it was a mistake, since it requires a more expensive laser than steel or acryl, and may just not be the best material for a keyboard plate, since it bends (even if it gets back; there are different kinds of aluminium). Had to look through dozens of ugly and generally disgusting local websites, writing and asking whether they could cut a single plate, and the answer usually was "no, but we can cut 80". Websites of foreign companies were not very different, but there was also a delivery cost attached. Finally I've found a local company that did that for a more or less reasonable price, and got a couple of plates (since it was about the same price as one anyway, but that way I had a spare one). They were slightly bent though, and it made me to worry about how it would work out, and I've tried to straighten them (heard that it would harm them, but apparently it didn't). Good news are that it was the worst part; the rest went more smoothly. Perhaps the only nice thing here was that they didn't hog personal information: didn't even ask a name or phone number, just gave an order number by email, and I've picked it then.

The switches I've ordered on ebay; it required a PayPal payment, and PayPal required a lot of private data (not just name and delivery address), and was not usable with FF accessibility features: the card type selection is done via NIHed select, which is made with divs and background images, so I've filled the data a few times before figuring that out. PayPal is terrible, and not just in that, yet Cherry GmbH doesn't sell the switches directly, so one has to use ebay or something like that. Payment systems are terrible in general, perhaps PayPal is not even the worst: at least your card number is safe until they'll leak it. Oh, and I think I've received 98 switches instead of 100 (actually didn't recount them, since didn't care that much – needed even fewer).

The PCB I ordered on Hackvana (which was closed in 2018, but there are other similar services): though had to pay for delivery there as well, it was nice, and there is IRC support. Had to whitelist their host on my mail server though, since it was getting a high spam score; also had to order 5 PCBs at once. But it seemed like local companies were not eager to make single PCBs, and I was worried about quality at that point, after the metal plates. They accepted PayPal payments (with 5% tax) and some transferwise thing, which was seemingly even more broken than PayPal: error messages like "error.unexpected.please.contact.CS", and just doubtful claims like "100% SECURE & FCA AUTHORISED". By that time, the card I used for PayPal has expired, so I tried to add a new one, but nothing seemed to happen when I did that a few times. Eventually I opened it in a clean browser profile, but the card was already there. Anyway, hackvana is nice, and I acquired nice PCBs.

Though not only the payment systems are bad – I am forgetting to mention delivery. The only delivery option was EMS, which works here like this: a courier arrives at random time, you're not home or sleeping, they leave a note. Then you should call them, they don't respond. Then you are finally getting to their call center, and trying to retrieve the delivery. Apparently it's better to avoid EMS in Russia whenever possible. Update (+1 year): sometimes it takes weeks, multiple scheduling attempts, and retrieval from a remote post office by yourself in the end to get your parcel with EMS; their courier service is barely functioning in Moscow, and the warehouse is not particularly easy to reach, but apparently it is easier — and much faster — than to get a courier delivey. Another update (2023): the regular Russian Post used to work relatively well, but now there are long queues, and then it turns out that the parcels are not sorted out yet, so you have to visit them and stand in those hour-long queues multiple times.

The diodes (NXP 1N4148) I've acquired locally (finally, an easy one).

The keycaps I've ordered from pimpmykeyboard.com. The delivery cost estimation form was buggy there at the time, so ordered by email (at least the support was helpful). They've arrived from Washington to Moscow in under a week, and then took a month to get from Moscow to Moscow (not even on customs). (Update: as of 2020, it's somewhat better with UPS "extremely urgent" delivery: a few days to arrive from another continent, then 10 days to get through the customs, but then courier delivery is quick.)

I've also acquired a cheap soldering station, a table lamp, solder with flux, solderable breadboards and pins for practice, safety glasses, and other common things locally. A good lamp was surprisingly hard to find, by the way: most of them are decorative, not functional. Most of the designs are both ugly and just screw things, by e.g. reflecting a portion of light into your eyes instead of keeping it directed – somewhat similar to web design overall, actually.

## Soldering practice

It took a while to acquire all the components, so I've learned and practiced soldering during that time.

There are nice videos, such as Collin's Lab: Soldering, and plenty of articles around. The process doesn't seem to be hard, but requires some practice to figure small details (mostly how the solder behaves).

I've acquired solderable breadboards and pins, soldered hundreds of joints before getting to the keyboard PCB. Started without proper lighting, and acquired a table lamp later; it is much easier to solder when you actually see what you are doing.

I've also acquired a multimeter, and seeing that everything works (i.e., there is contact) helped to build some confidence.

## Assembling the keyboard

I've watched the Ergo-Dox keyboard assembly video to get an approximate order (though it was clear anyway, but was looking for tips and such), though this keyboard is different. Soldered everything together, except for the controller pins (soldered them to the controller, but not to the keyboard PCB), and wrote test firmware, all that over a weekend, and – somewhat surprisingly – it worked.

Then I've attached keycaps, found that one column doesn't work. Decided to solder the controller legs, and it seemed to be faster, easier, and better than soldering before that; apparently I've actually acquired a soldering skill, which I may never use again. Everything worked fine then.

## Writing the firmware

I've used PaulStoffregen/{cores, teensy_loader_cli} to deal with firmware, though the official alternative is some bloated Arduino SDK that requires Java, and a proprietary GUI loader.

There is no documentation, so one has to figure how it works from sources. A gotcha for newbies such as me was active low, also described on the PJRC Digital I/O page. I've imagined active high before, so had to get it by using `INPUT_PULLDOWN`, as can be seen in the firmware.

Apparently the delay between scans should be 4-5 ms for Cherry MX switches, and that's it; writing the firmware is fairly easy.