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