Happy Hacking With Teensy

10 Jul 2015 in Programming / Projects

I’ve been enjoying my Ergodox for quite some time now, mostly due to its comfortable layout and split hand design. One of the features I have not fully explored is the programmability of the Teensy 2.0 microcontroler that drives the keyboard. While I have my own layout and a few layers, I haven’t dived into the capabilities this flexibility offers.

The Ergodox is primarily a work keyboard, but at home I switch between a Happy Hacking Keyboard Pro 2, or HHKB and a Filco Majestouch with Cherry Blue keys. Given the HHKB’s compact layout, I felt some adjustments via layers might make life a bit easier. In particular, I didn’t quite like how the Control key took the place of the Caps Lock key, which I usually mapped to Escape for vim. I tried to get myself to get used to the alternate escape key combination Ctrl+[, but switching between keyboards often made this awkward.

Enter TMK and Hasu. TMK is a custom keyboard firmware that can be built for a number of microcontrollers, including PJRC’s Teensy 2.0. Hasu has gone through the effort of printing a set of controller boards that can be screwed into the space where the original HHKB control board sits, but I decided ordering the Teensy would be faster (and cheaper).

The parts list:

Teensy 2.0 microcontroller
13 pin female connector pin-compatible with the HHKB’s internal cable
Sugru
13 wire harness (could come from anywhere as long as it’s the right size)
heat shrink tubing

The installation instructions are relatively straightforward. I’ve made one or two changes from Hasu’s original instructions. As I don’t prefer to double-up wires on individual holes (and the Teensy has two 5V pins and two ground pins), I’ve wired those seperately to the pins at the “back” of the Teensy (the “front” being on the micro USB connector side). Also, for some reason, Smasher816 decided to move two pins around (PD7 to PF0 and PB7 to PF1), which requires changes in TMK to match. I don’t recommend doing so, as it just complicates the installation for no reason I can see.

After wiring up the pins and testing the keyboard with the default HHKB layout, I had two problems to solve. The first was how to secure the Teensy to the case without damaging or altering the case, and the second was deciding on the keyboard layout.

For the first, I chose to go with Sugru. Since the “front” of the Teensy fits nicely into the micro USB port on the case and it happens to be opposite a small clip, I decided to put the Suguru in between the “back” of the Teensy and the clip on the case. To take it out, I rotate the Teensy from the “front” and the Sugru on the side with the clip, and the Teensy lifts out easily. The Sugru was also formed to be slightly over the “back” lip of the Teensy, so as to hold it down.

Warning: The Sugru will stick to your parts if you simply form it against the Teensy and the case. You can wrap the Sugru in cling film/plastic wrap so it will not bond to the Teensy or the case, allowing you to remove it once it sets.

For the layout, the two things I wanted to add were the SpaceFn feature, which would give me access to a Fn layer without having to reach for the Fn key, and a Dual Role key for Escape/Control for the Control Key.

You can find the keymap here.

The keymap is basically the same as the standard HHKB, but the spacebar, when held down, gets you to layer 2. I’ve currently just assigned a few media keys to the left side of the home row and Vi-style navigation keys to the right side of the home row. Also, when you tap the Control key, you get Escape instead. If you hold it down, you get the Control modifier. The creators of TMK seem to also gone through the trouble of detecting when you’ve double-tapped the space bar and held it down, thus allowing you to insert spaces until you lift off the key, as opposed to going into SpaceFn mode.

A few pictures of the keyboard:

The HHKB