Building a Dactyl Keyboard, Running QMK

TL;DR - It can be done! I'll save you time showing where I messed up

I've been enjoying a Kinesis Advantage2 as my daily driver at work for a while, but enjoying the world of possibility that QMK firmware gives on the board I've been using at home, an Atreus62.

I've been eyeing a Dactyl for a while, but I was intimidated by the amount of skill I would need to finish the project. It didn't help that somewhere in the ogling, I found a quote somewhere from its creator, Matt Adereth, that the Kinesis is still probably a better choice for most people. Also ordering the case print from Shapeways is hella expensive, and I don't even say "hella", that's how this has got me acting!

There are some cool mods that let you replace the Kinesis controller with a Teensy, which is pretty cool, but that seems pretty nuts too, so I just leaned into the Kinesis for a while. In the mean time, I scored a used Ergodox-EZ and have been using it for a while. This one had its switches swapped for Zealio 67gs, which is pretty close to my now favorite¹ switch, the Zealio 78g.

Just trying the default Ergodox-EZ keymap (once I remapped the thumb clusters to Kinesis for Mac style) jazzed me up again. The Ctrl/Z thing and Cmd/Escape thing² were enough to get me excited about all the options again.

Then I happened upon somebody selling a Dactyl case they were abandoning on MechMarket, so I figured for half the price, I'd give it a shot. What could possibly go wrong?

Lots.

I started with the guide because printing my own flexible PCB? I'm pretty sure I'd have found a way to poison myself. I can barely be trusted with superglue.

The abandoned project I bought came with a Teensy, MCP23018 and the two TRRS jacks I needed. On top of that, /u/hbheroinbob mailed me a TRRS cable, coiled USB cable and stabilizers just to be nice. His game is vintage switch harvesting, so hit him up if you want to buy anything like that. His Aristotle rates are the best I've seen.

Wiring Mistakes Made

Diodes

I had a ton of the diodes I needed to wire the columns and I was using this photo from the guide as reference.

Original Diode Pic from the guide

Looking at that photo made me second guess the direction I was going to wire the diodes in. I was going to wire them with the black bar away from the switch, but the picture has the black bar towards the switch.

I looked up the diode direction in circuit diagrams, but misread the resource which I thought confirmed the picture from the guide, so I proceeded to solder all 70 diodes in backwards! I was actually able to desolder and salvage all of them in the right direction.

Row Wiring

The picture above also uses magnet wire to connect the rows. I just couldn't wrap my head around how the row wire wouldn't touch the column diode wiring and short circuit all the things, so I tried some insulated wire.

This is the first time (and not the last!) that I ran into the most important thing you need to keep in mind when wiring a Dactyl:

THE CASE LEAVES VERY LITTLE ROOM FOR ANYTHING

If you find yourself thinking "Maybe I'll be able to squeeze that in", stop. deactivate. You definitely won't be able to.

I went to the local hardware store to buy the thinnest wire they had. It was 20AWG doorbell wire that stayed wherever I put it when bent. I thought it would fit, and I was so wrong. I thought I took a picture of that monstrosity so I could share here, but I didn't. The red and white doorbell wire gave a candycane vibe, so that was something.

All this to say that after a day and change of soldering, I was actually further behind than having not done anything at all. It's kind of a blur now, but I feel like I tested the wiring with the custom Ergodox firmware referenced in the guide, and then at some point moved to the ergodox-ez build of QMK I was running on my EZ, but that also could be a story I'm telling myself to feel better about all those early poor decisions I could have avoided.

Breadboarding

One thing I got right from the beginning is that I'm likely to screw something up when trying to wire up the Teensy and MCP23018. I thought it would be a good idea to wire up the following diagram on a breadboard to make sure it all worked.

Dactyl Circuit Diagram

So, I wired it up as pictured below.

My Dactyl Breadboarded

I did eventually add the RESET wire, which isn't pictured. At this point I was able to bridge a column with a row and get the expected keystroke like an old-timey telephone operator. The brain was working! So why is this in the "wiring mistakes" section?

After pulling the MCP23018 and soldering some of the pins, we had the first of the Teensy casualties. I could no longer old-timey type with the MCP's matrix, only the ones on the Teensy. I wasn't sure but I suspected that I might have fried the MCP while soldering it.

