README

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