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](doc/keycode.txt) in `doc/keycode.txt`  or `common/keycode.h` for other keycodes.
 293
 294  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.
 295 [HID usage]: http://www.usb.org/developers/devclass_docs/Hut1_11.pdf
 296
 297
 298
 299 ### 2. Action
 300 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.
 301
 302 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`.
 303
 304 #### 2.1 Key action
 305 Key is simple action that registers keycode on press of key and unregister on release.
 306 You can define `Key` action on `A` with:
 307
 308     ACTION_KEY(KC_A)
 309
 310 But you won't need to use this expression directly because you can just put symbol like `A` in `KEYMAP`.
 311
 312  Say you want to assign a key to `Shift + 1` to get *!* or `Alt + Tab` to switch windows.
 313
 314     ACTION_MOD_KEY(KC_LSHIFT, KC_1)
 315     ACTION_MOD_KEY(KC_LALT, KC_TAB)
 316
 317 `Alt,Shift + Tab`
 318     ACTION_MODS_KEY((MOD_BIT(KC_LALT) | MOD_BIT(KC_LSHIFT)), KC_TAB)
 319
 320 These actions are comprised of strokes of modifiers and a key. `Macro` action is needed if you want more complex key strokes.
 321
 322 #### 2.2 Layer Actions
 323 This sets `default layer` into `current layer`. With this action you can return to `default layer`.
 324
 325     ACTION_LAYER_DEFAULT
 326
 327 `Layer Set` action sets given layer argument to `current layer`. `Layer Set` action can take 0 to 15 as argument.
 328
 329     ACTION_LAYER_SET(layer)
 330     ACTION_LAYER_SET_TOGGLE(layer)
 331     ACTION_LAYER_SET_TAP_KEY(layer, key)
 332     ACTION_LAYER_SET_TAP_TOGGLE(layer)
 333
 334 `Layer Bit` action XOR bits with `current layer`. `Layer Bit` action can take 0 to 8 as argument.
 335
 336     ACTION_LAYER_BIT(bits)
 337     ACTION_LAYER_BIT_TOGGLE(bits)
 338     ACTION_LAYER_BIT_TAP_KEY(bits, key)
 339     ACTION_LAYER_BIT_TAP_TOGGLE(bits)
 340
 341 These acitons change `default layer`.
 342     ACTION_LAYER_SET_DEFAULT(layer)
 343     ACTION_LAYER_BIT_DEFAULT(bits)
 344
 345
 346 #### 2.3 Macro action
 347 `Macro` action indicates complex key strokes. ***TODO***
 348
 349
 350 #### 2.4 Function action
 351 `Function` action can be defined freely in C function. ***TODO***
 352 `Function` action is implemented in `keymap_call_function()`
 353
 354
 355
 356 ### 3. Layer
 357  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.
 358
 359  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.
 360
 361  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.
 362
 363
 364
 365 ### 4. Layer switching
 366 You can have some ways to switch layer with these actions.
 367 There are two kind of layer switch action `Layer Set` and `Layer Bit` and two type of switching behaviour **Momentary** and **Toggle**.
 368
 369 #### 4.1 Momentary switching
 370 Momentary switching changes layer only while holding Fn key.
 371
 372 ##### 4.1.1 Momentary Set
 373 This `Layer Set` action sets new layer(`Layer 1`) to `current layer` on key press event.
 374
 375     ACTION_LAYER_SET(1)
 376
 377 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.
 378
 379     ACTION_LAYER_DEFAULT
 380
 381 ##### 4.1.2 Momentary Bit
 382 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.
 383
 384     ACTION_LAYER_BIT(1)
 385
 386 #### 4.2 Toggle switching
 387 Toggle switching changes layer after press then release. You keep being on the layer until you press key to return.
 388
 389 ##### 4.2.1 Toggle Set
 390 This `Layer Set Toggle` action is to set `Layer 1` to `current layer` on release and do none on press.
 391
 392     ACTION_LAYER_SET_TOGGLE(1)
 393
 394 To get back to `default layer` you can use this action.
 395
 396     ACTION_LAYER_DEFAULT
 397
 398 ##### 4.2.2 Toggle Bit
 399 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.
 400
 401     ACTION_LAYER_BIT_TOGGLE(1)
 402
 403
 404 #### 4.3 Momentary switching with Tap key
 405 These actions switch to layer only while holding `Fn` key and register key on tap. **Tap** means to press and release key quickly.
 406
 407     ACTION_LAYER_SET_TAP_KEY(2, KC_SCLN)
 408     ACTION_LAYER_SET_BIT_KEY(2, KC_SCLN)
 409
 410 With these you can place layer switching function on normal alphabet key like `;` without losing its original register function.
 411
 412 #### 4.4 Momentary switching with Tap Toggle
 413 This changes layer only while holding `Fn` key and toggle layer after several taps. **Tap** means to press and release key quickly.
 414
 415     ACTION_LAYER_SET_TAP_TOGGLE(layer)
 416     ACTION_LAYER_BIT_TAP_TOGGLE(layer)
 417
 418 Number of taps can be defined with `TAPPING_TOGGLE` in `config.h`, `5` by default.
 419
 420
 421
 422
 423 Legacy Keymap
 424 -------------
 425 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.
 426
 427 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.
 428
 429 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.
 430
 431     static const uint8_t PROGMEM fn_layer[] = {
 432         1,              // Fn0
 433         2,              // Fn1
 434         2,              // Fn2
 435     };
 436
 437     static const uint8_t PROGMEM fn_keycode[] = {
 438         KC_NO,          // Fn0
 439         KC_NO,          // Fn1
 440         KC_SPC,         // Fn2
 441     };
 442
 443
 444
 445 Debuging
 446 --------
 447 Use PJRC's `hid_listen` to see debug messages. You can use the tool for debug even if firmware use LUFA stack.
 448
 449 You will see output from firmware like this.
 450
 451     r/c 01234567
 452     00: 00000000
 453     01: 00000000
 454     02: 00000000
 455     03: 00000000
 456     04: 00000000
 457     05: 00000000
 458     06: 00000000
 459     07: 00000000
 460
 461     ---- action_exec: start -----
 462     EVENT: 0307u(22511)
 463     Tapping: Tap release(2)
 464     ACTION: ACT_LAYER[5:2C]
 465     LAYER_PRESSED: Tap: unregister_code
 466     TAPPING_KEY=0307u(22511):2
 467     processed: 0307u(22511):2
 468
 469     Tapping: End(Timeout after releasing last tap): FFFFu(22715)
 470     TAPPING_KEY=0000u(0):0
 471
 472
 473
 474
 475 Magic Comannds
 476 --------------
 477 To see help press `Magic` + `H`.
 478
 479  `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.
 480
 481 Following commands can be also executed with `Magic` + key. In console mode `Magic` keybind is not needed.
 482
 483     ----- Command Help -----
 484     c:      enter console mode
 485     d:      toggle debug enable
 486     x:      toggle matrix debug
 487     k:      toggle keyboard debug
 488     m:      toggle mouse debug
 489     p:      toggle print enable
 490     v:      print device version & info
 491     t:      print timer count
 492     s:      print status
 493     0/F10:  switch to Layer0
 494     1/F1:   switch to Layer1
 495     2/F2:   switch to Layer2
 496     3/F3:   switch to Layer3
 497     4/F4:   switch to Layer4
 498     PScr:   power down/remote wake-up
 499     Caps:   Lock Keyboard(Child Proof)
 500     Paus:   jump to bootloader
 501
 502
 503
 504 Start Your Own Project
 505 -----------------------
 506
 507
 508
 509 Files & Directories
 510 -------------------
 511 ### Top
 512 * common/       - common codes
 513 * protocol/     - keyboard protocol support
 514 * keyboard/     - keyboard projects
 515 * converter/    - protocol converter projects
 516 * doc/          - documents
 517 * common.mk     - Makefile for common
 518 * protoco.mk    - Makefile for protocol
 519 * rules.mk      - Makefile for build rules
 520
 521 ### Common
 522 * action.[ch]
 523 * action_macro.[ch]
 524 * bootloader.[ch]
 525 * command.[ch]
 526 * controller_teensy.h
 527 * debug.[ch]
 528 * host.[ch]
 529 * host_driver.h
 530 * keyboard.[ch]
 531 * keycode.h
 532 * keymap.[ch]
 533 * led.h
 534 * matrix.h
 535 * mousekey.[ch]
 536 * print.[ch]
 537 * report.h
 538 * sendchar.h
 539 * sendchar_null.c
 540 * sendchar_uart.c
 541 * timer.[ch]
 542 * uart.[ch]
 543 * util.[ch]
 544
 545 ### Keyboard Protocols
 546 * lufa/     - LUFA USB stack
 547 * pjrc/     - PJRC USB stack
 548 * vusb/     - Objective Development V-USB
 549 * iwrap/    - Bluetooth HID for Bluegiga iWRAP
 550 * ps2.c     - PS/2 protocol
 551 * adb.c     - Apple Desktop Bus protocol
 552 * m0110.c   - Macintosh 128K/512K/Plus keyboard protocol
 553 * news.c    - Sony NEWS keyboard protocol
 554 * x68k.c    - Sharp X68000 keyboard protocol
 555 * serial_soft.c - Asynchronous Serial protocol implemented by software
 556
 557
 558
 559 License
 560 -------
 561 Under `GPL` 2 or later. Some protocol files are under `Modified BSD License`.
 562 PJRC stack has its own license.