geekhack Marketplace > TMK Keyboard Service

[TMK] HHKB Alt Controller with Mini-B/Type-C connector

(1/136) > >>

This Alt controller board replaces stock controller and makes your HHKB full programmable. The controller is fully assembled and you can install it into your HHKB only with screw driver.

For more technical information see also this thread.

Bluetooth and USB controller look like these.

Note: In current revision pcb color is green. Battery is not included.

HHKB Pro1(PD-KB300*), HHKB Pro2(PD-KB400*) and HHKB ProJP(PD-KB420*) including Type-S are supported.

Note that HHKB ProBT(PD-KB600/620), HHKB Pro Classic(PD-KB401), HHKB Pro Hybrid(PD-KB800/820) and HKKB Lite(PD-KB200/220) are NOT supported.

Bluetooth controllers are out of stock due to scarcity of bluetooth module in the market since March 2022. Only USB controllers are available at this time. 2022-09-26

Bluetooth controllers are available. The controller is assembled after your payment and it takes a week or two to be shipped.  2023-05-30

 - Mini-B USB Controller for Pro1 [42USD]
 - Mini-B USB Controller for Pro2 [44USD]
 - Mini-B USB Controller for ProJP [46USD]
 - Mini-B Bluetooth Controller for Pro2 [77 81USD]
 - Mini-B Bluetooth Controller for ProJP [79 83USD] (Check CAVEAT below before ordering this variant)
NOTE: Mini-B controllers have reliable Hirose USB connector as Topre original controller does.

 - Type-C USB Controller for Pro1 [44USD]  New!(2023-11-28)
 - Type-C USB Controller for Pro2 [46USD]
 - Type-C USB Controller for ProJP [48USD]
 - Type-C Bluetooth Controller for Pro2 [79 83USD]
 - Type-C Bluetooth Controller for ProJP [81 85USD] (Check CAVEAT below before ordering this variant)
NOTE: The Type-C connector comes cheap from obscure Chinese manufacturer, not from established manufacturers like Molex, TE, Hirose or etc. It is unclear about long-time reliablility and durability. But it has worked as expected and got no serious trouble report from users so far.  I mean, you can take Type-C controller if you prefer. It doesn't seem to be too risky now.

Pro1 controller supports all PD-KB300* modles.
Pro2 controller supports all PD-KB400* models including Type-S.
ProJP controller supports all PD-KB420* models including Type-S.
Note that HHKB ProBT(PD-KB600/620), HHKB Pro Classic(PD-KB401), HHKB Pro Hybrid(PD-KB800/820) and HKKB Lite(PD-KB200/220) are NOT supported.

NOTE: Bluetooth controller has all functions of USB controller including USB connection.
NOTE: Bluetooth controller doesn't include battery. See 'Bluetooth Battery' in 'MANUAL' section below for suitable Lipo battery spec.

CAVEAT for Bluetooth Controller for ProJP
More1. Case problem with Bluetooth Controller for ProJP
See this photo, black one is ProJP model and white is Pro2. As you can see ProJP bottom case has no hole for switch and LEDs.

To install Bluetooth controller into HHKB ProJP:
1) you need to drill bottom case to make holes or
2) you can use Pro2 bottom half with ProJP top half as the photo indicates.

2. Japanese specific keys cannot be sent via Bluetooth.
You can remap them to other normal keys. This won't be critical to other language users. See also LIMITATION section below.

All variants of the controller are virtually always in stock. (2023-11-28)

Lead time: Can be shipped usually in a few bussiness days for express shipping or a week for usual postal shipping.

Check this notes for current shipping situation and cost under COVID-2019 pandemic before placing an order. 2022-04-12

0. Read this post carefully and feel free to ask me if you have any question before placing an order.
1. Email me with subject "HHKB Alt" and let me variant of controller and your location in mail body. My email
2. PayPal Invoice will be emailed to you usually in a day.
3. Make sure you supply correct shipping address and recipient name(in English form) on PayPal when its payment. Email me your shipping info if not possible.
4. You will receive an email with tracking number from Japan Post or me after shipping. Let me know if you don't get tracking number in a week after payment.

    With PayPal Invoice you can make a payment with credit card even if you don't have PayPal account.

    Check this notes for current shipping situation and cost

    You can trace postal packet here or your country's postal service like USPS. (Japan Post) (USPS)

