Teensy HHKB Controller (Write up)

[Smasher816]

Intro:

Hey it's Smasher816. I found Geekhack earlier this year after researching mechanical keyboards and quickly "fell down the rabbit hole" and purchased a HHKB (Type-S). After a lot of reading and talking with Hasu I have successfully replaced my HHKB controller with a Teensy allowing me to use custom firmware (such as TMK) to bring extra features to this wonderful keyboard. If your interested in this project then keep reading on, if your not then feel free to pass by - I won't be offended.

Before you begin there are a few things you should know about the DIY mod.

Because the HHKB has a fairly modular design you can actually detach the original daughter controller board and connect in your own. You simply build the new controller on its own and plug it in once completed. You can then swap between the stock and custom one as much as you want. This makes it a fairly low risk mod. The only problem I could foresee is soldering the 5V power pin to some data pin which could damage the electronics.

By using the TMK firmware you can gain many great features including multiple layers, mouse keys, and dual role keys. What's even better is that everything you do is saved on the keyboard. Unlike software solutions which only apply to one computer this hardware mod will bring your changes to any computer you use it with. With the HHKB being such a small and light keyboard it makes a great travel companion for the mobile keyboard geek.

For all the perks there are some down sides. You will lose the USB hub on the back (unless you find some way to throw your own one inside). You will also lose the DIP switches (but that isn't a big deal since you can make up for it in your own layouts).

Without further adieu lets begin. Edit: As I write this I have noticed that it is turning out much longer than I expected it to. I hope I didn't ramble on too much.

Hardware:

DISCLAIMER: I am a software guy not a hardware guy. Everything that follows is my own personal thoughts which may very well be flawed.

----- Materials -----
 - Teensy 2.0 (http://www.pjrc.com/store/teensy.html)
 - HHKB header (http://www.digikey.com/product-detail/en/B13B-ZR(LF)(SN)/455-1668-ND/926575)
 - 13 pin ribbon cable
 - Wire strippers
 - Soldering Iron
 - SMALL solder
 - Heat shrink (+heat source)
 - Helping hands

If you want you could use a Teensy or Teensy++ 2.0 but note that if you do decide to you will have to make different changes when setting up the software. Make sure that you don't get one with pins installed as it won't be able to fit in the case. Also, the newer Teensy 3.0 is available but I did not use it because there are not many firmwares developed for it yet.

The HHKB header is what will let you swap between the teensy and the original controller with ease. Without it you would have to cut the original wires or make some other non-reversible hardware mod. These are really cheap if you can get them in stock, it's practically just the cost of shipping - so see if you can buy some other things at the same time. Hasu might still have some extras and be willing to sell them, check with him - http://geekhack.org/index.php?topic=57008.msg1329340#msg1329340

You can find 13 pin cables on many electronic stores online (such as mouser), but there is an alternative. I got an old IDE cable that was lying around and used some scissors to chop off the ends. I then used my fingers to separate the wires. You can keep them together if you want to but I found it easier if I ripped them all apart so I could work with them individually.

You will want small wire strippers to expose the metal inside your cables. The wires I am using are 26 awg (you don't want to get much bigger). A lot of wire strippers don't cover wires this small so double check yours will work. I picked up these (http://www.homedepot.com/p/Klein-Tools-Kurve-Wire-Stripper-Cutter-for-20-30-AWG-Solid-and-22-32-AWG-Stranded-Wire-11057/100352112) at Home Depot for around $20. You can probably return them after you are done if you don't want to keep them and get some money back.

I had a ****ty Weller SP23L laying around and it "worked" alright. If you have anything fancier then please use that. If not think about investing in a good one or borrowing one from a friend.

The header has a 1.5mm pitch (.059" gap between pins), which turns out to be very small when you see it in person. Each pin is tiny and they are fairly close to each other. Home Depot / Lowes / Etc only carry .062" solder which is just too large, there is no way you will be able to get a small enough and controlled solder joint. Please, find the smallest solder you possibly can. I used .025" which worked alright but even smaller would be better. 60/40, a rosin core, and all that jazz are always good. See if you can find a local electronic supply company that has something like that - if not you can always order some Kester online from somewhere like Amazon. Ohh a flux pin and solder wick might come in handy if you mess up.

The heatshrink tubing is technically optional but I highly encourage it. After I plugged my Teensy in I had many issues such as pressing "q" typed "q4", keys that didn't work, and random presses. All this was due to exposed wires that potentially touched each other. Once I covered the ends with some plastic it fixed everything and I have yet to have more problems. For what it's worth I have typed this whole post using my modded HHKB. My tubing looked thin but after it shrunk it ended up becoming too big for me to push all the way down due to the close pins. Hopefully you can find something that will work a little better. If you don't have a heat gun a hairdryer works fine so go find some female friend who owns one. I have also heard that lighters will work in a pinch but it could be hard to control and you might burn your fingers so I would advise against it.

You WILL also want to get some "helping hands". They are invaluable as you line up the small wires and pins. They keep everything still so your hands can focus on the iron and solder. Any cheap one should do. I did not need the included magnifying glass because the pins are still big enough to see fine with the naked eye. Without a pair of helping hands I'm not sure how you could keep everything lined up perfectly as you solder (Having a friend hold the cable or something will not work).

I think that's everything you need. The Teensy is only $16 and everything is possible that you have lying around (if you like to dabble in electrical work). Considering everything else keyboard enthusiasts buy this mod isn't too pricey.

----- Preliminary Info ------

The original controller looks like this

More

Notice how it has a connector in the bottom left corner. Our goal is to make something that will be compatible with that. The finished product should look something like this (Thank Soarer)

Once it's connected it should look something like this -

More

As you can see we will be wiring the header to the teensy with a bit of ribbon wire in between. This is the pinout I used. You might want to print it out or put it up on a big screen, it will help to have it handy.

Before you do any wiring you will want to plug the Teensy into your computer and program it with some firmware. This will come in handy for testing your solder job later. See the software section for more information. Here is a premade hex file to flash - http://geekhack.org/index.php?topic=57008.msg1332045#msg1332045. If you want a graphical program to flash this then look here - http://www.pjrc.com/teensy/loader.html

This is the Teensy 2.0 pinout. If you chose to wire yours up differently this page may be helpful - https://www.pjrc.com/teensy/pinout.html

----- Soldering - Header -----
This was actually my first soldering job so I'm pleasantly surprised that everything went well (especially with something so small). Hopefully it also means that everyone else can do it too. Note: I'm only 18 so I still have pretty good eyesight and a stable hand which did help.

Find a good working place and get yourself all set up. You will want to have a bit of time and patience as it is difficult to work with something so small if you don't have much experience.

I found one of the easier ways to accomplish this task is to use the helping hands to put a little over 1mm of your wire under the pin, then use your soldering iron to push the wire into the pin (make sure it doesn't move, there isn't much room for error), then add a tiny dab of solder from the top.

See this Imgur gallery from Janner for more images on what the soldering job looks like - https://imgur.com/gallery/lk7IU/new

If you don't add enough solder you can always heat it up and add more. If you add to much then you can try to remove some with your soldering iron (or some wick). Be careful that you only heat up the pin you are working on, you don't want to accidentally detach one of the previous pins. If you detach a pin then add some more flux and try to reflow the connection. Messing with the pins and trying to make everything perfect seemed pretty futile to me so make sure they are physically connected but don't worry about it too much.

----- Soldering - Teensy -----

This part is pretty easy since it is just your standard through hole soldering. The holes are fairly large and are separated enough that you don't have to worry about bridging or anything like that.

Mount your Teensy upside-down with one helping hand. Add your heatshrink tubing (DON'T FORGET). Then insert the wire through the hole (from the bottom) and secure it in place with the other helping hand. You can then use your iron and solder on the top of the teensy. Just touch the soldering iron to both the wire and hole and add solder until it looks good.

Note: Don't forget about the heat shrink tubing. If you solder both sides of the wire, then you will have to unsolder one of them to insert it.

Once your done slide the heatshrink tubing over the pins of the header and use your heat source (heat gun, hair dryer, lighter, etc) to shrink them. My heatshrink tubing was too thick so I ended up covering ever other pin and then sliding the rest down as much as I could - that should be enough to stop any electrical contact.

----- Installation -----

Now it's time to open up your precious keyboard. If you have already modded it (lube, 55g domes, silencing, etc) then you will know how it goes. For those that don't simply flip the board over and remove the 3 screws at the back (don't worry they are easy to find). Flip the board right side up again and then open it like a book (the spine would be at the bottom towards you). As you open it make sure to unplug the cable going to the original controller. You can now separate the two halves. See these two pictures (thanks mikelanding).

More

Plug your new teensy controller into the cable inside of the HHKB (Make sure it is the right direction). The red,orange,yellow side should be heading towards the 5V side of the teensy, and the black,brown,red side towards ground. If you forgot to program your Teensy then do that now (you don't need to do any fancy layouts yet, you just want to know it works). Plug the teensy into your computer and fire up AquaKeyTest or something similar and make sure everything is going ok. You might need to double check a solder joint, or ensure that the cables are sufficiently insulated.

Note: Double check you plugged it in the right direction before plugging it into your computer. I'm not sure what happens if it's backwards but I don't believe plugging the power pin into a data pin would be good.

Once you know your new controller works fine you can remove the original one. There is a screw in the top right corner of the pcb that must be removed, it can then simply be slid out. Plug your Teensy into the computer using the usb hole in the back of the case, just like the original one. A sticky pad can help keep it in place (otherwise it will fall back into the case once you unplug it from your computer).

Close everything up and pat yourself on the back. Now it's time to go to the computer and reprogram this bad boy. Take a look at the Customization section below.

Software:
NOTE: This was written on April 11th 2014 and is current at such time. The TMK firmware may (and most likely will) change in the future so avoid simply copy and pasting. The general ideas covered below should not change too much

There are a a lot of parts I could go into more detail about however they are either difficult to explain, vary widely (based on your setup), or are already explained well. Hopefully what follows is understandable to the non-programming mortals out there. If you make any mistakes then the compiler should throw an error message which you can give to someone for help. Knowing C syntax is very helpful.

----- Setup -----

You will need avr-gcc and avr-libc to compile the code, and teeny_loader_cli to program the board. If you run Linux like I do then these packages are probably in your favorite distribution's package manager. If you're running Windows then you can setup WinAVR and get the graphical teensy loader program.

Clone Hasu's wonderful tmk github repo (https://github.com/tmk/tmk_keyboard) and navigate to "keyboards/hhkb" as that is where we will be doing all our work. (For those who don't know you can download a zip/tarball from the github website, or run a command like "git clone https://github.com/tmk/tmk_keyboard.git")

Now that we have all the code we must make a few changes. Hasu's code is designed for a custom made PCB using at Atmega32u4 which has a few differences from our teensy setup.

We must edit the matrix code to match with the wiring job. If you used the same pinout as I did then you can simply copy and paste. If you did not then try to change the code to match the pins you used.

Open matrix.c and scroll down to this line "#elif defined(__AVR_ATmega32U4__)".

Replace the original init block

Code: [Select]

#define KEY_INIT()              do {    \
    DDRB  = 0xFF;                       \
    PORTB = 0x00;                       \
    DDRD  &= ~0x80;                     \
    PORTD |= 0x80;                      \
    /* keyswitch board power on */      \
    DDRD  |=  (1<<4);                   \
    PORTD |=  (1<<4);                   \
    KEY_UNABLE();                       \
    KEY_PREV_OFF();                     \
} while (0)

with

Code: [Select]

#define KEY_INIT()              do {    \
    DDRB  = 0xFF;                       \
    PORTB = 0x00;                       \
    DDRF |= (1<<1);                     \
    DDRF &= ~(1<<0);                    \
    PORTF |= (1<<0);                    \
    KEY_UNABLE();                       \
    KEY_PREV_OFF();                     \
} while (0)

This changes port PD7 to PF0 and PB7 to PF1 and removes the code for the PD* pins.

You will also have to replace

Code: [Select]

#define KEY_STATE()             (PIND & (1<<7))
#define KEY_PREV_ON()           (PORTB |=  (1<<7))
#define KEY_PREV_OFF()          (PORTB &= ~(1<<7))

with

Code: [Select]

#define KEY_STATE()             (PINF & (1<<0))
#define KEY_PREV_ON()           (PORTF |=  (1<<1))
#define KEY_PREV_OFF()          (PORTF &= ~(1<<1))

to correspond with the pin changes.

Next you have to open the Makefile and change

Code: [Select]

OPT_DEFS += -DBOOTLOADER_SIZE=4096

to

Code: [Select]

OPT_DEFS += -DBOOTLOADER_SIZE=512

as the Teensy (halfkay) bootloader is only 512 bytes long (not 4096 like the Atmel one). This will let us easily reboot into the bootloader.

----- Compiling -----

run "make clean" to ensure there are no leftover files.

Then run "make KEYMAP=hhkb" to generate an installable hex file. If you do not specify the hhkb layout you will get Hasu's custom one.

Note: if you are using Windows 8.1 and receive an error about avr-gcc.exe, then check out this thread, it may help you (Thanks to GetzTheGoldfish).
http://www.avrfreaks.net/index.php?name=PNphpBB2&file=viewtopic&p=1118778

Then run "make teensy" which will attempt to program the controller. You should plug the teensy into your computer with a usb cable and then press the small button on it. The program should quickly recognize the controller and begin programming it.

Note: You may need to run the above command as root (ex: with sudo) if it detects the device but does not have permission to communicate with it. (If your on Windows you might need to run it as administrator or double check your drivers, I'm not sure)

If you made it this far then congratulations, you should now have a fully working HHKB running Hasu's powerful TMK firmware.

From now on you should be able to use the "Magic" key combo to reboot into the bootloader (so you won't have to open the case and press the button on the teensy). By default this combo is LShift+RShift+Pause. However, the pause key is accessed with the function layer on the HHKB (FN+P). This makes the combo "Left Shift + Right Shift + FN + P". Once all the keys have been pressed at the same time the keyboard will reboot into its bootloader and wait to be reprogrammed. During this time it will not respond to any keypresses so it might be smart to have another keyboard lying around. A quick word for the wise - If you run "make teensy" before doing this then it will recognize the keyboard as soon as you press the combo. The board will then be programmed and reboot into a usable state. This means that you can flash your firmware with only one keyboard.

----- Customization -----

Copy one of the default layouts (keymap_hhkb.c, keymap_hasu.c, or keymap_spacefn.c) and rename it to something else. Make sure to use the new name when you are building.

For example: If you copy keymap_hhkb.c and rename it to keymap_gh.c then you will change the command to "make KEYMAP=gh". (You can also edit the Makefile to change the default keymap if you are lazy and know how to).

Open the new file and find the big KEYMAP() section. It should look something like this.

Code: [Select]

           KEYMAP(ESC, 1,   2,   3,   4,   5,   6,   7,   8,   9,   0,   MINS,EQL, BSLS,GRV,   \
           TAB, Q,   W,   E,   R,   T,   Y,   U,   I,   O,   P,   LBRC,RBRC,BSPC,       \
           LCTL,A,   S,   D,   F,   G,   H,   J,   K,   L,   SCLN,QUOT,ENT,             \
           LSFT,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,RSFT,FN0,             \
                LGUI,LALT,          SPC,                RALT,RGUI),

This is where you will change what each key does. You can also paste in another keymap section if you would like to add another layer (just make sure to add a way to switch to it). For a very dry, in depth, and possibly confusing explanation of layers and functions see https://github.com/tmk/tmk_keyboard/blob/master/doc/keymap.md. For my help I would look on google for a guide dedicated to creating your own layouts, or create a post in the TMK thread asking for help (link at the end of this post).

----- More -----

If your still following along then thank you. It took a bit of time to write this guide so I hope it helps some other people out there. Having a keyboard set up exactly as you like is a very nice feeling

Here are some additional links that may be of help or are interesting.

http://deskthority.net/workshop-f7/hardware-dvorak-hhkb-t3415.html - The "original" DT thread that got me interested in this mod. Contains many pictures you will want to see.

http://geekhack.org/index.php?topic=41989.msg841759#msg841759 - The official thread for Hasu's firmware. The people there are friendly so look there for all your questions and information.

http://geekhack.org/index.php?topic=12047.0 - An "Alternative Controller for HHKB". Like this teensy mod but an actual professional looking PCB, plus it may get bluetooth support sometime in the distant future.

http://grumpylemming.com/blog/2012/12/24/hacking-a-happy-hacking-keyboard/ - A blog post (similar to this) which covers using a Teensy as a HHKB controller. Note: He does cut the cables so you can not easily switch back to the original controller (ex: if you want to sell it stock, or something bad happens).

http://nathankot.com/blog/2013/09/05/modding-the-happy-hacking-keyboard/ - A blog post using Hasu's alternative controller board. Describes some possible layout tweaks.

http://grumpylemming.com/blog/2013/10/02/hacking-a-happy-hacking-keyboard-revisited/ - Another blog post. Goes over the features of the TMK firmware and his personal layout.

http://stevelosh.com/blog/2012/10/a-modern-space-cadet/#controlescape - A very long and informative blog post by a man who wants to have the best typing experience. There are many ideas presented that you might want to try out.

[SpAmRaY]

Awesome, awesome...did I say awesome...write up! Thank you for sharing.

[RESPRiT]

This is a fantastic write up, keep up the excellent work!

[mashby]

Wow... just... wow.

Great write up. Thank you for providing so much detail for newbs like me to easily understand. 

[Smasher816]

Thanks for all the kins words.

I wrote this pretty late at night and when skimming over it this morning noticed that there are a bit of typos. Once I get home I'll see if I can read through it again and make sure all the sentences make sense.

If any of you decide to try this then be sure to post here with your progress. If you have any problems I'll see if I can help - no promises though.

If you have soldering equipment already lying around then the most expensive part is a teensy - so it's not a big investment. You can assemble the new controller on its own before you ever open your HHKB making it pretty safe. The most difficult part was soldering on the header but with the right hardware and some patience it is doable.

[riotonthebay]

Thanks for the incredibly write-up, Smasher!

I have almost all of the "big parts" required for this – HHKB (duh), Teensy 2.0, soldering equipment and small solder, etc. The only question in my mind is what I might do with my new programmable controller… I basically love the HHKB layout already. What kinds of changes are being made to the layout? (Or for most of us without programmable HHKB's, what changes do you want to see?)

[Smasher816]

The only question in my mind is what I might do with my new programmable controller… I basically love the HHKB layout already. What kinds of changes are being made to the layout? (Or for most of us without programmable HHKB's, what changes do you want to see?)

Read the last few links I posted. There are many ideas presented - some of them you might find you want to use. I'll write out some of these ideas below, not all of them will apply to you since you love the HHKB layout (but someone else might not).

One nice thing is dual role keys. For instance you can make tapping the Control key act as escape, making it even closer (it's very nice if you use vim). If you can get used to it you can try turning it into a Backspace dual role key (like colemak).

If your a programmer you can try turning taps on the Shift keys into parentheses.

If you use another keyboard layout like Dvorak or Colemak you can embed that in the keyboard so it will work on any computer without having to get the language setup.

If you don't like the HHKB arrow keys you can move them. For instance you can use WASD if you are used to that from gaming or HJKL if you use vim. You can also create a FN-Lock key so you don't have to hold the function key down if you will be navigating a lot.

There are other things you can do. You could add a numpad type layer. Maybe add some mouse keys if you are into that.

TMK brings a lot of possibilities to the table.

[CPTBadAss]

Finally, a DIY/How-To writeup that realizes that not everyone inherently understands code and firmware. Thanks for posting this.

[AKIMbO]

Finally, a DIY/How-To writeup that realizes that not everyone inherently understands code and firmware. Thanks for posting this.

I know right?!  Awesome job!

[dsc.]

This is great, thanks for posting!

[Glissant]

Excellent writeup! Thank you very much for taking the time and effort. I will assuredly try this project with the awesome information you provided.

[osi]

Great writeup!! Will reference this if I ever get to this point. My biggest fear is gaming the tabs while opening up the hhkb case  ha

[Smasher816]

My biggest fear is gaming the tabs while opening up the hhkb case  ha

I woudn't worry about it too much. The HHKB is very easy to open. You don't have to unscrew the PCB and dig into all the internals - just get it open with the 3 screws on the back. Once you got it unscrewed and right side up then just grab the back of the upper piece and lift it towards you. To close it line up the 3 tabs at the bottom then lower the back. It should rest closed just fine if it doesn't then try to re-set it. Everything should go together easily - don't try to force anything.

Perhaps someone could upload a video to youtube. I have a bad camera and don't have a channel so I don't think I should. Perhaps it could be picked up by geekhackers or something.

Check out these two pictures from mikelanding's dental mod thread. It's really is simple.

[duq]

!!! Once again. Best community. Great job and thanks for taking he time.

[Smasher816]

Once again thanks for all the kind words. I really do appreciate it.

I finally went back and corrected some typo's in the OP. I also added links to a few more pictures (such as how to open the case), and a few more notes (such as how to use the magic combo to flash).

I also added a little bit more to my reply to riotonthebay. Some of the possible features of this mod are outlined there so you don't have to dig around in the linked pages.

Ohh and Osi, take a look at the the pictures I put in the OP and my last reply to you. Hopefully it should show you that opening up the HHKB isn't too scary.

[sublime]

I've been longing for a tutorial like this for quite some time. Thank you so much for providing such detail

[Smasher816]

Well I'm glad you found a tutorial, hopefully it can help you some.

I ended up cutting up a Command strip to stick the teensy to the bottom of the case. I was a little worried that it might still slide left and right so I made a cardboard cutout to fill the rest of the space the original controller took. It's not perfectly lined up with the hole but it has stayed in place after a couple of disconnects.
 


I also took another piece of cardboard and covered a side with black electrical tape. I then tacked it to the side so it would cover up the two usb port holes. I have to say it actually looks pretty good from the outside.



Now that everything is fairly "finalized" I have screwed the case back together and restored the wonderful thock sound. If any of you want more pictures then I would be happy to open it back up again and take some more. Unfortunately I did not take any pictures while I was soldering everything together

[abjr]

This is really cool, but one thing is confusing me. How does the HHKB matrix work with only 13 pins? 

[Smasher816]

This is really cool, but one thing is confusing me. How does the HHKB matrix work with only 13 pins? 

Take a look at Hasu's github page. He did a good job documenting all of his discoveries.
https://github.com/tmk/tmk_keyboard/tree/master/keyboard/hhkb/doc

pro2           Description                               Teensy++ pins
----------------------------------------------------------------------
1   Vcc(5V)                                              5V
2   Vcc(5V)                                              5V
3   TP1684     KEY: Low(0) when key pressed              PE6 input(with pullup)
4   TP1684     KEY_PREV: make threshold                  PE7 output
5   HC4051     A(bit0)\                                  PB0 output
6   HC4051     B(bit1) > select row(0 to 7)              PB1 output
7   HC4051     C(bit2)/                                  PB2 output
8   LS145      A(bit0)\                                  PB3 output
9   LS145      B(bit1) > select column(0 to 7)           PB4 output
10  LS145      C(bit2)/                                  PB5 output
11  LS145      D(enable) Low(0) enables selected column  PB6 output
12  GND                                                  GND
13  GND                                                  GND

Looking at that, pins 5-7 form a 3 bit number for the row (7 8 possible values, 0-7), and similarly pins 8-10 form the column. Each of the keys then fits into a 7x7 8x8 matrix.

   COL 0     1       2       3       4       5       6       7
ROW -------------------------------------------------------------
   0|  2     q       w       s       a       z       x       c
   1|  3     4       r       e       d       f       v       b
   2|  5     6       y       t       g       h       n             
   3|  1     Esc     Tab     Control LShift  LAlt    LMeta   Space
   4|  7     8       u       i       k       j       m             
   5|  \     `       Delete  Return  Fn      RShift  RAlt    RMeta
   6|  9     0       o       p       ;       l       ,             
   7|  -     +       ]       [       '       /       .             

Hopefully that answers your question

[hjkl_over_wasd]

One nice thing is dual role keys. For instance you can make tapping the Control key act as escape, making it even closer (it's very nice if you use vim). If you can get used to it you can try turning it into a Backspace dual role key (like colemak).

This is my entire reason for getting involved with the keyboard scene in the first place. Xcape is really nice, but it still lags a bit when you're using caps as escape and having to wait a slight moment for the signal to get to Vim. Having this done at the firmware level is exactly what I've wanted ever since I saw the Coding Horror keyboard and learned that crl/caps switching could be done with a DIP switch. Now I see it's possible, but I have to pay 350$ not including shipping and the absurd toll fee I would have to add to that.

I'm glad I've found that this is possible, but I'm also saddened by how much this is going to cost me as I'm still in Uni and currently without a job.

If your a programmer you can try turning taps on the Shift keys into parentheses.

Obviously, this would be a killer feature for LISP-like functional languages, but I wonder how much I'd like it when coding in C or Python.


Thank you so much for sharing this information. I cannot wait until I get to actually use it.

[abjr]

Looking at that, pins 5-7 form a 3 bit number for the row (7 possible values), and similarly pins 8-10 form the column. Each of the keys then fits into a 7x7 matrix.

Not to nit-pick, but 3 bits is 8 possible values, so we'd have an 8x8 matrix. 7x7 would be too small to cover all 60 keys on the HHKB.

Hopefully that answers your question

Yes, it does. Thanks a lot! You guys amaze me with all of this stuff you're able to figure out.

[Smasher816]

Looking at that, pins 5-7 form a 3 bit number for the row (7 possible values), and similarly pins 8-10 form the column. Each of the keys then fits into a 7x7 matrix.

Not to nit-pick, but 3 bits is 8 possible values, so we'd have an 8x8 matrix. 7x7 would be too small to cover all 60 keys on the HHKB.

Your correct. I neglected the 0 values

[margo baggins]

This is one of the best posts on GH! Thanks so much!

[GetzTheGoldfish]

First of all i must say thanks alot for this writeup since it's just what i needed although I did have a slight problem during the compiling that I'll explain in a second. It appears that people using windows especially windows 8.1 trying to compile will receive an error about avr-gcc.exe and I am just one of those people. The problem was in WinAvr and you can find the fix here http://www.avrfreaks.net/index.php?name=PNphpBB2&file=viewtopic&p=1118778
I hope that this will help any other windows users trying to follow this writeup 

----- Compiling -----

run "make  clean" to ensure there are no leftover files.

Then run "make KEYMAP=hhkb" to generate an installable hex file. (this is the part where you get the error on Windows 8.1)

Note: If you do not specify the hhkb layout you will get Hasu's custom one.

Then run "make teensy" which will attempt to program the controller. You should plug the teensy into your computer with a usb cable and then press the small button on it. The program should quickly recognize the controller and begin programming it.

[Smasher816]

Thanks GetzTheGoldfish,

I'll add it to the op when I get home.

Edit: Added. Ohh and welcome to GH

[n0rvig]

Nice work Smasher816. Inspiring.

[hasu]

Smasher816, great writeup!

For those who want to make thier own;
I have some B13B-ZR header connectors. I can send one to you for $3US(to most part of the world). PM me if you want.

left: B13B(right: S13B)

[admiralvorian]

Smasher this write-up is excellent!

After I meticulously built everything and flashed the hex to my teensy 2.0, nothing worked.
So, I told Windows to go to hell, grabbed Ubuntu, and compiled on there. Everything works fine now.

In case anyone else has issues with windows, or doesn't feel like messing with all these libraries and code, here's the hex file for the teensy 2.0 with Hasu's layout. If you want a different layout just let me know and I'll see if I can compile one for you!

[Smasher816]

Having this done at the firmware level is exactly what I've wanted ever since I saw the Coding Horror keyboard and learned that crl/caps switching could be done with a DIP switch. Now I see it's possible, but I have to pay 350$ not including shipping and the absurd toll fee I would have to add to that.

Don't fret so much. There are other ways to get a keyboard with a programmable controller. For instance a QFR Rapid will cost you $80, and "The Frosty Flake" replacement controller is only $20 (if they are still around).

Check out this thread. http://geekhack.org/index.php?topic=46700.0

For those who want to make thier own; I have some B13B-ZR header connectors. I can send one to you for $3US(to most part of the world). PM me if you want.

Take this man up on his offer. It is how I got my header connectors. For what it's worth, Hasu was very kind and responsive in his communication and the goods arrived fine after a while.

The cost of shipping is going to be the most expensive part of getting this ($.50) item. Depending on where you live paying a company like DigiKey to ship internationally to you will probably end up more expensive than Hasu's great $3 offer. At the time I do not remember a cheap USPS option with DigiKey so it would have cost me over $10.

.... Everything works fine now.

In case anyone else has issues with windows, or doesn't feel like messing with all these libraries and code, here's the hex file for the teensy 2.0 with Hasu's layout.

Awesome!

So you followed this write up and got your own teensy to work with your HHKB? If you have any pictures or advice for others feel free to share it.

I will be sure to add a link to the hex file to the OP so that others can use it. It's nice to have a premade file just to make sure that everything is working before you start customizing.

[admiralvorian]

So you followed this write up and got your own teensy to work with your HHKB? If you have any pictures or advice for others feel free to share it.

I will be sure to add a link to the hex file to the OP so that others can use it. It's nice to have a premade file just to make sure that everything is working before you start customizing.

pics

More

don't mind the weights, I'm trying to make my hhkb heavy as possible

Nothing special - I haven't fixed my teensy to the case yet (3M double sided tape should work well, but I might use hot glue to fix it solidly). I'm having a couple problems, though:



I'm a sometimes-gamer and the space bar works really strangely with this firmware. In minecraft, pressing space doesn't result in jumping. I have to double tap, then double tap again in creative mode to get an actual double-jump. Also, pressing shift results in a minute delay while it decides if I'm holding shift down or just tapping it to get the ( character. Is there a way I can fix the space and shift to act like standard space and shift keys? I looked in main.c and hhkb_layout.c and didn't find anything. I also asked in Hasu's thread but haven't had a reply yet.

[Smasher816]

Nothing special - I haven't fixed my teensy to the case yet (3M double sided tape should work well, but I might use hot glue to fix it solidly). I'm having a couple problems, though:

The Command strips that you are supposed to use to hang hooks from walls worked great for me. There might be some better alternatives out there but I had that laying around the house. I would discourage using hot glue because it sounds like a pain to clean up if you ever change your mind.

Regarding the firmware issues. I believe that is because Hasu's layout has "Mousekey layer with Space" (FN6). If you change the keymap to use SPC instead it should act like a normal space key. I also replied about the parenthesis in the TMK thread.

Maybe you should start with the standard HHKB layout and build up from there? "make LAYOUT=hhkb"


Edit: YAY! We made it to page 2

[admiralvorian]

Nothing special - I haven't fixed my teensy to the case yet (3M double sided tape should work well, but I might use hot glue to fix it solidly). I'm having a couple problems, though:

The Command strips that you are supposed to use to hang hooks from walls worked great for me. There might be some better alternatives out there but I had that laying around the house. I would discourage using hot glue because it sounds like a pain to clean up if you ever change your mind.

Regarding the firmware issues. I believe that is because Hasu's layout has "Mousekey layer with Space" (FN6). If you change the keymap to use SPC instead it should act like a normal space key. I also replied about the parenthesis in the TMK thread.

Maybe you should start with the standard HHKB layout and build up from there? "make LAYOUT=hhkb"


Edit: YAY! We made it to page 2

When you mentioned that the standard layout doesn't have that I got very confused. I was compiling using 'make KEYMAP=hhkb' which I thought would specify keymap_hhkb.c instead of keymap_hasu.c. What's strange is that some of the changes I made to keymap_hhkb.c were present, but so was hasu's ( and space key setup.

BRB recompiling.

[admiralvorian]

ok here's my keymap_hhkb.c

Code: [Select]

/*
 * HHKB Layout
 */
#include "keymap_common.h"


#ifdef KEYMAP_SECTION_ENABLE
const uint8_t keymaps[][MATRIX_ROWS][MATRIX_COLS] __attribute__ ((section (".keymap.keymaps"))) = {
#else
const uint8_t keymaps[][MATRIX_ROWS][MATRIX_COLS] PROGMEM = {
#endif
    /* Layer 0: Default Layer
     * ,-----------------------------------------------------------.
     * |Esc|  1|  2|  3|  4|  5|  6|  7|  8|  9|  0|  -|  =|  \|  `|
     * |-----------------------------------------------------------|
     * |Tab  |  Q|  W|  E|  R|  T|  Y|  U|  I|  O|  P|  [|  ]|Backs|
     * |-----------------------------------------------------------|
     * |Contro|  A|  S|  D|  F|  G|  H|  J|  K|  L|  ;|  '|Enter   |
     * |-----------------------------------------------------------|
     * |Shift   |  Z|  X|  C|  V|  B|  N|  M|  ,|  .|  /|Shift |Fn0|
     * `-----------------------------------------------------------'
     *       |Gui|Alt  |         Space         |Alt  |Gui|
     *       `-------------------------------------------'
     */
    KEYMAP(ESC, 1,   2,   3,   4,   5,   6,   7,   8,   9,   0,   MINS,EQL, GRV,BSPC   \
           TAB, Q,   W,   E,   R,   T,   Y,   U,   I,   O,   P,   LBRC,RBRC,BSLS,       \
           LCTL,A,   S,   D,   F,   G,   H,   J,   K,   L,   SCLN,QUOT,ENT,             \
           LSFT,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,RSFT,FN0,             \
                LGUI,LALT,          SPC,                RALT,RGUI),

    /* Layer 1: HHKB mode (HHKB Fn)
     * ,-----------------------------------------------------------.
     * |Pwr| F1| F2| F3| F4| F5| F6| F7| F8| F9|F10|F11|F12|Ins|Del|
     * |-----------------------------------------------------------|
     * |Caps |   |   |   |   |   |   |   |Psc|Slk|Pus|Up |   |Backs|
     * |-----------------------------------------------------------|
     * |      |VoD|VoU|Mut|   |   |  *|  /|Hom|PgU|Lef|Rig|Enter   |
     * |-----------------------------------------------------------|
     * |        |   |   |   |   |   |  +|  -|End|PgD|Dow|      |   |
     * `-----------------------------------------------------------'
     *       |   |     |                       |     |   |
     *       `-------------------------------------------'
     */
    KEYMAP(PWR, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, INS, DEL,   \
           CAPS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,PSCR,SLCK,PAUS, UP, TRNS, BSPC,      \
           TRNS,VOLD,VOLU,MUTE,TRNS,TRNS,PAST,PSLS,HOME,PGUP,LEFT,RGHT,PENT,            \
           TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,PPLS,PMNS,END, PGDN,DOWN,TRNS,TRNS,            \
                TRNS,TRNS,          TRNS,               TRNS,TRNS),
};



/*
 * Fn action definition
 */
#ifdef KEYMAP_SECTION_ENABLE
const uint16_t fn_actions[] __attribute__ ((section (".keymap.fn_actions"))) = {
#else
const uint16_t fn_actions[] PROGMEM = {
#endif
    [0] = ACTION_LAYER_MOMENTARY(1),
};

Then I run

Code: [Select]

make LAYOUT=hhkb
flashing the hex leaves me with hasu's layout. I run

Code: [Select]

make clean before changing things and compiling to ensure I don't have any garbage laying around.

[Smasher816]

Ooops. I shouldn't have written that from memory.

You are correct - It's actually "make KEYMAP=hhkb". So use Keymap not layout like I said before.

If you want to change the default value (for when you omit that part) then open up the Makefile and find

Code: [Select]

ifdef KEYMAP
    SRC := keymap_$(KEYMAP).c $(SRC)
else
    SRC := keymap_hasu.c $(SRC)
endif

and change that "keymap_hasu.c" part between the "else" and "endif"


I'm not sure why only some of your changes are applying after doing a clean compile.

How are you flashing the teensy? If you did not change the

Code: [Select]

DBOOTLOADER_SIZE= part like described in the OP then it will not write the changes correctly when using the magic keycombo. In that case I would make sure you use the little reset button on the teensy to make sure you get a clean flash.

[feizor]

Why does the original controller have so many more components than the teensy? Are the extra parts just for the USB hub functionality?

[Smasher816]

feizor,

I'll be honest. I have no idea why the original controller has so many extra parts. It may very well be part of the usb hub or dip switch addons. I do know that the main pcb is what takes care of all of the key detection, it then sends that information over the 13 pin cable to the controller we are talking about - which handles informing the computer of the keypresses. By changing the controller we change what is sent to the computer.

I would talk to Hasu since he is the one who reverse engineered this board and is creating his own alternative controller.

[feizor]

feizor,

I'll be honest. I have no idea why the original controller has so many extra parts. It may very well be part of the usb hub or dip switch addons. I do know that the main pcb is what takes care of all of the key detection, it then sends that information over the 13 pin cable to the controller we are talking about - which handles informing the computer of the keypresses. By changing the controller we change what is sent to the computer.

I would talk to Hasu since he is the one who reverse engineered this board and is creating his own alternative controller.

Show Image

Thanks for the quick reply. I will be doing this or a similar mod when I get my hhkb, will check with hash then.

[admiralvorian]

Ooops. I shouldn't have written that from memory.

You are correct - It's actually "make KEYMAP=hhkb". So use Keymap not layout like I said before.

If you want to change the default value (for when you omit that part) then open up the Makefile and find

Code: [Select]

ifdef KEYMAP
    SRC := keymap_$(KEYMAP).c $(SRC)
else
    SRC := keymap_hasu.c $(SRC)
endif

and change that "keymap_hasu.c" part between the "else" and "endif"


I'm not sure why only some of your changes are applying after doing a clean compile.

How are you flashing the teensy? If you did not change the

Code: [Select]

DBOOTLOADER_SIZE= part like described in the OP then it will not write the changes correctly when using the magic keycombo. In that case I would make sure you use the little reset button on the teensy to make sure you get a clean flash.

Very strange. I tried KEYMAP= and LAYOUT=

I was using make clean to remove all the compilation products and even checking to make sure they weren't there. I went so far as deleting everything, cloning the repo again, and re-modifying everything.

I made all the requisite changes in the makefile and matrix.c every time. The only thing that ended up working was editing keymap_hasu.c

[Smasher816]

As I mentioned in the second half of my post, how are you flashing it?

I had some issues when using the magic keycombo until I made that DBOOTLOADER_SIZE fix. Using the button on the teensy worked fine.

[hasu]

feizor,
Topre paid reasonable(or excess?) cost to get clean power supply. They use 'filter'(you can see big green inductor and big capacitors) to clean noise and boost converter to get 5V. Good and stable power supply is key for capacitive sensing, I think.
Pro2 has additional components for internal USB HUB but this is not critical. It is superfluous for keyboard in my opinion

EDIT: That big inductor is probably for boost(step-up) voltage converter, not for noise 'filter'. Some componets for surge protection and noise suppression can be found around USB connector. I don't have enough knowledge of analog and power circuit, though.

So far I've never had sensing problems  with my use but I'm just lucky probably. You may have a problem with alt controller if you have cheap HUB/PC with very bad power source or you are in harsh environment like factory with full of powerful machines and noise.

[feizor]

feizor,
Topre paid reasonable(or excess?) cost to get clean power supply. They use 'filter'(you can see big green inductor and big capacitors) to clean noise and boost converter to get 5V. Good and stable power supply is key for capacitive sensing, I think.
Pro2 has additional components for internal USB HUB but this is not critical. It is superfluous for keyboard in my opinion

So far I've never had sensing problems  with my use but I'm just lucky probably. You may have a problem with alt controller if you have cheap HUB/PC with very bad power source or you are in harsh environment like factory with full of powerful machines and noise.

Show Image

That explains it (in a very detailed way). Thanks!

[Smasher816]

Hasu, was there a big revision to the pro 2 PCB's? Because mine does not look like that.

One big difference is the lack of a big green capacitor on the left side. Also, My dip switches are white and slide instead of flip. Other than that they look pretty similar.

Here is a potato shot.

[hasu]

Yes, Topre has probably revised desgin and changed components several times.
I guess your controller is manufactured in Oct 9th 2013 and very newer revision '4'.

I'm almost sure 'NA1F2' means Pro2 controller unit and '4' is probably revision number. Other four numbers are product date(last digit of year, month, day) and serial number.

So Topre manufacture code is comprised like: <Unit+revision> <year> <month> <day> <serial>.
Unit code scheme is also not clear but HHKB has following code at least.
NA011 = Pro1 keyboard unit
NA012 = Pro1 Controller unit
NA1F1 = Pro2 keyboard unit
NA1F2 = Pro2 controller unit


And I have another revision '2' contller(2010/Jul).

[admiralvorian]

As I mentioned in the second half of my post, how are you flashing it?

I had some issues when using the magic keycombo until I made that DBOOTLOADER_SIZE fix. Using the button on the teensy worked fine.

Flashing through teensy cli via magic keystroke. Made the bootloader change in source before compiling anything.

It's all good now, I have my custom keymap by working around my issues (editing hasus keymap instead of using the keymap_*.c method).

Thanks for the help, by the way! I used some hightemp hot glue to hold the teensy in place, it looks 100% stock from the outside!

[Janner]

Hey there,

So I finished my HHKB mod yesterday! Imgur album: http://imgur.com/gallery/lk7IU/new

Immense thanks to hasu for giving me the appropriate header, and OF COURSE for writing the tmk keyboard firmware.

For anyone wanting to try this themselves: I have one B13B header to spare.

@Smasher816: thanks a lot for your original writeup. 'T was very informative.

[Smasher816]

Awesome job Janner.

Thanks for taking pictures of the soldering because I neglected to do that. I'll be sure to add it to the OP so that hopefully others will be able to better see what they have to do.

If you want to do more DIY stuff in the future then you might check this out later - http://geekhack.org/index.php?topic=58718.0. I am planning on using the teensy to make my HHKB into a bluetooth keyboard . Be aware, this one is significantly more expensive (parts are over $80).

[qwack]

Wow, this is stellar. Thanks a lot for this awesome write up, it should clear a lot of questions I have about the Teensy.

[Smasher816]

No problem. Glad it could help.

[jmolino]

Hi Smasher,

Can you help me out here?  I ordered the Teensy 2.0, but for some reason they sent me the Teensy++2.0!  Anyways, I wired it up the same as your diagram (see pic below) with the matching names (the names are a little different, but I think they are the direct related ones).

" alt="" class="bbc_img" />

Note:  I probably should have re-wired it to make it cleaner, but I didn't want to muck with more code changes... and although it looks like a lot of crossing in the image, in the physical world it actually wasn't that bad...

My question is, do I have to change any of the code you posted, and/or is there any other changes I need to implement?  Thank you.  Hopefully this can help other people interested in modd'ing the HHKB Pro2 using the Teensy ++ 2.0 controller.  According to Hasu he prefers this one (I think it is due to the size, or because of bluetooth.. I'm not remembering what he told me... perhaps he will post here and clarify).

Thanks,
John

P.S. why is this image I attached to this post messed up? I can't seem to fix it...

[jmolino]

According to Hasu he prefers this one (I think it is due to the size, or because of bluetooth.. I'm not remembering what he told me... perhaps he will post here and clarify).

I received a reply back from Hasu on this and actually, the Teensy ++ 2.0 is not preferred because it does not "install" properly/easily into the HHKB pro 2 due to the standoff (plastic piece where the screw that holds the case top and bottom halves together goes).  You can probably make it work somehow, or if you don't mind it just laying inside your case loose.... but using the Teensy ++ 2.0 will add this extra layer of complexity to your mod.  Probably best to stick w/ the Teensy 2.0.  Here is Hasu's explanation: http://geekhack.org/index.php?topic=12047.msg1373181#msg1373181