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 ### converter
  26 * ps2_usb       - [PS/2 keyboard to USB][GH_ps2]
  27 * adb_usb       - [ADB keyboard to USB][GH_adb]
  28 * m0110_usb     - [Machintosh 128K/512K/Plus keyboard to USB][GH_m0110]
  29 * terminal_usb  - [IBM Model M terminal keyboard(PS/2 scancode set3) to USB][GH_terminal]
  30 * news_usb      - [Sony NEWS keyboard to USB][GH_news]
  31 * x68k_usb      - [Sharp X68000 keyboard to USB][GH_x68k]
  32 * sun_usb       - Sun to USB(type4, 5 and 3?)
  33 * usb_usb       - USB to USB(experimental)
  34
  35 ### keyboard
  36 * hhkb          - [Happy Hacking Keyboard professional][GH_hhkb]
  37 * macway        - [Compact keyboard mod][GH_macway]
  38 * hbkb          - [Happy Buckling sprint keyboard(IBM Model M mod)][GH_hbkb]
  39 * IIgs_Standard - Apple IIGS keyboard mod(by JeffreySung)
  40 * hid_liber     - [HID liberation controller][HID_liber](by alaricljs)
  41 * phantom       - [Phantom keyboard][PHANTOM] (by Tranquilite)
  42 * gh60          - [GH60 keyboard][GH60]
  43
  44 [GH_macway]:    http://geekhack.org/showwiki.php?title=Island:11930
  45 [GH_hhkb]:      http://geekhack.org/showwiki.php?title=Island:12047
  46 [GH_ps2]:       http://geekhack.org/showwiki.php?title=Island:14618
  47 [GH_adb]:       http://geekhack.org/showwiki.php?title=Island:14290
  48 [GH_hhkb_bt]:   http://geekhack.org/showwiki.php?title=Island:20851
  49 [GH_m0110]:     http://geekhack.org/showwiki.php?title=Island:24965
  50 [GH_news]:      http://geekhack.org/showwiki.php?title=Island:25759
  51 [GH_terminal]:  http://geekhack.org/showwiki.php?title=Island:27272
  52 [GH_x68k]:      http://geekhack.org/showwiki.php?title=Island:29060
  53 [GH_hbkb]:      http://geekhack.org/showwiki.php?title=Island:29483
  54 [HID_liber]:    http://deskthority.net/wiki/HID_Liberation_Device_-_DIY_Instructions
  55 [PHANTOM]:      http://geekhack.org/index.php?topic=26742
  56 [GH60]:         http://geekhack.org/index.php?topic=34959
  57
  58
  59
  60 Build & Program
  61 ---------------
  62 ### Install Tools
  63 First, you need tools to build firmware and program your controller. I assume you are on Windows here.
  64
  65 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.
  66
  67 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.
  68
  69 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.
  70
  71 If you use PJRC Teensy you don't need step 2 and 3, just get [Teensy loader][teensy-loader].
  72
  73
  74 ### Download source
  75 You can find firmware source at github: https://github.com/tmk/tmk_keyboard
  76
  77 If you are familiar with `Git` tools you are recommended to use it.
  78 If not you can download zip archive from: https://github.com/tmk/tmk_keyboard/archive/master.zip
  79
  80
  81 ### Build firmware
  82 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.
  83
  84 2. Move to project directory in the firmware source.
  85
  86     cd tmk_keyboard/{keyboard or converter}/<project>
  87
  88 3. Build firmware using GNU `make` command. You'll see <project>_<variant>.hex file in that directory unless something unexpected occurs in build process.
  89
  90     mkae -f Makefile.<variant> clean
  91     make -f Makefile.<variant>
  92
  93
  94
  95
  96 ### Program Controller
  97 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`.
  98
  99 #### DFU bootloader
 100 To program AVR chip with DFU bootloader use `FLIP` or `dfu-programmer`.
 101 If you have a proper program command in `Makefile` just type this.
 102
 103 `FLIP` has two version of tool, GUI app and command line program. If you want GUI see tutorial section below.
 104 To use command line tool run this command. Note that you need to set PATH variable properly.
 105
 106     $ make -f Makefile.<variant> flip
 107
 108 To program with `dfu-programmer` run:
 109
 110     $ make -f Makefile.<variant> dfu
 111
 112 #### Teensy
 113 If you have PJRC Teensy see instruction of `Teensy Loader` at: <http://www.pjrc.com/teensy/loader.html>
 114 Or use this command if you have command line version of Teensy Loader installed.
 115
 116     $ make -f Makefile.<variant> teensy
 117
 118
 119 #### Other programmer
 120 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.
 121
 122     $ make -f Makefile.<variant> program
 123
 124
 125
 126 #### FLIP GUI tutorial
 127 1. On menu bar click Device -> Select, then. `ATmega32u4`.
 128 2. On menu bar click Settings -> Communication -> USB, then click 'Open' button on 'USB Port Connection' dialog.
 129 At this point you'll see greyouted widgets on the app get colored and ready.
 130
 131 3. On menu bar click File -> Load HEX File, then select your firmware hex file on File Selector dialog.
 132 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.
 133 5. Re-plug USB cord or click 'Start Application' button to restart your controller.
 134 Done.
 135
 136 See also these instaructions if you need.
 137
 138 - <http://code.google.com/p/micropendous/wiki/LoadingFirmwareWithFLIP>
 139 - <http://www.atmel.com/Images/doc7769.pdf>
 140
 141
 142 [winavr]:       http://winavr.sourceforge.net/
 143 [crosspack]:    http://www.obdev.at/products/crosspack/index.html
 144 [flip]:         http://www.atmel.com/tools/FLIP.aspx
 145 [dfu-prog]:     http://dfu-programmer.sourceforge.net/
 146 [teensy-loader]:http://www.pjrc.com/teensy/loader.html
 147
 148
 149
 150 Makefile Options
 151 ----------------
 152 ### 1. MCU and Frequency.
 153
 154     MCU = atmega32u4       # Teensy 2.0
 155     #MCU = at90usb1286      # Teensy++ 2.0
 156     F_CPU = 16000000
 157
 158 ### 2. Features
 159 Note that ***comment out*** to disable them.
 160
 161     MOUSEKEY_ENABLE = yes       # Mouse keys
 162     PS2_MOUSE_ENABLE = yes      # PS/2 mouse(TrackPoint) support
 163     EXTRAKEY_ENABLE = yes       # Enhanced feature for Windows(Audio control and System control)
 164     NKRO_ENABLE = yes           # USB Nkey Rollover
 165
 166 ### 3. Programmer
 167 Optional. Set proper command for your controller, bootloader and programmer.
 168
 169     # for PJRC Teensy
 170     PROGRAM_CMD = teensy_loader_cli -mmcu=$(MCU) -w -v $(TARGET).hex
 171
 172     # for Atmel chip with DFU bootloader
 173     PROGRAM_CMD = dfu-programmer $(MCU) flash $(TARGET).hex
 174
 175     # avrdude with other methods
 176     PROGRAM_CMD = avrdude -p $(MCU) -c avrispmkII -P USB -U flash:w:$(TARGET).hex
 177     PROGRAM_CMD = avrdude -p $(MCU) -c usbasp -U flash:w:$(TARGET).hex
 178     PROGRAM_CMD = avrdude -p $(MCU) -c arduino -P COM1 -b 57600 -U flash:w:$(TARGET).hex
 179
 180
 181
 182 Config.h Options
 183 ----------------
 184 ### 1. USB vendor/product ID and device description
 185     #define VENDOR_ID       0xFEED
 186     #define PRODUCT_ID      0xBEEF
 187     /* device description */
 188     #define MANUFACTURER    t.m.k.
 189     #define PRODUCT         Macway mod
 190     #define DESCRIPTION     t.m.k. keyboard firmware for Macway mod
 191
 192 ### 2. Keyboard matrix configuration
 193     #define MATRIX_ROWS 8
 194     #define MATRIX_COLS 8
 195     #define MATRIX_HAS_GHOST
 196
 197 ### 3. Mouse keys
 198
 199 ### 4. PS/2 mouse
 200
 201 ### 5. COMMAND key combination
 202
 203     #define IS_COMMAND() (keyboard_report->mods == (MOD_BIT(KB_LSHIFT) | MOD_BIT(KB_RSHIFT)))
 204
 205
 206 Keymap
 207 ------
 208 Many of existent projects offer keymap framework to define your own keymap easily. The following will explain how you can define keymap using this framework.
 209  Instead, you can also implement your own `keymap_get_action()` to return action code for each key if you want.
 210
 211 This is keymap example for [HHKB](http://en.wikipedia.org/wiki/Happy_Hacking_Keyboard) keyboard. Keyamp is defined in `keymaps[]` array.
 212
 213     static const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 214         /* Layer 0: Default Layer
 215          * ,-----------------------------------------------------------.
 216          * |Esc|  1|  2|  3|  4|  5|  6|  7|  8|  9|  0|  -|  =|  \|  `|
 217          * |-----------------------------------------------------------|
 218          * |Tab  |  Q|  W|  E|  R|  T|  Y|  U|  I|  O|  P|  [|  ]|Backs|
 219          * |-----------------------------------------------------------|
 220          * |Contro|  A|  S|  D|  F|  G|  H|  J|  K|  L|  ;|  '|Enter   |
 221          * |-----------------------------------------------------------|
 222          * |Shift   |  Z|  X|  C|  V|  B|  N|  M|  ,|  .|  /|Shift |Fn1|
 223          * `-----------------------------------------------------------'
 224          *       |Gui|Alt  |Space                  |Alt  |Fn2|
 225          *       `-------------------------------------------'
 226          */
 227         KEYMAP(ESC, 1,   2,   3,   4,   5,   6,   7,   8,   9,   0,   MINS,EQL, BSLS,GRV, \
 228                TAB, Q,   W,   E,   R,   T,   Y,   U,   I,   O,   P,   LBRC,RBRC,BSPC, \
 229                LCTL,A,   S,   D,   F,   G,   H,   J,   K,   L,   FN2, QUOT,ENT, \
 230                LSFT,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,RSFT,FN1, \
 231                     LGUI,LALT,          SPC,                RALT,FN3),
 232
 233         /* Layer 1: HHKB mode (HHKB Fn)
 234          * ,-----------------------------------------------------------.
 235          * |Pwr| F1| F2| F3| F4| F5| F6| F7| F8| F9|F10|F11|F12|Ins|Del|
 236          * |-----------------------------------------------------------|
 237          * |Caps |   |   |   |   |   |   |   |Psc|Slk|Pus|Up |   |Backs|
 238          * |-----------------------------------------------------------|
 239          * |Contro|VoD|VoU|Mut|   |   |  *|  /|Hom|PgU|Lef|Rig|Enter   |
 240          * |-----------------------------------------------------------|
 241          * |Shift   |   |   |   |   |   |  +|  -|End|PgD|Dow|Shift |Fn1|
 242          * `-----------------------------------------------------------'
 243          *      |Gui |Alt  |Space                  |Alt  |Gui|
 244          *      `--------------------------------------------'
 245          */
 246         KEYMAP(PWR, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, INS, DEL, \
 247                CAPS,NO,  NO,  NO,  NO,  NO,  NO,  NO,  PSCR,SLCK,PAUS,UP,  NO,  BSPC, \
 248                LCTL,VOLD,VOLU,MUTE,NO,  NO,  PAST,PSLS,HOME,PGUP,LEFT,RGHT,ENT, \
 249                LSFT,NO,  NO,  NO,  NO,  NO,  PPLS,PMNS,END, PGDN,DOWN,RSFT,FN0, \
 250                     LGUI,LALT,          SPC,                RALT,RGUI),
 251         /* Layer 2: Mouse mode (Semicolon)
 252          * ,-----------------------------------------------------------.
 253          * |Esc| F1| F2| F3| F4| F5| F6| F7| F8| F9|F10|F11|F12|Ins|Del|
 254          * |-----------------------------------------------------------|
 255          * |Tab  |   |   |   |   |   |MwL|MwD|MwU|MwR|   |   |   |Backs|
 256          * |-----------------------------------------------------------|
 257          * |Contro|   |   |   |   |   |McL|McD|McU|McR|Fn0|   |Return  |
 258          * |-----------------------------------------------------------|
 259          * |Shift   |   |   |   |   |Mb3|Mb2|Mb1|Mb4|Mb5|   |Shift |   |
 260          * `-----------------------------------------------------------'
 261          *      |Gui |Alt  |Mb1                    |Alt  |Fn0|
 262          *      `--------------------------------------------'
 263          * Mc: Mouse Cursor / Mb: Mouse Button / Mw: Mouse Wheel
 264          */
 265         KEYMAP(ESC, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, INS, DEL, \
 266                TAB, NO,  NO,  NO,  NO,  NO,  WH_L,WH_D,WH_U,WH_R,NO,  NO,  NO,  BSPC, \
 267                LCTL,NO,  ACL0,ACL1,ACL2,NO,  MS_L,MS_D,MS_U,MS_R,FN0, QUOT,ENT, \
 268                LSFT,NO,  NO,  NO,  NO,  BTN3,BTN2,BTN1,BTN4,BTN5,SLSH,RSFT,NO, \
 269                     LGUI,LALT,          BTN1,               RALT,FN0),
 270     };
 271
 272     static const uint16_t PROGMEM fn_actions[] = {
 273         ACTION_LAYER_DEFAULT,                           // FN0
 274         ACTION_LAYER_SET(1),                            // FN1
 275         ACTION_LAYER_SET_TAP_KEY(2, KC_SCLN),           // FN2
 276         ACTION_LAYER_BIT_TOGGLE(2),                     // FN3
 277     };
 278
 279
 280
 281 ### 1. Keycode
 282 See `common/keycode.h`. Keycode is 8bit internal code to inidicate action performed on key in keymap. Keycode has `KC_` prefixed symbol respectively. Most of keycodes like 'KC_A' have simple action register key on press and unregister on release, on the other some of keycodes has some special actions like Fn keys, Media contorl keys, System control keys and Mouse keys.
 283
 284  ***In `KEYMAP` definition you need to omit prefix part `KC_` of keycode to keep keymap compact.*** For example, just use `A` instead you place `KC_A` in `KEYMAP`. Some keycodes has 4-letter short name in addition to descriptive name, you'll prefer short one in `KEYMAP`.
 285
 286  **`KC_NO`** indicates the key has no keycode to transmit.
 287
 288  **`KC_LGUI`** and **`KC_RGUI`** are windows key or command key in Mac.
 289
 290  **`KC_FNnn`** are `Fn` keys which not given any action at the beginning unlike most of keycodes has its own action. To use these keys in `KEYMAP` you need to assign action you want at first. Action of `Fn` is defined in `fn_actions[]` and index of the array is identical with number part of `KC_FNnn`. Thus `KC_FN0` designates action defined in first element of the array. ***32 `Fn` keys can be defined at most.***
 291
 292  See keycode table or `keycode.h` for other keycodes.
 293  ***TODO: Keycode table link here.***
 294
 295  In regard to implementation side most of keycodes are identical with [HID usage] sent to host for real and some virtual keycodes are defined to support special actions.
 296 [HID usage]: http://www.usb.org/developers/devclass_docs/Hut1_11.pdf
 297
 298
 299
 300 ### 2. Action
 301 See `common/action.h`. Action is a 16bit code and defines function to perform on events of a key like press, release, hold and tap. You can define various actions to use various action codes.
 302
 303 Most of keys just register 8bit keycode as HID usage(or scan code) to host, but to support other complex functions needs 16bit extended action codes internally. But using 16bit action codes with keymap results in double size in memory against keycodes. To avoid this waste 8bit keycodes are used in `KEYMAP` to define instead of action codes. ***Keycodes can be considered as subset of action codes.*** Like `KC_A`(0x04) is equal to a `Key` action(0x0004) that transmit keycode of `A`.
 304
 305 #### 2.1 Key action
 306 Key is simple action that registers keycode on press of key and unregister on release.
 307 You can define `Key` action on `A` with:
 308
 309     ACTION_KEY(KC_A)
 310
 311 But you won't need to use this expression directly because you can just put symbol like `A` in `KEYMAP`.
 312
 313  Say you want to assign a key to `Shift + 1` to get *!* or `Alt + Tab` to switch windows.
 314
 315     ACTION_MOD_KEY(KC_LSHIFT, KC_1)
 316     ACTION_MOD_KEY(KC_LALT, KC_TAB)
 317
 318 `Alt,Shift + Tab`
 319     ACTION_MODS_KEY((MOD_BIT(KC_LALT) | MOD_BIT(KC_LSHIFT)), KC_TAB)
 320
 321 These actions are comprised of strokes of modifiers and a key. `Macro` action is needed if you want more complex key strokes.
 322
 323 #### 2.2 Layer Actions
 324 This sets `default layer` into `current layer`. With this action you can return to `default layer`.
 325
 326     ACTION_LAYER_DEFAULT
 327
 328 `Layer Set` action sets given layer argument to `current layer`. `Layer Set` action can take 0 to 15 as argument.
 329
 330     ACTION_LAYER_SET(layer)
 331     ACTION_LAYER_SET_TOGGLE(layer)
 332     ACTION_LAYER_SET_TAP_KEY(layer, key)
 333     ACTION_LAYER_SET_TAP_TOGGLE(layer)
 334
 335 `Layer Bit` action XOR bits with `current layer`. `Layer Bit` action can take 0 to 8 as argument.
 336
 337     ACTION_LAYER_BIT(bits)
 338     ACTION_LAYER_BIT_TOGGLE(bits)
 339     ACTION_LAYER_BIT_TAP_KEY(bits, key)
 340     ACTION_LAYER_BIT_TAP_TOGGLE(bits)
 341
 342 These acitons change `default layer`.
 343     ACTION_LAYER_SET_DEFAULT(layer)
 344     ACTION_LAYER_BIT_DEFAULT(bits)
 345
 346
 347 #### 2.3 Macro action
 348 `Macro` action indicates complex key strokes. ***TODO***
 349
 350
 351 #### 2.4 Function action
 352 `Function` action can be defined freely in C function. ***TODO***
 353 `Function` action is implemented in `keymap_call_function()`
 354
 355
 356
 357 ### 3. Layer
 358  Layer is key-action map to assign action to every physical key. You can define multiple layers in keymap and select a layer out of keymap during operation at will.
 359
 360  First layer is indexed by `Layer 0` which usually become **`default layer`** and active in initial state. **`current layer`** is active layer at that time and can be changed with user interaction. You can define **16 layers** at most in default keymap framework.
 361
 362  you can define a layer with placing keycode symbols separated with `comma` in `KEYMAP`, which is formed with resemblance to physical keyboard layout so as you can easily put keycode on place you want to map. ***You can define most of keys with just using keycodes*** except for `Fn` key serving special actions.
 363
 364
 365
 366 ### 4. Layer switching
 367 You can have some ways to switch layer with these actions.
 368 There are two kind of layer switch action `Layer Set` and `Layer Bit` and two type of switching behaviour **Momentary** and **Toggle**.
 369
 370 #### 4.1 Momentary switching
 371 Momentary switching changes layer only while holding Fn key.
 372
 373 ##### 4.1.1 Momentary Set
 374 This `Layer Set` action sets new layer(`Layer 1`) to `current layer` on key press event.
 375
 376     ACTION_LAYER_SET(1)
 377
 378 It switches to destination layer immediately when key is pressed, after that actions on keymap of destination layer is perfomed. ***Thus you shall need to place action to come back on destination layer***, or you will be stuck in destination layer without way to get back. To get back to `default layer` you can use this action.
 379
 380     ACTION_LAYER_DEFAULT
 381
 382 ##### 4.1.2 Momentary Bit
 383 This `Layer Bit` action performs XOR(`1`) with `current layer` on both press and release event. If you are on `Layer 0` now next layer to switch will be `Layer 1`. To come back to previous layer you need to place same action on destination layer.
 384
 385     ACTION_LAYER_BIT(1)
 386
 387 #### 4.2 Toggle switching
 388 Toggle switching changes layer after press then release. You keep being on the layer until you press key to return.
 389
 390 ##### 4.2.1 Toggle Set
 391 This `Layer Set Toggle` action is to set `Layer 1` to `current layer` on release and do none on press.
 392
 393     ACTION_LAYER_SET_TOGGLE(1)
 394
 395 To get back to `default layer` you can use this action.
 396
 397     ACTION_LAYER_DEFAULT
 398
 399 ##### 4.2.2 Toggle Bit
 400 This `Layer Bit Toggle` action is to XOR `1` with `current layer` on release and do none on press. If you are on `Layer 2` you'll switch to `Layer 3` on press. To come back to previous layer you need to place same action on destination layer.
 401
 402     ACTION_LAYER_BIT_TOGGLE(1)
 403
 404
 405 #### 4.3 Momentary switching with Tap key
 406 These actions switch to layer only while holding `Fn` key and register key on tap. **Tap** means to press and release key quickly.
 407
 408     ACTION_LAYER_SET_TAP_KEY(2, KC_SCLN)
 409     ACTION_LAYER_SET_BIT_KEY(2, KC_SCLN)
 410
 411 With these you can place layer switching function on normal alphabet key like `;` without losing its original register function.
 412
 413 #### 4.4 Momentary switching with Tap Toggle
 414 This changes layer only while holding `Fn` key and toggle layer after several taps. **Tap** means to press and release key quickly.
 415
 416     ACTION_LAYER_SET_TAP_TOGGLE(layer)
 417     ACTION_LAYER_BIT_TAP_TOGGLE(layer)
 418
 419 Number of taps can be defined with `TAPPING_TOGGLE` in `config.h`, `5` by default.
 420
 421
 422
 423
 424 Legacy Keymap
 425 -------------
 426 This was used in prior version and still works due to legacy support code in `common/keymap.c`. Legacy keymap doesn't support many of features that new keymap offers.
 427
 428 In comparison with new keymap how to define Fn key is different. It uses two arrays `fn_layer[]` and `fn_keycode[]`. The index of arrays corresponds with postfix number of `Fn` key. Array `fn_layer[]` indicates destination layer to switch and `fn_keycode[]` has keycodes to send when tapping `Fn` key.
 429
 430 In following setting example, `Fn0`, `Fn1` and `Fn2` switch layer to 1, 2 and 2 respectively. `Fn2` registers `Space` key when tap while `Fn0` and `Fn1` doesn't send any key.
 431
 432     static const uint8_t PROGMEM fn_layer[] = {
 433         1,              // Fn0
 434         2,              // Fn1
 435         2,              // Fn2
 436     };
 437
 438     static const uint8_t PROGMEM fn_keycode[] = {
 439         KC_NO,          // Fn0
 440         KC_NO,          // Fn1
 441         KC_SPC,         // Fn2
 442     };
 443
 444
 445
 446 Debuging
 447 --------
 448 Use PJRC's `hid_listen` to see debug messages. You can use the tool for debug even if firmware use LUFA stack.
 449
 450 You will see output from firmware like this.
 451
 452     r/c 01234567
 453     00: 00000000
 454     01: 00000000
 455     02: 00000000
 456     03: 00000000
 457     04: 00000000
 458     05: 00000000
 459     06: 00000000
 460     07: 00000000
 461
 462     ---- action_exec: start -----
 463     EVENT: 0307u(22511)
 464     Tapping: Tap release(2)
 465     ACTION: ACT_LAYER[5:2C]
 466     LAYER_PRESSED: Tap: unregister_code
 467     TAPPING_KEY=0307u(22511):2
 468     processed: 0307u(22511):2
 469
 470     Tapping: End(Timeout after releasing last tap): FFFFu(22715)
 471     TAPPING_KEY=0000u(0):0
 472
 473
 474
 475
 476 Magic Comannds
 477 --------------
 478 To see help press `Magic` + `H`.
 479
 480  `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.
 481
 482 Following commands can be also executed with `Magic` + key. In console mode `Magic` keybind is not needed.
 483
 484     ----- Command Help -----
 485     c:      enter console mode
 486     d:      toggle debug enable
 487     x:      toggle matrix debug
 488     k:      toggle keyboard debug
 489     m:      toggle mouse debug
 490     p:      toggle print enable
 491     v:      print device version & info
 492     t:      print timer count
 493     s:      print status
 494     0/F10:  switch to Layer0
 495     1/F1:   switch to Layer1
 496     2/F2:   switch to Layer2
 497     3/F3:   switch to Layer3
 498     4/F4:   switch to Layer4
 499     PScr:   power down/remote wake-up
 500     Caps:   Lock Keyboard(Child Proof)
 501     Paus:   jump to bootloader
 502
 503
 504
 505 Start Your Own Project
 506 -----------------------
 507
 508
 509
 510 Files & Directories
 511 -------------------
 512 ### Top
 513 * common/       - common codes
 514 * protocol/     - keyboard protocol support
 515 * keyboard/     - keyboard projects
 516 * converter/    - protocol converter projects
 517 * doc/          - documents
 518 * common.mk     - Makefile for common
 519 * protoco.mk    - Makefile for protocol
 520 * rules.mk      - Makefile for build rules
 521
 522 ### Common
 523 ***TODO***
 524
 525 ### Keyboard Protocols
 526 * lufa/     - LUFA USB stack
 527 * pjrc/     - PJRC USB stack
 528 * vusb/     - Objective Development V-USB
 529 * iwrap/    - Bluetooth HID for Bluegiga iWRAP
 530 * ps2.c     - PS/2 protocol
 531 * adb.c     - Apple Desktop Bus protocol
 532 * m0110.c   - Macintosh 128K/512K/Plus keyboard protocol
 533 * news.c    - Sony NEWS keyboard protocol
 534 * x68k.c    - Sharp X68000 keyboard protocol
 535 * serial_soft.c - Asynchronous Serial protocol implemented by software
 536
 537
 538
 539 License
 540 -------
 541 Under `GPL` 2 or later. Some protocol files are under `Modified BSD License`.
 542 PJRC stack has its own license.