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.