Just install it and check if you can type on your keyboad normally.
(For Bluetooth controller user, you can check both USB and Bluetooth function safely even without battery.)

WARN: PLEASE MAKE SURE BATTERY POLARITY BEFORE CONNECTING. Some batteries in the market has reverse polarity at connector and it will fry and break battery charger chip. With the broken charger chip you cannot charge battery fully anymore or controller may stop working completely. I can offer free repair service for faulty charger chip but you have to pay postage for both ways. No RMA service is provided for this, sorry.
Positive(+) side or red wire should be on left as the pic shows.

See "Bluetooth Battery" section below for more info. Get battery from reliable srouces like sparkfun or adafruit if you are not sure.

You can remap keys and download firmwre using TMK keymap editor on web browser. Please use Chrome if you have any problem on other browser. See 'MANUAL' section below for how to flash firmware onto controller.

NOTE: Use proper link to download firmware for your controller. There are four diffrent variants and they are incompatible each other.

USB for Pro1/Pro2 | Bluetooth for Pro2 | USB for ProJP | Bluetooth for ProJP

Use KEYMAP EDITOR to download compiled firmware unless you have specific need.

Firmware source code is available under GNU General Public License. To build firmware from source code consult documentation there.

- Fully Prorammable keyboard functions(USB and Bluetooth)
    TMK firmware offers various features including key mapping, mouse keys and USB NKRO.
- Switching between USB and Bluetooth(Bluetooth)
    You can switch the two connections with slide switch or key combination.
- RN42 config mode(Bluetooth)
    You can change power/connection configuration of the module if needed.
- Low battery alert(Bluetooth)
    Red LED turns on when low voltage.
- RN42 status indicator(Bluetooth)
    LED indicates status of Bluetooth connection.
- Pairing(Bluetooth)
    The module stores up to 8 connections.
- Auto connect(Bluetooth)
    The module connects the last connected device automatically.
- iOS support(USB and Bluetooth)
    works as keyboard with iPhone5. No tested completely. Note that iOS doesn't accept mouse device.
- Android support(USB and Bluetooth)
    works as keyboard and mouse with Nexus5. No tested completely.
- Battery charging(Bluetooth)
    You can charge from USB port or power adapter which has USB outlet.

- Class 2 Bluetooth 2.1 + EDR(Bluetooth controller only)
    Bluetooth module which Bluetooth controller uses is RN42 of Mcirochip:

- Bluetooth module RN42 limitations(Bluetooth controller only)
  See this for detail.
  = Japanese and Korean specific keys are not supported
        Bluetooth module RN42 cannot send HID keyboard usage more than 0x65. This won't affect most of latin language users. On USB connection all keyboard usages can be sent.
  = Mouse button 4,5(BTN4, BTN5) and horizontal wheel not supported
        Mouse button1,2,3(left, right, middle) and vertical wheel are supported.
  = NKRO does not work on Bluetooth
        Bluetooth is 6KRO like normal keyboards.
  = System control is not supported
        It can't send Power, Wake and Sleep keys.

- No USB Hub(USB and Bluetooth controller)
    Controller has no USB Hub fucntion, you lose two USB downstream ports and they turn into just two empty holes on HHKB Pro2.

- Short battery life(Bluetooth controller only)
    Around 12 hours with 850mAh.
    Around 30 hours with 2600mAh.
    BT Controller needs to use battery power to scan HHKB key matrix and get minimum latency on Bluetooth. If you don't mind slow scan rate and latency you can make battery life a little longer but not so much, HHKB and the module is power hog in the end.

- Lipo Battery is not included(Bluetooth controller only)
    Lipo battery is not included. And it cannot be shipped from Japan due to regulations.
    You have to purchase battery for BT controller, see Bluetooth Battery section below for the detail.

- LIPO BATTERY IS VERY DANGEROUS(Bluetooth controller only)

