-
Notifications
You must be signed in to change notification settings - Fork 1.7k
FAQ Keymap
https://github.com/tmk/tmk_core/blob/master/doc/keymap.md
KEYMAP is legacy format which uses 8-bit keycodes while ACTIONMAP is new one which uses 16-bit action codes. UNIMAP is a kind of ACTIONMAP and used mainly for Keymap Editor.
See doc/keycode.txt. Keycodes are actually defined in common/keycode.h.
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
Use KC_PWR instead of KC_POWER or vice versa.
-
KC_PWRworks with Windows and Linux, not with OSX. -
KC_POWERworks with OSX and Linux, not with Windows.
http://geekhack.org/index.php?topic=14290.msg1327264#msg1327264
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 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.
- https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
- http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
- https://github.com/tmk/tmk_keyboard/issues/105
- https://github.com/tmk/tmk_keyboard/issues/248
- https://github.com/tmk/tmk_keyboard/issues/397
- https://github.com/tmk/tmk_keyboard/issues/441
Fixed this problem at commit as of 2017/05/30. https://github.com/tmk/tmk_keyboard/commit/ba2883fd9ab040fc670ad729e6cddd4c67c8188c
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.
NO UNIVERSAL INPUT METHOD THAT WORKS OVER ALL SYSTEMS. It depends largely on your OS and 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
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 releaseOption -
Windows: Hold down
Alt,Keypad +, Unicode, then releaseAlt
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
These methods are specific to OS too.
- Alt code on Windows: http://en.wikipedia.org/wiki/Alt_code
-
Optionkey on Mac: http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input -
Composekey on Xorg: http://en.wikipedia.org/wiki/Compose_key
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.
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
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
Japanese JIS USB keyboard specific keys like 無変換(Muhenkan), 変換(Henkan) and ひらがな(hiragana) are not recognized on macOS by default. And Apple Mac keyboards don't have those keys.
Use keycode MACE and MACJ in TMK keymap instead, they should work as かな(kana) and 英数(eisu) key on macOS.
| Key | USB HID Usage |
|---|---|
| 無変換(JIS) | MHEN (0x8B) |
| 変換(JIS) | HENK (0x8A) |
| ひらがな(JIS) | KANA (0x88) |
| 英数(Mac) | MACE (0x91) |
| かな(Mac) | MACJ (0x90) |
- JIS layout vs Mac layout: https://en.wikipedia.org/wiki/Keyboard_layout#Japanese
- USB HID usages used on Mac: http://www2d.biglobe.ne.jp/~msyk/keyboard/layout/usbkeycode.html
Or you can use Karabiner-Elements to enable those keys probably.
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
With some keyboards like Vortex Pok3r and Leopold FC660C you can get ~(tilde) with pressing Shift and Esc.
To realize the behaviour in TMK you can use ACTION_LAYER_MODS action with MOD_LSFT or MOD_RSFT as parameter.
This keymap file uses the action to emulate FC660C behaviour, refer to Shift keys in Layer 0.
Keymap Editor for TMK FC660C Controller uses this trick, check Shift keys on Layer0 and `(Esc) on Layer2.
You can use 'Code Edit' tab to edit action of the Shift keys.
Note: Origianl Leopold FC660C controller has a flaw that you never be able to register Shift + Esc combination. With our keymap you can press Fn + Q to invert Esc key into `, then press Fn + Shift + Esc.
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
https://geekhack.org/index.php?topic=41989.msg1885526#msg1885526
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
TMK KC_EJCT and AC_EJCT was actually 'Stop/Eject - 0xCC of Consumer Page 0x08' until 2024-03.
Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default.
See this issue also. https://github.com/tmk/tmk_keyboard/issues/774
Apple Magic Keyboard Eject key is 'Eject 0xB8 of Consumer Page 0x08'. https://verityj.github.io/2023/06/17/eject.html
HHKB pro/pro2(PD-KB300/400) uses 'F20 - 0x6F of Keyboard Page 0x07' for its Eject key(Fn+f). https://github.com/tmk/tmk_keyboard/issues/250
HHKB classic(PD-KB401) uses 'Eject - 0xB8 of Consumer Page 0x08'.
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
AltGr is equivalent to Right Alt key, use KC_RALT. Use KC_LALT or KC_RALT for Option key on Mac.
See this. https://github.com/tmk/tmk_keyboard/issues/446#issuecomment-284899925
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
In Functoin Action you can check current modifier state with get_mods which returns 8-bit value, whose bit takes 1 when modifier turns on.
Modifier state:
76543210
|||||||`-- LCTRL
||||||`--- LSHIFT
|||||`---- LALT
||||`----- LGUI
|||`------ RCTRL
||`------- RSHIFT
|`-------- RALT
`--------- RGUI
So you can test modifer state like below:
if (get_mods() & MOD_BIT(KC_RALT)) {
// with RAlt
if (get_mods() & (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT))) {
// with Shift
} else {
// without Shift
}
else {
// without RAlt
}
Use KC_NUHS(KC_NONUS_HASH) for key around Enter and KC_NUBS(KC_NONUS_BSLASH) for one next to Left Shift.
https://github.com/tmk/tmk_keyboard/blob/be80ed2ef3ca669cc8dcc3555c09da0a7defae8c/tmk_core/common/keycode.h#L90-L91
It seems that many of ISO keyobards in the market uses KC_BSLS(KC_BSLASH) instead of KC_NUHS.
Also refer to footnotes 2 and 3 on p59 of 'USB HID Usage Tables' spec. http://www.usb.org/developers/hidpage/Hut1_12v2.pdf
2 Typical language mappings: US: \| Belg: μ`£ FrCa: <}> Dan:’* Dutch: <> Fren:*μ Ger: #’ Ital: ù§ LatAm: }`] Nor:,*
Span: }Ç Swed: ,* Swiss: $£ UK: #~.
3 Typical language mappings: Belg:<\> FrCa:«°» Dan:<\> Dutch:]|[ Fren:<> Ger:<|> Ital:<> LatAm:<> Nor:<> Span:<>
Swed:<|> Swiss:<\> UK:\| Brazil: \|.
Assume that you are using non-US-QWERTY layout on your OS here.
Computer world is absolutely US-centric and you have to think keymap in US-QWERTY way. Use 'Q'(KC_Q) for 'A' and 'Z'(KC_Z) for 'W' in French-AZERTY keyboard, for example.
This is woe of us, who are minorities belong to rest of the world :)
You can hook API for this purpose. hook_layer_change() is called when layer_state is changed and you can define the function to control your LED.
This is example from FC660C keymap file, it controls its LED when Layer1 state is changed.
#include "hook.h"
void hook_layer_change(uint32_t layer_state)
{
// lights LED on Insert when layer 1 is enabled
if (layer_state & (1L<<1)) {
PORTB &= ~(1<<5);
} else {
PORTB |= (1<<5);
}
}
At this time 'TAPPING_TERM' is only parameter for tap key. It is 200ms by default and you have to relase a key within the term to get 'tap' action and otherwise 'hold' action will come out.
You can configure in your config.h.
https://github.com/tmk/tmk_keyboard/blob/master/keyboard/hhkb/config.h#L43-L44
/* period of tapping(ms) */
#define TAPPING_TERM 300
Also see this entry for Tapping or Tap key. https://github.com/tmk/tmk_keyboard/wiki/Keymap#4-tapping
Especially when you are using keyboard with physical ISO or JIS layout Mac may not recognize your keyboard type immediately and you have to specify the type manually.
https://support.apple.com/kb/PH25495?locale=en_US&viewlocale=en_US
Try the above first. Go 'System Preferences -> Keyboard -> Input Sources' and replace current one with other source, for example, use 'British - PC' instead of 'British' for UK keyboard or vice versa.
If this doesn't resolve your problem search the web for further infos or it is time to configure in your firmware keymap.
TMK firmware supports all of Japnese specific keys; 無変換(muhenkan), 変換(henkan), ひらがな(hiragana), ろ(ro), ￥(yen) and 全角/半角(zenkaku/hankaku). Also Apple Mac keyboard specific keys are supported; 英数(eisuu) and かな(kana). Note that 全角/半角 key is identical to Grave(`~) in US in USB HID spec and TMK firmware.
TMK USB-USB converter translates 英数(eisuu) and かな(kana) into 無変換 and 変換 respectively.
| Key | USB HID Usage |
|---|---|
| 無変換 | MHEN (0x8B) |
| 変換 | HENK (0x8A) |
| ひらがな | KANA (0x88) |
| ろ | RO (0x87) |
| ￥ | JYEN (0x89) |
| 英数(Mac) | MACE (0x91) |
| かな(Mac) | MACJ (0x90) |
This is not trivial and you have to write C code to implement it.
Let's assume that you cannot change keyboard layout on the computer for some reason but you want to use US keyboard(layout).
For example, when you press '[' on your US keyboard you will get 'ü' on the German computer but you want to get '[' here.
To get '[' char on the computer the keyboard(conveter) have to send scan code of 'RAlt + 8'.
This can be done with ACTION_MODS_KEY(MOD_RALT, KC_8) relatively easily. See line 96 and 230.
Also you want to get '{' char when pressing Shift + '[' on your US keyboard. This is more complex.
The converter should send scan code for 'RAlt+9' but it have to cancel Shift before sending the code and restore Shift state after that.
CANCEL_SHIFT_ADD_RALT function is used for that.
See line 146 and 240.
* German(Linux): https://en.wikipedia.org/wiki/German_keyboard_layout#Linux
* Defult: Shift: RAlt: Sihft-RALt:
* ^1234567890ß' °!"§$%&/()=?` ′¹²³¼½¬{[]}\¸ ″¡⅛£¤⅜⅝⅞™±°¿˛
* qwertzuiopü+ QWERTZUIOPÜ* @ł€¶ŧ←↓→øþ"~ ΩŁ€®Ŧ¥↑ıØÞ°¯
* asdfghjklöä# ASDFGHJKLÖÄ' æſðđŋ ħ̣ĸł˝^’ ÆẞЪŊĦ˙&Ł̣ˇ˘˘
* <yxcvbnm,.- >YXCVBNM;:_ |»«¢„“”µ·…– ›‹©‚‘’º×÷—
*
*
* Current impl.:
* Defult: Shift: RAlt:(WIP) Sihft-RALt:(WIP)
* `1234567890-= ~!@#$%^&*()_+ ˛¡²³¤€¼½‘’¥× ¹ £ ÷
* qwertyuiop[]\ QWERTYUIOP{}| @ł€¶ŧ»↓→øþ[]’ ΩŁ€®Ŧ›↑ıØÞ™±`
* asdfghjkl;' ASDFGHJKL:" æſðđŋħ̣ ̣ ĸł˝^ ÆẞЪŊĦ˙&Ł̣ ˇ
* zxcvbnm,./ ZXCVBNM<>? ←«¢„“”µ·…⅞ ¥‹©‚‘’º×÷⅞
*
*
* US intl. with dead key(Linux) for reference:
* Defult: Shift: RAlt: Sihft-RALt:
* `1234567890-= ~!@#$%^&*()_+ `¡²³¤€¼½¾‘’¥× ~¹˝¯£¸^̛ ˛˘°̣ ÷
* qwertyuiop[]\ QWERTYUIOP{}| äåé®þüúíóö«»¬ ÄÅÉ®ÞÜÚÍÓÖ“”¦
* asdfghjkl;' ASDFGHJKL:" áßðfghjœø¶' Á§ÐFGHJŒØ°"
* zxcvbnm,./ ZXCVBNM<>? æx©vbñµç˙¿ ÆX¢VBÑµÇˇ̉
