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 (http://geekhack.org/index.php?topic=57008.msg1292479#msg1292479) 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
(http://i.imgur.com/suQytIEl.jpg)
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) (http://deskthority.net/resources/image/4776)
Once it's connected it should look something like this - More
(http://i.imgur.com/1Y5fpl.jpg)
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. (http://deskthority.net/resources/image/5174)
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
(http://img.photobucket.com/albums/v367/mikelanding/HHKB%20O%20Ring%20Mod/Oring0.jpg)
(http://img.photobucket.com/albums/v367/mikelanding/HHKB%20O%20Ring%20Mod/oring1a.jpg)
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
#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
#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
#define KEY_STATE() (PIND & (1<<7))
#define KEY_PREV_ON() (PORTB |= (1<<7))
#define KEY_PREV_OFF() (PORTB &= ~(1<<7))
with
#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
OPT_DEFS += -DBOOTLOADER_SIZE=4096
to
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.
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 (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 :thumb:
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.
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
(http://i.imgur.com/8QE77lc.jpg)
(http://i.imgur.com/wrxd4JP.jpg)
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.
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 (http://geekhack.org/index.php?topic=12047.0).
Show Image
(http://i.imgur.com/xKHNxV3.jpg)
Thanks for the quick reply. I will be doing this or a similar mod when I get my hhkb, will check with hash then.
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 :p
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
(http://i.imgur.com/RcJEe.jpg?2)
That explains it (in a very detailed way). Thanks!
Here's my first pass at my own mod with added USB hub:
Show Image
(http://i.imgur.com/ftAtIcD.jpg)
The appropriate response to that hotmelt glue job is "THE HORROR, THE HORROR" in your best Colonel Kurtz.
I had to puzzle out the tmk firmware a bit since it's changed quite a bit since the original thread post. Hasu clearly moves fast. Smasher816's write up (http://geekhack.org/index.php?topic=57008.msg1292217#msg1292217) and this DA post (http://deskthority.net/workshop-f7/how-to-build-your-very-own-keyboard-firmware-t7177.html) helped in getting to a working state (and since I'm typing on it now, I declare initial victory).
I'm running a tweaked (both in terms of timings and layers) SpaceFN layout. Really like it so far.
The one thing I want to add to this board is a feature that LOVE on the Leopold FC660M: Escape takes the place of the grave/tilde key, but Shift-Esc still produces a tilde (lesser used grave is banished to fn-Esc). I'm not entirely sure how to proceed in modifying the TMK firmware to produce this result. I'll continue to explore things, but any TMK pros out there that could weigh in would be appreciated.
Also, for anyone looking at the current TMK firmware and not sure what to mod to match Smasher816's pinout, I'm happy to load the relevant files to up to a gist...
Interesting project. It does look pretty horrible - but hey, if it works, then it works. Congrats! Somehow I feel there might be a better way by cannibalizing a usb hub and just plugging the teensy into that instead of hacking into the stock board. I'm not sure about that though.
Would you mind making the gist? I actually haven't updated much since I initially flashed the board, so I am still on an older version of the TMK code. So it would be nice to get updated again and update the OP. I could probably figure it out, but no sense in reinventing the wheel if it has already been done before.
Here's a minor revision (quick and dirty shield for cable retention) and a shot of the bottom where I put a hole in to do a hard reset on the teensy (for when magic keys aren't enough).
Show Image
(http://i.imgur.com/hHPw8AD.jpg?1)
Show Image
(http://i.imgur.com/XK4zoUS.jpg?1)
This mod is awesome! Programmable Teensy controller, USB hub retained (added), and a flash drive, wow. Maybe next you will replace the flash drive with a MicroSD card slot mounted in the side of your HHKB!! :D