- Karabiner doen't recognize Bluetooth inputs on Mac(Bluetooth controller only)
    Key strokes from Bluetooth are ignored by default. To make Karabiner recognize them enable option 'Allow devices which Vendor ID and Product ID are zero.'.
    See this issue.

USE AT YOUR OWN RISK. I can not be liable for any damage.
NO FRIENDLY CUSTOMER SUPPORT. You are required to teach yourself first.
NOT PROFESSIONAL JOB. I'm not a professional.
NOT LEAD FREE. I use leaded solder to assemble.

- how to change Bluetooth name More
The name 'TmkBT-XXXX' is stored actually in Bluetooth module RN42 and you can change 'TmkBT' part while '-XXXX' part is not configurable and it is last 4digits of bluetooth address.
You can change this line, build and upload firmware.

You can change the name by editing this line then build and upload firmware.

And you have to initialize RN42 module with LShift+RShift+ScrollLock(Fn+O). The intialization is nedeed just once after firmware is updated.  Refer to 'MANUAL of Bluetooth Controller' below.

Rev.A: 2013/06
Rev.B: 2014/03
Rev.C: 2014/08
Rev.D: 2014/10  Fix for Bluetooth
Rev.E: 2014/11  Fix for Bluetooth

NO ERRATA found for following revisions
Rev.F: 2014/12
Rev.F(batch2): 2015/01
Rev.G: 2015/03
Rev.H: 2015/07 Fix thermal releif spokes for reset/program button
Rev.I: 2015/12 Changed USB mini-B connector SMT to TH
Rev.J 2016/01 Removed C13 and added logo on silk layer

TMK firmware supports the controller and provides various features for the keyboard. You can use the features fully by building your own firmware from source codes. See following links for the detail.

Design files, source codes and the detail of the controller are available.

Old GB thread:
Cover for USB Hub hole by alienman82:
Cover for USB Hub hole and Qi charger by manisteinn:
Cover by RavenIl: reddit post

First of all, Use default firmware to test your hardware.
Note that there are four variants of controller fimware. Dowload proper firmware from Keymap Editor without editing keymap and flash it when you are in trouble.
USB for Pro1/Pro2 | Bluetooth for Pro2 | USB for ProJP | Bluetooth for ProJP

Check 'Bluetooth controller' of MANUAL section below, first.

Flash default firmware if you have problem after flashed firmware yourself.
Download firmware from Keymap Editor without editing keymap: Bluetooth for Pro2 | Bluetooth for ProJP

Controller can connect but doesn't register at all on Bluetooth while does on USB?
You are using firmware for *USB* controller(not Bluetooth) perhaps. With the wrong firmware Bluetooth controller works completely on USB while it doesn't register any keys on Bluetooth but it can still connect with computer. Use proper Bluetooth firmware for your controller, download from Keymap Editor you can find above.

How to connect
Try following steps when you are in trouble.

1. Turn on blueooth on keyboard by slide switch on controller.
2. Turn on blueooth on your computer, and remove/disconnect keyboard if it is already paired/connected.
3. Press Left Shift, Right Shift and P on keyboard to remove pairing infos. You should see red BT LED blinking at this time and it indicates that your keyboard is discoverable from computer now.
4. Add keyboard on computer. These may help:
Computer cannot find/connect bluetooth controller?
Try 'How to connect' above.

Have repeated or random key intput?
Try 'How to connect' above.
If you are using developer preview vesion of Windows or MacOS you may have weird problem on bleutooth. Some people had to update drivers, fix/remove OS configuration files or etc. Stay on stable realse or you will have to search solution yourself on the net.

Have bluetooth trouble in MacOS?
First, make sure you have correct firmware for Bluetooth controller, see entry above. Try removing '~/Library/Preferences/', '/Library/Preferences/' or both then reboot your Mac. You will have to do pairing process with all your devices again after this. This seems to be common solution for bluetooth trouble on MacOS. Refer to following links as well.

Still have problem and heed help?
Post your problem on this thread to share with the community!

MoreKeymap Editor
You can try HHKB keymap editor first. You can download pre-build firmware after editing your keymap. Some features are not available but it is easy to use.

Build firmware
If Keymap Editor is not enough it is time to edit source codes and build firmware yourself.

In short,

--- Code: ---$ cd keyboard/hhkb

