Fix keymap for new actions
[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
41bf9204 69Download and Install
70--------------------
71### 1. Install Tools
74ecdd15 72First, you need tools to build firmware and program your controller. I assume you are on Windows here.
afb08462 73
41bf9204 741. **Toolchain** 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.
74ecdd15 75
41bf9204 762. **Programmer** Install [Atmel FLIP][flip]. `FLIP` is a tool to program(load) firmware into AVR controller via DFU bootloader. AVR USB chips including ATmega32U4 has DFU bootloader by factory default. You can also use [dfu-programmer][dfu-prog] instead if you are on Mac or Linux.
74ecdd15 77
41bf9204 783. **Driver** 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.
74ecdd15 79
41bf9204 80If you use PJRC Teensy you don't need step 2 and 3 above, just get [Teensy loader][teensy-loader].
74ecdd15 81
82
41bf9204 83### 2. Download source
84You can find firmware source at github:
74ecdd15 85
41bf9204 86- <https://github.com/tmk/tmk_keyboard>
afb08462 87
41bf9204 88If you are familiar with `Git` tools you are recommended to use it but you can also download zip archive from:
afb08462 89
41bf9204 90- <https://github.com/tmk/tmk_keyboard/archive/master.zip>
74ecdd15 91
74ecdd15 92
41bf9204 93Build firmware
94--------------
95### 1. Open terminal
96Open 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.
97
98### 2. Change directory
99Move to project directory in the firmware source.
100
101 cd tmk_keyboard/{'keyboard' or 'converter'}/<project>
102
103### 3. Make
104Build firmware using GNU `make` command. You'll see `<project>_<variant>.hex` file in that directory unless something unexpected occurs in build process.
74ecdd15 105
74ecdd15 106
107 mkae -f Makefile.<variant> clean
108 make -f Makefile.<variant>
afb08462 109
afb08462 110
afb08462 111
afb08462 112
41bf9204 113Program Controller
114------------------
115Now you have **hex** file to program on current directory. This **hex** is only needed to program your controller, other files are used for development and you may leave and forget them.
116
117### 1. Start bootloader
118How to program controller depends on controller chip and its board design. To program AVR USB chips you'll need to start it up in bootloader mode. Most of boards with the chip have a push button to let bootloader come up. Consult with your controller board manual.
119
120### 2. Program with DFU bootloader
121Stock AVR USB chip including ATmega32U4 has DFU bootloader by factory default. `FLIP` is a DFU programmer on Windows offered by Atmel. Open source command line tool `dfu-programmer` also supports AVR chips, it runs on Linux, Mac OSX and even Windows.
74ecdd15 122
74ecdd15 123To program AVR chip with DFU bootloader use `FLIP` or `dfu-programmer`.
784c6e39 124If you have a proper program command in `Makefile` just type this.
afb08462 125
41bf9204 126`FLIP` has two version of tool, GUI app and command line program. If you want GUI see tutorial below.
74ecdd15 127To use command line tool run this command. Note that you need to set PATH variable properly.
128
129 $ make -f Makefile.<variant> flip
130
41bf9204 131Or to program with `dfu-programmer` run:
74ecdd15 132
133 $ make -f Makefile.<variant> dfu
afb08462 134
74ecdd15 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
41bf9204 151### 3. Program with Teensy Loader
152If you have PJRC Teensy see instruction of `Teensy Loader`.
153
154- <http://www.pjrc.com/teensy/loader.html>
155
156Or use this command if you have command line version of Teensy Loader installed.
157
158 $ make -f Makefile.<variant> teensy
159
160
161### 4. Program with Other programmer
162You may want to use other 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.
163
164 $ make -f Makefile.<variant> program
165
166
74ecdd15 167[winavr]: http://winavr.sourceforge.net/
168[crosspack]: http://www.obdev.at/products/crosspack/index.html
169[flip]: http://www.atmel.com/tools/FLIP.aspx
170[dfu-prog]: http://dfu-programmer.sourceforge.net/
171[teensy-loader]:http://www.pjrc.com/teensy/loader.html
afb08462 172
173
174
784c6e39 175Makefile Options
176----------------
177### 1. MCU and Frequency.
178
afb08462 179 MCU = atmega32u4 # Teensy 2.0
180 #MCU = at90usb1286 # Teensy++ 2.0
181 F_CPU = 16000000
182
41bf9204 183 # Boot Section Size in *bytes*
184 # Teensy halfKay 512
185 # Atmel DFU loader 4096
186 # LUFA bootloader 4096
187 OPT_DEFS += -DBOOTLOADER_SIZE=4096
188
784c6e39 189### 2. Features
41bf9204 190Optional. Note that ***comment out*** to disable them.
784c6e39 191
8b9bd51d 192 BOOTMAGIC_ENABLE = yes # Virtual DIP switch configuration(+1000)
193 MOUSEKEY_ENABLE = yes # Mouse keys(+4700)
194 EXTRAKEY_ENABLE = yes # Audio control and System control(+450)
195 CONSOLE_ENABLE = yes # Console for debug(+400)
9a3edb89 196 COMMAND_ENABLE = yes # Commands for debug and configuration
0142e20b 197 SLEEP_LED_ENABLE = yes # Breathing sleep LED during USB suspend
8b9bd51d 198 #NKRO_ENABLE = yes # USB Nkey Rollover - not yet supported in LUFA
afb08462 199
784c6e39 200### 3. Programmer
41bf9204 201Optional. Set proper command for your controller, bootloader and programmer. This command can be used with `make program`. Not needed if you use `FLIP`, `dfu-programmer` or `Teesy Loader`.
afb08462 202
41bf9204 203 # avrdude with AVRISPmkII
afb08462 204 PROGRAM_CMD = avrdude -p $(MCU) -c avrispmkII -P USB -U flash:w:$(TARGET).hex
41bf9204 205
206 # avrdude with USBaspLoader
afb08462 207 PROGRAM_CMD = avrdude -p $(MCU) -c usbasp -U flash:w:$(TARGET).hex
41bf9204 208
209 # avrdude with arduino
afb08462 210 PROGRAM_CMD = avrdude -p $(MCU) -c arduino -P COM1 -b 57600 -U flash:w:$(TARGET).hex
211
74ecdd15 212
213
214Config.h Options
784c6e39 215----------------
41bf9204 216### 1. Magic command key combination
afb08462 217
41bf9204 218 #define IS_COMMAND() (keyboard_report->mods == (MOD_BIT(KB_LSHIFT) | MOD_BIT(KB_RSHIFT)))
784c6e39 219
41bf9204 220### 2. Mechanical Locking Support for CapsLock
afb08462 221
41bf9204 222 /* Mechanical locking CapsLock support. Use KC_LCAP instead of KC_CAPS in keymap */
223 #define CAPSLOCK_LOCKING_ENABLE
224 /* Locking CapsLock resynchronize hack */
225 #define CAPSLOCK_LOCKING_RESYNC_ENABLE
afb08462 226
227
083c7581 228Change your keymap
229------------------
230[keymap.md](doc/keymap.md)
74ecdd15 231
afb08462 232
afb08462 233
234
235Debuging
236--------
74ecdd15 237Use PJRC's `hid_listen` to see debug messages. You can use the tool for debug even if firmware use LUFA stack.
238
239You will see output from firmware like this.
240
241 r/c 01234567
242 00: 00000000
243 01: 00000000
244 02: 00000000
245 03: 00000000
246 04: 00000000
247 05: 00000000
248 06: 00000000
249 07: 00000000
250
251 ---- action_exec: start -----
252 EVENT: 0307u(22511)
253 Tapping: Tap release(2)
254 ACTION: ACT_LAYER[5:2C]
255 LAYER_PRESSED: Tap: unregister_code
256 TAPPING_KEY=0307u(22511):2
257 processed: 0307u(22511):2
258
259 Tapping: End(Timeout after releasing last tap): FFFFu(22715)
260 TAPPING_KEY=0000u(0):0
261
afb08462 262
263
74ecdd15 264
265Magic Comannds
266--------------
267To see help press `Magic` + `H`.
268
269 `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.
270
271Following commands can be also executed with `Magic` + key. In console mode `Magic` keybind is not needed.
272
273 ----- Command Help -----
274 c: enter console mode
275 d: toggle debug enable
276 x: toggle matrix debug
277 k: toggle keyboard debug
278 m: toggle mouse debug
279 p: toggle print enable
280 v: print device version & info
281 t: print timer count
282 s: print status
283 0/F10: switch to Layer0
284 1/F1: switch to Layer1
285 2/F2: switch to Layer2
286 3/F3: switch to Layer3
287 4/F4: switch to Layer4
288 PScr: power down/remote wake-up
289 Caps: Lock Keyboard(Child Proof)
290 Paus: jump to bootloader
291
8b9bd51d 292**TBD**
39d09333 293
8b9bd51d 294### Conguration with Boot Magic
295Boot Magic are executed during boot up time. Press Magic key below then pulgin keyboard cable.
296These settings are stored in EEPROM.
39d09333 297
8b9bd51d 298- Clear configuration stored in EEPROM(`Backspace`)
299- Kick up Bootloader(`B`)
300- Debug enable(`D`)
301- Swap Control and CapsLock(`Left Control`)
302- Change CapsLock to Control(`Casp Lock`)
303- Swap LeftAlt and Gui(`Left Alt`)
304- Swap RightAlt and Gui(`Right Alt`)
305- Disable Gui(`Left Gui`)
306- Swap Grave and Escape(`Grave`)
307- Swap BackSlash and BackSpace(`Back Slash`)
39d09333 308
8b9bd51d 309**TBD**
39d09333 310
74ecdd15 311
c0137b4b 312Mechanical Locking support for CapsLock
313---------------------------------------
314To 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.
315
316 #define CAPSLOCK_LOCKING_ENABLE
317 #define CAPSLOCK_LOCKING_RESYNC_ENABLE
318
74ecdd15 319
320Start Your Own Project
afb08462 321-----------------------
0142e20b 322**TBD**
41bf9204 323### Config.h Options
324#### 1. USB vendor/product ID and device description
325 #define VENDOR_ID 0xFEED
326 #define PRODUCT_ID 0xBEEF
327 /* device description */
328 #define MANUFACTURER t.m.k.
329 #define PRODUCT Macway mod
330 #define DESCRIPTION t.m.k. keyboard firmware for Macway mod
331
332#### 2. Keyboard matrix configuration
333 #define MATRIX_ROWS 8
334 #define MATRIX_COLS 8
335 #define MATRIX_HAS_GHOST
336
afb08462 337
afb08462 338
afb08462 339
74ecdd15 340Files & Directories
341-------------------
342### Top
343* common/ - common codes
344* protocol/ - keyboard protocol support
345* keyboard/ - keyboard projects
346* converter/ - protocol converter projects
347* doc/ - documents
348* common.mk - Makefile for common
349* protoco.mk - Makefile for protocol
350* rules.mk - Makefile for build rules
351
352### Common
0be309cc 353* action.[ch]
354* action_macro.[ch]
355* bootloader.[ch]
356* command.[ch]
357* controller_teensy.h
358* debug.[ch]
359* host.[ch]
360* host_driver.h
361* keyboard.[ch]
362* keycode.h
363* keymap.[ch]
364* led.h
365* matrix.h
366* mousekey.[ch]
367* print.[ch]
368* report.h
369* sendchar.h
370* sendchar_null.c
371* sendchar_uart.c
372* timer.[ch]
373* uart.[ch]
374* util.[ch]
74ecdd15 375
376### Keyboard Protocols
377* lufa/ - LUFA USB stack
378* pjrc/ - PJRC USB stack
379* vusb/ - Objective Development V-USB
380* iwrap/ - Bluetooth HID for Bluegiga iWRAP
381* ps2.c - PS/2 protocol
382* adb.c - Apple Desktop Bus protocol
383* m0110.c - Macintosh 128K/512K/Plus keyboard protocol
384* news.c - Sony NEWS keyboard protocol
385* x68k.c - Sharp X68000 keyboard protocol
386* serial_soft.c - Asynchronous Serial protocol implemented by software
afb08462 387
afb08462 388
afb08462 389
74ecdd15 390License
391-------
392Under `GPL` 2 or later. Some protocol files are under `Modified BSD License`.
48e6d084 393LUFA, PJRC and V-USB stack have their own license respectively.
Imprint / Impressum