1 t.m.k. Keyboard Firmware Collection
2 ====================================
3 This is a keyboard firmware with some features for Atmel AVR controller.
5 Source code is available here: <http://github.com/tmk/tmk_keyboard>
10 * Multi-layer Keymap - Multiple keyboard layouts with layer switching.
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
25 You can find some keyboard specific projects under `converter` and `keyboard` directory.
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)
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]
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
52 [GH_news]: http://geekhack.org/showwiki.php?title=Island:25759
53 [GH_terminal]: http://geekhack.org/showwiki.php?title=Island:27272
54 [GH_x68k]: http://geekhack.org/showwiki.php?title=Island:29060
55 [GH_hbkb]: http://geekhack.org/showwiki.php?title=Island:29483
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
65 First, you need tools to build firmware and program your controller. I assume you are on Windows here.
67 1. 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.
69 2. 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.
71 3. 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.
73 If you use PJRC Teensy you don't need step 2 and 3, just get [Teensy loader][teensy-loader].
77 You can find firmware source at github: https://github.com/tmk/tmk_keyboard
79 If you are familiar with `Git` tools you are recommended to use it.
80 If not you can download zip archive from: https://github.com/tmk/tmk_keyboard/archive/master.zip
84 1. 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.
86 2. Move to project directory in the firmware source.
88 cd tmk_keyboard/{keyboard or converter}/<project>
90 3. Build firmware using GNU `make` command. You'll see <project>_<variant>.hex file in that directory unless something unexpected occurs in build process.
92 mkae -f Makefile.<variant> clean
93 make -f Makefile.<variant>
98 ### Program Controller
99 Sock 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`.
102 To program AVR chip with DFU bootloader use `FLIP` or `dfu-programmer`.
103 If you have a proper program command in `Makefile` just type this.
105 `FLIP` has two version of tool, GUI app and command line program. If you want GUI see tutorial section below.
106 To use command line tool run this command. Note that you need to set PATH variable properly.
108 $ make -f Makefile.<variant> flip
110 To program with `dfu-programmer` run:
112 $ make -f Makefile.<variant> dfu
115 If you have PJRC Teensy see instruction of `Teensy Loader` at: <http://www.pjrc.com/teensy/loader.html>
116 Or use this command if you have command line version of Teensy Loader installed.
118 $ make -f Makefile.<variant> teensy
121 #### Other programmer
122 You 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.
124 $ make -f Makefile.<variant> program
128 #### FLIP GUI tutorial
129 1. On menu bar click Device -> Select, then. `ATmega32u4`.
130 2. On menu bar click Settings -> Communication -> USB, then click 'Open' button on 'USB Port Connection' dialog.
131 At this point you'll see greyouted widgets on the app get colored and ready.
133 3. On menu bar click File -> Load HEX File, then select your firmware hex file on File Selector dialog.
134 4. 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.
135 5. Re-plug USB cord or click 'Start Application' button to restart your controller.
138 See also these instaructions if you need.
140 - <http://code.google.com/p/micropendous/wiki/LoadingFirmwareWithFLIP>
141 - <http://www.atmel.com/Images/doc7769.pdf>
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
154 ### 1. MCU and Frequency.
156 MCU = atmega32u4 # Teensy 2.0
157 #MCU = at90usb1286 # Teensy++ 2.0
161 Note that ***comment out*** to disable them.
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
169 Optional. Set proper command for your controller, bootloader and programmer.
172 PROGRAM_CMD = teensy_loader_cli -mmcu=$(MCU) -w -v $(TARGET).hex
174 # for Atmel chip with DFU bootloader
175 PROGRAM_CMD = dfu-programmer $(MCU) flash $(TARGET).hex
177 # avrdude with other methods
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
186 ### 1. USB vendor/product ID and device description
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
194 ### 2. Keyboard matrix configuration
195 #define MATRIX_ROWS 8
196 #define MATRIX_COLS 8
197 #define MATRIX_HAS_GHOST
203 ### 5. COMMAND key combination
205 #define IS_COMMAND() (keyboard_report->mods == (MOD_BIT(KB_LSHIFT) | MOD_BIT(KB_RSHIFT)))
210 [keymap.md](doc/keymap.md)
217 Use PJRC's `hid_listen` to see debug messages. You can use the tool for debug even if firmware use LUFA stack.
219 You will see output from firmware like this.
231 ---- action_exec: start -----
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
239 Tapping: End(Timeout after releasing last tap): FFFFu(22715)
240 TAPPING_KEY=0000u(0):0
247 To see help press `Magic` + `H`.
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.
251 Following commands can be also executed with `Magic` + key. In console mode `Magic` keybind is not needed.
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
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
273 Magic commands are executed when boot time. Press `Magic` command key then pulgin.
275 Define these macros in config.h.
278 IS_BOOTMAGIC_BOOTLOADER
280 ***TODO: sample impl***
281 See `keyboard/hhkb/config.h` for sample.
285 Start Your Own Project
286 -----------------------
293 * common/ - common codes
294 * protocol/ - keyboard protocol support
295 * keyboard/ - keyboard projects
296 * converter/ - protocol converter projects
298 * common.mk - Makefile for common
299 * protoco.mk - Makefile for protocol
300 * rules.mk - Makefile for build rules
307 * controller_teensy.h
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
342 Under `GPL` 2 or later. Some protocol files are under `Modified BSD License`.
343 LUFA, PJRC and V-USB stack have their own license respectively.