Model 2, Part 2 - Sourcing, Assembly, and Programming

Last Updated: 2022-07-14 07:30:00 -0500

Earlier on, I discussed the process I went through trying to design the Arcana Labs Model 2, a specialty mechanical keyboard that had to fit a space constraint while also including some kind of pointing device. That post dealt largely with the process of design at a high level; how I came up with the necessary constraints, and what tools I used to facilitate things. This post is going to deal with assembly, as well as the process of getting the firmware working.

Assembling this project was an absolute bear, with lessons to be learned in procurement, design, planning, and actual hands-on-tools work. It’s also still not technically complete; in the process of writing this article I found Yet Another Bad Line (we’ll talk about that later), the rotary encoders for the pointing device need to be re-ordered and installed (and the commensurate changes made to firmware), and, CRITICALLY, a new backplate needs to be designed, assembled, and installed. Let’s get into it.

Pre-Assembly: Sourcing Materials

The largest expense in the project - unsurprisingly - and therefore the biggest delay in terms of doing it piecemeal, was assembling all of the parts. After I had my SVG files (and made a few small changes to them in, of all thinks, Inkscape), I was able to send them off to a manufacturer, Ponoko, to have them cut from the materials I chose. This was part of the expense, really. I recognize there are cheaper laser-cutting vendors out there, and cheaper materials I could have used than acrylic, brass, and walnut-vaneer plywood.

Everything else in the keyboard was a commodity part. My favourite supplyer for electronics components, Digikey, was able to provide not only the solder, flux, and wire in use, but also the signal diodes that help make up the matrix, the teensy4.0 I ran the firmware on, and the Cherry MX blues themselves. This was, of course, where I ran into one of the first real blunders of sourcing. In coming up with my Bill of Materials, I failed to verify that Cherry still made the Blues in their clear-bodied RGB form-factor. Thes special clear switch bodies facilitate the passage of light from LEDs mounted underneath their plane in the keyboard, and as a stretch goal to the project I had specified the use of nearly 100 rather spendy serial-addressable LEDs into the design. For reasons we’ll get into when talking about final assembly I’m ultimately kind of glad I now won’t be able to, but because I ordered the parts in a piecemeal fashion I ordered the LEDs BEFORE the keyswitches, and they’re now completely useless to me; for this project, anyway.

I went to great lengths to find a specialty supplier that could produce the screws I wanted to use - I was hoping for something with a large “cheese” head for the look of the thing, and paid well more than it was worth to have the keys shipped in from the UK. While they did come out as nice screws, they aren’t quite the visual effect I was hoping for. I also misunderstood the measurements and got them in a size that is too short by exactly the thickness of the head. In the final design with the remade back plate, I’ll need to replace these screws as well.

Some keyboard parts are so specialty as to need specialty vendors. At a recommendation from a friend of a friend, I ultimately went with MechBoards as the supplier for the stabilizers and keycaps I ultimately went with. Again, in a planning and design failure, the stabilizers I ordered were inappropriate in type and insufficient in number. We’re seeing a pattern emerge on this project; Patch Arcana is an idiot.

In shortest form, a lot more planning and research should have gone into both the original drawings and part selection/sourcing. I’ll be talking about that more in a future episode, but it’s worth noting that this phase of the project is where it REALLY started to go off the rails, and almost everything thereafter is an act of salvage.

Assembling the Key Matrix to the Switch Plate

The QMK firmware documentation helpfully provides a guide on the particulars of designing and implementing a key matrix. For the sake of readability, I will briefly summarize the concept: in order to not require a unique pin on the microcontroller for each individual key in a keyboard (in my case, nearly 100, plus three encoders), it is the standard practice to design a grid wherein either the rows or columns of the grid are protected by diodes, and the opposite member is simply made up of conductor. By having a unique pin on the microcontroller connected the common element of each set of diodes and another to each wire, you can read the entire grid of keys using only COLUMNS + ROWS pins.

The most time consuming single activity in a keyboard project - and certainly in the assembly of a keyboard, is constructing this grid. If you’re working from a kit or have more advanced manufacturing capabilities than I do, you can work from a printed circuit board, and that would be pretty straightfoward. Thread in all your diodes facing the right way, solder them down, trim the legs, then repeat with the switches, and drop in the controller. Easy peasy.

Unfortunately, the manufacturer I work with for printed circuit boards doesn’t do single-unit production, and I had no use for five PCBs for a keyboard I was only going to make one of, not to mention the signficant expense five PCBs of that size would have represented. This really left me with one real option - hand wiring. What’s more, I had to hand-wire with the materials I already had on hand, which in retrospect were not best suited for the job.

