remove experimental return, cleanup slash_question key
[tmk_keyboard.git] / README.md
CommitLineData
cd3dc90c 1# girst's fork of evangs/tmk_keyboard
2
3This repository contains my keymap for the Minivan (rev2) keyboard. After changing the layout to my pleasing, I've converted the layout to use `actionmaps` to support all my planned features. Then, I merged upstream fixes from `tmk/tmk_keyboard`, because I needed `ba2883f`. The version without merges from upstream is preserved at branch `evangs_firmware`.
4
5```
6Layer 0: Base Layer
7,-------------------------------------------------.
8|Esc| Q| W| E| R| T| Z| U| I| O| P| BSp |
9|-------------------------------------------------|
10|Ctrl| A| S| D| F| G| H| J| K| L| ?/|Fn2 |
11|-------------------------------------------------|
12|Shift| Y| X| C| V| B| N| M| ,| .| -|Sft|
13|-------------------------------------------------|
14|Alt |Tab/Fn2|Fn1 |Enter| Space |Fn1 |Super| Fn3 |
15`-------------------------------------------------'
16
17Layer 1: Movement and Miscellaneous
18,-------------------------------------------------.
19|Esc| |wrd| |End| | |PUp| |Hom|Ins| Del |
20|-------------------------------------------------|
21|Ctrl| | |PDn| | |Lft| Up| Dn| Rt| | |
22|-------------------------------------------------|
23|Shift|PSc| | | |bck| |Pau|NUM|CAP|SCR|Sft|
24|-------------------------------------------------|
25|Alt | | | | | |Super| |
26`-------------------------------------------------'
27
28Layer 2: Numbers and ASCII-Symbols
29,-------------------------------------------------.
30| ^| !| "| '| $| %| &| @| (| )| =| BSp |
31|-------------------------------------------------|
32| `| 1| 2| 3| 4| 5| 6| 7| 8| 9| 0|Fn2 |
33|-------------------------------------------------|
34| #| <| || >| +| *| {| [| ]| }| \| ~|
35|-------------------------------------------------|
36|Alt |Tab/Fn2| | | | |Super| |
37`-------------------------------------------------'
38
39Layer 3: Function Keys and Unicode Symbols
40,-------------------------------------------------.
41| F1| F2| F3| F4| F5| F6| F7| F8| F9|F10|F11| F12|
42|-------------------------------------------------|
43|Ctrl| | | | | | | | Ä| Ö| Ü| |
44|-------------------------------------------------|
45|Shift| €| §| °| ²| ³| µ| ä| ö| ü| ß|Sft|
46|-------------------------------------------------|
47|Alt | | | | | |Super| Fn3 |
48`-------------------------------------------------'
49```
50
78fd5a71 51TMK Keyboard Firmware Collection
52================================
885e7adb 53This repository includes keyboard and converter firmware projects built with [`tmk_core`][tmk_core] keyboard library.
afb08462 54
885e7adb 55The latest source code is available here: <http://github.com/tmk/tmk_keyboard>
afb08462 56
57
799993c4
JW
58Updates
59-------
c0f09090 60#### 2017/01/11
61Changed action code for `ACTION_LAYER_MODS` and this may cause incompatibility with existent shared URL and downloaded firmwware of keymap editor. If you are using the action you just have to redefine it on keymap editor. Existent keymap code should not suffer.
62
1b5266cb 63#### 2016/06/26
64Keymap framework was updated. `fn_actions[]` should be defined as `action_t` instead of `uint16_t`. And default code for keymap handling is now included in core you just need define `uint8_t keymaps[][MATRIX_ROWS][MATRIX_COLS]` and `action_t fn_actions[]`.
65
66
885e7adb 67#### 2016/06/22
68Some projects were moved from `converter` and `keyboard` to `orphan` directory. Those might be removed in some future but you will be able to access them with `orphans` tag. See <https://github.com/tmk/tmk_keyboard/issues/173>
69
5b8e4ca2 70#### 2016/02/10
71core: flabbergast's Chibios protocol was merged from <https://github.com/flabbergast/tmk_keyboard/tree/chibios> (@72b1668). See [tmk_core/protocol/chibios/README.md](tmk_core/protocol/chibios/README.md). Chibios protocol supports Cortex-M such as STM32 and Kinetis.
72
799993c4
JW
73#### 2015/04/22
74Core library was separated to other branch `core`. <https://github.com/tmk/tmk_keyboard/tree/core>
75
76In `Makefile` you need to set `TMK_DIR` to indicate core library location now.
77
78 TMK_DIR = ../../tmk_core
79
80
81
afb08462 82Projects
83--------
083c7581 84You can find some keyboard specific projects under `converter` and `keyboard` directory.
85
afb08462 86### converter
1aa067e5 87* [ps2_usb](converter/ps2_usb/) - [PS/2 keyboard to USB][GH_ps2]
88* [adb_usb](converter/adb_usb/) - [ADB keyboard to USB][GH_adb]
22bd315b 89* [m0110_usb](converter/m0110_usb) - [Macintosh 128K/512K/Plus keyboard to USB][GH_m0110]
1aa067e5 90* [terminal_usb](converter/terminal_usb/) - [IBM Model M terminal keyboard(PS/2 scancode set3) to USB][GH_terminal]
91* [news_usb](converter/news_usb/) - [Sony NEWS keyboard to USB][GH_news]
92* [x68k_usb](converter/x68k_usb/) - [Sharp X68000 keyboard to USB][GH_x68k]
633d9aa5 93* [sun_usb](converter/sun_usb/) - [Sun] to USB(type4, 5 and 3?)
94* [pc98_usb](converter/pc98_usb/) - [PC98] to USB
885e7adb 95* [usb_usb](converter/usb_usb/) - [USB to USB][GH_usb]
96* [ibm4704_usb](converter/ibm4704_usb) - [IBM 4704 keyboard to USB][GH_ibm4704]
97* [next_usb](converter/next_usb) - NeXT(Non-ADB) to USB, contributed by [BCG](https://github.com/bgould) and based on [Adafruit's work](https://learn.adafruit.com/usb-next-keyboard-with-arduino-micro/overview)
afb08462 98
99### keyboard
78fd5a71 100* [hhkb](keyboard/hhkb/) - [Happy Hacking Keyboard pro][GH_hhkb] **my main board**
885e7adb 101* [alps64](keyboard/alps64/) - [Alps64 PCB](https://geekhack.org/index.php?topic=69740.0)
78fd5a71 102* [hbkb](keyboard/hbkb/) - [Happy Buckling spring keyboard][GH_hbkb](IBM Model M 60% mod)
d0fefb76 103* [Infinity](keyboard/infinity/) - Massdrop [Infinity keyboard][Infinity]
885e7adb 104* [gh60](keyboard/gh60/) - [GH60] DIY 60% keyboard [prototype][GH60_proto] **my second board**
105* [onekey](keyboard/onekey/) - Simple one key keyboard example
784c6e39 106
885e7adb 107
108### Projects based tmk_keyboard or tmk_core
109https://github.com/tmk/tmk_keyboard/wiki/TMK-Based-Projects
771347c4 110
111
afb08462 112[GH_hhkb]: http://geekhack.org/showwiki.php?title=Island:12047
113[GH_ps2]: http://geekhack.org/showwiki.php?title=Island:14618
114[GH_adb]: http://geekhack.org/showwiki.php?title=Island:14290
115[GH_hhkb_bt]: http://geekhack.org/showwiki.php?title=Island:20851
116[GH_m0110]: http://geekhack.org/showwiki.php?title=Island:24965
81706d11 117[GH_news]: http://geekhack.org/showwiki.php?title=Island:25759
afb08462 118[GH_terminal]: http://geekhack.org/showwiki.php?title=Island:27272
119[GH_x68k]: http://geekhack.org/showwiki.php?title=Island:29060
81706d11 120[GH_hbkb]: http://geekhack.org/showwiki.php?title=Island:29483
428b2364 121[GH_ibm4704]: http://geekhack.org/index.php?topic=54706.0
74ecdd15 122[GH60]: http://geekhack.org/index.php?topic=34959
78fd5a71 123[GH60_proto]: http://geekhack.org/index.php?topic=37570.0
633d9aa5 124[PC98]: http://en.wikipedia.org/wiki/NEC_PC-9801
125[Sun]: http://en.wikipedia.org/wiki/Sun-3
d0fefb76 126[Infinity]: https://www.massdrop.com/buy/infinity-keyboard-kit
38ab2356 127[tmk_core]: https://github.com/tmk/tmk_core
afb08462 128
129
130
78fd5a71 131License
132-------
133**GPLv2** or later. Some protocol files are under **Modified BSD License**.
1d5bac21
JW
134
135Third party libraries like LUFA, PJRC and V-USB have their own license respectively.
74ecdd15 136
afb08462 137
784c6e39 138
78fd5a71 139Build Firmware and Program Controller
140-------------------------------------
24c30681 141See [tmk_core/doc/build.md](tmk_core/doc/build.md).
afb08462 142
afb08462 143
144
083c7581 145Change your keymap
146------------------
24c30681 147See [tmk_core/doc/keymap.md](tmk_core/doc/keymap.md).
afb08462 148
149
74ecdd15 150
22bd315b 151Magic Commands
74ecdd15 152--------------
153To see help press `Magic` + `H`.
154
885e7adb 155`Magic` key combination is `LShift` + `RShift` in many projects, but `Power` key on ADB converter.
1d5bac21 156`Magic` keybind can be vary on each project, check `config.h` in project directory.
74ecdd15 157
158Following commands can be also executed with `Magic` + key. In console mode `Magic` keybind is not needed.
159
160 ----- Command Help -----
161 c: enter console mode
162 d: toggle debug enable
163 x: toggle matrix debug
164 k: toggle keyboard debug
165 m: toggle mouse debug
74ecdd15 166 v: print device version & info
167 t: print timer count
168 s: print status
4e93b3fa 169 e: print eeprom config
170 n: toggle NKRO
74ecdd15 171 0/F10: switch to Layer0
172 1/F1: switch to Layer1
173 2/F2: switch to Layer2
174 3/F3: switch to Layer3
175 4/F4: switch to Layer4
176 PScr: power down/remote wake-up
177 Caps: Lock Keyboard(Child Proof)
178 Paus: jump to bootloader
179
39d09333 180
799993c4
JW
181
182Boot Magic Configuration - Virtual DIP Switch
183---------------------------------------------
22bd315b 184Boot Magic are executed during boot up time. Press Magic key below then plug in keyboard cable.
4e93b3fa 185Note that you must use keys of **Layer 0** as Magic keys. These settings are stored in EEPROM so that retain your configure over power cycles.
39d09333 186
799993c4 187To avoid configuring accidentally additive salt key `KC_SPACE` also needs to be pressed along with the following configuration keys. The salt key is configurable in `config.h`. See [tmk_core/common/bootmagic.h](tmk_core/common/bootmagic.h).
05225dd9 188
dad9dab9 189#### General
190- Skip reading EEPROM to start with default configuration(`ESC`)
191- Clear configuration stored in EEPROM to reset configuration(`Backspace`)
4e93b3fa 192
193#### Bootloader
8b9bd51d 194- Kick up Bootloader(`B`)
4e93b3fa 195
196#### Debug
8b9bd51d 197- Debug enable(`D`)
4e93b3fa 198- Debug matrix enable(`D`+`X`)
199- Debug keyboard enable(`D`+`K`)
200- Debug mouse enable(`D`+`M`)
201
202#### Keymap
8b9bd51d 203- Swap Control and CapsLock(`Left Control`)
22bd315b 204- Change CapsLock to Control(`Caps Lock`)
8b9bd51d 205- Swap LeftAlt and Gui(`Left Alt`)
206- Swap RightAlt and Gui(`Right Alt`)
207- Disable Gui(`Left Gui`)
208- Swap Grave and Escape(`Grave`)
209- Swap BackSlash and BackSpace(`Back Slash`)
e5bafff7 210- Enable NKRO on boot(`N`)
39d09333 211
4e93b3fa 212#### Default Layer
213- Set Default Layer to 0(`0`)
dad9dab9 214- Set Default Layer to 1(`1`)
215- Set Default Layer to 2(`2`)
216- Set Default Layer to 3(`3`)
9de9d719 217- Set Default Layer to 4(`4`)
218- Set Default Layer to 5(`5`)
219- Set Default Layer to 6(`6`)
220- Set Default Layer to 7(`7`)
221
39d09333 222
74ecdd15 223
27210220 224Mechanical Locking support
225--------------------------
885e7adb 226This feature makes it possible for you to use mechanical locking switch for `CapsLock`, `NumLock`
1d5bac21
JW
227or `ScrollLock`. To enable this feature define these macros in `config.h` and use `KC_LCAP`, `KC_LN
228UM` or `KC_LSCR` in keymap for locking key instead of normal `KC_CAPS`, `KC_NLCK` or `KC_SLCK`. Res
229ync option tries to keep switch state consistent with keyboard LED state.
885e7adb 230
27210220 231 #define LOCKING_SUPPORT_ENABLE
232 #define LOCKING_RESYNC_ENABLE
c0137b4b 233
74ecdd15 234
799993c4 235
74ecdd15 236Start Your Own Project
afb08462 237-----------------------
885e7adb 2381. Add `tmk_core` into your repository using `git submodule` or `git subtree`.
2392. Copy files from `tmk_keybaord` or other project similar to yours
2403. Edit those files to support your keyboard.
241
242See these as examples.
243- https://github.com/tmk/infinity_ergodox
244- https://github.com/tmk/whitefox
78fd5a71 245
246
247
22bd315b 248Debugging
78fd5a71 249--------
885e7adb 250Use PJRC's `hid_listen` to see debug messages. You can use xprintf() to display debug info, see `tmk_core/common/xprintf.h`.
afb08462 251
885e7adb 252- https://www.pjrc.com/teensy/hid_listen.html
78fd5a71 253
254
255
256Files and Directories
74ecdd15 257-------------------
258### Top
74ecdd15 259* keyboard/ - keyboard projects
260* converter/ - protocol converter projects
24c30681 261* tmk_core/ - core library
262* tmk_core/doc/ - documents
afb08462 263
afb08462 264
afb08462 265
885e7adb 266Contribution
267------------
268- Report bugs in github **[Issues](https://github.com/tmk/tmk_keyboard/issues)**.
269- Pull requets are also welcomed.
270
271
272
22bd315b 273Coding Style
de7b46cd 274-------------
275- Doesn't use Tab to indent, use 4-spaces instead.
276
277
278
78fd5a71 279Other Keyboard Firmware Projects
280------------------
d4982a21 281You can learn a lot about keyboard firmware from these. See [Other Projects](https://github.com/tmk/tmk_keyboard/wiki/Other-Projects) other than TMK.
Imprint / Impressum