README.md

   1 t.m.k. Keyboard Firmware Collection
   2 ====================================
   3 This is a keyboard firmware with some features for Atmel AVR controller.
   4
   5 Source code is available here: <http://github.com/tmk/tmk_keyboard>
   6
   7
   8 Features
   9 --------
  10 * Mouse key - Mouse control by keyboard
  11 * System Control Key - Power Down, Sleep, Wake Up and USB Remote Wake up
  12 * Media Control Key - Volume Down/Up, Mute, Next/Prev track, Play, Stop and etc.
  13 * USB NKRO - Can send 120 keys(+ 8 modifiers) simultaneously.
  14 * PS/2 mouse support - integrate PS/2 mouse(TrackPoint) into keyboard as composite device.
  15
  16
  17 Projects
  18 --------
  19 ### converter
  20 * [ps2_usb][c1] - [PS/2 keyboard to USB][GH_ps2]
  21 * [adb_usb][c2] - [ADB keyboard to USB][GH_adb]
  22 * [m0110_usb][c3] - [Machintosh 128K/512K/Plus keyboard to USB][GH_m0110]
  23 * [terminal_usb][c4] - [IBM Model M terminal keyboard(PS/2 scancode set3) to USB][GH_terminal]
  24 * [news_usb][c5] - [Sony NEWS keyboard to USB][GH_news]
  25 * [x68k_usb][c6] - [Sharp X68000 keyboard to USB][GH_x68k]
  26
  27 ### keyboard
  28 * [hhkb][k1] - [Happy Hacking Keyboard professional][GH_hhkb]
  29 * [macway][k2] - [Compact keyboard mod][GH_macway]
  30 * [hbkb][k3] - [Happy Buckling sprint keyboard(IBM Model M mod)][GH_hbkb]
  31
  32 [c1]:   converter/ps2_usb/
  33 [c2]:   converter/adb_usb/
  34 [c3]:   converter/m0110_usb/
  35 [c4]:   converter/terminal_usb/
  36 [c5]:   converter/news_usb/
  37 [c6]:   converter/x68k_usb/
  38 [k1]:   keyboard/hhkb
  39 [k2]:   keyboard/macway
  40 [k3]:   keyboard/hbkb
  41 [GH_macway]:    http://geekhack.org/showwiki.php?title=Island:11930
  42 [GH_hhkb]:      http://geekhack.org/showwiki.php?title=Island:12047
  43 [GH_ps2]:       http://geekhack.org/showwiki.php?title=Island:14618
  44 [GH_adb]:       http://geekhack.org/showwiki.php?title=Island:14290
  45 [GH_hhkb_bt]:   http://geekhack.org/showwiki.php?title=Island:20851
  46 [GH_m0110]:     http://geekhack.org/showwiki.php?title=Island:24965
  47 [GH_news]:      http://geekhack.org/showwiki.php?title=Island:25759
  48 [GH_terminal]:  http://geekhack.org/showwiki.php?title=Island:27272
  49 [GH_x68k]:      http://geekhack.org/showwiki.php?title=Island:29060
  50 [GH_hbkb]:      http://geekhack.org/showwiki.php?title=Island:29483
  51
  52
  53
  54 Files & Directories
  55 -------------------
  56 ### Top
  57 * [common/](common/)        - common codes
  58 * [protocol/](protocol/)    - keyboard protocol support
  59 * [keyboard/](keyboard/)    - keyboard projects
  60 * [converter/](converter/)  - protocol converter projects
  61 * [doc/](doc/)              - documents
  62
  63 ### Keyboard Protocols
  64 * [pjrc/](protocol/pjrc/)     - PJRC USB stack
  65 * [vusb/](protocol/vusb/)     - Objective Development V-USB
  66 * [iwrap/](protocol/iwrap)    - Bluetooth HID for Bluegiga iWRAP
  67 * [ps2.c](protocol/ps2.c)     - PS/2 protocol
  68 * [adb.c](protocol/adb.c)     - Apple Desktop Bus protocol
  69 * [m0110.c](protocol/m0110.c) - Macintosh 128K/512K/Plus keyboard protocol
  70 * [news.c](protocol/news.c)   - Sony NEWS keyboard protocol
  71 * [x68k.c](protocol/x68k.c)   - Sharp X68000 keyboard protocol
  72
  73
  74 Build & Program
  75 ---------------
  76 ### Build firmware
  77 To compile you need `AVR GCC`, `AVR Libc` and `GNU make`.
  78 You can use [WinAVR][winavr] on Windows and [CrossPack][crosspack] on Mac.
  79
  80     $ cd <project>
  81     $ make
  82
  83 The firmware will be compiled as a file `tmk_<project>.hex`.
  84
  85 [winavr]:       http://winavr.sourceforge.net/
  86 [crosspack]:    http://www.obdev.at/products/crosspack/index.html
  87
  88 ### Program Controller
  89 If you have proper program command in Makefile just type this.
  90
  91     $ make program
  92
  93 As for `Teensy` you can use `PJRC's loader` to program hex file. <http://www.pjrc.com/teensy/loader.html>
  94
  95
  96
  97 Build Options
  98 -------------
  99 ### `Makefile`
 100 #### 1. MCU and Frequency.
 101     MCU = atmega32u4       # Teensy 2.0
 102     #MCU = at90usb1286      # Teensy++ 2.0
 103     F_CPU = 16000000
 104
 105 #### 2. Features
 106 Note that ***comment out*** to disable them.
 107     MOUSEKEY_ENABLE = yes       # Mouse keys
 108     PS2_MOUSE_ENABLE = yes      # PS/2 mouse(TrackPoint) support
 109     EXTRAKEY_ENABLE = yes       # Enhanced feature for Windows(Audio control and System control)
 110     NKRO_ENABLE = yes           # USB Nkey Rollover
 111
 112 #### 3. Programmer
 113 Set proper command for your controller, bootloader and programmer.
 114     # for PJRC Teensy
 115     PROGRAM_CMD = teensy_loader_cli -mmcu=$(MCU) -w -v $(TARGET).hex
 116
 117     # for Atmel AT90USBKEY
 118     PROGRAM_CMD = dfu-programmer $(MCU) flash $(TARGET).hex
 119
 120     # avrdude
 121     PROGRAM_CMD = avrdude -p $(MCU) -c avrispmkII -P USB -U flash:w:$(TARGET).hex
 122     PROGRAM_CMD = avrdude -p $(MCU) -c usbasp -U flash:w:$(TARGET).hex
 123     PROGRAM_CMD = avrdude -p $(MCU) -c arduino -P COM1 -b 57600 -U flash:w:$(TARGET).hex
 124
 125 ### `config.h`
 126 #### 1. USB vendor/product ID and device description
 127     #define VENDOR_ID       0xFEED
 128     #define PRODUCT_ID      0xBEEF
 129     /* device description */
 130     #define MANUFACTURER    t.m.k.
 131     #define PRODUCT         Macway mod
 132     #define DESCRIPTION     t.m.k. keyboard firmware for Macway mod
 133
 134 #### 2. Keyboard matrix configuration
 135     #define MATRIX_ROWS 8
 136     #define MATRIX_COLS 8
 137     #define MATRIX_HAS_GHOST
 138
 139 ### 3. Mouse keys configuration
 140
 141 ### 4. PS/2 mouse configuration
 142
 143
 144 Keymap
 145 ------
 146
 147
 148 Build your own firmware
 149 -----------------------
 150
 151
 152 Debuging
 153 --------
 154 Use PJRC's `hid_listen` to see debug messages and press `<COMMAND> + H` to debug menu.
 155 See `config.h` for definition of `<COMMAND>` key combination.
 156
 157
 158 Other Keyboard Projects
 159 -----------------------
 160 ### PJRC USB Keyboard/Mouse Example
 161 - <http://www.pjrc.com/teensy/usb_keyboard.html>
 162 - <http://www.pjrc.com/teensy/usb_mouse.html>
 163
 164 ### kbupgrade
 165 - <http://github.com/rhomann/kbupgrade>
 166 - <http://geekhack.org/showwiki.php?title=Island:8406>
 167
 168 ### c64key
 169 - <http://symlink.dk/projects/c64key/>
 170
 171 ### rump
 172 - <http://mg8.org/rump/>
 173 - <http://github.com/clee/rump>
 174
 175 ### dulcimer
 176 - <http://www.schatenseite.de/dulcimer.html>
 177
 178 ### humblehacker-keyboard
 179 - <http://github.com/humblehacker>
 180 - <http://www.humblehacker.com/keyboard/>
 181 - <http://geekhack.org/showwiki.php?title=Island:6292>
 182
 183 ### ps2avr
 184 - <http://sourceforge.net/projects/ps2avr/>