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
  12
  13 ##Features
  14 * Customizable keymap
  15 * More keymap layers(more Fn keys)
  16 * Mouse keys
  17 * USB NKRO
  18
  19 See README of [tmk_keyboard] for more.
  20
  21 [tmk_keyboard]: http://github.com/tmk/tmk_keyboard
  22
  23 ###Pros
  24 * No risks: Everything is all reversible
  25 * No need for PCB trace patching, case cutting or any other destructive mod
  26 * Can keep original controller intact
  27 * Can change all HHKB behaviour as you like
  28
  29 ###Cons
  30 * Void your warranty
  31 * Lose USB hub function of Pro2
  32
  33 ##DISCLAIMER
  34 I'm not a professional of electronics nor MCU programming. This may damage your HHKB.
  35 And my English writing is poor, I'm not sure I can convey my notions accurately.
  36
  37
  38 ##Documents
  39 See [doc/HHKB.txt](doc/HHKB.txt) and files under [doc/](doc/) for internal of HHKB and this controller.
  40
  41
  42 ##Build Firmware & Program
  43 See [this document](../../doc/build.md) first.
  44
  45 ### Configuration
  46 Set `MCU`, `BOOTLOADER_SIZE` and other build options in `Makefile` and `config.h`.
  47
  48 ### Build
  49 Just run make after intall tools.
  50
  51     $ make
  52
  53 Use `Makefile.pjrc` if you want to use PJRC stack instead of LUFA.(LUFA is recommended.)
  54
  55     $ make -f Makefile.pjrc
  56
  57 Use `Makefile.vusb` for [V-USB] controller.(not supported actively any more.)
  58     $ make -f Makefile.vusb
  59
  60 ### Program
  61 First, push reset button on board to start bootloader.
  62
  63 This command programs the controller with [dfu-programmer] if the tool is intalled and configured properly.
  64
  65     $ make dfu
  66
  67 Or you can also use [FLIP] command to program. Also the tool should be intalled and configured properly. FLIP GUI app is also available.
  68
  69     $ make flip
  70
  71 Use [Teensy Loader] if your controller is Teensy/Teensy++.
  72
  73
  74 ##How to Customize
  75 See [tmk_keyboard] documents.
  76
  77
  78 ##Hardware
  79 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.
  80
  81 ###1. TMK Alt Controller Board
  82 TMK designed [Keyboard Controller Board for HHKB Pro2(KiCad project)](https://github.com/tmk/HHKB_controller).
  83 See [this post](http://geekhack.org/index.php?topic=12047.msg948923#msg948923).
  84
  85
  86 ###2. PJRC Teensy++ 2.0 connection
  87     +---------------+
  88     |   Teensy++    |
  89     |               |
  90     |               |               HHKB pro    HHKB pro2
  91     |               |               ~~~~~~~~    ~~~~~~~~~
  92     |          PB0-2|------->ROW    (6-8)       (5-7)
  93     |          PB3-5|------->COL    (9-11)      (8-10)
  94     |            PB6|------->ENABLE (12)        (11)
  95     |            PE6|<-------KEY    (4)         (3)
  96     |            PE7|------->PREV   (5)         (4)
  97     |               |
  98     |               |   5V---       (1-3)       (1-2)
  99     |               |  GND---       (13-14)     (12-13)
 100     +---------------+
 101
 102 - NOTE: PJRC [Teensy](http://www.pjrc.com/teensy/)
 103
 104 ###3. V-USB connection
 105                     +---+   +---------------+
 106     USB            GND  |   |   ATmega328p  |
 107     ~~~                 C3  |               |
 108     5V <-------+--------+---|Vcc,AVCC       |               HHKB pro    pro2
 109                R1           |               |               ~~~~~~~~    ~~~~
 110     D- <----+--+-----R2-----|INT1      PB2-4|------->ROW    (6-8)       (5-7)
 111     D+ <----|---+----R3-----|INT0      PC0-2|------->COL    (9-11)      (8-10)
 112             Z1  Z2          |            PC3|------->ENABLE (12)        (11)
 113     GND<----+---+-----------|GND         PB0|<-------KEY    (4)         (3)
 114                             |            PB1|------->PREV   (5)         (4)
 115                             |               |
 116                 GND+-C2--+--|XTAL1       RXD|------->Debug Console
 117                          X1 |            TXD|<-------Debug Console
 118                 GND+-C3--+--|XTAL2       RST|---SW--+GND
 119                             +---------------+
 120     R1:     1.5K Ohm
 121     R2,R3:  68 Ohm
 122     Z1,Z2:  Zener 3.6V
 123     C1,C2:  22pF
 124     C3:     0.1uF
 125     X1:     Crystal 12MHz
 126     SW:     Push Switch(for bootloader)
 127
 128 - NOTE: See [V-USB] documentation for more detail of hardware and the USB stack.
 129 - NOTE: [USBaspLoader] is very useful for firmware update.
 130
 131
 132 [LUFA]: http://www.fourwalledcubicle.com/LUFA.php
 133 [PJRC]: http://www.pjrc.com/teensy/usb_keyboard.html
 134 [dfu-programmer]: http://dfu-programmer.sourceforge.net/
 135 [FLIP]: http://www.atmel.com/tools/FLIP.aspx
 136 [Teensy Loader]: http://www.pjrc.com/teensy/loader.html
 137 [V-USB]: http://www.obdev.at/products/vusb/index.html
 138 [USBaspLoader]: http://www.obdev.at/products/vusb/usbasploader.html