Improve documentation

4 files changed, 201 insertions, 233 deletions

diff --git a/keyboard/hhkb/README b/keyboard/hhkb/README
deleted file mode 100644
index 65f7dcab5a..0000000000
--- a/keyboard/hhkb/README
+++ /dev/null
@@ -1,151 +0,0 @@
-Alternative Controller for HHKB
-===============================
-
-Feature
--------
-- Mouse Keys
-- NKRO on USB(PJRC Tennsy only)
-- Keymap Layers
-
-
-Customize Keymap
-----------------
-see keymap.c.
-
-
-
-Build
-=====
-PJRC Teensy
------------
-0. Edit matrix.c.
-    adjust scan code to your pin configuration.(see doc/HHKB.txt for pinouts)
-1. Define macros in config_pjrc.h.(Optional)
-    VENDOR_ID, PRODUCT_ID and string descriptor.
-    IS_COMMAND
-2. Edit Makefile for MCU setting and build options.
-    MCU, F_CPU
-    MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, NKRO_ENABLE
-3. Build hex file.
-    $ make -f Makefile.pjrc
-4. Program MCU.
-    $  make -f Makefile.pjrc program
-
-
-V-USB
------
-0. Edit matrix.c and usbconfig.h.
-    adjust scan code to your pin configuration.(see doc/HHKB.txt for pinouts)
-    define macros for V-USB in usbconfig.h.
-1. Define macros in config_vusb.h.(Optional)
-    IS_COMMAND
-2. Edit Makefile.vusb for MCU setting and build options.
-    MCU, F_CPU
-    MOUSEKEY_ENABLE, EXTRAKEY_ENABLE
-3. Build hex file.
-    $ make -f Makefile.vusb
-4. Program MCU.
-    $  make -f Makefile.vusb program
-
-    Using a bootloader to program for convenience is recommended.
-    Once program this V-USB bootloader at first, you can program MCU without
-    extra programmer. You should have reset switch to start up as bootloader
-    mode in this case.
-    USBaspLoader:
-    http://www.obdev.at/products/vusb/usbasploader.html
-
-
-iWRAP
------
-0. Edit matrix.c and usbconfig.h.
-    adjust scan code to your pin configuration.(see doc/HHKB.txt for pinouts)
-    define macros for V-USB in usbconfig.h.
-1. Define macros in config_iwrap.h.(Optional)
-    IS_COMMAND
-2. Edit Makefile.iwrap for MCU setting and build options.
-    MCU, F_CPU
-    MOUSEKEY_ENABLE, EXTRAKEY_ENABLE
-3. Build hex file.
-    $ make -f Makefile.iwrap
-4. Program MCU.
-    $  make -f Makefile.iwrap program
-
-
-
-Hardware
-========
-PJRC Teensy
------------
-                        +---------------+
-                        |   Teensy++    |
-                        |               |
-                        |               |        HHKB
-                        |               |        ~~~~
-                        |          PB0-2|------->ROW(6-8)
-                        |          PB3-5|------->COL(9-11)
-                        |            PB6|------->ENABLE(12)
-                        |            PE6|<-------KEY(4)
-                        |            PE7|------->PREV(5)
-                        |               |
-                        |               |
-                        |               |
-                        +---------------+
-
-
-V-USB
------
-                +---+   +---------------+
-USB            GND  |   |   ATmega168   |
-~~~                 C3  |               |
-5V <-------+--------+---|Vcc,AVCC       |        HHKB
-           R1           |               |        ~~~~
-D- <----+--+-----R2-----|INT1      PB2-4|------->ROW(6-8)
-D+ <----|---+----R3-----|INT0      PC0-2|------->COL(9-11)
-        Z1  Z2          |            PC3|------->ENABLE(12)
-GND<----+---+-----------|GND         PB0|<-------KEY(4)
-                        |            PB1|------->PREV(5)
-                        |               |
-            GND+-C2--+--|XTAL1       RXD|------->Debug Console
-                     X1 |            TXD|<-------Debug Console
-            GND+-C3--+--|XTAL2       RST|---SW--+GND
-                        +---------------+
-R1:     1.5K Ohm
-R2,R3:  68 Ohm
-Z1,Z2:  Zener 3.6V
-C1,C2:  22pF
-C3:     0.1uF
-X1:     Crystal 20MHz(16MHz/12MHz)
-SW:     Push Switch(Optional for bootloader)
-
-
-iWRAP
------
-                        +---------------+        WT12
-              5V        |   ATmega168   | 5V/3.3V~~~~
-              +-----+---|Vcc,AVCC    PC4|---/--->iWRAP(RxD)
-USB           |     C3  |            PC5|<--/----iWRAP(TxD)
-~~~           |     +   |               | 
-5V <--BATT    +    GND  |               |        HHKB
-              R1        |               |        ~~~~
-D- <----+-----+--R2-----|INT1      PB2-4|------->ROW(6-8)
-D+ <----|---+----R3-----|INT0      PC0-2|------->COL(9-11)
-        Z1  Z2          |            PC3|------->ENABLE(12)
-GND<----+---+-----------|GND         PB0|<-------KEY(4)
-                        |            PB1|------->PREV(5)
-                        |               |
-            GND+-C2--+--|XTAL1       RXD|------->Debug Console
-                     X1 |            TXD|<-------Debug Console
-            GND+-C3--+--|XTAL2       RST|---SW--+GND
-                        +---------------+
-
-R1:     1.5K Ohm
-R2,R3:  68 Ohm
-Z1,Z2:  Zener 3.6V
-C1,C2:  22pF
-C3:     0.1uF
-X1:     Crystal 12MHz
-SW:     Push Switch(Optional)
-BATT:   Li-Po Battery, Battery Charger and Voltage Regulator(5V and 3.3V).
-
-
-EOF
diff --git a/keyboard/hhkb/README.md b/keyboard/hhkb/README.md
new file mode 100644
index 0000000000..cd3a43eb7f
--- /dev/null
+++ b/keyboard/hhkb/README.md
@@ -0,0 +1,135 @@
+Alternative Controller for HHKB Pro
+===================================
+I wanted to add some features like vi cursor and mouse keys to my [HHKB][HHKB] but its controller is not programmable and
+firmware source code is not open, of course. This means customizing this keyboard needs to replace original 
+controller with programmable one. For this purpose I used PJRC [Teensy++][Teensy] as alternative controller.
+
+[HHKB]: http://www.pfu.fujitsu.com/hhkeyboard/
+[Teensy]: http://www.pjrc.com/teensy/
+
+
+My keyboard firmware source tree is here: http://github.com/tmk/tmk_keyboard
+See directory keyboard/hhkb to build firmware for HHKB.
+
+
+##Features
+* Customizable keymap
+* More keymap layers(more Fn keys)
+* Mouse keys
+* USB NKRO
+
+###Pros
+* Without PCB trace cutting, case mod or any destructives
+* Can keep original controller intact
+* Can change all HHKB behaviour as you like
+
+###Cons
+* Void your warranty
+* Lose USB hub function in case of Pro2
+
+##DISCLAIMER
+I'm not a professional of electronics or MCU programming. This may damage your HHKB.
+And my English writing is poor, I'm not sure I can convey my notions accurately.
+
+
+
+
+
+
+##Build Firmware
+You can choose some combination of MCU and USB protocol stack.
+
+### Teensy++(AVR USB family) with [LUFA]
+0. Edit **matrix.c** to use your pin configuration. See doc/HHKB.txt for detail.
+
+1. Edit **keymap.c** to use your favoirte keymap.
+
+2. Edit **Makefile** if you want to use other `MCU` than Teensy++ 2.0.
+
+3. Build firmware binary file:
+    `$ make -f Makefile.lufa`
+
+4. Program MCU with PJRC [Teensy Loader] tool. If you install command line version of the loader just run:
+    `$  make -f Makefile.lufa teensy`
+
+[LUFA]: http://www.fourwalledcubicle.com/LUFA.php
+[Teensy Loader]: http://www.pjrc.com/teensy/loader.html
+
+
+###AVR Mega with [V-USB]
+Follow below if you want to use AVR with V-USB as .
+
+0. Edit **matrix.c** to use your pin configuration. See doc/HHKB.txt for detail.
+
+1. Edit **keymap.c** to use your favoirte keymap.
+
+2. Edit **usbconfig.h** to configure V-USB options. 
+
+3. Edit **Makefile.vusb** to define `MCU` and `F_CPU`.
+
+4. Build firmware binary file:
+    `$ make -f Makefile.vusb`
+
+5. Program MCU with AVR programmer like AVRISPmkII. If you already have [USBaspLoader] on MCU just run:
+    `$  make -f Makefile.vusb program`
+
+[V-USB]: http://www.obdev.at/products/vusb/index.html
+[USBaspLoader]: http://www.obdev.at/products/vusb/usbasploader.html
+
+
+###How to Customize Keymap
+Later...
+See **keymap.c**.
+
+
+##Hardware
+
+###Teensy++ installation
+Angled USB mini B adapter is used to install Teensy++ laterally.
+![doc/HHKB_img/teensy_install.jpg]
+
+Bread baord wires are used to connect Teensy++.
+![doc/HHKB_img/teensy_wiring.jpg]
+![doc/HHKB_img/connector_contact.jpg]
+
+
+###PJRC Teensy++ 2.0 connection
+                            +---------------+
+                            |   Teensy++    |
+                            |               |
+                            |               |        HHKB
+                            |               |        ~~~~
+                            |          PB0-2|------->ROW(6-8)
+                            |          PB3-5|------->COL(9-11)
+                            |            PB6|------->ENABLE(12)
+                            |            PE6|<-------KEY(4)
+                            |            PE7|------->PREV(5)
+                            |               |
+                            |               |
+                            |               |
+                            +---------------+
+
+
+###V-USB circuit
+                    +---+   +---------------+
+    USB            GND  |   |   ATmega168   |
+    ~~~                 C3  |               |
+    5V <-------+--------+---|Vcc,AVCC       |        HHKB
+               R1           |               |        ~~~~
+    D- <----+--+-----R2-----|INT1      PB2-4|------->ROW(6-8)
+    D+ <----|---+----R3-----|INT0      PC0-2|------->COL(9-11)
+            Z1  Z2          |            PC3|------->ENABLE(12)
+    GND<----+---+-----------|GND         PB0|<-------KEY(4)
+                            |            PB1|------->PREV(5)
+                            |               |
+                GND+-C2--+--|XTAL1       RXD|------->Debug Console
+                         X1 |            TXD|<-------Debug Console
+                GND+-C3--+--|XTAL2       RST|---SW--+GND
+                            +---------------+
+    R1:     1.5K Ohm
+    R2,R3:  68 Ohm
+    Z1,Z2:  Zener 3.6V
+    C1,C2:  22pF
+    C3:     0.1uF
+    X1:     Crystal 20MHz(16MHz/12MHz)
+    SW:     Push Switch(Optional for bootloader)
diff --git a/keyboard/hhkb/doc/HHKB.txt b/keyboard/hhkb/doc/HHKB.txt
index ace931de38..f99a074437 100644
--- a/keyboard/hhkb/doc/HHKB.txt
+++ b/keyboard/hhkb/doc/HHKB.txt
@@ -1,67 +1,16 @@
-Alternative Controller for HHKB pro
-===================================
-I want to add vi cursor 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.
+Internal of HHKB pro
+=====================
+HHKB pro has MCU and some chips on separate two PCBs.
 
