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