Flashing HHKB Jp Controller Mac Layout Hex

Having recently received Hasu’s fantastic HHKB JP Bluetooth Controller, I noticed one irksome thing: the alt and command keys were reversed on the left hand side, and the kana key that I typically remap to right command was reverted.

This is normal: the keyboard targets Windows users primarily, but one thing you lose when upgrading to the Hasu controller are the dip switches that allow changing the role of caps lock, the arrow keys and setting it to macOS mode.

The default HHKB layout without Hasu controller
The default HHKB JP OSX layout without Hasu controller – link

Of course it’s a pretty easy change to fix: you simply need to head over to the TMK Keymap Editor and edit the current layout, then download the hex file and flash it, but I’ve done the work, so I might as well share!

HHKB Hasu Jp OSX Layout
A layout that reverses alt and command and sets the kana key to right command for use with macOS computers
HHKB Hasu Jp Alternative Controller Layer 2
An overview of the second layer (layer1, counting from 0) used in the Hasu HHKB JP default layout

First off, as in other tutorials, you’ll need the DFU/AVR tools installed in OSX. This is accomplished by using Homebrew.

The code to get these installed is as follows:

brew tap osx-cross/avr
brew install avr-libc dfu-programmer

Next up, you’ll need to download the layout hex file that I have compiled here: “mac_version.hex“. If, for whatever reason, you need to go back to the default firmware, I have that compiled as well: default.hex. Remember to unzip these files prior to using them if Safari doesn’t automatically unzip your downloads.

Finally, put the keyboard in DFU mode by pressing the button on the back of the controller, where the dip switches used to reside. You may need to remove the cover to do so, and note that you can use the cover if you have short fingernails.

Once in DFU mode, this one-liner will erase the firmware, load the new hex layout and reset the keyboard so that you can use it once again. Note that I’m assuming your hex file will be in the Downloads folder in your home directory, and I’d also recommend having a spare keyboard handy in case anything goes wrong.

Bash script:

sudo dfu-programmer atmega32u4 erase --force && \
sudo dfu-programmer atmega32u4 flash ~/Downloads/mac_version.hex && \
sudo dfu-programmer atmega32u4 reset

Finally, if your layout is still a bit odd (underscore and pipe not working), you may have set the keyboard to the wrong layout. In Apple OSX this can be done by opening the keyboard section of the settings and changing the keyboard layout. Note that it doesn’t really matter that ANSI is suggested when you hit shift+z, shift+?, but that you select JIS once completed, like so:

Open the keyboard panel in System Preferences, then click “Change Keyboard Type…” on the bottom left
Click continue (or press return) to start the detection wizard
Press shift+z, then shift+? as instructed
Select the JIS radio button, even though it defaults to ANSI

Zeal60 Zealencio Zealiostotle JSpacer Holtite Custom Keyboard Build

Custom Backlit Mechanical Keyboard - Ryan MacLean
Custom Backlit Mechanical Keyboard - Ryan MacLean
The finished product – a ZealPC Zeal60 with holtite mod, Zealiostotlespacers, Originative Modern Beige Japanese keycaps resting in a Sentraq teal aluminum 60% case with teal plate.

After much research, I decided to assemble a keyboard using hand-picked parts.
The goals of this build were a bit lofty, but luckily I prevailed in the end:

  • Cold-swappable switches in case I change my mind later
  • Almost silent typing that would be safe for work
  • Tactile feeling on the keys when typing
  • The option to use backlighting at night
  • A small footprint so I could bring the keyboard home for the weekend
  • The board should be programmable and support multiple layouts
  • The keyboard should be as flat as possible
  • There should be no “ping” from the case
  • There should be no flex in the PCB when installing switches
  • Keycaps that fit Zealencios properly – Cherry profile thick keycaps

This led me to a few easy decisions: I would go with a ZealPC Zeal60 as it supported SMD LEDs, was programmable via QMK, was 60%. I’d also opt for Zealio 65g switches as they had great tactile response, and were fairly quiet when combined with Zealencios.

What I didn’t see coming was the arrival of the test Aristotle stems (via /r/mechmarket) and a last-minute purchase of JSpacers from The Van Keyboard. These were for two different projects, respectively: Gatistoles and Jailhoused Outemu blues. During those projects I got to wondering if I could mix the results, and sure enough, figured out a way to add JSpacers to Gatistoles. Not satisfied, I ended up trying this same mod in a Zealio housing, and then to seal the deal, put some Zealencios on top. This led to a tactile switch that was very quiet – more so than a typical dome keyboard.

Creating Zealiostotlespacers with Holtites - Ryan MacLean
Parts required for a “Zealiostotlespacer” – The Van Keyboard JSpacers (black rubber, bottom left), Zealios Switches (purple switch, middle), Aristotle switch stems (white, top right), and Zealencios (clear, top left). This creates a tactile, non-wobbly switch that is both satisfying and almost silent.

In order to be able to cold-swap switches as with the TeamWolf Zhuque+ and PC Gaming Master Race Mechanical Keyboard, I’d need to sort out a way to replicate the recepticles each of these boards implement. After doing a lot of research into LED sip sockets that might work, I stumbled across a Linus Tech Tips forum post about something called “holtites” which were used for this purpose. A few Reddit searches later I found out that the TE AMP connectors would fit the bill, and made a spur of the moment DigiKey order.

TE AMP Holtites - Ryan MacLean
TE Connectivity AMP Holtites – these allow you to “cold-swap” switches without desoldering, perfect for testing different switch types
Holtites Installed on ZealPC Zeal60 PCB - Ryan MacLean
Here you can see the Holtites installed in the Zeal60 board – they are flush-inserted using a spudger and a rotating motion to keep them snug.

