## How to customize {#how-to-customize}
-QMK has lots of [features](features/README.md) to explore, and a good deal of [reference documentation](reference/README.md) to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md).
+QMK has lots of [features](features.md) to explore, and a good deal of [reference documentation](http://docs.qmk.fm) to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md).
* [Bootmagic](feature_bootmagic.md)
* [Dynamic Macros](dynamic_macros.md)
* [Key Lock](key_lock.md)
- * [Leader Key](leader_key.md)
+ * [Leader Key](feature_leader_key.md)
* [Macros](macros.md)
* [Mouse keys](mouse_keys.md)
+ * [PS2 Mouse](feature_ps2_mouse.md)
* [Space Cadet](space_cadet_shift.md)
* [Tap Dance](tap_dance.md)
* [Thermal Printer](feature_thermal_printer.md)
* [Glossary](glossary.md)
* [Keymap overview](keymap.md)
* [Keycodes](keycodes.md)
- * [Basic](basic_keycodes.md)
+ * [Basic](keycodes_basic.md)
* [Quantum](quantum_keycodes.md)
* [Backlight](feature_backlight.md#backlight-keycodes)
* [Bluetooth](feature_bluetooth.md#bluetooth-keycodes)
* [Mod Tap](feature_common_shortcuts.md#mod-tap)
* [One Shot Keys](feature_common_shortcuts.md#one-shot-keys)
* [Shifted Keys](feature_common_shortcuts.md#shifted-keycodes)
+ * [Stenography](stenography.md#keycode-reference)
* [RGB Light](feature_rgblight.md#rgblight-keycodes)
* [Thermal Printer](feature_thermal_printer.md#thermal-printer-keycodes)
* [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
* [Porting your keyboard to QMK](porting_your_keyboard_to_qmk.md)
* For a Deeper Understanding
- * [How Keyboards Work](basic_how_keyboards_work.md)
+ * [How Keyboards Work](how_keyboards_work.md)
* [Understanding QMK](understanding_qmk.md)
* Other Topics
* **Disabled by default** - memory is a pretty limited on most chips QMK supports, and it's important that current keymaps aren't broken, so please allow your feature to be turned **on**, rather than being turned off. If you think it should be on by default, or reduces the size of the code, please talk with us about it.
* **Compile locally before submitting** - hopefully this one is obvious, but things need to compile! Our Travis system will catch any issues, but it's generally faster for you to compile a few keyboards locally instead of waiting for the results to come back.
-* **Consider subprojects and different chip-bases** - there are several keyboards that have subprojects that have allow for slightly different configurations, and even different chip-bases. Try to make a feature supported in ARM and AVR, or automatically disabled in one that doesn't work.
+* **Consider subprojects and different chip-bases** - there are several keyboards that have subprojects that allow for slightly different configurations, and even different chip-bases. Try to make a feature supported in ARM and AVR, or automatically disabled on platforms it doesn't work on.
* **Explain your feature** - Document it in `docs/`, either as a new file or as part of an existing file. If you don't document it other people won't be able to benefit from your hard work.
-* **Don't refactor code** - to maintain a clear vision of how things are laid out in QMK, we try to plan out refactors in-depth, and have a collaborator make the changes. If you have an idea for refactoring, or suggestions, [open an issue](https://github.com/qmk/qmk_firmware/issues).
+* **Don't refactor code** - to maintain a clear vision of how things are laid out in QMK, we try to plan out refactors in-depth, and have a collaborator make the changes. If you have an idea for refactoring, or suggestions, [open an issue](https://github.com/qmk/qmk_firmware/issues), we'd love to talk about how QMK can be improved.
+++ /dev/null
-# How keys are registered, and interpreted by computers
-
-In this file, you can will learn the concepts of how keyboards work over USB,
-and you'll be able to better understand what you can expect from changing your
-firmware directly.
-
-## Schematic view
-
-Whenever you type on 1 particular key, here is the chain of actions taking
-place:
-
-``` text
-+------+ +-----+ +----------+ +----------+ +----+
-| User |-------->| Key |------>| Firmware |----->| USB wire |---->| OS |
-+------+ +-----+ +----------+ +----------+ |----+
-```
-
-This scheme is a very simple view of what's going on, and more details follow
-in the next sections.
-
-## 1. You Press a Key
-
-Whenever you press a key, the firmware of your keyboard can register this event.
-It can register when the key is pressed, held and released.
-
-This usually happens with a periodic scan of key presses. This speed often is limited by the mechanical key response time, the protocol to transfer those key presses (here USB HID), and by the software it is used in.
-
-## 2. What the Firmware Sends
-
-The [HID specification](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) tells what a keyboard can actually send through USB to have a chance to be properly recognised. This includes a pre-defined list of scancodes which are simple numbers from `0x00` to `0xE7`. The firmware assigns a scancode to each key of the keyboard.
-
-The firmware does not send actually letters or characters, but only scancodes.
-Thus, by modifying the firmware, you only can modify what scancode is sent over
-USB for a given key.
-
-## 3. What the Operating System Does
-
-Once the keycode reaches the operating system, a piece of software has to have
-it match an actual character thanks to a keyboard layout. For example, if your
-layout is set to QWERTY, a sample of the matching table is as follow:
-
-| keycode | character |
-|---------|-----------|
-| 0x04 | a/A |
-| 0x05 | b/B |
-| 0x06 | c/C |
-| ... | ... |
-| 0x1C | y/Y |
-| 0x1D | z/Z |
-| ... | ... |
-
-## Back to the firmware
-
-As the layout is generally fixed (unless you create your own), the firmware can actually call a keycode by its layout name directly to ease things for you. This is exactly what is done here with `KC_A` actually representing `0x04` in QWERTY. The full list can be found in `keycode.txt`.
-
-## List of Characters You Can Send
-
-Putting aside shortcuts, having a limited set of keycodes mapped to a limited layout means that **the list of characters you can assign to a given key only is the ones present in the layout**.
-
-For example, this means that if you have a QWERTY US layout, and you want to assign 1 key to produce `€` (euro currency symbol), you are unable to do so, because the QWERTY US layout does not have such mapping. You could fix that by using a QWERTY UK layout, or a QWERTY US International.
-
-You may wonder why a keyboard layout containing all of Unicode is not devised then? The limited number of keycode available through USB simply disallow such a thing.
-
-## How to (Maybe) Enter Unicode Characters
-
-You can have the firmware send *sequences of keys* to use the [software Unicode Input Method](https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_code_input) of the target operating system, thus effectively entering characters independently of the layout defined in the OS.
-
-Yet, it does come with multiple disadvantages:
-
- - Tied to a specific OS a a time (need recompilation when changing OS);
- - Within a given OS, does not work in all software;
- - Limited to a subset of Unicode on some systems.
+++ /dev/null
-# Basic keycodes
-
-Basic keycodes are based on [HID Usage Keyboard/Keypad Page(0x07)](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) with following exceptions:
-
-* `KC_NO` = 0 for no action
-* `KC_TRNS` = 1 for layer transparency
-* internal special keycodes in the `0xA5-DF` range (tmk heritage).
-
-## Letters and Numbers
-
-|KC_1|KC_2|KC_3|KC_4|KC_5|KC_6|KC_7|KC_8|
-|----|----|----|----|----|----|----|----|
-|KC_9|KC_0|KC_F1|KC_F2|KC_F3|KC_F4|KC_F5|KC_F6|
-|KC_F7|KC_F8|KC_F9|KC_F10|KC_F11|KC_F12|KC_F13|KC_F14|
-|KC_F15|KC_F16|KC_F17|KC_F18|KC_F19|KC_F20|KC_F21|KC_F22|
-|KC_F23|KC_F24|KC_A|KC_B|KC_C|KC_D|KC_E|KC_F|
-|KC_G|KC_H|KC_I|KC_J|KC_K|KC_L|KC_M|KC_N|
-|KC_O|KC_P|KC_Q|KC_R|KC_S|KC_T|KC_U|KC_V|
-|KC_W|KC_X|KC_Y|KC_Z|||||
-
-## Punctuation
-
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
-|KC_ENTER|KC_ENT|`Return (ENTER)`|
-|KC_ESCAPE|KC_ESC|`ESCAPE`|
-|KC_BSPACE|KC_BSPC|`DELETE (Backspace)`|
-|KC_TAB||`Tab`|
-|KC_SPACE|KC_SPC|Spacebar|
-|KC_MINUS|KC_MINS|`-` and `_`|
-|KC_EQUAL|KC_EQL|`=` and `+`|
-|KC_LBRACKET|KC_LBRC|`[` and `{`|
-|KC_RBRACKET|KC_RBRC|`]` and `}`|
-|KC_BSLASH|KC_BSLS|`\` and <code>|</code> |
-|KC_NONUS_HASH|KC_NUHS|Non-US `#` and `~`|
-|KC_NONUS_BSLASH|KC_NUBS|Non-US `\` and <code>|</code> |
-|KC_INT1|KC_RO|JIS `\` and <code>|</code> |
-|KC_INT2|KC_KANA|International216|
-|KC_INT3|KC_JYEN|Yen Symbol (`¥`)|
-|KC_SCOLON|KC_SCLN|`;` and `:`|
-|KC_QUOTE|KC_QUOT|`‘` and `“`|
-|KC_GRAVE|KC_GRV|Grave Accent and Tilde|
-|KC_COMMA|KC_COMM|`,` and `<`|
-|KC_DOT||`.` and `>`|
-|KC_SLASH|KC_SLSH|`/` and `?`|
-|KC_CAPSLOCK|KC_CAPS|Caps Lock|
-
-## Modifiers
-
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
-|KC_LCTRL|KC_LCTL|LeftControl|
-|KC_LSHIFT|KC_LSFT|LeftShift|
-|KC_LALT||LeftAlt|
-|KC_LGUI||Left GUI(Windows/Apple/Meta key)|
-|KC_RCTRL|KC_RCTL|RightControl|
-|KC_RSHIFT|KC_RSFT|RightShift|
-|KC_RALT||RightAlt|
-|KC_RGUI||Right GUI(Windows/Apple/Meta key)|
-|KC_LOCKING_CAPS|KC_LCAP|Locking Caps Lock|
-|KC_LOCKING_NUM|KC_LNUM|Locking Num Lock|
-|KC_LOCKING_SCROLL|KC_LSCR|Locking Scroll Lock|
-|KC_INT4|KC_HENK|JIS Henken|
-|KC_INT5|KC_MHEN|JIS Muhenken|
-
-## Commands
-
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
-|KC_PSCREEN|KC_PSCR|PrintScreen|
-|KC_SCROLLLOCK|KC_SLCK|Scroll Lock|
-|KC_PAUSE|KC_PAUS|Pause|
-|KC_INSERT|KC_INS|Insert|
-|KC_HOME||Home|
-|KC_PGUP||PageUp|
-|KC_DELETE|KC_DEL|Delete Forward|
-|KC_END||End|
-|KC_PGDOWN|KC_PGDN|PageDown|
-|KC_RIGHT|KC_RGHT|RightArrow|
-|KC_LEFT||LeftArrow|
-|KC_DOWN||DownArrow|
-|KC_UP||UpArrow|
-|KC_APPLICATION|KC_APP|Application|
-|KC_POWER||Power|
-|KC_EXECUTE||Execute|
-|KC_HELP||Help|
-|KC_MENU||Menu|
-|KC_SELECT||Select|
-|KC_AGAIN||Again|
-|KC_UNDO||Undo|
-|KC_CUT||Cut|
-|KC_COPY||Copy|
-|KC_PASTE||Paste|
-|KC_FIND||Find|
-|KC_ALT_ERASE||Alternate Erase|
-|KC_SYSREQ||SysReq/Attention|
-|KC_CANCEL||Cancel|
-|KC_CLEAR||Clear|
-|KC_PRIOR||Prior|
-|KC_RETURN||Return|
-|KC_SEPARATOR||Separator|
-|KC_OUT||Out|
-|KC_OPER||Oper|
-|KC_CLEAR_AGAIN||Clear/Again|
-|KC_CRSEL||CrSel/Props|
-|KC_EXSEL||ExSel|
-|KC_SYSTEM_POWER|KC_PWR|System Power Down|
-|KC_SYSTEM_SLEEP|KC_SLEP|System Sleep|
-|KC_SYSTEM_WAKE|KC_WAKE|System Wake|
-|KC_MAIL|KC_MAIL||
-|KC_CALCULATOR|KC_CALC||
-|KC_MY_COMPUTER|KC_MYCM||
-|KC_WWW_SEARCH|KC_WSCH||
-|KC_WWW_HOME|KC_WHOM||
-|KC_WWW_BACK|KC_WBAK||
-|KC_WWW_FORWARD|KC_WFWD||
-|KC_WWW_STOP|KC_WSTP||
-|KC_WWW_REFRESH|KC_WREF||
-|KC_WWW_FAVORITES|KC_WFAV||
-
-## Media Keys
-
-Windows and Mac use different key codes for next track and previous track. Make sure you choose the keycode that corresponds to your OS.
-
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
-|KC_STOP||Stop|
-|KC__MUTE||Mute|
-|KC__VOLUP||Volume Up|
-|KC__VOLDOWN||Volume Down|
-|KC_AUDIO_MUTE|KC_MUTE||
-|KC_AUDIO_VOL_UP|KC_VOLU||
-|KC_AUDIO_VOL_DOWN|KC_VOLD||
-|KC_MEDIA_NEXT_TRACK|KC_MNXT|Next Track (Windows)|
-|KC_MEDIA_PREV_TRACK|KC_MPRV|Previous Track (Windows)|
-|KC_MEDIA_FAST_FORWARD|KC_MFFD|Next Track (macOS)|
-|KC_MEDIA_REWIND|KC_MRWD|Previous Track (macOS)|
-|KC_MEDIA_STOP|KC_MSTP||
-|KC_MEDIA_PLAY_PAUSE|KC_MPLY||
-|KC_MEDIA_SELECT|KC_MSEL||
-
-## Numpad
-
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
-|KC_NUMLOCK|KC_NLCK|Keypad Num Lock and Clear|
-|KC_KP_SLASH|KC_PSLS|Keypad /|
-|KC_KP_ASTERISK|KC_PAST|Keypad *|
-|KC_KP_MINUS|KC_PMNS|Keypad -|
-|KC_KP_PLUS|KC_PPLS|Keypad +|
-|KC_KP_ENTER|KC_PENT|Keypad ENTER|
-|KC_KP_1|KC_P1|Keypad 1 and End|
-|KC_KP_2|KC_P2|Keypad 2 and Down Arrow|
-|KC_KP_3|KC_P3|Keypad 3 and PageDn|
-|KC_KP_4|KC_P4|Keypad 4 and Left Arrow|
-|KC_KP_5|KC_P5|Keypad 5|
-|KC_KP_6|KC_P6|Keypad 6 and Right Arrow|
-|KC_KP_7|KC_P7|Keypad 7 and Home|
-|KC_KP_8|KC_P8|Keypad 8 and Up Arrow|
-|KC_KP_9|KC_P9|Keypad 9 and PageUp|
-|KC_KP_0|KC_P0|Keypad 0 and Insert|
-|KC_KP_DOT|KC_PDOT|Keypad . and Delete|
-|KC_KP_EQUAL|KC_PEQL|Keypad =|
-|KC_KP_COMMA|KC_PCMM|Keypad Comma|
-|KC_KP_EQUAL_AS400||Keypad Equal Sign|
-
-## Special Keys
-
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
-|KC_NO||Ignore this key. (NOOP) |
-
-## Mousekey
-
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
-|KC_MS_UP|KC_MS_U|Mouse Cursor Up|
-|KC_MS_DOWN|KC_MS_D|Mouse Cursor Down|
-|KC_MS_LEFT|KC_MS_L|Mouse Cursor Left|
-|KC_MS_RIGHT|KC_MS_R|Mouse Cursor Right|
-|KC_MS_BTN1|KC_BTN1|Mouse Button 1|
-|KC_MS_BTN2|KC_BTN2|Mouse Button 2|
-|KC_MS_BTN3|KC_BTN3|Mouse Button 3|
-|KC_MS_BTN4|KC_BTN4|Mouse Button 4|
-|KC_MS_BTN5|KC_BTN5|Mouse Button 5|
-|KC_MS_WH_UP|KC_WH_U|Mouse Wheel Up|
-|KC_MS_WH_DOWN|KC_WH_D|Mouse Wheel Down|
-|KC_MS_WH_LEFT|KC_WH_L|Mouse Wheel Left|
-|KC_MS_WH_RIGHT|KC_WH_R|Mouse Wheel Right|
-|KC_MS_ACCEL0|KC_ACL0|Mouse Acceleration 0|
-|KC_MS_ACCEL1|KC_ACL1|Mouse Acceleration 1|
-|KC_MS_ACCEL2|KC_ACL2|Mouse Acceleration 2|
What about an error message?
**[error [ERROR] This is not the error you are looking for]
```
+
+# Documenting Features
+
+If you create a new feature for QMK, create a documentation page for it. It doesn't have to be very long, a few sentances describing your feature and a table listing any relevant keycodes is enough. Here is a basic template:
+
+```markdown
+# My Cool Feature
+
+This page describes my cool feature. You can use my cool feature to make coffee and order cream and sugar to be delivered via drone.
+
+## My Cool Feature Keycodes
+
+|Long Name|Short Name|Description|
+|---------|----------|-----------|
+|KC_COFFEE||Make Coffee|
+|KC_CREAM||Order Cream|
+|KC_SUGAR||Order Sugar|
+```
+
+Place your documentation into `docs/feature_<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_summary.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.
# Frequently Asked Build Questions
-This page covers questions about building QMK. If you have not yet you should read the [Build Guide](https://github.com/qmk/qmk_firmware/blob/master/docs/build_guide.md).
-
-In short,
-
- $ make [-f Makefile.<variant>] [KEYMAP=...] clean
- $ make [-f Makefile.<variant>] [KEYMAP=...]
- $ make [-f Makefile.<variant>] [KEYMAP=...] dfu
-
+This page covers questions about building QMK. If you have not yet you should read the [Build Environment Setup](build_environment_setup.md) and [Make Instructions](make_instructions.md) guides.
## Can't program on Linux
-You will need proper permission to operate a device. For Linux users see udev rules below.
-Easy way is to use `sudo` command, if you are not familiar with this command check its manual with `man sudo` or this page on line.
+You will need proper permission to operate a device. For Linux users see udev rules below. Easy way is to use `sudo` command, if you are not familiar with this command check its manual with `man sudo` or this page on line.
In short when your controller is ATMega32u4,
or just
- $ sudo make dfu
+ $ sudo make <keyboard>-<keymap>-dfu
-But to run `make` with root privilege is not good idea. Use former method as possible.
+But to run `make` with root privilege is not good idea. Use former method if possible.
## WINAVR is obsolete
It is no longer recommended and may cause some problem.
-See [Issue #99](https://github.com/tmk/tmk_keyboard/issues/99).
+See [TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99).
## USB VID and PID
-You can use any ID you want with editing `config.h`. Using any presumably unused ID will be no problem in fact except for very least chance of collision with other product.
+You can use any ID you want with editing `config.h`. Using any presumably unused ID will be no problem in fact except for very low chance of collision with other product.
Most boards in QMK use `0xFEED` as the vendor ID. You should look through other keyboards to make sure you pick a unique Product ID.
- http://www.obdev.at/products/vusb/license.html
- http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1
-
## Linux udev rules
On Linux you need proper privilege to access device file of MCU, you'll have to use `sudo` when flashing firmware. You can circumvent this with placing these files in `/etc/udev/rules.d/`.
***
# Miscellaneous
+## Safety Considerations
+
+You probably don't want to "brick" your keyboard, making it impossible
+to rewrite firmware onto it. Here are some of the parameters to show
+what things are (and likely aren't) too risky.
+
+- If your keyboard map does not include RESET, then, to get into DFU
+ mode, you will need to press the reset button on the PCB, which
+ requires unscrewing the bottom.
+- Messing with tmk_core / common files might make the keyboard
+ inoperable
+- Too large a .hex file is trouble; `make dfu` will erase the block,
+ test the size (oops, wrong order!), which errors out, failing to
+ flash the keyboard, leaving it in DFU mode.
+ - To this end, note that the maximum .hex file size on Planck is
+ 7000h (28672 decimal)
+
+```
+Linking: .build/planck_rev4_cbbrowne.elf [OK]
+Creating load file for Flash: .build/planck_rev4_cbbrowne.hex [OK]
+
+Size after:
+ text data bss dec hex filename
+ 0 22396 0 22396 577c planck_rev4_cbbrowne.hex
+```
+
+ - The above file is of size 22396/577ch, which is less than
+ 28672/7000h
+ - As long as you have a suitable alternative .hex file around, you
+ can retry, loading that one
+ - Some of the options you might specify in your keyboard's Makefile
+ consume extra memory; watch out for BOOTMAGIC_ENABLE,
+ MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE
+- DFU tools do /not/ allow you to write into the bootloader (unless
+ you throw in extra fruitsalad of options), so there is little risk
+ there.
+- EEPROM has around a 100000 write cycle. You shouldn't rewrite the
+ firmware repeatedly and continually; that'll burn the EEPROM
+ eventually.
## NKRO Doesn't work
First you have to compile frimware with this build option `NKRO_ENABLE` in **Makefile**.
TMK was originally designed and implemented by [Jun Wako](https://github.com/tmk). QMK started as [Jack Humbert's](https://github.com/jackhumbert) fork of TMK for the Planck. After a while Jack's fork had diverged quite a bit from TMK, and in 2015 Jack decided to rename his fork to QMK.
-From a technical standpoint QMK builds upon TMK by adding several new features. Most notably QMK has expanded the number of available keycodes and uses these to implement advanced features like `S()`, `LCTL()`, and `MO()`. You can see a complete list of these keycodes in [Quantum Keycodes](quantum_keycodes.html).
+From a technical standpoint QMK builds upon TMK by adding several new features. Most notably QMK has expanded the number of available keycodes and uses these to implement advanced features like `S()`, `LCTL()`, and `MO()`. You can see a complete list of these keycodes in [Keycodes](keycodes.md).
-From a project and community management standpoint TMK maintains all the officially supported keyboards by himself, with a bit of community support. Separate community maintained forks exist or can be created for other keyboards. Only a few keymaps are provided by default, so users typically don't share keymaps with each other. QMK encourages sharing of both keyboards and keymaps through a centrally managed repository, accepting all pull requests that follows the quality standards. These are mostly community maintained, but the QMK team also helps when necessary.
+From a project and community management standpoint TMK maintains all the officially supported keyboards by himself, with a bit of community support. Separate community maintained forks exist or can be created for other keyboards. Only a few keymaps are provided by default, so users typically don't share keymaps with each other. QMK encourages sharing of both keyboards and keymaps through a centrally managed repository, accepting all pull requests that follow the quality standards. These are mostly community maintained, but the QMK team also helps when necessary.
Both approaches have their merits and their drawbacks, and code flows freely between TMK and QMK when it makes sense.
# Keymap FAQ
-This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap.html) first.
+This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap.md) first.
## What Keycodes Can I Use?
-See [Basic Keycodes](keycodes.html) and [Quantum Keycodes](quantum_keycodes.html) for most of the keys you can define.
+See [Keycodes](keycodes.md) for an index of keycodes available to you. These link to more extensive documentation when available.
Keycodes are actually defined in [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h).
# Audio
+Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any AVR keyboard that allows access to the C6 or B5 port (`#define C6_AUDIO` and/or `#define B5_AUDIO`), you can hook up a simple speaker and make it beep. You can use those beeps to indicate layer transitions, modifiers, special keys, or just to play some funky 8bit tunes.
+
+If you add `AUDIO_ENABLE = yes` to your `rules.mk`, there's a couple different sounds that will automatically be enabled without any other configuration:
+
+```
+STARTUP_SONG // plays when the keyboard starts up (audio.c)
+GOODBYE_SONG // plays when you press the RESET key (quantum.c)
+AG_NORM_SONG // plays when you press AG_NORM (quantum.c)
+AG_SWAP_SONG // plays when you press AG_SWAP (quantum.c)
+MUSIC_ON_SONG // plays when music mode is activated (process_music.c)
+MUSIC_OFF_SONG // plays when music mode is deactivated (process_music.c)
+CHROMATIC_SONG // plays when the chromatic music mode is selected (process_music.c)
+GUITAR_SONG // plays when the guitar music mode is selected (process_music.c)
+VIOLIN_SONG // plays when the violin music mode is selected (process_music.c)
+MAJOR_SONG // plays when the major music mode is selected (process_music.c)
+```
+
+You can override the default songs by doing something like this in your `config.h`:
+
+```c
+#ifdef AUDIO_ENABLE
+ #define STARTUP_SONG SONG(STARTUP_SOUND)
+#endif
+```
+
+A full list of sounds can be found in [quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) - feel free to add your own to this list! All available notes can be seen in [quantum/audio/musical_notes.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/musical_notes.h).
+
+To play a custom sound at a particular time, you can define a song like this (near the top of the file):
+
+```c
+float my_song[][2] = SONG(QWERTY_SOUND);
+```
+
+And then play your song like this:
+
+```c
+PLAY_SONG(my_song);
+```
+
+Alternatively, you can play it in a loop like this:
+
+```c
+PLAY_LOOP(my_song);
+```
+
+It's advised that you wrap all audio features in `#ifdef AUDIO_ENABLE` / `#endif` to avoid causing problems when audio isn't built into the keyboard.
+
+## Music mode
+
+The music mode maps your columns to a chromatic scale, and your rows to octaves. This works best with ortholinear keyboards, but can be made to work with others. All keycodes less than `0xFF` get blocked, so you won't type while playing notes - if you have special keys/mods, those will still work. A work-around for this is to jump to a different layer with KC_NOs before (or after) enabling music mode.
+
+Recording is experimental due to some memory issues - if you experience some weird behavior, unplugging/replugging your keyboard will fix things.
+
+Keycodes available:
+
+* `MU_ON` - Turn music mode on
+* `MU_OFF` - Turn music mode off
+* `MU_TOG` - Toggle music mode
+* `MU_MOD` - Cycle through the music modes:
+ * `CHROMATIC_MODE` - Chromatic scale, row changes the octave
+ * `GUITAR_MODE` - Chromatic scale, but the row changes the string (+5 st)
+ * `VIOLIN_MODE` - Chromatic scale, but the row changes the string (+7 st)
+ * `MAJOR_MODE` - Major scale
+
+In music mode, the following keycodes work differently, and don't pass through:
+
+* `LCTL` - start a recording
+* `LALT` - stop recording/stop playing
+* `LGUI` - play recording
+* `KC_UP` - speed-up playback
+* `KC_DOWN` - slow-down playback
+
+By default, `MUSIC_MASK` is set to `keycode < 0xFF` which means keycodes less than `0xFF` are turned into notes, and don't output anything. You can change this by defining this in your `config.h` like this:
+
+ #define MUSIC_MASK keycode != KC_NO
+
+Which will capture all keycodes - be careful, this will get you stuck in music mode until you restart your keyboard!
+
+The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`:
+
+ #define PITCH_STANDARD_A 432.0f
+
+## MIDI functionalty
+
+This is still a WIP, but check out `quantum/keymap_midi.c` to see what's happening. Enable from the Makefile.
+
<!-- FIXME: this formatting needs work
## Audio
# Bluetooth
-<!-- FIXME: Document bluetooth support. -->
+## 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.
+
+<!-- FIXME: Document bluetooth support more completely. -->
## Bluetooth Keycodes
### Limits of these aliases
-Currently, the keycodes able to used with these functions are limited to the [Basic Keycodes](keycodes.html), meaning you can't use keycodes like `KC_TILD`, or anything greater than 0xFF. For a full list of the keycodes able to be used see [Keycodes](keycodes.html).
+Currently, the keycodes able to used with these functions are limited to the [Basic Keycodes](keycodes_basic.html), meaning you can't use keycodes like `KC_TILD`, or anything greater than 0xFF. For a full list of the keycodes able to be used see [Basic Keycodes](keycodes_basic.html).
## Switching and toggling layers
--- /dev/null
+# The Leader key: A new kind of modifier
+
+If you've ever used Vim, you know what a Leader key is. If not, you're about to discover a wonderful concept. :) Instead of hitting Alt+Shift+W for example (holding down three keys at the same time), what if you could hit a _sequence_ of keys instead? So you'd hit our special modifier (the Leader key), followed by W and then C (just a rapid succession of keys), and something would happen.
+
+That's what `KC_LEAD` does. Here's an example:
+
+1. Pick a key on your keyboard you want to use as the Leader key. Assign it the keycode `KC_LEAD`. This key would be dedicated just for this -- it's a single action key, can't be used for anything else.
+2. Include the line `#define LEADER_TIMEOUT 300` somewhere in your keymap.c file, probably near the top. The 300 there is 300ms -- that's how long you have for the sequence of keys following the leader. You can tweak this value for comfort, of course.
+3. Within your `matrix_scan_user` function, do something like this:
+
+```
+LEADER_EXTERNS();
+
+void matrix_scan_user(void) {
+ LEADER_DICTIONARY() {
+ leading = false;
+ leader_end();
+
+ SEQ_ONE_KEY(KC_F) {
+ register_code(KC_S);
+ unregister_code(KC_S);
+ }
+ SEQ_TWO_KEYS(KC_A, KC_S) {
+ register_code(KC_H);
+ unregister_code(KC_H);
+ }
+ SEQ_THREE_KEYS(KC_A, KC_S, KC_D) {
+ register_code(KC_LGUI);
+ register_code(KC_S);
+ unregister_code(KC_S);
+ unregister_code(KC_LGUI);
+ }
+ }
+}
+```
+
+As you can see, you have three function. you can use - `SEQ_ONE_KEY` for single-key sequences (Leader followed by just one key), and `SEQ_TWO_KEYS` and `SEQ_THREE_KEYS` for longer sequences. Each of these accepts one or more keycodes as arguments. This is an important point: You can use keycodes from **any layer on your keyboard**. That layer would need to be active for the leader macro to fire, obviously.
\ No newline at end of file
--- /dev/null
+## PS/2 Mouse Support
+
+Its possible to hook up a PS/2 mouse (for example touchpads or trackpoints) to your keyboard as a composite device.
+
+To hook up a Trackpoint, you need to obtain a Trackpoint module (i.e. harvest from a Thinkpad keyboard), identify the function of each pin of the module, and make the necessary circuitry between controller and Trackpoint module. For more information, please refer to [Trackpoint Hardware](https://deskthority.net/wiki/TrackPoint_Hardware) page on Deskthority Wiki.
+
+There are three available modes for hooking up PS/2 devices: USART (best), interrupts (better) or busywait (not recommended).
+
+### Busywait version
+
+Note: This is not recommended, you may encounter jerky movement or unsent inputs. Please use interrupt or USART version if possible.
+
+In rules.mk:
+
+```
+PS2_MOUSE_ENABLE = yes
+PS2_USE_BUSYWAIT = yes
+```
+
+In your keyboard config.h:
+
+```
+#ifdef PS2_USE_BUSYWAIT
+# define PS2_CLOCK_PORT PORTD
+# define PS2_CLOCK_PIN PIND
+# define PS2_CLOCK_DDR DDRD
+# define PS2_CLOCK_BIT 1
+# define PS2_DATA_PORT PORTD
+# define PS2_DATA_PIN PIND
+# define PS2_DATA_DDR DDRD
+# define PS2_DATA_BIT 2
+#endif
+```
+
+### Interrupt version
+
+The following example uses D2 for clock and D5 for data. You can use any INT or PCINT pin for clock, and any pin for data.
+
+In rules.mk:
+
+```
+PS2_MOUSE_ENABLE = yes
+PS2_USE_INT = yes
+```
+
+In your keyboard config.h:
+
+```
+#ifdef PS2_USE_INT
+#define PS2_CLOCK_PORT PORTD
+#define PS2_CLOCK_PIN PIND
+#define PS2_CLOCK_DDR DDRD
+#define PS2_CLOCK_BIT 2
+#define PS2_DATA_PORT PORTD
+#define PS2_DATA_PIN PIND
+#define PS2_DATA_DDR DDRD
+#define PS2_DATA_BIT 5
+
+#define PS2_INT_INIT() do { \
+ EICRA |= ((1<<ISC21) | \
+ (0<<ISC20)); \
+} while (0)
+#define PS2_INT_ON() do { \
+ EIMSK |= (1<<INT2); \
+} while (0)
+#define PS2_INT_OFF() do { \
+ EIMSK &= ~(1<<INT2); \
+} while (0)
+#define PS2_INT_VECT INT2_vect
+#endif
+```
+
+### USART version
+
+To use USART on the ATMega32u4, you have to use PD5 for clock and PD2 for data. If one of those are unavailable, you need to use interrupt version.
+
+In rules.mk:
+
+```
+PS2_MOUSE_ENABLE = yes
+PS2_USE_USART = yes
+```
+
+In your keyboard config.h:
+
+```
+#ifdef PS2_USE_USART
+#define PS2_CLOCK_PORT PORTD
+#define PS2_CLOCK_PIN PIND
+#define PS2_CLOCK_DDR DDRD
+#define PS2_CLOCK_BIT 5
+#define PS2_DATA_PORT PORTD
+#define PS2_DATA_PIN PIND
+#define PS2_DATA_DDR DDRD
+#define PS2_DATA_BIT 2
+
+/* synchronous, odd parity, 1-bit stop, 8-bit data, sample at falling edge */
+/* set DDR of CLOCK as input to be slave */
+#define PS2_USART_INIT() do { \
+ PS2_CLOCK_DDR &= ~(1<<PS2_CLOCK_BIT); \
+ PS2_DATA_DDR &= ~(1<<PS2_DATA_BIT); \
+ UCSR1C = ((1 << UMSEL10) | \
+ (3 << UPM10) | \
+ (0 << USBS1) | \
+ (3 << UCSZ10) | \
+ (0 << UCPOL1)); \
+ UCSR1A = 0; \
+ UBRR1H = 0; \
+ UBRR1L = 0; \
+} while (0)
+#define PS2_USART_RX_INT_ON() do { \
+ UCSR1B = ((1 << RXCIE1) | \
+ (1 << RXEN1)); \
+} while (0)
+#define PS2_USART_RX_POLL_ON() do { \
+ UCSR1B = (1 << RXEN1); \
+} while (0)
+#define PS2_USART_OFF() do { \
+ UCSR1C = 0; \
+ UCSR1B &= ~((1 << RXEN1) | \
+ (1 << TXEN1)); \
+} while (0)
+#define PS2_USART_RX_READY (UCSR1A & (1<<RXC1))
+#define PS2_USART_RX_DATA UDR1
+#define PS2_USART_ERROR (UCSR1A & ((1<<FE1) | (1<<DOR1) | (1<<UPE1)))
+#define PS2_USART_RX_VECT USART1_RX_vect
+#endif
+```
+
+### Additional Settings
+
+#### PS/2 mouse features
+
+These enable settings supported by the PS/2 mouse protocol: http://www.computer-engineering.org/ps2mouse/
+
+```
+/* Use remote mode instead of the default stream mode (see link) */
+#define PS2_MOUSE_USE_REMOTE_MODE
+
+/* Enable the scrollwheel or scroll gesture on your mouse or touchpad */
+#define PS2_MOUSE_ENABLE_SCROLLING
+
+/* Some mice will need a scroll mask to be configured. The default is 0xFF. */
+#define PS2_MOUSE_SCROLL_MASK 0x0F
+
+/* Applies a transformation to the movement before sending to the host (see link) */
+#define PS2_MOUSE_USE_2_1_SCALING
+
+/* The time to wait after initializing the ps2 host */
+#define PS2_MOUSE_INIT_DELAY 1000 /* Default */
+```
+
+You can also call the following functions from ps2_mouse.h
+
+```
+void ps2_mouse_disable_data_reporting(void);
+
+void ps2_mouse_enable_data_reporting(void);
+
+void ps2_mouse_set_remote_mode(void);
+
+void ps2_mouse_set_stream_mode(void);
+
+void ps2_mouse_set_scaling_2_1(void);
+
+void ps2_mouse_set_scaling_1_1(void);
+
+void ps2_mouse_set_resolution(ps2_mouse_resolution_t resolution);
+
+void ps2_mouse_set_sample_rate(ps2_mouse_sample_rate_t sample_rate);
+```
+
+#### Fine control
+
+Use the following defines to change the sensitivity and speed of the mouse.
+Note: you can also use `ps2_mouse_set_resolution` for the same effect (not supported on most touchpads).
+
+```
+#define PS2_MOUSE_X_MULTIPLIER 3
+#define PS2_MOUSE_Y_MULTIPLIER 3
+#define PS2_MOUSE_V_MULTIPLIER 1
+```
+
+#### Scroll button
+
+If you're using a trackpoint, you will likely want to be able to use it for scrolling.
+Its possible to enable a "scroll button/s" that when pressed will cause the mouse to scroll instead of moving.
+To enable the feature, you must set a scroll button mask as follows:
+
+```
+#define PS2_MOUSE_SCROLL_BTN_MASK (1<<PS2_MOUSE_BUTTON_MIDDLE) /* Default */
+```
+
+To disable the scroll button feature:
+
+```
+#define PS2_MOUSE_SCROLL_BTN_MASK 0
+```
+
+The available buttons are:
+
+```
+#define PS2_MOUSE_BTN_LEFT 0
+#define PS2_MOUSE_BTN_RIGHT 1
+#define PS2_MOUSE_BTN_MIDDLE 2
+```
+
+You can also combine buttons in the mask by `|`ing them together.
+
+Once you've configured your scroll button mask, you must configure the scroll button send interval.
+This is the interval before which if the scroll buttons were released they would be sent to the host.
+After this interval, they will cause the mouse to scroll and will not be sent.
+
+```
+#define PS2_MOUSE_SCROLL_BTN_SEND 300 /* Default */
+```
+
+To disable sending the scroll buttons:
+```
+#define PS2_MOUSE_SCROLL_BTN_SEND 0
+```
+
+Fine control over the scrolling is supported with the following defines:
+
+```
+#define PS2_MOUSE_SCROLL_DIVISOR_H 2
+#define PS2_MOUSE_SCROLL_DIVISOR_V 2
+```
+
+#### Debug settings
+
+To debug the mouse, add `debug_mouse = true` or enable via bootmagic.
+
+```
+/* To debug the mouse reports */
+#define PS2_MOUSE_DEBUG_HID
+#define PS2_MOUSE_DEBUG_RAW
+```
<!-- FIXME: Describe how to use RGB Lighting here. -->
+## RGB Under Glow Mod
+
+
+
+Here is a quick demo on Youtube (with NPKC KC60) (https://www.youtube.com/watch?v=VKrpPAHlisY).
+
+For this mod, you need an unused pin wiring to DI of WS2812 strip. After wiring the VCC, GND, and DI, you can enable the underglow in your Makefile.
+
+ RGBLIGHT_ENABLE = yes
+
+In order to use the underglow animation functions, you need to have `#define RGBLIGHT_ANIMATIONS` in your `config.h`.
+
+Please add the following options into your config.h, and set them up according your hardware configuration. These settings are for the `F4` pin by default:
+
+ #define RGB_DI_PIN F4 // The pin your RGB strip is wired to
+ #define RGBLIGHT_ANIMATIONS // Require for fancier stuff (not compatible with audio)
+ #define RGBLED_NUM 14 // Number of LEDs
+ #define RGBLIGHT_HUE_STEP 10
+ #define RGBLIGHT_SAT_STEP 17
+ #define RGBLIGHT_VAL_STEP 17
+
+You'll need to edit `RGB_DI_PIN` to the pin you have your `DI` on your RGB strip wired to.
+
+The firmware supports 5 different light effects, and the color (hue, saturation, brightness) can be customized in most effects. To control the underglow, you need to modify your keymap file to assign those functions to some keys/key combinations. For details, please check this keymap. `keyboards/planck/keymaps/yang/keymap.c`
+
+### WS2812 Wiring
+
+
+
+Please note the USB port can only supply a limited amount of power to the keyboard (500mA by standard, however, modern computer and most usb hubs can provide 700+mA.). According to the data of NeoPixel from Adafruit, 30 WS2812 LEDs require a 5V 1A power supply, LEDs used in this mod should not more than 20.
+
## RGB Lighting Keycodes
This controls the RGB Lighting functionality. Most keyboards use WS2812 (and compatible) LEDs for underlight or case lighting.
## The Leader key: A new kind of modifier
-Most modifiers have to be held or toggled. But what if you had a key that indicated the start of a sequence? You could press that key and then rapidly press 1-3 more keys to trigger a macro, or enter a special layer, or anything else you might want to do. To learn more about it check out the [Leader Key](leader_key.md) page.
+Most modifiers have to be held or toggled. But what if you had a key that indicated the start of a sequence? You could press that key and then rapidly press 1-3 more keys to trigger a macro, or enter a special layer, or anything else you might want to do. To learn more about it check out the [Leader Key](feature_leader_key.md) page.
## Tap Dance: A single key can do 3, 5, or 100 different things
* The WSL Git is **not** compatible with the Windows Git, so use the Windows Git Bash or a windows Git GUI for all Git operations
* You can edit files either inside WSL or normally using Windows, but note that if you edit makefiles or shell scripts, make sure you are using an editor that saves the files with Unix line endings. Otherwise the compilation might not work.
-## Windows (Vista and later)
+## Windows (Vista and later) (Deprecated)
These are the old instructions for Windows Vista and later. We recommend you use [MSYS2 as outlined above](#windows-with-msys2-recommended).
* `keyboard` folder, the command will automatically fill the `<keyboard>` part. So you only need to type `<subproject>-<keymap>-<target>`
* `subproject` folder, it will fill in both `<keyboard>` and `<subproject>`
* `keymap` folder, then `<keyboard>` and `<keymap>` will be filled in. If you need to specify the `<subproject>` use the following syntax `<subproject>-<target>`
- * Note in order to support this shortcut, the keymap needs its own Makefile (see the example [here](https://github.com/qmk/qmk_firmware/blob/master/doc/keymap_makefile_example.mk))
+ * Note in order to support this shortcut, the keymap needs its own Makefile
* `keymap` folder of a `subproject`, then everything except the `<target>` will be filled in
The `<target>` means the following
`AUDIO_ENABLE`
-This allows you output audio on the C6 pin (needs abstracting). See the [audio section](#audio-output-from-a-speaker) for more information.
+This allows you output audio on the C6 pin (needs abstracting). See the [audio page](feature_audio.md) for more information.
`FAUXCLICKY_ENABLE`
`VARIABLE_TRACE`
-Use this to debug changes to variable values, see the [tracing variables](#tracing-variables) section for more information.
+Use this to debug changes to variable values, see the [tracing variables](unit_testing.md#tracing-variables) section of the Unit Testing page for more information.
`API_SYSEX_ENABLE`
};
```
-Note that the layout of the keycodes is similar to the physical layout of our keyboard - this make it much easier to see what's going on. A lot of the keycodes should be fairly obvious, but for a full list of them, check out [tmk_code/doc/keycode.txt](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/doc/keycode.txt) - there are also a lot of aliases to condense your keymap file.
+Note that the layout of the keycodes is similar to the physical layout of our keyboard - this make it much easier to see what's going on. A lot of the keycodes should be fairly obvious, but for a full list of them, check out [Keycodes](keycodes.md) - there are also a lot of aliases to condense your keymap file.
It's also important to use the `KEYMAP` function we defined earlier - this is what allows the firmware to associate our intended readable keymap with the actual wiring.
## Compiling your firmware
-After you've written out your entire keymap, you're ready to get the firmware compiled and onto your Teensy. Before compiling, you'll need to get your [development environment set-up](build_guide.md) - you can skip the dfu-programmer instructions, but you'll need to download and install the [Teensy Loader](https://www.pjrc.com/teensy/loader.html) to get the firmware on your Teensy.
+After you've written out your entire keymap, you're ready to get the firmware compiled and onto your Teensy. Before compiling, you'll need to get your [development environment set-up](getting_started_build_tools.md) - you can skip the dfu-programmer instructions, but you'll need to download and install the [Teensy Loader](https://www.pjrc.com/teensy/loader.html) to get the firmware on your Teensy.
Once everything is installed, running `make` in the terminal should get you some output, and eventually a `<project_name>.hex` file in that folder. If you're having trouble with this step, see the end of the guide for the trouble-shooting section.
Now that you have a working board, it's time to get things in their permanent positions. I've often used liberal amounts of hot glue to secure and insulate things, so if that's your style, start spreading that stuff like butter. Otherwise, double-sided tape is always an elegant solution, and electrical tape is a distant second. Due to the nature of these builds, a lot of this part is up to you and how you planned (or didn't plan) things out.
-There are a lot of possibilities inside the firmware - check out the [readme](https://github.com/qmk/qmk_firmware/blob/master/readme.md) for a full feature list, and dive into the different project (Planck, Ergodox EZ, etc) to see how people use all of them. You can always stop by [the OLKB subreddit for help!](http://reddit.com/r/olkb)
+There are a lot of possibilities inside the firmware - explore [docs.qmk.fm](http://docs.qmk.fm) for a full feature list, and dive into the different project (Planck, Clueboard, Ergodox EZ, etc) to see how people use all of them. You can always stop by [the OLKB subreddit for help!](http://reddit.com/r/olkb)
--- /dev/null
+# How keys are registered, and interpreted by computers
+
+In this file, you can will learn the concepts of how keyboards work over USB,
+and you'll be able to better understand what you can expect from changing your
+firmware directly.
+
+## Schematic view
+
+Whenever you type on 1 particular key, here is the chain of actions taking
+place:
+
+``` text
++------+ +-----+ +----------+ +----------+ +----+
+| User |-------->| Key |------>| Firmware |----->| USB wire |---->| OS |
++------+ +-----+ +----------+ +----------+ |----+
+```
+
+This scheme is a very simple view of what's going on, and more details follow
+in the next sections.
+
+## 1. You Press a Key
+
+Whenever you press a key, the firmware of your keyboard can register this event.
+It can register when the key is pressed, held and released.
+
+This usually happens with a periodic scan of key presses. This speed often is limited by the mechanical key response time, the protocol to transfer those key presses (here USB HID), and by the software it is used in.
+
+## 2. What the Firmware Sends
+
+The [HID specification](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) tells what a keyboard can actually send through USB to have a chance to be properly recognised. This includes a pre-defined list of scancodes which are simple numbers from `0x00` to `0xE7`. The firmware assigns a scancode to each key of the keyboard.
+
+The firmware does not send actually letters or characters, but only scancodes.
+Thus, by modifying the firmware, you only can modify what scancode is sent over
+USB for a given key.
+
+## 3. What the Operating System Does
+
+Once the keycode reaches the operating system, a piece of software has to have
+it match an actual character thanks to a keyboard layout. For example, if your
+layout is set to QWERTY, a sample of the matching table is as follow:
+
+| keycode | character |
+|---------|-----------|
+| 0x04 | a/A |
+| 0x05 | b/B |
+| 0x06 | c/C |
+| ... | ... |
+| 0x1C | y/Y |
+| 0x1D | z/Z |
+| ... | ... |
+
+## Back to the firmware
+
+As the layout is generally fixed (unless you create your own), the firmware can actually call a keycode by its layout name directly to ease things for you. This is exactly what is done here with `KC_A` actually representing `0x04` in QWERTY. The full list can be found in `keycode.txt`.
+
+## List of Characters You Can Send
+
+Putting aside shortcuts, having a limited set of keycodes mapped to a limited layout means that **the list of characters you can assign to a given key only is the ones present in the layout**.
+
+For example, this means that if you have a QWERTY US layout, and you want to assign 1 key to produce `€` (euro currency symbol), you are unable to do so, because the QWERTY US layout does not have such mapping. You could fix that by using a QWERTY UK layout, or a QWERTY US International.
+
+You may wonder why a keyboard layout containing all of Unicode is not devised then? The limited number of keycode available through USB simply disallow such a thing.
+
+## How to (Maybe) Enter Unicode Characters
+
+You can have the firmware send *sequences of keys* to use the [software Unicode Input Method](https://en.wikipedia.org/wiki/Unicode_input#Hexadecimal_code_input) of the target operating system, thus effectively entering characters independently of the layout defined in the OS.
+
+Yet, it does come with multiple disadvantages:
+
+ - Tied to a specific OS a a time (need recompilation when changing OS);
+ - Within a given OS, does not work in all software;
+ - Limited to a subset of Unicode on some systems.
|`KC_X`||||
|`KC_Y`||||
|`KC_Z`||||
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
|`KC_ENTER`|`KC_ENT`|`Return (ENTER)`|
|`KC_ESCAPE`|`KC_ESC`|`ESCAPE`|
|`KC_BSPACE`|`KC_BSPC`|`DELETE (Backspace)`|
|`KC_DOT`||`.` and `>`|
|`KC_SLASH`|`KC_SLSH`|`/` and `?`|
|`KC_CAPSLOCK`|`KC_CAPS`|Caps Lock|
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
|`KC_LCTRL`|`KC_LCTL`|LeftControl|
|`KC_LSHIFT`|`KC_LSFT`|LeftShift|
|`KC_LALT`||LeftAlt|
|`KC_LOCKING_SCROLL`|`KC_LSCR`|Locking Scroll Lock|
|`KC_INT4`|`KC_HENK`|JIS Henken|
|`KC_INT5`|`KC_MHEN`|JIS Muhenken|
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
|`KC_PSCREEN`|`KC_PSCR`|PrintScreen|
|`KC_SCROLLLOCK`|`KC_SLCK`|Scroll Lock|
|`KC_PAUSE`|`KC_PAUS`|Pause|
|`KC_WWW_STOP`|`KC_WSTP`||
|`KC_WWW_REFRESH`|`KC_WREF`||
|`KC_WWW_FAVORITES`|`KC_WFAV`||
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
|`KC_STOP`||Stop|
|`KC__MUTE`||Mute|
|`KC__VOLUP`||Volume Up|
|`KC_MEDIA_STOP`|`KC_MSTP`||
|`KC_MEDIA_PLAY_PAUSE`|`KC_MPLY`||
|`KC_MEDIA_SELECT`|`KC_MSEL`||
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
|`KC_NUMLOCK`|`KC_NLCK`|Keypad Num Lock and Clear|
|`KC_KP_SLASH`|`KC_PSLS`|Keypad /|
|`KC_KP_ASTERISK`|`KC_PAST`|Keypad *|
|`KC_KP_EQUAL`|`KC_PEQL`|Keypad =|
|`KC_KP_COMMA`|`KC_PCMM`|Keypad Comma|
|`KC_KP_EQUAL_AS400`||Keypad Equal Sign|
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
|`KC_NO`||Ignore this key. (NOOP) |
|`KC_TRNS`||Make this key transparent to find the key on a lower layer.|
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
|[`KC_MS_UP`](mouse_keys.md)|`KC_MS_U`|Mouse Cursor Up|
|[`KC_MS_DOWN`](mouse_keys.md)|`KC_MS_D`|Mouse Cursor Down|
|[`KC_MS_LEFT`](mouse_keys.md)|`KC_MS_L`|Mouse Cursor Left|
|[`KC_MS_ACCEL0`](mouse_keys.md)|`KC_ACL0`|Mouse Acceleration 0|
|[`KC_MS_ACCEL1`](mouse_keys.md)|`KC_ACL1`|Mouse Acceleration 1|
|[`KC_MS_ACCEL2`](mouse_keys.md)|`KC_ACL2`|Mouse Acceleration 2|
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
|[`RESET`](quantum_keycodes.md#qmk-keycodes)||Put the keyboard into DFU mode for flashing|
|[`DEBUG`](quantum_keycodes.md#qmk-keycodes)||Toggles debug mode|
|[`KC_GESC`](quantum_keycodes.md#qmk-keycodes)|`GRAVE_ESC`|Acts as escape when pressed normally but when pressed with Shift or GUI will send a `~`|
|[`KC_LSPO`](quantum_keycodes.md#qmk-keycodes)||Left shift when held, open paranthesis when tapped|
|[`KC_RSPC`](quantum_keycodes.md#qmk-keycodes)||Right shift when held, close paranthesis when tapped|
-|[`KC_LEAD`](quantum_keycodes.md#qmk-keycodes)||The [leader key](leader_key.md)|
+|[`KC_LEAD`](feature_leader_key.md)||The leader key|
|[`FUNC(n)`](quantum_keycodes.md#qmk-keycodes)|`F(n)`|Call `fn_action(n)`|
|[`M(n)`](quantum_keycodes.md#qmk-keycodes)||to call macro n|
|[`MACROTAP(n)`](quantum_keycodes.md#qmk-keycodes)||to macro-tap n idk FIXME`|
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
|[`MAGIC_SWAP_CONTROL_CAPSLOCK`](feature_bootmagic.md)||Swap Capslock and Left Control|
|[`MAGIC_CAPSLOCK_TO_CONTROL`](feature_bootmagic.md)||Treat Capslock like a Control Key|
|[`MAGIC_SWAP_LALT_LGUI`](feature_bootmagic.md)||Swap the left Alt and GUI keys|
|[`MAGIC_UNHOST_NKRO`](feature_bootmagic.md)||Force NKRO off|
|[`MAGIC_UNSWAP_ALT_GUI`/`AG_NORM`](feature_bootmagic.md)||Disable the Alt/GUI switching|
|[`MAGIC_TOGGLE_NKRO`](feature_bootmagic.md)||Turn NKRO on or off|
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
|[`BL_x`](feature_backlight.md)||Set a specific backlight level between 0-9|
|[`BL_ON`](feature_backlight.md)||An alias for `BL_9`|
|[`BL_OFF`](feature_backlight.md)||An alias for `BL_0`|
|[`BL_INC`](feature_backlight.md)||Turn the backlight level up by 1|
|[`BL_TOGG`](feature_backlight.md)||Toggle the backlight on or off|
|[`BL_STEP`](feature_backlight.md)||Step through backlight levels, wrapping around to 0 when you reach the top.|
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
|[`RGB_TOG`](feature_rgblight.md)||toggle on/off|
|[`RGB_MOD`](feature_rgblight.md)||cycle through modes|
|[`RGB_HUI`](feature_rgblight.md)||hue increase|
|[`RGB_SAD`](feature_rgblight.md)||saturation decrease|
|[`RGB_VAI`](feature_rgblight.md)||value increase|
|[`RGB_VAD`](feature_rgblight.md)||value decrease|
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
|[`PRINT_ON`](feature_thermal_printer.md)||Start printing everything the user types|
|[`PRINT_OFF`](feature_thermal_printer.md)||Stop printing everything the user types|
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
|[`OUT_AUTO`](feature_bluetooth.md)||auto mode|
|[`OUT_USB`](feature_bluetooth.md)||usb only|
|[`OUT_BT`](feature_bluetooth.md)||bluetooth (when `BLUETOOTH_ENABLE`)|
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
|[`KC_HYPR`](quantum_keycodes.md#modifiers)||Hold down LCTL + LSFT + LALT + LGUI`|
|[`KC_MEH`](quantum_keycodes.md#modifiers)||Hold down LCTL + LSFT + LALT`|
|[`LCTL(kc)`](quantum_keycodes.md#modifiers)||`LCTL` + `kc`|
|[`ALTG(kc)`](quantum_keycodes.md#modifiers)||`RCTL` + `RALT` + `kc`|
|[`SCMD(kc)`](quantum_keycodes.md#modifiers)|[`SWIN(kc)`](quantum_keycodes.md#modifiers)|`LGUI` + `LSFT` + `kc`|
|[`LCA(kc)`](quantum_keycodes.md#modifiers)||`LCTL` + `LALT` + `kc`|
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
|[`CTL_T(kc)`](quantum_keycodes.md#mod-tap-keys)|[`LCTL_T(kc)`](quantum_keycodes.md#mod-tap-keys)|`LCTL` when held, `kc` when tapped|
|[`RCTL_T(kc)`](quantum_keycodes.md#mod-tap-keys)||[`RCTL` when held, `kc` when tapped|
|[`SFT_T(kc)`](quantum_keycodes.md#mod-tap-keys)|[`LSFT_T(kc)`](quantum_keycodes.md#mod-tap-keys)|`LSFT` when held, `kc` when tapped|
|[`ALL_T(kc)`](quantum_keycodes.md#mod-tap-keys)||`LCTL` + `LSFT` + `LALT` + `LGUI` when held, `kc` when tapped [more info](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)|
|[`SCMD_T(kc)`](quantum_keycodes.md#mod-tap-keys)|[`SWIN_T(kc)`](quantum_keycodes.md#mod-tap-keys)|`LGUI` + `LSFT` when held, `kc` when tapped|
|[`LCA_T(kc)`](quantum_keycodes.md#mod-tap-keys)||`LCTL` + `LALT` when held, `kc` when tapped|
-|Short Name|Long Name|Description|
-|----------|---------|-----------|
|[`KC_TILD`](keycodes_us_ansi_shifted.md)|`KC_TILDE`|tilde `~`|
|[`KC_EXLM`](keycodes_us_ansi_shifted.md)|`KC_EXCLAIM`|exclamation mark `!`|
|[`KC_AT`](keycodes_us_ansi_shifted.md)||at sign `@`|
|[`KC_PIPE`](keycodes_us_ansi_shifted.md)||pipe `\|`|
|[`KC_QUES`](keycodes_us_ansi_shifted.md)|`KC_QUESTION`|question mark `?`|
|[`KC_DQT`/`KC_DQUO`](keycodes_us_ansi_shifted.md)|`KC_DOUBLE_QUOTE`|double quote `"`|
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
-|[`LT(layer, kc)`](feature_common_shortcuts.md#switching-and-toggling-layers)||turn on layer (0-15) when held, kc ([basic keycodes](basic_keycodes.md)) when tapped|
+|[`LT(layer, kc)`](feature_common_shortcuts.md#switching-and-toggling-layers)||turn on layer (0-15) when held, kc ([basic keycodes](keycodes_basic.md)) when tapped|
|[`TO(layer)`](feature_common_shortcuts.md#switching-and-toggling-layers)||turn on layer when depressed|
|[`MO(layer)`](feature_common_shortcuts.md#switching-and-toggling-layers)||momentarily turn on layer when depressed (requires `KC_TRNS` on destination layer)|
|[`DF(layer)`](feature_common_shortcuts.md#switching-and-toggling-layers)||sets the base (default) layer|
|[`TG(layer)`](feature_common_shortcuts.md#switching-and-toggling-layers)||toggle layer on/off|
-|[`TT(layer)](feature_common_shortcuts.md#switching-and-toggling-layers)`||tap toggle? idk FIXME`|
+|[`TT(layer)`](feature_common_shortcuts.md#switching-and-toggling-layers)||tap toggle? idk FIXME`|
|[`OSM(mod)`](quantum_keycodes.md#one-shot-keys)||hold mod for one keypress|
|[`OSL(layer)`](quantum_keycodes.md#one-shot-keys)||switch to layer for one keypress|
-|Long Name|Short Name|Description|
-|---------|----------|-----------|
|[`UNICODE(n)`](unicode.md)|[`UC(n)`](unicode.md)|if `UNICODE_ENABLE`, this will send characters up to `0x7FFF`|
|[`X(n)`](unicode.md)||if `UNICODEMAP_ENABLE`, also sends unicode via a different method|
--- /dev/null
+# Basic keycodes
+
+Basic keycodes are based on [HID Usage Keyboard/Keypad Page(0x07)](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) with following exceptions:
+
+* `KC_NO` = 0 for no action
+* `KC_TRNS` = 1 for layer transparency
+* internal special keycodes in the `0xA5-DF` range (tmk heritage).
+
+## Letters and Numbers
+
+|KC_1|KC_2|KC_3|KC_4|KC_5|KC_6|KC_7|KC_8|
+|----|----|----|----|----|----|----|----|
+|KC_9|KC_0|KC_F1|KC_F2|KC_F3|KC_F4|KC_F5|KC_F6|
+|KC_F7|KC_F8|KC_F9|KC_F10|KC_F11|KC_F12|KC_F13|KC_F14|
+|KC_F15|KC_F16|KC_F17|KC_F18|KC_F19|KC_F20|KC_F21|KC_F22|
+|KC_F23|KC_F24|KC_A|KC_B|KC_C|KC_D|KC_E|KC_F|
+|KC_G|KC_H|KC_I|KC_J|KC_K|KC_L|KC_M|KC_N|
+|KC_O|KC_P|KC_Q|KC_R|KC_S|KC_T|KC_U|KC_V|
+|KC_W|KC_X|KC_Y|KC_Z|||||
+
+## Punctuation
+
+|Long Name|Short Name|Description|
+|---------|----------|-----------|
+|KC_ENTER|KC_ENT|`Return (ENTER)`|
+|KC_ESCAPE|KC_ESC|`ESCAPE`|
+|KC_BSPACE|KC_BSPC|`DELETE (Backspace)`|
+|KC_TAB||`Tab`|
+|KC_SPACE|KC_SPC|Spacebar|
+|KC_MINUS|KC_MINS|`-` and `_`|
+|KC_EQUAL|KC_EQL|`=` and `+`|
+|KC_LBRACKET|KC_LBRC|`[` and `{`|
+|KC_RBRACKET|KC_RBRC|`]` and `}`|
+|KC_BSLASH|KC_BSLS|`\` and <code>|</code> |
+|KC_NONUS_HASH|KC_NUHS|Non-US `#` and `~`|
+|KC_NONUS_BSLASH|KC_NUBS|Non-US `\` and <code>|</code> |
+|KC_INT1|KC_RO|JIS `\` and <code>|</code> |
+|KC_INT2|KC_KANA|International216|
+|KC_INT3|KC_JYEN|Yen Symbol (`¥`)|
+|KC_SCOLON|KC_SCLN|`;` and `:`|
+|KC_QUOTE|KC_QUOT|`‘` and `“`|
+|KC_GRAVE|KC_GRV|Grave Accent and Tilde|
+|KC_COMMA|KC_COMM|`,` and `<`|
+|KC_DOT||`.` and `>`|
+|KC_SLASH|KC_SLSH|`/` and `?`|
+|KC_CAPSLOCK|KC_CAPS|Caps Lock|
+
+## Modifiers
+
+|Long Name|Short Name|Description|
+|---------|----------|-----------|
+|KC_LCTRL|KC_LCTL|LeftControl|
+|KC_LSHIFT|KC_LSFT|LeftShift|
+|KC_LALT||LeftAlt|
+|KC_LGUI||Left GUI(Windows/Apple/Meta key)|
+|KC_RCTRL|KC_RCTL|RightControl|
+|KC_RSHIFT|KC_RSFT|RightShift|
+|KC_RALT||RightAlt|
+|KC_RGUI||Right GUI(Windows/Apple/Meta key)|
+|KC_LOCKING_CAPS|KC_LCAP|Locking Caps Lock|
+|KC_LOCKING_NUM|KC_LNUM|Locking Num Lock|
+|KC_LOCKING_SCROLL|KC_LSCR|Locking Scroll Lock|
+|KC_INT4|KC_HENK|JIS Henken|
+|KC_INT5|KC_MHEN|JIS Muhenken|
+
+## Commands
+
+|Long Name|Short Name|Description|
+|---------|----------|-----------|
+|KC_PSCREEN|KC_PSCR|PrintScreen|
+|KC_SCROLLLOCK|KC_SLCK|Scroll Lock|
+|KC_PAUSE|KC_PAUS|Pause|
+|KC_INSERT|KC_INS|Insert|
+|KC_HOME||Home|
+|KC_PGUP||PageUp|
+|KC_DELETE|KC_DEL|Delete Forward|
+|KC_END||End|
+|KC_PGDOWN|KC_PGDN|PageDown|
+|KC_RIGHT|KC_RGHT|RightArrow|
+|KC_LEFT||LeftArrow|
+|KC_DOWN||DownArrow|
+|KC_UP||UpArrow|
+|KC_APPLICATION|KC_APP|Application|
+|KC_POWER||Power|
+|KC_EXECUTE||Execute|
+|KC_HELP||Help|
+|KC_MENU||Menu|
+|KC_SELECT||Select|
+|KC_AGAIN||Again|
+|KC_UNDO||Undo|
+|KC_CUT||Cut|
+|KC_COPY||Copy|
+|KC_PASTE||Paste|
+|KC_FIND||Find|
+|KC_ALT_ERASE||Alternate Erase|
+|KC_SYSREQ||SysReq/Attention|
+|KC_CANCEL||Cancel|
+|KC_CLEAR||Clear|
+|KC_PRIOR||Prior|
+|KC_RETURN||Return|
+|KC_SEPARATOR||Separator|
+|KC_OUT||Out|
+|KC_OPER||Oper|
+|KC_CLEAR_AGAIN||Clear/Again|
+|KC_CRSEL||CrSel/Props|
+|KC_EXSEL||ExSel|
+|KC_SYSTEM_POWER|KC_PWR|System Power Down|
+|KC_SYSTEM_SLEEP|KC_SLEP|System Sleep|
+|KC_SYSTEM_WAKE|KC_WAKE|System Wake|
+|KC_MAIL|KC_MAIL||
+|KC_CALCULATOR|KC_CALC||
+|KC_MY_COMPUTER|KC_MYCM||
+|KC_WWW_SEARCH|KC_WSCH||
+|KC_WWW_HOME|KC_WHOM||
+|KC_WWW_BACK|KC_WBAK||
+|KC_WWW_FORWARD|KC_WFWD||
+|KC_WWW_STOP|KC_WSTP||
+|KC_WWW_REFRESH|KC_WREF||
+|KC_WWW_FAVORITES|KC_WFAV||
+
+## Media Keys
+
+Windows and Mac use different key codes for next track and previous track. Make sure you choose the keycode that corresponds to your OS.
+
+|Long Name|Short Name|Description|
+|---------|----------|-----------|
+|KC_STOP||Stop|
+|KC__MUTE||Mute|
+|KC__VOLUP||Volume Up|
+|KC__VOLDOWN||Volume Down|
+|KC_AUDIO_MUTE|KC_MUTE||
+|KC_AUDIO_VOL_UP|KC_VOLU||
+|KC_AUDIO_VOL_DOWN|KC_VOLD||
+|KC_MEDIA_NEXT_TRACK|KC_MNXT|Next Track (Windows)|
+|KC_MEDIA_PREV_TRACK|KC_MPRV|Previous Track (Windows)|
+|KC_MEDIA_FAST_FORWARD|KC_MFFD|Next Track (macOS)|
+|KC_MEDIA_REWIND|KC_MRWD|Previous Track (macOS)|
+|KC_MEDIA_STOP|KC_MSTP||
+|KC_MEDIA_PLAY_PAUSE|KC_MPLY||
+|KC_MEDIA_SELECT|KC_MSEL||
+
+## Numpad
+
+|Long Name|Short Name|Description|
+|---------|----------|-----------|
+|KC_NUMLOCK|KC_NLCK|Keypad Num Lock and Clear|
+|KC_KP_SLASH|KC_PSLS|Keypad /|
+|KC_KP_ASTERISK|KC_PAST|Keypad *|
+|KC_KP_MINUS|KC_PMNS|Keypad -|
+|KC_KP_PLUS|KC_PPLS|Keypad +|
+|KC_KP_ENTER|KC_PENT|Keypad ENTER|
+|KC_KP_1|KC_P1|Keypad 1 and End|
+|KC_KP_2|KC_P2|Keypad 2 and Down Arrow|
+|KC_KP_3|KC_P3|Keypad 3 and PageDn|
+|KC_KP_4|KC_P4|Keypad 4 and Left Arrow|
+|KC_KP_5|KC_P5|Keypad 5|
+|KC_KP_6|KC_P6|Keypad 6 and Right Arrow|
+|KC_KP_7|KC_P7|Keypad 7 and Home|
+|KC_KP_8|KC_P8|Keypad 8 and Up Arrow|
+|KC_KP_9|KC_P9|Keypad 9 and PageUp|
+|KC_KP_0|KC_P0|Keypad 0 and Insert|
+|KC_KP_DOT|KC_PDOT|Keypad . and Delete|
+|KC_KP_EQUAL|KC_PEQL|Keypad =|
+|KC_KP_COMMA|KC_PCMM|Keypad Comma|
+|KC_KP_EQUAL_AS400||Keypad Equal Sign|
+
+## Special Keys
+
+|Long Name|Short Name|Description|
+|---------|----------|-----------|
+|KC_NO||Ignore this key. (NOOP) |
+
+## Mousekey
+
+|Long Name|Short Name|Description|
+|---------|----------|-----------|
+|KC_MS_UP|KC_MS_U|Mouse Cursor Up|
+|KC_MS_DOWN|KC_MS_D|Mouse Cursor Down|
+|KC_MS_LEFT|KC_MS_L|Mouse Cursor Left|
+|KC_MS_RIGHT|KC_MS_R|Mouse Cursor Right|
+|KC_MS_BTN1|KC_BTN1|Mouse Button 1|
+|KC_MS_BTN2|KC_BTN2|Mouse Button 2|
+|KC_MS_BTN3|KC_BTN3|Mouse Button 3|
+|KC_MS_BTN4|KC_BTN4|Mouse Button 4|
+|KC_MS_BTN5|KC_BTN5|Mouse Button 5|
+|KC_MS_WH_UP|KC_WH_U|Mouse Wheel Up|
+|KC_MS_WH_DOWN|KC_WH_D|Mouse Wheel Down|
+|KC_MS_WH_LEFT|KC_WH_L|Mouse Wheel Left|
+|KC_MS_WH_RIGHT|KC_WH_R|Mouse Wheel Right|
+|KC_MS_ACCEL0|KC_ACL0|Mouse Acceleration 0|
+|KC_MS_ACCEL1|KC_ACL1|Mouse Acceleration 1|
+|KC_MS_ACCEL2|KC_ACL2|Mouse Acceleration 2|
This should have given you a basic overview for creating your own keymap. For more details see the following resources:
-* https://github.com/qmk/qmk_firmware/wiki/Keycodes
-* https://github.com/qmk/qmk_firmware/wiki/FAQ-Keymap
-* https://github.com/qmk/qmk_firmware/wiki/Keymap-examples
+* [Keycodes](keycodes.md)
+* [Keymap FAQ](faq_keymap.md)
-We are actively working to improve these docs. If you have suggestions for how they could be made better please [file an issue](https://github.com/qmk/qmk_firmware/issues/new)!
\ No newline at end of file
+We are actively working to improve these docs. If you have suggestions for how they could be made better please [file an issue](https://github.com/qmk/qmk_firmware/issues/new)!
+++ /dev/null
-# The Leader key: A new kind of modifier
-
-If you've ever used Vim, you know what a Leader key is. If not, you're about to discover a wonderful concept. :) Instead of hitting Alt+Shift+W for example (holding down three keys at the same time), what if you could hit a _sequence_ of keys instead? So you'd hit our special modifier (the Leader key), followed by W and then C (just a rapid succession of keys), and something would happen.
-
-That's what `KC_LEAD` does. Here's an example:
-
-1. Pick a key on your keyboard you want to use as the Leader key. Assign it the keycode `KC_LEAD`. This key would be dedicated just for this -- it's a single action key, can't be used for anything else.
-2. Include the line `#define LEADER_TIMEOUT 300` somewhere in your keymap.c file, probably near the top. The 300 there is 300ms -- that's how long you have for the sequence of keys following the leader. You can tweak this value for comfort, of course.
-3. Within your `matrix_scan_user` function, do something like this:
-
-```
-LEADER_EXTERNS();
-
-void matrix_scan_user(void) {
- LEADER_DICTIONARY() {
- leading = false;
- leader_end();
-
- SEQ_ONE_KEY(KC_F) {
- register_code(KC_S);
- unregister_code(KC_S);
- }
- SEQ_TWO_KEYS(KC_A, KC_S) {
- register_code(KC_H);
- unregister_code(KC_H);
- }
- SEQ_THREE_KEYS(KC_A, KC_S, KC_D) {
- register_code(KC_LGUI);
- register_code(KC_S);
- unregister_code(KC_S);
- unregister_code(KC_LGUI);
- }
- }
-}
-```
-
-As you can see, you have three function. you can use - `SEQ_ONE_KEY` for single-key sequences (Leader followed by just one key), and `SEQ_TWO_KEYS` and `SEQ_THREE_KEYS` for longer sequences. Each of these accepts one or more keycodes as arguments. This is an important point: You can use keycodes from **any layer on your keyboard**. That layer would need to be active for the leader macro to fire, obviously.
\ No newline at end of file
};
```
-This defines two macros which will be run when the key they are assigned to is pressed. If you'd like them to run when the release is released instead you can change the if statement:
+This defines two macros which will be run when the key they are assigned to is pressed. If instead you'd like them to run when the key is released you can change the if statement:
```c
if (!record->event.pressed) {
+++ /dev/null
-
-## Audio output from a speaker
-
-Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any AVR keyboard that allows access to the C6 or B5 port (`#define C6_AUDIO` and/or `#define B5_AUDIO`), you can hook up a simple speaker and make it beep. You can use those beeps to indicate layer transitions, modifiers, special keys, or just to play some funky 8bit tunes.
-
-If you add `AUDIO_ENABLE = yes` to your `rules.mk`, there's a couple different sounds that will automatically be enabled without any other configuration:
-
-```
-STARTUP_SONG // plays when the keyboard starts up (audio.c)
-GOODBYE_SONG // plays when you press the RESET key (quantum.c)
-AG_NORM_SONG // plays when you press AG_NORM (quantum.c)
-AG_SWAP_SONG // plays when you press AG_SWAP (quantum.c)
-MUSIC_ON_SONG // plays when music mode is activated (process_music.c)
-MUSIC_OFF_SONG // plays when music mode is deactivated (process_music.c)
-CHROMATIC_SONG // plays when the chromatic music mode is selected (process_music.c)
-GUITAR_SONG // plays when the guitar music mode is selected (process_music.c)
-VIOLIN_SONG // plays when the violin music mode is selected (process_music.c)
-MAJOR_SONG // plays when the major music mode is selected (process_music.c)
-```
-
-You can override the default songs by doing something like this in your `config.h`:
-
-```c
-#ifdef AUDIO_ENABLE
- #define STARTUP_SONG SONG(STARTUP_SOUND)
-#endif
-```
-
-A full list of sounds can be found in [quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) - feel free to add your own to this list! All available notes can be seen in [quantum/audio/musical_notes.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/musical_notes.h).
-
-To play a custom sound at a particular time, you can define a song like this (near the top of the file):
-
-```c
-float my_song[][2] = SONG(QWERTY_SOUND);
-```
-
-And then play your song like this:
-
-```c
-PLAY_SONG(my_song);
-```
-
-Alternatively, you can play it in a loop like this:
-
-```c
-PLAY_LOOP(my_song);
-```
-
-It's advised that you wrap all audio features in `#ifdef AUDIO_ENABLE` / `#endif` to avoid causing problems when audio isn't built into the keyboard.
-
-## Music mode
-
-The music mode maps your columns to a chromatic scale, and your rows to octaves. This works best with ortholinear keyboards, but can be made to work with others. All keycodes less than `0xFF` get blocked, so you won't type while playing notes - if you have special keys/mods, those will still work. A work-around for this is to jump to a different layer with KC_NOs before (or after) enabling music mode.
-
-Recording is experimental due to some memory issues - if you experience some weird behavior, unplugging/replugging your keyboard will fix things.
-
-Keycodes available:
-
-* `MU_ON` - Turn music mode on
-* `MU_OFF` - Turn music mode off
-* `MU_TOG` - Toggle music mode
-* `MU_MOD` - Cycle through the music modes:
- * `CHROMATIC_MODE` - Chromatic scale, row changes the octave
- * `GUITAR_MODE` - Chromatic scale, but the row changes the string (+5 st)
- * `VIOLIN_MODE` - Chromatic scale, but the row changes the string (+7 st)
- * `MAJOR_MODE` - Major scale
-
-In music mode, the following keycodes work differently, and don't pass through:
-
-* `LCTL` - start a recording
-* `LALT` - stop recording/stop playing
-* `LGUI` - play recording
-* `KC_UP` - speed-up playback
-* `KC_DOWN` - slow-down playback
-
-By default, `MUSIC_MASK` is set to `keycode < 0xFF` which means keycodes less than `0xFF` are turned into notes, and don't output anything. You can change this by defining this in your `config.h` like this:
-
- #define MUSIC_MASK keycode != KC_NO
-
-Which will capture all keycodes - be careful, this will get you stuck in music mode until you restart your keyboard!
-
-The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`:
-
- #define PITCH_STANDARD_A 432.0f
-
-## 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.
-
-## RGB Under Glow Mod
-
-
-
-Here is a quick demo on Youtube (with NPKC KC60) (https://www.youtube.com/watch?v=VKrpPAHlisY).
-
-For this mod, you need an unused pin wiring to DI of WS2812 strip. After wiring the VCC, GND, and DI, you can enable the underglow in your Makefile.
-
- RGBLIGHT_ENABLE = yes
-
-In order to use the underglow animation functions, you need to have `#define RGBLIGHT_ANIMATIONS` in your `config.h`.
-
-Please add the following options into your config.h, and set them up according your hardware configuration. These settings are for the `F4` pin by default:
-
- #define RGB_DI_PIN F4 // The pin your RGB strip is wired to
- #define RGBLIGHT_ANIMATIONS // Require for fancier stuff (not compatible with audio)
- #define RGBLED_NUM 14 // Number of LEDs
- #define RGBLIGHT_HUE_STEP 10
- #define RGBLIGHT_SAT_STEP 17
- #define RGBLIGHT_VAL_STEP 17
-
-You'll need to edit `RGB_DI_PIN` to the pin you have your `DI` on your RGB strip wired to.
-
-The firmware supports 5 different light effects, and the color (hue, saturation, brightness) can be customized in most effects. To control the underglow, you need to modify your keymap file to assign those functions to some keys/key combinations. For details, please check this keymap. `keyboards/planck/keymaps/yang/keymap.c`
-
-### WS2812 Wiring
-
-
-
-Please note the USB port can only supply a limited amount of power to the keyboard (500mA by standard, however, modern computer and most usb hubs can provide 700+mA.). According to the data of NeoPixel from Adafruit, 30 WS2812 LEDs require a 5V 1A power supply, LEDs used in this mod should not more than 20.
-
-## PS/2 Mouse Support
-
-Its possible to hook up a PS/2 mouse (for example touchpads or trackpoints) to your keyboard as a composite device.
-
-To hook up a Trackpoint, you need to obtain a Trackpoint module (i.e. harvest from a Thinkpad keyboard), identify the function of each pin of the module, and make the necessary circuitry between controller and Trackpoint module. For more information, please refer to [Trackpoint Hardware](https://deskthority.net/wiki/TrackPoint_Hardware) page on Deskthority Wiki.
-
-There are three available modes for hooking up PS/2 devices: USART (best), interrupts (better) or busywait (not recommended).
-
-### Busywait version
-
-Note: This is not recommended, you may encounter jerky movement or unsent inputs. Please use interrupt or USART version if possible.
-
-In rules.mk:
-
-```
-PS2_MOUSE_ENABLE = yes
-PS2_USE_BUSYWAIT = yes
-```
-
-In your keyboard config.h:
-
-```
-#ifdef PS2_USE_BUSYWAIT
-# define PS2_CLOCK_PORT PORTD
-# define PS2_CLOCK_PIN PIND
-# define PS2_CLOCK_DDR DDRD
-# define PS2_CLOCK_BIT 1
-# define PS2_DATA_PORT PORTD
-# define PS2_DATA_PIN PIND
-# define PS2_DATA_DDR DDRD
-# define PS2_DATA_BIT 2
-#endif
-```
-
-### Interrupt version
-
-The following example uses D2 for clock and D5 for data. You can use any INT or PCINT pin for clock, and any pin for data.
-
-In rules.mk:
-
-```
-PS2_MOUSE_ENABLE = yes
-PS2_USE_INT = yes
-```
-
-In your keyboard config.h:
-
-```
-#ifdef PS2_USE_INT
-#define PS2_CLOCK_PORT PORTD
-#define PS2_CLOCK_PIN PIND
-#define PS2_CLOCK_DDR DDRD
-#define PS2_CLOCK_BIT 2
-#define PS2_DATA_PORT PORTD
-#define PS2_DATA_PIN PIND
-#define PS2_DATA_DDR DDRD
-#define PS2_DATA_BIT 5
-
-#define PS2_INT_INIT() do { \
- EICRA |= ((1<<ISC21) | \
- (0<<ISC20)); \
-} while (0)
-#define PS2_INT_ON() do { \
- EIMSK |= (1<<INT2); \
-} while (0)
-#define PS2_INT_OFF() do { \
- EIMSK &= ~(1<<INT2); \
-} while (0)
-#define PS2_INT_VECT INT2_vect
-#endif
-```
-
-### USART version
-
-To use USART on the ATMega32u4, you have to use PD5 for clock and PD2 for data. If one of those are unavailable, you need to use interrupt version.
-
-In rules.mk:
-
-```
-PS2_MOUSE_ENABLE = yes
-PS2_USE_USART = yes
-```
-
-In your keyboard config.h:
-
-```
-#ifdef PS2_USE_USART
-#define PS2_CLOCK_PORT PORTD
-#define PS2_CLOCK_PIN PIND
-#define PS2_CLOCK_DDR DDRD
-#define PS2_CLOCK_BIT 5
-#define PS2_DATA_PORT PORTD
-#define PS2_DATA_PIN PIND
-#define PS2_DATA_DDR DDRD
-#define PS2_DATA_BIT 2
-
-/* synchronous, odd parity, 1-bit stop, 8-bit data, sample at falling edge */
-/* set DDR of CLOCK as input to be slave */
-#define PS2_USART_INIT() do { \
- PS2_CLOCK_DDR &= ~(1<<PS2_CLOCK_BIT); \
- PS2_DATA_DDR &= ~(1<<PS2_DATA_BIT); \
- UCSR1C = ((1 << UMSEL10) | \
- (3 << UPM10) | \
- (0 << USBS1) | \
- (3 << UCSZ10) | \
- (0 << UCPOL1)); \
- UCSR1A = 0; \
- UBRR1H = 0; \
- UBRR1L = 0; \
-} while (0)
-#define PS2_USART_RX_INT_ON() do { \
- UCSR1B = ((1 << RXCIE1) | \
- (1 << RXEN1)); \
-} while (0)
-#define PS2_USART_RX_POLL_ON() do { \
- UCSR1B = (1 << RXEN1); \
-} while (0)
-#define PS2_USART_OFF() do { \
- UCSR1C = 0; \
- UCSR1B &= ~((1 << RXEN1) | \
- (1 << TXEN1)); \
-} while (0)
-#define PS2_USART_RX_READY (UCSR1A & (1<<RXC1))
-#define PS2_USART_RX_DATA UDR1
-#define PS2_USART_ERROR (UCSR1A & ((1<<FE1) | (1<<DOR1) | (1<<UPE1)))
-#define PS2_USART_RX_VECT USART1_RX_vect
-#endif
-```
-
-### Additional Settings
-
-#### PS/2 mouse features
-
-These enable settings supported by the PS/2 mouse protocol: http://www.computer-engineering.org/ps2mouse/
-
-```
-/* Use remote mode instead of the default stream mode (see link) */
-#define PS2_MOUSE_USE_REMOTE_MODE
-
-/* Enable the scrollwheel or scroll gesture on your mouse or touchpad */
-#define PS2_MOUSE_ENABLE_SCROLLING
-
-/* Some mice will need a scroll mask to be configured. The default is 0xFF. */
-#define PS2_MOUSE_SCROLL_MASK 0x0F
-
-/* Applies a transformation to the movement before sending to the host (see link) */
-#define PS2_MOUSE_USE_2_1_SCALING
-
-/* The time to wait after initializing the ps2 host */
-#define PS2_MOUSE_INIT_DELAY 1000 /* Default */
-```
-
-You can also call the following functions from ps2_mouse.h
-
-```
-void ps2_mouse_disable_data_reporting(void);
-
-void ps2_mouse_enable_data_reporting(void);
-
-void ps2_mouse_set_remote_mode(void);
-
-void ps2_mouse_set_stream_mode(void);
-
-void ps2_mouse_set_scaling_2_1(void);
-
-void ps2_mouse_set_scaling_1_1(void);
-
-void ps2_mouse_set_resolution(ps2_mouse_resolution_t resolution);
-
-void ps2_mouse_set_sample_rate(ps2_mouse_sample_rate_t sample_rate);
-```
-
-#### Fine control
-
-Use the following defines to change the sensitivity and speed of the mouse.
-Note: you can also use `ps2_mouse_set_resolution` for the same effect (not supported on most touchpads).
-
-```
-#define PS2_MOUSE_X_MULTIPLIER 3
-#define PS2_MOUSE_Y_MULTIPLIER 3
-#define PS2_MOUSE_V_MULTIPLIER 1
-```
-
-#### Scroll button
-
-If you're using a trackpoint, you will likely want to be able to use it for scrolling.
-Its possible to enable a "scroll button/s" that when pressed will cause the mouse to scroll instead of moving.
-To enable the feature, you must set a scroll button mask as follows:
-
-```
-#define PS2_MOUSE_SCROLL_BTN_MASK (1<<PS2_MOUSE_BUTTON_MIDDLE) /* Default */
-```
-
-To disable the scroll button feature:
-
-```
-#define PS2_MOUSE_SCROLL_BTN_MASK 0
-```
-
-The available buttons are:
-
-```
-#define PS2_MOUSE_BTN_LEFT 0
-#define PS2_MOUSE_BTN_RIGHT 1
-#define PS2_MOUSE_BTN_MIDDLE 2
-```
-
-You can also combine buttons in the mask by `|`ing them together.
-
-Once you've configured your scroll button mask, you must configure the scroll button send interval.
-This is the interval before which if the scroll buttons were released they would be sent to the host.
-After this interval, they will cause the mouse to scroll and will not be sent.
-
-```
-#define PS2_MOUSE_SCROLL_BTN_SEND 300 /* Default */
-```
-
-To disable sending the scroll buttons:
-```
-#define PS2_MOUSE_SCROLL_BTN_SEND 0
-```
-
-Fine control over the scrolling is supported with the following defines:
-
-```
-#define PS2_MOUSE_SCROLL_DIVISOR_H 2
-#define PS2_MOUSE_SCROLL_DIVISOR_V 2
-```
-
-#### Debug settings
-
-To debug the mouse, add `debug_mouse = true` or enable via bootmagic.
-
-```
-/* To debug the mouse reports */
-#define PS2_MOUSE_DEBUG_HID
-#define PS2_MOUSE_DEBUG_RAW
-```
-
-## Safety Considerations
-
-You probably don't want to "brick" your keyboard, making it impossible
-to rewrite firmware onto it. Here are some of the parameters to show
-what things are (and likely aren't) too risky.
-
-- If your keyboard map does not include RESET, then, to get into DFU
- mode, you will need to press the reset button on the PCB, which
- requires unscrewing the bottom.
-- Messing with tmk_core / common files might make the keyboard
- inoperable
-- Too large a .hex file is trouble; `make dfu` will erase the block,
- test the size (oops, wrong order!), which errors out, failing to
- flash the keyboard, leaving it in DFU mode.
- - To this end, note that the maximum .hex file size on Planck is
- 7000h (28672 decimal)
-
-```
-Linking: .build/planck_rev4_cbbrowne.elf [OK]
-Creating load file for Flash: .build/planck_rev4_cbbrowne.hex [OK]
-
-Size after:
- text data bss dec hex filename
- 0 22396 0 22396 577c planck_rev4_cbbrowne.hex
-```
-
- - The above file is of size 22396/577ch, which is less than
- 28672/7000h
- - As long as you have a suitable alternative .hex file around, you
- can retry, loading that one
- - Some of the options you might specify in your keyboard's Makefile
- consume extra memory; watch out for BOOTMAGIC_ENABLE,
- MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE
-- DFU tools do /not/ allow you to write into the bootloader (unless
- you throw in extra fruitsalad of options), so there is little risk
- there.
-- EEPROM has around a 100000 write cycle. You shouldn't rewrite the
- firmware repeatedly and continually; that'll burn the EEPROM
- eventually.
-
OPT_DEFS += -DBOOTLOADER_SIZE=512
```
-At the bottom of the file, you'll find lots of features to turn on and off - all of these options should be set with `?=` to allow for the keymap overrides. `?=` only assigns if the variable was previously undefined. For the full documenation of these features, see the [Makefile options](#makefile-options).
+At the bottom of the file, you'll find lots of features to turn on and off - all of these options should be set with `?=` to allow for the keymap overrides. `?=` only assigns if the variable was previously undefined. For the full documenation of these features, see the [Makefile options](getting_started_make_guide.md#makefile-options).
## `/keyboards/<keyboard>/readme.md`
## `/keyboards/<keyboard>/<keyboard>.c`
-This is where all of the custom logic for your keyboard goes - you may not need to put anything in this file, since a lot of things are configured automatically. All of the `*_kb()` functions are defined here. If you modify them, remember to keep the calls to `*_user()`, or things in the keymaps might not work. You can read more about the functions [here](#custom-quantum-functions-for-keyboards-and-keymaps)
+This is where all of the custom logic for your keyboard goes - you may not need to put anything in this file, since a lot of things are configured automatically. All of the `*_kb()` functions are defined here. If you modify them, remember to keep the calls to `*_user()`, or things in the keymaps might not work. You can read more about the functions [here](custom_quantum_functions.md).
## `/keyboards/<keyboard>/<keyboard>.h`
|`KC_GESC`/`GRAVE_ESC`|Acts as escape when pressed normally but when pressed with Shift or GUI will send a ```|
|`KC_LSPO`|Left shift when held, open paranthesis when tapped|
|`KC_RSPC`|Right shift when held, close paranthesis when tapped|
-|`KC_LEAD`|The [leader key](leader_key.md)|
+|`KC_LEAD`|The [leader key](feature_leader_key.md)|
|`KC_LOCK`|The [lock key](key_lock.md)|
-|`FUNC(n)`/`F(n)`|Call `fn_action(n)`|
+|`FUNC(n)`/`F(n)`|Call `fn_action(n)` (deprecated)|
|`M(n)`|to call macro n|
|`MACROTAP(n)`|to macro-tap n idk FIXME|
This document attempts to explain how the QMK firmware works from a very high level. It assumes you understand basic programming concepts but does not (except where needed to demonstrate) assume familiarity with C. It assumes that you have a basic understanding of the following documents:
* [QMK Overview](qmk_overview.md)
-* [How Keyboards Work](basic_how_keyboards_work.md)
+* [How Keyboards Work](how_keyboards_work.md)
* [FAQ](faq.md)
## Startup
projects / qmk_firmware.git / commitdiff