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