In order to debug if the two halves were even talking to each other, I made a QMK build with console output and used hid_listen to see the output. I can't stress how helpful it was to have an Ergodox-EZ here so I could flash the same firmware and see what they were doing differently. Anyway, I noticed something I wasn't outputting, so I rebuilt QMK and reflashed the Teensy. Unfortunately I had left hid_listen running in a different terminal, and well... The firmware write failed, the proprietary HalfKay bootloader got fried, and that was all she wrote for Teensy #1.

This was a good time to take a break from Hardware, and since it was a Sunday, there was nothing I could really do except see if there was any way I could factory restore the Teensy. I didn't find a way, and I think it's PJRC's secret sauce, so I gave up and ordered another Teensy.

Waiting for another package

Since I had to wait for a replacement Teensy, I figured I'd look at what else I might need to help me avoid some of the mistakes I already made.

I started with adding some diodes to the cart, in case I couldn't salvage them all. (I did, but 500 for $7 solved every diode shortage I'll have for a long time)

I also bought this spool of 30AWG insulated wire in 8 colors, and you're welcome, it's going to make the final working wiring diagram and pictures super clear for you. I also bought a wire stripper capable of going that small.

Wire Comparison Shot

I really did think my MCP23018 was fried, so I figured I'd order another because a $6 chip was worth me discovering I'd fried the original and not have to wait another week to keep going. I searched for MCP23018 on Amazon and got one result, so I bought it. When it arrived, it was an MCP23017. Yo Amazon, how about saying "0 results" if you don't sell the thing I want.

Since I had a pretty bad time soldering the MCP pins, I decided to give these a shot too, so I could actually remove the MCP23018 if and when I mess up again.

My plan was to also use some pin extenders for the Teensy so I could to the same thing, but I already had those.

Breadboarding Teensy #2

When Teensy #2 arrived, I soldered the pins on, made sure the breadboard was wired up right and tried testing the MCP I thought was fried. I couldn't get it to work and broke off one of the pins, so no matter what was going on, I'd need a new MCP23018. Order placed, left half on hold.

Since QMK isn't like the Ergodox firmware, in that it will let the right half work when not connected to the left, I continued to work with what I had. Once I breadboarded the TRRS jack, I was able to plug the left half of my Ergodox-EZ into the breadboarded Dactyl, and if worked great!

That felt good, and there was nothing in the way of finishing up the left half. I wired up all the rows and columns like the Dactyl guide recommends. I attached those wires to the makeshift female-to-male pin extenders and left plenty of slack. Why? It's hard to see where the Teensy and TRRS jack belong on the top case. It is very clear where they belong on the bottom.

I thought it would be so cool to use some double sided tape to adhere the Teensy and TRRS jack to the bottom of the case, slide all the pins into the right place and close it up.

I did all that, and plugged it in. It worked!! Kinda. The top left key in the right thumb cluster did nothing. Maybe a hardware issue, but it had to be punted on for what was definitely a hardware issue.

I had once again broken the Dactyl prime directive. I thought the extra wire and pins would fit in the case. I was wrong.

In an effort to remove pins or at least bend them to a place they'd fit, I definitely rendered pin F4 useless. After a while I had a build of QMK working that used C7 as a replacement for F4. While it felt pretty good to understand the firmware at that level, I wasn't sure I wanted to run a fork of QMK in perpetuity. Plus, I still had a ton of pins to do to make it fit, how many more will I destroy?!

I tried my best to get Teensy #2 to fit, and I think I did, but when I fired it up, the computer recognized it as an Ergodox-EZ, but no LEDs flashed and no keystroke did anything.

And now we pay tribute to the fallen

The subsection in which I give up.

It was at this point where I told my wife that I didn't think I'd ever be able to complete the project. She, being the most excellent spouse that she is, immediately called bullshit.

I was then quick to rephrase it to "the number of Teensys I'd have to buy to acquire the skill I need here is likely financially prohibitive." It's not necessarily different, but that second one tells me a much better story about me, so I took it.

I gave myself one more Teensy and MCP23018 to get this right.

Wiring Successes

Here's where I give in and really internalize the truth of this case. I need to pack everything as tight as I possibly can. Adhere the chips and jacks to the top of the case. Sometimes this meant rerouting the top row all the way down around row 3 to leave room. It meant clipping off some of the supports for the PCB mount switches I was using. It even meant clipping some of the switches' terminals.

