usb_usb: Add Makefiles
[tmk_keyboard.git] / README.md
1 TMK Keyboard Firmware Collection
2 ================================
3 This repository includes keyboard and converter firmware projects built with [`tmk_core`][tmk_core] keyboard library.
4
5 The latest source code is available here: <http://github.com/tmk/tmk_keyboard>
6
7
8 Updates
9 -------
10 #### 2017/01/11
11 Changed 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
13 #### 2016/06/26
14 Keymap 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
17 #### 2016/06/22
18 Some 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
20 #### 2016/02/10
21 core: 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
23 #### 2015/04/22
24 Core library was separated to other branch `core`. <https://github.com/tmk/tmk_keyboard/tree/core>
25
26 In `Makefile` you need to set `TMK_DIR` to indicate core library location now.
27
28 TMK_DIR = ../../tmk_core
29
30
31
32 Projects
33 --------
34 You can find some keyboard specific projects under `converter` and `keyboard` directory.
35
36 ### converter
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]
39 * [m0110_usb](converter/m0110_usb) - [Macintosh 128K/512K/Plus keyboard to USB][GH_m0110]
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]
43 * [sun_usb](converter/sun_usb/) - [Sun] to USB(type4, 5 and 3?)
44 * [pc98_usb](converter/pc98_usb/) - [PC98] to USB
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)
48
49 ### keyboard
50 * [hhkb](keyboard/hhkb/) - [Happy Hacking Keyboard pro][GH_hhkb] **my main board**
51 * [alps64](keyboard/alps64/) - [Alps64 PCB](https://geekhack.org/index.php?topic=69740.0)
52 * [hbkb](keyboard/hbkb/) - [Happy Buckling spring keyboard][GH_hbkb](IBM Model M 60% mod)
53 * [Infinity](keyboard/infinity/) - Massdrop [Infinity keyboard][Infinity]
54 * [gh60](keyboard/gh60/) - [GH60] DIY 60% keyboard [prototype][GH60_proto] **my second board**
55 * [onekey](keyboard/onekey/) - Simple one key keyboard example
56
57
58 ### Projects based tmk_keyboard or tmk_core
59 https://github.com/tmk/tmk_keyboard/wiki/TMK-Based-Projects
60
61
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
67 [GH_news]: http://geekhack.org/showwiki.php?title=Island:25759
68 [GH_terminal]: http://geekhack.org/showwiki.php?title=Island:27272
69 [GH_x68k]: http://geekhack.org/showwiki.php?title=Island:29060
70 [GH_hbkb]: http://geekhack.org/showwiki.php?title=Island:29483
71 [GH_ibm4704]: http://geekhack.org/index.php?topic=54706.0
72 [GH60]: http://geekhack.org/index.php?topic=34959
73 [GH60_proto]: http://geekhack.org/index.php?topic=37570.0
74 [PC98]: http://en.wikipedia.org/wiki/NEC_PC-9801
75 [Sun]: http://en.wikipedia.org/wiki/Sun-3
76 [Infinity]: https://www.massdrop.com/buy/infinity-keyboard-kit
77 [tmk_core]: https://github.com/tmk/tmk_core
78
79
80
81 License
82 -------
83 **GPLv2** or later. Some protocol files are under **Modified BSD License**.
84
85 Third party libraries like LUFA, PJRC and V-USB have their own license respectively.
86
87
88
89 Build Firmware and Program Controller
90 -------------------------------------
91 See [tmk_core/doc/build.md](tmk_core/doc/build.md).
92
93
94
95 Change your keymap
96 ------------------
97 See [tmk_core/doc/keymap.md](tmk_core/doc/keymap.md).
98
99
100
101 Magic Commands
102 --------------
103 To see help press `Magic` + `H`.
104
105 `Magic` key combination is `LShift` + `RShift` in many projects, but `Power` key on ADB converter.
106 `Magic` keybind can be vary on each project, check `config.h` in project directory.
107
108 Following 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
116 v: print device version & info
117 t: print timer count
118 s: print status
119 e: print eeprom config
120 n: toggle NKRO
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
130
131
132 Boot Magic Configuration - Virtual DIP Switch
133 ---------------------------------------------
134 Boot Magic are executed during boot up time. Press Magic key below then plug in keyboard cable.
135 Note 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.
136
137 To 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).
138
139 #### General
140 - Skip reading EEPROM to start with default configuration(`ESC`)
141 - Clear configuration stored in EEPROM to reset configuration(`Backspace`)
142
143 #### Bootloader
144 - Kick up Bootloader(`B`)
145
146 #### Debug
147 - Debug enable(`D`)
148 - Debug matrix enable(`D`+`X`)
149 - Debug keyboard enable(`D`+`K`)
150 - Debug mouse enable(`D`+`M`)
151
152 #### Keymap
153 - Swap Control and CapsLock(`Left Control`)
154 - Change CapsLock to Control(`Caps Lock`)
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`)
160 - Enable NKRO on boot(`N`)
161
162 #### Default Layer
163 - Set Default Layer to 0(`0`)
164 - Set Default Layer to 1(`1`)
165 - Set Default Layer to 2(`2`)
166 - Set Default Layer to 3(`3`)
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
172
173
174 Mechanical Locking support
175 --------------------------
176 This feature makes it possible for you to use mechanical locking switch for `CapsLock`, `NumLock`
177 or `ScrollLock`. To enable this feature define these macros in `config.h` and use `KC_LCAP`, `KC_LN
178 UM` or `KC_LSCR` in keymap for locking key instead of normal `KC_CAPS`, `KC_NLCK` or `KC_SLCK`. Res
179 ync option tries to keep switch state consistent with keyboard LED state.
180
181 #define LOCKING_SUPPORT_ENABLE
182 #define LOCKING_RESYNC_ENABLE
183
184
185
186 Start Your Own Project
187 -----------------------
188 1. Add `tmk_core` into your repository using `git submodule` or `git subtree`.
189 2. Copy files from `tmk_keybaord` or other project similar to yours
190 3. Edit those files to support your keyboard.
191
192 See these as examples.
193 - https://github.com/tmk/infinity_ergodox
194 - https://github.com/tmk/whitefox
195
196
197
198 Debugging
199 --------
200 Use PJRC's `hid_listen` to see debug messages. You can use xprintf() to display debug info, see `tmk_core/common/xprintf.h`.
201
202 - https://www.pjrc.com/teensy/hid_listen.html
203
204
205
206 Files and Directories
207 -------------------
208 ### Top
209 * keyboard/ - keyboard projects
210 * converter/ - protocol converter projects
211 * tmk_core/ - core library
212 * tmk_core/doc/ - documents
213
214
215
216 Contribution
217 ------------
218 - Report bugs in github **[Issues](https://github.com/tmk/tmk_keyboard/issues)**.
219 - Pull requets are also welcomed.
220
221
222
223 Coding Style
224 -------------
225 - Doesn't use Tab to indent, use 4-spaces instead.
226
227
228
229 Other Keyboard Firmware Projects
230 ------------------
231 You 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