Each individual joint on the keyboard was a learning opportunity, and in point of fact, I am still finding places where the joins are suboptimal, causing odd behaviours in the keyboard. Without sufficient work-holding to keep diodes suspended correctly in orientation I ended up with a lot of messy joins, fewer straight lines than I normally like to see, and a matrix that was wired to be taller in space than I actually would have liked.

This introduced another opportunity to learn for the next go-around of the design phase; I failed to consider the impact my materials choices had on the room available inside the keyboard. This meant that even before wiring in the microcontroller, test assemblies with the back plate were disturbing and weakening the solder joints by physically squishing the device.

It’s very important to thoroughly inspect and ensure the stability and conductivity of every solder joint you make here, and that is likely to be three for every switch in the keyboard, plus a few when you wire in the microcontroller. A missed connection can lead to an entire row or column of your keyboard simply not working. A flaky connection can lead to problems like keyswitch stuttering, where a key only works intermittently or a single keypress is detected as multiple events by the firmware.

It was only after I finished assembly that I realized PCBs for both “halves” of my keyboard would have existed as seperate projects, and with a little junkyard engineering I probably could have obtained one of either, and used them to greatly facilitate the wiring up process, which would also have made the internal space of the case less of an issue.

Assembling the Case Layers

Once I had the matrix wired up, I wanted to determine, in concrete terms, the actual envelope of the interior of the keyboard, in order to help me position the controller. As I mentioned in the earlier chapter, I had attempted to save some money by breaking up the “hollow” middle layers of the case at their corners, using registration shapes to fit them back together.

My design of these registration marks failed to take into account the kerf of the laser, which is uneven in acrylic, and also lead to missing some dimensions because parts were now smaller in space than originally intended. Try as I might, I could not get stable joins for the hollow layers by only gluing their corners back together, and they also would not come out square. I ended up having to use CA glue to glue the pieces of the “open” layer to the bottom of the switch plate, and the pieces of the closed layer to the bottom of the back plate. In the end, this would save me some energy later.

Once I had these pieces assembled and cured I was able to do a stack-up and assembly, and this was when I discovered the screws I had selected were slightly too short. For expediency’s sake, I chose to solve this problem by taking a modeling file to the acrylic and wearing down the corners, which weakened them significantly, but as I saw it, so long as I didn’t drop the keyboard (which already had fragility problems given the interior wiring condition), we could tolerate such weakenesses.

I didn’t know it at the time, but this first assembly probably damaged the matrix; it also certainly made it abundantly clear how much the remaining space inside the keyboard was at a premium.

Making Stabilizers Work Where They Shouldn’t

I hinted last time that the stabilizers I ordered were inappropriate, but I never really got around to explaining why. While they were the right format (Cherry), and worked with my keycaps, my decision to make the switch plate as thick as I did didn’t align with the standard conventions for such things, and the stabilizers could not be installed correctly into the plate.

Since they are thouroughly necessary for the proper function of the keys they belong to, I had to improvise to get them working, by trimming away parts of the housings, and ommiting the metal levers that join the left and right stabilizer together. In the case of the spacebar stabilizers they were so wrongly positioned on the plate that I had to admit the inner portion of the stabilizers altogether and trim away at the uprights so that they acted as guides to the spacebar’s underside rather than how they normally operate. Time will tell how stupid a decision this was.

This was also the step where I figured out that my rotary encoders and the knobs I picked out for them are too short to install on the keyboard and that I need to source new ones.

Installing the Microcontroller

The Teensy 4.0 has just enough pins that in my preliminary figuring of the wiring, it was possible to connect all of the keys, and the rotary encoders, and still have two lines open for potentially adding an LED matrix, which is why I selected it. I was also, being arduino compatible, seemingly the easiest solution to my space constraints. While I’m obviously much more familiar with the MSP430 product family, nobody I’m aware of makes a board for one as small as the boards for the Teensy.

What I hadn’t really thought of prior to assembly was the inherent conundrum of a compact device like the teensy. Consider the following factors:

  • My matrix, and the lines connecting the matrix to the controller, are made up of relatively thick and stiff 22 AWG single-core “jumper” wire;
  • The Teensy 4.0’s reset button is on its obverse face, and;
  • TEN of the GPIO “pins” are actually surface-mount pads on the reverse face.

This put me in the uncomfortable position of having to orient the device upside down and backwards, leaving it largely immobile once most of the lines were connected, and just enough space to get in underneath it with my sparrows lock-pin tweezers to hit the programming button. While I do trust it to hold its orientation in space without exterior supports, this rigidity made it difficult to remap all of the pins once I lost the original note that told me which row and column were attached to which GPIO pin. What’s worse, all I’ve left myself to connect to when I go back to add the encoders are a few of the surface-mount pads, and if I’m indelicate in that installation I risk desoldering the other, neighbouring pads.