--- End code ---


--- Code: ---make -f Makefile
--- End code ---
for USB controller

--- Code: ---$ make -f Makefile.rn42
--- End code ---
for Bluetooth controller

Flash Firmware
MoreYou can use dfu-programmer or Atmel FLIP to program microcontroller on the board. To get controller into bootloader(program) mode you can push red button on back or press key combo "LShift+RShift+Fn+P(Pause)" with default keymap. Microcontroller of board is Atmel ATMega32u4.

MoreThere is good instruciton video. Thank you Tech Intake!

1. Unscrew three bolts on bottom and open case carefully not to damage cables.

2. Unscrew bolt at top right on board first and then unmate connector to remove original board.
Note that you don't need any tool to unmate. See this.

3. Mate with connector of Alt board firmly and screw.
For Bluetooth: Also connect Lipo battery to board. Battery should be fixed with double sided adhesive tape or something but too strong stickyness may deform and damage battery when you remove it.

4. Close case and scew bolts.
Make sure ferrite core on cables are placed right position like pic above beore screwing, otherwise It won't close decently.

Bluetooth Controller

BT Switch
This turn on Bluetooth function of controller and switch keyboard into Bluetooth mode. When this switch is off keyboard works in USB mode.

It lights red when Bluetooth is connected to host, blinks red(once per second) when waiting for connection and blinks red(10 times per second) when Bluetooth module is config mode.

When keyboard are powered with USB it lights green if battery is fully charged or ligths red if charging. And it lights red to alarm for low battery when not powered with USB.

Charging with USB
Lipo battery can be charged when keyboard is powered with USB cable. You can power it with USB port on PC and 5V USB power adapter. Charging battery with low voltage takes long time or can't charge full. Note that cheap or unpowered USB hub may not be able to supply enough power.

You can connect keyboard with OS specific method during red BT LED is blinking. You can make up to eight pairing with different hosts, according to manual of RN42.

You cannot pair with new host during keyboard is connected to a host. To pair with new host you have to disconnect by turning off the host's Bluetooth radio, removing pairing info from the host, keeping away enough to make its radio unreachable or use magic command 'p' to remove pairing info from keyboard.

Auto Connect
Keyboard is automatically connected to host once pairing process is done. Keyboard is always connected host to which keyboard connected last time.
This means you can't connect keyboad to other hosts when the last host are in reachable range. In this case you will have to make keyboard into pairing mode forcibly using magic command 'p' and redo pairing process.

Also see this post.

Magic commands
Prefix of magic command are LShift + RShift.

- i displays Bluetooth information on hid_listen console.
- b displays battery voltage on console.
- Delete enter/exits Bluetoot module RN42 config mode on console. See RN42 manual.
- Scroll Lock initializes module with TMK default configuration.
- p put keyboard into pairing mode focibly.  Note that this removes all pairing infos.
- u switches between USB and Bluetooth mode.

RN42 initialize
This is not needed in most cases. You can initialize module as a last resort when you are in trouble and any other method doesn't help. You should follow steps below with special care to prevent the module from being cofigured incompletely or wrongly.

0. Turn BT swich off and unplug USB cable.
1. open hid_listen. You can do without it but I recommend strongly.
2. Plug USB cable and wait for keyboard to startup for 5 seconds.
3. Press key combo of LShift+RShift+ScrollLock(Fn+O).
4. Turn BT switch on. You will see output below on hid_listen.
5. Do not touch keyobard until the command completes or for 20 seconds.

Now module is configured with default setting and in pairing mode. You may need extra power cycle for pairing, try BT switch off and on.

Output on hid_listen from initialize command.

--- Quote ---Entering config mode ...
Ver 6.15 04/26/2013
(c) Roving Networks
Exiting config mode ...

--- End quote ---

RN42 config mode
You need hid_listen to access this mode. You can change configuration of Bluetooth module with this. Don't change baud rate! Never! Firmware will lose access to the modlue and you need to communicate to the module with 3.3V UART adapter hardware to fix this problem.
This may brick your Bluetooth module. Read all documents of RN42 before do this. DO NOT USE IF YOU ARE NOT SURE.

