X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=README.md;h=55fb76798b96229766d041be67de0c2f394bf5b7;hb=a085265aaa18cbaedfd7ff21364877b9c018083c;hp=d6d8fb4ec8a337ffc35d5913a0abdf6b1a183d01;hpb=81706d1130fdc3c0d6d110f4d8665c47ffd7fb59;p=qmk_firmware.git diff --git a/README.md b/README.md index d6d8fb4ec..55fb76798 100644 --- a/README.md +++ b/README.md @@ -1,184 +1,177 @@ -t.m.k. Keyboard Firmware Collection -==================================== -This is a keyboard firmware with some features for Atmel AVR controller. - -Source code is available here: - - -Features --------- -* Mouse key - Mouse control by keyboard -* System Control Key - Power Down, Sleep, Wake Up and USB Remote Wake up -* Media Control Key - Volume Down/Up, Mute, Next/Prev track, Play, Stop and etc. -* USB NKRO - Can send 120 keys(+ 8 modifiers) simultaneously. -* PS/2 mouse support - integrate PS/2 mouse(TrackPoint) into keyboard as composite device. - - -Projects --------- -### converter -* [ps2_usb][c1] - [PS/2 keyboard to USB][GH_ps2] -* [adb_usb][c2] - [ADB keyboard to USB][GH_adb] -* [m0110_usb][c3] - [Machintosh 128K/512K/Plus keyboard to USB][GH_m0110] -* [terminal_usb][c4] - [IBM Model M terminal keyboard(PS/2 scancode set3) to USB][GH_terminal] -* [news_usb][c5] - [Sony NEWS keyboard to USB][GH_news] -* [x68k_usb][c6] - [Sharp X68000 keyboard to USB][GH_x68k] - -### keyboard -* [hhkb][k1] - [Happy Hacking Keyboard professional][GH_hhkb] -* [macway][k2] - [Compact keyboard mod][GH_macway] -* [hbkb][k3] - [Happy Buckling sprint keyboard(IBM Model M mod)][GH_hbkb] - -[c1]: converter/ps2_usb/ -[c2]: converter/adb_usb/ -[c3]: converter/m0110_usb/ -[c4]: converter/terminal_usb/ -[c5]: converter/news_usb/ -[c6]: converter/x68k_usb/ -[k1]: keyboard/hhkb -[k2]: keyboard/macway -[k3]: keyboard/hbkb -[GH_macway]: http://geekhack.org/showwiki.php?title=Island:11930 -[GH_hhkb]: http://geekhack.org/showwiki.php?title=Island:12047 -[GH_ps2]: http://geekhack.org/showwiki.php?title=Island:14618 -[GH_adb]: http://geekhack.org/showwiki.php?title=Island:14290 -[GH_hhkb_bt]: http://geekhack.org/showwiki.php?title=Island:20851 -[GH_m0110]: http://geekhack.org/showwiki.php?title=Island:24965 -[GH_news]: http://geekhack.org/showwiki.php?title=Island:25759 -[GH_terminal]: http://geekhack.org/showwiki.php?title=Island:27272 -[GH_x68k]: http://geekhack.org/showwiki.php?title=Island:29060 -[GH_hbkb]: http://geekhack.org/showwiki.php?title=Island:29483 - - - -Files & Directories -------------------- -### Top -* [common/](common/) - common codes -* [protocol/](protocol/) - keyboard protocol support -* [keyboard/](keyboard/) - keyboard projects -* [converter/](converter/) - protocol converter projects -* [doc/](doc/) - documents - -### Keyboard Protocols -* [pjrc/](protocol/pjrc/) - PJRC USB stack -* [vusb/](protocol/vusb/) - Objective Development V-USB -* [iwrap/](protocol/iwrap) - Bluetooth HID for Bluegiga iWRAP -* [ps2.c](protocol/ps2.c) - PS/2 protocol -* [adb.c](protocol/adb.c) - Apple Desktop Bus protocol -* [m0110.c](protocol/m0110.c) - Macintosh 128K/512K/Plus keyboard protocol -* [news.c](protocol/news.c) - Sony NEWS keyboard protocol -* [x68k.c](protocol/x68k.c) - Sharp X68000 keyboard protocol - - -Build & Program ---------------- -### Build firmware -To compile you need `AVR GCC`, `AVR Libc` and `GNU make`. -You can use [WinAVR][winavr] on Windows and [CrossPack][crosspack] on Mac. - - $ cd - $ make - -The firmware will be compiled as a file `tmk_.hex`. - -[winavr]: http://winavr.sourceforge.net/ -[crosspack]: http://www.obdev.at/products/crosspack/index.html - -### Program Controller -If you have proper program command in Makefile just type this. - - $ make program - -As for `Teensy` you can use `PJRC's loader` to program hex file. - - - -Build Options -------------- -### `Makefile` -#### 1. MCU and Frequency. - MCU = atmega32u4 # Teensy 2.0 - #MCU = at90usb1286 # Teensy++ 2.0 - F_CPU = 16000000 - -#### 2. Features -Note that ***comment out*** to disable them. - MOUSEKEY_ENABLE = yes # Mouse keys - PS2_MOUSE_ENABLE = yes # PS/2 mouse(TrackPoint) support - EXTRAKEY_ENABLE = yes # Enhanced feature for Windows(Audio control and System control) - NKRO_ENABLE = yes # USB Nkey Rollover - -#### 3. Programmer -Set proper command for your controller, bootloader and programmer. - # for PJRC Teensy - PROGRAM_CMD = teensy_loader_cli -mmcu=$(MCU) -w -v $(TARGET).hex - - # for Atmel AT90USBKEY - PROGRAM_CMD = dfu-programmer $(MCU) flash $(TARGET).hex - - # avrdude - PROGRAM_CMD = avrdude -p $(MCU) -c avrispmkII -P USB -U flash:w:$(TARGET).hex - PROGRAM_CMD = avrdude -p $(MCU) -c usbasp -U flash:w:$(TARGET).hex - PROGRAM_CMD = avrdude -p $(MCU) -c arduino -P COM1 -b 57600 -U flash:w:$(TARGET).hex - -### `config.h` -#### 1. USB vendor/product ID and device description - #define VENDOR_ID 0xFEED - #define PRODUCT_ID 0xBEEF - /* device description */ - #define MANUFACTURER t.m.k. - #define PRODUCT Macway mod - #define DESCRIPTION t.m.k. keyboard firmware for Macway mod - -#### 2. Keyboard matrix configuration - #define MATRIX_ROWS 8 - #define MATRIX_COLS 8 - #define MATRIX_HAS_GHOST +# Quantum MK Firmware -### 3. Mouse keys configuration +This is a keyboard firmware based on the [tmk_keyboard firmware](http://github.com/tmk/tmk_keyboard) with some useful features for Atmel AVR controllers, and more specifically, the [OLKB product line](http://olkb.co) and the [ErgoDox EZ](http://www.ergodox-ez.com) keyboard. -### 4. PS/2 mouse configuration +QMK is developed and maintained by Jack Humbert of OLKB with contributions from the community, and of course, TMK. +This documentation is edited and maintained by Erez Zukerman of ErgoDox EZ. If you spot any typos or inaccuracies, please [open an issue](https://github.com/jackhumbert/qmk_firmware/issues/new). -Keymap ------- +## Important background info: TMK documentation +The documentation below explains QMK customizations and elaborates on some of the more useful features of TMK. To understand the base firmware, and especially what *layers* are and how they work, please see [TMK_README.md](/TMK_README.md). -Build your own firmware ------------------------ +## Getting started +* **If you're looking to customize a keyboard that currently runs QMK or TMK** , find your keyboard's directory under `/keyboard/` and read the README file. This will get you all set up. +* If you're looking to apply this firmware to an entirely new hardware project (a new kind of keyboard), you can create your own Quantum-based project by using `./new_project.sh `, which will create `/keyboard/` with all the necessary components for a Quantum project. -Debuging --------- -Use PJRC's `hid_listen` to see debug messages and press ` + H` to debug menu. -See `config.h` for definition of `` key combination. +You have access to a bunch of goodies! Check out the Makefile to enable/disable some of the features. Uncomment the `#` to enable them. Setting them to `no` does nothing and will only confuse future you. + BACKLIGHT_ENABLE = yes # Enable keyboard backlight functionality + MIDI_ENABLE = yes # MIDI controls + # UNICODE_ENABLE = yes # Unicode support - this is commented out, just as an example. You have to use #, not // + BLUETOOTH_ENABLE = yes # Enable Bluetooth with the Adafruit EZ-Key HID -Other Keyboard Projects ------------------------ -### PJRC USB Keyboard/Mouse Example -- -- +## Quick aliases to common actions -### kbupgrade -- -- +Your keymap can include shortcuts to common operations (called "function actions" in tmk). -### c64key -- +### Switching and toggling layers -### rump -- -- +`MO(layer)` - momentary switch to *layer*. As soon as you let go of the key, the layer is deactivated and you pop back out to the previous layer. When you apply this to a key, that same key must be set as `KC_TRNS` on the destination layer. Otherwise, you won't make it back to the original layer when you release the key (and you'll get a keycode sent). You can only switch to layers *above* your current layer. If you're on layer 0 and you use `MO(1)`, that will switch to layer 1 just fine. But if you include `MO(3)` on layer 5, that won't do anything for you -- because layer 3 is lower than layer 5 on the stack. -### dulcimer -- +`LT(layer, kc)` - momentary switch to *layer* when held, and *kc* when tapped. Like `MO()`, this only works upwards in the layer stack (`layer` must be higher than the current layer). -### humblehacker-keyboard -- -- -- +`TG(layer)` - toggles a layer on or off. As with `MO()`, you should set this key as `KC_TRNS` in the destination layer so that tapping it again actually toggles back to the original layer. Only works upwards in the layer stack. -### ps2avr -- +### Fun with modifier keys + +* `LSFT(kc)` - applies left Shift to *kc* (keycode) - `S(kc)` is an alias +* `RSFT(kc)` - applies right Shift to *kc* +* `LCTL(kc)` - applies left Control to *kc* +* `RCTL(kc)` - applies right Control to *kc* +* `LALT(kc)` - applies left Alt to *kc* +* `RALT(kc)` - applies right Alt to *kc* +* `LGUI(kc)` - applies left GUI (command/win) to *kc* +* `RGUI(kc)` - applies right GUI (command/win) to *kc* +* `HYPR(kc)` - applies Hyper (all modifiers) to *kc* +* `MEH(kc)` - applies Meh (all modifiers except Win/Cmd) to *kc* + +You can also chain these, like this: + + LALT(LCTL(KC_DEL)) -- this makes a key that sends Alt, Control, and Delete in a single keypress. + +The following shortcuts automatically add `LSFT()` to keycodes to get commonly used symbols. Their long names are also available and documented in `/quantum/keymap_common.h`. + + KC_TILD ~ + KC_EXLM ! + KC_AT @ + KC_HASH # + KC_DLR $ + KC_PERC % + KC_CIRC ^ + KC_AMPR & + KC_ASTR * + KC_LPRN ( + KC_RPRN ) + KC_UNDS _ + KC_PLUS + + KC_LCBR { + KC_RCBR } + KC_PIPE | + KC_COLN : + +`MT(mod, kc)` - is *mod* (modifier key - MOD_LCTL, MOD_LSFT) when held, and *kc* when tapped. In other words, you can have a key that sends Esc (or the letter O or whatever) when you tap it, but works as a Control key or a Shift key when you hold it down. + +These are the values you can use for the `mod` in `MT()` (right-hand modifiers are not available): + + * MOD_LCTL + * MOD_LSFT + * MOD_LALT + * MOD_LGUI + +These can also be combined like `MOD_LCTL | MOD_LSFT` e.g. `MT(MOD_LCTL | MOD_LSFT, KC_ESC)` which would activate Control and Shift when held, and send Escape when tapped. + +We've added shortcuts to make common modifier/tap (mod-tap) mappings more compact: + + * `CTL_T(kc)` - is LCTL when held and *kc* when tapped + * `SFT_T(kc)` - is LSFT when held and *kc* when tapped + * `ALT_T(kc)` - is LALT when held and *kc* when tapped + * `GUI_T(kc)` - is LGUI when held and *kc* when tapped + * `ALL_T(kc)` - is Hyper (all mods) when held and *kc* when tapped. To read more about what you can do with a Hyper key, see [this blog post by Brett Terpstra](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/) + * `MEH_T(kc)` - is like Hyper, but not as cool -- does not include the Cmd/Win key, so just sends Alt+Ctrl+Shift. + +### Temporarily setting the default layer + +`DF(layer)` - sets default layer to *layer*. The default layer is the one at the "bottom" of the layer stack - the ultimate fallback layer. This currently does not persist over power loss. When you plug the keyboard back in, layer 0 will always be the default. It is theoretically possible to work around that, but that's not what `DF` does. + +### Remember: These are just aliases + +These functions work the same way that their `ACTION_*` functions do - they're just quick aliases. To dig into all of the tmk ACTION_* functions, please see the [TMK documentation](https://github.com/jackhumbert/qmk_firmware/blob/master/tmk_core/doc/keymap.md#2-action). + +Instead of using `FNx` when defining `ACTION_*` functions, you can use `F(x)` - the benefit here is being able to use more than 32 function actions (up to 4096), if you happen to need them. + +## Macro shortcuts: Send a whole string when pressing just one key + +Instead of using the `ACTION_MACRO` function, you can simply use `M(n)` to access macro *n* - *n* will get passed into the `action_get_macro` as the `id`, and you can use a switch statement to trigger it. This gets called on the keydown and keyup, so you'll need to use an if statement testing `record->event.pressed` (see keymap_default.c). + +```c +const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) // this is the function signature -- just copy/paste it into your keymap file as it is. +{ + switch(id) { + case 0: // this would trigger when you hit a key mapped as M(0) + if (record->event.pressed) { + return MACRO( I(255), T(H), T(E), T(L), T(L), W(255), T(O), END ); // this sends the string 'hello' when the macro executes + } + break; + } + return MACRO_NONE; +}; +``` +A macro can include the following commands: + +* I() change interval of stroke in milliseconds. +* D() press key. +* U() release key. +* T() type key(press and release). +* W() wait (milliseconds). +* END end mark. + +So above you can see the stroke interval changed to 255ms between each keystroke, then a bunch of keys being typed, waits a while, then the macro ends. + +Note: Using macros to have your keyboard send passwords for you is a bad idea. + +### Additional keycode aliases for software-implemented layouts (Colemak, Dvorak, etc) + +Everything is assuming you're in Qwerty (in software) by default, but there is built-in support for using a Colemak or Dvorak layout by including this at the top of your keymap: + + #include "keymap_.h" + +Where is "colemak" or "dvorak". After including this line, you will get access to: + + * `CM_*` for all of the Colemak-equivalent characters + * `DV_*` for all of the Dvorak-equivalent characters + +These implementations assume you're using Colemak or Dvorak on your OS, not on your keyboard - this is referred to as a software-implemented layout. If your computer is in Qwerty and your keymap is in Colemak or Dvorak, this is referred to as a firmware-implemented layout, and you won't need these features. + +To give an example, if you're using software-implemented Colemak, and want to get an `F`, you would use `CM_F` - `KC_F` under these same circumstances would result in `T`. + +## Additional language support + +In `quantum/keymap_extras/`, you'll see various language files - these work the same way as the alternative layout ones do. Most are defined by their two letter country/language code followed by an underscore and a 4-letter abbreviation of its name. `FR_UGRV` which will result in a `ù` when using a software-implemented AZERTY layout. It's currently difficult to send such characters in just the firmware (but it's being worked on - see Unicode support). + +## Unicode support + +You can currently send 4 hex digits with your OS-specific modifier key (RALT for OSX with the "Unicode Hex Input" layout) - this is currently limited to supporting one OS at a time, and requires a recompile for switching. 8 digit hex codes are being worked on. The keycode function is `UC(n)`, where *n* is a 4 digit hexidecimal. Enable from the Makefile. + +## Other firmware shortcut keycodes + +* `RESET` - puts the MCU in DFU mode for flashing new firmware (with `make dfu`) +* `DEBUG` - the firmware into debug mode - you'll need hid_listen to see things +* `BL_ON` - turns the backlight on +* `BL_OFF` - turns the backlight off +* `BL_` - sets the backlight to level *n* +* `BL_INC` - increments the backlight level by one +* `BL_DEC` - decrements the backlight level by one +* `BL_TOGG` - toggles the backlight +* `BL_STEP` - steps through the backlight levels + +Enable the backlight from the Makefile. + +## MIDI functionalty + +This is still a WIP, but check out `quantum/keymap_midi.c` to see what's happening. Enable from the Makefile. + +## Bluetooth functionality + +This requires [some hardware changes](https://www.reddit.com/r/MechanicalKeyboards/comments/3psx0q/the_planck_keyboard_with_bluetooth_guide_and/?ref=search_posts), but can be enabled via the Makefile. The firmware will still output characters via USB, so be aware of this when charging via a computer. It would make sense to have a switch on the Bluefruit to turn it off at will.