-This is just a proof of concept for replacing controller of HHKB, not a complete firmware.
-
-My prototype firmware source tree is here:
-    github(http://github.com/tmk/tmk_keyboard)
-This firmware is a port of my previous project:
-    HHKB style Mod(http://geekhack.org/showwiki.php?title=Island:11930)
-PJRC:
-    Teensy++/Teensy(http://www.pjrc.com/teensy/)
-
-
-Pros:
-    * without pattern cutting, case mod  and soldering
-    * can keep original controller intact
-    * can change HHKB behaviour as you like(by C programming)
-
-Cons:
-    * void your warranty
-    * unavailability of Teensy++/Teensy(because of PS3 cracking boom?)
-
-Features:
-    * customized keymap
-    * more keymap layers
-    * mouse keys for minimum mouse operation(never comfortable for normal use)
-    * and more...(in the future)
-
-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.
-
-
-Teensy++ installation
----------------------
-Angled USB mini B adapter is used to install Teensy++ laterally.
-(teensy_install.jpg)
-
-Bread baord wires are used to connect Teensy++.
-(teensy_wiring.jpg)
-(connector_contact.jpg)
-
-
-HHKB internal
--------------
-HHKB pro has some chips on separate two PCBs.
-
-Controller PCB:
+Controller PCB
+--------------
     M38K07M4    Renesas MCU with USB function
                 http://documentation.renesas.com/eng/products/mpumcu/rej03b0192_38k0ds.pdf
 
     (HHKB_controller.jpg)
 
-Keyswitch PCB:
+Keyswitch PCB
+-------------
     HC4051      Analog Multiplexer: select a row line.
                 http://www.alldatasheet.com/datasheet-pdf/pdf/203989/KODENSHI/KK74HC4051A.html
     LS145       BCD Decoder: select a column line.
@@ -76,13 +25,16 @@ Keyswitch PCB:
     (HHKB_TP1684.jpg)
 
 
-Two PCBs are connected by 15 lines. Vcc and GND use 3 lines each, other 9 lines are for keyboard signaling.
+Connector Cable
+---------------
+Two PCBs are connected by 15 lines(13 in case of Pro2).
+Vcc and GND use 3(2) lines each, other 9 lines are for keyboard signaling.
 
     Keyswitch PCB connector                                 Teensy++ pins
     -------------------------------------------------------------------------------
-     1  Vcc(5V)                                             5V
-     2  Vcc(5V)
-     3  Vcc(5V)
+     1  Vcc(5V)   Not exist on Pro2                         5V
+     2  Vcc(5V)                                             5V
+     3  Vcc(5V)                                             5V
      4  TP1684    KEY: Low(0) when key pressed              PE6 input(with pullup)
      5  TP1684    KEY_PREV: assert previous key state???    PE7 output
      6  HC4051    A(bit0) select 8 rows(0 to 7)             PB0 output
@@ -92,9 +44,11 @@ Two PCBs are connected by 15 lines. Vcc and GND use 3 lines each, other 9 lines
     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
+    13  GND                                                 GND
+    14  GND                                                 GND
+    15  GND       Not exist on Pro2                         GND
+
+    NOTE: guessing pin5(KEY_PREV) may work for hysteresis of capacitive sensing.
 
     (HHKB_connector.jpg)
 
@@ -103,19 +57,20 @@ Keyswitch matrix
 ----------------
 60 keyswitches in 8*8 matrix. It is ghost-free and bounce-free.
 
-  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_
+      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:
+
              +-------------------------+-+-+-+-+-+-+-+     Vcc
              |bias control?            - - - - - - - -     ---
              |                  3.9K*8 R R R R R R R R      |
@@ -141,7 +96,8 @@ Matrix diagram:
                     to controller
                                     
 
-Signals charts:
+Signals 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.
@@ -157,7 +113,8 @@ Signals charts:
     (HHKB_chart2.jpg)
 
 
-Matrix scan pseudo code:
+Matrix scan pseudo code
+-----------------------
     for (row: 0-7) {
         SELECT_ROW(row);        // set HC4051(A,B,C)
 
@@ -190,10 +147,5 @@ Matrix scan pseudo code:
     }
 
 
-Keymap layers
--------------
-Followings are added layers with additional Fn keys.
-
-see keymap.c
 
 EOF
diff --git a/keyboard/hhkb/iwrap.txt b/keyboard/hhkb/iwrap.txt
new file mode 100644
index 0000000000..20a2420a0b
--- /dev/null
+++ b/keyboard/hhkb/iwrap.txt
@@ -0,0 +1,32 @@
+
+iWRAP
+-----
+                        +---------------+        WT12
+              5V        |   ATmega168   | 5V/3.3V~~~~
+              +-----+---|Vcc,AVCC    PC4|---/--->iWRAP(RxD)
+USB           |     C3  |            PC5|<--/----iWRAP(TxD)
+~~~           |     +   |               | 
+5V <--BATT    +    GND  |               |        HHKB
+              R1        |               |        ~~~~
+D- <----+-----+--R2-----|INT1      PB2-4|------->ROW(6-8)
+D+ <----|---+----R3-----|INT0      PC0-2|------->COL(9-11)
+        Z1  Z2          |            PC3|------->ENABLE(12)
+GND<----+---+-----------|GND         PB0|<-------KEY(4)
+                        |            PB1|------->PREV(5)
+                        |               |
+            GND+-C2--+--|XTAL1       RXD|------->Debug Console
+                     X1 |            TXD|<-------Debug Console
+            GND+-C3--+--|XTAL2       RST|---SW--+GND
+                        +---------------+
+
+R1:     1.5K Ohm
+R2,R3:  68 Ohm
+Z1,Z2:  Zener 3.6V
+C1,C2:  22pF
+C3:     0.1uF
+X1:     Crystal 12MHz
+SW:     Push Switch(Optional)
+BATT:   Li-Po Battery, Battery Charger and Voltage Regulator(5V and 3.3V).
+
+
+