rgb_led struct conversion (aka: Per led (key) type rgb matrix effects - part 2) (#5783)

* Initial conversion of the rgb_led struct

* Converting last keyboard & updating effects to take advantage of the new structure

* New struct should not be const

* Updated docs

* Changing define ___ for no led to NO_LED

* Missed converting some keymap usages of the old struct layout

.clang-format

@@ -1,4 +1,4 @@
----
+---
 BasedOnStyle: Google
 AlignAfterOpenBracket: Align
 AlignConsecutiveAssignments: 'true'
@@ -20,7 +20,7 @@ SortIncludes: 'false'
 SpaceBeforeAssignmentOperators: 'true'
 SpaceBeforeParens: ControlStatements
 SpaceInEmptyParentheses: 'false'
-TabWidth: '2'
+TabWidth: '4'
 UseTab: Never
 
 ...

.editorconfig

@@ -5,7 +5,7 @@ root = true
 
 [*]
 indent_style = space
-indent_size = 2
+indent_size = 4
 
 # We recommend you to keep these unchanged
 charset = utf-8

.gitignore

@@ -54,6 +54,7 @@ util/Win_Check_Output.txt
 .vscode/tasks.json
 .vscode/last.sql
 .vscode/temp.sql
+.vscode/ipch/
 .stfolder
 .tags
 

.travis.yml

@@ -10,17 +10,22 @@ branches:
 env:
   global:
   - secure: vBTSL34BDPxDilKUuTXqU4CJ26Pv5hogD2nghatkxSQkI1/jbdnLj/DQdPUrMJFDIY6TK3AltsBx72MaMsLQ1JO/Ou24IeHINHXzUC1FlS9yQa48cpxnhX5kzXNyGs3oa0qaFbvnr7RgYRWtmD52n4bIZuSuW+xpBv05x2OCizdT2ZonH33nATaHGFasxROm4qYZ241VfzcUv766V6RVHgL4x9V08warugs+RENVkfzxxwhk3NmkrISabze0gSVJLHBPHxroZC6EUcf/ocobcuDrCwFqtEt90i7pNIAFUE7gZsN2uE75LmpzAWin21G7lLPcPL2k4FJVd8an1HiP2WmscJU6U89fOfMb2viObnKcCzebozBCmKGtHEuXZo9FcReOx49AnQSpmESJGs+q2dL/FApkTjQiyT4J6O5dJpoww0/r57Wx0cmmqjETKBb5rSgXM51Etk3wO09mvcPHsEwrT7qH8r9XWdyCDoEn7FCLX3/LYnf/D4SmZ633YPl5gv3v9XEwxR5+04akjgnvWDSNIaDbWBdxHNb7l4pMc+WR1bwCyMyA7KXj0RrftEGOrm9ZRLe6BkbT4cycA+j77nbPOMcyZChliV9pPQos+4TOJoTzcK2L8yWVoY409aDNVuAjdP6Yum0R2maBGl/etLmIMpJC35C5/lZ+dUNjJAM=
+  - MAKEFLAGS="-j3 --output-sync"
 before_install:
   - wget http://ww1.microchip.com/downloads/en/DeviceDoc/avr8-gnu-toolchain-3.5.4.1709-linux.any.x86_64.tar.gz || wget http://qmk.fm/avr8-gnu-toolchain-3.5.4.1709-linux.any.x86_64.tar.gz
+  # Need DFU > .5 for dfu-suffix
+  - sudo add-apt-repository --yes ppa:tormodvolden/ppa
+  - sudo apt-get update -qq
 install:
   - tar -zxf avr8-gnu-toolchain-3.5.4.1709-linux.any.x86_64.tar.gz
   - export PATH="$PATH:$TRAVIS_BUILD_DIR/avr8-gnu-toolchain-linux_x86_64/bin"
   - npm install -g moxygen
+  - sudo apt-get -y --force-yes install dfu-util
 before_script:
   - avr-gcc --version
 script:
 - git rev-parse --short HEAD
-- make test:all
+- bash util/travis_test.sh
 - bash util/travis_build.sh
 - bash util/travis_docs.sh
 addons:

Dockerfile

@@ -1,4 +1,4 @@
-FROM debian
+FROM debian:9
 
 RUN apt-get update && apt-get install --no-install-recommends -y \
     avr-libc \

Makefile

@@ -534,6 +534,8 @@ endef
 %:
 	# Check if we have the CMP tool installed
 	cmp $(ROOT_DIR)/Makefile $(ROOT_DIR)/Makefile >/dev/null 2>&1; if [ $$? -gt 0 ]; then printf "$(MSG_NO_CMP)"; exit 1; fi;
+	# Ensure that python3 is installed. This check can be removed after python is used in more places.
+	if ! python3 --version 1> /dev/null 2>&1; then printf "$(MSG_PYTHON_MISSING)"; fi
 	# Check if the submodules are dirty, and display a warning if they are
 ifndef SKIP_GIT
 	if [ ! -e lib/chibios ]; then git submodule sync lib/chibios && git submodule update --depth 1 --init lib/chibios; fi

Vagrantfile

@@ -6,7 +6,7 @@ Vagrant.configure(2) do |config|
   config.vm.define "qmk_firmware"
 
   # VMware/Virtualbox ( and also Hyperv/Parallels) 64 bit
-  config.vm.box = "bento/ubuntu-16.04"
+  config.vm.box = "generic/debian9"
 
   # This section allows you to customize the Virtualbox VM
   # settings, ie showing the GUI or upping the memory
@@ -55,7 +55,7 @@ Vagrant.configure(2) do |config|
   # image, you'll need to: chmod -R a+rw .
   config.vm.provider "docker" do |docker, override|
     override.vm.box = nil
-    docker.image = "jesselang/debian-vagrant:jessie"
+    docker.image = "jesselang/debian-vagrant:stretch"
     docker.has_ssh = true
   end
 

build_keyboard.mk

@@ -280,6 +280,23 @@ ifneq ("$(wildcard $(KEYBOARD_PATH_1)/config.h)","")
     CONFIG_H += $(KEYBOARD_PATH_1)/config.h
 endif
 
+POST_CONFIG_H :=
+ifneq ("$(wildcard $(KEYBOARD_PATH_1)/post_config.h)","")
+    POST_CONFIG_H += $(KEYBOARD_PATH_1)/post_config.h
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_2)/post_config.h)","")
+    POST_CONFIG_H += $(KEYBOARD_PATH_2)/post_config.h
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_3)/post_config.h)","")
+    POST_CONFIG_H += $(KEYBOARD_PATH_3)/post_config.h
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_4)/post_config.h)","")
+    POST_CONFIG_H += $(KEYBOARD_PATH_4)/post_config.h
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_5)/post_config.h)","")
+    POST_CONFIG_H += $(KEYBOARD_PATH_5)/post_config.h
+endif
+
 # Save the defines and includes here, so we don't include any keymap specific ones
 PROJECT_DEFS := $(OPT_DEFS)
 PROJECT_INC := $(VPATH) $(EXTRAINCDIRS) $(KEYBOARD_PATHS)
@@ -307,7 +324,6 @@ ifneq ("$(wildcard $(KEYMAP_PATH)/config.h)","")
 endif
 
 # # project specific files
-SRC += $(patsubst %.c,%.clib,$(LIB_SRC))
 SRC += $(KEYBOARD_SRC) \
     $(KEYMAP_C) \
     $(QUANTUM_SRC)
@@ -317,15 +333,16 @@ SRC += $(KEYBOARD_SRC) \
 
 # Search Path
 VPATH += $(KEYMAP_PATH)
+VPATH += $(USER_PATH)
 VPATH += $(KEYBOARD_PATHS)
 VPATH += $(COMMON_VPATH)
-VPATH += $(USER_PATH)
 
 include common_features.mk
 include $(TMK_PATH)/protocol.mk
 include $(TMK_PATH)/common.mk
 include bootloader.mk
 
+SRC += $(patsubst %.c,%.clib,$(LIB_SRC))
 SRC += $(patsubst %.c,%.clib,$(QUANTUM_LIB_SRC))
 SRC += $(TMK_COMMON_SRC)
 OPT_DEFS += $(TMK_COMMON_DEFS)
@@ -355,6 +372,7 @@ ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
     include $(VISUALIZER_PATH)/visualizer.mk
 endif
 
+CONFIG_H += $(POST_CONFIG_H)
 ALL_CONFIGS := $(PROJECT_CONFIG) $(CONFIG_H)
 
 OUTPUTS := $(KEYMAP_OUTPUT) $(KEYBOARD_OUTPUT)

common_features.mk

@@ -103,7 +103,9 @@ ifeq ($(strip $(UNICODE_COMMON)), yes)
 endif
 
 ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
+    POST_CONFIG_H += $(QUANTUM_DIR)/rgblight_post_config.h
     OPT_DEFS += -DRGBLIGHT_ENABLE
+    SRC += $(QUANTUM_DIR)/color.c
     SRC += $(QUANTUM_DIR)/rgblight.c
     CIE1931_CURVE = yes
     LED_BREATHING_TABLE = yes
@@ -114,7 +116,7 @@ ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
     endif
 endif
 
-VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 custom
+VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 IS31FL3737 WS2812 custom
 
 LED_MATRIX_ENABLE ?= no
 ifneq ($(strip $(LED_MATRIX_ENABLE)), no)
@@ -135,6 +137,7 @@ ifeq ($(strip $(LED_MATRIX_ENABLE)), IS31FL3731)
 endif
 
 RGB_MATRIX_ENABLE ?= no
+
 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)
@@ -151,19 +154,39 @@ ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
 endif
 
 ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3731)
-    OPT_DEFS += -DIS31FL3731
+    OPT_DEFS += -DIS31FL3731 -DSTM32_I2C -DHAL_USE_I2C=TRUE
     COMMON_VPATH += $(DRIVER_PATH)/issi
     SRC += is31fl3731.c
     SRC += i2c_master.c
 endif
 
 ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3733)
-    OPT_DEFS += -DIS31FL3733
+    OPT_DEFS += -DIS31FL3733 -DSTM32_I2C -DHAL_USE_I2C=TRUE
     COMMON_VPATH += $(DRIVER_PATH)/issi
     SRC += is31fl3733.c
     SRC += i2c_master.c
 endif
 
+ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3737)
+    OPT_DEFS += -DIS31FL3737 -DSTM32_I2C -DHAL_USE_I2C=TRUE
+    COMMON_VPATH += $(DRIVER_PATH)/issi
+    SRC += is31fl3737.c
+    SRC += i2c_master.c
+endif
+
+ifeq ($(strip $(RGB_MATRIX_ENABLE)), WS2812)
+    OPT_DEFS += -DWS2812
+    SRC += ws2812.c
+endif
+
+ifeq ($(strip $(RGB_MATRIX_CUSTOM_KB)), yes)
+    OPT_DEFS += -DRGB_MATRIX_CUSTOM_KB
+endif
+
+ifeq ($(strip $(RGB_MATRIX_CUSTOM_USER)), yes)
+    OPT_DEFS += -DRGB_MATRIX_CUSTOM_USER
+endif
+
 ifeq ($(strip $(TAP_DANCE_ENABLE)), yes)
     OPT_DEFS += -DTAP_DANCE_ENABLE
     SRC += $(QUANTUM_DIR)/process_keycode/process_tap_dance.c
@@ -305,6 +328,7 @@ ifneq ($(strip $(DEBOUNCE_TYPE)), custom)
 endif
 
 ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
+    POST_CONFIG_H += $(QUANTUM_DIR)/split_common/post_config.h
     OPT_DEFS += -DSPLIT_KEYBOARD
 
     # Include files used by all split keyboards
@@ -321,3 +345,16 @@ ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
     endif
     COMMON_VPATH += $(QUANTUM_PATH)/split_common
 endif
+
+ifeq ($(strip $(OLED_DRIVER_ENABLE)), yes)
+    OPT_DEFS += -DOLED_DRIVER_ENABLE
+    COMMON_VPATH += $(DRIVER_PATH)/oled
+    QUANTUM_LIB_SRC += i2c_master.c
+    SRC += oled_driver.c
+endif
+
+SPACE_CADET_ENABLE ?= yes
+ifeq ($(strip $(SPACE_CADET_ENABLE)), yes)
+  SRC += $(QUANTUM_DIR)/process_keycode/process_space_cadet.c
+  OPT_DEFS += -DSPACE_CADET_ENABLE
+endif

docs/_summary.md

@@ -3,7 +3,7 @@
   * [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)
+  * [Git Best Practices](newbs_best_practices.md)
   * [Learning Resources](newbs_learn_more_resources.md)
 
 * [QMK Basics](README.md)
@@ -63,13 +63,13 @@
   * [LED Matrix](feature_led_matrix.md)
   * [Macros](feature_macros.md)
   * [Mouse Keys](feature_mouse_keys.md)
+  * [OLED Driver](feature_oled_driver)
   * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
   * [Pointing Device](feature_pointing_device.md)
   * [PS/2 Mouse](feature_ps2_mouse.md)
   * [RGB Lighting](feature_rgblight.md)
   * [RGB Matrix](feature_rgb_matrix.md)
