Merge branch 'action_tapping'
[tmk_keyboard.git] / README.md
CommitLineData
afb08462 1t.m.k. Keyboard Firmware Collection
2====================================
3This is a keyboard firmware with some features for Atmel AVR controller.
4
5Source code is available here: <http://github.com/tmk/tmk_keyboard>
6
7
8Features
9--------
633d9aa5 10* Multi-layer Keymap - Multiple keyboard layouts with layer switching
74ecdd15 11* Mouse key - Mouse control with keyboard
12* System Control Key - Power Down, Sleep, Wake Up and USB Remote Wake up
13* Media Control Key - Volume Down/Up, Mute, Next/Prev track, Play, Stop and etc
14* USB NKRO - 120 keys(+ 8 modifiers) simultaneously
15* PS/2 mouse support - PS/2 mouse(TrackPoint) as composite device
16* Keyboard protocols - PS/2, ADB, M0110, Sun and other old keyboard protocols
17* User Function - Customizable function of key with writing code
18* Macro - Very primitive at this time
19* Keyboard Tricks - Oneshot modifier and modifier with tapping feature
20* Debug Console - Messages for debug and interaction with firmware
8b9bd51d 21* Virtual DIP Switch - Configurations stored EEPROM(Boot Magic)
c0137b4b 22* Locking CapsLock - Mechanical switch support for CapsLock
0142e20b 23* Breathing Sleep LED - Sleep indicator with charm during USB suspend
afb08462 24
25
26Projects
27--------
083c7581 28You can find some keyboard specific projects under `converter` and `keyboard` directory.
29
afb08462 30### converter
1aa067e5 31* [ps2_usb](converter/ps2_usb/) - [PS/2 keyboard to USB][GH_ps2]
32* [adb_usb](converter/adb_usb/) - [ADB keyboard to USB][GH_adb]
33* [m0110_usb](converter/m0110_usb) - [Machintosh 128K/512K/Plus keyboard to USB][GH_m0110]
34* [terminal_usb](converter/terminal_usb/) - [IBM Model M terminal keyboard(PS/2 scancode set3) to USB][GH_terminal]
35* [news_usb](converter/news_usb/) - [Sony NEWS keyboard to USB][GH_news]
36* [x68k_usb](converter/x68k_usb/) - [Sharp X68000 keyboard to USB][GH_x68k]
633d9aa5 37* [sun_usb](converter/sun_usb/) - [Sun] to USB(type4, 5 and 3?)
38* [pc98_usb](converter/pc98_usb/) - [PC98] to USB
1aa067e5 39* [usb_usb](converter/usb_usb/) - USB to USB(experimental)
afb08462 40
41### keyboard
1aa067e5 42* [hhkb](keyboard/hhkb/) - [Happy Hacking Keyboard professional][GH_hhkb]
43* [macway](keyboard/macway/) - [Compact keyboard mod][GH_macway]
44* [hbkb](keyboard/hbkb/) - [Happy Buckling sprint keyboard(IBM Model M mod)][GH_hbkb]
5808317b 45* [IIgs_Standard](keyboard/IIgs/) - Apple [IIGS] keyboard mod(by JeffreySung)
1aa067e5 46* [hid_liber](keyboard/hid_liber/) - [HID liberation controller][HID_liber](by alaricljs)
47* [phantom](keyboard/phantom/) - [Phantom keyboard][PHANTOM] (by Tranquilite)
48* [gh60](keyboard/gh60/) - [GH60 keyboard][GH60]
784c6e39 49
afb08462 50[GH_macway]: http://geekhack.org/showwiki.php?title=Island:11930
51[GH_hhkb]: http://geekhack.org/showwiki.php?title=Island:12047
52[GH_ps2]: http://geekhack.org/showwiki.php?title=Island:14618
53[GH_adb]: http://geekhack.org/showwiki.php?title=Island:14290
54[GH_hhkb_bt]: http://geekhack.org/showwiki.php?title=Island:20851
55[GH_m0110]: http://geekhack.org/showwiki.php?title=Island:24965
81706d11 56[GH_news]: http://geekhack.org/showwiki.php?title=Island:25759
afb08462 57[GH_terminal]: http://geekhack.org/showwiki.php?title=Island:27272
58[GH_x68k]: http://geekhack.org/showwiki.php?title=Island:29060
81706d11 59[GH_hbkb]: http://geekhack.org/showwiki.php?title=Island:29483
74ecdd15 60[HID_liber]: http://deskthority.net/wiki/HID_Liberation_Device_-_DIY_Instructions
61[PHANTOM]: http://geekhack.org/index.php?topic=26742
62[GH60]: http://geekhack.org/index.php?topic=34959
633d9aa5 63[PC98]: http://en.wikipedia.org/wiki/NEC_PC-9801
64[Sun]: http://en.wikipedia.org/wiki/Sun-3
65[IIGS]: http://en.wikipedia.org/wiki/Apple_IIGS
afb08462 66
67
68
74ecdd15 69Build & Program
70---------------
71### Install Tools
72First, you need tools to build firmware and program your controller. I assume you are on Windows here.
afb08462 73
74ecdd15 741. Install [WinAVR][winavr]. This is old but works well for this purpose. `WinAVR` is a tool set to build firmware including C compiler(gcc) and make commands. You can use [CrossPack][crosspack] instead if you are on Mac.
75
762. Install [Atmel FLIP][flip]. `FLIP` is a tool to program(load) firmware into AVR controller(ATMega32u4) via DFU bootloader. ATMega32u4 has DFU bootloader by factory default. You can use [dfu-programmer][dfu-prog] instead if you are on Mac.
77
783. Install driver for DFU bootloader. At first time you start DFU bootloader on Chip 'Found New Hardware Wizard' will come up on Windows. If you install device driver properly you can find chip name like 'ATmega32U4' under 'LibUSB-Win32 Devices' tree on 'Device Manager'. If not you shall need to update its driver on 'Device Manager'. You will find the driver in `FLIP` install directory like: C:\Program Files (x86)\Atmel\Flip 3.4.5\usb\. If you use `dfu-programmer` install its driver.
79
80If you use PJRC Teensy you don't need step 2 and 3, just get [Teensy loader][teensy-loader].
81
82
83### Download source
84You can find firmware source at github: https://github.com/tmk/tmk_keyboard
85
86If you are familiar with `Git` tools you are recommended to use it.
87If not you can download zip archive from: https://github.com/tmk/tmk_keyboard/archive/master.zip
afb08462 88
89
afb08462 90### Build firmware
74ecdd15 911. Open terminal window to get access to commands. You can use `cmd` in Windows or `Terminal.app` on Mac OSX. In Windows press `Windows` key and `R` then enter `cmd` in Run command dialog showing up.
92
932. Move to project directory in the firmware source.
94
95 cd tmk_keyboard/{keyboard or converter}/<project>
96
973. Build firmware using GNU `make` command. You'll see <project>_<variant>.hex file in that directory unless something unexpected occurs in build process.
98
99 mkae -f Makefile.<variant> clean
100 make -f Makefile.<variant>
afb08462 101
afb08462 102
afb08462 103
afb08462 104
105### Program Controller
74ecdd15 106Sock AVR USB chip including ATmega32U4 has DFU bootloader by factory default, you can use DFU tools for this purpose. `FLIP` is a DFU tool on Windows offered by Atmel. Open source command line DFU tool `dfu-programmer` also supports AVR chips, which run on Linux, Mac OSX and even Windows. If you have a PJRC Teensy you should use `Teensy Loader`.
107
108#### DFU bootloader
109To program AVR chip with DFU bootloader use `FLIP` or `dfu-programmer`.
784c6e39 110If you have a proper program command in `Makefile` just type this.
afb08462 111
74ecdd15 112`FLIP` has two version of tool, GUI app and command line program. If you want GUI see tutorial section below.
113To use command line tool run this command. Note that you need to set PATH variable properly.
114
115 $ make -f Makefile.<variant> flip
116
117To program with `dfu-programmer` run:
118
119 $ make -f Makefile.<variant> dfu
afb08462 120
74ecdd15 121#### Teensy
122If you have PJRC Teensy see instruction of `Teensy Loader` at: <http://www.pjrc.com/teensy/loader.html>
123Or use this command if you have command line version of Teensy Loader installed.
124
125 $ make -f Makefile.<variant> teensy
126
127
128#### Other programmer
129You may want to use other you favorite programmer like `avrdude` with AVRISPmkII, Aruduino or USBasp. In that case you can still use make target `program` for build with configuring PROGRAM_CMD in Makefile.
130
131 $ make -f Makefile.<variant> program
132
133
134
135#### FLIP GUI tutorial
1361. On menu bar click Device -> Select, then. `ATmega32u4`.
1372. On menu bar click Settings -> Communication -> USB, then click 'Open' button on 'USB Port Connection' dialog.
138At this point you'll see greyouted widgets on the app get colored and ready.
139
1403. On menu bar click File -> Load HEX File, then select your firmware hex file on File Selector dialog.
1414. On 'Operations Flow' panel click 'Run' button to load the firmware binary to the chip. Note that you should keep 'Erase', 'Blank Check', 'Program' and 'Verify' check boxes selected.
1425. Re-plug USB cord or click 'Start Application' button to restart your controller.
143Done.
144
145See also these instaructions if you need.
146
147- <http://code.google.com/p/micropendous/wiki/LoadingFirmwareWithFLIP>
148- <http://www.atmel.com/Images/doc7769.pdf>
149
150
151[winavr]: http://winavr.sourceforge.net/
152[crosspack]: http://www.obdev.at/products/crosspack/index.html
153[flip]: http://www.atmel.com/tools/FLIP.aspx
154[dfu-prog]: http://dfu-programmer.sourceforge.net/
155[teensy-loader]:http://www.pjrc.com/teensy/loader.html
afb08462 156
157
158
784c6e39 159Makefile Options
160----------------
161### 1. MCU and Frequency.
162
afb08462 163 MCU = atmega32u4 # Teensy 2.0
164 #MCU = at90usb1286 # Teensy++ 2.0
165 F_CPU = 16000000
166
784c6e39 167### 2. Features
afb08462 168Note that ***comment out*** to disable them.
784c6e39 169
8b9bd51d 170 BOOTMAGIC_ENABLE = yes # Virtual DIP switch configuration(+1000)
171 MOUSEKEY_ENABLE = yes # Mouse keys(+4700)
172 EXTRAKEY_ENABLE = yes # Audio control and System control(+450)
173 CONSOLE_ENABLE = yes # Console for debug(+400)
9a3edb89 174 COMMAND_ENABLE = yes # Commands for debug and configuration
0142e20b 175 SLEEP_LED_ENABLE = yes # Breathing sleep LED during USB suspend
8b9bd51d 176 #NKRO_ENABLE = yes # USB Nkey Rollover - not yet supported in LUFA
177 #PS2_MOUSE_ENABLE = yes # PS/2 mouse(TrackPoint) support
afb08462 178
784c6e39 179### 3. Programmer
8b9bd51d 180Optional. Set proper command for your controller, bootloader and programmer. This command can be used with `make program`.
784c6e39 181
afb08462 182 # for PJRC Teensy
183 PROGRAM_CMD = teensy_loader_cli -mmcu=$(MCU) -w -v $(TARGET).hex
184
74ecdd15 185 # for Atmel chip with DFU bootloader
afb08462 186 PROGRAM_CMD = dfu-programmer $(MCU) flash $(TARGET).hex
187
74ecdd15 188 # avrdude with other methods
afb08462 189 PROGRAM_CMD = avrdude -p $(MCU) -c avrispmkII -P USB -U flash:w:$(TARGET).hex
190 PROGRAM_CMD = avrdude -p $(MCU) -c usbasp -U flash:w:$(TARGET).hex
191 PROGRAM_CMD = avrdude -p $(MCU) -c arduino -P COM1 -b 57600 -U flash:w:$(TARGET).hex
192
74ecdd15 193
194
195Config.h Options
784c6e39 196----------------
197### 1. USB vendor/product ID and device description
afb08462 198 #define VENDOR_ID 0xFEED
199 #define PRODUCT_ID 0xBEEF
200 /* device description */
201 #define MANUFACTURER t.m.k.
202 #define PRODUCT Macway mod
203 #define DESCRIPTION t.m.k. keyboard firmware for Macway mod
204
784c6e39 205### 2. Keyboard matrix configuration
afb08462 206 #define MATRIX_ROWS 8
207 #define MATRIX_COLS 8
208 #define MATRIX_HAS_GHOST
209
784c6e39 210### 3. Mouse keys
211
212### 4. PS/2 mouse
213
214### 5. COMMAND key combination
afb08462 215
784c6e39 216 #define IS_COMMAND() (keyboard_report->mods == (MOD_BIT(KB_LSHIFT) | MOD_BIT(KB_RSHIFT)))
afb08462 217
218
083c7581 219Change your keymap
220------------------
221[keymap.md](doc/keymap.md)
74ecdd15 222
afb08462 223
afb08462 224
225
226Debuging
227--------
74ecdd15 228Use PJRC's `hid_listen` to see debug messages. You can use the tool for debug even if firmware use LUFA stack.
229
230You will see output from firmware like this.
231
232 r/c 01234567
233 00: 00000000
234 01: 00000000
235 02: 00000000
236 03: 00000000
237 04: 00000000
238 05: 00000000
239 06: 00000000
240 07: 00000000
241
242 ---- action_exec: start -----
243 EVENT: 0307u(22511)
244 Tapping: Tap release(2)
245 ACTION: ACT_LAYER[5:2C]
246 LAYER_PRESSED: Tap: unregister_code
247 TAPPING_KEY=0307u(22511):2
248 processed: 0307u(22511):2
249
250 Tapping: End(Timeout after releasing last tap): FFFFu(22715)
251 TAPPING_KEY=0000u(0):0
252
afb08462 253
254
74ecdd15 255
256Magic Comannds
257--------------
258To see help press `Magic` + `H`.
259
260 `Magic` key bind may be `LShift` + `RShift` in many project, but `Power` key on ADB converter. `Magic` keybind can be vary on each project, check `config.h` in project directory.
261
262Following commands can be also executed with `Magic` + key. In console mode `Magic` keybind is not needed.
263
264 ----- Command Help -----
265 c: enter console mode
266 d: toggle debug enable
267 x: toggle matrix debug
268 k: toggle keyboard debug
269 m: toggle mouse debug
270 p: toggle print enable
271 v: print device version & info
272 t: print timer count
273 s: print status
274 0/F10: switch to Layer0
275 1/F1: switch to Layer1
276 2/F2: switch to Layer2
277 3/F3: switch to Layer3
278 4/F4: switch to Layer4
279 PScr: power down/remote wake-up
280 Caps: Lock Keyboard(Child Proof)
281 Paus: jump to bootloader
282
8b9bd51d 283**TBD**
39d09333 284
8b9bd51d 285### Conguration with Boot Magic
286Boot Magic are executed during boot up time. Press Magic key below then pulgin keyboard cable.
287These settings are stored in EEPROM.
39d09333 288
8b9bd51d 289- Clear configuration stored in EEPROM(`Backspace`)
290- Kick up Bootloader(`B`)
291- Debug enable(`D`)
292- Swap Control and CapsLock(`Left Control`)
293- Change CapsLock to Control(`Casp Lock`)
294- Swap LeftAlt and Gui(`Left Alt`)
295- Swap RightAlt and Gui(`Right Alt`)
296- Disable Gui(`Left Gui`)
297- Swap Grave and Escape(`Grave`)
298- Swap BackSlash and BackSpace(`Back Slash`)
39d09333 299
8b9bd51d 300**TBD**
39d09333 301
74ecdd15 302
c0137b4b 303Mechanical Locking support for CapsLock
304---------------------------------------
305To enable this feature define these two macros in `config.h` and use `KC_LCAP` for locking CapsLock in keymap instead of normal `KC_CAPS`. Resync option tries to keep lock switch state consistent with keyboard LED state.
306
307 #define CAPSLOCK_LOCKING_ENABLE
308 #define CAPSLOCK_LOCKING_RESYNC_ENABLE
309
74ecdd15 310
311Start Your Own Project
afb08462 312-----------------------
0142e20b 313**TBD**
afb08462 314
afb08462 315
afb08462 316
74ecdd15 317Files & Directories
318-------------------
319### Top
320* common/ - common codes
321* protocol/ - keyboard protocol support
322* keyboard/ - keyboard projects
323* converter/ - protocol converter projects
324* doc/ - documents
325* common.mk - Makefile for common
326* protoco.mk - Makefile for protocol
327* rules.mk - Makefile for build rules
328
329### Common
0be309cc 330* action.[ch]
331* action_macro.[ch]
332* bootloader.[ch]
333* command.[ch]
334* controller_teensy.h
335* debug.[ch]
336* host.[ch]
337* host_driver.h
338* keyboard.[ch]
339* keycode.h
340* keymap.[ch]
341* led.h
342* matrix.h
343* mousekey.[ch]
344* print.[ch]
345* report.h
346* sendchar.h
347* sendchar_null.c
348* sendchar_uart.c
349* timer.[ch]
350* uart.[ch]
351* util.[ch]
74ecdd15 352
353### Keyboard Protocols
354* lufa/ - LUFA USB stack
355* pjrc/ - PJRC USB stack
356* vusb/ - Objective Development V-USB
357* iwrap/ - Bluetooth HID for Bluegiga iWRAP
358* ps2.c - PS/2 protocol
359* adb.c - Apple Desktop Bus protocol
360* m0110.c - Macintosh 128K/512K/Plus keyboard protocol
361* news.c - Sony NEWS keyboard protocol
362* x68k.c - Sharp X68000 keyboard protocol
363* serial_soft.c - Asynchronous Serial protocol implemented by software
afb08462 364
afb08462 365
afb08462 366
74ecdd15 367License
368-------
369Under `GPL` 2 or later. Some protocol files are under `Modified BSD License`.
48e6d084 370LUFA, PJRC and V-USB stack have their own license respectively.
Imprint / Impressum