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