qmk_firmware/keyboard/hhkb/README.md

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.

This controller can work with HHKB **Professional**, **Professional** 2, **JP** and **Type-S**.

See [this thread][AltController] in geekhack.org.

[HHKB]: http://www.pfu.fujitsu.com/hhkeyboard/
[AltController]: http://geekhack.org/index.php?topic=12047.0


## Update
* Bluetooth module RN-42 is supported.(2015/01)
* V-USB and iWRAP are no longer supported now, but still it'll works with a little fix. See not_supported directory.(2015/01)


##Features
* Customizable keymap
* More keymap layers(more Fn keys)
* Mouse keys
* USB NKRO
* Bluetooth(RN-42)

See README of [tmk_keyboard] for more.

[tmk_keyboard]: http://github.com/tmk/tmk_keyboard
 
###Pros
* No risks: Everything is all reversible
* No need for PCB trace patching, case cutting or any other destructive mod
* Can keep original controller intact
* Can change all HHKB behavior as you like

###Cons
* Void your warranty
* Lose USB hub function of Pro2

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


##Documents
See [doc/HHKB.txt](doc/HHKB.txt) and files under [doc/](doc/) for internal of HHKB and this controller.


##Build Firmware & Program
See [this document](../../doc/build.md) first.

### Configuration
If your target is **HHKB JP** you need to set `HHKB_JP` build option in `Makefile` or use `Makefile.jp` instead of `Makefile`.

If you use other than **TMK Alt Controller Board** set proper `MCU`, `BOOTLOADER_SIZE` and other build options in `Makefile` and `config.h`. At least PJRC Teensy requires changing `BOOTLOADER_SIZE` to 512.

### Build 
Several version of keymap are available in advance but you are recommended to define your favorite layout yourself. Just `make` with `KEYMAP` option like:

    $ make -f Makefile.<jp|pjrc|rn42> KEYMAP=(hasu|hhkb|spacefn|<name>)

You can omit `-f` option when you use `Makefile`. `Makefile` is used for **Pro2 and Pro**, `Makefile.jp` fits for **JP** model and `Makefile.rn42` supports Bluetooth module **RN-42**. `Makefile.pjrc` uses **PJRC** as output protocol instead of **LUFA**.


### Program
First, push reset button on board to start bootloader.

This command programs the controller with [dfu-programmer] if the tool is installed and configured properly.

    $ make -f Makefile.<variant> KEYMAP=<name> dfu

Or you can also use [FLIP] command to program. Also the tool should be installed and configured properly. FLIP GUI application is also available.

    $ make -f Makefile.<variant> KEYMAP=<name> flip

Use [Teensy Loader] if your controller is Teensy/Teensy++.


##Keymap
To define your own keymap create a file in the keymaps folder named `<name>.c` and see keymap document (you can find in top README.md) and existent keymap files.


##Hardware
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 cheaper option for DIY.

