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. Keymap 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 #### 1.0 Other key
 287 - `KC_NO` for no aciton
 288 - `KC_TRNS` for transparent layer
 289
 290 #### 1.1 Normal key
 291 - `KC_A` to `KC_Z`, `KC_1` to `KC_0` for alpha numeric key
 292 - `KC_MINS`, `KC_EQL`, `KC_GRV`, `KC_RBRC`, `KC_LBRC`, `KC_COMM`, `KC_DOT`, `KC_BSLS`, `KC_SLSH`, `KC_SCLN`, `KC_QUOT`
 293 - `KC_ESC`, `KC_TAB`, `KC_SPC`, `KC_BSPC`, `KC_ENT`, `KC_DEL`, `KC_INS`
 294 - `KC_UP`, `KC_DOWN`, `KC_RGHT`, `KC_LEFT`, `KC_PGUP`, `KC_PGDN`, `KC_HOME`, `KC_END`
 295 - `KC_CAPS`, `KC_NLCK`, `KC_SLCK`, `KC_PSCR`, `KC_PAUS`, `KC_APP`, `KC_F1` to `KC_F24`
 296 - `KC_P1` to `KC_P0`, `KC_PDOT`, `KC_PCMM`, `KC_PSLS`, `KC_PAST`, `KC_PMNS`, `KC_PPLS`, `KC_PEQL`, `KC_PENT` for keypad.
 297
 298 #### 1.2 Modifier
 299 There are 8 modifiers which has discrimination between left and right.
 300
 301 - `KC_LCTL` and `KC_RCTL` for Control
 302 - `KC_LSFT` and `KC_RSFT` for Shift
 303 - `KC_LALT` and `KC_RALT` for Alt
 304 - `KC_LGUI` and `KC_RGUI` for Windows key or Command key in Mac
 305
 306 #### 1.3 Fn key
 307 `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.***
 308
 309 #### 1.4 Mousekey
 310 - `KC_MS_U`, `KC_MS_D`, `KC_MS_L`, `KC_MS_R` for mouse cursor
 311 - `KC_WH_U`, `KC_WH_D`, `KC_WH_L`, `KC_WH_R` for mouse wheel
 312 - `KC_BTN1`, `KC_BTN2`, `KC_BTN3`, `KC_BTN4`, `KC_BTN5` for mouse buttons
 313
 314 #### 1.5 System & Media key
 315 - `KC_PWR`, `KC_SLEP`, `KC_WAKE` for Power, Sleep, Wake
 316 - `KC_MUTE`, `KC_VOLU`, `KC_VOLD` for audio volume control
 317 - `KC_MNXT`, `KC_MPRV`, `KC_MSTP`, `KC_MPLY`, `KC_MSEL` for media control
 318 - `KC_MAIL`, `KC_CALC`, `KC_MYCM` for application launch
 319 - `KC_WSCH`, `KC_WHOM`, `KC_WBAK`, `KC_WFWD`, `KC_WSTP`, `KC_WREF`, `KC_WFAV` for web browser operation
 320
 321 #### Keycode Table
 322  See [keycode table](doc/keycode.txt) in `doc/keycode.txt`  or `common/keycode.h` for the detail or other keycodes.
 323
 324  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.
 325 [HID usage]: http://www.usb.org/developers/devclass_docs/Hut1_11.pdf
 326
 327
 328
 329 ### 2. Action
 330 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.
 331
 332 Most of keys just register 8bit keycode as HID usage(or scan code) to host, but to support other complex features needs 16bit extended action codes internally. But using 16bit action codes in 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'*.
 333
 334 #### 2.1 Key action
 335 Key is simple action that registers keycode on press of key and unregister on release.
 336 You can define `Key` action on *'A'* key with:
 337
 338     ACTION_KEY(KC_A)
 339
 340 But you don't need to use this expression directly because you can just put symbol `A` in `KEYMAP` definition.
 341
 342  Say you want to assign a key to `Shift + 1` to get charactor *'!'* or `Alt + Tab` to switch windows.
 343
 344     ACTION_MOD_KEY(KC_LSHIFT, KC_1)
 345     ACTION_MOD_KEY(KC_LALT, KC_TAB)
 346
 347 Or `Alt,Shift + Tab` can be defined.
 348
 349     ACTION_MODS_KEY((MOD_BIT(KC_LALT) | MOD_BIT(KC_LSHIFT)), KC_TAB)
 350
 351 These actions are comprised of strokes of modifiers and a key. `Macro` action is needed if you want more complex key strokes.
 352
 353 #### 2.2 Layer Actions
 354 This sets `default layer` into `current layer`. With this action you can return to `default layer`.
 355
 356     ACTION_LAYER_DEFAULT
 357
 358 `Layer Set` action sets given layer argument to `current layer`. `Layer Set` action can take 0 to 15 as argument.
 359
 360     ACTION_LAYER_SET(layer)
 361     ACTION_LAYER_SET_TOGGLE(layer)
 362     ACTION_LAYER_SET_TAP_KEY(layer, key)
 363     ACTION_LAYER_SET_TAP_TOGGLE(layer)
 364
 365 `Layer Bit` action XOR given bits with `current layer`. `Layer Bit` action can take 0 to 15 as argument.
 366
 367     ACTION_LAYER_BIT(bits)
 368     ACTION_LAYER_BIT_TOGGLE(bits)
 369     ACTION_LAYER_BIT_TAP_KEY(bits, key)
 370     ACTION_LAYER_BIT_TAP_TOGGLE(bits)
 371
 372 These acitons change `default layer`.
 373     ACTION_LAYER_SET_DEFAULT(layer)
 374     ACTION_LAYER_BIT_DEFAULT(bits)
 375
 376
 377 #### 2.3 Macro action
 378 ***NOT FIXED***
 379 `Macro` action indicates complex key strokes.
 380
 381     MACRO( MD(LSHIFT), D(D), END )
 382     MACRO( U(D), MU(LSHIFT), END )
 383     MACRO( I(255), T(H), T(E), T(L), T(L), W(255), T(O), END )
 384
 385 ##### 2.3.1 Normal mode
 386 - **I()**   change interavl of stroke.
 387 - **D()**   press key
 388 - **U()**   release key
 389 - **T()**   type key(press and release)
 390 - **W()**   wait
 391 - **MD()**  modifier down
 392 - **MU()**  modifier up
 393 - **END**   end mark
 394
 395 ##### 2.3.2 Extended mode
 396
 397 ***TODO: sample impl***
 398 See `keyboard/hhkb/keymap.c` for sample.
 399
 400
 401 #### 2.4 Function action
 402 ***NOT FIXED***
 403 There are two type of action, normal `Function` and tappable `Function`.
 404 These actions call user defined function with `id`, `opt`, and key event information as arguments.
 405
 406 ##### 2.4.1 Function
 407 To define normal `Function` action in keymap use this.
 408
 409     ACTION_FUNCTION(id, opt)
 410
 411 ##### 2.4.2 Function with tap
 412 To define tappable `Function` action in keymap use this.
 413
 414     ACTION_FUNCTION_TAP(id, opt)
 415
 416 ##### 2.4.3 Implement user function
 417 `Function` actions can be defined freely with C by user in callback function:
 418
 419     void keymap_call_function(keyrecord_t *event, uint8_t id, uint8_t opt)
 420
 421 This C function is called every time key is operated, argument `id` selects action to be performed and `opt` can be used for option. Functon `id` can be 0-255 and `opt` can be 0-15.
 422
 423  `keyrecord_t` is comprised of key event and tap count. `keyevent_t` indicates which and when key is pressed or released. From `tap_count` you can know tap state, 0 means no tap. These information will be used in user function to decide how action of key is performed.
 424
 425     typedef struct {
 426         keyevent_t  event;
 427         uint8_t     tap_count;
 428     } keyrecord_t;
 429
 430     typedef struct {
 431         key_t    key;
 432         bool     pressed;
 433         uint16_t time;
 434     } keyevent_t;
 435
 436     typedef struct {
 437         uint8_t col;
 438         uint8_t row;
 439     } key_t;
 440
 441 ***TODO: sample impl***
 442 See `keyboard/hhkb/keymap.c` for sample.
 443
 444
 445
 446
 447
 448 ### 3. Layer
 449  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.
 450
 451  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.
 452
 453  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.
 454
 455
 456
 457 ### 4. Layer switching
 458 You can have some ways to switch layer with these actions.
 459 There are two kind of layer switch action `Layer Set` and `Layer Bit` and two type of switching behaviour **Momentary** and **Toggle**.
 460
 461 #### 4.1 Momentary switching
 462 Momentary switching changes layer only while holding Fn key.
 463
 464 ##### 4.1.1 Momentary Set
 465 This `Layer Set` action sets new layer `Layer 1` to `current layer` on key press event.
 466
 467     ACTION_LAYER_SET(1)
 468
 469 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.
 470
 471     ACTION_LAYER_DEFAULT
 472
 473 ##### 4.1.2 Momentary Bit
 474 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.
 475
 476     ACTION_LAYER_BIT(1)
 477
 478 #### 4.2 Toggle switching
 479 Toggle switching changes layer after press then release. You keep being on the layer until you press key to return.
 480
 481 ##### 4.2.1 Toggle Set
 482 This `Layer Set Toggle` action is to set `Layer 1` to `current layer` on release and do none on press.
 483
 484     ACTION_LAYER_SET_TOGGLE(1)
 485
 486 To get back to `default layer` you can use this action.
 487
 488     ACTION_LAYER_DEFAULT
 489
 490 ##### 4.2.2 Toggle Bit
 491 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.
 492
 493     ACTION_LAYER_BIT_TOGGLE(1)
 494
 495
 496 #### 4.3 Momentary switching with Tap key
 497 These actions switch to layer only while holding `Fn` key and register key on tap. **Tap** means to press and release key quickly.
 498
 499     ACTION_LAYER_SET_TAP_KEY(2, KC_SCLN)
 500     ACTION_LAYER_SET_BIT_KEY(2, KC_SCLN)
 501
 502 With these you can place layer switching function on normal alphabet key like `;` without losing its original register function.
 503
 504 #### 4.4 Momentary switching with Tap Toggle
 505 This changes layer only while holding `Fn` key and toggle layer after several taps. **Tap** means to press and release key quickly.
 506
 507     ACTION_LAYER_SET_TAP_TOGGLE(layer)
 508     ACTION_LAYER_BIT_TAP_TOGGLE(layer)
 509
 510 Number of taps can be defined with `TAPPING_TOGGLE` in `config.h`, `5` by default.
 511
 512
 513
 514
 515 Legacy Keymap
 516 -------------
 517 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.
 518
 519 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.
 520
 521 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.
 522
 523     static const uint8_t PROGMEM fn_layer[] = {
 524         1,              // Fn0
 525         2,              // Fn1
 526         2,              // Fn2
 527     };
 528
 529     static const uint8_t PROGMEM fn_keycode[] = {
 530         KC_NO,          // Fn0
 531         KC_NO,          // Fn1
 532         KC_SPC,         // Fn2
 533     };
 534
 535
 536
 537 Debuging
 538 --------
 539 Use PJRC's `hid_listen` to see debug messages. You can use the tool for debug even if firmware use LUFA stack.
 540
 541 You will see output from firmware like this.
 542
 543     r/c 01234567
 544     00: 00000000
 545     01: 00000000
 546     02: 00000000
 547     03: 00000000
 548     04: 00000000
 549     05: 00000000
 550     06: 00000000
 551     07: 00000000
 552
 553     ---- action_exec: start -----
 554     EVENT: 0307u(22511)
 555     Tapping: Tap release(2)
 556     ACTION: ACT_LAYER[5:2C]
 557     LAYER_PRESSED: Tap: unregister_code
 558     TAPPING_KEY=0307u(22511):2
 559     processed: 0307u(22511):2
 560
 561     Tapping: End(Timeout after releasing last tap): FFFFu(22715)
 562     TAPPING_KEY=0000u(0):0
 563
 564
 565
 566
 567 Magic Comannds
 568 --------------
 569 To see help press `Magic` + `H`.
 570
 571  `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.
 572
 573 Following commands can be also executed with `Magic` + key. In console mode `Magic` keybind is not needed.
 574
 575     ----- Command Help -----
 576     c:      enter console mode
 577     d:      toggle debug enable
 578     x:      toggle matrix debug
 579     k:      toggle keyboard debug
 580     m:      toggle mouse debug
 581     p:      toggle print enable
 582     v:      print device version & info
 583     t:      print timer count
 584     s:      print status
 585     0/F10:  switch to Layer0
 586     1/F1:   switch to Layer1
 587     2/F2:   switch to Layer2
 588     3/F3:   switch to Layer3
 589     4/F4:   switch to Layer4
 590     PScr:   power down/remote wake-up
 591     Caps:   Lock Keyboard(Child Proof)
 592     Paus:   jump to bootloader
 593
 594 ### Boot Magic
 595 Magic commands are executed when boot time. Press `Magic` command key then pulgin.
 596
 597 Define these macros in config.h.
 598
 599     IS_BOOTMAGIC_DEBUG
 600     IS_BOOTMAGIC_BOOTLOADER
 601
 602 ***TODO: sample impl***
 603 See `keyboard/hhkb/config.h` for sample.
 604
 605
 606
 607 Start Your Own Project
 608 -----------------------
 609
 610
 611
 612 Files & Directories
 613 -------------------
 614 ### Top
 615 * common/       - common codes
 616 * protocol/     - keyboard protocol support
 617 * keyboard/     - keyboard projects
 618 * converter/    - protocol converter projects
 619 * doc/          - documents
 620 * common.mk     - Makefile for common
 621 * protoco.mk    - Makefile for protocol
 622 * rules.mk      - Makefile for build rules
 623
 624 ### Common
 625 * action.[ch]
 626 * action_macro.[ch]
 627 * bootloader.[ch]
 628 * command.[ch]
 629 * controller_teensy.h
 630 * debug.[ch]
 631 * host.[ch]
 632 * host_driver.h
 633 * keyboard.[ch]
 634 * keycode.h
 635 * keymap.[ch]
 636 * led.h
 637 * matrix.h
 638 * mousekey.[ch]
 639 * print.[ch]
 640 * report.h
 641 * sendchar.h
 642 * sendchar_null.c
 643 * sendchar_uart.c
 644 * timer.[ch]
 645 * uart.[ch]
 646 * util.[ch]
 647
 648 ### Keyboard Protocols
 649 * lufa/     - LUFA USB stack
 650 * pjrc/     - PJRC USB stack
 651 * vusb/     - Objective Development V-USB
 652 * iwrap/    - Bluetooth HID for Bluegiga iWRAP
 653 * ps2.c     - PS/2 protocol
 654 * adb.c     - Apple Desktop Bus protocol
 655 * m0110.c   - Macintosh 128K/512K/Plus keyboard protocol
 656 * news.c    - Sony NEWS keyboard protocol
 657 * x68k.c    - Sharp X68000 keyboard protocol
 658 * serial_soft.c - Asynchronous Serial protocol implemented by software
 659
 660
 661
 662 License
 663 -------
 664 Under `GPL` 2 or later. Some protocol files are under `Modified BSD License`.
 665 LUFA, PJRC and V-USB stack have their own license respectively.