README

   1 t.m.k. Keyboard Firmware
   2 ========================
   3 This is keyboard firmware for Teensy(AVR USB MCU) and V-USB board.
   4
   5 source code repository:
   6 http://github.com/tmk/tmk_keyboard
   7
   8 This firmware is used in following projects:
   9 HHKB mod:   http://geekhack.org/showwiki.php?title=Island:12047
  10 Macway mod: http://geekhack.org/showwiki.php?title=Island:11930
  11 PS2 to USB: http://geekhack.org/showwiki.php?title=Island:14618
  12 ADB to USB: http://geekhack.org/showwiki.php?title=Island:14290
  13
  14 The project is heavily based on PJRC USB Keyboard/Mouse Example and
  15 owes a debt to preceding keyboard firmware projects.
  16 http://www.pjrc.com/teensy
  17
  18
  19 Features
  20 --------
  21 Mouse key
  22     control mouse cursor from keyboard.
  23 System Control Key
  24     Power Down, Sleep, Wake Up & USB Remote Wake up
  25 Media Control Key
  26     Volume Down/Up, Mute
  27 USB NKRO
  28     send 120 keys(+ 8 modifiers) at most simultaneously.
  29 PS/2 mouse support
  30     integrate PS/2 mouse(TrackPoint) into keyboard as composite device.
  31
  32
  33 Limitations
  34 -----------
  35
  36
  37 Files & Directories
  38 -------------------
  39 Target:
  40 hhkb/                           keyboard controller for PFU HHKB pro
  41 macway/                         keyboard controller for Macway mod
  42 ps2_usb/                        PS2 to USB keyboard converter
  43 adb_usb/                        ADB to USB keyboard converter
  44
  45 USB Protocol Stack:
  46 pjrc/                           PJRC  USB stack
  47 vusb/                           V-USB USB stack
  48 ps2.[ch]                        PS/2 protocol
  49 adb.[ch]                        ADB protocol
  50
  51
  52 Build
  53 -----
  54 To compile needs AVR GCC, AVR Libc and GNU make.
  55 You can use WinAVR on Windows.  http://winavr.sourceforge.net/
  56
  57 $ cd <target>
  58 $ make
  59
  60 The firmware will be compiled as a file tmk_<target>.hex.
  61
  62
  63 Build your own firmware
  64 -----------------------
  65 Copying exsistent target(macway) is easy way.
  66 1. Copy contens of macway/ to your own target directory.
  67 2. Edit Makefile. See next section.
  68 3. Edit config.h. See next section.
  69 4. Edit matrix.c. You will need to fix followings at least.
  70      matrix_init()
  71      matrix_scan()
  72      read_col()
  73      unselect_rows()
  74      select_row()
  75 5. Edit keymap.c. NOTE: It is not final design and a bit messy.
  76    You will need to fix followings at least.
  77      KEYMAP
  78      fn_layer[]
  79      fn_keycode[]
  80      keymaps[]
  81 6. Build.
  82
  83 If you have a build error like following, comment out "--relax" option in Makefile.common.
  84     (.vectors+0x30): relocation truncated to fit: R_AVR_13_PCREL against symbol `__vector_12'
  85
  86
  87 Build Options
  88 -------------
  89 <target>/Makefile:
  90 1. Set target name for your firmware.
  91      TARGET = tmk_<target>
  92 2. Choose a MCU and its frequency.
  93      MCU = atmega32u4       # Teensy 2.0
  94      #MCU = at90usb1286      # Teensy++ 2.0
  95      F_CPU = 16000000
  96 3. Choose optional modules as needed. Comment out to disable optional modules.
  97      MOUSEKEY_ENABLE = yes      # Mouse keys
  98      PS2_MOUSE_ENABLE = yes     # PS/2 mouse(TrackPoint) support
  99      EXTRAKEY_ENABLE = yes      # Enhanced feature for Windows(Audio control and System control)
 100      NKRO_ENABLE = yes          # USB Nkey Rollover
 101
 102 <target>/config.h:
 103 1. USB vendor/product ID and device description
 104      #define VENDOR_ID       0xFEED
 105      #define PRODUCT_ID      0xBEEF
 106      /* device description */
 107      #define MANUFACTURER    t.m.k.
 108      #define PRODUCT         Macway mod
 109      #define DESCRIPTION     t.m.k. keyboard firmware for Macway mod
 110 2. Keyboard matrix configuration
 111      #define MATRIX_ROWS 8
 112      #define MATRIX_COLS 8
 113      #define MATRIX_HAS_GHOST
 114 3. Mouse keys configuration if needed.
 115 4. PS/2 mouse configuration if needed.
 116
 117
 118 Debuging & Rescue
 119 -----------------
 120 Use PJRC's hid_listen.exe to see debug messages.
 121 Press <COMMAND> + H to debug menu.
 122 (see config.h for <COMMAND> key combination.)
 123
 124 Pressing any 3 keys when connected enables debug output.
 125 Pressing any 4 keys when connected makes bootloader comes up.
 126
 127
 128 Projects related
 129 ----------------
 130 PJRC USB Keyboard/Mouse Example
 131     http://www.pjrc.com/teensy/usb_keyboard.html
 132     http://www.pjrc.com/teensy/usb_mouse.html
 133 kbupgrade
 134     http://github.com/rhomann/kbupgrade
 135     http://geekhack.org/showwiki.php?title=Island:8406
 136 c64key
 137     http://symlink.dk/projects/c64key/
 138 rump
 139     http://mg8.org/rump/
 140     http://github.com/clee/rump
 141 dulcimer
 142     http://www.schatenseite.de/dulcimer.html
 143 humblehacker-keyboard
 144     http://github.com/humblehacker
 145     http://www.humblehacker.com/keyboard/
 146     http://geekhack.org/showwiki.php?title=Island:6292
 147 ps2avr
 148     http://sourceforge.net/projects/ps2avr/
 149
 150
 151 EOF