07baa1b6 |
1 | ## READ FIRST |
c4f5db93 |
2 | https://github.com/tmk/tmk_core/blob/master/doc/keymap.md |
07baa1b6 |
3 | |
a94c683a |
4 | ## How to get keycode |
359245bc |
5 | See [Keycodes](Keycodes). Keycodes are actually defined in [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h). |
a94c683a |
6 | |
59c8a733 |
7 | ## Sysrq key |
f27207e8 |
8 | 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'. |
2f44de62 |
9 | |
10 | See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and |
f27207e8 |
11 | - http://en.wikipedia.org/wiki/Magic_SysRq_key |
12 | - http://en.wikipedia.org/wiki/System_request |
59c8a733 |
13 | |
083c7739 |
14 | ## Power key doesn't work |
15 | Use `KC_PWR` instead of `KC_POWER` or vice versa. |
16 | - `KC_PWR` works with Windows and Linux, not with OSX. |
17 | - `KC_POWER` works with OSX and Linux, not with Windows. |
18 | |
19 | http://geekhack.org/index.php?topic=14290.msg1327264#msg1327264 |
20 | |
21 | ## Oneshot modifier |
22 | Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'. Oneshot Shift mitgates this for me. |
23 | https://github.com/tmk/tmk_keyboard/issues/67 |
24 | |
25 | ## Modifier/Layer stuck |
26 | Modifier keys or layers can be stuck unless layer switching is configured properly. |
27 | 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. |
28 | |
c4f5db93 |
29 | - https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching |
6163f0ea |
30 | - http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604 |
31 | - https://github.com/tmk/tmk_keyboard/issues/248 |
083c7739 |
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 | |
4178b005 |
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 | |
f7172ff5 |
45 | ## Input special charactors other than ASCII like Cédille 'Ç' |
cca7b107 |
46 | NO UNIVERSAL METHOD TO INPUT THOSE WORKS OVER ALL SYSTEMS. You have to define **MACRO** in way specific to your OS or layout. |
4178b005 |
47 | |
cca7b107 |
48 | See this post for example **MACRO** code. |
d4437d66 |
49 | |
4178b005 |
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. |
1650d469 |
63 | - http://en.wikipedia.org/wiki/Unicode_input |
64 | |
65 | |
33b55c11 |
66 | ## Apple/Mac keyboard Fn |
1650d469 |
67 | Not supported. |
68 | |
33b55c11 |
69 | Apple/Mac keyboard sends keycode for Fn unlike most of other keyboards. |
8002d8dc |
70 | I think you can send Apple Fn key using Apple venter specific Page 0xff01 and usage 0x0003. But you have to change HID Report Descriptor for this, of course. |
1650d469 |
71 | |
72 | https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/AppleHIDUsageTables.h |
73 | |
74 | |
b321f44f |
75 | ## Media control keys in Mac OSX |
2c22bbda |
76 | #### KC_MNXT and KC_MPRV does not work on Mac |
77 | Use `KC_MFFD`(`KC_MEDIA_FAST_FORWARD`) and `KC_MRWD`(`KC_MEDIA_REWIND`) instead of `KC_MNXT` and `KC_MPRV`. |
78 | See https://github.com/tmk/tmk_keyboard/issues/195 |
b321f44f |
79 | |
5e5aee44 |
80 | |
b321f44f |
81 | ## Keys supported in Mac OSX? |
1650d469 |
82 | You can know which keycodes are supported in OSX from this source code. |
83 | |
84 | `usb_2_adb_keymap` array maps Keyboard/Keypad Page usages to ADB scancodes(OSX internal keycodes). |
85 | |
86 | https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c |
87 | |
88 | And `IOHIDConsumer::dispatchConsumerEvent` handles Consumer page usages. |
89 | |
0eff2b19 |
90 | https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp |
91 | |
92 | |
93 | ## JIS keys in Mac OSX |
2c11165f |
94 | 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. |
0eff2b19 |
95 | |
97619073 |
96 | * Enable NFER Key on PC keyboard |
97 | * Enable XFER Key on PC keyboard |
98 | * Enable KATAKANA Key on PC keyboard |
0eff2b19 |
99 | |
cd71aeb6 |
100 | https://pqrs.org/osx/karabiner/seil.html |
101 | |
102 | |
103 | ## RN-42 Bluetooth doesn't work with Karabiner |
104 | 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. |
105 | https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237 |
106 | |
107 | See these for the deail of this problem. |
108 | https://github.com/tmk/tmk_keyboard/issues/213 |
08f1bde3 |
109 | https://github.com/tekezo/Karabiner/issues/403 |
110 | |
111 | |
112 | ## Esc and `~ on a key |
f7ae7096 |
113 | |
9d25855b |
114 | |
1b0fec88 |
115 | You can define FC660 and Poker style ESC with `ACTION_LAYER_MODS`. |
c4f5db93 |
116 | https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#35-momentary-switching-with-modifiers |
1b0fec88 |
117 | |
118 | ``` |
119 | #include "keymap_common.h" |
120 | |
121 | |
122 | /* Leopold FC660 |
123 | * https://elitekeyboards.com/products.php?sub=leopold,compact&pid=fc660c |
124 | * Shift + Esc = ~ |
125 | * Fn + Esc = ` |
126 | * |
127 | * Votex Poker II |
128 | * https://adprice.fedorapeople.org/poker2_manual.pdf |
129 | * Fn + Esc = ` |
130 | * Fn + Shift + Esc = ~ |
131 | */ |
132 | const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { |
133 | /* 0: qwerty */ |
134 | [0] = KEYMAP( \ |
135 | ESC, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, MINS,EQL, NUHS,BSPC, \ |
136 | TAB, Q, W, E, R, T, Y, U, I, O, P, LBRC,RBRC,BSLS, \ |
137 | LCTL,A, S, D, F, G, H, J, K, L, SCLN,QUOT,ENT, \ |
138 | FN0, NUBS,Z, X, C, V, B, N, M, COMM,DOT, SLSH,RSFT,ESC, \ |
139 | LCTL,LGUI,LALT, SPC, RALT,FN1, RGUI,RCTL), |
140 | [1] = KEYMAP( \ |
141 | GRV, TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \ |
142 | TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\ |
143 | TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \ |
144 | TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \ |
145 | TRNS,TRNS,TRNS, TRNS, TRNS,TRNS,TRNS,TRNS), |
146 | [2] = KEYMAP( \ |
50e0b355 |
147 | GRV, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, TRNS,TRNS, \ |
1b0fec88 |
148 | TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\ |
149 | TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \ |
150 | TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \ |
151 | TRNS,TRNS,TRNS, TRNS, TRNS,TRNS,TRNS,TRNS), |
152 | }; |
153 | |
154 | const uint16_t PROGMEM fn_actions[] = { |
c4f5db93 |
155 | // https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#35-momentary-switching-with-modifiers |
1b0fec88 |
156 | [0] = ACTION_LAYER_MODS(1, MOD_LSFT), |
157 | [1] = ACTION_LAYER_MOMENTARY(2), |
158 | }; |
159 | ``` |
9d25855b |
160 | |
f7ae7096 |
161 | Otherwise, you can write code, see this. |
162 | https://github.com/p3lim/keyboard_firmware/commit/fd799c12b69a5ab5addd1d4c03380a1b8ef8e9dc |
163 | |
164 | |
9d25855b |
165 | ## 32 Fn keys are not enough? |
166 | ### actionmap |
7328ba0f |
167 | 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. |
9d25855b |
168 | https://github.com/tmk/tmk_keyboard/issues?utf8=%E2%9C%93&q=is%3Aissue+actionmap |
169 | |
170 | ### extension for modified keys |
eeaef60f |
171 | https://geekhack.org/index.php?topic=41989.msg1885526#msg1885526 |
172 | |
173 | |
174 | ## Arrow on Right Modifier keys with Dual-Role |
175 | 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**. |
176 | ``` |
177 | #include "keymap_common.h" |
178 | |
179 | |
180 | /* Arrow keys on right modifier keys with TMK dual role feature |
181 | * |
c4f5db93 |
182 | * https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role |
eeaef60f |
183 | * https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys |
184 | */ |
185 | const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { |
186 | /* 0: qwerty */ |
187 | [0] = KEYMAP( \ |
188 | ESC, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, MINS,EQL, NUHS,BSPC, \ |
189 | TAB, Q, W, E, R, T, Y, U, I, O, P, LBRC,RBRC,BSLS, \ |
190 | LCTL,A, S, D, F, G, H, J, K, L, SCLN,QUOT,ENT, \ |
191 | LSFT,NUBS,Z, X, C, V, B, N, M, COMM,DOT, SLSH,FN0, ESC, \ |
192 | FN4, LGUI,LALT, SPC, APP, FN2, FN1, FN3), |
193 | [1] = KEYMAP( \ |
194 | GRV, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, TRNS,TRNS, \ |
195 | TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\ |
196 | TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \ |
197 | TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,FN5, TRNS, \ |
198 | TRNS,TRNS,TRNS, TRNS, TRNS,FN7, FN6, FN8), |
199 | }; |
200 | |
201 | const uint16_t PROGMEM fn_actions[] = { |
202 | [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP), |
203 | [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN), |
204 | [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT), |
205 | [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT), |
206 | [4] = ACTION_LAYER_MOMENTARY(1), |
207 | [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP), |
208 | [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN), |
209 | [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME), |
210 | [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END), |
211 | }; |
212 | |
213 | ``` |
214 | |
215 | |
ee732d77 |
216 | Dual-role key: https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys |
217 | |
218 | |
219 | ## Eject on Mac OSX |
483de131 |
220 | `EJCT` keycode works on OSX. https://github.com/tmk/tmk_keyboard/issues/250 |
c38bac48 |
221 | It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default. |
483de131 |
222 | |
4e917015 |
223 | 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. |
224 | |
225 | |
226 | |
227 | ## What's weak_mods and real_mods in action_util.c |
228 | ___TO BE IMPROVED___ |
229 | |
230 | real_mods is intended to retains state of real/physical modifier key state, while |
231 | weak_mods retains state of virtual or temprary modifiers which should not affect state real modifier key. |
232 | |
233 | Let's say you hold down physical left shift key and type ACTION_MODS_KEY(LSHIFT, KC_A), |
234 | |
235 | with weak_mods, |
bf88dfa5 |
236 | * (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT) |
237 | * (2) press ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT) |
238 | * (3) release ACTION_MODS_KEY(LSHIFT, KC_A): waek_mods &= ~MOD_BIT(LSHIFT) |
4e917015 |
239 | real_mods still keeps modifier state. |
240 | |
241 | without weak mods, |
bf88dfa5 |
242 | * (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT) |
243 | * (2) press ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT) |
244 | * (3) release ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT) |
4e917015 |
245 | here real_mods lost state for 'physical left shift'. |
246 | |
247 | weak_mods is ORed with real_mods when keyboard report is sent. |
359245bc |
248 | https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57 |