Merge commit '28203e909e83b1ac6becb45a3eadae23b190df32' into master-core-pull
[tmk_keyboard.git] / 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.
Imprint / Impressum