Alternative Controller for HHKB

[hasu]

I wanted to add vi cursor keys and mouse keys to HHKB. Original HHKB controller is not programmable and
firmware source code is not open. So, customizing HHKB needs to replace original controller with programmable one.
I used Teensy++ as alternative controller. Though a Teensy has enough ports to drive HHKB,
Teensy++ has clean pinout and it makes programing and wiring easier.

My firmware is now mature enough for my daily job.
I'm happy to use this HHKB every day, in particular I can't live without mouse keys!

Any suggestions or ideas are welcome.


NOTE
    My HHKB is just "Professional". This means followings may not be applied to "Professional2".


DISCLAIMER
    I'm not a professional for electronics and MCU programming. This may damage your HHKB.
    And my English writing is poor, I'm not sure I can convey my notions accurately.



UPDATE
2011/05/25

• added V-USB support: (You can use a plain ATMega168(328) as a controller now.)

Features
    * customizable keymap layers
    * mouse keys
    * USB NKRO
    * audio & system controll

USB NKRO demonstration:
coming soon

Mouse keys demonstration:
[youtube]PFMwqdtmNnA[/youtube]



Resouces
firmware source code:
    github(http://github.com/tmk/tmk_keyboard)

Teensy:
    PJRC(http://www.pjrc.com/teensy/)

V-USB:
Objective Development(http://www.obdev.at/products/vusb/index.html)



Controller Installation
Teensy++ is installed on one HHKB and ATMega168 on other.
[ Attachment Invalid Or Does Not Exist ] 18574[/ATTACH] [ Attachment Invalid Or Does Not Exist ] 18575[/ATTACH] [ Attachment Invalid Or Does Not Exist ] 18572[/ATTACH]

Angled USB mini B adapter is used to install Teensy++ laterally. Bread board wires are used to connect Teensy++.




HHKB internal

HHKB pro has some chips on separate two PCBs.

Controller PCB:       M38K07M4    Renesas MCU with USB function
                http://documentation.renesas.com/eng...192_38k0ds.pdf
    (HHKB_controller.jpg)
    Keyswitch PCB:       HC4051      Analog Multiplexer: select a row line.
                http://www.alldatasheet.com/datashee...74HC4051A.html

    LS145       BCD Decoder: select a column line.
                http://www.alldatasheet.com/datashee...N74LS145D.html

    BU9831      Non-volatile electronic potentiometer: for calibration?
                http://www.alldatasheet.com/datashee...HM/BU9831.html

    TP1684      Capacitive Sensing controller: no datasheet available.
    (HHKB_keyswitch.jpg)
   

    Topre original chip?
    (HHKB_TP1684.jpg)
   



Connector:
Two PCBs are connected with 15(13) lines. Vcc and GND uses 3(2) lines each, other 9 lines are used for keyboard control signaling.

    HHKB Pro:

Code: [Select]

   Keyswitch PCB connector                                 Teensy++ pins
    -------------------------------------------------------------------------------
     1  Vcc(5V)                                             5V
     2  Vcc(5V)
     3  Vcc(5V)
     4  TP1684    KEY: Low(0) when key pressed              PE6 input(pulluped)
     5  TP1684    KEY_PREV: assert previous key state???    PE7 output
     6  HC4051    A(bit0) select 8 rows(0 to 7)             PB0 output
     7  HC4051    B(bit1)                                   PB1 output
     8  HC4051    C(bit2)                                   PB2 output
     9  LS145     A(bit0) select 8 columns(0 to 7)          PB3 output
    10  LS145     B(bit1)                                   PB4 output
    11  LS145     C(bit2)                                   PB5 output
    12  LS145     D(enable) Low(0) enable selected column   PB6 output
    13  GND
    14  GND
    15  GND                                                 GND


    HHKB Pro2:

Code: [Select]


    Keyswitch PCB connector                                 Teensy++ pins
    -------------------------------------------------------------------------------
     1  Vcc(5V)                                             5V
     2  Vcc(5V)
     3  TP1684    KEY: Low(0) when key pressed              PE6 input(pulluped)
     4  TP1684    KEY_PREV: assert previous key state???    PE7 output
     5  HC4051    A(bit0) select 8 rows(0 to 7)             PB0 output
     6  HC4051    B(bit1)                                   PB1 output
     7  HC4051    C(bit2)                                   PB2 output
     8  LS145     A(bit0) select 8 columns(0 to 7)          PB3 output
     9  LS145     B(bit1)                                   PB4 output
    10  LS145     C(bit2)                                   PB5 output
    11  LS145     D(enable) Low(0) enable selected column   PB6 output
    12  GND
    13  GND                                                 GND



    (HHKB_connector.jpg)
   



Keyswitch matrix

60 keyswitches in 8*8 matrix. It's ghost free and bounce free.

Code: [Select]

 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       _NONE_
  3|  1     Esc     Tab     Control LShift  LAlt    LMeta   Space
  4|  7     8       u       i       k       j       m       _NONE_
  5|  \     `       Delete  Return  Fn      RShift  RAlt    RMeta
  6|  9     0       o       p       ;       l       ,       _NONE_
  7|  -     +       ]       [       '       /       .       _NONE_Matrix diagram:

Code: [Select]

            +-------------------------+-+-+-+-+-+-+-+     Vcc
             |bias control?            - - - - - - - -     ---
             |                  3.9K*8 R R R R R R R R      |
    +--------^+      +--------+        - - - - - - - -      |
    | TP 1684 |      | HC4051 <0-------|-|-|-|-|-|-|-|--|R|-+
    |         |capa. |        <1-------|-|-|-|-|-|-|-|--|R|-+
    |         |sense |        <2-------|-|-|-|-|-|-|-|--|R|-+
    |         <------|        <3-------|-|-|-|-|-|-|-|--|R|-+
    |         |      |        <4-------|-|-|-|-|-|-|-|--|R|-+
    |         |      |        <5-------|-|-|-|-|-|-|-|--|R|-+
    |         |calib.|        <6-------|-|-|-|-|-|-|-|--|R|-+
    |         <-+?   |        <7-------|-|-|-|-|-|-|-|--|R|-+
    +---V-----+ |    +-^-^-^--+        0 1 2 3 4 5 6 7  33K*8
       KEY  |      A B C         +-----------------+
        |   | +-^----+ | | |         |      LS145      |
    Vcc |   | |BU9831| | | |         +-^--^--^--^------+
    --- |   | +------+ | | |           A  B  C  D   +------+
     |  |   |          | | |           |  |  |  |   |      |
    1-3 4   5          6 7 8           9 10 11 12 13-15    |
    +--------------------------------------------------+   |
    |                connector                         |  ---
    +--------------------------------------------------+  GND
                    to controllerSignals charts:       While pressing space bar, watched HHKB original controller signals by logic analyzer.
    Row and column is looping between 0-7 each for selecting a key.
    A key is scaned every about 15ms, so scan rate is 66Hz.
    (HHKB_chart1.jpg)
   

    Space bar locate at ROW:3 COL:7. Key are selected by HC4051(C,B,A) and LS145(C,B,A).
    Key state can be read on TP1684(4/KEY) while asserting low on LS145(D).
    Usage of TP1684(5) is not clear. Original controller seemed to output previous key state on this line.
    However key state can be read without using this signal.

    (HHKB_chart2.jpg)
    Matrix scan pseudo code:

Code: [Select]

   for (row: 0-7) {
        SELECT_ROW(row);        // set HC4051(A,B,C)

        for (col: 0-7) {
            SELECT_COL(col);    // set LS145(A,B,C)

            _delay_us(40);

            if (prev_key_state(row, col) {
                KEY_PREV_ON;
            }

            _delay_us(7);

            ENALBLE_COL();      // set LS145(D) to low

            _Delay_us(10);

            if (KEY == 0) {     // read TP1684(KEY)
                // key pressed
            } else {
                // not pressed
            }

            KEY_PREV_OFF;
            UNABLE_COL();       // set LS145(D) to high
            _delay_us(150);
        }
    }



Keymap layers

Followings are added layers with additional Fn keys.

Code: [Select]


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|Fn3|  '|Return  |
    |-----------------------------------------------------------|
    |Shift   |  Z|  X|  C|  V|  B|  N|  M|  ,|  .|Fn2|Shift |Fn1|
    `-----------------------------------------------------------'
          |Gui|Alt  |Space                  |Alt  |Gui|
          `-------------------------------------------'

Layer 1: HHKB mode (HHKB Fn)
    ,-----------------------------------------------------------.
    |Pow| F1| F2| F3| F4| F5| F6| F7| F8| F9|F10|F11|F12|Ins|Del|
    |-----------------------------------------------------------|
    |Caps |   |   |   |   |   |   |   |Psc|Slk|Pus|Up |   |Backs|
    |-----------------------------------------------------------|
    |Contro|VoD|VoU|Mut|   |   |  *|  /|Hom|PgU|Lef|Rig|Enter   |
    |-----------------------------------------------------------|
    |Shift   |   |   |   |   |   |  +|  -|End|PgD|Dow|Shift |xxx|
    `-----------------------------------------------------------'
         |Gui |Alt  |Space                  |Alt  |Gui|
         `--------------------------------------------'

Layer 2: Vi mode (Slash)
    ,-----------------------------------------------------------.
    |Esc| F1| F2| F3| F4| F5| F6| F7| F8| F9|F10|F11|F12|Ins|Del|
    |-----------------------------------------------------------|
    |Tab  |Hom|PgD|Up |PgU|End|Hom|PgD|PgUlEnd|   |   |   |Backs|
    |-----------------------------------------------------------|
    |Contro|   |Lef|Dow|Rig|   |Lef|Dow|Up |Rig|   |   |Return  |
    |-----------------------------------------------------------|
    |Shift   |   |   |   |   |   |Hom|PgD|PgU|End|xxx|Shift |   |
    `-----------------------------------------------------------'
          |Gui|Alt  |Space                  |Alt  |Gui|
          `-------------------------------------------'

Layer 3: Mouse mode (Semicolon)
    ,-----------------------------------------------------------.
    |Esc|   |   |   |   |   |   |   |   |   |   |   |   |   |   |
    |-----------------------------------------------------------|
    |Tab  |MwL|MwU|McU|MwD|MwL|MwR|MwD|MwU|MwR|   |   |   |Backs|
    |-----------------------------------------------------------|
    |Contro|   |McL|McD|McR|   |McL|McD|McU|McR|xxx|   |Return  |
    |-----------------------------------------------------------|
    |Shift   |Mb4|Mb5|Mb1|Mb2|Mb3|Mb2|Mb1|Mb4|Mb5|   |Shift |   |
    `-----------------------------------------------------------'
         |Gui |Alt  |Mb1                    |Alt  |Gui|
         `--------------------------------------------'

Layer 4: Matias half keyboard style (Space)
,-----------------------------------------------------------.
|  -|  0|  9|  8|  7|  6|  5|  4|  3|  2|  1|   |   |   |Esc|
|-----------------------------------------------------------|
|Backs|  P|  O|  I|  U|  Y|  T|  R|  E|  W|  Q|   |   |Tab  |
|-----------------------------------------------------------|
|Contro|  ;|  L|  K|  J|  H|  G|  F|  D|  S|  A|Con|Control |
|-----------------------------------------------------------|
|Shift   |  /|  .|  ,|  M|  N|  B|  V|  C|  X|  Z|Shift |   |
`-----------------------------------------------------------'
     |Gui |Alt  |xxxxxxxxxxxxxxxxxxxxxxx|Alt  |Gui|
     `--------------------------------------------'i
    Mc: Mouse Cursor / Mb: Mouse Button / Mw: Mouse Wheel





Goodies for HHKB

silencing
plungers with rings made from kitchen melamine foam.
[ Attachment Invalid Or Does Not Exist ] 18577[/ATTACH]

Typed 1. silencing HHKB pro 2. original HHKB pro 3. ThinkPad X201s in this video.
[youtube]Km2G8vdLXmw[/youtube]

This have effect in a way. But I have not sufficient result yet.
My goal is the quietness tolerable to use in library:)

and see this post:
http://geekhack.org/showthread.php?5...628#post246628
http://geekhack.org/showthread.php?18935-New-HHKB-The-HHKB-Pro-Type-S&p=364477&viewfull=1#post364477



case mod
USB connector on left side.
[ Attachment Invalid Or Does Not Exist ] 18571[/ATTACH] [ Attachment Invalid Or Does Not Exist ] 18573[/ATTACH] [ Attachment Invalid Or Does Not Exist ] 18576[/ATTACH]

This is the result: happy hacking on laptop!
[ Attachment Invalid Or Does Not Exist ] 18580[/ATTACH]

[Rajagra]

Wow. I would have assumed everything in the HHKB Pro would be integrated, and inaccessible to tinkerers. I'm impressed they were methodical enough to separate functional tasks into multiple chips. That is pro. Even more impressed that someone has found a way to hack into it. Good job! :thumb:

[lowpoly]

Awesome.

[didjamatic]

Oh my!!!  Fantastic mod!  That is seriously impressive.

[itlnstln]

That's money.  Great job.

-Sent from my muhf*ckin' HHKB Pro 2

[Daniel Beaver]

Excellent. I would love to have a fully-reprogrammable HHKB.

[itlnstln]

The one thing I would do is create a virtual numpad on mine.  That's the only thing I miss on the HHKB, but the size more than makes up for it.

[lowpoly]

unavailability of Teensy++/Teensy(because of PS3 cracking boom?)

Please explain.

[RickyJ]

^ Sony's PS3 finally got cracked, group that did it released USB dongles that jailbreak the PS3.  After Sony threatened legal action against any online store selling the dongles, the group released the source code.  Now anyone can do it using a Teensy, or certain other Atmel based devices.

I've been thinking of resurrecting my other Nan-Tan board that has a fried controller, using an Arduino that I have on my work bench.  Thanks for the added motivation!

[hasu]

lowpoly:
Open source PS3 jailbreak - PSGroove has been public last month. PSGroove uses AT90USB to crack PS3.
So, the demand of AT90USBs rose sharply. AT90USB boards(Teensy, USBKEY and etc)  has disappeared on the planet.

[kishy]

Makes me glad I grabbed my Teensy++ when I did.

Interesting point is, AFAIK, the Teensy-based PS3 hacks are still unusable, broken by a PS3 update during the hack's rise to popularity.

[kishy]

Yes, well, as it was explained to me...a good number of people did the update while waiting for their Teensies to arrive.

[JBert]

@the OP: you say you're no professional but you still got some logic analyser around. Which hardware/software combo is it?

[hasu]

It is a sample application for CPLD dev board which was available in Japan several years ago. It is no longer available and supported. All information is Japanese only.
http://translate.google.co.jp/translate?u=http%3A%2F%2Foptimize.ath.cx%2Fcusb%2Flogiana.html&hl=en&langpair=auto|en&tbb=1


I would like a open source logic analyzer or the Saleae Logic if I buy now.

http://dangerousprototypes.com/docs/Open_Bench_Logic_Sniffer
http://www.saleae.com/logic/

[hasu]

I added this video on article page.
This video show some keymap layers and case mod for USB receptacle.

[youtube]PFMwqdtmNnA[/youtube]

Left side USB jack is very nice when I use HHKB on ThinkPad.

[Laser Freud]

Thanks for posting, this is very helpful information. I have the HHKB pro 2 and I want to keep the USB hub intact, so instead of replacing the controller completely I'm going to program an AVR to just translate the address bits on 6-11 to the remapped keys.

[hasu]

I added USB 12KRO support and some features to my firmware.
I know 6KRO is enough for most people include me, though it's just possible and fun.
Auido control and sleep/wakeup feature is more essential for me.

12KRO:
[youtube]sDYSJ1pWf9M[/youtube]

audio control/power down & wakeup:
[youtube]tAVLhaca8xc;[/youtube]

[nanu]

Too pro.

[woody]

How did you add 12KRO support to a USB keyboard.  Are you using a custom driver or the standard Microsoft HID keyboard driver?

I'd guess more reports in the firmware. There is nothing about 6 in the USB specs, so the HID driver should handle any KRO.

[hasu]

It uses two standard HID endpoints for 12KRO and standard driver is used.
Windows sees this as two another keyboards on Device Manager.
AVR(AT90USB) has 6 endpoints, 6*6KRO should be possible.

Some source says M$ driver can recognizes 10Keys a each endpoint, and if so,
6*10KRO will be possible on Windows without custom driver.

How did you add 12KRO support to a USB keyboard.  Are you using a custom driver or the standard Microsoft HID keyboard driver?

[woody]

It uses two standard HID endpoints for 12KRO and standard driver is used.
Windows sees this as two another keyboards on Device Manager.

You have to be careful with that - if a report moves between "keyboards", it will be like releasing the key on one and pressing it on the other virtual keyboard.

BTW, why don't you just try increasing the number of reports with a single keyboard, along with a proper descriptor?

[hasu]

You have to be careful with that - if a report moves between "keyboards", it will be like releasing the key on one and pressing it on the other virtual keyboard.

BTW, why don't you just try increasing the number of reports with a single keyboard, along with a proper descriptor?

Your point-out is right. To avoid this problem, it uses some extra memory and cycles.

I am not sure that increasing over 6 keys on single report is recognized by OS keyboard driver. The keyboard which needs a custom driver is cumbersome.

[woody]

I am not sure that increasing over 6 keys on single report is recognized by OS keyboard driver. The keyboard which needs a custom driver is cumbersome.

The HID doesn't specify anything about limit, so I don't see why HID drivers should have any limit, let alone at 6. That's the whole purpose of the cumbersome HID and the descriptors after all! I can speculate that the keyboards are 6KRO because the firmware developer just copied some example descriptors, or was lazy and chose easier compatibility with the boot mode.

On the other hand, if some OS' driver is hardcoded to a limit, that'll be useful information. Can you verify that?

I'll get to it someday soon, but you have all the tools at your disposal. Be the hero to uncover the mystery. ;-)

[hasu]

The HID doesn't specify anything about limit, so I don't see why HID drivers should have any limit, let alone at 6. That's the whole purpose of the cumbersome HID and the descriptors after all! I can speculate that the keyboards are 6KRO because the firmware developer just copied some example descriptors, or was lazy and chose easier compatibility with the boot mode.

I agree.
But the problem exist  in not only keyboard firmware but also OS driver side.
I can't believe driver/kernel can understand such complex HID report descriptors, I guess it doesn't even read

Using 8bytes(6keys)+ report may cause a compatibility problem on some circumstance(which expect a 8bytes report only). This is reason why I use two reports for 12KRO.

On the other hand, if some OS' driver is hardcoded to a limit, that'll be useful information. Can you verify that?

I'll get to it someday soon, but you have all the tools at your disposal. Be the hero to uncover the mystery. ;-)

I guess the driver is hardcoded on almost OS.
If I get spare time, I'll try to verify the limit on Windows/Linux. (I have no working Mac now

I'm not familiar with Linux internal, but this seems to be hardcoded.
http://lxr.linux.no/#linux+v2.6.36/drivers/hid/usbhid/usbkbd.c#L101

Code: [Select]

101        for (i = 2; i < 8; i++) {
 102
 103                if (kbd->old[i] > 3 && memscan(kbd->new + 2, kbd->old[i], 6) == kbd->new + 8) {
 104                        if (usb_kbd_keycode[kbd->old[i]])
 105                                input_report_key(kbd->dev, usb_kbd_keycode[kbd->old[i]], 0);
 106                        else
 107                                dev_info(&urb->dev->dev,
 108                                                &quot;Unknown key (scancode %#x) released.\n&quot;, kbd->old[i]);
 109                }
 110
 111                if (kbd->new[i] > 3 && memscan(kbd->old + 2, kbd->new[i], 6) == kbd->old + 8) {
 112                        if (usb_kbd_keycode[kbd->new[i]])
 113                                input_report_key(kbd->dev, usb_kbd_keycode[kbd->new[i]], 1);
 114                        else
 115                                dev_info(&urb->dev->dev,
 116                                                &quot;Unknown key (scancode %#x) released.\n&quot;, kbd->new[i]);
 117                }
 118        }
 119
 120        input_sync(kbd->dev);
 121
 122        memcpy(kbd->old, kbd->new, 8);


[kps]

If I get spare time, I'll try to verify the limit on Windows/Linux. (I have no working Mac now

I don't know whether the Mac driver has the same limit, but it has one other notable difference: keyboard state is separate for each keyboard, so a modifier key only applies to the keyboard it is on. For example, if you have two keyboards, and press the shift key on one keyboard and the ";:" key on another, Linux & Windows will process this as ":" but OS X will treat it as ";".

[Soarer]

Thanks to the OP for the idea, this (ed: the multiple virtual keyboards bit) has now become a 'to-do' for my Teensy based PS2 to USB adapter.

I vaguely remember the problem with using larger reports being related to the bios... and that switching to larger reports once Windows boots should be possible, but isn't for some reason.

I wonder if it would work if the first virtual keyboard used 6-key reports and the second used larger reports?

It's rather academic because 12-key really is enough!

I don't know whether the Mac driver has the same limit, but it has one other notable difference: keyboard state is separate for each keyboard, so a modifier key only applies to the keyboard it is on. For example, if you have two keyboards, and press the shift key on one keyboard and the ";:" key on another, Linux & Windows will process this as ":" but OS X will treat it as ";".

In this case, the solution is simple - just send the same modifiers for all the virtual keyboards. :-)

[hasu]

Thanks for an interesting info.
Hmm. I have to try my keyboard on Mac.

I don't know whether the Mac driver has the same limit, but it has one other notable difference: keyboard state is separate for each keyboard, so a modifier key only applies to the keyboard it is on. For example, if you have two keyboards, and press the shift key on one keyboard and the ";:" key on another, Linux & Windows will process this as ":" but OS X will treat it as ";".

[kishy]

Like I've said earlier I've seen lots of people saying you can simply change a HID descriptor but I'm pretty sure the OS will not  recognize it.

If it was that easy some keyboard manufacturer would have done it by now other than Microsoft's Sidewinder X4.

If I am to understand it correctly, it isn't an OS support issue. It's the boot mode which doesn't work.

dfj knows more than I, I just spew whatever little I retain from our lengthy conversations.

[ricercar]

The HID doesn't specify anything about limit, so I don't see why HID drivers should have any limit,

Packet size. I don't have the numbers handy, but there can be only so much data in a USB packet. In the USB Keyboard HID this comes out to 6 keys and some overhead.

[kishy]

Whatever the reason is, far more than 6kro is possible using standard HID drivers. I have seen this on my own computers and I have a device that does it cable-tied to the back of my desk...

There can be low-level BIOS incompatibilities, however, which is one conceivable reason why we don't see this as the standard.