From 9d1a08e38ac9937cff4e61abfd0acc26ad5fdf4a Mon Sep 17 00:00:00 2001 From: skullY Date: Sun, 6 Aug 2017 20:57:57 -0700 Subject: Doc updates from going through every file --- docs/README.md | 2 +- docs/_summary.md | 8 +- docs/adding_features_to_qmk.md | 4 +- docs/basic_how_keyboards_work.md | 72 ------- docs/basic_keycodes.md | 192 ----------------- docs/documentation_best_practices.md | 20 ++ docs/faq_build.md | 21 +- docs/faq_debug.md | 39 ++++ docs/faq_general.md | 4 +- docs/faq_keymap.md | 4 +- docs/feature_audio.md | 86 ++++++++ docs/feature_bluetooth.md | 6 +- docs/feature_common_shortcuts.md | 2 +- docs/feature_leader_key.md | 37 ++++ docs/feature_ps2_mouse.md | 238 +++++++++++++++++++++ docs/feature_rgblight.md | 31 +++ docs/features.md | 2 +- docs/getting_started_build_tools.md | 2 +- docs/getting_started_make_guide.md | 6 +- docs/hand_wire.md | 6 +- docs/how_keyboards_work.md | 72 +++++++ docs/keycodes.md | 42 +--- docs/keycodes_basic.md | 192 +++++++++++++++++ docs/keymap.md | 7 +- docs/leader_key.md | 37 ---- docs/macros.md | 2 +- docs/modding_your_keyboard.md | 403 ----------------------------------- docs/porting_your_keyboard_to_qmk.md | 4 +- docs/quantum_keycodes.md | 4 +- docs/understanding_qmk.md | 2 +- 30 files changed, 759 insertions(+), 788 deletions(-) delete mode 100644 docs/basic_how_keyboards_work.md delete mode 100644 docs/basic_keycodes.md create mode 100644 docs/feature_leader_key.md create mode 100644 docs/feature_ps2_mouse.md create mode 100644 docs/how_keyboards_work.md create mode 100644 docs/keycodes_basic.md delete mode 100644 docs/leader_key.md delete mode 100644 docs/modding_your_keyboard.md (limited to 'docs') diff --git a/docs/README.md b/docs/README.md index 06597a2b69..09317d6520 100644 --- a/docs/README.md +++ b/docs/README.md @@ -22,4 +22,4 @@ This would build the `rev4` revision of the `planck` with the `default` keymap. ## 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). diff --git a/docs/_summary.md b/docs/_summary.md index 071ce56310..c73b8a0edf 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -17,9 +17,10 @@ * [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) @@ -30,7 +31,7 @@ * [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) @@ -40,6 +41,7 @@ * [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) @@ -57,7 +59,7 @@ * [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 diff --git a/docs/adding_features_to_qmk.md b/docs/adding_features_to_qmk.md index fb036496c7..e031ddbb7b 100644 --- a/docs/adding_features_to_qmk.md +++ b/docs/adding_features_to_qmk.md @@ -11,6 +11,6 @@ Once you have implemented your new feature you will generally submit a [pull req * **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. diff --git a/docs/basic_how_keyboards_work.md b/docs/basic_how_keyboards_work.md deleted file mode 100644 index 3969c5680d..0000000000 --- a/docs/basic_how_keyboards_work.md +++ /dev/null @@ -1,72 +0,0 @@ -# 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. diff --git a/docs/basic_keycodes.md b/docs/basic_keycodes.md deleted file mode 100644 index b1f69ab167..0000000000 --- a/docs/basic_keycodes.md +++ /dev/null @@ -1,192 +0,0 @@ -# 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 | | -|KC_NONUS_HASH|KC_NUHS|Non-US `#` and `~`| -|KC_NONUS_BSLASH|KC_NUBS|Non-US `\` and | | -|KC_INT1|KC_RO|JIS `\` and | | -|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| diff --git a/docs/documentation_best_practices.md b/docs/documentation_best_practices.md index f30793181c..059b25bcd3 100644 --- a/docs/documentation_best_practices.md +++ b/docs/documentation_best_practices.md @@ -75,3 +75,23 @@ You can add some colors. What about a warning message? 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_.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. diff --git a/docs/faq_build.md b/docs/faq_build.md index ebe8caccd1..353e805948 100644 --- a/docs/faq_build.md +++ b/docs/faq_build.md @@ -1,17 +1,9 @@ # 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.] [KEYMAP=...] clean - $ make [-f Makefile.] [KEYMAP=...] - $ make [-f Makefile.] [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, @@ -21,16 +13,16 @@ In short when your controller is ATMega32u4, or just - $ sudo make dfu + $ sudo make --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. @@ -41,7 +33,6 @@ You can buy a really unique VID:PID here. I don't think you need this for person - 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/`. diff --git a/docs/faq_debug.md b/docs/faq_debug.md index 9e76ac4094..3f7cfe7477 100644 --- a/docs/faq_debug.md +++ b/docs/faq_debug.md @@ -48,6 +48,45 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666" *** # 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**. diff --git a/docs/faq_general.md b/docs/faq_general.md index efa564743c..fcc40e0a1f 100644 --- a/docs/faq_general.md +++ b/docs/faq_general.md @@ -12,9 +12,9 @@ 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. diff --git a/docs/faq_keymap.md b/docs/faq_keymap.md index 9f54f2213f..eb49a36996 100644 --- a/docs/faq_keymap.md +++ b/docs/faq_keymap.md @@ -1,9 +1,9 @@ # 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). diff --git a/docs/feature_audio.md b/docs/feature_audio.md index 6b476880d1..c142ff69c2 100644 --- a/docs/feature_audio.md +++ b/docs/feature_audio.md @@ -1,5 +1,91 @@ # 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. + +## 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. + + ## Bluetooth Keycodes diff --git a/docs/feature_common_shortcuts.md b/docs/feature_common_shortcuts.md index e911420261..a3dde8b670 100644 --- a/docs/feature_common_shortcuts.md +++ b/docs/feature_common_shortcuts.md @@ -13,7 +13,7 @@ This will allow you to use `FN_CAPS` and `ALT_TAB` in your `KEYMAP()`, keeping i ### 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 diff --git a/docs/feature_leader_key.md b/docs/feature_leader_key.md new file mode 100644 index 0000000000..bf4d5456d1 --- /dev/null +++ b/docs/feature_leader_key.md @@ -0,0 +1,37 @@ +# 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 diff --git a/docs/feature_ps2_mouse.md b/docs/feature_ps2_mouse.md new file mode 100644 index 0000000000..8629b28cff --- /dev/null +++ b/docs/feature_ps2_mouse.md @@ -0,0 +1,238 @@ +## 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< +## RGB Under Glow Mod + +![Planck with RGB Underglow](https://raw.githubusercontent.com/qmk/qmk_firmware/master/keyboards/planck/keymaps/yang/planck-with-rgb-underglow.jpg) + +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 + +![WS2812 Wiring](https://raw.githubusercontent.com/qmk/qmk_firmware/master/keyboards/planck/keymaps/yang/WS2812-wiring.jpg) + +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. diff --git a/docs/features.md b/docs/features.md index 0de6622938..c5965f4c0e 100644 --- a/docs/features.md +++ b/docs/features.md @@ -7,7 +7,7 @@ Steve Losh [described](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) ## 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 diff --git a/docs/getting_started_build_tools.md b/docs/getting_started_build_tools.md index 49ffdaf69f..e46b7f2e53 100644 --- a/docs/getting_started_build_tools.md +++ b/docs/getting_started_build_tools.md @@ -86,7 +86,7 @@ The Toolchain setup is done through the Windows Subsystem for Linux, and the pro * 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). diff --git a/docs/getting_started_make_guide.md b/docs/getting_started_make_guide.md index 299c5785b2..fac801082f 100644 --- a/docs/getting_started_make_guide.md +++ b/docs/getting_started_make_guide.md @@ -21,7 +21,7 @@ As mentioned above, there are some shortcuts, when you are in a: * `keyboard` folder, the command will automatically fill the `` part. So you only need to type `--` * `subproject` folder, it will fill in both `` and `` * `keymap` folder, then `` and `` will be filled in. If you need to specify the `` use the following syntax `-` - * 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 `` will be filled in The `` means the following @@ -142,7 +142,7 @@ This allows you to interface with a Bluefruit EZ-key to send keycodes wirelessly `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` @@ -150,7 +150,7 @@ Uses buzzer to emulate clicky switches. A cheap imitation of the Cherry blue swi `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` diff --git a/docs/hand_wire.md b/docs/hand_wire.md index 9f63095426..263cd59948 100644 --- a/docs/hand_wire.md +++ b/docs/hand_wire.md @@ -298,13 +298,13 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { }; ``` -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 `.hex` file in that folder. If you're having trouble with this step, see the end of the guide for the trouble-shooting section. @@ -328,4 +328,4 @@ If you've done all of these things, keep in mind that sometimes you might have h 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) diff --git a/docs/how_keyboards_work.md b/docs/how_keyboards_work.md new file mode 100644 index 0000000000..3969c5680d --- /dev/null +++ b/docs/how_keyboards_work.md @@ -0,0 +1,72 @@ +# 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. diff --git a/docs/keycodes.md b/docs/keycodes.md index b9e1f42f77..c601ad4ced 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -66,8 +66,6 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |`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)`| @@ -90,8 +88,6 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |`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| @@ -105,8 +101,6 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |`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| @@ -157,8 +151,6 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |`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| @@ -173,8 +165,6 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |`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 *| @@ -195,12 +185,8 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |`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| @@ -217,19 +203,15 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |[`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| @@ -249,8 +231,6 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |[`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`| @@ -258,8 +238,6 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |[`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| @@ -268,17 +246,11 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |[`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`| @@ -295,8 +267,6 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |[`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| @@ -312,8 +282,6 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |[`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 `@`| @@ -335,17 +303,13 @@ When defining a [keymap](keymap.md) each key needs a valid key definition. This |[`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| diff --git a/docs/keycodes_basic.md b/docs/keycodes_basic.md new file mode 100644 index 0000000000..b1f69ab167 --- /dev/null +++ b/docs/keycodes_basic.md @@ -0,0 +1,192 @@ +# 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|