-  * [Space Cadet Shift](feature_space_cadet_shift.md)
-  * [Space Cadet Shift Enter](feature_space_cadet_shift_enter.md)
+  * [Space Cadet](feature_space_cadet.md)
   * [Stenography](feature_stenography.md)
   * [Swap Hands](feature_swap_hands.md)
   * [Tap Dance](feature_tap_dance.md)
@@ -92,7 +92,8 @@
   * [Understanding QMK](understanding_qmk.md)
 
 * Other Topics
-  * [Using Eclipse with QMK](eclipse.md)
+  * [Using Eclipse with QMK](other_eclipse.md)
+  * [Using VSCode with QMK](other_vscode.md)
   * [Support](support.md)
 
 * QMK Internals (In Progress)

docs/config_options.md

@@ -59,6 +59,8 @@ This is a C header file that is one of the first things included, and will persi
   * define is matrix has ghost (unlikely)
 * `#define DIODE_DIRECTION COL2ROW`
   * COL2ROW or ROW2COL - how your matrix is configured. COL2ROW means the black mark on your diode is facing to the rows, and between the switch and the rows.
+* `#define DIRECT_PINS { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
+  * pins mapped to rows and columns, from left to right. Defines a matrix where each switch is connected to a separate pin and ground.
 * `#define AUDIO_VOICES`
   * turns on the alternate audio voices (to cycle through)
 * `#define C4_AUDIO`
@@ -126,6 +128,8 @@ If you define these options you will enable the associated feature, which may in
 
 * `#define TAPPING_TERM 200`
   * how long before a tap becomes a hold, if set above 500, a key tapped during the tapping term will turn it into a hold too
