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