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