+* `#define TAPPING_TERM_PER_KEY`
+  * enables handling for per key `TAPPING_TERM` settings
 * `#define RETRO_TAPPING`
   * tap anyway, even after TAPPING_TERM, if there was no other key interruption between press and release
   * See [Retro Tapping](feature_advanced_keycodes.md#retro-tapping) for details
@@ -171,11 +175,17 @@ If you define these options you will enable the associated feature, which may in
 ## RGB Light Configuration
 
 * `#define RGB_DI_PIN D7`
-  * pin the DI on the ws2812 is hooked-up to
+  * pin the DI on the WS2812 is hooked-up to
 * `#define RGBLIGHT_ANIMATIONS`
   * run RGB animations
-* `#define RGBLED_NUM 15`
+* `#define RGBLED_NUM 12`
   * number of LEDs
+* `#define RGBLIGHT_SPLIT`
+  * Needed if both halves of the board have RGB LEDs wired directly to the RGB output pin on the controllers instead of passing the output of the left half to the input of the right half
+* `#define RGBLED_SPLIT { 6, 6 }`
+  * number of LEDs connected that are directly wired to `RGB_DI_PIN` on each half of a split keyboard
+  * First value indicates number of LEDs for left half, second value is for the right half
+  * When RGBLED_SPLIT is defined, RGBLIGHT_SPLIT is implicitly defined.
 * `#define RGBLIGHT_HUE_STEP 12`
   * units to step when in/decreasing hue
 * `#define RGBLIGHT_SAT_STEP 25`
@@ -208,9 +218,13 @@ There are a few different ways to set handedness for split keyboards (listed in
 
 1. Set `SPLIT_HAND_PIN`: Reads a pin to determine handedness. If pin is high, it's the left side, if low, the half is determined to be the right side
 2. Set `EE_HANDS` and flash `eeprom-lefthand.eep`/`eeprom-righthand.eep` to each half
+   * For boards with DFU bootloader you can use `:dfu-split-left`/`:dfu-split-right` to flash these EEPROM files
+   * For boards with Caterina bootloader (like stock Pro Micros), use `:avrdude-split-left`/`:avrdude-split-right`
 3. Set `MASTER_RIGHT`: Half that is plugged into the USB port is determined to be the master and right half (inverse of the default)
 4. Default: The side that is plugged into the USB port is the master half and is assumed to be the left half. The slave side is the right half
 
+#### Defines for handedness
+
 * `#define SPLIT_HAND_PIN B7`
   * For using high/low pin to determine handedness, low = right hand, high = left hand. Replace `B7` with the pin you are using. This is optional, and if you leave `SPLIT_HAND_PIN` undefined, then you can still use the EE_HANDS method or MASTER_LEFT / MASTER_RIGHT defines like the stock Let's Split uses.
 
@@ -232,6 +246,9 @@ There are a few different ways to set handedness for split keyboards (listed in
 * `#define MATRIX_COL_PINS_RIGHT { <col pins> }`
   * If you want to specify a different pinout for the right half than the left half, you can define `MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT`. Currently, the size of `MATRIX_ROW_PINS` must be the same as `MATRIX_ROW_PINS_RIGHT` and likewise for the definition of columns.
 
+* `#define RGBLED_SPLIT { 6, 6 }`
+  * See [RGB Light Configuration](#rgb-light-configuration)
+
 * `#define SELECT_SOFT_SERIAL_SPEED <speed>` (default speed is 1)
   * Sets the protocol speed when using serial communication
   * Speeds:
@@ -313,6 +330,8 @@ Use these to enable or disable building certain features. The more you have enab
   * 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.
+* `LINK_TIME_OPTIMIZATION_ENABLE`
+  = Enables Link Time Optimization (`LTO`) when compiling the keyboard.  This makes the process take longer, but can significantly reduce the compiled size (and since the firmware is small, the added time is not noticable).  However, this will automatically disable the old Macros and Functions features automatically, as these break when `LTO` is enabled.  It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION` 
 
 ## USB Endpoint Limitations
 

docs/contributing.md

@@ -56,7 +56,7 @@ 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 indent using four (4) spaces (soft tabs)
 * 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
@@ -71,6 +71,14 @@ Most of our style is pretty easy to pick up on, but right now it's not entirely
   * 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`)
+* We accept both forms of preprocessor if's: `#ifdef DEFINED` and `#if defined(DEFINED)`
+  * If you are not sure which to prefer use the `#if defined(DEFINED)` form.
+  * Do not change existing code from one style to the other, except when moving to a multiple condition `#if`.
+  * Do not put whitespace between `#` and `if`.
+  * When deciding how (or if) to indent directives keep these points in mind:
+    * Readability is more important than consistency.
+    * Follow the file's existing style. If the file is mixed follow the style that makes sense for the section you are modifying.
+    * When choosing to indent you can follow the indention level of the surrounding C code, or preprocessor directives can have their own indent level. Choose the style that best communicates the intent of your code.
 
 Here is an example for easy reference:
 

docs/custom_quantum_functions.md

@@ -116,29 +116,29 @@ Use the `IS_LED_ON(usb_led, led_name)` and `IS_LED_OFF(usb_led, led_name)` macro
 ```c
 void led_set_user(uint8_t usb_led) {
     if (IS_LED_ON(usb_led, USB_LED_NUM_LOCK)) {
-        PORTB |= (1<<0);
+        writePinLow(B0);
     } else {
-        PORTB &= ~(1<<0);
+        writePinHigh(B0);
     }
     if (IS_LED_ON(usb_led, USB_LED_CAPS_LOCK)) {
-        PORTB |= (1<<1);
+        writePinLow(B1);
     } else {
-        PORTB &= ~(1<<1);
+        writePinHigh(B1);
     }
     if (IS_LED_ON(usb_led, USB_LED_SCROLL_LOCK)) {
-        PORTB |= (1<<2);
+        writePinLow(B2);
     } else {
-        PORTB &= ~(1<<2);
+        writePinHigh(B2);
     }
     if (IS_LED_ON(usb_led, USB_LED_COMPOSE)) {
-        PORTB |= (1<<3);
+        writePinLow(B3);
     } else {
-        PORTB &= ~(1<<3);
+        writePinHigh(B3);
     }
     if (IS_LED_ON(usb_led, USB_LED_KANA)) {
-        PORTB |= (1<<4);
+        writePinLow(B4);
     } else {
-        PORTB &= ~(1<<4);
+        writePinHigh(B4);
     }
 }
 ```
@@ -189,16 +189,18 @@ However, if you have hardware stuff that you need initialized, this is the best
 
 ### Example `keyboard_pre_init_user()` Implementation
 
-This example, at the keyboard level, sets up B1, B2, and B3 as LED pins.
+This example, at the keyboard level, sets up B0, B1, B2, B3, and B4 as LED pins.
 
 ```c
 void keyboard_pre_init_user(void) {
   // Call the keyboard pre init code.
 
   // Set our LED pins as output
-  DDRB |= (1<<1);
-  DDRB |= (1<<2);
-  DDRB |= (1<<3);
+  setPinOutput(B0);
+  setPinOutput(B1);
+  setPinOutput(B2);
+  setPinOutput(B3);
+  setPinOutput(B4);
 }
 ```
 
@@ -233,7 +235,7 @@ This example, running after everything else has initialized, sets up the rgb und
 void keyboard_post_init_user(void) {
   // Call the post init code.
   rgblight_enable_noeeprom(); // enables Rgb, without saving settings
-  rgblight_sethsv_noeeprom(180, 255, 255): // sets the color to teal/cyan without saving
+  rgblight_sethsv_noeeprom(180, 255, 255); // sets the color to teal/cyan without saving
   rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // sets mode to Fast breathing without saving
 }
 ```
@@ -270,16 +272,13 @@ This is controlled by two functions: `suspend_power_down_*` and `suspend_wakeup_
 
 ### 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)
-{
+void suspend_power_down_user(void) {
     rgb_matrix_set_suspend_state(true);
 }
 
-void suspend_wakeup_init_user(void)
-{
+void suspend_wakeup_init_user(void) {
     rgb_matrix_set_suspend_state(false);
 }
 ```
@@ -324,6 +323,7 @@ uint32_t layer_state_set_user(uint32_t state) {
 * Keyboard/Revision: `uint32_t layer_state_set_kb(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)
 
 
@@ -343,7 +343,7 @@ This is an example of how to add settings, and read and write it. We're using th
 
 
 In your keymap.c file, add this to the top:
-```
+```c
 typedef union {
   uint32_t raw;
   struct {
@@ -356,11 +356,11 @@ 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. 
+We're using `rgb_layer_change`, for the `layer_state_set_*` function, and use `keyboard_post_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) {
+Now, using the `keyboard_post_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: 
+```c
+void keyboard_post_init_user(void) {
   // Call the keymap level matrix init.
 
   // Read the user config from EEPROM
@@ -376,7 +376,7 @@ void matrix_init_user(void) {
 ```
 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. 
 
-```
+```c
 uint32_t layer_state_set_user(uint32_t state) {
     switch (biton32(state)) {
     case _RAISE:
@@ -398,8 +398,8 @@ uint32_t layer_state_set_user(uint32_t state) {
   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:
-```
+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`. 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:
+```c
 
 bool process_record_user(uint16_t keycode, keyrecord_t *record) {
   switch (keycode) {
@@ -416,11 +416,6 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
             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
@@ -443,10 +438,11 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
   }
 }
 ```
-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. 
+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. To force an EEPROM reset, use the `EEP_RST` keycode or [Bootmagic](feature_bootmagic.md) functionallity. For example, if you want to set rgb layer indication by default, and save the default valued. 
 
-```
+```c
 void eeconfig_init_user(void) {  // EEPROM is getting reset! 
+  user_config.raw = 0;
   user_config.rgb_layer_change = true; // We want this enabled by default
   eeconfig_update_user(user_config.raw); // Write default value to EEPROM now
 
@@ -465,3 +461,31 @@ And you're done.  The RGB layer indication will only work if you want it to. And
 * 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. 
+
+# Custom Tapping Term
+
+By default, the tapping term is defined globally, and is not configurable by key.  For most users, this is perfectly fine.  But in come cases, dual function keys would be greatly improved by different timeouts than `LT` keys, or because some keys may be easier to hold than others.  Instead of using custom key codes for each, this allows for per key configurable `TAPPING_TERM`.
+
+To enable this functionality, you need to add `#define TAPPING_TERM_PER_KEY` to your `config.h`, first.  
+
+
+## Example `get_tapping_term` Implementation
+
+To change the `TAPPING TERM` based on the keycode, you'd want to add something like the following to your `keymap.c` file: 
+
+```c
+uint16_t get_tapping_term(uint16_t keycode) {
+  switch (keycode) {
+    case SFT_T(KC_SPC):
+      return TAPPING_TERM + 1250;
+    case LT(1, KC_GRV):
+      return 130;
+    default:
+      return TAPPING_TERM;
+  }
+}
+```
+
+### `get_tapping_term` Function Documentation
+
+Unlike many of the other functions here, there isn't a need (or even reason) to have a quantum or keyboard level function. Only a user level function is useful here, so no need to mark it as such.

docs/faq_build.md

@@ -15,7 +15,7 @@ or just:
 
     $ sudo make <keyboard>:<keymap>:dfu
 
-Note that running `make` with `sudo` is generally *not* a good idea, and you should use one of the former methods, if possible.
+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
 On Linux, you'll need proper privileges to access the MCU. You can either use
@@ -36,6 +36,12 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="066
 # tmk keyboard products     https://github.com/tmk/tmk_keyboard
 SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
 ```
+**/etc/udev/rules.d/54-input-club-keyboard.rules:**
+
+```
+# Input Club keyboard bootloader
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666"
+```
 
 ### Serial device is not detected in bootloader mode on Linux
 Make sure your kernel has appropriate support for your device. If your device uses USB ACM, such as
@@ -47,7 +53,12 @@ If you're using Windows to flash your keyboard, and you are running into issues,
 
 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.
+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 `WinUSB` option, and hit "Reinstall driver". Once you've done that, try flashing your board, again.  If that doesn't work, try all of the options, until one works. 
+
+?> There isn't a best option for which driver should be used here.  Some options work better on some systems than others.  libUSB and WinUSB seem to be the best options here.
+
+If the bootloader doesn't show up in the list for devices, you may need to enable the "List all devices" option in the `Options` menu, and then find the bootloader in question. 
+
 
 ## WINAVR is Obsolete
 It is no longer recommended and may cause some problem.

docs/feature_audio.md

@@ -100,6 +100,16 @@ In music mode, the following keycodes work differently, and don't pass through:
 * `KC_UP` - speed-up playback
 * `KC_DOWN` - slow-down playback
 
+The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`:
+
+    #define PITCH_STANDARD_A 432.0f
+
+You can completely disable Music Mode as well. This is useful, if you're pressed for space on your controller.  To disable it, add this to your `config.h`:
+
+    #define NO_MUSIC_MODE
+
+### Music Mask
+
 By default, `MUSIC_MASK` is set to `keycode < 0xFF` which means keycodes less than `0xFF` are turned into notes, and don't output anything. You can change this by defining this in your `config.h` like this:
 
     #define MUSIC_MASK keycode != KC_NO
@@ -120,13 +130,26 @@ For a more advanced way to control which keycodes should still be processed, you
 
 Things that return false are not part of the mask, and are always processed.
 
-The pitch standard (`PITCH_STANDARD_A`) is 440.0f by default - to change this, add something like this to your `config.h`:
+### Music Map
 
-    #define PITCH_STANDARD_A 432.0f
+By default, the Music Mode uses the columns and row to determine the scale for the keys. For a board that uses a rectangular matrix that matches the keyboard layout, this is just fine.  However, for boards that use a more complicated matrix (such as the Planck Rev6, or many split keyboards) this would result in a very skewed experience.  
 
-You can completely disable Music Mode as well. This is useful, if you're pressed for space on your controller.  To disable it, add this to your `config.h`:
+However, the Music Map option allows you to remap the scaling for the music mode, so it fits the layout, and is more natural. 
 
-    #define NO_MUSIC_MODE
+To enable this feature, add `#define MUSIC_MAP` to your `config.h` file, and then you will want to add a `uint8_t music_map` to your keyboard's `c` file, or your `keymap.c`.
+
+```c
+const uint8_t music_map[MATRIX_ROWS][MATRIX_COLS] = LAYOUT_ortho_4x12(
+	36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47,
+	24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35,
+	12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23,
+	 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11
+);
+```
+
+You will want to use whichever `LAYOUT` macro that your keyboard uses here.  This maps it to the correct key location.  Start in  the bottom left of the keyboard layout, and  move to the right, and then upwards.  Fill in all the entries until you have a complete matrix.  
+
+You can look at the [Planck Keyboard](https://github.com/qmk/qmk_firmware/blob/e9ace1487887c1f8b4a7e8e6d87c322988bec9ce/keyboards/planck/planck.c#L24-L29) as an example of how to implement this. 
 
 ## Audio Click
 

docs/feature_backlight.md

@@ -30,7 +30,31 @@ You should then be able to use the keycodes below to change the backlight level.
 
 This feature is distinct from both the [RGB underglow](feature_rgblight.md) and [RGB matrix](feature_rgb_matrix.md) features as it usually allows for only a single colour per switch, though you can obviously use multiple different coloured LEDs on a keyboard.
 
-Hardware PWM is only supported on certain pins of the MCU, so if the backlighting is not connected to one of them, a software implementation will be used, and backlight breathing will not be available. Currently the supported pins are `B5`, `B6`, `B7`, and `C6`.
+Hardware PWM is only supported on certain pins of the MCU, so if the backlighting is not connected to one of them, a software PWM implementation triggered by hardware timer interrupts will be used.
+
+Hardware PWM is supported according to the following table:
+
+| Backlight Pin | Hardware timer |
+|---------------|----------------|
+|`B5`           | Timer 1        |
+|`B6`           | Timer 1        |
+|`B7`           | Timer 1        |
+|`C6`           | Timer 3        |
+| other         | Software PWM   |
+
+The [audio feature](feature_audio.md) also uses hardware timers. Please refer to the following table to know what hardware timer the software PWM will use depending on the audio configuration:
+
+| Audio Pin(s) | Audio Timer | Software PWM Timer |
+|--------------|-------------|--------------------|
+| `C4`         | Timer 3     | Timer 1            |
+| `C5`         | Timer 3     | Timer 1            |
+| `C6`         | Timer 3     | Timer 1            |
+| `B5`         | Timer 1     | Timer 3            |
+| `B6`         | Timer 1     | Timer 3            |
+| `B7`         | Timer 1     | Timer 3            |
+| `Bx` & `Cx`  | Timer 1 & 3 | None               |
+
+When all timers are in use for [audio](feature_audio.md), the backlight software PWM will not use a hardware timer, but instead will be triggered during the matrix scan. In this case the backlight doesn't support breathing and might show lighting artifacts (for instance flickering), because the PWM computation might not be called with enough timing precision.
 
 ## Configuration
 
@@ -39,11 +63,26 @@ To change the behaviour of the backlighting, `#define` these in your `config.h`:
 |Define               |Default      |Description                                                                                                  |
 |---------------------|-------------|-------------------------------------------------------------------------------------------------------------|
 |`BACKLIGHT_PIN`      |`B7`         |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this|
+|`BACKLIGHT_PINS`     |*Not defined*|experimental: see below for more information|
 |`BACKLIGHT_LEVELS`   |`3`          |The number of brightness levels (maximum 15 excluding off)                                                   |
 |`BACKLIGHT_CAPS_LOCK`|*Not defined*|Enable Caps Lock indicator using backlight (for keyboards without dedicated LED)                             |
-|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if hardware PWM is used                                                          |
+|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported                                                          |
 |`BREATHING_PERIOD`   |`6`          |The length of one backlight "breath" in seconds                                                              |
 
+## Multiple backlight pins
+
+Most keyboards have only one backlight pin which control all backlight LEDs (especially if the backlight is connected to an hardware PWM pin).
+In software PWM, it is possible to define multiple backlight pins. All those pins will be turned on and off at the same time during the PWM duty cycle.
+This feature allows to set for instance the Caps Lock LED (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped LCTRL in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on.
+
+To activate multiple backlight pins, you need to add something like this to your user `config.h`:
+
+~~~c
+#define BACKLIGHT_LED_COUNT 2
+#undef BACKLIGHT_PIN
+#define BACKLIGHT_PINS { F5, B2 }
+~~~
+
 ## Hardware PWM Implementation
 
 When using the supported pins for backlighting, QMK will use a hardware timer configured to output a PWM signal. This timer will count up to `ICRx` (by default `0xFFFF`) before resetting to 0.
@@ -53,6 +92,15 @@ In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus th
 The breathing effect is achieved by registering an interrupt handler for `TIMER1_OVF_vect` that is called whenever the counter resets, roughly 244 times per second.
 In this handler, the value of an incrementing counter is mapped onto a precomputed brightness curve. To turn off breathing, the interrupt handler is simply disabled, and the brightness reset to the level stored in EEPROM.
 
+## Software PWM Implementation
+
+When `BACKLIGHT_PIN` is not set to a hardware backlight pin, QMK will use a hardware timer configured to trigger software interrupts. This time will count up to `ICRx` (by default `0xFFFF`) before resetting to 0.
+When resetting to 0, the CPU will fire an OVF (overflow) interrupt that will turn the LEDs on, starting the duty cycle.
+The desired brightness is calculated and stored in the `OCRxx` register. When the counter reaches this value, the CPU will fire a Compare Output match interrupt, which will turn the LEDs off.
+In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus the brightness, where `0x0000` is completely off and `0xFFFF` is completely on.
+
+The breathing effect is the same as in the hardware PWM implementation.
+
 ## Backlight Functions
 
 |Function  |Description                                                |

docs/feature_combo.md

@@ -19,7 +19,6 @@ 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
 

docs/feature_debounce_type.md

@@ -33,7 +33,10 @@ The debounce code is compatible with split keyboards.
 # Changing between included debouncing methods
 You can either use your own code, by including your own debounce.c, or switch to another included one.
 Included debounce methods are:
-* eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE_DELAY``` millseconds of no further input for that key
+* eager_pr - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE_DELAY``` milliseconds of no further input for that row. 
+For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be
+appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use.
+* eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE_DELAY``` milliseconds of no further input for that key
 * sym_g - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE_DELAY``` milliseconds of no changes has occured, all input changes are pushed.
 
 

docs/feature_grave_esc.md

@@ -18,7 +18,7 @@ If Mary presses GESC on her keyboard, the OS will see an KC_ESC character. Now i
 
 ### Caveats
 
- * On macOS CMD/GUI + KC_GRV is actually mapped to a hot key so it will not output a backtick.
+On macOS, Command+<code>&#96;</code> is by default mapped to "Move focus to next window" so it will not output a backtick. Additionally, Terminal always recognises this shortcut to cycle between windows, even if the shortcut is changed in the Keyboard preferences.
 
 ## Configuration
 

docs/feature_macros.md

@@ -146,9 +146,102 @@ send_string(my_str);
 SEND_STRING(".."SS_TAP(X_END));
 ```
 
-## The Old Way: `MACRO()` & `action_get_macro`
 
-?> This is inherited from TMK, and hasn't been updated - it's recommend that you use `SEND_STRING` and `process_record_user` instead.
+## Advanced Macro Functions
+
+There are some functions you may find useful in macro-writing. Keep in mind that while you can write some fairly advanced code within a macro, if your functionality gets too complex you may want to define a custom keycode instead. Macros are meant to be simple.
+
+### `record->event.pressed`
+
+This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is
+
+```c
+    if (record->event.pressed) {
+        // on keydown
+    } else {
+        // on keyup
+    }
+```
+
+### `register_code(<kc>);`
+
+This sends the `<kc>` keydown event to the computer. Some examples would be `KC_ESC`, `KC_C`, `KC_4`, and even modifiers such as `KC_LSFT` and `KC_LGUI`.
+
+### `unregister_code(<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).
+
+If you're having issues with taps (un)registering, you can add a delay between the register and unregister events by setting `#define TAP_CODE_DELAY 100` in your `config.h` file. The value is in milliseconds.
+
+### `register_code16(<kc>);`, `unregister_code16(<kc>);` and `tap_code16(<kc>);`
+
+These functions work similar to their regular counterparts, but allow you to use modded keycodes (with Shift, Alt, Control, and/or GUI applied to them).
+
+Eg, you could use `register_code16(S(KC_5));` instead of registering the mod, then registering the keycode.
+
+### `clear_keyboard();`
+
+This will clear all mods and keys currently pressed.
+
+### `clear_mods();`
+
+This will clear all mods currently pressed.
+
+### `clear_keyboard_but_mods();`
+
+This will clear all keys besides the mods currently pressed.
+
+## Advanced Example: 
+
+### Super ALT↯TAB
+
+This macro will register `KC_LALT` and tap `KC_TAB`, then wait for 1000ms. If the key is tapped again, it will send another `KC_TAB`; if there is no tap, `KC_LALT` will be unregistered, thus allowing you to cycle through windows. 
+
+```c
+bool is_alt_tab_active = false;    # ADD this near the begining of keymap.c
+uint16_t alt_tab_timer = 0;        # we will be using them soon.
+
+enum custom_keycodes {             # Make sure have the awesome keycode ready
+  ALT_TAB = SAFE_RANGE,
+};
+
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {               # This will do most of the grunt work with the keycodes.
+    case ALT_TAB:
+      if (record->event.pressed) {
+        if (!is_alt_tab_active) {
+          is_alt_tab_active = true;
+          register_code(KC_LALT);
+        } 
+        alt_tab_timer = timer_read();
+        register_code(KC_TAB);
+      } else {
+        unregister_code(KC_TAB);
+      }
+      break;
+  }
+  return true;
+}
+
+void matrix_scan_user(void) {     # The very important timer. 
+  if (is_alt_tab_active) {
+    if (timer_elapsed(alt_tab_timer) > 1000) {
+      unregister_code(KC_LALT);
+      is_alt_tab_active = false;
+    }
+  }
+}
+```
+
+---
+
+##  **(DEPRECATED)** The Old Way: `MACRO()` & `action_get_macro`
+
+!> This is inherited from TMK, and hasn't been updated - it's recommended that you use `SEND_STRING` and `process_record_user` instead.
 
 By default QMK assumes you don't have any macros. To define your macros you create an `action_get_macro()` function. For example:
 
@@ -222,49 +315,10 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 };
 ```
 
-## Advanced Macro Functions
 
-There are some functions you may find useful in macro-writing. Keep in mind that while you can write some fairly advanced code within a macro if your functionality gets too complex you may want to define a custom keycode instead. Macros are meant to be simple.
+## Advanced Example: 
 
-### `record->event.pressed`
-
-This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is
-
-```c
-    if (record->event.pressed) {
-        // on keydown
-    } else {
-        // on keyup
-    }
-```
-
-### `register_code(<kc>);`
-
-This sends the `<kc>` keydown event to the computer. Some examples would be `KC_ESC`, `KC_C`, `KC_4`, and even modifiers such as `KC_LSFT` and `KC_LGUI`.
-
-### `unregister_code(<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).
-
-If you're having issues with taps (un)registering, you can add a delay between the register and unregister events by setting `#define TAP_CODE_DELAY 100` in your `config.h` file. The value is in milliseconds.
-
-### `clear_keyboard();`
-
-This will clear all mods and keys currently pressed.
-
-### `clear_mods();`
-
-This will clear all mods currently pressed.
-
-### `clear_keyboard_but_mods();`
-
-This will clear all keys besides the mods currently pressed.
-
-## Advanced Example: Single-Key Copy/Paste
+### Single-Key Copy/Paste
 
 This example defines a macro which sends `Ctrl-C` when pressed down, and `Ctrl-V` when released.
 

docs/feature_mouse_keys.md

@@ -1,81 +1,119 @@
-# Mousekeys
+# Mouse keys
 
+Mouse keys is a feature that allows you to emulate a mouse using your keyboard. You can move the pointer at different speeds, press 5 buttons and scroll in 8 directions.
 
-Mousekeys is a feature that allows you to emulate a mouse using your keyboard. You can move the pointer around, click up to 5 buttons, and even scroll in all 4 directions. QMK uses the same algorithm as the X Window System MouseKeysAccel feature. You can read more about it [on Wikipedia](https://en.wikipedia.org/wiki/Mouse_keys).
+## Adding mouse keys to your keyboard
 
-## Adding Mousekeys to a Keymap
+To use mouse keys, you must at least enable mouse keys support and map mouse actions to keys on your keyboard.
 
-There are two steps to adding Mousekeys support to your keyboard. You must enable support in the `rules.mk` file and you must map mouse actions to keys on your keyboard.
+### Enabling mouse keys
 
-### Adding Mousekeys Support in the `rules.mk`
+To enable mouse keys, add the following line to your keymap’s `rules.mk`:
 
-To add support for Mousekeys you simply need to add a single line to your keymap's `rules.mk`:
-
-```
+```c
 MOUSEKEY_ENABLE = yes
 ```
 
-You can see an example here: https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/66/keymaps/mouse_keys/rules.mk
+### Mapping mouse actions
 
-### Mapping Mouse Actions to Keyboard Keys
+In your keymap you can use the following keycodes to map key presses to mouse actions:
 
-You can use these keycodes within your keymap to map button presses to mouse actions:
+|Key             |Aliases  |Description      |
+|----------------|---------|-----------------|
+|`KC_MS_UP`      |`KC_MS_U`|Move cursor up   |
+|`KC_MS_DOWN`    |`KC_MS_D`|Move cursor down |
+|`KC_MS_LEFT`    |`KC_MS_L`|Move cursor left |
+|`KC_MS_RIGHT`   |`KC_MS_R`|Move cursor right|
+|`KC_MS_BTN1`    |`KC_BTN1`|Press button 1   |
+|`KC_MS_BTN2`    |`KC_BTN2`|Press button 2   |
+|`KC_MS_BTN3`    |`KC_BTN3`|Press button 3   |
+|`KC_MS_BTN4`    |`KC_BTN4`|Press button 4   |
+|`KC_MS_BTN5`    |`KC_BTN5`|Press button 5   |
+|`KC_MS_WH_UP`   |`KC_WH_U`|Move wheel up    |
+|`KC_MS_WH_DOWN` |`KC_WH_D`|Move wheel down  |
+|`KC_MS_WH_LEFT` |`KC_WH_L`|Move wheel left  |
+|`KC_MS_WH_RIGHT`|`KC_WH_R`|Move wheel right |
+|`KC_MS_ACCEL0`  |`KC_ACL0`|Set speed to 0   |
+|`KC_MS_ACCEL1`  |`KC_ACL1`|Set speed to 1   |
+|`KC_MS_ACCEL2`  |`KC_ACL2`|Set speed to 2   |
 
-|Key             |Aliases  |Description                |
-|----------------|---------|---------------------------|
-|`KC_MS_UP`      |`KC_MS_U`|Mouse Cursor Up            |
-|`KC_MS_DOWN`    |`KC_MS_D`|Mouse Cursor Down          |
-|`KC_MS_LEFT`    |`KC_MS_L`|Mouse Cursor Left          |
-|`KC_MS_RIGHT`   |`KC_MS_R`|Mouse Cursor Right         |
-|`KC_MS_BTN1`    |`KC_BTN1`|Mouse Button 1             |
-|`KC_MS_BTN2`    |`KC_BTN2`|Mouse Button 2             |
-|`KC_MS_BTN3`    |`KC_BTN3`|Mouse Button 3             |
-|`KC_MS_BTN4`    |`KC_BTN4`|Mouse Button 4             |
-|`KC_MS_BTN5`    |`KC_BTN5`|Mouse Button 5             |
-|`KC_MS_WH_UP`   |`KC_WH_U`|Mouse Wheel Up             |
-|`KC_MS_WH_DOWN` |`KC_WH_D`|Mouse Wheel Down           |
-|`KC_MS_WH_LEFT` |`KC_WH_L`|Mouse Wheel Left           |
-|`KC_MS_WH_RIGHT`|`KC_WH_R`|Mouse Wheel Right          |
-|`KC_MS_ACCEL0`  |`KC_ACL0`|Set mouse acceleration to 0|
-|`KC_MS_ACCEL1`  |`KC_ACL1`|Set mouse acceleration to 1|
-|`KC_MS_ACCEL2`  |`KC_ACL2`|Set mouse acceleration to 2|
+## Configuring mouse keys
 
-You can see an example in the `_ML` here: https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/66/keymaps/mouse_keys/keymap.c#L46
+Mouse keys supports two different modes to move the cursor:
 
-## Configuring the Behavior of Mousekeys
+* **Accelerated (default):** Holding movement keys accelerates the cursor until it reaches its maximum speed.
+* **Constant:** Holding movement keys moves the cursor at constant speeds.
 
-The default speed for controlling the mouse with the keyboard is intentionally slow. You can adjust these parameters by adding these settings to your keymap's `config.h` file. All times are specified in milliseconds (ms).
+The same principle applies to scrolling.
 
-```
-#define MOUSEKEY_DELAY             300
-#define MOUSEKEY_INTERVAL          50
-#define MOUSEKEY_MAX_SPEED         10
-#define MOUSEKEY_TIME_TO_MAX       20
-#define MOUSEKEY_WHEEL_MAX_SPEED   8
-#define MOUSEKEY_WHEEL_TIME_TO_MAX 40
+Configuration options that are times, intervals or delays are given in milliseconds. Scroll speed is given as multiples of the default scroll step. For example, a scroll speed of 8 means that each scroll action covers 8 times the length of the default scroll step as defined by your operating system or application.
+
+### Accelerated mode
+
+This is the default mode. You can adjust the cursor and scrolling acceleration using the following settings in your keymap’s `config.h` file:
+
+|Define                      |Default|Description                                              |
+|----------------------------|-------|---------------------------------------------------------|
+|`MOUSEKEY_DELAY`            |300    |Delay between pressing a movement key and cursor movement|
+|`MOUSEKEY_INTERVAL`         |50     |Time between cursor movements                            |
+|`MOUSEKEY_MAX_SPEED`        |10     |Maximum cursor speed at which acceleration stops         |
+|`MOUSEKEY_TIME_TO_MAX`      |20     |Time until maximum cursor speed is reached               |
+|`MOUSEKEY_WHEEL_MAX_SPEED`  |8      |Maximum number of scroll steps per scroll action         |
+|`MOUSEKEY_WHEEL_TIME_TO_MAX`|40     |Time until maximum scroll speed is reached               |
+
+Tips:
+
+* Setting `MOUSEKEY_DELAY` too low makes the cursor unresponsive. Setting it too high makes small movements difficult.
+* For smoother cursor movements, lower the value of `MOUSEKEY_INTERVAL`. If the refresh rate of your display is 60Hz, you could set it to `16` (1/60). As this raises the cursor speed significantly, you may want to lower `MOUSEKEY_MAX_SPEED`.
+* Setting `MOUSEKEY_TIME_TO_MAX` or `MOUSEKEY_WHEEL_TIME_TO_MAX` to `0` will disable acceleration for the cursor or scrolling respectively. This way you can make one of them constant while keeping the other accelerated, which is not possible in constant speed mode.
+
+Cursor acceleration uses the same algorithm as the X Window System MouseKeysAccel feature. You can read more about it [on Wikipedia](https://en.wikipedia.org/wiki/Mouse_keys).
+
+### Constant mode
+
+In this mode you can define multiple different speeds for both the cursor and the mouse wheel. There is no acceleration. `KC_ACL0`, `KC_ACL1` and `KC_ACL2` change the cursor and scroll speed to their respective setting.
+
+You can choose whether speed selection is momentary or tap-to-select:
+
+* **Momentary:** The chosen speed is only active while you hold the respective key. When the key is raised, mouse keys returns to the unmodified speed.
+* **Tap-to-select:** The chosen speed is activated when you press the respective key and remains active even after the key has been raised. The default speed is that of `KC_ACL1`. There is no unmodified speed.
+
+The default speeds from slowest to fastest are as follows:
+
+* **Momentary:** `KC_ACL0` < `KC_ACL1` < *unmodified* < `KC_ACL2`
+* **Tap-to-select:** `KC_ACL0` < `KC_ACL1` < `KC_ACL2`
+
+To use constant speed mode, you must at least define `MK_3_SPEED` in your keymap’s `config.h` file:
+
+```c
+#define MK_3_SPEED
 ```
 
+To enable momentary mode, also define `MK_MOMENTARY_ACCEL`:
 
-### `MOUSEKEY_DELAY`
+```c
+#define MK_MOMENTARY_ACCEL
+```
 
-When one of the mouse movement buttons is pressed this setting is used to define the delay between that button press and the mouse cursor moving. Some people find that small movements are impossible if this setting is too low, while settings that are too high feel sluggish.
+Use the following settings if you want to adjust cursor movement or scrolling:
 
-### `MOUSEKEY_INTERVAL`
-
-When a movement key is held down this specifies how long to wait between each movement report. Lower settings will translate into an effectively higher mouse speed.
-
-### `MOUSEKEY_MAX_SPEED`
-
-As a movement key is held down the speed of the mouse cursor will increase until it reaches `MOUSEKEY_MAX_SPEED`.
-
-### `MOUSEKEY_TIME_TO_MAX`
-
-How long you want to hold down a movement key for until `MOUSEKEY_MAX_SPEED` is reached. This controls how quickly your cursor will accelerate.
-
-### `MOUSEKEY_WHEEL_MAX_SPEED`
-
-The top speed for scrolling movements.
-
-### `MOUSEKEY_WHEEL_TIME_TO_MAX`
-
-How long you want to hold down a scroll key for until `MOUSEKEY_WHEEL_MAX_SPEED` is reached. This controls how quickly your scrolling will accelerate.
+|Define               |Default      |Description                                |
+|---------------------|-------------|-------------------------------------------|
+|`MK_3_SPEED`         |*Not defined*|Enable constant cursor speeds              |
+|`MK_MOMENTARY_ACCEL` |*Not defined*|Enable momentary speed selection           |
+|`MK_C_OFFSET_UNMOD`  |16           |Cursor offset per movement (unmodified)    |
+|`MK_C_INTERVAL_UNMOD`|16           |Time between cursor movements (unmodified) |
+|`MK_C_OFFSET_0`      |1            |Cursor offset per movement (`KC_ACL0`)     |
+|`MK_C_INTERVAL_0`    |32           |Time between cursor movements (`KC_ACL0`)  |
+|`MK_C_OFFSET_1`      |4            |Cursor offset per movement (`KC_ACL1`)     |
+|`MK_C_INTERVAL_1`    |16           |Time between cursor movements (`KC_ACL1`)  |
+|`MK_C_OFFSET_2`      |32           |Cursor offset per movement (`KC_ACL2`)     |
+|`MK_C_INTERVAL_2`    |16           |Time between cursor movements (`KC_ACL2`)  |
+|`MK_W_OFFSET_UNMOD`  |1            |Scroll steps per scroll action (unmodified)|
+|`MK_W_INTERVAL_UNMOD`|40           |Time between scroll steps (unmodified)     |
+|`MK_W_OFFSET_0`      |1            |Scroll steps per scroll action (`KC_ACL0`) |
+|`MK_W_INTERVAL_0`    |360          |Time between scroll steps (`KC_ACL0`)      |
+|`MK_W_OFFSET_1`      |1            |Scroll steps per scroll action (`KC_ACL1`) |
+|`MK_W_INTERVAL_1`    |120          |Time between scroll steps (`KC_ACL1`)      |
+|`MK_W_OFFSET_2`      |1            |Scroll steps per scroll action (`KC_ACL2`) |
+|`MK_W_INTERVAL_2`    |20           |Time between scroll steps (`KC_ACL2`)      |

docs/feature_oled_driver.md

@@ -0,0 +1,274 @@
+# OLED Driver
+
+## OLED Supported Hardware
+
+128x32 OLED modules using SSD1306 driver IC over I2C. Supported on AVR based keyboards. Possible but untested hardware includes ARM based keyboards and other sized OLED modules using SSD1306 over I2C, such as 128x64. 
+
+!> Warning: This OLED Driver currently uses the new i2c_master driver from split common code. If your split keyboard uses i2c to communication between sides this driver could cause an address conflict (serial is fine). Please contact your keyboard vendor and ask them to migrate to the latest split common code to fix this. 
+
+## Usage
+
+To enable the OLED feature, there are three steps. First, when compiling your keyboard, you'll need to set `OLED_DRIVER_ENABLE=yes` in `rules.mk`, e.g.:
+
+```
+OLED_DRIVER_ENABLE = yes
+```
+
+This enables the feature and the `OLED_DRIVER_ENABLE` define. Then in your `keymap.c` file, you will need to implement the user task call, e.g:
+
+```C++
+#ifdef OLED_DRIVER_ENABLE
+void oled_task_user(void) {
+  // Host Keyboard Layer Status
+  oled_write_P(PSTR("Layer: "), false);
+  switch (biton32(layer_state)) {
+    case _QWERTY:
+      oled_write_P(PSTR("Default\n"), false);
+      break;
+    case _FN:
+      oled_write_P(PSTR("FN\n"), false);
+      break;
+    case _ADJ:
+      oled_write_P(PSTR("ADJ\n"), false);
+      break;
+    default:
+      // Or use the write_ln shortcut over adding '\n' to the end of your string
+      oled_write_ln_P(PSTR("Undefined"), false);
+  }
+
+  // Host Keyboard LED Status
+  uint8_t led_usb_state = host_keyboard_leds();
+  oled_write_P(led_usb_state & (1<<USB_LED_NUM_LOCK) ? PSTR("NUMLCK ") : PSTR("       "), false);
+  oled_write_P(led_usb_state & (1<<USB_LED_CAPS_LOCK) ? PSTR("CAPLCK ") : PSTR("       "), false);
+  oled_write_P(led_usb_state & (1<<USB_LED_SCROLL_LOCK) ? PSTR("SCRLCK ") : PSTR("       "), false);
+}
+#endif
+```
+
+## Logo Example
+
+In the default font, ranges in the font file are reserved for a QMK Logo. To Render this logo to the oled screen, use the following code example:
+
+```C++
+static void render_logo(void) {
+  static const char PROGMEM qmk_logo[] = {
+    0x80,0x81,0x82,0x83,0x84,0x85,0x86,0x87,0x88,0x89,0x8a,0x8b,0x8c,0x8d,0x8e,0x8f,0x90,0x91,0x92,0x93,0x94,
+    0xa0,0xa1,0xa2,0xa3,0xa4,0xa5,0xa6,0xa7,0xa8,0xa9,0xaa,0xab,0xac,0xad,0xae,0xaf,0xb0,0xb1,0xb2,0xb3,0xb4,
+    0xc0,0xc1,0xc2,0xc3,0xc4,0xc5,0xc6,0xc7,0xc8,0xc9,0xca,0xcb,0xcc,0xcd,0xce,0xcf,0xd0,0xd1,0xd2,0xd3,0xd4,0};
+
+  oled_write_P(qmk_logo, false);
+}
+```
+
+## Other Examples
+
+In split keyboards, it is very common to have two OLED displays that each render different content and oriented flipped differently. You can do this by switching which content to render by using the return from `is_keyboard_master()` or `is_keyboard_left()` found in `split_util.h`, e.g:
+
+```C++
+#ifdef OLED_DRIVER_ENABLE
+oled_rotation_t oled_init_user(oled_rotation_t rotation) {
+  if (!is_keyboard_master())
+    return OLED_ROTATION_180;  // flips the display 180 degrees if offhand
+  return rotation;
+}
+
+void oled_task_user(void) {
+  if (is_keyboard_master()) {
+    render_status();     // Renders the current keyboard state (layer, lock, caps, scroll, etc)
+  } else {
+    render_logo();       // Renders a statuc logo
+    oled_scroll_left();  // Turns on scrolling
+  }
+}
+#endif
+```
+
+
+ ## Basic Configuration
+
+|Define                 |Default        |Description                                     |
+|-----------------------|---------------|------------------------------------------------|
+|`OLED_DISPLAY_ADDRESS` |`0x3C`         |The i2c address of the OLED Display             |
+|`OLED_FONT_H`          |`"glcdfont.c"` |The font code file to use for custom fonts      |
+|`OLED_FONT_START`      |`0`            |The starting characer index for custom fonts    |
+|`OLED_FONT_END`        |`224`          |The ending characer index for custom fonts      |
+|`OLED_FONT_WIDTH`      |`6`            |The font width                                  |
+|`OLED_FONT_HEIGHT`     |`8`            |The font height (untested)                      |
+|`OLED_DISABLE_TIMEOUT` |*Not defined*  |Disables the built in OLED timeout feature. Useful when implementing custom timeout rules.|
+
+
+
+ ## 128x64 & Custom sized OLED Displays
+
+ The default display size for this feature is 128x32 and all necessary defines are precalculated with that in mind. We have added a define, `OLED_DISPLAY_128X64`, to switch all the values to be used in a 128x64 display, as well as added a custom define, `OLED_DISPLAY_CUSTOM`, that allows you to provide the necessary values to the driver.
+
+|Define                 |Default        |Description                                                      |
+|-----------------------|---------------|-----------------------------------------------------------------|
+|`OLED_DISPLAY_128X64`  |*Not defined*  |Changes the display defines for use with 128x64 displays.        |
+|`OLED_DISPLAY_CUSTOM`  |*Not defined*  |Changes the display defines for use with custom displays.<br />Requires user to implement the below defines. |
+|`OLED_DISPLAY_WIDTH`   |`128`          |The width of the OLED display.                                   |
+|`OLED_DISPLAY_HEIGHT`  |`32`           |The height of the OLED display.                                  |
+|`OLED_MATRIX_SIZE`     |`512`          |The local buffer size to allocate.<br />`(OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH)`|
+|`OLED_BLOCK_TYPE`      |`uint16_t`     |The unsigned integer type to use for dirty rendering.|
+|`OLED_BLOCK_COUNT`     |`16`           |The number of blocks the display is divided into for dirty rendering.<br />`(sizeof(OLED_BLOCK_TYPE) * 8)`|
+|`OLED_BLOCK_SIZE`      |`32`           |The size of each block for dirty rendering<br />`(OLED_MATRIX_SIZE / OLED_BLOCK_COUNT)`|
+|`OLED_SOURCE_MAP`      |`{ 0, ... N }` |Precalculated source array to use for mapping source buffer to target OLED memory in 90 degree rendering.         |
+|`OLED_TARGET_MAP`      |`{ 24, ... N }`|Precalculated target array to use for mapping source buffer to target OLED memory in 90 degree rendering.         |
+
+
+### 90 Degree Rotation - Technical Mumbo Jumbo 
+
+```C
+// OLED Rotation enum values are flags
+typedef enum {
+    OLED_ROTATION_0   = 0,
+    OLED_ROTATION_90  = 1,
+    OLED_ROTATION_180 = 2,
+    OLED_ROTATION_270 = 3, // OLED_ROTATION_90 | OLED_ROTATION_180
+} oled_rotation_t;
+```
+
+ OLED displays driven by SSD1306 drivers only natively support in hard ware 0 degree and 180 degree rendering. This feature is done in software and not free. Using this feature will increase the time to calculate what data to send over i2c to the OLED. If you are strapped for cycles, this can cause keycodes to not register. In testing however, the rendering time on an `atmega32u4` board only went from 2ms to 5ms and keycodes not registering was only noticed once we hit 15ms. 
+ 
+ 90 Degree Rotated Rendering is achieved by using bitwise operations to rotate each 8 block of memory and uses two precalculated arrays to remap buffer memory to OLED memory. The memory map defines are precalculated for remap performance and are calculated based on the OLED Height, Width, and Block Size. For example, in the 128x32 implementation with a `uint8_t` block type, we have a 64 byte block size. This gives us eight 8 byte blocks that need to be rotated and rendered. The OLED renders horizontally two 8 byte blocks before moving down a page, e.g:
+
+|   |   |   |   |   |   |
+|---|---|---|---|---|---|
+| 0 | 1 |   |   |   |   |
+| 2 | 3 |   |   |   |   |
+| 4 | 5 |   |   |   |   |
+| 6 | 7 |   |   |   |   |
+
+However the local buffer is stored as if it was Height x Width display instead of Width x Height, e.g:
+
+|   |   |   |   |   |   |
+|---|---|---|---|---|---|
+| 3 | 7 |   |   |   |   |
+| 2 | 6 |   |   |   |   |
+| 1 | 5 |   |   |   |   |
+| 0 | 4 |   |   |   |   |
+
+So those precalculated arrays just index the memory offsets in the order in which each one iterates its data.
+
+## OLED API
+
+```C++
+// OLED Rotation enum values are flags
+typedef enum {
+    OLED_ROTATION_0   = 0,
+    OLED_ROTATION_90  = 1,
+    OLED_ROTATION_180 = 2,
+    OLED_ROTATION_270 = 3, // OLED_ROTATION_90 | OLED_ROTATION_180
+} oled_rotation_t;
+
+// Initialize the OLED display, rotating the rendered output based on the define passed in.
+// Returns true if the OLED was initialized successfully
+bool oled_init(oled_rotation_t rotation);
+
+// Called at the start of oled_init, weak function overridable by the user
+// rotation - the value passed into oled_init
+// Return new oled_rotation_t if you want to override default rotation
+oled_rotation_t oled_init_user(oled_rotation_t rotation);
+
+// Clears the display buffer, resets cursor position to 0, and sets the buffer to dirty for rendering
+void oled_clear(void);
+
+// Renders the dirty chunks of the buffer to OLED display
+void oled_render(void);
+
+// Moves cursor to character position indicated by column and line, wraps if out of bounds
+// Max column denoted by 'oled_max_chars()' and max lines by 'oled_max_lines()' functions
+void oled_set_cursor(uint8_t col, uint8_t line);
+
+// Advances the cursor to the next page, writing ' ' if true
+// Wraps to the begining when out of bounds
+void oled_advance_page(bool clearPageRemainder);
+
+// Moves the cursor forward 1 character length
+// Advance page if there is not enough room for the next character
+// Wraps to the begining when out of bounds
+void oled_advance_char(void);
+
+// Writes a single character to the buffer at current cursor position
+// Advances the cursor while writing, inverts the pixels if true
+// Main handler that writes character data to the display buffer
+void oled_write_char(const char data, bool invert);
+
+// Writes a string to the buffer at current cursor position
+// Advances the cursor while writing, inverts the pixels if true
+void oled_write(const char *data, bool invert);
+
+// Writes a string to the buffer at current cursor position
+// Advances the cursor while writing, inverts the pixels if true
+// Advances the cursor to the next page, wiring ' ' to the remainder of the current page
+void oled_write_ln(const char *data, bool invert);
+
+// Writes a PROGMEM string to the buffer at current cursor position
+// Advances the cursor while writing, inverts the pixels if true
+// Remapped to call 'void oled_write(const char *data, bool invert);' on ARM
+void oled_write_P(const char *data, bool invert);
+
+// Writes a PROGMEM string to the buffer at current cursor position
+// Advances the cursor while writing, inverts the pixels if true
+// Advances the cursor to the next page, wiring ' ' to the remainder of the current page
+// Remapped to call 'void oled_write_ln(const char *data, bool invert);' on ARM
+void oled_write_ln_P(const char *data, bool invert);
+
+// Can be used to manually turn on the screen if it is off
+// Returns true if the screen was on or turns on
+bool oled_on(void);
+
+// Can be used to manually turn off the screen if it is on
+// Returns true if the screen was off or turns off
+bool oled_off(void);
+
+// Basically it's oled_render, but with timeout management and oled_task_user calling!
+void oled_task(void);
+
+// Called at the start of oled_task, weak function overridable by the user
+void oled_task_user(void);
+
+// Scrolls the entire display right
+// Returns true if the screen was scrolling or starts scrolling
+// NOTE: display contents cannot be changed while scrolling
+bool oled_scroll_right(void);
+
+// Scrolls the entire display left
+// Returns true if the screen was scrolling or starts scrolling
+// NOTE: display contents cannot be changed while scrolling
+bool oled_scroll_left(void);
+
+// Turns off display scrolling
+// Returns true if the screen was not scrolling or stops scrolling
+bool oled_scroll_off(void);
+
+// Returns the maximum number of characters that will fit on a line
+uint8_t oled_max_chars(void);
+
+// Returns the maximum number of lines that will fit on the OLED
+uint8_t oled_max_lines(void);
+```
+
+## SSD1306.h driver conversion guide
+
+|Old API                    |Recommended New API                |
+|---------------------------|-----------------------------------|
+|`struct CharacterMatrix`   |*removed - delete all references*  |
+|`iota_gfx_init`            |`oled_init`                        |
+|`iota_gfx_on`              |`oled_on`                          |
+|`iota_gfx_off`             |`oled_off`                         |
+|`iota_gfx_flush`           |`oled_render`                      |
+|`iota_gfx_write_char`      |`oled_write_char`                  |
+|`iota_gfx_write`           |`oled_write`                       |
+|`iota_gfx_write_P`         |`oled_write_P`                     |
+|`iota_gfx_clear_screen`    |`oled_clear`                       |
+|`matrix_clear`             |*removed - delete all references*  |
+|`matrix_write_char_inner`  |`oled_write_char`                  |
+|`matrix_write_char`        |`oled_write_char`                  |
+|`matrix_write`             |`oled_write`                       |
+|`matrix_write_ln`          |`oled_write_ln`                    |
+|`matrix_write_P`           |`oled_write_P`                     |
+|`matrix_write_ln_P`        |`oled_write_ln_P`                  |
+|`matrix_render`            |`oled_render`                      |
+|`iota_gfx_task`            |`oled_task`                        |
+|`iota_gfx_task_user`       |`oled_task_user`                   |

docs/feature_rgblight.md

@@ -23,10 +23,11 @@ RGBLIGHT_ENABLE = yes
 
 At minimum you must define the data pin your LED strip is connected to, and the number of LEDs in the strip, in your `config.h`. If your keyboard has onboard RGB LEDs, and you are simply creating a keymap, you usually won't need to modify these.
 
-|Define      |Description                                  |
-|------------|---------------------------------------------|
-|`RGB_DI_PIN`|The pin connected to the data pin of the LEDs|
-|`RGBLED_NUM`|The number of LEDs connected                 |
+|Define         |Description                                                                                              |
+|---------------|---------------------------------------------------------------------------------------------------------|
+|`RGB_DI_PIN`   |The pin connected to the data pin of the LEDs                                                            |
+|`RGBLED_NUM`   |The number of LEDs connected                                                                             |
+|`RGBLED_SPLIT` |(Optional) For split keyboards, the number of LEDs connected on each half directly wired to `RGB_DI_PIN` |
 
 Then you should be able to use the keycodes below to change the RGB lighting to your liking.
 
@@ -74,6 +75,7 @@ Your RGB lighting can be configured by placing these `#define`s in your `config.
 |`RGBLIGHT_VAL_STEP`  |`17`         |The number of steps to increment the brightness by                           |
 |`RGBLIGHT_LIMIT_VAL` |`255`        |The maximum brightness level                                                 |
 |`RGBLIGHT_SLEEP`     |*Not defined*|If defined, the RGB lighting will be switched off when the host goes to sleep|
+|`RGBLIGHT_SPLIT`     |*Not defined*|If defined, synchronization functionality for split keyboards is added|
 
 ## Animations
 
@@ -112,7 +114,7 @@ The following options can be used to tweak the various animations:
 |`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_CENTER`    |*Not defined*|If defined, 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                             |
 |`RGBLIGHT_EFFECT_KNIGHT_LENGTH`     |`3`          |The number of LEDs to light up for the "Knight" animation                            |
@@ -124,6 +126,8 @@ The following options can be used to tweak the various animations:
 
 You can also modify the speeds that the different modes animate at:
 
+Here is a quick demo on Youtube (with NPKC KC60) (https://www.youtube.com/watch?v=VKrpPAHlisY).
+
 ```c
 // How long (in milliseconds) to wait between animation steps for each of the "Solid color breathing" animations
 const uint8_t RGBLED_BREATHING_INTERVALS[] PROGMEM = {30, 20, 10, 5};
@@ -141,7 +145,7 @@ const uint8_t RGBLED_SNAKE_INTERVALS[] PROGMEM = {100, 50, 20};
 const uint8_t RGBLED_KNIGHT_INTERVALS[] PROGMEM = {127, 63, 31};
 
 // These control which hues are selected for each of the "Static gradient" modes
-const uint16_t RGBLED_GRADIENT_RANGES[] PROGMEM = {360, 240, 180, 120, 90};
+const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64};
 ```
 
 ## Functions
@@ -185,9 +189,115 @@ If you need to change your RGB lighting in code, for example in a macro to chang
 |`rgblight_increase_val_noeeprom()`          |Increase the value for all LEDs. This wraps around at maximum value (not written to EEPROM)                                                                   |
 |`rgblight_decrease_val()`                   |Decrease the value for all LEDs. This wraps around at minimum value                                                                                           |
 |`rgblight_decrease_val_noeeprom()`          |Decrease the value for all LEDs. This wraps around at minimum value (not written to EEPROM)                                                                   |
+|`rgblight_set_clipping_range(pos, num)`     |Set clipping Range                                                                                                                                            |
 
-Additionally, [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h) defines several predefined shortcuts for various colors. Feel free to add to this list!
+## Colors
 
-## Hardware Modification
+These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions.
+
+|RGB                |HSV                |
+|-------------------|-------------------|
+|`RGB_WHITE`        |`HSV_WHITE`        |
+|`RGB_RED`          |`HSV_RED`          |
+|`RGB_CORAL`        |`HSV_CORAL`        |
+|`RGB_ORANGE`       |`HSV_ORANGE`       |
+|`RGB_GOLDENROD`    |`HSV_GOLDENROD`    |
+|`RGB_GOLD`         |`HSV_GOLD`         |
+|`RGB_YELLOW`       |`HSV_YELLOW`       |
+|`RGB_CHARTREUSE`   |`HSV_CHARTREUSE`   |
+|`RGB_GREEN`        |`HSV_GREEN`        |
+|`RGB_SPRINGGREEN`  |`HSV_SPRINGGREEN`  |
+|`RGB_TURQUOISE`    |`HSV_TURQUOISE`    |
+|`RGB_TEAL`         |`HSV_TEAL`         |
+|`RGB_CYAN`         |`HSV_CYAN`         |
+|`RGB_AZURE`        |`HSV_AZURE`        |
+|`RGB_BLUE`         |`HSV_BLUE`         |
+|`RGB_PURPLE`       |`HSV_PURPLE`       |
+|`RGB_MAGENTA`      |`HSV_MAGENTA`      |
+|`RGB_PINK`         |`HSV_PINK`         |
+
+```c
+rgblight_setrgb(RGB_ORANGE);
+rgblight_sethsv_noeeprom(HSV_GREEN);
+rgblight_setrgb_at(RGB_GOLD, 3);
+rgblight_sethsv_range(HSV_WHITE, 0, 6);
+```
+
+These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list!
+
+
+## Changing the order of the LEDs
+
+If you want to make the logical order of LEDs different from the electrical connection order, you can do this by defining the `RGBLIGHT_LED_MAP` macro in your `config.h`.
+
+Normally, the contents of the LED buffer are output to the LEDs in the same order.
+<img src="https://user-images.githubusercontent.com/2170248/55743718-01866c80-5a6e-11e9-8134-25419928327a.JPG" alt="simple dicrect" width="50%"/>
+
+By defining `RGBLIGHT_LED_MAP` as in the example below, you can specify the LED with addressing in reverse order of the electrical connection order.
+
+```c
+// config.h
+
+#define RGBLED_NUM 4
+#define RGBLIGHT_LED_MAP { 3, 2, 1, 0 }
+
+```
+<img src="https://user-images.githubusercontent.com/2170248/55743725-08ad7a80-5a6e-11e9-83ed-126a2b0209fc.JPG" alt="simple mapped" width="50%"/>
+
+For keyboards that use the RGB LEDs as a backlight for each key, you can also define it as in the example below.
+
+```c
+// config.h
+
+#define RGBLED_NUM 30
+
+/* RGB LED Conversion macro from physical array to electric array */
+#define LED_LAYOUT( \
+    L00, L01, L02, L03, L04, L05,  \
+    L10, L11, L12, L13, L14, L15,  \
+    L20, L21, L22, L23, L24, L25,  \
+    L30, L31, L32, L33, L34, L35,  \
+    L40, L41, L42, L43, L44, L45 ) \
+  { \
+    L05, L04, L03, L02, L01, L00,   \
+    L10, L11, L12, L13, L14, L15,   \
+    L25, L24, L23, L22, L21, L20,   \
+    L30, L31, L32, L33, L34, L35,   \
+    L46, L45, L44, L43, L42, L41    \
+  }
+
+/* RGB LED logical order map */
+/* Top->Bottom, Right->Left */
+#define RGBLIGHT_LED_MAP LED_LAYOUT( \
+  25, 20, 15, 10,  5,  0,       \
+  26, 21, 16, 11,  6,  1,       \
+  27, 22, 17, 12,  7,  2,       \
+  28, 23, 18, 13,  8,  3,       \
+  29, 24, 19, 14,  9,  4 )
+
+```
+## Clipping Range
+
+Using the `rgblight_set_clipping_range()` function, you can prepare more buffers than the actual number of LEDs, and output some of the buffers to the LEDs. This is useful if you want the split keyboard to treat left and right LEDs as logically contiguous.
+
+You can set the Clipping Range by executing the following code.
+
+```c
+// some soruce
+  rgblight_set_clipping_range(3, 4);
+```
+<img src="https://user-images.githubusercontent.com/2170248/55743785-2bd82a00-5a6e-11e9-9d4b-1b4ffaf4932b.JPG" alt="clip direct" width="70%"/>
+
+In addition to setting the Clipping Range, you can use `RGBLIGHT_LED_MAP` together.
+
+```c
+// config.h
+#define RGBLED_NUM 8
+#define RGBLIGHT_LED_MAP { 7, 6, 5, 4, 3, 2, 1, 0 }
+
+// some soruce
+  rgblight_set_clipping_range(3, 4);
+```
+<img src="https://user-images.githubusercontent.com/2170248/55743747-119e4c00-5a6e-11e9-91e5-013203ffae8a.JPG" alt="clip mapped" width="70%"/>
 
 If your keyboard lacks onboard underglow LEDs, you may often be able to solder on an RGB LED strip yourself. You will need to find an unused pin to wire to the data pin of your LED strip. Some keyboards may break out unused pins from the MCU to make soldering easier. The other two pins, VCC and GND, must also be connected to the appropriate power pins.

docs/feature_space_cadet.md

@@ -0,0 +1,59 @@
+# Space Cadet: The Future, Built In
+
+Steve Losh described the [Space Cadet Shift](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) quite well. Essentially, when you tap Left Shift on its own, you get an opening parenthesis; tap Right Shift on its own and you get the closing one. When held, the Shift keys function as normal. Yes, it's as cool as it sounds, and now even cooler supporting Control and Alt as well!
+
+## Usage
+
+Firstly, in your keymap, do one of the following:
+- Replace the Left Shift key with `KC_LSPO` (Left Shift, Parenthesis Open), and Right Shift with `KC_RSPC` (Right Shift, Parenthesis Close).
+- Replace the Left Control key with `KC_LCPO` (Left Control, Parenthesis Open), and Right Control with `KC_RCPC` (Right Control, Parenthesis Close).
+- Replace the Left Alt key with `KC_LAPO` (Left Alt, Parenthesis Open), and Right Alt with `KC_RAPC` (Right Alt, Parenthesis Close).
+- Replace any Shift key in your keymap with `KC_SFTENT` (Right Shift, Enter).
+
+## Keycodes
+
+|Keycode    |Description                                |
+|-----------|-------------------------------------------|
+|`KC_LSPO`  |Left Shift when held, `(` when tapped      |
+|`KC_RSPC`  |Right Shift when held, `)` when tapped     |
+|`KC_LCPO`  |Left Control when held, `(` when tapped    |
+|`KC_RCPC`  |Right Control when held, `)` when tapped   |
+|`KC_LAPO`  |Left Alt when held, `(` when tapped        |
+|`KC_RAPC`  |Right Alt when held, `)` when tapped       |
+|`KC_SFTENT`|Right Shift when held, `Enter` when tapped |
+
+## Caveats
+
+Space Cadet's functionality can conflict with the default Command functionality when both Shift keys are held at the same time. See the [Command feature](feature_command.md) for info on how to change it, or make sure that Command is disabled in your `rules.mk` with:
+
+```make
+COMMAND_ENABLE = no
+```
+
+## Configuration
+
+By default Space Cadet assumes a US ANSI layout, but if your layout uses different keys for parentheses, you can redefine them in your `config.h`. In addition, you can redefine the modifier to send on tap, or even send no modifier at all. The new configuration defines bundle all options up into a single define of 3 key codes in this order: the `Modifier` when held or when used with other keys, the `Tap Modifer` sent when tapped (no modifier if `KC_TRNS`), finally the `Keycode` sent when tapped. Now keep in mind, mods from other keys will still apply to the `Keycode` if say `KC_RSFT` is held while tapping `KC_LSPO` key with `KC_TRNS` as the `Tap Modifer`.
+
+|Define          |Default                        |Description                                                                      |
+|----------------|-------------------------------|---------------------------------------------------------------------------------|
+|`LSPO_KEYS`     |`KC_LSFT, LSPO_MOD, LSPO_KEY`  |Send `KC_LSFT` when held, the mod and  key defined by `LSPO_MOD` and `LSPO_KEY`. |
+|`RSPC_KEYS`     |`KC_RSFT, RSPC_MOD, RSPC_KEY`  |Send `KC_RSFT` when held, the mod and  key defined by `RSPC_MOD` and `RSPC_KEY`. |
+|`LCPO_KEYS`     |`KC_LCTL, KC_LCTL, KC_9`       |Send `KC_LCTL` when held, the mod `KC_LCTL` with the key `KC_9` when tapped.     |
+|`RCPC_KEYS`     |`KC_RCTL, KC_RCTL, KC_0`       |Send `KC_RCTL` when held, the mod `KC_RCTL` with the key `KC_0` when tapped.     |
+|`LAPO_KEYS`     |`KC_LALT, KC_LALT, KC_9`       |Send `KC_LALT` when held, the mod `KC_LALT` with the key `KC_9` when tapped.     |
+|`RAPC_KEYS`     |`KC_RALT, KC_RALT, KC_0`       |Send `KC_RALT` when held, the mod `KC_RALT` with the key `KC_0` when tapped.     |
+|`SFTENT_KEYS`   |`KC_RSFT, KC_TRNS, SFTENT_KEY` |Send `KC_RSFT` when held, no mod with the key `SFTENT_KEY` when tapped.          |
+
+
+## Obsolete Configuration
+
+These defines are used in the above defines internally to support backwards compatibility, so you may continue to use them, however the above defines open up a larger range of flexibility than before. As an example, say you want to not send any modifier when you tap just `KC_LSPO`, with the old defines you had an all or nothing choice of using the `DISABLE_SPACE_CADET_MODIFIER` define. Now you can define that key as: `#define LSPO_KEYS KC_LSFT, KC_TRNS, KC_9`. This tells the system to set Left Shift if held or used with other keys, then on tap send no modifier (transparent) with the `KC_9`.
+
+|Define                        |Default      |Description                                                       |
+|------------------------------|-------------|------------------------------------------------------------------|
+|`LSPO_KEY`                    |`KC_9`       |The keycode to send when Left Shift is tapped                     |
+|`RSPC_KEY`                    |`KC_0`       |The keycode to send when Right Shift is tapped                    |
+|`LSPO_MOD`                    |`KC_LSFT`    |The modifier to apply to `LSPO_KEY`                               |
+|`RSPC_MOD`                    |`KC_RSFT`    |The modifier to apply to `RSPC_KEY`                               |
+|`SFTENT_KEY`                  |`KC_ENT`     |The keycode to send when the Shift key is tapped                  |
+|`DISABLE_SPACE_CADET_MODIFIER`|*Not defined*|If defined, prevent the Space Cadet from applying a modifier      |

docs/feature_space_cadet_shift.md

@@ -1,37 +0,0 @@
-# Space Cadet Shift: The Future, Built In
-
-Steve Losh described the [Space Cadet Shift](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) quite well. Essentially, when you tap Left Shift on its own, you get an opening parenthesis; tap Right Shift on its own and you get the closing one. When held, the Shift keys function as normal. Yes, it's as cool as it sounds.
-
-## Usage
-
-Replace the Left Shift key in your keymap with `KC_LSPO` (Left Shift, Parenthesis Open), and Right Shift with `KC_RSPC` (Right Shift, Parenthesis Close).
-
-## Keycodes
-
-|Keycode  |Description                           |
-|---------|--------------------------------------|
-|`KC_LSPO`|Left Shift when held, `(` when tapped |
-|`KC_RSPC`|Right Shift when held, `)` when tapped|
-
-## Caveats
-
-Space Cadet's functionality can conflict with the default Command functionality when both Shift keys are held at the same time. Make sure that Command is disabled in your `rules.mk` with:
-
-```make
-COMMAND_ENABLE = no
-```
-
-## Configuration
-
-By default Space Cadet assumes a US ANSI layout, but if your layout uses different keys for parentheses, you can redefine them in your `config.h`.
-You can also disable the rollover, allowing you to use the opposite Shift key to cancel the Space Cadet state in the event of an erroneous press, instead of emitting a pair of parentheses when the keys are released.
-Also, by default, the Space Cadet applies modifiers LSPO_MOD and RSPC_MOD to keys defined by LSPO_KEY and RSPC_KEY. You can override this behavior by redefining those variables in your `config.h`. You can also prevent the Space Cadet to apply a modifier by defining DISABLE_SPACE_CADET_MODIFIER in your `config.h`.
-
-|Define                        |Default      |Description                                                                     |
-|------------------------------|-------------|--------------------------------------------------------------------------------|
-|`LSPO_KEY`                    |`KC_9`       |The keycode to send when Left Shift is tapped                                   |
-|`RSPC_KEY`                    |`KC_0`       |The keycode to send when Right Shift is tapped                                  |
-|`LSPO_MOD`                    |`KC_LSFT`    |The keycode to send when Left Shift is tapped                                   |
-|`RSPC_MOD`                    |`KC_RSFT`    |The keycode to send when Right Shift is tapped                                  |
-|`DISABLE_SPACE_CADET_ROLLOVER`|*Not defined*|If defined, use the opposite Shift key to cancel Space Cadet                    |
-|`DISABLE_SPACE_CADET_MODIFIER`|*Not defined*|If defined, prevent the Space Cadet to apply a modifier to LSPO_KEY and RSPC_KEY|

docs/feature_space_cadet_shift_enter.md

@@ -1,31 +0,0 @@
-# Space Cadet Shift Enter
-
-Based on the [Space Cadet Shift](feature_space_cadet_shift.md) feature. Tap the Shift key on its own, and it behaves like Enter. When held, the Shift functions as normal.
-
-## Usage
-
-Replace any Shift key in your keymap with `KC_SFTENT` (Shift, Enter), and you're done.
-
-## Keycodes
-
-|Keycode    |Description                             |
-|-----------|----------------------------------------|
-|`KC_SFTENT`|Right Shift when held, Enter when tapped|
-
-## Caveats
-
-As with Space Cadet Shift, this feature may conflict with Command, so it should be disabled in your `rules.mk` with:
-
-```make
-COMMAND_ENABLE = no
-```
-
-This feature also uses the same timers as Space Cadet Shift, so using them in tandem may produce strange results.
-
-## Configuration
-
-By default Space Cadet assumes a US ANSI layout, but if you'd like to use a different key for Enter, you can redefine it in your `config.h`:
-
-|Define      |Default |Description                                     |
-|------------|--------|------------------------------------------------|
-|`SFTENT_KEY`|`KC_ENT`|The keycode to send when the Shift key is tapped|

docs/feature_unicode.md

@@ -4,11 +4,11 @@ There are three Unicode keymap definition methods available in QMK:
 
 ## `UNICODE_ENABLE`
 
-Supports Unicode up to `0x7FFF`. This covers characters for most modern languages, as well as symbols, but it doesn't cover emoji. The keycode function is `UC(c)` in the keymap file, where _c_ is the code point's number (preferably hexadecimal, up to 4 digits long). For example: `UC(0x45B)`, `UC(0x30C4)`.
+Supports Unicode up to `0x7FFF`. This covers characters for most modern languages, as well as symbols, but it doesn't cover emoji. The keycode function is `UC(c)` in the keymap, where _c_ is the code point's number (preferably hexadecimal, up to 4 digits long). For example: `UC(0x45B)`, `UC(0x30C4)`.
 
 ## `UNICODEMAP_ENABLE`
 
-Supports Unicode up to `0x10FFFF` (all possible code points). You need to maintain a separate mapping table `const uint32_t PROGMEM unicode_map[] = {...}` in your keymap file. The keycode function is `X(i)`, where _i_ is an array index into the mapping table. The table may contain at most 1024 entries.
+Supports Unicode up to `0x10FFFF` (all possible code points). You need to maintain a separate mapping table `const uint32_t PROGMEM unicode_map[] = {...}` in your keymap file. The keycode function is `X(i)`, where _i_ is an array index into the mapping table. The table may contain at most 16384 entries.
 
 You may want to have an enum to make referencing easier. So, you could add something like this to your keymap file:
 
@@ -26,13 +26,21 @@ const uint32_t PROGMEM unicode_map[] = {
 };
 ```
 
-Then you can use `X(BANG)` etc. in your keymap.
+Then you can use `X(BANG)`, `X(SNEK)` etc. in your keymap.
+
+### Lower and Upper Case
+
+Characters often come in lower and upper case pairs, for example: å, Å. To make inputting these characters easier, you can use `XP(i, j)` in your keymap, where _i_ and _j_ are the mapping table indices of the lower and upper case character, respectively. If you're holding down Shift or have Caps Lock turned on when you press the key, the second (upper case) character will be inserted; otherwise, the first (lower case) version will appear.
+
+This is most useful when creating a keymap for an international layout with special characters. Instead of having to put the lower and upper case versions of a character on separate keys, you can have them both on the same key by using `XP`. This blends Unicode keys in with regular alphas.
+
+Due to keycode size constraints, _i_ and _j_ can each only refer to one of the first 128 characters in your `unicode_map`. In other words, 0 ≤ _i_ ≤ 127 and 0 ≤ _j_ ≤ 127. This is enough for most use cases, but if you'd like to customize the index calculation, you can override the [`unicodemap_index()`](https://github.com/qmk/qmk_firmware/blob/71f640d47ee12c862c798e1f56392853c7b1c1a8/quantum/process_keycode/process_unicodemap.c#L40) function. This also allows you to, say, check Ctrl instead of Shift/Caps.
 
 ## `UCIS_ENABLE`
 
-Supports Unicode up to `0x10FFFF` (all possible code points). As with `UNICODEMAP`, you need to maintain a mapping table in your keymap file. However, there are no built-in keycodes for this feature — you will have to add a keycode or function that calls `qk_ucis_start()`. Once this function's been called, you can type the corresponding mnemonic for your character, then hit Space or Enter to complete it, or Esc to cancel. If the mnemonic matches an entry in your table, the typed text will automatically be erased and the corresponding Unicode character inserted.
+Supports Unicode up to `0x10FFFF` (all possible code points). As with `UNICODEMAP`, you need to maintain a mapping table in your keymap file. However, there are no built-in keycodes for this feature — you have to add a keycode or function that calls `qk_ucis_start()`. Once this function has been called, you can type the corresponding mnemonic for your character, then hit Space or Enter to complete it, or Esc to cancel. If the mnemonic matches an entry in your table, the typed text will automatically be erased and the corresponding Unicode character inserted.
 
-For instance, you would define a table like this in your keymap file:
+For instance, you could define a table like this in your keymap file:
 
 ```c
 const qk_ucis_symbol_t ucis_symbol_table[] = UCIS_TABLE(
@@ -42,7 +50,7 @@ const qk_ucis_symbol_t ucis_symbol_table[] = UCIS_TABLE(
 );
 ```
 
-You call `qk_ucis_start()`, then type "rofl" and hit Enter. QMK should erase the "rofl" text and input the laughing emoji.
+To use it, call `qk_ucis_start()`, then type "rofl" and hit Enter. QMK should erase the "rofl" text and insert the laughing emoji.
 
 ### Customization
 
@@ -60,28 +68,29 @@ Unicode input in QMK works by inputting a sequence of characters to the OS, sort
 
 The following input modes are available:
 
-* **`UC_OSX`**: Mac OS X built-in Unicode hex input. Supports code points up to `0xFFFF` (`0x10FFFF` with `UNICODEMAP`).
+* **`UC_OSX`**: macOS built-in Unicode hex input. Supports code points up to `0xFFFF` (`0x10FFFF` with `UNICODEMAP`).
 
   To enable, go to _System Preferences > Keyboard > Input Sources_, add _Unicode Hex Input_ to the list (it's under _Other_), then activate it from the input dropdown in the Menu Bar.
-  By default, this mode uses the left Option key (`KC_LALT`), but this can be changed by defining [`UNICODE_OSX_KEY`](#input-key-configuration) with another keycode.
+  By default, this mode uses the left Option key (`KC_LALT`) for Unicode input, but this can be changed by defining [`UNICODE_KEY_OSX`](#input-key-configuration) with another keycode.
 
-  **Note:** Using the _Unicode Hex Input_ input source may disable some Option based shortcuts, such as: Option + Left Arrow (`moveWordLeftAndModifySelection`) and Option + Right Arrow  (`moveWordRightAndModifySelection`).
+  !> Using the _Unicode Hex Input_ input source may disable some Option based shortcuts, such as Option + Left Arrow and Option + Right Arrow.
 
 * **`UC_LNX`**: Linux built-in IBus Unicode input. Supports code points up to `0x10FFFF` (all possible code points).
 
   Enabled by default and works almost anywhere on IBus-enabled distros. Without IBus, this mode works under GTK apps, but rarely anywhere else.
+  By default, this mode uses Ctrl+Shift+U (`LCTL(LSFT(KC_U))`) to start Unicode input, but this can be changed by defining [`UNICODE_KEY_LNX`](#input-key-configuration) with another keycode. This might be required for IBus versions ≥1.5.15, where Ctrl+Shift+U behavior is consolidated into Ctrl+Shift+E.
 
 * **`UC_WIN`**: _(not recommended)_ Windows built-in hex numpad Unicode input. Supports code points up to `0xFFFF`.
 
-  To enable, create a registry key under `HKEY_CURRENT_USER\Control Panel\Input Method\EnableHexNumpad` of type `REG_SZ` called `EnableHexNumpad` and set its value to `1`. This can be done from the Command Prompt by running `reg add "HKCU\Control Panel\Input Method" -v EnableHexNumpad -t REG_SZ -d 1` with administrator privileges. Afterwards, reboot.
+  To enable, create a registry key under `HKEY_CURRENT_USER\Control Panel\Input Method\EnableHexNumpad` of type `REG_SZ` called `EnableHexNumpad` and set its value to `1`. This can be done from the Command Prompt by running `reg add "HKCU\Control Panel\Input Method" -v EnableHexNumpad -t REG_SZ -d 1` with administrator privileges. Reboot afterwards.
   This mode is not recommended because of reliability and compatibility issues; use the `UC_WINC` mode instead.
 
 * **`UC_BSD`**: _(non implemented)_ Unicode input under BSD. Not implemented at this time. If you're a BSD user and want to help add support for it, please [open an issue on GitHub](https://github.com/qmk/qmk_firmware/issues).
 
-* **`UC_WINC`**: Windows Unicode input using [WinCompose](https://github.com/samhocevar/wincompose). As of v0.8.2, supports code points up to `0xFFFFF` (all currently assigned code points).
+* **`UC_WINC`**: Windows Unicode input using [WinCompose](https://github.com/samhocevar/wincompose). As of v0.9.0, supports code points up to `0x10FFFF` (all possible code points).
 
   To enable, install the [latest release](https://github.com/samhocevar/wincompose/releases/latest). Once installed, WinCompose will automatically run on startup. Works reliably under all version of Windows supported by the app.
-  By default, this mode uses the right Alt key (`KC_RALT`), but this can be changed in the WinCompose settings and by defining [`UNICODE_WINC_KEY`](#input-key-configuration) with another keycode.
+  By default, this mode uses right Alt (`KC_RALT`) as the Compose key, but this can be changed in the WinCompose settings and by defining [`UNICODE_KEY_WINC`](#input-key-configuration) with another keycode.
 
 ### Switching Input Modes
 
@@ -89,17 +98,17 @@ There are two ways to set the input mode for Unicode: by keycode or by function.
 
 You can switch the input mode at any time by using one of the following keycodes. The easiest way is to add the ones you use to your keymap.
 
-|Keycode                |Alias    |Input mode   |Description                              |
-|-----------------------|---------|-------------|-----------------------------------------|
-|`UNICODE_MODE_FORWARD` |`UC_MOD` |             |Cycles forwards through the available modes. [(Disabled by default)](#input-method-cycling)|
-|`UNICODE_MODE_REVERSE` |`UC_RMOD`|             |Cycles forwards through the available modes. [(Disabled by default)](#input-method-cycling)|
-|`UNICODE_MODE_OSX`     |`UC_M_OS`|`UC_OSX`     |Switch to Mac OS X input.                |
-|`UNICODE_MODE_LNX`     |`UC_M_LN`|`UC_LNX`     |Switch to Linux input.                   |
-|`UNICODE_MODE_WIN`     |`UC_M_WI`|`UC_WIN`     |Switch to Windows input.                 |
-|`UNICODE_MODE_BSD`     |`UC_M_BS`|`UC_BSD`     |Switch to BSD input (not implemented).   |
-|`UNICODE_MODE_WINC`    |`UC_M_WC`|`UC_WINC`    |Switch to Windows input using WinCompose.|
+|Keycode               |Alias    |Input Mode  |Description                                                   |
+|----------------------|---------|------------|--------------------------------------------------------------|
+|`UNICODE_MODE_FORWARD`|`UC_MOD` |Next in list|[Cycle](#input-mode-cycling) through selected modes           |
+|`UNICODE_MODE_REVERSE`|`UC_RMOD`|Prev in list|[Cycle](#input-mode-cycling) through selected modes in reverse|
+|`UNICODE_MODE_OSX`    |`UC_M_OS`|`UC_OSX`    |Switch to macOS input                                         |
+|`UNICODE_MODE_LNX`    |`UC_M_LN`|`UC_LNX`    |Switch to Linux input                                         |
+|`UNICODE_MODE_WIN`    |`UC_M_WI`|`UC_WIN`    |Switch to Windows input                                       |
+|`UNICODE_MODE_BSD`    |`UC_M_BS`|`UC_BSD`    |Switch to BSD input (not implemented)                         |
+|`UNICODE_MODE_WINC`   |`UC_M_WC`|`UC_WINC`   |Switch to Windows input using WinCompose                      |
 
-You can also switch the input mode by calling `set_unicode_input_mode(x)` in your code, where _x_ is one of the above input mode constants (e.g. `UC_LNX`). Since the function only needs to be called once, it's recommended that you do it in `eeconfig_init_user` (or a similar function). For example:
+You can also switch the input mode by calling `set_unicode_input_mode(x)` in your code, where _x_ is one of the above input mode constants (e.g. `UC_LNX`). Since the function only needs to be called once, it's recommended that you do it in `eeconfig_init_user()` (or a similar function). For example:
 
 ```c
 void eeconfig_init_user(void) {
@@ -123,35 +132,45 @@ For instance, you can add these definitions to your `config.h` file:
 
 ### Additional Customization
 
-Because Unicode is such a large and variable feature, there are a number of options that you can customize to work better on your system.
+Because Unicode is a large and versatile feature, there are a number of options you can customize to make it work better on your system.
 
-#### Start and Finish input functions
+#### Start and Finish Input Functions
 
 The functions for starting and finishing Unicode input on your platform can be overridden locally. Possible uses include customizing input mode behavior if you don't use the default keys, or adding extra visual/audio feedback to Unicode input.
 
-* `void unicode_input_start(void)` – This sends the initial sequence that tells your platform to enter Unicode input mode. For example, it presses Ctrl+Shift+U on Linux and holds the Option key on Mac.
+* `void unicode_input_start(void)` – This sends the initial sequence that tells your platform to enter Unicode input mode. For example, it presses Ctrl+Shift+U on Linux and holds the Option key on macOS.
 * `void unicode_input_finish(void)` – This is called to exit Unicode input mode, for example by pressing Space or releasing the Option key.
 
 You can find the default implementations of these functions in [`process_unicode_common.c`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_unicode_common.c).
 
-
 #### Input Key Configuration
 
-Additionally, you can customize the keys used to trigger the unicode input for macOS and WinCompose by adding defines to your `config.h`
+You can customize the keys used to trigger Unicode input for macOS, Linux and WinCompose by adding corresponding defines to your `config.h`. The default values match the platforms' default settings, so you shouldn't need to change this unless Unicode input isn't working, or you want to use a different key (e.g. in order to free up left or right Alt).
+
+|Define            |Type      |Default           |Example                                    |
+|------------------|----------|------------------|-------------------------------------------|
+|`UNICODE_KEY_OSX` |`uint8_t` |`KC_LALT`         |`#define UNICODE_KEY_OSX  KC_RALT`         |
+|`UNICODE_KEY_LNX` |`uint16_t`|`LCTL(LSFT(KC_U))`|`#define UNICODE_KEY_LNX  LCTL(LSFT(KC_E))`|
+|`UNICODE_KEY_WINC`|`uint8_t` |`KC_RALT`         |`#define UNICODE_KEY_WINC KC_RGUI`         |
+
+#### Input Mode Cycling
+
+You can choose which input modes are available for cycling through. By default, this is disabled. If you want to enable it, limiting it to just the modes you use makes sense. Note that the values in the list are comma-delimited.
 
 ```c
-#define UNICODE_OSX_KEY  KC_LALT
-#define UNICODE_WINC_KEY KC_RALT
+#define UNICODE_SELECTED_MODES UC_OSX, UC_LNX, UC_WIN, UC_WINC
 ```
 
-#### Input Method Cycling
+You can cycle through the selected modes by using the `UC_MOD`/`UC_RMOD` keycodes, or by calling `cycle_unicode_input_mode(offset)` in your code (`offset` is how many modes to move forward by, so +1 corresponds to `UC_MOD`).
 
-Also, you can choose which input methods are availble for cycling through.  By default, this is disabled. But if you want to enabled it, then limiting it to just those modes makes sense.  Note that `UNICODE_SELECTED_MODES` define is comma delimited.
+By default, when the keyboard boots, it will initialize the input mode to the last one you used. You can disable this and make it start with the first mode in the list every time by adding the following to your `config.h`:
 
 ```c
-#define UNICODE_SELECTED_MODES UC_OSX, UC_LNX, UC_WIN, UC_BSD, UC_WINC
+#define UNICODE_CYCLE_PERSIST false
 ```
 
+!> Using `UNICODE_SELECTED_MODES` means you don't have to initially set the input mode in `matrix_init_user()` (or a similar function); the Unicode system will do that for you on startup. This has the added benefit of avoiding unnecessary writes to EEPROM.
+
 ## `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.

docs/flashing.md

@@ -49,9 +49,18 @@ To generate this bootloader, use the `bootloader` target, eg `make planck/rev4:d
 
 To generate a production-ready .hex file (containing the application and the bootloader), use the `production` target, eg `make planck/rev4:default:production`.
 
+### DFU commands
+
+There are a number of DFU commands that you can use to flash firmware to a DFU device:
+
+* `:dfu` - This is the normal option and waits until a DFU device is available, and then flashes the firmware. This will check every 5 seconds, to see if a DFU device has appeared.
+* `:dfu-ee` - This flashes an `eep` file instead of the normal hex.  This is uncommon. 
+* `:dfu-split-left` - This flashes the normal firmware, just like the default option (`:dfu`). However, this also flashes the "Left Side" EEPROM file for split keyboards. _This is ideal for Elite C based split keyboards._
+* `:dfu-split-right` - This flashes the normal firmware, just like the default option (`:dfu`). However, this also flashes the "Right Side" EEPROM file for split keyboards. _This is ideal for Elite C based split keyboards._
+
 ## Caterina
 
-Arduino boards and their clones use the [Caterina bootloader](https://github.com/arduino/Arduino/tree/master/hardware/arduino/avr/bootloaders/caterina) (any keyboard built with a Pro Micro, or clone), and uses the avr109 protocol to communicate through virtual serial. Bootloaders like [A-Star](https://www.pololu.com/docs/0J61/9) are based on Caterina.
+Arduino boards and their clones use the [Caterina bootloader](https://github.com/arduino/ArduinoCore-avr/tree/master/bootloaders/caterina) (any keyboard built with a Pro Micro, or clone), and uses the avr109 protocol to communicate through virtual serial. Bootloaders like [A-Star](https://www.pololu.com/docs/0J61/9) are based on Caterina.
 
 To ensure compatibility with the Caterina bootloader, make sure this block is present your `rules.mk`:
 
@@ -84,6 +93,7 @@ or if you want to flash multiple boards, use the following command
 
 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).
@@ -131,3 +141,12 @@ Flashing sequence:
     * 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
+
+### STM32 Commands
+
+There are a number of DFU commands that you can use to flash firmware to a STM32 device:
+
+* `:dfu-util` - The default command for flashing to STM32 devices. 
+* `:dfu-util-wait` - This works like the default command, but it gives you a (configurable) 10 second timeout before it attempts to flash the firmware.  You can use `TIME_DELAY=20` from the command line to change the timeout.
+   * Eg: `make <keyboard>:<keymap>:dfu-util TIME_DELAY=5`
+* `:st-link-cli` - This allows you to flash the firmware via ST-LINK's CLI utility, rather than dfu-util. 

docs/getting_started_build_tools.md

@@ -4,7 +4,9 @@ This page describes setting up the build environment for QMK. These instructions
 
 <!-- FIXME: We should have ARM instructions somewhere. -->
 
-Note: If it is your first time here, Check out the "Complete Newbs guide" instead
+**Note:** If this is your first time here, check out the [Complete Newbs Guide](newbs.md) page.
+
+Before continuing, double check that your submodules (third-party libraries) are up to date by running `make git-submodule`.
 
 ## Linux