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 * Multi-layer Keymap  - Multiple keyboard layouts with layer switching
  11 * Mouse key           - Mouse control with keyboard
  12 * System Control Key  - Power Down, Sleep, Wake Up and USB Remote Wake up
  13 * Media Control Key   - Volume Down/Up, Mute, Next/Prev track, Play, Stop and etc
  14 * USB NKRO            - 120 keys(+ 8 modifiers) simultaneously
  15 * PS/2 mouse support  - PS/2 mouse(TrackPoint) as composite device
  16 * Keyboard protocols  - PS/2, ADB, M0110, Sun and other old keyboard protocols
  17 * User Function       - Customizable function of key with writing code
  18 * Macro               - Very primitive at this time
  19 * Keyboard Tricks     - Oneshot modifier and modifier with tapping feature
  20 * Debug Console       - Messages for debug and interaction with firmware
  21
  22
  23 Projects
  24 --------
  25 You can find some keyboard specific projects under `converter` and `keyboard` directory.
  26
  27 ### converter
  28 * [ps2_usb](converter/ps2_usb/)             - [PS/2 keyboard to USB][GH_ps2]
  29 * [adb_usb](converter/adb_usb/)             - [ADB keyboard to USB][GH_adb]
  30 * [m0110_usb](converter/m0110_usb)          - [Machintosh 128K/512K/Plus keyboard to USB][GH_m0110]
  31 * [terminal_usb](converter/terminal_usb/)   - [IBM Model M terminal keyboard(PS/2 scancode set3) to USB][GH_terminal]
  32 * [news_usb](converter/news_usb/)           - [Sony NEWS keyboard to USB][GH_news]
  33 * [x68k_usb](converter/x68k_usb/)           - [Sharp X68000 keyboard to USB][GH_x68k]
  34 * [sun_usb](converter/sun_usb/)             - [Sun] to USB(type4, 5 and 3?)
  35 * [pc98_usb](converter/pc98_usb/)           - [PC98] to USB
  36 * [usb_usb](converter/usb_usb/)             - USB to USB(experimental)
  37
  38 ### keyboard
  39 * [hhkb](keyboard/hhkb/)                    - [Happy Hacking Keyboard professional][GH_hhkb]
  40 * [macway](keyboard/macway/)                - [Compact keyboard mod][GH_macway]
  41 * [hbkb](keyboard/hbkb/)                    - [Happy Buckling sprint keyboard(IBM Model M mod)][GH_hbkb]
  42 * [IIgs_Standard](keyboard/IIgs_Standard/)  - Apple [IIGS] keyboard mod(by JeffreySung)
  43 * [hid_liber](keyboard/hid_liber/)          - [HID liberation controller][HID_liber](by alaricljs)
  44 * [phantom](keyboard/phantom/)              - [Phantom keyboard][PHANTOM] (by Tranquilite)
  45 * [gh60](keyboard/gh60/)                    - [GH60 keyboard][GH60]
  46
  47 [GH_macway]:    http://geekhack.org/showwiki.php?title=Island:11930
  48 [GH_hhkb]:      http://geekhack.org/showwiki.php?title=Island:12047
  49 [GH_ps2]:       http://geekhack.org/showwiki.php?title=Island:14618
  50 [GH_adb]:       http://geekhack.org/showwiki.php?title=Island:14290
  51 [GH_hhkb_bt]:   http://geekhack.org/showwiki.php?title=Island:20851
  52 [GH_m0110]:     http://geekhack.org/showwiki.php?title=Island:24965
  53 [GH_news]:      http://geekhack.org/showwiki.php?title=Island:25759
  54 [GH_terminal]:  http://geekhack.org/showwiki.php?title=Island:27272
  55 [GH_x68k]:      http://geekhack.org/showwiki.php?title=Island:29060
  56 [GH_hbkb]:      http://geekhack.org/showwiki.php?title=Island:29483
  57 [HID_liber]:    http://deskthority.net/wiki/HID_Liberation_Device_-_DIY_Instructions
  58 [PHANTOM]:      http://geekhack.org/index.php?topic=26742
  59 [GH60]:         http://geekhack.org/index.php?topic=34959
  60 [PC98]:         http://en.wikipedia.org/wiki/NEC_PC-9801
  61 [Sun]:          http://en.wikipedia.org/wiki/Sun-3
  62 [IIGS]:         http://en.wikipedia.org/wiki/Apple_IIGS
  63
  64
  65
  66 Build & Program
  67 ---------------
  68 ### Install Tools
  69 First, you need tools to build firmware and program your controller. I assume you are on Windows here.
  70
  71 1. Install [WinAVR][winavr]. This is old but works well for this purpose. `WinAVR` is a tool set to build firmware including C compiler(gcc) and make commands. You can use [CrossPack][crosspack] instead if you are on Mac.
  72
  73 2. Install [Atmel FLIP][flip]. `FLIP` is a tool to program(load) firmware into AVR controller(ATMega32u4) via DFU bootloader. ATMega32u4 has DFU bootloader by factory default. You can use [dfu-programmer][dfu-prog] instead if you are on Mac.
  74
  75 3. Install driver for DFU bootloader. At first time you start DFU bootloader on Chip 'Found New Hardware Wizard' will come up on Windows. If you install device driver properly you can find chip name like 'ATmega32U4' under 'LibUSB-Win32 Devices' tree on 'Device Manager'. If not you shall need to update its driver on 'Device Manager'. You will find the driver in `FLIP` install directory like: C:\Program Files (x86)\Atmel\Flip 3.4.5\usb\. If you use `dfu-programmer` install its driver.
  76
  77 If you use PJRC Teensy you don't need step 2 and 3, just get [Teensy loader][teensy-loader].
  78
  79
  80 ### Download source
  81 You can find firmware source at github: https://github.com/tmk/tmk_keyboard
  82
  83 If you are familiar with `Git` tools you are recommended to use it.
  84 If not you can download zip archive from: https://github.com/tmk/tmk_keyboard/archive/master.zip
  85
  86
  87 ### Build firmware
  88 1.  Open terminal window to get access to commands. You can use `cmd` in Windows or `Terminal.app` on Mac OSX. In Windows press `Windows` key and `R` then enter `cmd` in Run command dialog showing up.
  89
  90 2. Move to project directory in the firmware source.
  91
  92     cd tmk_keyboard/{keyboard or converter}/<project>
  93
  94 3. Build firmware using GNU `make` command. You'll see <project>_<variant>.hex file in that directory unless something unexpected occurs in build process.
  95
  96     mkae -f Makefile.<variant> clean
  97     make -f Makefile.<variant>
  98
  99
 100
 101
 102 ### Program Controller
 103 Sock AVR USB chip including ATmega32U4 has DFU bootloader by factory default, you can use DFU tools for this purpose. `FLIP` is a DFU tool on Windows offered by Atmel. Open source command line DFU tool `dfu-programmer` also supports AVR chips, which run on Linux, Mac OSX and even Windows. If you have a PJRC Teensy you should use `Teensy Loader`.
 104
 105 #### DFU bootloader
 106 To program AVR chip with DFU bootloader use `FLIP` or `dfu-programmer`.
 107 If you have a proper program command in `Makefile` just type this.
 108
 109 `FLIP` has two version of tool, GUI app and command line program. If you want GUI see tutorial section below.
 110 To use command line tool run this command. Note that you need to set PATH variable properly.
 111
 112     $ make -f Makefile.<variant> flip
 113
 114 To program with `dfu-programmer` run:
 115
 116     $ make -f Makefile.<variant> dfu
 117
 118 #### Teensy
 119 If you have PJRC Teensy see instruction of `Teensy Loader` at: <http://www.pjrc.com/teensy/loader.html>
 120 Or use this command if you have command line version of Teensy Loader installed.
 121
 122     $ make -f Makefile.<variant> teensy
 123
 124
 125 #### Other programmer
 126 You may want to use other you favorite programmer like `avrdude` with AVRISPmkII, Aruduino or USBasp. In that case you can still use make target `program` for build with configuring PROGRAM_CMD in Makefile.
 127
 128     $ make -f Makefile.<variant> program
 129
 130
 131
 132 #### FLIP GUI tutorial
 133 1. On menu bar click Device -> Select, then. `ATmega32u4`.
 134 2. On menu bar click Settings -> Communication -> USB, then click 'Open' button on 'USB Port Connection' dialog.
 135 At this point you'll see greyouted widgets on the app get colored and ready.
 136
 137 3. On menu bar click File -> Load HEX File, then select your firmware hex file on File Selector dialog.
 138 4. On 'Operations Flow' panel click 'Run' button to load the firmware binary to the chip. Note that you should keep 'Erase', 'Blank Check', 'Program' and 'Verify' check boxes selected.
 139 5. Re-plug USB cord or click 'Start Application' button to restart your controller.
 140 Done.
 141
 142 See also these instaructions if you need.
 143
 144 - <http://code.google.com/p/micropendous/wiki/LoadingFirmwareWithFLIP>
 145 - <http://www.atmel.com/Images/doc7769.pdf>
 146
 147
 148 [winavr]:       http://winavr.sourceforge.net/
 149 [crosspack]:    http://www.obdev.at/products/crosspack/index.html
 150 [flip]:         http://www.atmel.com/tools/FLIP.aspx
 151 [dfu-prog]:     http://dfu-programmer.sourceforge.net/
 152 [teensy-loader]:http://www.pjrc.com/teensy/loader.html
 153
 154
 155
 156 Makefile Options
 157 ----------------
 158 ### 1. MCU and Frequency.
 159
 160     MCU = atmega32u4       # Teensy 2.0
 161     #MCU = at90usb1286      # Teensy++ 2.0
 162     F_CPU = 16000000
 163
 164 ### 2. Features
 165 Note that ***comment out*** to disable them.
 166
 167     MOUSEKEY_ENABLE = yes       # Mouse keys
 168     PS2_MOUSE_ENABLE = yes      # PS/2 mouse(TrackPoint) support
 169     EXTRAKEY_ENABLE = yes       # Enhanced feature for Windows(Audio control and System control)
 170     NKRO_ENABLE = yes           # USB Nkey Rollover
 171
 172 ### 3. Programmer
 173 Optional. Set proper command for your controller, bootloader and programmer.
 174
 175     # for PJRC Teensy
 176     PROGRAM_CMD = teensy_loader_cli -mmcu=$(MCU) -w -v $(TARGET).hex
 177
 178     # for Atmel chip with DFU bootloader
 179     PROGRAM_CMD = dfu-programmer $(MCU) flash $(TARGET).hex
 180
 181     # avrdude with other methods
 182     PROGRAM_CMD = avrdude -p $(MCU) -c avrispmkII -P USB -U flash:w:$(TARGET).hex
 183     PROGRAM_CMD = avrdude -p $(MCU) -c usbasp -U flash:w:$(TARGET).hex
 184     PROGRAM_CMD = avrdude -p $(MCU) -c arduino -P COM1 -b 57600 -U flash:w:$(TARGET).hex
 185
 186
 187
 188 Config.h Options
 189 ----------------
 190 ### 1. USB vendor/product ID and device description
 191     #define VENDOR_ID       0xFEED
 192     #define PRODUCT_ID      0xBEEF
 193     /* device description */
 194     #define MANUFACTURER    t.m.k.
 195     #define PRODUCT         Macway mod
 196     #define DESCRIPTION     t.m.k. keyboard firmware for Macway mod
 197
 198 ### 2. Keyboard matrix configuration
 199     #define MATRIX_ROWS 8
 200     #define MATRIX_COLS 8
 201     #define MATRIX_HAS_GHOST
 202
 203 ### 3. Mouse keys
 204
 205 ### 4. PS/2 mouse
 206
 207 ### 5. COMMAND key combination
 208
 209     #define IS_COMMAND() (keyboard_report->mods == (MOD_BIT(KB_LSHIFT) | MOD_BIT(KB_RSHIFT)))
 210
 211
 212 Change your keymap
 213 ------------------
 214 [keymap.md](doc/keymap.md)
 215
 216
 217
 218
 219 Debuging
 220 --------
 221 Use PJRC's `hid_listen` to see debug messages. You can use the tool for debug even if firmware use LUFA stack.
 222
 223 You will see output from firmware like this.
 224
 225     r/c 01234567
 226     00: 00000000
 227     01: 00000000
 228     02: 00000000
 229     03: 00000000
 230     04: 00000000
 231     05: 00000000
 232     06: 00000000
 233     07: 00000000
 234
 235     ---- action_exec: start -----
 236     EVENT: 0307u(22511)
 237     Tapping: Tap release(2)
 238     ACTION: ACT_LAYER[5:2C]
 239     LAYER_PRESSED: Tap: unregister_code
 240     TAPPING_KEY=0307u(22511):2
 241     processed: 0307u(22511):2
 242
 243     Tapping: End(Timeout after releasing last tap): FFFFu(22715)
 244     TAPPING_KEY=0000u(0):0
 245
 246
 247
 248
 249 Magic Comannds
 250 --------------
 251 To see help press `Magic` + `H`.
 252
 253  `Magic` key bind may be `LShift` + `RShift` in many project, but `Power` key on ADB converter. `Magic` keybind can be vary on each project, check `config.h` in project directory.
 254
 255 Following commands can be also executed with `Magic` + key. In console mode `Magic` keybind is not needed.
 256
 257     ----- Command Help -----
 258     c:      enter console mode
 259     d:      toggle debug enable
 260     x:      toggle matrix debug
 261     k:      toggle keyboard debug
 262     m:      toggle mouse debug
 263     p:      toggle print enable
 264     v:      print device version & info
 265     t:      print timer count
 266     s:      print status
 267     0/F10:  switch to Layer0
 268     1/F1:   switch to Layer1
 269     2/F2:   switch to Layer2
 270     3/F3:   switch to Layer3
 271     4/F4:   switch to Layer4
 272     PScr:   power down/remote wake-up
 273     Caps:   Lock Keyboard(Child Proof)
 274     Paus:   jump to bootloader
 275
 276 ### Boot Magic
 277 Magic commands are executed when boot time. Press `Magic` command key then pulgin.
 278
 279 Define these macros in config.h.
 280
 281     IS_BOOTMAGIC_DEBUG
 282     IS_BOOTMAGIC_BOOTLOADER
 283
 284 ***TODO: sample impl***
 285 See `keyboard/hhkb/config.h` for sample.
 286
 287
 288
 289 Start Your Own Project
 290 -----------------------
 291
 292
 293
 294 Files & Directories
 295 -------------------
 296 ### Top
 297 * common/       - common codes
 298 * protocol/     - keyboard protocol support
 299 * keyboard/     - keyboard projects
 300 * converter/    - protocol converter projects
 301 * doc/          - documents
 302 * common.mk     - Makefile for common
 303 * protoco.mk    - Makefile for protocol
 304 * rules.mk      - Makefile for build rules
 305
 306 ### Common
 307 * action.[ch]
 308 * action_macro.[ch]
 309 * bootloader.[ch]
 310 * command.[ch]
 311 * controller_teensy.h
 312 * debug.[ch]
 313 * host.[ch]
 314 * host_driver.h
 315 * keyboard.[ch]
 316 * keycode.h
 317 * keymap.[ch]
 318 * led.h
 319 * matrix.h
 320 * mousekey.[ch]
 321 * print.[ch]
 322 * report.h
 323 * sendchar.h
 324 * sendchar_null.c
 325 * sendchar_uart.c
 326 * timer.[ch]
 327 * uart.[ch]
 328 * util.[ch]
 329
 330 ### Keyboard Protocols
 331 * lufa/     - LUFA USB stack
 332 * pjrc/     - PJRC USB stack
 333 * vusb/     - Objective Development V-USB
 334 * iwrap/    - Bluetooth HID for Bluegiga iWRAP
 335 * ps2.c     - PS/2 protocol
 336 * adb.c     - Apple Desktop Bus protocol
 337 * m0110.c   - Macintosh 128K/512K/Plus keyboard protocol
 338 * news.c    - Sony NEWS keyboard protocol
 339 * x68k.c    - Sharp X68000 keyboard protocol
 340 * serial_soft.c - Asynchronous Serial protocol implemented by software
 341
 342
 343
 344 License
 345 -------
 346 Under `GPL` 2 or later. Some protocol files are under `Modified BSD License`.
 347 LUFA, PJRC and V-USB stack have their own license respectively.