I had a softer touch with the soldering iron around the MCP. I was actually able to pull off using the IC jack I bought with the MCP (sort of) and I didn't use pins at all on Teensy #3.

That one key still doesn't work.

Once I wired the left half of the Dactyl and plugged it in to the right half of my Ergodox-EZ, I found that k00 wasn't working. The exact mirror of what's happening on the right. So now I have two problems, but a clear path to the solution.

Now I felt confident it was a wiring error I had made on both sides. Turns out the error was not comparing the photos I was working off of from the guide with the circuit diagram from the Ergodox-EZ. Look what's going on in the bottom row and far right column! Absolutely nothing. So of course the key I have wired in that spot does nothing. The Dactyl doesn't have the two inside columns that the Ergodox-EZ (or all ergodoxes) has, but that one key is expected to be part of that column. It was pretty painless to add these columns for one key.

The Inner Column

In order to keep all functionality between the Dactyl and Ergodox-EZ so I can use one keymap interchangeably, I decided to add those three missing keys to the outside with Cherry ML switches, which went off without a hitch. These were all on the same column I just added to fix those last two keys.

The Big Payoff

Just to add another wrinkle, QMK treats the physical columns as software rows and the physical rows as software columns. So we end up with a 14 row software matrix!

// matrix positions
{   // MCP23018                                              \
 { k00, k10, k20,   k30, k40,   KC_NO },                     \
 { k01, k11, k21,   k31, k41,   k51   },                     \
 { k02, k12, k22,   k32, k42,   k52   },                     \
 { k03, k13, k23,   k33, k43,   k53   },                     \
 { k04, k14, k24,   k34, k44,   k54   },                     \
 { k05, k15, k25,   k35, KC_NO, k55   },                     \
 { k06, k16, KC_NO, k36, KC_NO, k56   },                     \
    // Teensy                                                \
 { k07, k17, KC_NO, k37, KC_NO, k57   },                     \
 { k08, k18, k28,   k38, KC_NO, k58   },                     \
 { k09, k19, k29,   k39, k49,   k59   },                     \
 { k0A, k1A, k2A,   k3A, k4A,   k5A   },                     \
 { k0B, k1B, k2B,   k3B, k4B,   k5B   },                     \
 { k0C, k1C, k2C,   k3C, k4C,   k5C   },                     \
 { k0D, k1D, k2D,   k3D, k4D,   KC_NO }                      \
}

Here's how it's wired. The solid bars are physical columns and need diodes. The outline boxes are physical rows and need no diodes.

Wiring Diagram

The diagram is color coded to the wire I used in the photos below. It's important to note that the row numbers are backwards from the Dactyl guide, so

My column numbers are in sync with the Dactyl guide, but here they are with color codes and pins:

Wired Right Half

Teensy #3 Hot Mess

A tight spot for pull up resistors

I wired the left half to be a mirror image of the right, with the mirror between the two halves. That means the rows are the same, but the column are both purple on the outside, and red on the inside.

Wired Left Half

I was actually able to use the IC sockets for the MCP23018, but I had to cut them up and use them only for rows and columns. Everything else was soldered onto the chip ever so carefully.

MCP23018 Column Socket

MCP23018 Row Socket, Mislabeled with row numbers from the Dactyl Guide

LEDs

I wired the three LEDs into the top row's rightmost three keys.

Bare LED

Capped LED

Cherry MLs

Here are the Cherry MLs I added. I harvested them from some old keyboards I bought off eBay for $20. If you're going to try this, shoot me an email and I'll mail you some for free! CONUS only.

Cherry MLs

(Universal) Serial Bus

Because I had to adhere everything to the top of the case, things didn't line up as nicely as I was going for on the bottom of the case. In my failed attempt to stick the Teensy and TRRS jack to the bottom of the case, at least the USB port was flush with the hole. I was even able to put a little hole in the case to access the reset button.

By the time it was all done and working, the only cable that I could plug in was one I shaved to fit in the case.

It works, but hardly seems 'Universal'

Rather than do anything invasive, I bought a Mini USB extension cable, which I could semi-permenantly mount, taking some stress off the internal components, and use any Mini USB cable with.

USB Extender, not perfect, but good enough

The Finished Product

So here it is, done.

Done!

Was it worth it?

I was definitely right to be intimidated by this project. And it's super cool that I was able to finish it. It's pretty nice to type on, but I'll do a review on that after I've spent more time with it. So really only time will tell.