You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
This repo is archived. You can view files and clone it, but cannot push or open issues/pull-requests.

README.md 15KB

11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393
  1. t.m.k. Keyboard Firmware Collection
  2. ====================================
  3. This is a keyboard firmware with some features for Atmel AVR controller.
  4. Source code is available here: <http://github.com/tmk/tmk_keyboard>
  5. Features
  6. --------
  7. * Multi-layer Keymap - Multiple keyboard layouts with layer switching
  8. * Mouse key - Mouse control with keyboard
  9. * System Control Key - Power Down, Sleep, Wake Up and USB Remote Wake up
  10. * Media Control Key - Volume Down/Up, Mute, Next/Prev track, Play, Stop and etc
  11. * USB NKRO - 120 keys(+ 8 modifiers) simultaneously
  12. * PS/2 mouse support - PS/2 mouse(TrackPoint) as composite device
  13. * Keyboard protocols - PS/2, ADB, M0110, Sun and other old keyboard protocols
  14. * User Function - Customizable function of key with writing code
  15. * Macro - Very primitive at this time
  16. * Keyboard Tricks - Oneshot modifier and modifier with tapping feature
  17. * Debug Console - Messages for debug and interaction with firmware
  18. * Virtual DIP Switch - Configurations stored EEPROM(Boot Magic)
  19. * Locking CapsLock - Mechanical switch support for CapsLock
  20. * Breathing Sleep LED - Sleep indicator with charm during USB suspend
  21. Projects
  22. --------
  23. You can find some keyboard specific projects under `converter` and `keyboard` directory.
  24. ### converter
  25. * [ps2_usb](converter/ps2_usb/) - [PS/2 keyboard to USB][GH_ps2]
  26. * [adb_usb](converter/adb_usb/) - [ADB keyboard to USB][GH_adb]
  27. * [m0110_usb](converter/m0110_usb) - [Machintosh 128K/512K/Plus keyboard to USB][GH_m0110]
  28. * [terminal_usb](converter/terminal_usb/) - [IBM Model M terminal keyboard(PS/2 scancode set3) to USB][GH_terminal]
  29. * [news_usb](converter/news_usb/) - [Sony NEWS keyboard to USB][GH_news]
  30. * [x68k_usb](converter/x68k_usb/) - [Sharp X68000 keyboard to USB][GH_x68k]
  31. * [sun_usb](converter/sun_usb/) - [Sun] to USB(type4, 5 and 3?)
  32. * [pc98_usb](converter/pc98_usb/) - [PC98] to USB
  33. * [usb_usb](converter/usb_usb/) - USB to USB(experimental)
  34. ### keyboard
  35. * [hhkb](keyboard/hhkb/) - [Happy Hacking Keyboard professional][GH_hhkb]
  36. * [macway](keyboard/macway/) - [Compact keyboard mod][GH_macway]
  37. * [hbkb](keyboard/hbkb/) - [Happy Buckling sprint keyboard(IBM Model M mod)][GH_hbkb]
  38. * [IIgs_Standard](keyboard/IIgs/) - Apple [IIGS] keyboard mod(by JeffreySung)
  39. * [hid_liber](keyboard/hid_liber/) - [HID liberation controller][HID_liber](by alaricljs)
  40. * [phantom](keyboard/phantom/) - [Phantom keyboard][PHANTOM] (by Tranquilite)
  41. * [gh60](keyboard/gh60/) - [GH60 keyboard][GH60]
  42. [GH_macway]: http://geekhack.org/showwiki.php?title=Island:11930
  43. [GH_hhkb]: http://geekhack.org/showwiki.php?title=Island:12047
  44. [GH_ps2]: http://geekhack.org/showwiki.php?title=Island:14618
  45. [GH_adb]: http://geekhack.org/showwiki.php?title=Island:14290
  46. [GH_hhkb_bt]: http://geekhack.org/showwiki.php?title=Island:20851
  47. [GH_m0110]: http://geekhack.org/showwiki.php?title=Island:24965
  48. [GH_news]: http://geekhack.org/showwiki.php?title=Island:25759
  49. [GH_terminal]: http://geekhack.org/showwiki.php?title=Island:27272
  50. [GH_x68k]: http://geekhack.org/showwiki.php?title=Island:29060
  51. [GH_hbkb]: http://geekhack.org/showwiki.php?title=Island:29483
  52. [HID_liber]: http://deskthority.net/wiki/HID_Liberation_Device_-_DIY_Instructions
  53. [PHANTOM]: http://geekhack.org/index.php?topic=26742
  54. [GH60]: http://geekhack.org/index.php?topic=34959
  55. [PC98]: http://en.wikipedia.org/wiki/NEC_PC-9801
  56. [Sun]: http://en.wikipedia.org/wiki/Sun-3
  57. [IIGS]: http://en.wikipedia.org/wiki/Apple_IIGS
  58. Download and Install
  59. --------------------
  60. ### 1. Install Tools
  61. First, you need tools to build firmware and program your controller. I assume you are on Windows here.
  62. 1. **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.
  63. 2. **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.
  64. 3. **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.
  65. If you use PJRC Teensy you don't need step 2 and 3 above, just get [Teensy loader][teensy-loader].
  66. ### 2. Download source
  67. You can find firmware source at github:
  68. - <https://github.com/tmk/tmk_keyboard>
  69. If you are familiar with `Git` tools you are recommended to use it but you can also download zip archive from:
  70. - <https://github.com/tmk/tmk_keyboard/archive/master.zip>
  71. Build firmware
  72. --------------
  73. ### 1. Open terminal
  74. 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.
  75. ### 2. Change directory
  76. Move to project directory in the firmware source.
  77. cd tmk_keyboard/{'keyboard' or 'converter'}/<project>
  78. ### 3. Make
  79. Build firmware using GNU `make` command. You'll see `<project>_<variant>.hex` file in that directory unless something unexpected occurs in build process.
  80. mkae -f Makefile.<variant> clean
  81. make -f Makefile.<variant>
  82. Program Controller
  83. ------------------
  84. Now 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.
  85. ### 1. Start bootloader
  86. How 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.
  87. ### 2. Program with DFU bootloader
  88. Stock 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.
  89. To program AVR chip with DFU bootloader use `FLIP` or `dfu-programmer`.
  90. If you have a proper program command in `Makefile` just type this.
  91. `FLIP` has two version of tool, GUI app and command line program. If you want GUI see tutorial below.
  92. To use command line tool run this command. Note that you need to set PATH variable properly.
  93. $ make -f Makefile.<variant> flip
  94. Or to program with `dfu-programmer` run:
  95. $ make -f Makefile.<variant> dfu
  96. #### FLIP GUI tutorial
  97. 1. On menu bar click Device -> Select, then. `ATmega32u4`.
  98. 2. On menu bar click Settings -> Communication -> USB, then click 'Open' button on 'USB Port Connection' dialog.
  99. At this point you'll see greyouted widgets on the app get colored and ready.
  100. 3. On menu bar click File -> Load HEX File, then select your firmware hex file on File Selector dialog.
  101. 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.
  102. 5. Re-plug USB cord or click 'Start Application' button to restart your controller.
  103. Done.
  104. See also these instaructions if you need.
  105. - <http://code.google.com/p/micropendous/wiki/LoadingFirmwareWithFLIP>
  106. - <http://www.atmel.com/Images/doc7769.pdf>
  107. ### 3. Program with Teensy Loader
  108. If you have PJRC Teensy see instruction of `Teensy Loader`.
  109. - <http://www.pjrc.com/teensy/loader.html>
  110. Or use this command if you have command line version of Teensy Loader installed.
  111. $ make -f Makefile.<variant> teensy
  112. ### 4. Program with Other programmer
  113. You 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.
  114. $ make -f Makefile.<variant> program
  115. [winavr]: http://winavr.sourceforge.net/
  116. [crosspack]: http://www.obdev.at/products/crosspack/index.html
  117. [flip]: http://www.atmel.com/tools/FLIP.aspx
  118. [dfu-prog]: http://dfu-programmer.sourceforge.net/
  119. [teensy-loader]:http://www.pjrc.com/teensy/loader.html
  120. Makefile Options
  121. ----------------
  122. ### 1. MCU and Frequency.
  123. MCU = atmega32u4 # Teensy 2.0
  124. #MCU = at90usb1286 # Teensy++ 2.0
  125. F_CPU = 16000000
  126. # Boot Section Size in *bytes*
  127. # Teensy halfKay 512
  128. # Atmel DFU loader 4096
  129. # LUFA bootloader 4096
  130. OPT_DEFS += -DBOOTLOADER_SIZE=4096
  131. ### 2. Features
  132. Optional. Note that ***comment out*** to disable them.
  133. BOOTMAGIC_ENABLE = yes # Virtual DIP switch configuration(+1000)
  134. MOUSEKEY_ENABLE = yes # Mouse keys(+4700)
  135. EXTRAKEY_ENABLE = yes # Audio control and System control(+450)
  136. CONSOLE_ENABLE = yes # Console for debug(+400)
  137. COMMAND_ENABLE = yes # Commands for debug and configuration
  138. SLEEP_LED_ENABLE = yes # Breathing sleep LED during USB suspend
  139. #NKRO_ENABLE = yes # USB Nkey Rollover - not yet supported in LUFA
  140. ### 3. Programmer
  141. Optional. 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`.
  142. # avrdude with AVRISPmkII
  143. PROGRAM_CMD = avrdude -p $(MCU) -c avrispmkII -P USB -U flash:w:$(TARGET).hex
  144. # avrdude with USBaspLoader
  145. PROGRAM_CMD = avrdude -p $(MCU) -c usbasp -U flash:w:$(TARGET).hex
  146. # avrdude with arduino
  147. PROGRAM_CMD = avrdude -p $(MCU) -c arduino -P COM1 -b 57600 -U flash:w:$(TARGET).hex
  148. Config.h Options
  149. ----------------
  150. ### 1. Magic command key combination
  151. #define IS_COMMAND() (keyboard_report->mods == (MOD_BIT(KB_LSHIFT) | MOD_BIT(KB_RSHIFT)))
  152. ### 2. Mechanical Locking Support for CapsLock
  153. /* Mechanical locking CapsLock support. Use KC_LCAP instead of KC_CAPS in keymap */
  154. #define CAPSLOCK_LOCKING_ENABLE
  155. /* Locking CapsLock resynchronize hack */
  156. #define CAPSLOCK_LOCKING_RESYNC_ENABLE
  157. Change your keymap
  158. ------------------
  159. [keymap.md](doc/keymap.md)
  160. Debuging
  161. --------
  162. Use PJRC's `hid_listen` to see debug messages. You can use the tool for debug even if firmware use LUFA stack.
  163. You will see output from firmware like this.
  164. r/c 01234567
  165. 00: 00000000
  166. 01: 00000000
  167. 02: 00000000
  168. 03: 00000000
  169. 04: 00000000
  170. 05: 00000000
  171. 06: 00000000
  172. 07: 00000000
  173. ---- action_exec: start -----
  174. EVENT: 0307u(22511)
  175. Tapping: Tap release(2)
  176. ACTION: ACT_LAYER[5:2C]
  177. LAYER_PRESSED: Tap: unregister_code
  178. TAPPING_KEY=0307u(22511):2
  179. processed: 0307u(22511):2
  180. Tapping: End(Timeout after releasing last tap): FFFFu(22715)
  181. TAPPING_KEY=0000u(0):0
  182. Magic Comannds
  183. --------------
  184. To see help press `Magic` + `H`.
  185. `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.
  186. Following commands can be also executed with `Magic` + key. In console mode `Magic` keybind is not needed.
  187. ----- Command Help -----
  188. c: enter console mode
  189. d: toggle debug enable
  190. x: toggle matrix debug
  191. k: toggle keyboard debug
  192. m: toggle mouse debug
  193. p: toggle print enable
  194. v: print device version & info
  195. t: print timer count
  196. s: print status
  197. 0/F10: switch to Layer0
  198. 1/F1: switch to Layer1
  199. 2/F2: switch to Layer2
  200. 3/F3: switch to Layer3
  201. 4/F4: switch to Layer4
  202. PScr: power down/remote wake-up
  203. Caps: Lock Keyboard(Child Proof)
  204. Paus: jump to bootloader
  205. **TBD**
  206. ### Conguration with Boot Magic
  207. Boot Magic are executed during boot up time. Press Magic key below then pulgin keyboard cable.
  208. These settings are stored in EEPROM.
  209. - Clear configuration stored in EEPROM(`Backspace`)
  210. - Kick up Bootloader(`B`)
  211. - Debug enable(`D`)
  212. - Swap Control and CapsLock(`Left Control`)
  213. - Change CapsLock to Control(`Casp Lock`)
  214. - Swap LeftAlt and Gui(`Left Alt`)
  215. - Swap RightAlt and Gui(`Right Alt`)
  216. - Disable Gui(`Left Gui`)
  217. - Swap Grave and Escape(`Grave`)
  218. - Swap BackSlash and BackSpace(`Back Slash`)
  219. **TBD**
  220. Mechanical Locking support for CapsLock
  221. ---------------------------------------
  222. To 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.
  223. #define CAPSLOCK_LOCKING_ENABLE
  224. #define CAPSLOCK_LOCKING_RESYNC_ENABLE
  225. Start Your Own Project
  226. -----------------------
  227. **TBD**
  228. ### Config.h Options
  229. #### 1. USB vendor/product ID and device description
  230. #define VENDOR_ID 0xFEED
  231. #define PRODUCT_ID 0xBEEF
  232. /* device description */
  233. #define MANUFACTURER t.m.k.
  234. #define PRODUCT Macway mod
  235. #define DESCRIPTION t.m.k. keyboard firmware for Macway mod
  236. #### 2. Keyboard matrix configuration
  237. #define MATRIX_ROWS 8
  238. #define MATRIX_COLS 8
  239. #define MATRIX_HAS_GHOST
  240. Files & Directories
  241. -------------------
  242. ### Top
  243. * common/ - common codes
  244. * protocol/ - keyboard protocol support
  245. * keyboard/ - keyboard projects
  246. * converter/ - protocol converter projects
  247. * doc/ - documents
  248. * common.mk - Makefile for common
  249. * protoco.mk - Makefile for protocol
  250. * rules.mk - Makefile for build rules
  251. ### Common
  252. * action.[ch]
  253. * action_macro.[ch]
  254. * bootloader.[ch]
  255. * command.[ch]
  256. * controller_teensy.h
  257. * debug.[ch]
  258. * host.[ch]
  259. * host_driver.h
  260. * keyboard.[ch]
  261. * keycode.h
  262. * keymap.[ch]
  263. * led.h
  264. * matrix.h
  265. * mousekey.[ch]
  266. * print.[ch]
  267. * report.h
  268. * sendchar.h
  269. * sendchar_null.c
  270. * sendchar_uart.c
  271. * timer.[ch]
  272. * uart.[ch]
  273. * util.[ch]
  274. ### Keyboard Protocols
  275. * lufa/ - LUFA USB stack
  276. * pjrc/ - PJRC USB stack
  277. * vusb/ - Objective Development V-USB
  278. * iwrap/ - Bluetooth HID for Bluegiga iWRAP
  279. * ps2.c - PS/2 protocol
  280. * adb.c - Apple Desktop Bus protocol
  281. * m0110.c - Macintosh 128K/512K/Plus keyboard protocol
  282. * news.c - Sony NEWS keyboard protocol
  283. * x68k.c - Sharp X68000 keyboard protocol
  284. * serial_soft.c - Asynchronous Serial protocol implemented by software
  285. License
  286. -------
  287. Under `GPL` 2 or later. Some protocol files are under `Modified BSD License`.
  288. LUFA, PJRC and V-USB stack have their own license respectively.