tmk_core/README.md

   1 TMK Keyboard Firmware Core Library
   2 ==================================
   3 This is a keyboard firmware library with some useful features for Atmel AVR and Cortex-M.
   4
   5 Source code is available here: <https://github.com/tmk/tmk_keyboard/tree/core>
   6
   7
   8 Updates
   9 -------
  10 #### 2017/05/30
  11 Fixed **Modifier/Layer key stuck** problem. See this wiki entry. <https://github.com/tmk/tmk_keyboard/wiki/FAQ-Keymap#modifierlayer-stuck> If you need old keymap behaviour for some reason define `NO_TRACK_KEY_PRESS` in your `config.h`.
  12
  13 This is virtually equivalent to QMK `PREVENT_STUCK_MODIFIERS`. <https://github.com/qmk/qmk_firmware/pull/182>
  14
  15 #### 2017/01/11
  16 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.
  17
  18 #### 2016/06/26
  19 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[]`.
  20
  21 #### 2016/02/10
  22 flabbergast's Chibios protocol was merged from <https://github.com/flabbergast/tmk_keyboard/tree/chibios>. See [protocol/chibios/README.md](protocol/chibios/README.md). Chibios protocol supports Cortex-M such as STM32 and Kinetis.
  23
  24 #### 2015/04/22
  25 separated with TMK Keyboard Firmware Collection
  26
  27
  28
  29 Features
  30 --------
  31 These features can be used in your keyboard.
  32
  33 * Multi-layer Keymap  - Multiple keyboard layouts with layer switching
  34 * Mouse key           - Mouse control with keyboard
  35 * System Control Key  - Power Down, Sleep, Wake Up and USB Remote Wake up
  36 * Media Control Key   - Volume Down/Up, Mute, Next/Prev track, Play, Stop and etc
  37 * USB NKRO            - 120 keys(+ 8 modifiers) simultaneously
  38 * PS/2 mouse support  - PS/2 mouse(TrackPoint) as composite device
  39 * Keyboard protocols  - PS/2, ADB, M0110, Sun and other old keyboard protocols
  40 * User Function       - Customizable function of key with writing code
  41 * Macro               - Very primitive at this time
  42 * Keyboard Tricks     - Oneshot modifier and modifier with tapping feature
  43 * Debug Console       - Messages for debug and interaction with firmware
  44 * Virtual DIP Switch  - Configurations stored EEPROM(Boot Magic)
  45 * Locking CapsLock    - Mechanical switch support for CapsLock
  46 * Breathing Sleep LED - Sleep indicator with charm during USB suspend
  47 * Backlight           - Control backlight levels
  48
  49
  50
  51 TMK Keyboard Firmware Collection
  52 --------------------------------
  53 Complete firmwares for various keyboards and protocol converters.
  54
  55 <https://github.com/tmk/tmk_keyboard>
  56
  57
  58
  59 License
  60 -------
  61 **GPLv2** or later. Some protocol files are under **Modified BSD License**.
  62 LUFA, PJRC and V-USB stack have their own license respectively.
  63
  64
  65
  66 Build Firmware and Program Controller
  67 -------------------------------------
  68 See [doc/build.md](doc/build.md).
  69
  70
  71
  72 Start Your Own Project
  73 -----------------------
  74 **TBD**
  75 ### Config.h Options
  76 #### 1. USB vendor/product ID and device description
  77     #define VENDOR_ID       0xFEED
  78     #define PRODUCT_ID      0xBEEF
  79     #define MANUFACTURER    t.m.k.
  80     #define PRODUCT         Macway mod
  81     #define DESCRIPTION     t.m.k. keyboard firmware for Macway mod
  82
  83 #### 2. Keyboard matrix configuration
  84     #define MATRIX_ROWS 8
  85     #define MATRIX_COLS 8
  86     #define MATRIX_HAS_GHOST
  87
  88
  89
  90 Architecture
  91 ------------
  92     Architecture Diagram
  93                                +---------------+---------------+-------------+
  94                                |    Host       |   Keyboard    | Matrix, LED |
  95        ___________             |-----------+-+ +-------------+ | +-----------|
  96       /          /| Keys/Mouse | Protocol  |d| | Action      | | | Protocol  |
  97      /__________/ |<-----------|  LUFA     |r| |  Layer, Tap | | |  Matrix   |
  98      |.--------.| |   LED      |  V-USB    |i| |-------------| | |  PS/2,IBM |             __________________
  99      ||        || |----------->|  PJRC     |v| | Keymap      | | |  ADB,M0110|  Keys      / /_/_/_/_/_/_/_/ /|
 100      ||  Host  || |  Console   |  iWRAP(BT)|e| | Mousekey    | | |  SUN/NEWS |<----------/ /_/_/_/_/_/_/_/ / /
 101      ||________||/.<-----------|  UART     |r| | Report      | | |  X68K/PC98| Control  / /_/_/_/_/_/_/_/ / /
 102      `_========_'/|            |---------------------------------------------|-------->/___ /_______/ ___/ /
 103      |_o______o_|/             | Sendchar, Print, Debug, Command, ...        |         |_________________|/
 104                                +---------------------------------------------+              Keyboard
 105
 106
 107
 108 Debugging
 109 --------
 110 Use PJRC's `hid_listen` to see debug messages. You can use the tool for debug even if firmware use LUFA stack.
 111
 112 You can use xprintf() to display debug info on `hid_listen`, see `common/xprintf.h`.
 113
 114
 115
 116 Files and Directories
 117 -------------------
 118 ### Top
 119 * common/       - common codes
 120 * protocol/     - keyboard protocol support
 121 * doc/          - documents
 122 * common.mk     - Makefile for common
 123 * protocol.mk    - Makefile for protocol
 124 * rules.mk      - Makefile for build rules
 125
 126 ### Common
 127 * host.h
 128 * host_driver.h
 129 * keyboard.h
 130 * command.h
 131 * keymap.h
 132 * action.h
 133 * keycode.h
 134 * matrix.h
 135 * led.h
 136 * mousekey.h
 137 * report.h
 138 * debug.h
 139 * print.h
 140 * bootloader.h
 141 * sendchar.h
 142 * timer.h
 143 * util.h
 144
 145 ### Keyboard Protocols
 146 * lufa/     - LUFA USB stack
 147 * pjrc/     - PJRC USB stack
 148 * vusb/     - Objective Development V-USB
 149 * iwrap/    - Bluetooth HID for Bluegiga iWRAP
 150 * ps2.c     - PS/2 protocol
 151 * adb.c     - Apple Desktop Bus protocol
 152 * m0110.c   - Macintosh 128K/512K/Plus keyboard protocol
 153 * news.c    - Sony NEWS keyboard protocol
 154 * x68k.c    - Sharp X68000 keyboard protocol
 155 * serial_soft.c - Asynchronous Serial protocol implemented by software
 156
 157
 158
 159 Coding Style
 160 -------------
 161 - Doesn't use Tab to indent, use 4-spaces instead.