Skip to content

FAQ Keymap

Jump to bottom
tmk edited this page Jun 13, 2017 · 80 revisions

READ FIRST

https://github.com/tmk/tmk_core/blob/master/doc/keymap.md

How to get keycode

See doc/keycode.txt. Keycodes are actually defined in common/keycode.h.

Sysrq key

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'.

See issue #168 and

Power key doesn't work

Use KC_PWR instead of KC_POWER or vice versa.

  • KC_PWR works with Windows and Linux, not with OSX.
  • KC_POWER works with OSX and Linux, not with Windows.

http://geekhack.org/index.php?topic=14290.msg1327264#msg1327264

Oneshot modifier

Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'. Oneshot Shift mitgates this for me. https://github.com/tmk/tmk_keyboard/issues/67

Modifier/Layer stuck

Modifier keys or layers can be stuck unless layer switching is configured properly. 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.

Fixed this problem at commit as of 2017/05/30. https://github.com/tmk/tmk_keyboard/commit/ba2883fd9ab040fc670ad729e6cddd4c67c8188c

Mechanical Lock Switch Support

https://github.com/tmk/tmk_keyboard#mechanical-locking-support

This feature is for mechanical lock switch like this Alps one. http://deskthority.net/wiki/Alps_SKCL_Lock

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.

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.

Input special charactors other than ASCII like Cédille 'Ç'

NO UNIVERSAL INPUT METHOD THAT WORKS OVER ALL SYSTEMS. It depends largely on your OS and keyboard layout.

1. Keyboard Layout

Some keyboard layouts support language specific charactor input with AltGr key. AltGr key is equivalent to Right Alt generally. http://en.wikipedia.org/wiki/AltGr_key

How to input a charactor is diffrent between keyboard layouts. For example you can register 'ç' just with 9 key without any modifier in French AZERTY layout. But using this layout won't be a solution in many cases here.

'US international' layout will be useful if you prefer ANSI keyboard layout basically, you can type 'ç' with AltGr + ,. See this for detail. https://en.wikipedia.org/wiki/QWERTY#US-International

You can use Modified key action such as ACTION_MODS_KEY(MOD_RALT, KC_COMMA) in keymap. https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#212-modified-key

Some charactors require 'dead key' sequence such as AltGr + 6, a to get 'â'. In this case you have to define keymap MACRO for this purpose. https://en.wikipedia.org/wiki/Dead_key

For other language layouts you can find here. https://en.wikipedia.org/wiki/AltGr_key#Function

2. Unicode input

Key sequence for Unicode input differs between OS's. You need to use keymap MACRO in keymap to input the key sequence.

http://en.wikipedia.org/wiki/Unicode_input

  • Xorg: Ctrl + Shift + u, Unicode, Enter
  • Mac: Hold down Option, Unicode, then release Option
  • Windows: Hold down Alt, Keypad +, Unicode, then release Alt

You can search code point for Unicode charactor here. https://unicode-table.com/en/

You need to edit registry to enable this on Windows. See this. https://en.wikipedia.org/wiki/Unicode_input#In_Microsoft_Windows

3. Other methods

These methods are specific to OS too.

Apple/Mac keyboard Fn

Not supported.

Apple/Mac keyboard sends keycode for Fn unlike most of other keyboards. I think you can send Apple Fn key using Apple vendor specific Page 0xff01 and usage 0x0003. But you have to change HID Report Descriptor for this, of course.

https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/AppleHIDUsageTables.h

Media control keys in Mac OSX

KC_MNXT and KC_MPRV does not work on Mac

Use KC_MFFD(KC_MEDIA_FAST_FORWARD) and KC_MRWD(KC_MEDIA_REWIND) instead of KC_MNXT and KC_MPRV. See https://github.com/tmk/tmk_keyboard/issues/195 and https://github.com/tmk/tmk_keyboard/issues/332

EDIT: they work on El Capitan. 2016/07/09 https://github.com/tmk/tmk_keyboard/issues/332#issuecomment-231521504

Keys supported in Mac OSX?

You can know which keycodes are supported in OSX from this source code.

usb_2_adb_keymap array maps Keyboard/Keypad Page usages to ADB scancodes(OSX internal keycodes).

https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c

And IOHIDConsumer::dispatchConsumerEvent handles Consumer page usages.

https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp

JIS keys in Mac OSX

Japanese JIS keyboard specific keys like 無変換(Muhenkan), 変換(Henkan), ひらがな(hiragana) are not recognized on OSX. You can use Seil to enable those keys, try following options.

  • Enable NFER Key on PC keyboard
  • Enable XFER Key on PC keyboard
  • Enable KATAKANA Key on PC keyboard

https://pqrs.org/osx/karabiner/seil.html

RN-42 Bluetooth doesn't work with Karabiner

Karabiner - Keymapping tool on Mac OSX - ignores inputs from RN-42 module by default. You have to enable this option to make Karabiner working with your keyboard. https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237

See these for the deail of this problem. https://github.com/tmk/tmk_keyboard/issues/213 https://github.com/tekezo/Karabiner/issues/403