See this for configuration commands.
And for other documents.

RN42 Factory Reset
When you make a mess of the module configuration you can do Factory Reset. This resets the module factory default settings.
Quote from manual.

--- Quote ---To reset the module to the factory defaults, GPIO4 should be high on
power-up and then toggle low, high, low, high with a 1 second wait between the transitions.

--- End quote ---
You can toggle GPIO4 with two pads labeled as "F.RST" in pic below. You can turn it high(ON) by closing the pads with tweezer, paper clip, or screwdriver and low(OFF) by keeping open.

After reset you have to initialize the module to use it as Bluetooth keyboard.

Bluetooth Battery
MoreBluetooth Controller doesn't include battery. I confirmed Sparkfun Lipo battery(850mA and 1000mA) but you will be able to find proper batteries at many sites on the net.

You need to use 3.7V Lithium Ion Polymer battery with JST PH 2pin connector and battery protection circuit. Battery space inside HHKB is around 54mm x 50mm and its height is 7mm(or 8mm).

Confirmed batteries:
- Adafruit 2000mAh recommended -

- Current 2000mAh battery on doesn't fit into the cavity. (2020-02-19)
   2000mAh 60 x 50 x 5 mm (1 mm) -

- Sparkfun 850mAh -                         
- Sparkfun 1000mAh -
- Sparkfun 2000mAh - Not fits.

- Adafruit 2500mAh -
    It does not fit in the space basically.
    You need case modification
    or bending battery
    Warn: either way, do it at your own risk, of course.

- ebay 2600mAh -
    Note that you will need to rewire and crimp JST PH connector yourself.

Note that some battery connector has reverse polarity. It will fry battery charger chip. Left side should be red wire or positive(+) of battery when plugged as this pic shows.


2014/05/01 GB was closed  and moved to artisan service.
2015/08/22 components for next batch were ordered, it will take a few weeks to be delivered.
2015/09/10 waiting for PCB 7-10days
2015/10/07 All components are stocked for all variants now.
2015/11/09 Keymap editor was updated
2016/01/11 Updated keymap editor
2016/04/16 Revised price of USB controller
2016/08/31 New keymap editor: also finally available for ProJP
2016/10/01 out of stock
2016/10/07 back in stock
2017/04/28 All variants are virtually always in stock.
2017/06/06 Added note for shipping to Canada.
2018/09/08 Shipping to Canada is no problem now. Removed caveat.
2019/11/21  Type-C controller is tetatively available.
2021/03/29  Revised shipping rate
2021/04/12 Revised price of controller
2022/01/01 Bluetooth controller is available again.
2022/03/09 Revised price of controller
2022/04/12 Change ORDER instruction

Wow I feel honored to be the first one to post here...
First of all, much Congratz on your well deserved artisan thread hasu!  :)

I'm super interested in one of your boards, since Im about to pull the trigger on my first hhkb an knew I would pretty much have to get your controller once I do so...  :thumb:

Does this still work in a 'waiting list style'? (So basically boards get made once a certain number of orders is reached?)

Im still considering weather to go bluetooth or not honestly (tending towards yes), but I would very much be down for one, so if there is a waiting list I would love to be on it! =)

Thanks for your interest, FoC_Tow.

No waiting list anymore. Basically I'll make some boards if I have time and retain some extra preassembled controllers for immediate shipment.

Currently two USB controllers and one BT controller are in stock with preassembled and tested. They can be shipped in a few days.

I have also components for 10+ USB and 4 BT controllers so that those can be assembled to meet further orders. Probably lead time will be less than a week.

I just ordered my HHKB. And Hasu's board. Chose USB for now, bc I'm hoping the BT stuff will improve over time and that (maybe) I can help:)

I think with some work we can get power saving and battery good enough to last weeks. Switching hosts would be nice too. These sound like they might take a while. So I figured if I really need the BT, maybe just use an external for a while.

Fwiw since FoC_Tow was debating options.



Thanks again! The bluetooth module works flawlessly.

If anyone is interested in buying a USB only PCB please let me know! PM me or check out the post I just posted in the for sale section of Geekhack.

Thank you again Hasu!


[0] Message Index

[#] Next page

Go to full version