t.m.k. Keyboard Firmware
========================
+This is keyboard firmware for Teensy(AVR USB MCU) and V-USB board.
+
+source code repository:
http://github.com/tmk/tmk_keyboard
-This is keyboard firmware for PFU HHKB style keyboard and Teensy/Teensy++ 2.0.
-OS see this as composite device which has keyboard and mouse.
+This firmware is used in following projects:
+HHKB mod: http://geekhack.org/showwiki.php?title=Island:12047
+Macway mod: http://geekhack.org/showwiki.php?title=Island:11930
+PS2 to USB: http://geekhack.org/showwiki.php?title=Island:14618
+ADB to USB: http://geekhack.org/showwiki.php?title=Island:14290
The project is heavily based on PJRC USB Keyboard/Mouse Example and
owes a debt to preceding keyboard firmware projects.
+http://www.pjrc.com/teensy
+
+Features
+--------
+Mouse key
+ control mouse cursor from keyboard.
+System Control Key
+ Power Down, Sleep, Wake Up & USB Remote Wake up
+Media Control Key
+ Volume Down/Up, Mute
+USB NKRO
+ send 120 keys(+ 8 modifiers) at most simultaneously.
+PS/2 mouse support
+ integrate PS/2 mouse(TrackPoint) into keyboard as composite device.
-Version
--------
-0.1 2010/08/23
- It works as normal keyboard.
- It is for modified Macway keyboard(TP-999KB-E).
-1.0 2010/10/02
- keyboard has mouse key now.
- keyboard with layers.(see keymap.c)
- FN_1(right cmd):
- vi style layer
- FN_2(next to right shift):
- HHKB style layer
- FN_3(left bottom):
- h j k l: mouse move
- a s d spc: mouse buttons
- m ,: mouse wheel
+Limitations
+-----------
-1.1 2010/10/08
- Matrix wiring changed for casing.
- (and my Teensy PD3 seems to be latchuped and unusable. :<)
-1.2 2010/10/13
- HHKB support
- horizontal mouse wheel support
- change keymaps
+Files & Directories
+-------------------
+Target:
+hhkb/ keyboard controller for PFU HHKB pro
+macway/ keyboard controller for Macway mod
+ps2_usb/ PS2 to USB keyboard converter
+adb_usb/ ADB to USB keyboard converter
+
+USB Protocol Stack:
+pjrc/ PJRC USB stack
+vusb/ V-USB USB stack
+ps2.[ch] PS/2 protocol
+adb.[ch] ADB protocol
Build
-----
-Compiling sources need AVR GCC, AVR Libc and GNU make.(You can use WinAVR on Windows.)
+To compile needs AVR GCC, AVR Libc and GNU make.
+You can use WinAVR on Windows. http://winavr.sourceforge.net/
-$ cd <target> (hhkb or macway)
+$ cd <target>
$ make
-
-AVR Target board
-----------------
-Teensy/Teensy++
-http://www.pjrc.com/teensy
+The firmware will be compiled as a file tmk_<target>.hex.
+
+
+Build your own firmware
+-----------------------
+Copying exsistent target(macway) is easy way.
+1. Copy contens of macway/ to your own target directory.
+2. Edit Makefile. See next section.
+3. Edit config.h. See next section.
+4. Edit matrix.c. You will need to fix followings at least.
+ matrix_init()
+ matrix_scan()
+ read_col()
+ unselect_rows()
+ select_row()
+5. Edit keymap.c. NOTE: It is not final design and a bit messy.
+ You will need to fix followings at least.
+ KEYMAP
+ fn_layer[]
+ fn_keycode[]
+ keymaps[]
+6. Build.
+
+If you have a build error like following, comment out "--relax" option in Makefile.common.
+ (.vectors+0x30): relocation truncated to fit: R_AVR_13_PCREL against symbol `__vector_12'
+
+
+Build Options
+-------------
+<target>/Makefile:
+1. Set target name for your firmware.
+ TARGET = tmk_<target>
+2. Choose a MCU and its frequency.
+ MCU = atmega32u4 # Teensy 2.0
+ #MCU = at90usb1286 # Teensy++ 2.0
+ F_CPU = 16000000
+3. Choose optional modules as needed. Comment out to disable optional modules.
+ MOUSEKEY_ENABLE = yes # Mouse keys
+ PS2_MOUSE_ENABLE = yes # PS/2 mouse(TrackPoint) support
+ USB_EXTRA_ENABLE = yes # Enhanced feature for Windows(Audio control and System control)
+ USB_NKRO_ENABLE = yes # USB Nkey Rollover
+
+<target>/config.h:
+1. USB vendor/product ID and device description
+ #define VENDOR_ID 0xFEED
+ #define PRODUCT_ID 0xBEEF
+ /* device description */
+ #define MANUFACTURER t.m.k.
+ #define PRODUCT Macway mod
+ #define DESCRIPTION t.m.k. keyboard firmware for Macway mod
+2. Keyboard matrix configuration
+ #define MATRIX_ROWS 8
+ #define MATRIX_COLS 8
+ #define MATRIX_HAS_GHOST
+3. Mouse keys configuration if needed.
+4. PS/2 mouse configuration if needed.
+
+
+Debuging & Rescue
+-----------------
+Use PJRC's hid_listen.exe to see debug messages.
+Press <COMMAND> + H to debug menu.
+(see config.h for <COMMAND> key combination.)
+
+Pressing any 3 keys when connected enables debug output.
+Pressing any 4 keys when connected makes bootloader comes up.
Projects related
http://sourceforge.net/projects/ps2avr/
-TODO & ideas
-------------
-licensing notes(GPL)
- I think GPL is not infringement of PJRC license.
-souce code cleaning
-sleep&wakeup
-debouncing logic
- will be coded when bouncing occurs.
- bouncing doesnt occur on my ALPS switch so far.
- scan rate is too slow?(to be measure)
-
-Trackpoint(PS/2)
- receive PS/2 signal from TrackPoint
- send USB HID report
-Thinkpad keyboard support
- turn keyboard to USB keyboard/mouse composite device
-mouse horizontal wheel
- http://www.microchip.com/forums/tm.aspx?high=&m=391435&mpage=1#391521
- http://www.keil.com/forum/15671/
- http://www.microsoft.com/whdc/device/input/wheel.mspx
-setting menu(configure without changing firmware)
- console for display
- keymap/layer setting
- mouse speed/acceleration
- matrix display
-PS/2 keyboard mode
- with USB to PS/2 dumb adapter(possible?)
-AT90USBKEY support
- and other AVR USB boards
-
-DONE:
-support for HHKB pro matrix signal
- exchange controller board with teensy
- 2010/10/11
-
-
EOF