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. For this purpose I used PJRC [Teensy++][Teensy] as alternative controller.
   6
   7 [HHKB]: http://www.pfu.fujitsu.com/hhkeyboard/
   8 [Teensy]: http://www.pjrc.com/teensy/
   9
  10
  11 My keyboard firmware source tree is here: http://github.com/tmk/tmk_keyboard
  12 See directory keyboard/hhkb to build firmware for HHKB.
  13
  14
  15 ##Features
  16 * Customizable keymap
  17 * More keymap layers(more Fn keys)
  18 * Mouse keys
  19 * USB NKRO
  20
  21 ###Pros
  22 * Without PCB trace cutting, case mod or any destructives
  23 * Can keep original controller intact
  24 * Can change all HHKB behaviour as you like
  25
  26 ###Cons
  27 * Void your warranty
  28 * Lose USB hub function in case of Pro2
  29
  30 ##DISCLAIMER
  31 I'm not a professional of electronics or MCU programming. This may damage your HHKB.
  32 And my English writing is poor, I'm not sure I can convey my notions accurately.
  33
  34
  35
  36
  37
  38
  39 ##Build Firmware
  40 You can choose some combination of MCU and USB protocol stack.
  41
  42 ### Teensy++(AVR USB family) with [LUFA]
  43 0. Edit **matrix.c** to use your pin configuration. See doc/HHKB.txt for detail.
  44
  45 1. Edit **keymap.c** to use your favoirte keymap.
  46
  47 2. Edit **Makefile** if you want to use other `MCU` than Teensy++ 2.0.
  48
  49 3. Build firmware binary file:
  50     `$ make -f Makefile.lufa`
  51
  52 4. Program MCU with PJRC [Teensy Loader] tool. If you install command line version of the loader just run:
  53     `$  make -f Makefile.lufa teensy`
  54
  55 [LUFA]: http://www.fourwalledcubicle.com/LUFA.php
  56 [Teensy Loader]: http://www.pjrc.com/teensy/loader.html
  57
  58
  59 ###AVR Mega with [V-USB]
  60 Follow below if you want to use AVR with V-USB as .
  61
  62 0. Edit **matrix.c** to use your pin configuration. See doc/HHKB.txt for detail.
  63
  64 1. Edit **keymap.c** to use your favoirte keymap.
  65
  66 2. Edit **usbconfig.h** to configure V-USB options.
  67
  68 3. Edit **Makefile.vusb** to define `MCU` and `F_CPU`.
  69
  70 4. Build firmware binary file:
  71     `$ make -f Makefile.vusb`
  72
  73 5. Program MCU with AVR programmer like AVRISPmkII. If you already have [USBaspLoader] on MCU just run:
  74     `$  make -f Makefile.vusb program`
  75
  76 [V-USB]: http://www.obdev.at/products/vusb/index.html
  77 [USBaspLoader]: http://www.obdev.at/products/vusb/usbasploader.html
  78
  79
  80 ###How to Customize Keymap
  81 Later...
  82 See **keymap.c**.
  83
  84
  85 ##Hardware
  86
  87 ###Teensy++ installation
  88 Angled USB mini B adapter is used to install Teensy++ laterally.
  89
  90 ![Image of Teensy install](hhkb/doc/HHKB_img/teensy_install.jpg)
  91
  92 Bread baord wires are used to connect Teensy++.
  93
  94 ![Image of Teensy wiring](hhkb/doc/HHKB_img/teensy_wiring.jpg)
  95
  96 ![Image of Connector](hhkb/doc/HHKB_img/connector_contact.jpg)
  97
  98
  99 ###PJRC Teensy++ 2.0 connection
 100                             +---------------+
 101                             |   Teensy++    |
 102                             |               |
 103                             |               |        HHKB
 104                             |               |        ~~~~
 105                             |          PB0-2|------->ROW(6-8)
 106                             |          PB3-5|------->COL(9-11)
 107                             |            PB6|------->ENABLE(12)
 108                             |            PE6|<-------KEY(4)
 109                             |            PE7|------->PREV(5)
 110                             |               |
 111                             |               |
 112                             |               |
 113                             +---------------+
 114
 115
 116 ###V-USB circuit
 117                     +---+   +---------------+
 118     USB            GND  |   |   ATmega168   |
 119     ~~~                 C3  |               |
 120     5V <-------+--------+---|Vcc,AVCC       |        HHKB
 121                R1           |               |        ~~~~
 122     D- <----+--+-----R2-----|INT1      PB2-4|------->ROW(6-8)
 123     D+ <----|---+----R3-----|INT0      PC0-2|------->COL(9-11)
 124             Z1  Z2          |            PC3|------->ENABLE(12)
 125     GND<----+---+-----------|GND         PB0|<-------KEY(4)
 126                             |            PB1|------->PREV(5)
 127                             |               |
 128                 GND+-C2--+--|XTAL1       RXD|------->Debug Console
 129                          X1 |            TXD|<-------Debug Console
 130                 GND+-C3--+--|XTAL2       RST|---SW--+GND
 131                             +---------------+
 132     R1:     1.5K Ohm
 133     R2,R3:  68 Ohm
 134     Z1,Z2:  Zener 3.6V
 135     C1,C2:  22pF
 136     C3:     0.1uF
 137     X1:     Crystal 20MHz(16MHz/12MHz)
 138     SW:     Push Switch(Optional for bootloader)