Now that I had the switches and board picked out, I was left with a tough decision regarding the case and plate. Nothing I could find actually had the proper mounting standoffs for the Zeal60 PCB, most were of the “Poker” variety, which were missing top screw standoffs, as well as one lower-left. It looked like I had to compromise, and seeing as most 60% cases seemed to be incredibly similar, I ended up going with a Sentraq aluminum case and plate based on looks alone. I ended up getting a cyan case and plate, as well as purple versions of the same, intending to try and colour match the Zeal60. It later turned out that I preferred the cyan varieties, which you’ll see in the shots.

Custom keyboard with Zeal60, Zealiostotlespacers, Enjoy PBT Kana Keycaps, Sentraq Teal Plate and Case - Ryan MacLean
A pretty good match – the Sentraq teal aluminum case fit the purple legends with teal kana subscript

The Sentraq case with the Zeal60 is not without problems: both cases prohibited me from screwing in the leftmost PCB screw, and both seemed to have the wrong thread on the top left standoff. Nothing altogether impossible to get around, but disconcerting all the same. Furthermore, the fit and finish of the top plate in the case wasn’t great, causing the right side to be less snug than the left. All of this to say: I’m still on the lookout for a case and plate that fit well together, and have not ruled out making my own.

Sentraq Teal Case and Plate - Ryan MacLean
The Sentraq plate and case are pretty snug, but there’s definitely room for improvement. That being said, this is a 1:1 macro…

As for the keycaps, I searched all over, asked around and tried a few OEM samples and was not satisfied. I ended up purchasing an Originative Co Modern Beige purple set with kana legends which I am happy with in terms of looks, fit and sound, but am not sure they are fit for work. In other words – I’m still looking for a good set of keycaps. I’ve been told GMK might be the best call for the Aristotle stems, and as soon as I have a sample of them, I’ll report back.

Enjoy PBT Keycaps with Kana Legends - Ryan MacLean
Originative Co Modern Beige with purple legends and cyan kana keycaps
Custom keyboard with Zeal60, Zealiostotlespacers, Enjoy PBT Kana Keycaps, Sentraq Teal Plate and Case - Ryan MacLean
The Cherry profile is perfect for the Zealencios, which didn’t work very well with the OEM keycaps I had tried previously.

Finally, regarding the LEDs: though I was not at all interested in RGB LEDs (preferring white when possible), I ended up actually really liking the default rainbow profile (fn1+2). This is a bit colourful for most, but as I have them turned off most of the time, the assumption is that I’ll be the only one seeing them.

Originative Co Modern Beige Keycaps with Kana Legends - Ryan MacLean
The SMD LEDs are fairly bright when set to max!

Gallery of the rest of the shots from this set:

Building Zeal60 Keymaps on OSX

Before starting, this guide requires Homebrew, which you can install from here: https://brew.sh

Open Terminal, and paste in the following. It will take a while to build, but you should be able to get it all done in one fell swoop:

git clone https://github.com/Wilba6582/qmk_firmware.git
cd qmk_firmware
git branch zeal60
cd keyboards/zeal60
git submodule update --init --recursive
brew tap osx-cross/avr
brew install avr-gcc avr-libc dfu-programmer

You can then make your keymap, like so:

  • make keymap=default
  • make keymap=poker2_ansi
  • make keymap=poker2_iso
  • make keymap=hhkb_ansi

You can run them all if you want, but you’ll probably only need one 🙂

Once you have your firmware, you can flash like so (for HHKB ANSI):

sudo dfu-programmer atmega32u4 erase --force
sudo dfu-programmer atmega32u4 flash hhkb_ansi.hex
sudo dfu-programmer atmega32u4 reset

Getting Started with the ZealPC Zeal60 Keyboard PCB

Recently I picked up a Zeal 60 printed circuit board from BC-based ZealPC, and I couldn’t be happier!

The board supports a few layouts for now, though it’s open source, and you can either fork it to add your own, or add a pull request to share with the community.

The first thing you’ll want to do after getting a Zeal60 PCB is to flash it with the “default.hex” file. I used Windows for this, though you can achieve similar results on Linux and MacOS (OSX).

Initial Downloads

  1. Download Java Runtime Environment (JRE) here: http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html
  2. Download the Atmel flashing utility “FLIP”: http://www.atmel.com/tools/flip.aspx
  3. Grab the most recent Zeal 60 keyboard zip: https://cdn.shopify.com/s/files/1/0490/7329/files/zeal60_v0_3.zip
  4. Unzip the zeal60_v0_3.zip file to your desktop

Install the Driver

  1. Plug in your Zeal60 to your computer via USB
  2. Hit “Windows” and “r” keys together, then type “devmgmt.msc”
  3. Right click the device with the exclamation point next to it
  4. Click “browse for driver”
  5. Navigate to C:\Program Files\FLIP\Drivers
  6. Hit “next”

Flashing the Board

  1. Install the driver –
  2. If you’ve not started assembling anything yet, press the golden button between the “A” and “S” pads on the board (if you’ve already assembled it, unplug it and hold the “space” and “esc” keys while plugging in the USB cable)
  3. Open FLIP
  4. In FLIP, hit connect to the device, and select “ATMega32U4”
  5. Hit “ctrl” + “U” keys to connect to the Zeal 60 PCB
  6. Hit “ctrl” + “L” to load a file
  7. Select the “default.hex” file in the Zeal 60 folder you extracted to your desktop
  8. On the left-hand window, click “Run”
  9. Once completed, then click “Start Application” in the right window

You’re all set!