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