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
  66 Build Options
  67 -------------
  68 <target>/Makefile:
  69 1. Set target name for your firmware.
  70      TARGET = tmk_<target>
  71 2. Choose a MCU and its frequency.
  72      MCU = atmega32u4       # Teensy 2.0
  73      #MCU = at90usb1286      # Teensy++ 2.0
  74      F_CPU = 16000000
  75 3. Choose optional modules as needed. Comment out to disable optional modules.
  76      MOUSEKEY_ENABLE = yes      # Mouse keys
  77      PS2_MOUSE_ENABLE = yes     # PS/2 mouse(TrackPoint) support
  78      USB_EXTRA_ENABLE = yes     # Enhanced feature for Windows(Audio control and System control)
  79      USB_NKRO_ENABLE = yes      # USB Nkey Rollover
  80
  81 <target>/config.h:
  82 1. USB vendor/product ID and device description
  83      #define VENDOR_ID       0xFEED
  84      #define PRODUCT_ID      0xBEEF
  85      /* device description */
  86      #define MANUFACTURER    t.m.k.
  87      #define PRODUCT         Macway mod
  88      #define DESCRIPTION     t.m.k. keyboard firmware for Macway mod
  89 2. Keyboard matrix configuration
  90      #define MATRIX_ROWS 8
  91      #define MATRIX_COLS 8
  92      #define MATRIX_HAS_GHOST
  93 3. Mouse keys configuration if needed.
  94 4. PS/2 mouse configuration if needed.
  95
  96
  97 Debuging & Rescue
  98 -----------------
  99 Use PJRC's hid_listen.exe to see debug messages.
 100 Press right Control + Shift + Alt + GUI + H to debug menu.
 101
 102 Pressing any 3 keys when connected enables debug output.
 103 Pressing any 4 keys when connected makes bootloader comes up.
 104
 105
 106 Projects related
 107 ----------------
 108 PJRC USB Keyboard/Mouse Example
 109     http://www.pjrc.com/teensy/usb_keyboard.html
 110     http://www.pjrc.com/teensy/usb_mouse.html
 111 kbupgrade
 112     http://github.com/rhomann/kbupgrade
 113     http://geekhack.org/showwiki.php?title=Island:8406
 114 c64key
 115     http://symlink.dk/projects/c64key/
 116 rump
 117     http://mg8.org/rump/
 118     http://github.com/clee/rump
 119 dulcimer
 120     http://www.schatenseite.de/dulcimer.html
 121 humblehacker-keyboard
 122     http://github.com/humblehacker
 123     http://www.humblehacker.com/keyboard/
 124     http://geekhack.org/showwiki.php?title=Island:6292
 125 ps2avr
 126     http://sourceforge.net/projects/ps2avr/
 127
 128
 129 EOF