Fix raw hid define for chibios (#4460)

* Fix firmware to work with latest Wilba changes (i.e. dynamic keymap) and M60a.

* Get back RGB Backlight codes.

* More tweaks.

* Update users/talljoe/rules.mk

Co-Authored-By: Talljoe <jwasson+github@gmail.com>

Makefile

@@ -578,7 +578,7 @@ lib/%:
 
 git-submodule:
 	git submodule sync --recursive
-	git submodule update --init --recursive
+	git submodule update --init --recursive --progress
 
 ifdef SKIP_VERSION
 SKIP_GIT := yes

Vagrantfile

@@ -59,7 +59,7 @@ Vagrant.configure(2) do |config|
   # add a # before ,args: and run 'vagrant up' to get a working
   # non-updated box and then attempt to troubleshoot or open a Github issue
 
-  config.vm.provision "shell", run: "always", path: "./util/install_dependencies.sh", args: "-update"
+  config.vm.provision "shell", run: "always", path: "./util/qmk_install.sh", args: "-update"
 
   config.vm.post_up_message = <<-EOT
 

build_keyboard.mk

@@ -110,8 +110,28 @@ ifneq ("$(wildcard $(KEYBOARD_C_1))","")
     KEYBOARD_SRC += $(KEYBOARD_C_1)
 endif
 
-OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE)
+# Generate KEYBOARD_name_subname for all levels of the keyboard folder
+KEYBOARD_FILESAFE_1 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_1)))
+KEYBOARD_FILESAFE_2 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_2)))
+KEYBOARD_FILESAFE_3 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_3)))
+KEYBOARD_FILESAFE_4 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_4)))
+KEYBOARD_FILESAFE_5 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_5)))
 
+ifneq ("$(wildcard $(KEYBOARD_PATH_5)/)","")
+    OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_5)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_4)/)","")
+    OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_4)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_3)/)","")
+    OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_3)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_2)/)","")
+    OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_2)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_1)/)","")
+    OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_1)
+endif
 
 # Setup the define for QMK_KEYBOARD_H. This is used inside of keymaps so
 # that the same keymap may be used on multiple keyboards.

common_features.mk

@@ -114,37 +114,35 @@ ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
     endif
 endif
 
-ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
+RGB_MATRIX_ENABLE ?= no
+VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 custom
+ifneq ($(strip $(RGB_MATRIX_ENABLE)), no)
+ifeq ($(filter $(RGB_MATRIX_ENABLE),$(VALID_MATRIX_TYPES)),)
+    $(error RGB_MATRIX_ENABLE="$(RGB_MATRIX_ENABLE)" is not a valid matrix type)
+endif
     OPT_DEFS += -DRGB_MATRIX_ENABLE
-    OPT_DEFS += -DIS31FL3731
-    COMMON_VPATH += $(DRIVER_PATH)/issi
-    SRC += is31fl3731.c
-    SRC += i2c_master.c
     SRC += $(QUANTUM_DIR)/color.c
     SRC += $(QUANTUM_DIR)/rgb_matrix.c
+    SRC += $(QUANTUM_DIR)/rgb_matrix_drivers.c
     CIE1931_CURVE = yes
 endif
 
+ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
+	RGB_MATRIX_ENABLE = IS31FL3731
+endif
+
 ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3731)
-    OPT_DEFS += -DRGB_MATRIX_ENABLE
     OPT_DEFS += -DIS31FL3731
     COMMON_VPATH += $(DRIVER_PATH)/issi
     SRC += is31fl3731.c
     SRC += i2c_master.c
-    SRC += $(QUANTUM_DIR)/color.c
-    SRC += $(QUANTUM_DIR)/rgb_matrix.c
-    CIE1931_CURVE = yes
 endif
 
 ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3733)
-    OPT_DEFS += -DRGB_MATRIX_ENABLE
     OPT_DEFS += -DIS31FL3733
     COMMON_VPATH += $(DRIVER_PATH)/issi
     SRC += is31fl3733.c
     SRC += i2c_master.c
-    SRC += $(QUANTUM_DIR)/color.c
-    SRC += $(QUANTUM_DIR)/rgb_matrix.c
-    CIE1931_CURVE = yes
 endif
 
 ifeq ($(strip $(TAP_DANCE_ENABLE)), yes)