Esc and `~ on a key

You can define FC660 and Poker style ESC with ACTION_LAYER_MODS. https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#35-momentary-switching-with-modifiers

#include "keymap_common.h"


/* Leopold FC660
 * https://elitekeyboards.com/products.php?sub=leopold,compact&pid=fc660c
 * Shift + Esc = ~
 * Fn    + Esc = `
 *
 * Votex Poker II
 * https://adprice.fedorapeople.org/poker2_manual.pdf
 * Fn         + Esc = `
 * Fn + Shift + Esc = ~
 */
const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    /* 0: qwerty */
    [0] = KEYMAP( \
        ESC, 1,   2,   3,   4,   5,   6,   7,   8,   9,   0,   MINS,EQL, NUHS,BSPC, \
        TAB, Q,   W,   E,   R,   T,   Y,   U,   I,   O,   P,   LBRC,RBRC,BSLS, \
        LCTL,A,   S,   D,   F,   G,   H,   J,   K,   L,   SCLN,QUOT,ENT,  \
        FN0, NUBS,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,RSFT,ESC, \
        LCTL,LGUI,LALT,          SPC,                     RALT,FN1, RGUI,RCTL),
    [1] = KEYMAP( \
        GRV, TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\
        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
        TRNS,TRNS,TRNS,          TRNS,                    TRNS,TRNS,TRNS,TRNS),
    [2] = KEYMAP( \
        GRV, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, TRNS,TRNS, \
        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\
        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
        TRNS,TRNS,TRNS,          TRNS,                    TRNS,TRNS,TRNS,TRNS),
};

const uint16_t PROGMEM fn_actions[] = {
    // https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#35-momentary-switching-with-modifiers
    [0] = ACTION_LAYER_MODS(1, MOD_LSFT),
    [1] = ACTION_LAYER_MOMENTARY(2),
};

Otherwise, you can write code, see this. https://github.com/p3lim/keyboard_firmware/commit/fd799c12b69a5ab5addd1d4c03380a1b8ef8e9dc

32 Fn keys are not enough?

actionmap

It uses 16 bit codes and has no limitation of 32 Fn at the expense of memory space. TMK keymap is actually is 8 bit codes as subset of the actionmap. https://github.com/tmk/tmk_keyboard/issues?utf8=%E2%9C%93&q=is%3Aissue+actionmap

extension for modified keys

https://geekhack.org/index.php?topic=41989.msg1885526#msg1885526

Arrow on Right Modifier keys with Dual-Role

This turns right modifer keys into arrow keys when the keys are tapped while still modifiers when the keys are hold. In TMK the dual-role function is dubbed TAP.

#include "keymap_common.h"


/* Arrow keys on right modifier keys with TMK dual role feature
 *
 *  https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role
 *  https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
 */
const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    /* 0: qwerty */
    [0] = KEYMAP( \
        ESC, 1,   2,   3,   4,   5,   6,   7,   8,   9,   0,   MINS,EQL, NUHS,BSPC, \
        TAB, Q,   W,   E,   R,   T,   Y,   U,   I,   O,   P,   LBRC,RBRC,BSLS, \
        LCTL,A,   S,   D,   F,   G,   H,   J,   K,   L,   SCLN,QUOT,ENT,  \
        LSFT,NUBS,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,FN0, ESC, \
        FN4, LGUI,LALT,          SPC,                     APP, FN2, FN1, FN3),
    [1] = KEYMAP( \
        GRV, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, TRNS,TRNS, \
        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\
        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,FN5, TRNS, \
        TRNS,TRNS,TRNS,          TRNS,                    TRNS,FN7, FN6, FN8),
};

const uint16_t PROGMEM fn_actions[] = {
    [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP),
    [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN),
    [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT),
    [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT),
    [4] = ACTION_LAYER_MOMENTARY(1),
    [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP),
    [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN),
    [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME),
    [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END),
};

Dual-role key: https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys

Eject on Mac OSX

EJCT keycode works on OSX. https://github.com/tmk/tmk_keyboard/issues/250 It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default.

Not sure what keycode Eject is on genuine Apple keyboard actually. HHKB uses F20 for Eject key(Fn+f) on Mac mode but this is not same as Apple Eject keycode probably.

What's weak_mods and real_mods in action_util.c

TO BE IMPROVED

real_mods is intended to retains state of real/physical modifier key state, while weak_mods retains state of virtual or temprary modifiers which should not affect state real modifier key.

Let's say you hold down physical left shift key and type ACTION_MODS_KEY(LSHIFT, KC_A),

with weak_mods,

  • (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
  • (2) press ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT)
  • (3) release ACTION_MODS_KEY(LSHIFT, KC_A): waek_mods &= ~MOD_BIT(LSHIFT) real_mods still keeps modifier state.

without weak mods,

  • (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
  • (2) press ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT)
  • (3) release ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT) here real_mods lost state for 'physical left shift'.

weak_mods is ORed with real_mods when keyboard report is sent. https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57

Looking for AtlGr or Option key

AltGr is equivalent to Right Alt key, use KC_RALT. Use KC_LALT or KC_RALT for Option key on Mac.

How to define your own action/How to explore build-in action

See this. https://github.com/tmk/tmk_keyboard/issues/446#issuecomment-284899925

Multimedia key

Email on Windows

AL Email Reader(18A) is recognized as 'Photo viewer' on Windows10 weirdly. You can configure this behaviour at Settings>System>Apps for websites>Photo viewer.

https://geekhack.org/index.php?topic=88720.msg2439662#msg2439662

Clone this wiki locally