FAQ-Keymap.md

   1 ## READ FIRST
   2 https://github.com/tmk/tmk_keyboard/blob/master/doc/keymap.md
   3
   4 ## How to get keycode
   5 See [doc/keycode.txt](https://github.com/tmk/tmk_keyboard/blob/master/doc/keycode.txt).
   6 Keycodes are actually defined in [common/keycode.h](https://github.com/tmk/tmk_keyboard/blob/master/common/keycode.h).
   7
   8 ## Sysrq key
   9 Use keycode for Print Screen(`KC_PSCREEN` or `KC_PSCR`) instead of `KC_SYSREQ`. Key combination of 'Alt + Print Screen' is recognized as 'System request'.
  10
  11 See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and
  12 - http://en.wikipedia.org/wiki/Magic_SysRq_key
  13 - http://en.wikipedia.org/wiki/System_request
  14
  15 ## Power key doesn't work
  16 Use `KC_PWR` instead of `KC_POWER` or vice versa.
  17 - `KC_PWR` works with Windows and Linux, not with OSX.
  18 - `KC_POWER` works with OSX and Linux, not with Windows.
  19
  20 http://geekhack.org/index.php?topic=14290.msg1327264#msg1327264
  21
  22 ## Oneshot modifier
  23 Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'.  Oneshot Shift mitgates this for me.
  24 https://github.com/tmk/tmk_keyboard/issues/67
  25
  26 ## Modifier/Layer stuck
  27 Modifier keys or layers can be stuck unless layer switching is configured properly.
  28 For Modifier keys and layer actions you have to place `KC_TRANS` on same position of destination layer to  unregister the modifier key or return to previous layer on release event.
  29
  30 https://github.com/tmk/tmk_keyboard/blob/master/doc/keymap.md#31-momentary-switching
  31 http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
  32
  33
  34 ## Mechanical Lock Switch Support
  35 https://github.com/tmk/tmk_keyboard#mechanical-locking-support
  36
  37 This feature is for *mechanical lock switch* like this Alps one.
  38 http://deskthority.net/wiki/Alps_SKCL_Lock
  39
  40 Using enabling this feature and using keycodes `LCAP`, `LNUM` or `LSCR` in keymap you can use physical locking CapsLock, NumLock or ScrollLock keys as you expected.
  41
  42 Old vintage mechanical keyboards occasionally have lock switches but modern ones don't have. ***You don't need this feature in most case and just use keycodes `CAPS`, `NLCK` and `SLCK`.***
  43
  44
  45 ## Input special charactors other than ASCII like Cédille 'Ç'
  46 NO UNIVERSAL METHOD TO INPUT THOSE WORKS OVER ALL SYSTEMS. You have to define **MACRO** in way specific to your OS or layout.
  47
  48 See this post for example **MACRO** code.
  49
  50 http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620
  51
  52 On **Windows** you can use `AltGr` key or **Alt code**.
  53 - http://en.wikipedia.org/wiki/AltGr_key
  54 - http://en.wikipedia.org/wiki/Alt_code
  55
  56 On **Mac** OS defines `Option` key combinations.
  57 - http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input
  58
  59 On **Xorg** you can use `compose` key, instead.
  60 - http://en.wikipedia.org/wiki/Compose_key
  61
  62 And see this for **Unicode** input.
  63 - http://en.wikipedia.org/wiki/Unicode_input
  64
  65
  66 ### Apple keyboard Fn
  67 Not supported.
  68
  69 Apple keyboard sends keycode for Fn unlike most of other keyboards.
  70 I think you can send Apple Fn key using Apple venter specific Page 0xff00 and usage 0x0003. But you have to change HID Report Descriptor for this, of course.
  71
  72 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/AppleHIDUsageTables.h
  73
  74
  75 ## Media control keys in Mac OSX
  76 See [PR #160](https://github.com/tmk/tmk_keyboard/issues/160).
  77
  78 >The "Play/Pause"(KC_MPLY) works good on Apple OS. But "Next/Prev Track" buttons are unfunctional.
  79 Apple OS use "Fast Forwad"(F9 on Apple keyboard) & "Rewind"(F7 on Apple keyboard) instead.
  80
  81 Use `KC_MFFD`(`KC_MEDIA_FAST_FORWARD`) and `KC_MRWD`(`KC_MEDIA_REWIND`) instead of KC_ and `KC_MNXT` and `KC_MPRV`.
  82
  83 https://github.com/tmk/tmk_keyboard/blob/5a8dbc63ea29eb454ad5f36de5c6c33172230f88/common/keycode.h#L141-L144
  84
  85
  86 ## Keys supported in Mac OSX?
  87 You can know which keycodes are supported in OSX from this source code.
  88
  89 `usb_2_adb_keymap` array maps Keyboard/Keypad Page usages to ADB scancodes(OSX internal keycodes).
  90
  91 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c
  92
  93 And `IOHIDConsumer::dispatchConsumerEvent` handles Consumer page usages.
  94
  95 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp