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