In retrospect, I think if I was doing this again I would have just ordered the slightly more expensive Teensy 4.1, which has the same capabilities and chip, but exposes all of the GPIO pins as holes in the edge of the card, and would have been easier to wire up as well as possible to wire up with the reset button facing upward.

Compiling the QMK Firmware

QMK has complete, if not slightly byzantine, documentation, and a well-developed ecosystem for designing a custom keyboard configuration and flashing it to the device. I will spare a recounting of that process in great detail as it will be idiosyncratic for your device.

I also didn’t take the time, initially, to do much that was fancy with the keyboard. I programmed a simple two-layer layout that added some function keys to the number pad for controlling things as relates to audio (the usual vol up/down, skip/play/pause, and mute) as well as a keybinding to reset the teensy into programming mode (allowing me to flash the keyboard without removing the back panel of the keyboard). Future firmware changes will be added for the rotary encoders as well as likely more and more specialized function keybindings.

However, I did run into one chief difficulty - the Teensy 4.0 is not an officially supported host for QMK. There is a single keyboard in QMK I am aware of that uses the Teensy 4.1, the Kinesis Kint41, and between consulting that keyboard and its open issues, as well as the Chibi OS submodule QMK relies upon, I was able to get the values I needed to include in the and config.h files to get the keyboard working.

This also leads me to point out that when dealing with the Teensy 4.0 (and presumably, the 4.1) you can’t use QMK’s make tooling to program the board. Instead you need an alternative method that accepts hex files produced by qmk build and will send them to the device manually. PJRC, the makers of the Teensy, offer a variety of options. They all seem to suck, but the CLI Version of Teensy Loader was the easiest for me to figure out and ultimately what I went with.

Debugging. For Weeks.

It took quite a bit of debugging to get the keyboard fully working; a lot of working out which rows or columns were misbehaving, then investigating why (usually bad soldering), repairing the issue, and back and forth. The function-escape keybind to reset and reprogram the keyboard was wonderfully helpful in this regard. While I’m still finding the odd time where my usage of the keyboard has shaken something loose and caused a problem, for the most part those are easy fixes.

Where we did run into a very major problem is with the case back. As mentioned, there’s very little interior space in the keyboard. Adding the current back plate to the stack and securing it with the screws applies enough force to the teensy to depress the programming switch, rendering it effectively non-operative. I’ve been using the keyboard without a back plate, until I can figure out a way to source a new back and a new “closed” layer to assemble, along with new fasteners to hold it all together.

What’s Next?

Next up in this series are going to be two articles: one as a complete discussion of failures during the design process and what can be learned from them to apply to future projects, and one a discussion of the specific foibles in the actual assembly process, in far greater detail than covered briefly here.

As far as what’s next for the Model 2, I really need that new back plate, and just this morning (midway through writing this article, in fact), it had developed yet another spotty solder joint that could use a tap or two from the Magic Hakko to correct. The rotary encoders are also going to be needed if I ever want to start work on the model 3, though that might be shelved for a bit. We’ll have a State of the Lab post to talk about that in the near future.

Finally, there’s a question I’ve been asked at least twice, and been asking myself for weeks now: would there be a Model2 Mark 2, or some other redesign of this keyboard. I think the answer to that is a qualified maybe. I would absolutely love an opportunity to redesign this keyboard properly, incorporating the lessons I learned the first time into an improved design. Where I hesitate is in ever actualizing that design into a physical object. No part of this project was cheap, and even if I did the right thing and salvaged the maximum amount of components from the first one into a second, I’d be looking at a reasonably significant outlay to get it all done. As it is, I have no, or next to no, ongoing hobby budget for at least the rest of the year, apart from what the fine folks that sponsor the lab throw in the cup.

That said, hopefully within the next year or so, my wife and I are looking at buying a house of our own outright instead of renting. If that works, and if we find one with the extra space for a lab that I’m hoping for, I might be able to acquire enough tooling that I can produce some of the more expensive elements of the design in-house for cheaper. So yes, over the next god-knows-how-long, you can probably expect to see a cleaner design for the keyboard as well as a remanufacturing to that better design; I just can’t promise when that will be.

If you wanted to show your support financially, for free tools and toys like Pyminder, Tapestry, and PETI, your best avenue is via my Github Sponsors account or by making a one-time donation to Arcana Labs via or through other avenues detailed here. Github Sponsors also get access to a special patrons-only section of the Arcana Labs Discord Server, where we talk about the ongoing super-secret project.