keyboard/hhkb/README.md

   1 Alternative Controller for HHKB Pro
   2 ===================================
   3 I wanted to add some features like vi cursor and mouse keys to my [HHKB][HHKB] but its controller is not programmable and
   4 firmware source code is not open, of course. This means customizing this keyboard needs to replace original
   5 controller with programmable one. This controller can work with HHKB Professional and Professional 2 model.
   6
   7 See [this thread][AltController] in geekhack.org.
   8
   9 [HHKB]: http://www.pfu.fujitsu.com/hhkeyboard/
  10 [AltController]: http://geekhack.org/index.php?topic=12047.0
  11 [Teensy]: http://www.pjrc.com/teensy/
  12
  13
  14 ##Features
  15 * Customizable keymap
  16 * More keymap layers(more Fn keys)
  17 * Mouse keys
  18 * USB NKRO
  19
  20 See README of [tmk_keyboard] for more.
  21
  22 [tmk_keyboard]: http://github.com/tmk/tmk_keyboard
  23
  24 ###Pros
  25 * No risk: Everything is all reversible
  26 * Without PCB trace cutting, case mod or any destructives
  27 * Can keep original controller intact
  28 * Can change all HHKB behaviour as you like
  29
  30 ###Cons
  31 * Void your warranty
  32 * Lose USB hub function of Pro2
  33
  34 ##DISCLAIMER
  35 I'm not a professional of electronics nor MCU programming. This may damage your HHKB.
  36 And my English writing is poor, I'm not sure I can convey my notions accurately.
  37
  38
  39 ##Documents
  40 See [doc/HHKB.txt](doc/HHKB.txt) and files under [doc/](doc/) for internal of HHKB and this controller.
  41
  42
  43 ##Build Firmware & Program
  44 You can choose some combination of hardware and USB protocol stack([LUFA], [PJRC]).
  45
  46 ### Install Tools
  47 See [this document](../../doc/build.md).
  48
  49 ### TMK Alt Controller Board
  50     $ make -f Makefile.tmk
  51
  52 This programs the controller with [dfu-programmer] if the tool is intalled and configured properly.
  53
  54     $ make -f Makefile.tmk dfu
  55
  56 Push reset button and program with [FLIP]. The tool should be intalled and configured properly.
  57
  58     $ make -f Makefile.tmk flip
  59
  60 Or you can also program with FLIP GUI.
  61
  62 [dfu-programmer]: http://dfu-programmer.sourceforge.net/
  63 [FLIP]: http://www.atmel.com/tools/FLIP.aspx
  64
  65
  66 ### PJRC Teensy++
  67 Build with [LUFA] USB stack:
  68
  69     $ make -f Makefile.lufa
  70
  71 or with [PJRC] USB stack:
  72
  73     $ make -f Makefile.pjrc
  74
  75 Push reset button and program with [Teensy Loader(command line)]. The tool should be intalled and configured properly.
  76
  77     $  make -f Makefile.lufa teensy
  78     $  make -f Makefile.pjrc teensy
  79
  80 Or you can also program with [Teensy Loader(GUI)].
  81
  82 [LUFA]: http://www.fourwalledcubicle.com/LUFA.php
  83 [PJRC]: http://www.pjrc.com/teensy/usb_keyboard.html
  84 [Teensy Loader(command line)]: http://www.pjrc.com/teensy/loader_cli.html
  85 [Teensy Loader(GUI)]: http://www.pjrc.com/teensy/loader.html
  86
  87
  88 ###AVR Mega with [V-USB]
  89 Build:
  90     $ make -f Makefile.vusb
  91
  92 Program [USBaspLoader] on MCU with AVR programmer like [AVRISPmkII] and tool like [avrdude].
  93
  94 You can programs with [avrdude] once you have programmed [USBaspLoader] on MCU.
  95     $  make -f Makefile.vusb program
  96
  97 [AVRISPmkII]: http://www.atmel.com/tools/AVRISPMKII.aspx
  98 [avrdude]: http://www.nongnu.org/avrdude/
  99
 100
 101 ##How to Customize
 102 See [tmk_keyboard] documents.
 103
 104
 105 ##Hardware
 106 You have some options for hardware. Development boards with USB AVR family(ATMega32U4, AT90USB1286) like Teensy will work while MegaAVR with V-USB library is also cheapear option for DIY.
 107
 108 ###1. TMK Alt Controller Board
 109 TMK designed [Keyboard Controller Board for HHKB Pro2(KiCad project)](https://github.com/tmk/HHKB_controller).
 110 See [this post](http://geekhack.org/index.php?topic=12047.msg948923#msg948923).
 111
 112
 113 ###2. PJRC Teensy++ 2.0 connection
 114     +---------------+
 115     |   Teensy++    |
 116     |               |
 117     |               |               HHKB pro    HHKB pro2
 118     |               |               ~~~~~~~~    ~~~~~~~~~
 119     |          PB0-2|------->ROW    (6-8)       (5-7)
 120     |          PB3-5|------->COL    (9-11)      (8-10)
 121     |            PB6|------->ENABLE (12)        (11)
 122     |            PE6|<-------KEY    (4)         (3)
 123     |            PE7|------->PREV   (5)         (4)
 124     |               |
 125     |               |   5V---       (1-3)       (1-2)
 126     |               |  GND---       (13-14)     (12-13)
 127     +---------------+
 128
 129 - NOTE: PJRC [Teensy](http://www.pjrc.com/teensy/)
 130 [Teensy Loader]: http://www.pjrc.com/teensy/loader.html
 131
 132 ###3. V-USB connection
 133                     +---+   +---------------+
 134     USB            GND  |   |   ATmega328p  |
 135     ~~~                 C3  |               |
 136     5V <-------+--------+---|Vcc,AVCC       |               HHKB pro    pro2
 137                R1           |               |               ~~~~~~~~    ~~~~
 138     D- <----+--+-----R2-----|INT1      PB2-4|------->ROW    (6-8)       (5-7)
 139     D+ <----|---+----R3-----|INT0      PC0-2|------->COL    (9-11)      (8-10)
 140             Z1  Z2          |            PC3|------->ENABLE (12)        (11)
 141     GND<----+---+-----------|GND         PB0|<-------KEY    (4)         (3)
 142                             |            PB1|------->PREV   (5)         (4)
 143                             |               |
 144                 GND+-C2--+--|XTAL1       RXD|------->Debug Console
 145                          X1 |            TXD|<-------Debug Console
 146                 GND+-C3--+--|XTAL2       RST|---SW--+GND
 147                             +---------------+
 148     R1:     1.5K Ohm
 149     R2,R3:  68 Ohm
 150     Z1,Z2:  Zener 3.6V
 151     C1,C2:  22pF
 152     C3:     0.1uF
 153     X1:     Crystal 12MHz
 154     SW:     Push Switch(for bootloader)
 155
 156 - NOTE: See [V-USB] documentation for more detail of hardware and the USB stack.
 157 - NOTE: [USBaspLoader] is very useful for firmware update.
 158
 159 [V-USB]: http://www.obdev.at/products/vusb/index.html
 160 [USBaspLoader]: http://www.obdev.at/products/vusb/usbasploader.html