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