usb_usb: Update binary
[tmk_keyboard.git] / README.md
CommitLineData
78fd5a71 1TMK Keyboard Firmware Collection
2================================
885e7adb 3This repository includes keyboard and converter firmware projects built with [`tmk_core`][tmk_core] keyboard library.
afb08462 4
885e7adb 5The latest source code is available here: <http://github.com/tmk/tmk_keyboard>
afb08462 6
7
799993c4
JW
8Updates
9-------
c0f09090 10#### 2017/01/11
11Changed 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.
12
1b5266cb 13#### 2016/06/26
14Keymap 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[]`.
15
16
885e7adb 17#### 2016/06/22
18Some 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>
19
5b8e4ca2 20#### 2016/02/10
21core: 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.
22
799993c4
JW
23#### 2015/04/22
24Core library was separated to other branch `core`. <https://github.com/tmk/tmk_keyboard/tree/core>
25
26In `Makefile` you need to set `TMK_DIR` to indicate core library location now.
27
28 TMK_DIR = ../../tmk_core
29
30
31
afb08462 32Projects
33--------
083c7581 34You can find some keyboard specific projects under `converter` and `keyboard` directory.
35
afb08462 36### converter
1aa067e5 37* [ps2_usb](converter/ps2_usb/) - [PS/2 keyboard to USB][GH_ps2]
38* [adb_usb](converter/adb_usb/) - [ADB keyboard to USB][GH_adb]
22bd315b 39* [m0110_usb](converter/m0110_usb) - [Macintosh 128K/512K/Plus keyboard to USB][GH_m0110]
1aa067e5 40* [terminal_usb](converter/terminal_usb/) - [IBM Model M terminal keyboard(PS/2 scancode set3) to USB][GH_terminal]
41* [news_usb](converter/news_usb/) - [Sony NEWS keyboard to USB][GH_news]
42* [x68k_usb](converter/x68k_usb/) - [Sharp X68000 keyboard to USB][GH_x68k]
633d9aa5 43* [sun_usb](converter/sun_usb/) - [Sun] to USB(type4, 5 and 3?)
44* [pc98_usb](converter/pc98_usb/) - [PC98] to USB
885e7adb 45* [usb_usb](converter/usb_usb/) - [USB to USB][GH_usb]
46* [ibm4704_usb](converter/ibm4704_usb) - [IBM 4704 keyboard to USB][GH_ibm4704]
47* [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 48
49### keyboard
78fd5a71 50* [hhkb](keyboard/hhkb/) - [Happy Hacking Keyboard pro][GH_hhkb] **my main board**
885e7adb 51* [alps64](keyboard/alps64/) - [Alps64 PCB](https://geekhack.org/index.php?topic=69740.0)
78fd5a71 52* [hbkb](keyboard/hbkb/) - [Happy Buckling spring keyboard][GH_hbkb](IBM Model M 60% mod)
d0fefb76 53* [Infinity](keyboard/infinity/) - Massdrop [Infinity keyboard][Infinity]
885e7adb 54* [gh60](keyboard/gh60/) - [GH60] DIY 60% keyboard [prototype][GH60_proto] **my second board**
55* [onekey](keyboard/onekey/) - Simple one key keyboard example
784c6e39 56
885e7adb 57
58### Projects based tmk_keyboard or tmk_core
59https://github.com/tmk/tmk_keyboard/wiki/TMK-Based-Projects
771347c4 60
61
afb08462 62[GH_hhkb]: http://geekhack.org/showwiki.php?title=Island:12047
63[GH_ps2]: http://geekhack.org/showwiki.php?title=Island:14618
64[GH_adb]: http://geekhack.org/showwiki.php?title=Island:14290
65[GH_hhkb_bt]: http://geekhack.org/showwiki.php?title=Island:20851
66[GH_m0110]: http://geekhack.org/showwiki.php?title=Island:24965
81706d11 67[GH_news]: http://geekhack.org/showwiki.php?title=Island:25759
afb08462 68[GH_terminal]: http://geekhack.org/showwiki.php?title=Island:27272
69[GH_x68k]: http://geekhack.org/showwiki.php?title=Island:29060
81706d11 70[GH_hbkb]: http://geekhack.org/showwiki.php?title=Island:29483
428b2364 71[GH_ibm4704]: http://geekhack.org/index.php?topic=54706.0
74ecdd15 72[GH60]: http://geekhack.org/index.php?topic=34959
78fd5a71 73[GH60_proto]: http://geekhack.org/index.php?topic=37570.0
633d9aa5 74[PC98]: http://en.wikipedia.org/wiki/NEC_PC-9801
75[Sun]: http://en.wikipedia.org/wiki/Sun-3
d0fefb76 76[Infinity]: https://www.massdrop.com/buy/infinity-keyboard-kit
38ab2356 77[tmk_core]: https://github.com/tmk/tmk_core
afb08462 78
79
80
78fd5a71 81License
82-------
83**GPLv2** or later. Some protocol files are under **Modified BSD License**.
1d5bac21
JW
84
85Third party libraries like LUFA, PJRC and V-USB have their own license respectively.
74ecdd15 86
afb08462 87
784c6e39 88
78fd5a71 89Build Firmware and Program Controller
90-------------------------------------
24c30681 91See [tmk_core/doc/build.md](tmk_core/doc/build.md).
afb08462 92
afb08462 93
94
083c7581 95Change your keymap
96------------------
24c30681 97See [tmk_core/doc/keymap.md](tmk_core/doc/keymap.md).
afb08462 98
99
74ecdd15 100
22bd315b 101Magic Commands
74ecdd15 102--------------
103To see help press `Magic` + `H`.
104
885e7adb 105`Magic` key combination is `LShift` + `RShift` in many projects, but `Power` key on ADB converter.
1d5bac21 106`Magic` keybind can be vary on each project, check `config.h` in project directory.
74ecdd15 107
108Following commands can be also executed with `Magic` + key. In console mode `Magic` keybind is not needed.
109
110 ----- Command Help -----
111 c: enter console mode
112 d: toggle debug enable
113 x: toggle matrix debug
114 k: toggle keyboard debug
115 m: toggle mouse debug
74ecdd15 116 v: print device version & info
117 t: print timer count
118 s: print status
4e93b3fa 119 e: print eeprom config
120 n: toggle NKRO
74ecdd15 121 0/F10: switch to Layer0
122 1/F1: switch to Layer1
123 2/F2: switch to Layer2
124 3/F3: switch to Layer3
125 4/F4: switch to Layer4
126 PScr: power down/remote wake-up
127 Caps: Lock Keyboard(Child Proof)
128 Paus: jump to bootloader
129
39d09333 130
799993c4
JW
131
132Boot Magic Configuration - Virtual DIP Switch
133---------------------------------------------
22bd315b 134Boot Magic are executed during boot up time. Press Magic key below then plug in keyboard cable.
4e93b3fa 135Note 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 136
799993c4 137To 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 138
dad9dab9 139#### General
140- Skip reading EEPROM to start with default configuration(`ESC`)
141- Clear configuration stored in EEPROM to reset configuration(`Backspace`)
4e93b3fa 142
143#### Bootloader
8b9bd51d 144- Kick up Bootloader(`B`)
4e93b3fa 145
146#### Debug
8b9bd51d 147- Debug enable(`D`)
4e93b3fa 148- Debug matrix enable(`D`+`X`)
149- Debug keyboard enable(`D`+`K`)
150- Debug mouse enable(`D`+`M`)
151
152#### Keymap
8b9bd51d 153- Swap Control and CapsLock(`Left Control`)
22bd315b 154- Change CapsLock to Control(`Caps Lock`)
8b9bd51d 155- Swap LeftAlt and Gui(`Left Alt`)
156- Swap RightAlt and Gui(`Right Alt`)
157- Disable Gui(`Left Gui`)
158- Swap Grave and Escape(`Grave`)
159- Swap BackSlash and BackSpace(`Back Slash`)
e5bafff7 160- Enable NKRO on boot(`N`)
39d09333 161
4e93b3fa 162#### Default Layer
163- Set Default Layer to 0(`0`)
dad9dab9 164- Set Default Layer to 1(`1`)
165- Set Default Layer to 2(`2`)
166- Set Default Layer to 3(`3`)
9de9d719 167- Set Default Layer to 4(`4`)
168- Set Default Layer to 5(`5`)
169- Set Default Layer to 6(`6`)
170- Set Default Layer to 7(`7`)
171
39d09333 172
74ecdd15 173
27210220 174Mechanical Locking support
175--------------------------
885e7adb 176This feature makes it possible for you to use mechanical locking switch for `CapsLock`, `NumLock`
1d5bac21
JW
177or `ScrollLock`. To enable this feature define these macros in `config.h` and use `KC_LCAP`, `KC_LN
178UM` or `KC_LSCR` in keymap for locking key instead of normal `KC_CAPS`, `KC_NLCK` or `KC_SLCK`. Res
179ync option tries to keep switch state consistent with keyboard LED state.
885e7adb 180
27210220 181 #define LOCKING_SUPPORT_ENABLE
182 #define LOCKING_RESYNC_ENABLE
c0137b4b 183
74ecdd15 184
799993c4 185
74ecdd15 186Start Your Own Project
afb08462 187-----------------------
885e7adb 1881. Add `tmk_core` into your repository using `git submodule` or `git subtree`.
1892. Copy files from `tmk_keybaord` or other project similar to yours
1903. Edit those files to support your keyboard.
191
192See these as examples.
193- https://github.com/tmk/infinity_ergodox
194- https://github.com/tmk/whitefox
78fd5a71 195
196
197
22bd315b 198Debugging
78fd5a71 199--------
885e7adb 200Use PJRC's `hid_listen` to see debug messages. You can use xprintf() to display debug info, see `tmk_core/common/xprintf.h`.
afb08462 201
885e7adb 202- https://www.pjrc.com/teensy/hid_listen.html
78fd5a71 203
204
205
206Files and Directories
74ecdd15 207-------------------
208### Top
74ecdd15 209* keyboard/ - keyboard projects
210* converter/ - protocol converter projects
24c30681 211* tmk_core/ - core library
212* tmk_core/doc/ - documents
afb08462 213
afb08462 214
afb08462 215
885e7adb 216Contribution
217------------
218- Report bugs in github **[Issues](https://github.com/tmk/tmk_keyboard/issues)**.
219- Pull requets are also welcomed.
220
221
222
22bd315b 223Coding Style
de7b46cd 224-------------
225- Doesn't use Tab to indent, use 4-spaces instead.
226
227
228
78fd5a71 229Other Keyboard Firmware Projects
230------------------
d4982a21 231You 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