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