@@ -215,25 +213,39 @@ endif
 ifeq ($(strip $(TERMINAL_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/process_keycode/process_terminal.c
     OPT_DEFS += -DTERMINAL_ENABLE
+    OPT_DEFS += -DUSER_PRINT
 endif
 
 ifeq ($(strip $(USB_HID_ENABLE)), yes)
     include $(TMK_DIR)/protocol/usb_hid.mk
 endif
 
+ifeq ($(strip $(ENCODER_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/encoder.c
+    OPT_DEFS += -DENCODER_ENABLE
+endif
 
 ifeq ($(strip $(HD44780_ENABLE)), yes)
     SRC += drivers/avr/hd44780.c
     OPT_DEFS += -DHD44780_ENABLE
 endif
 
+ifeq ($(strip $(DYNAMIC_KEYMAP_ENABLE)), yes)
+    OPT_DEFS += -DDYNAMIC_KEYMAP_ENABLE
+    SRC += $(QUANTUM_DIR)/dynamic_keymap.c
+endif
+
+ifeq ($(strip $(LEADER_ENABLE)), yes)
+  SRC += $(QUANTUM_DIR)/process_keycode/process_leader.c
+  OPT_DEFS += -DLEADER_ENABLE
+endif
+
 QUANTUM_SRC:= \
     $(QUANTUM_DIR)/quantum.c \
     $(QUANTUM_DIR)/keymap_common.c \
-    $(QUANTUM_DIR)/keycode_config.c \
-    $(QUANTUM_DIR)/process_keycode/process_leader.c
+    $(QUANTUM_DIR)/keycode_config.c
 
-ifndef CUSTOM_MATRIX
+ifneq ($(strip $(CUSTOM_MATRIX)), yes)
     ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
         QUANTUM_SRC += $(QUANTUM_DIR)/split_common/matrix.c
     else
@@ -246,5 +258,5 @@ ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
     QUANTUM_SRC += $(QUANTUM_DIR)/split_common/split_flags.c \
                 $(QUANTUM_DIR)/split_common/split_util.c \
                 $(QUANTUM_DIR)/split_common/i2c.c \
-                $(QUANTUM_DIR)/split_common/serial.c  
+                $(QUANTUM_DIR)/split_common/serial.c
 endif

docs/_sidebar.md

@@ -3,6 +3,8 @@
   * [Building Your First Firmware](newbs_building_firmware.md)
   * [Flashing Firmware](newbs_flashing.md)
   * [Testing and Debugging](newbs_testing_debugging.md)
+  * [Best Practices](newbs_best_practices.md)
+  * [Learning Resources](newbs_learn_more_resources.md)
 
 * [QMK Basics](README.md)
   * [QMK Introduction](getting_started_introduction.md)
@@ -37,6 +39,7 @@
   * [Glossary](reference_glossary.md)
   * [Unit Testing](unit_testing.md)
   * [Useful Functions](ref_functions.md)
+  * [Configurator Support](reference_configurator_support.md)
 
 * [Features](features.md)
   * [Basic Keycodes](keycodes_basic.md)
@@ -47,8 +50,10 @@
   * [Backlight](feature_backlight.md)
   * [Bluetooth](feature_bluetooth.md)
   * [Bootmagic](feature_bootmagic.md)
+  * [Combos](feature_combo)
   * [Command](feature_command.md)
   * [Dynamic Macros](feature_dynamic_macros.md)
+  * [Encoders](feature_encoders.md)
   * [Grave Escape](feature_grave_esc.md)
   * [Key Lock](feature_key_lock.md)
   * [Layouts](feature_layouts.md)
@@ -74,6 +79,8 @@
 * For Makers and Modders
   * [Hand Wiring Guide](hand_wire.md)
   * [ISP Flashing Guide](isp_flashing_guide.md)
+  * [ARM Debugging Guide](arm_debugging.md)
+  * [I2C Driver](i2c_driver.md)
 
 * For a Deeper Understanding
   * [How Keyboards Work](how_keyboards_work.md)

docs/_summary.md

@@ -3,6 +3,8 @@
   * [Building Your First Firmware](newbs_building_firmware.md)
   * [Flashing Firmware](newbs_flashing.md)
   * [Testing and Debugging](newbs_testing_debugging.md)
+  * [Best Practices](newbs_best_practices.md)
+  * [Learning Resources](newbs_learn_more_resources.md)
 
 * [QMK Basics](README.md)
   * [QMK Introduction](getting_started_introduction.md)
@@ -37,6 +39,7 @@
   * [Glossary](reference_glossary.md)
   * [Unit Testing](unit_testing.md)
   * [Useful Functions](ref_functions.md)
+  * [Configurator Support](reference_configurator_support.md)
 
 * [Features](features.md)
   * [Basic Keycodes](keycodes_basic.md)
@@ -47,8 +50,10 @@
   * [Backlight](feature_backlight.md)
   * [Bluetooth](feature_bluetooth.md)
   * [Bootmagic](feature_bootmagic.md)
+  * [Combos](feature_combo)
   * [Command](feature_command.md)
   * [Dynamic Macros](feature_dynamic_macros.md)
+  * [Encoders](feature_encoders.md)
   * [Grave Escape](feature_grave_esc.md)
   * [Key Lock](feature_key_lock.md)
   * [Layouts](feature_layouts.md)
@@ -74,6 +79,8 @@
 * For Makers and Modders
   * [Hand Wiring Guide](hand_wire.md)
   * [ISP Flashing Guide](isp_flashing_guide.md)
+  * [ARM Debugging Guide](arm_debugging.md)
+  * [I2C Driver](i2c_driver.md)
 
 * For a Deeper Understanding
   * [How Keyboards Work](how_keyboards_work.md)

docs/arm_debugging.md

@@ -0,0 +1,87 @@
+# ARM Debugging usign Eclipse
+
+This page describes how to setup debugging for ARM MCUs using an SWD adapter and open-source/free tools. In this guide we will install GNU MCU Eclipse IDE for C/C++ Developers and OpenOCD together with all the necessary dependencies.
+
+This guide is catered towards advance users and assumes you can compile an ARM compatible keyboard on your machine using the MAKE flow.
+
+## Installing the software
+
+The main objective here is to get the MCU Eclipse IDE correcly installed on our machine. The necesarry instructions are derived from [this](https://gnu-mcu-eclipse.github.io/install/) install guide.
+
+### The xPack Manager
+
+This tool is a software package manager and it is used to help us get the necesarry depencencies.
+
+XPM runs using Node.js so grab that form [here](https://nodejs.org/en/). After installation, open a terminal and type `npm -v`. A reply with the version number means that the instalation was successful.
+
+XPM instalation instructions can be found [here](https://www.npmjs.com/package/xpm) and are OS specific. Entering `xpm --version` to your terminal should return the software version.
+
+### The ARM Toolchain
+
+Using XPM it is very easy to install the ARM toolchain. Enter the command `xpm install --global @gnu-mcu-eclipse/arm-none-eabi-gcc`.
+
+### Windows build tools
+
+If you are using windows you need to install this!
+
+`xpm install --global @gnu-mcu-eclipse/windows-build-tools`
+
+### Programer/Debugger Drivers
+
+Now its the time to install your programer's drivers. This tutorial was made using an ST-Link v2 which you can get from almost anywhere.
+If you have an ST-Link the drivers can be found [here](https://www.st.com/en/development-tools/stsw-link009.html) otherwise consult the manufuturer of your tool.
+
+### OpenOCD
+
+This dependency allows SWD access from GDB and it is essential for debugging. Run `xpm install --global @gnu-mcu-eclipse/openocd`.
+
+### Java
+
+Java is needed by Eclipse so please download it from [here](https://www.oracle.com/technetwork/java/javase/downloads/index.html).
+
+### GNU MCU Eclipse IDE
+
+Now its finally time to install the IDE. Use the Release page [here](https://github.com/gnu-mcu-eclipse/org.eclipse.epp.packages/releases/) to get the latest version.
+
+## Configuring Eclipse
+
+Open up the Eclipse IDE we just downloaded. To import our QMK directory select File -> Import -> C/C++ -> Existing code as Makefile Project. Select next and use Browse to select your QMK folder. In the tool-chain list select ARM Cross GCC and select Finish.
+
+Now you can see the QMK folder on the left hand side. Right click it and select Properties. On the left hand side, expand MCU and select ARM Toolchain Paths. Press xPack and OK. Repeat for OpenOCD Path  and if you are on windows for Build Tool Path. Select Apply and Close.
+
+Now its time to install the necessary MCU packages. Go to Packs perspective by selecting Window -> Open Perspective -> Others -> Packs. Now select the yellow refresh symbol next to the Packs tab. This will take a long time as it is requesting the MCU definitions from various places. If some of the links fail you can probably select Ignore.
+
+When this finishes you must find the MCU which we will be building/debugging for. In this example I will be using the STM32F3 series MCUs. On the left, select STMicroelectonics -> STM32F3 Series. On the middle window we can see the pack. Right click and select Install. Once that is done we can go back to the default perspective, Window -> Open Perspective -> Others -> C/C++.
+
+We need to let eclipse know the device we intent to build QMK on. Right click on the QMK folder -> Properties -> C/C++ Build -> Settings. Select the Devices tab and under devices select the appropriate variant of your MCU. For my example it is STM32F303CC
+
+While we are here let's setup the build command as well. Select C/C++ Build and then the Behavior tab. On the build command, replace `all` with your necessary make command. For example for a rev6 Planck with the default keymap this would be `planck/rev6:default`. Select Apply and Close.
+
+## Building
+
+If you have setup everything correctly pressing the hammer button should build the firmware for you and a .bin file should appear.
+
+## Debugging
+
+### Connecting the Debugger
+
+ARM MCUs use the Single Wire Debug (SWD) protocol which comprises of the clock (SWCLK) signal and the data (SWDIO) signal. Connecting this two wires and ground should be enough to allow full manipulation of the MCU. Here we assume that the keyboard will be powered though USB. The RESET signal is not necessary as we can manually assert it using the reset button. For a more advance setup, the SWO signal can be used which pipes printf and scanf asynchronously to the host but for our setup we will ignore it.
+
+NOTE: Make sure the SWCLK and SWDIO pins are not used in the matrix of your keyboard. If they are you can temporarily switch them for some other pins.
+
+### Configuring the Debugger
+
+Right click on your QMK folder, select Debug As -> Debug Configuration. Here double click on GDB OpenOCD Debugging. Select the debugger tab and enter the configuration necessary for your MCU. This might take some fiddling and googleing to find out. The default script for the STM32F3 is called stm32f3discovery.cfg. To let OpenOCD know, in the Config options enter `-f board/stm32f3discovery.cfg`.
+
+NOTE: In my case this configuration script requires editing to disable the reset assertion. The locations of the scripts can be found in the actual executable field usually under the path `openocd/version/.content/scripts/board`. Here I edited `reset_config srst_only` to `reset_config none`.
+
+Select Apply and Close.
+
+### Running the Debugger.
+
+Reset your keyboard.
+
+Press the bug icon and if all goes well you should soon find yourself in the debug perspective. Here the program counter will pause at the beginning of the main function and way for you to press Play. Most of the features of all debuggers work on ARM MCUs but for exact details google is your friend!
+
+
+Happy debugging!

docs/config_options.md

@@ -119,8 +119,8 @@ If you define these options you will enable the associated feature, which may in
 
 * `#define FORCE_NKRO`
   * NKRO by default requires to be turned on, this forces it on during keyboard startup regardless of EEPROM setting. NKRO can still be turned off but will be turned on again if the keyboard reboots.
-* `#define PREVENT_STUCK_MODIFIERS`
-  * stores the layer a key press came from so the same layer is used when the key is released, regardless of which layers are enabled
+* `#define STRICT_LAYER_RELEASE`
+  * force a key release to be evaluated using the current layer stack instead of remembering which layer it came from (used for advanced cases)
 
 ## Behaviors That Can Be Configured
 
@@ -132,14 +132,15 @@ If you define these options you will enable the associated feature, which may in
 * `#define TAPPING_TOGGLE 2`
   * how many taps before triggering the toggle
 * `#define PERMISSIVE_HOLD`
-  * makes tap and hold keys work better for fast typers who don't want tapping term set above 500
+  * makes tap and hold keys trigger the hold if another key is pressed before releasing, even if it hasn't hit the `TAPPING_TERM`
   * See [Permissive Hold](feature_advanced_keycodes.md#permissive-hold) for details
 * `#define IGNORE_MOD_TAP_INTERRUPT`
-  * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold
-  * See [Mod tap interrupt](feature_advanced_keycodes.md#mod-tap-interrupt) for details
+  * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold, by enforcing the `TAPPING_TERM` for both keys.
+  * See [Mod tap interrupt](feature_advanced_keycodes.md#ignore-mod-tap-interrupt) for details
 * `#define TAPPING_FORCE_HOLD`
   * makes it possible to use a dual role key as modifier shortly after having been tapped
-  * See [Hold after tap](feature_advanced_keycodes.md#hold-after-tap)
+  * See [Hold after tap](feature_advanced_keycodes.md#tapping-force-hold)
+  * Breaks any Tap Toggle functionality (`TT` or the One Shot Tap Toggle)
 * `#define LEADER_TIMEOUT 300`
   * how long before the leader key times out
 * `#define ONESHOT_TIMEOUT 300`
@@ -155,6 +156,10 @@ If you define these options you will enable the associated feature, which may in
     going to produce the 500 keystrokes a second needed to actually get more than a
     few ms of delay from this. But if you're doing chording on something with 3-4ms
     scan times? You probably want this.
+* `#define COMBO_COUNT 2`
+  * Set this to the number of combos that you're using in the [Combo](feature_combo.md) feature.
+* `#define COMBO_TERM 200`
+  * how long for the Combo keys to be detected. Defaults to `TAPPING_TERM` if not defined.
 
 ## RGB Light Configuration
 
@@ -234,6 +239,8 @@ Use these to enable or disable building certain features. The more you have enab
   * Console for debug(+400)
 * `COMMAND_ENABLE`
   * Commands for debug and configuration
+* `COMBO_ENABLE`
+  * Key combo feature
 * `NKRO_ENABLE`
   * USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
 * `AUDIO_ENABLE`
@@ -245,10 +252,41 @@ Use these to enable or disable building certain features. The more you have enab
 * `UNICODE_ENABLE`
   * Unicode
 * `BLUETOOTH_ENABLE`
-  * Enable Bluetooth with the Adafruit EZ-Key HID
+  * Legacy option to Enable Bluetooth with the Adafruit EZ-Key HID. See BLUETOOTH
+* `BLUETOOTH`
+  * Current options are AdafruitEzKey, AdafruitBLE, RN42
 * `SPLIT_KEYBOARD`
   * Enables split keyboard support (dual MCU like the let's split and bakingpy's boards) and includes all necessary files located at quantum/split_common
 * `WAIT_FOR_USB`
   * Forces the keyboard to wait for a USB connection to be established before it starts up
 * `NO_USB_STARTUP_CHECK`
   * Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master.
+
+## USB Endpoint Limitations
+
+In order to provide services over USB, QMK has to use USB endpoints.
+These are a finite resource: each microcontroller has only a certain number.
+This limits what features can be enabled together.
+If the available endpoints are exceeded, a build error is thrown.
+
+The following features can require separate endpoints:
+
+* `MOUSEKEY_ENABLE`
+* `EXTRAKEY_ENABLE`
+* `CONSOLE_ENABLE`
+* `NKRO_ENABLE`
+* `MIDI_ENABLE`
+* `RAW_ENABLE`
+* `VIRTSER_ENABLE`
+
+In order to improve utilisation of the endpoints, the HID features can be combined to use a single endpoint.
+By default, `MOUSEKEY`, `EXTRAKEY`, and `NKRO` are combined into a single endpoint.
+
+The base keyboard functionality can also be combined into the endpoint,
+by setting `KEYBOARD_SHARED_EP = yes`.
+This frees up one more endpoint,
+but it can prevent the keyboard working in some BIOSes,
+as they do not implement Boot Keyboard protocol switching.
+
+Combining the mouse also breaks Boot Mouse compatibility.
+The mouse can be uncombined by setting `MOUSE_SHARED_EP = no` if this functionality is required.

docs/contributing.md

@@ -57,19 +57,39 @@ Never made an open source contribution before? Wondering how contributions work
 Most of our style is pretty easy to pick up on, but right now it's not entirely consistent. You should match the style of the code surrounding your change, but if that code is inconsistent or unclear use the following guidelines:
 
 * We indent using two spaces (soft tabs)
-* We use One True Brace Style
+* We use a modified One True Brace Style
   * Opening Brace: At the end of the same line as the statement that opens the block
   * Closing Brace: Lined up with the first character of the statement that opens the block
   * Else If: Place the closing brace at the beginning of the line and the next opening brace at the end of the same line.
   * Optional Braces: Always include optional braces.
     * Good: if (condition) { return false; }
     * Bad: if (condition) return false;
-* We use C style comments: `/* */`
+* We encourage use of C style comments: `/* */`
   * Think of them as a story describing the feature
   * Use them liberally to explain why particular decisions were made.
   * Do not write obvious comments
   * If you not sure if a comment is obvious, go ahead and include it.
 * In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns.
+* We use `#pragma once` at the start of header files rather than old-style include guards (`#ifndef THIS_FILE_H`, `#define THIS_FILE_H`, ..., `#endif`)
+
+Here is an example for easy reference:
+
+```c
+/* Enums for foo */
+enum foo_state {
+  FOO_BAR,
+  FOO_BAZ,
+};
+
+/* Returns a value */
+int foo(void) {
+  if (some_condition) {
+    return FOO_BAR;
+  } else {
+    return -1;
+  }
+}
+```
 
 # General Guidelines
 

docs/custom_quantum_functions.md

@@ -27,7 +27,7 @@ The first step to creating your own custom keycode(s) is to enumerate them. This
 
 Here is an example of enumerating 2 keycodes. After adding this block to your `keymap.c` you will be able to use `FOO` and `BAR` inside your keymap.
 
-```
+```c
 enum my_keycodes {
   FOO = SAFE_RANGE,
   BAR
@@ -44,7 +44,7 @@ These function are called every time a key is pressed or released.
 
 This example does two things. It defines the behavior for a custom keycode called `FOO`, and it supplements our Enter key by playing a tone whenever it is pressed.
 
-```
+```c
 bool process_record_user(uint16_t keycode, keyrecord_t *record) {
   switch (keycode) {
     case FOO:
@@ -75,16 +75,16 @@ The `keycode` argument is whatever is defined in your keymap, eg `MO(1)`, `KC_L`
 
 The `record` argument contains information about the actual press:
 
-```
+```c
 keyrecord_t record {
-+-keyevent_t event {
-| +-keypos_t key {
-| | +-uint8_t col
-| | +-uint8_t row
-| | }
-| +-bool     pressed
-| +-uint16_t time
-| }
+  keyevent_t event {
+    keypos_t key {
+      uint8_t col
+      uint8_t row
+    }
+    bool     pressed
+    uint16_t time
+  }
 }
 ```
 
@@ -100,7 +100,7 @@ This allows you to control the 5 LED's defined as part of the USB Keyboard spec.
 
 ### Example `led_set_user()` Implementation
 
-```
+```c
 void led_set_user(uint8_t usb_led) {
     if (usb_led & (1<<USB_LED_NUM_LOCK)) {
         PORTB |= (1<<0);
@@ -117,12 +117,12 @@ void led_set_user(uint8_t usb_led) {
     } else {
         PORTB &= ~(1<<2);
     }
-    if (usb_led & (1<<USB_LED_COMPOSE_LOCK)) {
+    if (usb_led & (1<<USB_LED_COMPOSE)) {
         PORTB |= (1<<3);
     } else {
         PORTB &= ~(1<<3);
     }
-    if (usb_led & (1<<USB_LED_KANA_LOCK)) {
+    if (usb_led & (1<<USB_LED_KANA)) {
         PORTB |= (1<<4);
     } else {
         PORTB &= ~(1<<4);
@@ -138,14 +138,14 @@ void led_set_user(uint8_t usb_led) {
 
 # Matrix Initialization Code
 
-Before a keyboard can be used the hardware must be initialized. QMK handles initialization of the keyboard matrix itself, but if you have other hardware like LED's or i&#xb2;c controllers you will need to set up that hardware before it can be used.  
+Before a keyboard can be used the hardware must be initialized. QMK handles initialization of the keyboard matrix itself, but if you have other hardware like LED's or i&#xb2;c controllers you will need to set up that hardware before it can be used.
 
 
 ### Example `matrix_init_user()` Implementation
 
 This example, at the keyboard level, sets up B1, B2, and B3 as LED pins.
 
-```
+```c
 void matrix_init_user(void) {
   // Call the keymap level matrix init.
 
@@ -181,16 +181,16 @@ You should use this function if you need custom matrix scanning code. It can als
 
 # Keyboard Idling/Wake Code
 
-If the board supports it, it can be "idled", by stopping a number of functions.  A good example of this is RGB lights or backlights.   This can save on power consumption, or may be better behavior for your keyboard.  
+If the board supports it, it can be "idled", by stopping a number of functions.  A good example of this is RGB lights or backlights.   This can save on power consumption, or may be better behavior for your keyboard.
 
-This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_init_*`, which are called when the system is board is idled and when it wakes up, respectively. 
+This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_init_*`, which are called when the system is board is idled and when it wakes up, respectively.
 
 
 ### Example suspend_power_down_user() and suspend_wakeup_init_user() Implementation
 
 This example, at the keyboard level, sets up B1, B2, and B3 as LED pins.
 
-```
+```c
 void suspend_power_down_user(void)
 {
     rgb_matrix_set_suspend_state(true);
@@ -210,13 +210,13 @@ void suspend_wakeup_init_user(void)
 
 # Layer Change Code
 
-This runs code every time that the layers get changed.  This can be useful for layer indication, or custom layer handling. 
+This runs code every time that the layers get changed.  This can be useful for layer indication, or custom layer handling.
 
 ### Example `layer_state_set_*` Implementation
 
 This example shows how to set the [RGB Underglow](feature_rgblight.md) lights based on the layer, using the Planck as an example
 
-```
+```c
 uint32_t layer_state_set_user(uint32_t state) {
     switch (biton32(state)) {
     case _RAISE:
@@ -244,3 +244,143 @@ uint32_t layer_state_set_user(uint32_t state) {
 * Keymap: `uint32_t layer_state_set_user(uint32_t state)`
 
 The `state` is the bitmask of the active layers, as explained in the [Keymap Overview](keymap.md#keymap-layer-status)
+
+
+# Persistent Configuration (EEPROM)
+
+This allows you to configure persistent settings for your keyboard.  These settings are stored in the EEPROM of your controller, and are retained even after power loss. The settings can be read with `eeconfig_read_kb` and `eeconfig_read_user`, and can be written to using `eeconfig_update_kb` and `eeconfig_update_user`. This is useful for features that you want to be able to toggle (like toggling rgb layer indication).  Additionally, you can use `eeconfig_init_kb` and `eeconfig_init_user` to set the default values for the EEPROM. 
+
+The complicated part here, is that there are a bunch of ways that you can store and access data via EEPROM, and there is no "correct" way to do this.  However, you only have a DWORD (4 bytes) for each function.
+
+Keep in mind that EEPROM has a limited number of writes. While this is very high, it's not the only thing writing to the EEPROM, and if you write too often, you can potentially drastically shorten the life of your MCU.
+
+* If you don't understand the example, then you may want to avoid using this feature, as it is rather complicated. 
+
+### Example  Implementation
+
+This is an example of how to add settings, and read and write it. We're using the user keymap for the example here.  This is a complex function, and has a lot going on.  In fact, it uses a lot of the above functions to work! 
+
+
+In your keymap.c file, add this to the top:
+```
+typedef union {
+  uint32_t raw;
+  struct {
+    bool     rgb_layer_change :1;
+  };
+} user_config_t;
+
+user_config_t user_config;
+```
+
+This sets up a 32 bit structure that we can store settings with in memory, and write to the EEPROM. Using this removes the need to define variables, since they're defined in this structure. Remember that `bool` (boolean) values use 1 bit, `uint8_t` uses 8 bits, `uint16_t` uses up 16 bits.  You can mix and match, but changing the order can cause issues, as it will change the values that are read and written. 
+
+We're using `rgb_layer_change`, for the `layer_state_set_*` function, and use `matrix_init_user` and `process_record_user` to configure everything. 
+
+Now, using the `matrix_init_user` code above, you want to add `eeconfig_read_user()` to it, to populate the structure you've just created. And you can then immediately use this structure to control functionality in your keymap.  And It should look like: 
+```
+void matrix_init_user(void) {
+  // Call the keymap level matrix init.
+
+  // Read the user config from EEPROM
+  user_config.raw = eeconfig_read_user();
+
+  // Set default layer, if enabled
+  if (user_config.rgb_layer_change) {
+    rgblight_enable_noeeprom();
+    rgblight_sethsv_noeeprom_cyan(); 
+    rgblight_mode_noeeprom(1);
+  }
+}
+```
+The above function will use the EEPROM config immediately after reading it, to set the default layer's RGB color. The "raw" value of it is converted in a usable structure based on the "union" that you created above. 
+
+```
+uint32_t layer_state_set_user(uint32_t state) {
+    switch (biton32(state)) {
+    case _RAISE:
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); }
+        break;
+    case _LOWER:
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_red(); rgblight_mode_noeeprom(1); }
+        break;
+    case _PLOVER:
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_green(); rgblight_mode_noeeprom(1); }
+        break;
+    case _ADJUST:
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); }
+        break;
+    default: //  for any other layers, or the default layer
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); }
+        break;
+    }
+  return state;
+}
+```
+This will cause the RGB underglow to be changed ONLY if the value was enabled.  Now to configure this value, create a new keycode for `process_record_user` called `RGB_LYR` and `EPRM`. Additionally, we want to make sure that if you use the normal RGB codes, that it turns off  Using the example above, make it look this:
+```
+
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case FOO:
+      if (record->event.pressed) {
+        // Do something when pressed
+      } else {
+        // Do something else when release
+      }
+      return false; // Skip all further processing of this key
+    case KC_ENTER:
+        // Play a tone when enter is pressed
+        if (record->event.pressed) {
+            PLAY_NOTE_ARRAY(tone_qwerty);
+        }
+        return true; // Let QMK send the enter press/release events
+    case EPRM:
+        if (record->event.pressed) {
+            eeconfig_init(); // resets the EEPROM to default
+        }
+        return false;
+    case RGB_LYR:  // This allows me to use underglow as layer indication, or as normal
+        if (record->event.pressed) { 
+            user_config.rgb_layer_change ^= 1; // Toggles the status
+            eeconfig_update_user(user_config.raw); // Writes the new status to EEPROM
+            if (user_config.rgb_layer_change) { // if layer state indication is enabled, 
+                layer_state_set(layer_state);   // then immediately update the layer color
+            }
+        }
+        return false; break;
+    case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // For any of the RGB codes (see quantum_keycodes.h, L400 for reference)
+        if (record->event.pressed) { //This disables layer indication, as it's assumed that if you're changing this ... you want that disabled
+            if (user_config.rgb_layer_change) {        // only if this is enabled 
+                user_config.rgb_layer_change = false;  // disable it, and 
+                eeconfig_update_user(user_config.raw); // write the setings to EEPROM
+            }
+        }
+        return true; break;
+    default:
+      return true; // Process all other keycodes normally
+  }
+}
+```
+And lastly, you want to add the `eeconfig_init_user` function, so that when the EEPROM is reset, you can specify default values, and even custom actions. For example, if you want to set rgb layer indication by default, and save the default valued. 
+
+```
+void eeconfig_init_user(void) {  // EEPROM is getting reset! 
+  user_config.rgb_layer_change = true; // We want this enabled by default
+  eeconfig_update_user(user_config.raw); // Write default value to EEPROM now
+
+  // use the non noeeprom versions, to write these values to EEPROM too
+  rgblight_enable(); // Enable RGB by default
+  rgblight_sethsv_cyan();  // Set it to CYAN by default
+  rgblight_mode(1); // set to solid by default
+}
+```
+
+And you're done.  The RGB layer indication will only work if you want it to. And it will be saved, even after unplugging the board. And if you use any of the RGB codes, it will disable the layer indication, so that it stays on the mode and color that you set it to. 
+
+### 'EECONFIG' Function Documentation
+
+* Keyboard/Revision: `void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)` and `void eeconfig_update_kb(uint32_t val)`
+* Keymap: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` and `void eeconfig_update_user(uint32_t val)`
+
+The `val` is the value of the data that you want to write to EEPROM.  And the `eeconfig_read_*` function return a 32 bit (DWORD) value from the EEPROM. 

docs/documentation_templates.md

@@ -36,7 +36,7 @@ Make example for this keyboard (after setting up your build environment):
 
     make planck/rev4:default
 
-See [build environment setup](https://docs.qmk.fm/build_environment_setup.html) then the [make instructions](https://docs.qmk.fm/make_instructions.html) for more information.
+See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs).
 ```
 
 There needs to be two spaces at the end of the `Keyboard Maintainer` and `Hardware Supported` lines for it to render correctly with Markdown.

docs/faq_build.md

@@ -17,7 +17,7 @@ or just:
 
 Note that running `make` with `sudo` is generally *not* a good idea, and you should use one of the former methods, if possible.
 
-## Linux `udev` Rules
+### Linux `udev` Rules
 On Linux, you'll need proper privileges to access the MCU. You can either use
 `sudo` when flashing firmware, or place these files in `/etc/udev/rules.d/`.
 
@@ -37,6 +37,14 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="066
 SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
 ```
 
+## Unknown Device for DFU Bootloader
+
+If you're using Windows to flash your keyboard, and you are running into issues, check the Device Manager.  If you see an "Unknown Device" when the keyboard is in "bootloader mode", then you may have a driver issue. 
+
+Re-running the installation script for MSYS2 may help (eg run `./util/qmk_install.sh` from MSYS2/WSL) or reinstalling the QMK Toolbox may fix the issue. 
+
+If that doesn't work, then you may need to grab the [Zadig Utility](https://zadig.akeo.ie/). Download this, find the device in question, and select the `WinUS(libusb-1.0)` option, and hit "Reinstall driver". Once you've done that, try flashing your board, again. 
+
 ## WINAVR is Obsolete
 It is no longer recommended and may cause some problem.
 See [TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99).
@@ -97,10 +105,12 @@ The solution is to remove and reinstall all affected modules.
 ```
 brew rm avr-gcc
 brew rm dfu-programmer
+brew rm dfu-util
 brew rm gcc-arm-none-eabi
 brew rm avrdude
 brew install avr-gcc
 brew install dfu-programmer
+brew install dfu-util
 brew install gcc-arm-none-eabi
 brew install avrdude
 ```
@@ -116,5 +126,5 @@ For now, you need to rollback avr-gcc to 7 in brew.
 ```
 brew uninstall --force avr-gcc
 brew install avr-gcc@7
-brew link avr-gcc@7
+brew link --force avr-gcc@7
 ```

docs/feature_advanced_keycodes.md

@@ -2,7 +2,7 @@
 
 Your keymap can include keycodes that are more advanced than normal, for example keys that switch layers or send modifiers when held, but send regular keycodes when tapped. This page documents the functions that are available to you.
 
-### Assigning Custom Names
+## Assigning Custom Names
 
 People often define custom names using `#define`. For example:
 
@@ -13,7 +13,7 @@ People often define custom names using `#define`. For example:
 
 This will allow you to use `FN_CAPS` and `ALT_TAB` in your `KEYMAP()`, keeping it more readable.
 
-### Caveats
+## Caveats
 
 Currently, `LT()` and `MT()` are limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. Modifiers specified as part of a Layer Tap or Mod Tap's keycode will be ignored.
 
@@ -26,7 +26,8 @@ These functions allow you to activate layers in various ways. Note that layers a
 * `DF(layer)` - switches the default layer. The default layer is the always-active base layer that other layers stack on top of. See below for more about the default layer. This might be used to switch from QWERTY to Dvorak layout. (Note that this is a temporary switch that only persists until the keyboard loses power. To modify the default layer in a persistent way requires deeper customization, such as calling the `set_single_persistent_default_layer` function inside of [process_record_user](custom_quantum_functions.md#programming-the-behavior-of-any-keycode).)
 * `MO(layer)` - momentarily activates *layer*. As soon as you let go of the key, the layer is deactivated. 
 * `LM(layer, mod)` - Momentarily activates *layer* (like `MO`), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers.
-* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped.
+* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped. Only supports layers 0-15.
+* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys](#one-shot-keys) for details and additional functionality.
 * `TG(layer)` - toggles *layer*, activating it if it's inactive and vice versa
 * `TO(layer)` - activates *layer* and de-activates all other layers (except your default layer). This function is special, because instead of just adding/removing one layer to your active layer stack, it will completely replace your current active layers, uniquely allowing you to replace higher layers with a lower one. This is activated on keydown (as soon as the key is pressed).
 * `TT(layer)` - Layer Tap-Toggle. If you hold the key down, *layer* is activated, and then is de-activated when you let go (like `MO`). If you repeatedly tap it, the layer will be toggled on or off (like `TG`). It needs 5 taps by default, but you can change this by defining `TAPPING_TOGGLE` -- for example, `#define TAPPING_TOGGLE 2` to toggle on just two taps.
@@ -35,7 +36,7 @@ These functions allow you to activate layers in various ways. Note that layers a
 
 Care must be taken when switching layers, it's possible to lock yourself into a layer with no way to deactivate that layer (without unplugging your keyboard.) We've created some guidelines to help users avoid the most common problems.
 
-### Beginners
+## Beginners
 
 If you are just getting started with QMK you will want to keep everything simple. Follow these guidelines when setting up your layers:
 
@@ -43,11 +44,11 @@ If you are just getting started with QMK you will want to keep everything simple
 * Arrange your layers in a "tree" layout, with layer 0 as the root. Do not try to enter the same layer from more than one other layer.
 * In a layer's keymap, only reference higher-numbered layers. Because layers are processed from the highest-numbered (topmost) active layer down, modifying the state of lower layers can be tricky and error-prone.
 
-### Intermediate Users
+## Intermediate Users
 
 Sometimes you need more than one base layer. For example, if you want to switch between QWERTY and Dvorak, switch between layouts for different countries, or switch your layout for different videogames. Your base layers should always be the lowest numbered layers. When you have multiple base layers you should always treat them as mutually exclusive. When one base layer is on the others are off.
 
-### Advanced Users
+## Advanced Users
 
 Once you have a good feel for how layers work and what you can do, you can get more creative. The rules listed in the beginner section will help you be successful by avoiding some of the tricker details but they can be constraining, especially for ultra-compact keyboard users. Understanding how layers work will allow you to use them in more advanced ways.
 
@@ -72,7 +73,6 @@ These allow you to combine a modifier with a keycode. When pressed, the keydown
 |`HYPR(kc)`|                      |Hold Left Control, Shift, Alt and GUI and press `kc`|
 |`MEH(kc)` |                      |Hold Left Control, Shift and Alt and press `kc`     |
 |`LCAG(kc)`|                      |Hold Left Control, Alt and GUI and press `kc`       |
-|`ALTG(kc)`|                      |Hold Right Control and Alt and press `kc`           |
 |`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`|Hold Left Shift and GUI and press `kc`              |
 |`LCA(kc)` |                      |Hold Left Control and Alt and press `kc`            |
 
@@ -125,6 +125,14 @@ For convenience, QMK includes some Mod-Tap shortcuts to make common combinations
 |`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)`             |Left Shift and GUI when held, `kc` when tapped         |
 |`LCA_T(kc)` |                                       |Left Control and Alt when held, `kc` when tapped       |
 
+## Caveats
+
+Unfortunately, these keycodes cannot be used in Mod-Taps or Layer-Taps, since any modifiers specified in the keycode are ignored.
+
+Additionally, you may run into issues when using Remote Desktop Connection on Windows. Because these codes send shift very fast, Remote Desktop may miss the codes.
+
+To fix this, open Remote Desktop Connection, click on "Show Options", open the the "Local Resources" tab. In the keyboard section, change the drop down to "On this Computer". This will fix the issue, and allow the characters to work correctly.
+
 # One Shot Keys
 
 One shot keys are keys that remain active until the next key is pressed, and then are released. This allows you to type keyboard combinations without pressing more than one key at a time. These keys are usually called "Sticky keys" or "Dead keys".
@@ -133,6 +141,8 @@ For example, if you define a key as `OSM(MOD_LSFT)`, you can type a capital A ch
 
 One shot keys also work as normal modifiers. If you hold down a one shot key and type other keys, your one shot will be released immediately after you let go of the key.
 
+Additionally, hitting keys five times in a short period will lock that key. This applies for both One Shot Modifiers and One Shot Layers, and is controlled by the `ONESHOT_TAP_TOGGLE` define.
+
 You can control the behavior of one shot keys by defining these in `config.h`:
 
 ```c
@@ -143,42 +153,73 @@ You can control the behavior of one shot keys by defining these in `config.h`:
 * `OSM(mod)` - Momentarily hold down *mod*. You must use the `MOD_*` keycodes as shown in [Mod Tap](#mod-tap), not the `KC_*` codes.
 * `OSL(layer)` - momentary switch to *layer*.
 
-Sometimes, you want to activate a one-shot layer as part of a macro or tap dance routine. To do this, you need to call `set_oneshot_layer(LAYER, ONESHOT_START)` on key down, and `set_oneshot_layer(ONESHOT_PRESSED)` on key up. If you want to cancel the oneshot, call `reset_oneshot_layer()`. For more complicated actions, take a look at the oneshot implementation in [`process_record`](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action.c#L429).
+Sometimes, you want to activate a one-shot key as part of a macro or tap dance routine.  
+
+For one shot layers, you need to call `set_oneshot_layer(LAYER, ONESHOT_START)` on key down, and `set_oneshot_layer(ONESHOT_PRESSED)` on key up. If you want to cancel the oneshot, call `reset_oneshot_layer()`.
+
+For one shot mods, you need to call `set_oneshot_mods(MOD)` to set it, or `clear_oneshot_mods()` to cancel it.
+
+!> If you're having issues with OSM translating over Remote Desktop Connection, this can be fixed by opening the settings, going to the "Local Resources" tap, and in the keyboard section, change the drop down to "On this Computer".  This will fix the issue and allow OSM to function properly over Remote Desktop.
 
-If you're having issues with OSM translating over Remote Desktop Connection, this can be fixed by opening the settings, going to the "Local Resources" tap, and in the keyboard section, change the drop down to "On this Computer".  This will fix the issue and allow OSM to function properly over Remote Desktop.
 
 # Permissive Hold
 
 As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new `config.h` option:
 
-```
+```c
 #define PERMISSIVE_HOLD
 ```
 
-This makes it easier for fast typists to use dual-function keys. Without this, if you let go of a held key inside the tapping term, it won't register.
+This makes tap and hold keys (like Mod Tap) work better for fast typist, or for high `TAPPING_TERM` settings. 
 
-Example: (Tapping Term = 200ms)
+If you press a Mod Tap key, tap another key (press and release) and then release the Mod Tap key, all within the tapping term, it will output the "tapping" function for both keys.
 
-- SHFT_T(KC_A) Down
-- KC_X Down
-- KC_X Up
-- SHFT_T(KC_A) Up
+For Instance:
 
-With defaults, if above is typed within tapping term, this will emit `ax`. With permissive hold, if above is typed within tapping term, this will emit `X` (so, Shift+X).
+- `SHFT_T(KC_A)` Down
+- `KC_X` Down
+- `KC_X` Up
+- `SHFT_T(KC_A)` Up
 
-# Mod tap interrupt
+Normally, if you do all this within the `TAPPING_TERM` (default: 200ms) this will be registered as `ax` by the firmware and host system. With permissive hold enabled, this modifies how this is handled by considering the Mod Tap keys as a Mod if another key is tapped, and would registered as `X` (`SHIFT`+`x`). 
 
-When a dual role key used for a modifier is quickly followed by another keys, it is interpreted as held even before the tapping term elapsed.  This is a problem if a key is used for example inside a rolling combo because the second key will be pressed before the first key is released.
+?> If you have `Ignore Mod Tap Interrupt` enabled, as well, this will modify how both work. The regular key has the modifier added if the first key is released first or if both keys are held longer than the `TAPPING_TERM`.
 
-For example, when trying to type the rolling combo "zx" and z being configured to send Ctrl when hold, z rapidly followed by x actually sends Ctrl-x. That's bad.
+# Ignore Mod Tap Interrupt
 
-You can disable this behavior by defining `IGNORE_MOD_TAP_INTERRUPT` in `config.h`.
+To enable this setting, add this to your `config.h`:
 
-Note that this only concerns modifiers and not layer switching keys.
+```c
+#define IGNORE_MOD_TAP_INTERRUPT
+```
 
-# Hold after tap
+Similar to Permissive Hold, this alters how the firmware processes input for fast typist. If you press a Mod Tap key, press another key, release the Mod Tap key, and then release the normal key, it would normally output the "tapping" function for both keys. This may not be desirable for rolling combo keys. 
 
-When the user holds a key after tap, this repeats the tapped key rather to hold a modifier key.  This allows to use auto repeat for the tapped key.  If you prefer to hold a modifier instead, define `TAPPING_FORCE_HOLD` in `config.h`.
+Setting `Ignore Mod Tap Interrupt` requires  holding both keys for the `TAPPING_TERM` to trigger the hold function (the mod).
+
+For Instance:
+
+- `SHFT_T(KC_A)` Down
+- `KC_X` Down
+- `SHFT_T(KC_A)` Up
+- `KC_X` Up
+
+Normally, this would send `X` (`SHIFT`+`x`). With `Ignore Mod Tap Interrupt` enabled, holding both keys are required for the `TAPPING_TERM` to register the hold action. A quick tap will output `ax` in this case, while a hold on both will still output `X`  (`SHIFT`+`x`).
+
+
+?> __Note__: This only concerns modifiers and not layer switching keys.
+
+?> If you have `Permissive Hold` enabled, as well, this will modify how both work. The regular key has the modifier added if the first key is released first or if both keys are held longer than the `TAPPING_TERM`.
+
+# Tapping Force Hold
+
+To enable `tapping force hold`, add the following to your `config.h`: 
+
+```c
+#define TAPPING_FORCE_HOLD
+```
+
+When the user holds a key after tap, this repeats the tapped key rather to hold a modifier key.  This allows to use auto repeat for the tapped key.  
 
 Example:
 
@@ -196,6 +237,12 @@ With `TAPPING_FORCE_HOLD`, the second press will be interpreted as a Shift, allo
 
 # Retro Tapping
 
-When you hold a dual function key, and haven't pressed anything when you release the key, normally nothing happens.  However, if you enable this, if you release the key without pressing another key, it will send the original key, even if it is outside of the tapping term. 
+To enable `retro tapping`, add the following to your `config.h`: 
 
-For instance, if you're using `LT(2, KC_SPACE)`, if you hold the key, don't hit anything else and then release it, normally, nothing happens. But with `RETRO_TAPPING` defined in your `config.h`, it will send `KC_SPACE`. 
+```c
+#define RETRO_TAPPING
+```
+
+Holding and releasing a dual function key without pressing another key will result in nothing happening. With retro tapping enabled, releasing the key without pressing another will send the original keycode even if it is outside the tapping term.
+
+For instance, holding and releasing `LT(2, KC_SPACE)` without hitting another key will result in nothing happening. With this enabled, it will send `KC_SPACE` instead.

docs/feature_audio.md

@@ -119,22 +119,22 @@ You can completely disable Music Mode as well. This is useful, if you're pressed
 
     #define NO_MUSIC_MODE
 
-## Faux Click
+## Audio Click
 
 This adds a click sound each time you hit a button, to simulate click sounds from the keyboard. And the sounds are slightly different for each keypress, so it doesn't sound like a single long note, if you type rapidly. 
 
 * `CK_TOGG` - Toggles the status (will play sound if enabled)
-* `CK_RST` - Resets the frequency to the default state 
-* `CK_UP` - Increases the frequency of the clicks
-* `CK_DOWN` - Decreases the frequency of the clicks
+* `CK_ON` - Turns on Audio Click (plays sound)
+* `CK_OFF` - Turns off Audio Click (doesn't play sound)
+* `CK_RST` - Resets the frequency to the default state (plays sound at default frequency)
+* `CK_UP` - Increases the frequency of the clicks (plays sound at new frequency)
+* `CK_DOWN` - Decreases the frequency of the clicks (plays sound at new frequency)
+
 
 The feature is disabled by default, to save space.  To enable it, add this to your `config.h`:
 
     #define AUDIO_CLICKY
 
-Additionally, even when enabled, the feature is not enabled by default, so you would need to turn it on first.  And since we don't use EEPROM to store the setting (yet), you can default this to on by adding this to your `config.h`:
-
-    #define AUDIO_CLICKY_ON
 
 You can configure the default, min and max frequencies, the stepping and built in randomness by defining these values: 
 
@@ -144,7 +144,7 @@ You can configure the default, min and max frequencies, the stepping and built i
 | `AUDIO_CLICKY_FREQ_MIN` | 65.0f | Sets the lowest frequency (under 60f are a bit buggy). |
 | `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | Sets the the highest frequency. Too high may result in coworkers attacking you. |
 | `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f| Sets the stepping of UP/DOWN key codes. |
-| `AUDIO_CLICKY_FREQ_RANDOMNESS`     |  0.05f |  Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical. | 
+| `AUDIO_CLICKY_FREQ_RANDOMNESS`     |  0.05f |  Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical, and `1.0f` will make this sound much like the 90's computer screen scrolling/typing effect. | 
 
 
 

docs/feature_backlight.md

@@ -54,14 +54,17 @@ In this handler, the value of an incrementing counter is mapped onto a precomput
 
 ## Backlight Functions
 
-|Function  |Description                                               |
-|----------|----------------------------------------------------------|
-|`backlight_toggle()`   |Turn the backlight on or off                 |
-|`backlight_step()`     |Cycle through backlight levels               |
-|`backlight_increase()` |Increase the backlight level                 |
-|`backlight_decrease()` |Decrease the backlight level                 |
-|`backlight_level(x)`   |Sets the backlight level to specified level  |
-|`get_backlight_level()`|Toggle backlight breathing                   |
+|Function  |Description                                                |
+|----------|-----------------------------------------------------------|
+|`backlight_toggle()`    |Turn the backlight on or off                 |
+|`backlight_enable()`    |Turn the backlight on                        |
+|`backlight_disable()`   |Turn the backlight off                       |
+|`backlight_step()`      |Cycle through backlight levels               |
+|`backlight_increase()`  |Increase the backlight level                 |
+|`backlight_decrease()`  |Decrease the backlight level                 |
+|`backlight_level(x)`    |Sets the backlight level to specified level  |
+|`get_backlight_level()` |Return the current backlight level           |
+|`is_backlight_enabled()`|Return whether the backlight is currently on |
 
 ### Backlight Breathing Functions
 

docs/feature_bluetooth.md

@@ -1,10 +1,40 @@
 # Bluetooth
 
-## Bluetooth Functionality
+## Bluetooth Known Supported Hardware
 
+Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1 Qmk has support for RN-42 HID Firmware and Bluefruit EZ Key the later of which is not produced anymore. For more recent BLE protocols currently only the Adafruit Bluefruit SPI friend is directly supported. BLE is needed to connect to iOS devices. Note iOS does not support Mouse Input.
+
+|Board                                                           |Bluetooth Protocol          |Connection Type |Rules.mk                   |Bluetooth Chip|
+|----------------------------------------------------------------|----------------------------|----------------|---------------------------|--------------|
+|[Adafruit EzKey HID]("https://www.adafruit.com/product/1535")   |Bluetooth Classic           | UART           | BLUETOOTH = AdafruitEZKey |              |
+|Rover Networks RN-42 (Sparkfun Bluesmirf)                       |Bluetooth Classic           | UART           | BLUETOOTH = RN42          | RN-42        |
+|[Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633)|Bluetooth Low Energy        | SPI            | BLUETOOTH = AdafruitBLE   | nRF5182      |
+
+Not Supported Yet but possible:
+* [Bluefruit LE UART Friend](https://www.adafruit.com/product/2479). [Possible tmk implementation found in](https://github.com/tmk/tmk_keyboard/issues/514)
+* HC-05 boards flashed with RN-42 firmware. They apparently both use the CSR BC417 Chip. Flashing it with RN-42 firmware gives it HID capability.
+* [Sparkfun Bluetooth mate](https://www.sparkfun.com/products/14839)
+* HM-13 based boards
+
+### Adafruit BLE SPI Friend
+Currently The only bluetooth chipset supported by QMK is the Adafruit Bluefruit SPI Friend. It's a Nordic nRF5182 based chip running Adafruit's custom firmware. Data is transmitted via Adafruit's SDEP over Hardware SPI. The [Feather 32u4 Bluefruit LE](https://www.adafruit.com/product/2829) is supported as it's an AVR mcu connected via SPI to the Nordic BLE chip with Adafruit firmware. If Building a custom board with the SPI friend it would be easiest to just use the pin selection that the 32u4 feather uses but you can change the pins in the config.h options with the following defines:
+* #define AdafruitBleResetPin D4
+* #define AdafruitBleCSPin    B4
+* #define AdafruitBleIRQPin   E6
+
+A Bluefruit UART friend can be converted to an SPI friend, however this [requires](https://github.com/qmk/qmk_firmware/issues/2274) some reflashing and soldering directly to the MDBT40 chip.
+
+## Adafruit EZ-Key hid
 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 Rules.mk Options
+Use only one of these
+* BLUETOOTH_ENABLE = yes (Legacy Option)
+* BLUETOOTH = RN42
+* BLUETOOTH = AdafruitEZKey
+* BLUETOOTH = AdafruitBLE
 
 ## Bluetooth Keycodes
 

docs/feature_bootmagic.md

@@ -11,7 +11,15 @@ There are three separate but related features that allow you to change the behav
 On some keyboards Bootmagic is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk` with:
 
 ```make
-BOOTMAGIC_ENABLE = yes
+BOOTMAGIC_ENABLE = full
+```
+
+?> You may see `yes` being used in place of `full`, and this is okay. However, `yes` is deprecated, and ideally `full` (or `lite`) should be used instead.
+
+Additionally, you can use [Bootmagic Lite](#bootmagic-lite) (a scaled down, very basic version of Bootmagic) by adding the following to your `rules.mk` file:
+
+```make
+BOOTMAGIC_ENABLE = lite
 ```
 
 ## Hotkeys
@@ -57,6 +65,7 @@ Hold down the Bootmagic key (Space by default) and the desired hotkey while plug
 |`MAGIC_UNNO_GUI`                  |         |Enable the GUI keys                       |
 |`MAGIC_SWAP_ALT_GUI`              |`AG_SWAP`|Swap Alt and GUI on both sides (for macOS)|
 |`MAGIC_UNSWAP_ALT_GUI`            |`AG_NORM`|Unswap Left Alt and Left GUI              |
+|`MAGIC_TOGGLE_ALT_GUI`            |`AG_TOGG`|Toggle Left Alt and GUI swap              |
 |`MAGIC_SWAP_BACKSLASH_BACKSPACE`  |         |Swap `\` and Backspace                    |
 |`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|         |Unswap `\` and Backspace                  |
 |`MAGIC_SWAP_CONTROL_CAPSLOCK`     |         |Swap Left Control and Caps Lock           |
@@ -98,3 +107,45 @@ If you would like to change the hotkey assignments for Bootmagic, `#define` thes
 |`BOOTMAGIC_KEY_DEFAULT_LAYER_5`         |`KC_5`       |Make layer 5 the default layer                     |
 |`BOOTMAGIC_KEY_DEFAULT_LAYER_6`         |`KC_6`       |Make layer 6 the default layer                     |
 |`BOOTMAGIC_KEY_DEFAULT_LAYER_7`         |`KC_7`       |Make layer 7 the default layer                     |
+
+# Bootmagic Lite
+
+In addition to the full blown Bootmagic feature, is the Bootmagic Lite feature that only handles jumping into the bootloader.  This is great for boards that don't have a physical reset button but you need a way to jump into the bootloader, and don't want to deal with the headache that Bootmagic can cause.
+
+To enable this version of Bootmagic, you need to enable it in your `rules.mk` with:
+
+```make
+BOOTMAGIC_ENABLE = lite
+```
+
+Additionally, you may want to specify which key to use.  This is especially useful for keyboards that have unusual matrices.  To do so, you need to specify the row and column of the key that you want to use. Add these entries to your `config.h` file:
+
+```c
+#define BOOTMAGIC_LITE_ROW 0
+#define BOOTMAGIC_LITE_COLUMN 1
+```
+
+By default, these are set to 0 and 0, which is usually the "ESC" key on a majority of keyboards.
+
+And to trigger the bootloader, you hold this key down when plugging the keyboard in. Just the single key. 
+
+## Advanced Bootmagic Lite
+
+The `bootmagic_lite` function is defined weakly, so that you can replace this in your code, if you need.  A great example of this is the Zeal60 boards that have some additional handling needed.
+
+To replace the function, all you need to do is add something like this to your code:
+
+```c
+void bootmagic_lite(void) {
+    matrix_scan();
+    wait_ms(DEBOUNCING_DELAY * 2);
+    matrix_scan();
+
+    if (matrix_get_row(BOOTMAGIC_LITE_ROW) & (1 << BOOTMAGIC_LITE_COLUMN)) {
+      // Jump to bootloader.
+      bootloader_jump();
+    }
+}
+```
+
+You can additional feature here. For instance, resetting the eeprom or requiring additional keys to be pressed to trigger bootmagic.  Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware.

docs/feature_combo.md

@@ -0,0 +1,89 @@
+# Combos
+
+The Combo feature is a chording type solution for adding custom actions.  It lets you hit multiple keys at once and produce a different effect.  For instance, hitting `A` and `S` within the tapping term would hit `ESC` instead, or have it perform even more complex tasks.
+
+To enable this feature, yu need to add `COMBO_ENABLE = yes` to your `rules.mk`.
+
+Additionally, in your `config.h`, you'll need to specify the number of combos that you'll be using, by adding `#define COMBO_COUNT 1` (replacing 1 with the number that you're using).
+<!-- At this time, this is necessary -->
+
+Also, by default, the tapping term for the Combos is set to the same value as `TAPPING_TERM` (200 by default on most boards). But you can specify a different value by defining it in your `config.h`.  For instance: `#define COMBO_TERM 300` would set the time out period for combos to 300ms.
+
+Then, your `keymap.c` file, you'll need to define a sequence of keys, terminated with `COMBO_END`, and a structure to list the combination of keys, and it's resulting action.
+
+```c
+const uint16_t PROGMEM test_combo[] = {KC_A, KC_B, COMBO_END};
+combo_t key_combos[COMBO_COUNT] = {COMBO(test_combo, KC_ESC)};
+```
+
+This will send "Escape" if you hit the A and B keys.
+
+!> This method only supports [basic keycodes](keycodes_basic.md). See the examples for more control.
+!> You cannot reuse (share) keys in combos. Each key should only belong to a single combo.  
+
+## Examples
+
+If you want to add a list, then you'd use something like this:
+
+```c
+enum combos {
+  AB_ESC,
+  JK_TAB
+}
+const uint16_t PROGMEM ab_combo[] = {KC_A, KC_B, COMBO_END};
+const uint16_t PROGMEM jk_combo[] = {KC_J, KC_K, COMBO_END};
+
+combo_t key_combos[COMBO_COUNT] = {
+  [AB_ESC] = COMBO(ab_combo, KC_ESC),
+  [JK_TAB] = COMBO(jk_combo, KC_TAB)
+};
+```
+
+For a more complicated implementation, you can use the `process_combo_event` function to add custom handling.
+
+```c
+enum combo_events {
+  ZC_COPY,
+  XV_PASTE
+  };
+
+const uint16_t PROGMEM copy_combo[] = {KC_Z, KC_C, COMBO_END};
+const uint16_t PROGMEM paste_combo[] = {KC_X, KC_V, COMBO_END};
+
+combo_t key_combos[COMBO_COUNT] = {
+  [ZC_COPY] = COMBO_ACTION(copy_combo),
+  [XV_PASTE] = COMBO_ACTION(paste_combo),
+};
+
+void process_combo_event(uint8_t combo_index, bool pressed) {
+  switch(combo_index) {
+    case ZC_COPY:
+      if (pressed) {
+        register_code(KC_LCTL);
+        register_code(KC_C);
+        unregister_code(KC_C);
+        unregister_code(KC_LCTL);
+      }
+      break;
+
+    case XV_PASTE:
+      if (pressed) {
+        register_code(KC_LCTL);
+        register_code(KC_V);
+        unregister_code(KC_V);
+        unregister_code(KC_LCTL);
+      }
+      break;
+  }
+}
+```
+
+This will send Ctrl+C if you hit Z and C, and Ctrl+V if you hit X and V.  But you could change this to do stuff like change layers, play sounds, or change settings.
+
+## Additional Configuration
+
+If you're using long combos, or even longer combos, you may run into issues with this, as the structure may not be large enough to accommodate what you're doing.
+
+In this case, you can add either `#define EXTRA_LONG_COMBOS` or `#define EXTRA_EXTRA_LONG_COMBOS` in your `config.h` file.
+
+You may also be able to enable action keys by defining `COMBO_ALLOW_ACTION_KEYS`.

docs/feature_encoders.md

@@ -0,0 +1,48 @@
+# Encoders
+
+Basic encoders are supported by adding this to your `rules.mk`:
+
+    ENCODER_ENABLE = yes
+
+and this to your `config.h`:
+
+    #define NUMBER_OF_ENCODERS 1
+    #define ENCODERS_PAD_A { B12 }
+    #define ENCODERS_PAD_B { B13 }
+
+Each PAD_A/B variable defines an array so multiple encoders can be defined, e.g.:
+
+    #define ENCODERS_PAD_A { encoder1a, encoder2a }
+    #define ENCODERS_PAD_B { encoder1a, encoder2b }
+
+If your encoder's clockwise directions are incorrect, you can swap the A & B pad definitions.
+
+Additionally, the resolution can be specified in the same file (the default & suggested is 4):
+
+    #define ENCODER_RESOLUTION 4
+
+## Callbacks
+
+The callback functions can be inserted into your `<keyboard>.c`:
+
+    void encoder_update_kb(uint8_t index, bool clockwise) {
+        encoder_update_user(index, clockwise);
+    }
+
+or `keymap.c`:
+
+    void encoder_update_user(uint8_t index, bool clockwise) {
+        if (index == 0) {
+            if (clockwise) {
+                register_code(KC_PGDN);
+                unregister_code(KC_PGDN);
+            } else {
+                register_code(KC_PGUP);
+                unregister_code(KC_PGUP);
+            }
+        }
+    }
+
+## Hardware
+
+The A an B lines of the encoders should be wired directly to the MCU, and the C/common lines should be wired to ground.

docs/feature_leader_key.md

@@ -5,7 +5,7 @@ If you've ever used Vim, you know what a Leader key is. If not, you're about to
 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.
+2. Include the line `#define LEADER_TIMEOUT 300` in your config.h. 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:
 
 ```
@@ -39,3 +39,11 @@ void matrix_scan_user(void) {
 As you can see, you have a few function. You can use `SEQ_ONE_KEY` for single-key sequences (Leader followed by just one key), and `SEQ_TWO_KEYS`, `SEQ_THREE_KEYS` up to `SEQ_FIVE_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.
+
+## Adding Leader Key Support in the `rules.mk`
+
+To add support for Leader Key you simply need to add a single line to your keymap's `rules.mk`:
+
+```
+LEADER_ENABLE = yes
+```

docs/feature_macros.md

@@ -228,6 +228,10 @@ This sends the `<kc>` keydown event to the computer. Some examples would be `KC_
 
 Parallel to `register_code` function, this sends the `<kc>` keyup event to the computer. If you don't use this, the key will be held down until it's sent.
 
+### `tap_code(<kc>);`
+
+This will send `register_code(<kc>)` and then `unregister_code(<kc>)`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it).
+
 ### `clear_keyboard();`
 
 This will clear all mods and keys currently pressed.

docs/feature_ps2_mouse.md

@@ -6,6 +6,24 @@ To hook up a Trackpoint, you need to obtain a Trackpoint module (i.e. harvest fr
 
 There are three available modes for hooking up PS/2 devices: USART (best), interrupts (better) or busywait (not recommended).
 
+### The Cirtuitry between Trackpoint and Controller
+
+To get the things working, a 4.7K drag is needed between the two lines DATA and CLK and the line 5+. 
+
+```
+
+          DATA ----------+--------- PIN
+                         |
+                        4.7K
+                         |
+MODULE    5+  --------+--+--------- PWR   CONTROLLER
+                      |
+                     4.7K
+                      |    
+          CLK   ------+------------ PIN
+```
+
+
 ### Busywait Version
 
 Note: This is not recommended, you may encounter jerky movement or unsent inputs. Please use interrupt or USART version if possible.

docs/feature_rgb_matrix.md

@@ -140,6 +140,7 @@ These are the effects that are currently available:
 	    RGB_MATRIX_RAINBOW_PINWHEELS,
 	    RGB_MATRIX_RAINBOW_MOVING_CHEVRON,
 	    RGB_MATRIX_JELLYBEAN_RAINDROPS,
+	    RGB_MATRIX_DIGITAL_RAIN,
 	#ifdef RGB_MATRIX_KEYPRESSES
 	    RGB_MATRIX_SOLID_REACTIVE,
 	    RGB_MATRIX_SPLASH,
@@ -149,6 +150,30 @@ These are the effects that are currently available:
 	#endif
 	    RGB_MATRIX_EFFECT_MAX
 	};
+    
+You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `config.h`:
+
+
+|Define                                             |Description                                 |
+|---------------------------------------------------|--------------------------------------------|
+|`#define DISABLE_RGB_MATRIX_ALPHAS_MODS`           |Disables `RGB_MATRIX_ALPHAS_MODS`           |
+|`#define DISABLE_RGB_MATRIX_DUAL_BEACON`           |Disables `RGB_MATRIX_DUAL_BEACON`           |
+|`#define DISABLE_RGB_MATRIX_GRADIENT_UP_DOWN`      |Disables `RGB_MATRIX_GRADIENT_UP_DOWN`      |
+|`#define DISABLE_RGB_MATRIX_RAINDROPS`             |Disables `RGB_MATRIX_RAINDROPS`             |
+|`#define DISABLE_RGB_MATRIX_CYCLE_ALL`             |Disables `RGB_MATRIX_CYCLE_ALL`             |
+|`#define DISABLE_RGB_MATRIX_CYCLE_LEFT_RIGHT`      |Disables `RGB_MATRIX_CYCLE_LEFT_RIGHT`      |
+|`#define DISABLE_RGB_MATRIX_CYCLE_UP_DOWN`         |Disables `RGB_MATRIX_CYCLE_UP_DOWN`         |
+|`#define DISABLE_RGB_MATRIX_RAINBOW_BEACON`        |Disables `RGB_MATRIX_RAINBOW_BEACON`        |
+|`#define DISABLE_RGB_MATRIX_RAINBOW_PINWHEELS`     |Disables `RGB_MATRIX_RAINBOW_PINWHEELS`     |
+|`#define DISABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON`|Disables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON`|
+|`#define DISABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS`   |Disables `RGB_MATRIX_JELLYBEAN_RAINDROPS`   |
+|`#define DISABLE_RGB_MATRIX_DIGITAL_RAIN`          |Disables `RGB_MATRIX_DIGITAL_RAIN`          |
+|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE`        |Disables `RGB_MATRIX_SOLID_REACTIVE`        |
+|`#define DISABLE_RGB_MATRIX_SPLASH`                |Disables `RGB_MATRIX_SPLASH`                |
+|`#define DISABLE_RGB_MATRIX_MULTISPLASH`           |Disables `RGB_MATRIX_MULTISPLASH`           |
+|`#define DISABLE_RGB_MATRIX_SOLID_SPLASH`          |Disables `RGB_MATRIX_SOLID_SPLASH`          |
+|`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH`     |Disables `RGB_MATRIX_SOLID_MULTISPLASH`     |
+
 
 ## Custom layer effects
 

docs/feature_rgblight.md

@@ -79,28 +79,41 @@ Your RGB lighting can be configured by placing these `#define`s in your `config.
 
 ## Animations
 
-Not only can this lighting be whatever color you want, if `RGBLIGHT_ANIMATIONS` is defined, you also have a number of animation modes at your disposal:
 
-|Mode |Description          |
-|-----|---------------------|
-|1    |Solid color          |
-|2-5  |Solid color breathing|
-|6-8  |Cycling rainbow      |
-|9-14 |Swirling rainbow     |
-|15-20|Snake                |
-|21-23|Knight               |
-|24   |Christmas            |
-|25-34|Static gradient      |
-|35   |RGB Test             |
-|36   |Alternating          |
+Not only can this lighting be whatever color you want,
+if `RGBLIGHT_EFFECT_xxxx` or `RGBLIGHT_ANIMATIONS` is defined, you also have a number of animation modes at your disposal:
+
+|Mode number symbol           |Additional number  |Description                            |
+|-----------------------------|-------------------|---------------------------------------|
+|`RGBLIGHT_MODE_STATIC_LIGHT` | *None*            |Solid color (this mode is always enabled) |
+|`RGBLIGHT_MODE_BREATHING`    | 0,1,2,3           |Solid color breathing                  |
+|`RGBLIGHT_MODE_RAINBOW_MOOD` | 0,1,2             |Cycling rainbow                        |
+|`RGBLIGHT_MODE_RAINBOW_SWIRL`| 0,1,2,3,4,5       |Swirling rainbow                       |
+|`RGBLIGHT_MODE_SNAKE`        | 0,1,2,3,4,5       |Snake                                  |
+|`RGBLIGHT_MODE_KNIGHT`       | 0,1,2             |Knight                                 |
+|`RGBLIGHT_MODE_CHRISTMAS`    | *None*            |Christmas                              |
+|`RGBLIGHT_MODE_STATIC_GRADIENT`| 0,1,..,9        |Static gradient                        |
+|`RGBLIGHT_MODE_RGB_TEST`     | *None*            |RGB Test                               |
+|`RGBLIGHT_MODE_ALTERNATING`  | *None*            |Alternating                            |
 
 Check out [this video](https://youtube.com/watch?v=VKrpPAHlisY) for a demonstration.
 
+Note: For versions older than 0.6.117, The mode numbers were written directly. In `quantum/rgblight.h` there is a contrast table between the old mode number and the current symbol.
+
 The following options can be used to tweak the various animations:
 
 |Define                              |Default      |Description                                                                          |
 |------------------------------------|-------------|-------------------------------------------------------------------------------------|
-|`RGBLIGHT_ANIMATIONS`               |*Not defined*|If defined, enables additional animation modes                                       |
+|`RGBLIGHT_EFFECT_BREATHING`         |*Not defined*|If defined, enable breathing animation mode.                                         |
+|`RGBLIGHT_EFFECT_RAINBOW_MOOD`      |*Not defined*|If defined, enable rainbow mood animation mode.                                      |
+|`RGBLIGHT_EFFECT_RAINBOW_SWIRL`     |*Not defined*|If defined, enable rainbow swirl animation mode.                                     |
+|`RGBLIGHT_EFFECT_SNAKE`             |*Not defined*|If defined, enable snake animation mode.                                             |
+|`RGBLIGHT_EFFECT_KNIGHT`            |*Not defined*|If defined, enable knight animation mode.                                            |
+|`RGBLIGHT_EFFECT_CHRISTMAS`         |*Not defined*|If defined, enable christmas animation mode.                                         |
+|`RGBLIGHT_EFFECT_STATIC_GRADIENT`   |*Not defined*|If defined, enable static gradient mode.                                             |
+|`RGBLIGHT_EFFECT_RGB_TEST`          |*Not defined*|If defined, enable RGB test animation mode.                                          |
+|`RGBLIGHT_EFFECT_ALTERNATING`       |*Not defined*|If defined, enable alternating animation mode.                                       |
+|`RGBLIGHT_ANIMATIONS`               |*Not defined*|If defined, enables all additional animation modes                                   |
 |`RGBLIGHT_EFFECT_BREATHE_CENTER`    |`1.85`       |Used to calculate the curve for the breathing animation. Valid values are 1.0 to 2.7 |
 |`RGBLIGHT_EFFECT_BREATHE_MAX`       |`255`        |The maximum brightness for the breathing mode. Valid values are 1 to 255             |
 |`RGBLIGHT_EFFECT_SNAKE_LENGTH`      |`4`          |The number of LEDs to light up for the "Snake" animation                             |
@@ -109,6 +122,7 @@ The following options can be used to tweak the various animations:
 |`RGBLIGHT_EFFECT_KNIGHT_LED_NUM`    |`RGBLED_NUM` |The number of LEDs to have the "Knight" animation travel                             |
 |`RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL`|`1000`       |How long to wait between light changes for the "Christmas" animation, in milliseconds|
 |`RGBLIGHT_EFFECT_CHRISTMAS_STEP`    |`2`          |The number of LEDs to group the red/green colors by for the "Christmas" animation    |
+|`RGBLIGHT_RAINBOW_SWIRL_RANGE`      |`360`        |Range adjustment for the rainbow swirl effect to get different swirls                |
 
 You can also modify the speeds that the different modes animate at:
 

docs/feature_tap_dance.md

@@ -26,6 +26,8 @@ This array specifies what actions shall be taken when a tap-dance key is in acti
 
 The first option is enough for a lot of cases, that just want dual roles. For example, `ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT)` will result in `Space` being sent on single-tap, `Enter` otherwise.
 
+!> Keep in mind that only [basic keycodes](keycodes_basic.md) are supported here. Custom keycodes are not supported.
+
 And that's the bulk of it!
 
 And now, on to the explanation of how it works!

docs/feature_unicode.md

@@ -4,40 +4,108 @@ There are three Unicode keymap definition method available in QMK:
 
 ## UNICODE_ENABLE
 
-Supports Unicode input up to 0xFFFF. The keycode function is `UC(n)` in
-keymap file, where *n* is a 4 digit hexadecimal.
+Supports Unicode input up to 0xFFFF. The keycode function is `UC(n)` in keymap file, where *n* is a 4 digit hexadecimal.
 
 ## UNICODEMAP_ENABLE
 
-Supports Unicode up to 0xFFFFFFFF. You need to maintain a separate mapping
-table `const uint32_t PROGMEM unicode_map[] = {...}` in your keymap file.
-The keycode function is `X(n)` where *n* is the array index of the mapping
-table.
+Supports Unicode up to 0xFFFFFFFF. You need to maintain a separate mapping table `const uint32_t PROGMEM unicode_map[] = {...}` in your keymap file. The keycode function is `X(n)` where *n* is the array index of the mapping table.
+
+And you may want to have an enum to make reference easier.  So you'd want to add something like this to your keymap:
+
+```c
+enum unicode_name {
+  BANG, // ‽
+  IRONY, // ⸮
+  SNEK // snke 🐍
+};
+
+const uint32_t PROGMEM unicode_map[] = {
+  [BANG]      = 0x0203D, // ‽
+  [IRONY]     = 0x02E2E, // ⸮
+  [SNEK]      = 0x1F40D // snke 🐍
+}:
+```
+
+Make sure that the order for both matches.
 
 ## UCIS_ENABLE
 
-TBD
+Supports Unicode up to 0xFFFFFFFF. As with `UNICODE_MAP`, you may want to main a mapping table in your keymap file.  However, there is no keycodes for this feature, you will have to add a keycode or function to call `qk_ucis_start()`. Once you've run that, you can just type the text for your unicode, and then hit space or enter to complete it, or ESC to cancel it. And if it matches an entry in your table, it will automatically "backspace" the trigger word (from your table) and then will input the unicode sequence.
 
-Unicode input in QMK works by inputing a sequence of characters to the OS,
-sort of like macro. Unfortunately, each OS has different ideas on how Unicode is inputted.
+For instance, you would need to have a table like this in your keymap:
+
+```c
+const qk_ucis_symbol_t ucis_symbol_table[] = UCIS_TABLE
+(
+ UCIS_SYM("poop", 0x1f4a9),
+ UCIS_SYM("rofl", 0x1f923),
+ UCIS_SYM("kiss", 0x1f619)
+);
+```
+
+You run the function, and then type "rofl" and hit enter, it should backspace remove "rofl" and input the `0x1f923` unicode.
+
+### Customization
+
+There are several functions that you can add to your keymap to customize the functionality of this feature.
+
+* `void qk_ucis_start_user(void)` - This runs when you run the "start" function, and can be used to provide feedback. By default, it types out a keyboard emoji.
+* `void qk_ucis_success(uint8_t symbol_index)` - This runs when the unicode input has matched something, and has completed. Default doesn't do anything.
+* `void qk_ucis_symbol_fallback (void)` - This runs if the input text doesn't match anything.  The default function falls back to trying that input as a unicode code.
+
+The default code for these are:
+
+```c
+void qk_ucis_start_user(void) { // outputs keyboard emoji
+  unicode_input_start();
+  register_hex(0x2328);
+  unicode_input_finish();
+}
+
+void qk_ucis_success(uint8_t symbol_index) {
+}
+
+void qk_ucis_symbol_fallback (void) { // falls back to manual unicode entry
+  for (uint8_t i = 0; i < qk_ucis_state.count - 1; i++) {
+    uint8_t code = qk_ucis_state.codes[i];
+    register_code(code);
+    unregister_code(code);
+    wait_ms(UNICODE_TYPE_DELAY);
+  }
+}
+```
+
+## Unicode Input methods
+
+Unicode input in QMK works by inputting a sequence of characters to the OS,
+sort of like macro. Unfortunately, each OS has different ideas on how Unicode is input.
 
 This is the current list of Unicode input method in QMK:
 
-* UC_OSX: MacOS Unicode Hex Input support. Works only up to 0xFFFF. Disabled by default. To enable: go to System Preferences -> Keyboard -> Input Sources, and enable Unicode Hex.
-* UC_OSX_RALT: Same as UC_OSX, but sends the Right Alt key for unicode input
-* UC_LNX: Unicode input method under Linux. Works up to 0xFFFFF. Should work almost anywhere on ibus enabled distros. Without ibus, this works under GTK apps, but rarely anywhere else.
-* UC_WIN: (not recommended) Windows built-in Unicode input. To enable: create registry key under `HKEY_CURRENT_USER\Control Panel\Input Method\EnableHexNumpad` of type `REG_SZ` called `EnableHexNumpad`, set its value to 1, and reboot. This method is not recommended because of reliability and compatibility issue, use WinCompose method below instead.
-* UC_WINC: Windows Unicode input using WinCompose. Requires [WinCompose](https://github.com/samhocevar/wincompose). Works reliably under many (all?) variations of Windows.
+* __UC_OSX__: MacOS Unicode Hex Input support. Works only up to 0xFFFF. Disabled by default. To enable: go to System Preferences -> Keyboard -> Input Sources, and enable Unicode Hex.
+* __UC_OSX_RALT__: Same as UC_OSX, but sends the Right Alt key for unicode input
+* __UC_LNX__: Unicode input method under Linux. Works up to 0xFFFFF. Should work almost anywhere on ibus enabled distros. Without ibus, this works under GTK apps, but rarely anywhere else.
+* __UC_WIN__: (not recommended) Windows built-in Unicode input. To enable: create registry key under `HKEY_CURRENT_USER\Control Panel\Input Method\EnableHexNumpad` of type `REG_SZ` called `EnableHexNumpad`, set its value to 1, and reboot. This method is not recommended because of reliability and compatibility issue, use WinCompose method below instead.
+* __UC_WINC__: Windows Unicode input using WinCompose. Requires [WinCompose](https://github.com/samhocevar/wincompose). Works reliably under many (all?) variations of Windows.
 
-# Additional Language Support
+At some point, you need to call `set_unicode_input_mode(x)` to set the correct unicode method.  This sets the method that is used to send the unicode, and stores it in EEPROM, so you only need to call this once.
+
+## `send_unicode_hex_string`
+
+To type multiple characters for things like (ノಠ痊ಠ)ノ彡┻━┻, you can use `send_unicode_hex_string()` much like `SEND_STRING()` except you would use hex values separate by spaces.
+For example, the table flip seen above would be `send_unicode_hex_string("0028 30CE 0CA0 75CA 0CA0 0029 30CE 5F61 253B 2501 253B")`
+
+There are many ways to get a hex code, but an easy one is [this site](https://r12a.github.io/app-conversion/). Just make sure to convert to hexadecimal, and that is your string.
+
+## Additional Language Support
 
 In `quantum/keymap_extras/`, you'll see various language files - these work the same way as the alternative layout ones do. Most are defined by their two letter country/language code followed by an underscore and a 4-letter abbreviation of its name. `FR_UGRV` which will result in a `ù` when using a software-implemented AZERTY layout. It's currently difficult to send such characters in just the firmware.
 
-# International Characters on Windows
+## International Characters on Windows
 
-[AutoHotkey](https://autohotkey.com) allows Windows users to create custom hotkeys among others.
+### AutoHotkey allows Windows users to create custom hotkeys among others.
 
-The method does not require Unicode support in the keyboard itself but depends instead of AutoHotkey running in the background.
+The method does not require Unicode support in the keyboard itself but depends instead of [AutoHotkey](https://autohotkey.com) running in the background.
 
 First you need to select a modifier combination that is not in use by any of your programs.
 CtrlAltWin is not used very widely and should therefore be perfect for this.
@@ -52,3 +120,11 @@ In the default script of AutoHotkey you can define custom hotkeys.
 
 The hotkeys above are for the combination CtrlAltGui and CtrlAltGuiShift plus the letter a.
 AutoHotkey inserts the Text right of `Send, ` when this combination is pressed.
+
+### US International
+
+If you enable the US International layout on the system, it will use punctuation to accent the characters. 
+
+For instance, typing "`a" will result in à.
+
+You can find details on how to enable this [here](https://support.microsoft.com/en-us/help/17424/windows-change-keyboard-layout).

docs/feature_userspace.md

@@ -5,15 +5,12 @@ If you use more than one keyboard with a similar keymap, you might see the benef
 * `/users/<name>/` (added to the path automatically)
   * `readme.md` (optional, recommended)
   * `rules.mk` (included automatically)
+  * `config.h` (included automatically)
   * `<name>.h` (optional)
   * `<name>.c` (optional)
-  * `config.h` (optional)
+  * `cool_rgb_stuff.c` (optional)
+  * `cool_rgb_stuff.h` (optional)
 
-`<name>.c` will need to be added to the SRC in `rules.mk` like this:
-
-    SRC += <name>.c
-
-Additional files may be added in the same way - it's recommended you have one named `<name>`.c/.h though.
 
 All this only happens when you build a keymap named `<name>`, like this:
 
@@ -23,82 +20,179 @@ For example,
 
     make planck:jack
 
-Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`.
+Will include the `/users/jack/` folder in the path, along with `/users/jack/rules.mk`.  
+
+!> This `name` can be [overridden](#override-default-userspace), if needed.  
+
+## `Rules.mk`
+
+The `rules.mk` is one of the two files that gets processed automatically.  This is how you add additional source files (such as  `<name>.c`) will be added when compiling.
+
+It's highly recommended that you use `<name>.c` as the default source file to be added. And to add it, you need to add it the SRC in `rules.mk` like this:
+
+    SRC += <name>.c
+
+Additional files may be added in the same way - it's recommended you have one named `<name>`.c/.h to start off with, though. 
+
+The `/users/<name>/rules.mk` file will be included in the build _after_ the `rules.mk` from your keymap. This allows you to have features in your userspace `rules.mk` that depend on individual QMK features that may or may not be available on a specific keyboard. 
+
+For example, if you have RGB control features shared between all your keyboards that support RGB lighting, you can add support for that if the RGBLIGHT feature is enabled:
+```make
+ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
+  # Include my fancy rgb functions source here
+  SRC += cool_rgb_stuff.c
+endif
+```
+
+Alternatively, you can `define RGB_ENABLE` in your keymap's `rules.mk` and then check for the variable in your userspace's `rules.mk` like this:
+```make
+ifdef RGB_ENABLE
+  # Include my fancy rgb functions source here
+  SRC += cool_rgb_stuff.c
+endif
+```
+
+### Override default userspace
+
+By default the userspace used will be the same as the keymap name. In some situations this isn't desirable. For instance, if you use the [layout](feature_layouts.md) feature you can't use the same name for different keymaps (e.g. ANSI and ISO). You can name your layouts `mylayout-ansi` and `mylayout-iso` and add the following line to your layout's `rules.mk`:
+
+```
+USER_NAME := mylayout
+```
+
+This is also useful if you have multiple different keyboards with different features physically present on the board (such as one with RGB Lights, and one with Audio, or different number of LEDs, or connected to a different PIN on the controller).
+
+## Configuration Options (`config.h`)
 
 Additionally, `config.h` here will be processed like the same file in your keymap folder.  This is handled separately from the `<name>.h` file.
 
 The reason for this, is that `<name>.h` won't be added in time to add settings (such as `#define TAPPING_TERM 100`), and including the `<name.h>` file in any `config.h` files will result in compile issues.
 
-So you should use the `config.h` for QMK settings, and the `<name>.h` file for user or keymap specific settings.
+!>You should use the `config.h` for [configuration options](config_options.md), and the `<name>.h` file for user or keymap specific settings (such as the enum for layer or keycodes)
 
-`/users/<name>/rules.mk` will be included in the build _after_ the `rules.mk` from your keymap. This allows you to have features in your userspace `rules.mk` that depend on individual QMK features that may or may not be available on a specific keyboard. For example, if you have RGB control features shared between all your keyboards that support RGB lighting, you can `define RGB_ENABLE` in your keymap `rules.mk` and then check for the variable in your userspace `rules.mk` like this:
-```make
-ifdef RGB_ENABLE
-    # Include my fancy rgb functions source here
-endif
-```
-Because of this, any time you turn on QMK features in your `users/<name>/rules.mk`, you should conditionally enable them only if the flag isn't already defined, like this:
-```make
-ifndef TAP_DANCE_ENABLE
-    TAP_DANCE_ENABLE = yes
-endif
-```
-This will ensure that you can explicitly turn off features for an individual keymap.
 
-## Readme
+## Readme (`readme.md`)
 
 Please include authorship (your name, github username, email), and optionally [a license that's GPL compatible](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses).
 
-## `Config.h`
+You can use this as a template: 
+```
+Copyright <year> <name> <email> @<github_username>
 
-If you do add a `config,h` file, you want to make sure that it only gets processed once.  So you may want to start off with something like this:
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 of the License, or
+(at your option) any later version.
 
-```c
-#ifndef USERSPACE_CONFIG_H
-#define USERSPACE_CONFIG_H
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
 
-// Put normal config.h settings here:
-
-#endif // !USERSPACE_CONFIG_H
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
 ```
 
-You can use any option hre that you could use in your keymap's `config.h` file. You can find a list of vales [here](config_options.md).
+You'd want to replace the year, name, email and github username with your info. 
 
-## Example
+Additionally, this is a good place to document your code, if you wish to share it with others. 
 
-For a brief example, checkout `/users/_example/` , or for a more detailed examples check out [`template.h`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.h) and [`template.c`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.c) in `/users/drashna/` .
+# Examples
 
-### Consolidated Macros
+For a brief example, checkout [`/users/_example/`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna).  
+For a more complicated example, checkout [`/users/drashna/`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna)'s userspace.
 
-If you wanted to consolidate macros and other functions into your userspace for all of your keymaps, you can do that.  The issue is that you then cannot call any function defined in your userspace, or it gets complicated.  To better handle this, you can call the functions here and create new functions to use in individual keymaps.
+
+## Customized Functions
+
+QMK has a bunch of [functions](custom_quantum_functions.md) that have [`_quantum`, `_kb`, and `_user` versions](custom_quantum_functions.md#a-word-on-core-vs-keyboards-vs-keymap) that you can use.  You will pretty much always want to use the user version of these functions.  But the problem is that if you use them in your userspace, then you don't have a version that you can use in your keymap. 
+
+However, you can actually add support for keymap version, so that you can use it in both your userspace and your keymap! 
+
+
+For instance, lets looks at the `layer_state_set_user` function.  Lets enable the [Tri Layer State](ref_functions.md#olkb-tri-layers) functionalitly to all of our boards, and then still have your `keymap.c` still able to use this functionality. 
+
+In your `<name.c>` file, you'd want to add this: 
+```c
+__attribute__ ((weak))
+uint32_t layer_state_set_keymap (uint32_t state) {
+  return state;
+}
+
+uint32_t layer_state_set_user (uint32_t state) {
+  state = update_tri_layer_state(state, 2, 3, 5);
+  return layer_state_set_keymap (state);
+}
+```
+The `__attribute__ ((weak))` part tells the compiler that this is a placeholder function that can then be replaced by a version in your `keymap.c`.  That way, you don't need to add it to your `keymap.c`, but if you do, you won't get any conflicts because the function is the same name. 
+
+The `_keymap` part here doesn't matter, it just needs to be something other than `_quantum`, `_kb`, or `_user`, since those are already in use. So you could use `layer_state_set_mine`, `layer_state_set_fn`, or anything else.
+
+You can see a list of this and other common functions in [`template.c`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.c) in [`users/drashna`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna).
+
+## Custom Features
+
+Since the Userspace feature can support a staggering number of boards, you may have boards that you want to enable certain functionality for, but not for others. And you can actually create "features" that you can enable or disable in your own userspace.  
+
+For instance, if you wanted to have a bunch of macros available, but only on certain boards (to save space), you could "hide" them being a `#ifdef MACROS_ENABLED`, and then enable it per board.  To do this, add this to your rules.mk
+```make
+ifeq ($(strip $(MACROS_ENABLED)), yes)
+    OPT_DEFS += -DMACROS_ENABLED
+endif
+```
+The `OPT_DEFS` setting causes `MACROS_ENABLED` to be defined for your keyboards (note the `-D` in front of the name), and you could use `#ifdef MACROS_ENABLED` to check the status in your c/h files, and handle that code based on that. 
+
+Then you add `MACROS_ENABLED = yes` to the `rules.mk` for you keymap to enable this feature and the code in your userspace.
+
+And in your `process_record_user` function, you'd do something like this: 
+```c
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+#ifdef MACROS_ENABLED
+  case MACRO1:
+    if (!record->event.pressed) {
+      SEND_STRING("This is macro 1!");
+    }
+    break;
+  case MACRO2:
+    if (!record->event.pressed) {
+      SEND_STRING("This is macro 2!");
+    }
+    break;
+#endif
+  }
+  return true;
+}
+```
+
+
+## Consolidated Macros
+
+If you wanted to consolidate macros and other functions into your userspace for all of your keymaps, you can do that.  This builds upon the [Customized Functions](#customized-functions) example above. This lets you maintain a bunch of macros that are shared between the different keyboards, and allow for keyboard specific macros, too. 
 
 First, you'd want to go through all of your `keymap.c` files and replace `process_record_user` with `process_record_keymap` instead.   This way, you can still use keyboard specific codes on those boards, and use your custom "global" keycodes as well.   You'll also want to replace `SAFE_RANGE` with `NEW_SAFE_RANGE` so that you wont have any overlapping keycodes
 
 Then add `#include <name.h>` to all of your keymap.c files.  This allows you to use these new keycodes without having to redefine them in each keymap.
 
 Once you've done that, you'll want to set the keycode definitions that you need to the `<name>.h`  file. For instance:
-```
-#ifndef USERSPACE
-#define USERSPACE
+```c
+#pragma once
 
 #include "quantum.h"
+#include "action.h"
+#include "version.h"
 
 // Define all of
 enum custom_keycodes {
   KC_MAKE = SAFE_RANGE,
   NEW_SAFE_RANGE  //use "NEW_SAFE_RANGE" for keymap specific codes
 };
-
-#endif
 ```
 
 Now you want to create the `<name>.c` file, and add this content to it:
 
-```
+```c
 #include "<name>.h"
-#include "quantum.h"
-#include "action.h"
-#include "version.h"
 
 __attribute__ ((weak))
 bool process_record_keymap(uint16_t keycode, keyrecord_t *record) {
@@ -126,14 +220,8 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
 }
 ```
 
-This will add a new `KC_MAKE`  keycode that can be used in any of your keymaps.  And this keycode will output `make <keyboard>:<keymap">`, making frequent compiling easier.  And this will work with any keyboard and any keymap as it will output the current boards info, so that you don't have to type this out every time.
+This will add a new `KC_MAKE` keycode that can be used in any of your keymaps.  And this keycode will output `make <keyboard>:<keymap>`, making frequent compiling easier.  And this will work with any keyboard and any keymap as it will output the current boards info, so that you don't have to type this out every time.
 
 Additionally, this should flash the newly compiled firmware automatically, using the correct utility, based on the bootloader settings (or default to just generating the HEX file). However, it should be noted that this may not work on all systems. AVRDUDE doesn't work on WSL, namely (and will dump the HEX in the ".build" folder instead).
 
-## Override default userspace
 
-By default the userspace used will be the same as the keymap name. In some situations this isn't desirable. For instance, if you use the [layout](feature_layouts.md) feature you can't use the same name for different keymaps (e.g. ANSI and ISO). You can name your layouts `mylayout-ansi` and `mylayout-iso` and add the following line to your layout's `rules.mk`:
-
-```
-USER_NAME := mylayout
-```

docs/features.md

@@ -8,13 +8,17 @@ QMK has a staggering number of features for building your keyboard. It can take
 * [Auto Shift](feature_auto_shift.md) - Tap for the normal key, hold slightly longer for its shifted state.
 * [Backlight](feature_backlight.md) - LED lighting support for your keyboard.
 * [Bootmagic](feature_bootmagic.md) - Adjust the behavior of your keyboard using hotkeys.
+* [Combos](feature_combo.md) - Custom actions for multiple key holds.
+* [Command](feature_command.md) - Runtime version of bootmagic (Formerly known as "Magic").
 * [Dynamic Macros](feature_dynamic_macros.md) - Record and playback macros from the keyboard itself.
+* [Grave Escape](feature_grave_esc.md) - Lets you use a single key for Esc and Grave. 
 * [HD44780 LCD Display](feature_hd44780.md) - Support for LCD character displays using the HD44780 standard.
 * [Key Lock](feature_key_lock.md) - Lock a key in the "down" state.
 * [Layouts](feature_layouts.md) - Use one keymap with any keyboard that supports your layout.
 * [Leader Key](feature_leader_key.md) - Tap the leader key followed by a sequence to trigger custom behavior.
 * [Macros](feature_macros.md) - Send multiple key presses when pressing only one physical key.
 * [Mouse keys](feature_mouse_keys.md) - Control your mouse pointer from your keyboard.
+* [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys) - Sticky Keys, lets hit a key rather than holding it.
 * [Pointing Device](feature_pointing_device.md) - Framework for connecting your custom pointing device to your keyboard.
 * [PS2 Mouse](feature_ps2_mouse.md) - Driver for connecting a PS/2 mouse directly to your keyboard.
 * [RGB Light](feature_rgblight.md) - RGB lighting for your keyboard.

docs/flashing.md

@@ -2,7 +2,7 @@
 
 There are quite a few different types of bootloaders that keyboards use, and just about all of the use a different flashing method. Luckily, projects like the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) aim to be compatible with all the different types without having to think about it much, but this article will describe the different types of bootloaders, and available methods for flashing them.
 
-If you have a bootloader selected with the `BOOTLOADER` variable in your `rules.mk`, QMK will automatically calculate if your .hex file is the right size to be flashed to the device, and output the total size it bytes (along with the max). To run this process manually, compile with the target `check-size`, eg `make planck/rev4:default:check-size`.
+If you have a bootloader selected with the `BOOTLOADER` variable in your `rules.mk`, QMK will automatically calculate if your .hex file is the right size to be flashed to the device, and output the total size in bytes (along with the max). To run this process manually, compile with the target `check-size`, eg `make planck/rev4:default:check-size`.
 
 ## DFU
 
@@ -71,13 +71,19 @@ Flashing sequence:
 
 1. Press the `RESET` keycode, or short RST to GND quickly (you only have 7 seconds to flash once it enters)
 2. Wait for the OS to detect the device
-4. Flash a .hex file
-5. Wait for the device to reset automatically
+3. Flash a .hex file
+4. Wait for the device to reset automatically
 
 or
 
     make <keyboard>:<keymap>:avrdude
 
+or if you want to flash multiple boards, use the following command
+
+    make <keyboard>:<keymap>:avrdude-loop
+
+When you're done flashing boards, you'll need to hit Ctrl + C or whatever the correct keystroke is for your operating system to break the loop.
+
 ## Halfkay
 
 Halfkay is a super-slim protocol developed by PJRC that uses HID, and come on all Teensys (namely the 2.0).
@@ -100,5 +106,28 @@ Flashing sequence:
 
 1. Press the `RESET` keycode, or short RST to GND quickly (you only have 7 seconds to flash once it enters)
 2. Wait for the OS to detect the device
-4. Flash a .hex file
-5. Reset the device into application mode (may be done automatically)
+3. Flash a .hex file
+4. Reset the device into application mode (may be done automatically)
+
+## STM32
+
+All STM32 chips come preloaded with a factory bootloader that cannot be modified nor deleted. Some STM32 chips have bootloaders that do not come with USB programming (e.g. STM32F103) but the process is still the same.
+
+At the moment, no `BOOTLOADER` variable is needed on `rules.mk` for STM32.
+
+Compatible flashers:
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
+* [dfu-util](https://github.com/Stefan-Schmidt/dfu-util) / `:dfu-util` (recommended command line)
+
+Flashing sequence:
+
+1. Enter the bootloader using any of the following methods:
+    * Tap the `RESET` keycode (may not work on STM32F042 devices)
+    * If a reset circuit is present, tap the RESET button
+    * Otherwise, you need to bridge BOOT0 to VCC (via BOOT0 button or bridge), short RESET to GND (via RESET button or bridge), and then let go of the BOOT0 bridge
+2. Wait for the OS to detect the device
+3. Flash a .bin file
+    * You will receive a warning about the DFU signature; Just ignore it
+4. Reset the device into application mode (may be done automatically)
+    * If you are building from command line (e.g. `make planck/rev6:default:dfu-util`), make sure that `:leave` is passed to the `DFU_ARGS` variable inside your `rules.mk` (e.g. `DFU_ARGS = -d 0483:df11 -a 0 -s 0x08000000:leave`) so that your device resets after flashing

docs/getting_started_build_tools.md

@@ -8,7 +8,7 @@ Note: If it is your first time here, Check out the "Complete Newbs guide" instea
 
 ## Linux
 
-To ensure you are always up to date, you can just run `sudo util/install_dependencies.sh`. That should always install all the dependencies needed. **This will run `apt-get upgrade`.**
+To ensure you are always up to date, you can just run `sudo util/qmk_install.sh`. That should always install all the dependencies needed. **This will run `apt-get upgrade`.**
 
 You can also install things manually, but this documentation might not be always up to date with all requirements.
 
@@ -57,11 +57,13 @@ If you're using [homebrew,](http://brew.sh/) you can use the following commands:
     brew tap PX4/homebrew-px4
     brew update
     brew install avr-gcc@7
+    brew link --force avr-gcc@7
     brew install dfu-programmer
+    brew install dfu-util
     brew install gcc-arm-none-eabi
     brew install avrdude
 
-This is the recommended method. If you don't have homebrew, [install it!](http://brew.sh/) It's very much worth it for anyone who works in the command line. Note that the `make` and `make install` portion during the homebrew installation of avr-libc can take over 20 minutes and exhibit high CPU usage.
+This is the recommended method. If you don't have homebrew, [install it!](http://brew.sh/) It's very much worth it for anyone who works in the command line. Note that the `make` and `make install` portion during the homebrew installation of `avr-gcc@7` can take over 20 minutes and exhibit high CPU usage.
 
 ## Windows with msys2 (recommended)
 
@@ -69,9 +71,9 @@ The best environment to use, for Windows Vista through any later version (tested
 
 * Install msys2 by downloading it and following the instructions here: http://www.msys2.org
 * Open the ``MSYS2 MingGW 64-bit`` shortcut
-* Navigate to your qmk checkout. For example, if it's in the root of your c drive:
+* Navigate to your QMK repository. For example, if it's in the root of your c drive:
  * `$ cd /c/qmk_firmware`
-* Run `util/msys2_install.sh` and follow the prompts
+* Run `util/qmk_install.sh` and follow the prompts
 
 ## Windows 10 (deprecated)
 These are the old instructions for Windows 10. We recommend you use [MSYS2 as outlined above](#windows-with-msys2-recommended).