###1. TMK Alt Controller Board
Design files are available at [Keyboard Controller Board for HHKB(KiCad project)](https://github.com/tmk/HHKB_controller) and see [Controller Distribution thread](http://geekhack.org/index.php?topic=56494.0) if you get an assembled one.


###2. PJRC Teensy
See [this thread](http://geekhack.org/index.php?topic=57008.0).


###3. V-USB version
See [V-USB controller for HHKB](doc/V-USB.md).


[LUFA]: http://www.fourwalledcubicle.com/LUFA.php
[PJRC]: http://www.pjrc.com/teensy/usb_keyboard.html
[dfu-programmer]: http://dfu-programmer.sourceforge.net/
[FLIP]: http://www.atmel.com/tools/FLIP.aspx
[Teensy Loader]: http://www.pjrc.com/teensy/loader.html
[V-USB]: http://www.obdev.at/products/vusb/index.html
Improve documentation 2012-11-01 05:24:21 +00:00			`Alternative Controller for HHKB Pro`
			`===================================`
Fix README.md of hhkb 2013-11-30 03:32:47 +00:00			`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.`

Fix READEM of hhkb and doc/build.md 2014-07-10 06:28:36 +00:00			`This controller can work with HHKB Professional, Professional 2, JP and Type-S.`
Fix README and doc 2013-07-11 07:23:53 +00:00
			`See [this thread][AltController] in geekhack.org.`
Improve documentation 2012-11-01 05:24:21 +00:00
			`[HHKB]: http://www.pfu.fujitsu.com/hhkeyboard/`
Fix README and doc 2013-07-11 07:23:53 +00:00			`[AltController]: http://geekhack.org/index.php?topic=12047.0`
Improve documentation 2012-11-01 05:24:21 +00:00

hhkb: Integrate RN-42 support, remove hhkb_rn42 2015-01-16 01:21:18 +00:00			`## Update`
			`* Bluetooth module RN-42 is supported.(2015/01)`
			`* V-USB and iWRAP are no longer supported now, but still it'll works with a little fix. See not_supported directory.(2015/01)`


Improve documentation 2012-11-01 05:24:21 +00:00			`##Features`
			`* Customizable keymap`
			`* More keymap layers(more Fn keys)`
			`* Mouse keys`
			`* USB NKRO`
hhkb: Integrate RN-42 support, remove hhkb_rn42 2015-01-16 01:21:18 +00:00			`* Bluetooth(RN-42)`
Improve documentation 2012-11-01 05:24:21 +00:00
Fix README and doc 2013-07-11 07:23:53 +00:00			`See README of [tmk_keyboard] for more.`

			`[tmk_keyboard]: http://github.com/tmk/tmk_keyboard`

Improve documentation 2012-11-01 05:24:21 +00:00			`###Pros`
Change README Makefile and config.h in hhkb 2013-07-28 15:53:18 +00:00			`* No risks: Everything is all reversible`
			`* No need for PCB trace patching, case cutting or any other destructive mod`
Improve documentation 2012-11-01 05:24:21 +00:00			`* Can keep original controller intact`
Spellchecking keyboard README files. 2014-01-05 03:52:19 +00:00			`* Can change all HHKB behavior as you like`
Improve documentation 2012-11-01 05:24:21 +00:00
			`###Cons`
			`* Void your warranty`
Fix README and doc 2013-07-11 07:23:53 +00:00			`* Lose USB hub function of Pro2`
Improve documentation 2012-11-01 05:24:21 +00:00
			`##DISCLAIMER`
Fix README and doc 2013-07-11 07:23:53 +00:00			`I'm not a professional of electronics nor MCU programming. This may damage your HHKB.`
Improve documentation 2012-11-01 05:24:21 +00:00			`And my English writing is poor, I'm not sure I can convey my notions accurately.`


Fix README and doc 2013-07-11 07:23:53 +00:00			`##Documents`
			`See [doc/HHKB.txt](doc/HHKB.txt) and files under [doc/](doc/) for internal of HHKB and this controller.`
Improve documentation 2012-11-01 05:24:21 +00:00

Fix README and doc 2013-07-11 07:23:53 +00:00			`##Build Firmware & Program`
Change README Makefile and config.h in hhkb 2013-07-28 15:53:18 +00:00			`See [this document](../../doc/build.md) first.`
Improve documentation 2012-11-01 05:24:21 +00:00
Change README Makefile and config.h in hhkb 2013-07-28 15:53:18 +00:00			`### Configuration`
hhkb: Add Makefile.jp for HHKB JP 2015-01-10 16:54:17 +00:00			If your target is HHKB JP you need to set `HHKB_JP` build option in `Makefile` or use `Makefile.jp` instead of `Makefile`.

			If you use other than TMK Alt Controller Board set proper `MCU`, `BOOTLOADER_SIZE` and other build options in `Makefile` and `config.h`. At least PJRC Teensy requires changing `BOOTLOADER_SIZE` to 512.
Improve documentation 2012-11-01 05:24:21 +00:00
Change README Makefile and config.h in hhkb 2013-07-28 15:53:18 +00:00			`### Build`
Fix README.md of hhkb 2013-11-30 03:32:47 +00:00			Several version of keymap are available in advance but you are recommended to define your favorite layout yourself. Just `make` with `KEYMAP` option like:
Improve documentation 2012-11-01 05:24:21 +00:00
hhkb: Integrate RN-42 support, remove hhkb_rn42 2015-01-16 01:21:18 +00:00			`$ make -f Makefile.<jp\|pjrc\|rn42> KEYMAP=(hasu\|hhkb\|spacefn\|<name>)`

			You can omit `-f` option when you use `Makefile`. `Makefile` is used for Pro2 and Pro, `Makefile.jp` fits for JP model and `Makefile.rn42` supports Bluetooth module RN-42. `Makefile.pjrc` uses PJRC as output protocol instead of LUFA.
Improve documentation 2012-11-01 05:24:21 +00:00

Change README Makefile and config.h in hhkb 2013-07-28 15:53:18 +00:00			`### Program`
			`First, push reset button on board to start bootloader.`
Improve documentation 2012-11-01 05:24:21 +00:00
Spellchecking keyboard README files. 2014-01-05 03:52:19 +00:00			`This command programs the controller with [dfu-programmer] if the tool is installed and configured properly.`
Improve documentation 2012-11-01 05:24:21 +00:00
hhkb: Integrate RN-42 support, remove hhkb_rn42 2015-01-16 01:21:18 +00:00			`$ make -f Makefile.<variant> KEYMAP=<name> dfu`
Fix image link 3 :( 2012-11-01 05:40:24 +00:00
Spellchecking keyboard README files. 2014-01-05 03:52:19 +00:00			`Or you can also use [FLIP] command to program. Also the tool should be installed and configured properly. FLIP GUI application is also available.`
Improve documentation 2012-11-01 05:24:21 +00:00
hhkb: Integrate RN-42 support, remove hhkb_rn42 2015-01-16 01:21:18 +00:00			`$ make -f Makefile.<variant> KEYMAP=<name> flip`
Fix image link 3 :( 2012-11-01 05:40:24 +00:00
Change README Makefile and config.h in hhkb 2013-07-28 15:53:18 +00:00			`Use [Teensy Loader] if your controller is Teensy/Teensy++.`
Fix image link 3 :( 2012-11-01 05:40:24 +00:00
Improve documentation 2012-11-01 05:24:21 +00:00
Fix README.md of hhkb 2013-11-30 03:32:47 +00:00			`##Keymap`
Updated several keyboard folders to use new keymap naming scheme 2016-03-30 01:53:36 +00:00			To define your own keymap create a file in the keymaps folder named `<name>.c` and see keymap document (you can find in top README.md) and existent keymap files.
Improve documentation 2012-11-01 05:24:21 +00:00

Fix README and doc 2013-07-11 07:23:53 +00:00			`##Hardware`
Spellchecking keyboard README files. 2014-01-05 03:52:19 +00:00			`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 cheaper option for DIY.`
Fix README and doc 2013-07-11 07:23:53 +00:00
			`###1. TMK Alt Controller Board`
Fix READEM of hhkb and doc/build.md 2014-07-10 06:28:36 +00:00			`Design files are available at [Keyboard Controller Board for HHKB(KiCad project)](https://github.com/tmk/HHKB_controller) and see [Controller Distribution thread](http://geekhack.org/index.php?topic=56494.0) if you get an assembled one.`


			`###2. PJRC Teensy`
			`See [this thread](http://geekhack.org/index.php?topic=57008.0).`

Improve documentation 2012-11-01 05:24:21 +00:00
Fix README.md of hhkb 2013-11-30 03:32:47 +00:00			`###3. V-USB version`
Fix READEM of hhkb and doc/build.md 2014-07-10 06:28:36 +00:00			`See [V-USB controller for HHKB](doc/V-USB.md).`
Fix README and doc 2013-07-11 07:23:53 +00:00
Change README Makefile and config.h in hhkb 2013-07-28 15:53:18 +00:00
			`[LUFA]: http://www.fourwalledcubicle.com/LUFA.php`
			`[PJRC]: http://www.pjrc.com/teensy/usb_keyboard.html`
			`[dfu-programmer]: http://dfu-programmer.sourceforge.net/`
			`[FLIP]: http://www.atmel.com/tools/FLIP.aspx`
			`[Teensy Loader]: http://www.pjrc.com/teensy/loader.html`
Fix README and doc 2013-07-11 07:23:53 +00:00			`[V-USB]: http://www.obdev.at/products/vusb/index.html`