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