Add support for using ranges for RGB (#4981)

* Add support for using ranges for RGB

This patch adds support for controlling continuous ranges of RGB LEDs.
Helper functions for split boards are also available.

* RGB Range: Use hardware-platform agnostic wait

.github/ISSUE_TEMPLATE/blank.md

@@ -0,0 +1,5 @@
+---
+name: Blank issue
+about: If you're 100% sure that you don't need one of the other issue templates, use this one instead. 
+
+---

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Create a report to help us improve the QMK Firmware
+---
+<!-- Provide a general summary of the bug in the title above. -->
+
+<!--- This template is entirely optional and can be removed, but is here to help both you and us. -->
+<!--- Anything on lines wrapped in comments like these will not show up in the final text. -->
+
+## Describe the Bug
+
+<!-- A clear and concise description of what the bug is. -->
+
+## System Information
+
+ - Keyboard:  
+   - Revision (if applicable):  
+ - Operating system:
+ - AVR GCC version: 
+<!-- Run `avr-gcc --version` to find this out. -->
+ - ARM GCC version: 
+<!-- Run `arm-none-eabi-gcc --version` to find this out. -->
+ - QMK Firmware version:
+<!-- Run `git describe --abbrev=0 --tags` to find this out. -->
+ - Any keyboard related software installed? 
+   - [ ] AutoHotKey
+   - [ ] Karabiner
+   - [ ] Other:
+
+## Additional Context
+
+<!-- Add any other relevant information about the problem here. -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest a new feature or changes to existing features 
+---
+<!--- Provide a general summary of the changes you want in the title above. -->
+
+<!--- This template is entirely optional and can be removed, but is here to help both you and us. -->
+<!--- Anything on lines wrapped in comments like these will not show up in the final text. -->
+
+## Feature Request Type
+
+- [ ] Core functionality
+- [ ] Add-on hardware support (eg. audio, RGB, OLED screen, etc.)
+- [ ] Alteration (enhancement/optimization) of existing feature(s)
+- [ ] New behavior
+
+## Description
+
+<!-- A few sentences describing what it is that you'd like to see in QMK. Additional information (such as links to spec sheets, licensing info, other related issues or PRs, etc) would be helpful. -->

.github/ISSUE_TEMPLATE/other_issues.md

@@ -0,0 +1,9 @@
+---
+name: Other issues
+about: Anything else that doesn't fall into the above categories. 
+---
+<!--- Provide a general summary of the changes you want in the title above. -->
+
+<!--- Anything on lines wrapped in comments like these will not show up in the final text. -->
+
+<!-- Please check https://docs.qmk.fm/#/support for additional resources first. If that doesn't answer your question, choose the bug report template instead, as that may be more appropriate. -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,34 @@
+<!--- Provide a general summary of your changes in the title above. -->
+
+<!--- This template is entirely optional and can be removed, but is here to help both you and us. -->
+<!--- Anything on lines wrapped in comments like these will not show up in the final text. -->
+
+## Description
+
+<!--- Describe your changes in detail here. -->
+
+## Types of Changes
+
+<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply. -->
+- [ ] Core
+- [ ] Bugfix
+- [ ] New feature
+- [ ] Enhancement/optimization
+- [ ] Keyboard (addition or update)
+- [ ] Keymap/layout/userspace (addition or update)
+- [ ] Documentation
+
+## Issues Fixed or Closed by This PR
+
+* 
+
+## Checklist
+
+<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
+<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
+- [ ] My code follows the code style of this project.
+- [ ] My change requires a change to the documentation.
+- [ ] I have updated the documentation accordingly.
+- [ ] I have read the [**CONTRIBUTING** document](https://docs.qmk.fm/#/contributing).
+- [ ] I have added tests to cover my changes.
+- [ ] I have tested the changes and verified that they work and don't break anything (as well as I can manage).

.gitignore

@@ -1,3 +1,4 @@
+.history/
 .dep
 *.o
 *.bin

.travis.yml

@@ -19,7 +19,8 @@ install:
 before_script:
   - avr-gcc --version
 script:
-- make test:all AUTOGEN=false
+- git rev-parse --short HEAD
+- make test:all
 - bash util/travis_build.sh
 - bash util/travis_docs.sh
 addons:
@@ -33,7 +34,7 @@ addons:
     - diffutils
     - dos2unix
     - doxygen
-after_success: 
+after_success:
   bash util/travis_compiled_push.sh
 notifications:
   webhooks:

Dockerfile

@@ -1,28 +1,29 @@
-FROM debian:jessie
-MAINTAINER Erik Dasque <erik@frenchguys.com>
+FROM debian
 
-RUN apt-get update && apt-get install --no-install-recommends -y build-essential \
+RUN apt-get update && apt-get install --no-install-recommends -y \
+    avr-libc \
+    avrdude \
+    binutils-arm-none-eabi \
+    binutils-avr \
+    build-essential \
+    dfu-programmer \
+    dfu-util \
     gcc \
+    gcc-arm-none-eabi \
+    gcc-avr \
+    git \
+    libnewlib-arm-none-eabi \
+    software-properties-common \
     unzip \
     wget \
     zip \
-    gcc-avr \
-    binutils-avr \
-    avr-libc \
-    dfu-programmer \
-    dfu-util \
-    gcc-arm-none-eabi \
-    binutils-arm-none-eabi \
-    libnewlib-arm-none-eabi \
-    git \
-    software-properties-common \
-    avrdude \
     && rm -rf /var/lib/apt/lists/*
 
-ENV keyboard=ergodox
-ENV subproject=ez
-ENV keymap=default
+ENV KEYBOARD=ergodox_ez
+ENV KEYMAP=default
 
-VOLUME /qmk
-WORKDIR /qmk
-CMD make clean ; make keyboard=${keyboard} subproject=${subproject} keymap=${keymap}
+VOLUME /qmk_firmware
+WORKDIR /qmk_firmware
+COPY . .
+
+CMD make $KEYBOARD:$KEYMAP

Makefile

@@ -112,23 +112,29 @@ $(eval $(call GET_KEYBOARDS))
 # Only consider folders with makefiles, to prevent errors in case there are extra folders
 #KEYBOARDS += $(patsubst $(ROOD_DIR)/keyboards/%/rules.mk,%,$(wildcard $(ROOT_DIR)/keyboards/*/*/rules.mk))
 
+.PHONY: list-keyboards
 list-keyboards:
 	echo $(KEYBOARDS)
-	exit 0
 
 define PRINT_KEYBOARD
 	$(info $(PRINTING_KEYBOARD))
 endef
 
+.PHONY: generate-keyboards-file
 generate-keyboards-file:
 	$(foreach PRINTING_KEYBOARD,$(KEYBOARDS),$(eval $(call PRINT_KEYBOARD)))
-	exit 0
 
+.PHONY: clean
 clean:
-	echo -n 'Deleting .build ... '
+	echo -n 'Deleting .build/ ... '
 	rm -rf $(BUILD_DIR)
-	echo 'done'
-	exit 0
+	echo 'done.'
+
+.PHONY: distclean
+distclean: clean
+	echo -n 'Deleting *.bin and *.hex ... '
+	rm -f *.bin *.hex
+	echo 'done.'
 
 #Compatibility with the old make variables, anything you specify directly on the command line
 # always overrides the detected folders
@@ -548,9 +554,10 @@ endif
 	# it has to be there to allow parallel execution of the submake
 	# This always tries to compile everything, even if error occurs in the middle
 	# But we return the error code at the end, to trigger travis failures
-	$(foreach COMMAND,$(COMMANDS),$(RUN_COMMAND))
+	# The sort at this point is to remove duplicates
+	$(foreach COMMAND,$(sort $(COMMANDS)),$(RUN_COMMAND))
 	if [ -f $(ERROR_FILE) ]; then printf "$(MSG_ERRORS)" & exit 1; fi;
-	$(foreach TEST,$(TESTS),$(RUN_TEST))
+	$(foreach TEST,$(sort $(TESTS)),$(RUN_TEST))
 	if [ -f $(ERROR_FILE) ]; then printf "$(MSG_ERRORS)" & exit 1; fi;
 
 # These no longer work because of the colon system
@@ -576,6 +583,7 @@ lib/%:
 	git submodule sync $?
 	git submodule update --init $?
 
+.PHONY: git-submodule
 git-submodule:
 	git submodule sync --recursive
 	git submodule update --init --recursive --progress

Vagrantfile

@@ -2,8 +2,11 @@
 # vi: set ft=ruby :
 
 Vagrant.configure(2) do |config|
-  # VMware/Virtualbox 64 bit
-  config.vm.box = "phusion/ubuntu-14.04-amd64"
+  # define a name instead of just 'default'
+  config.vm.define "qmk_firmware"
+
+  # VMware/Virtualbox ( and also Hyperv/Parallels) 64 bit
+  config.vm.box = "bento/ubuntu-16.04"
 
   # This section allows you to customize the Virtualbox VM
   # settings, ie showing the GUI or upping the memory
@@ -15,13 +18,16 @@ Vagrant.configure(2) do |config|
     # your Teensy via the VM rather than your host OS
     #vb.customize ['modifyvm', :id, '--usb', 'on']
     #vb.customize ['usbfilter', 'add', '0',
-    #    	  '--target', :id,
-    #    	  '--name', 'teensy',
-    #    	  '--vendorid', '0x16c0',
-    #    	  '--productid','0x0478'
-    #		 ]
+    #         '--target', :id,
+    #         '--name', 'teensy',
+    #         '--vendorid', '0x16c0',
+    #         '--productid','0x0478'
+    #        ]
     # Customize the amount of memory on the VM:
     vb.memory = "512"
+    # Uncomment the below lines if you have time sync
+    # issues with make and incremental builds
+    #vb.customize [ "guestproperty", "set", :id, "/VirtualBox/GuestAdd/VBoxService/--timesync-set-threshold", 1000 ]
   end
 
   # This section allows you to customize the VMware VM
@@ -56,19 +62,18 @@ Vagrant.configure(2) do |config|
   # This script ensures the required packages for AVR programming are installed
   # It also ensures the system always gets the latest updates when powered on
   # If this causes issues you can run a 'vagrant destroy' and then
-  # add a # before ,args: and run 'vagrant up' to get a working
+  # add a # before ,run: (or change "always" to "once") and run 'vagrant up' to get a working
   # non-updated box and then attempt to troubleshoot or open a Github issue
-
-  config.vm.provision "shell", run: "always", path: "./util/qmk_install.sh", args: "-update"
+  config.vm.provision "shell", inline: "/bin/sh -c 'yes | /vagrant/util/qmk_install.sh'", run: "always"
 
   config.vm.post_up_message = <<-EOT
 
   Log into the VM using 'vagrant ssh'. QMK directory synchronized with host is
   located at /vagrant
-  To compile the .hex files use make command inside this directory.
+  To compile the .hex files use make command inside this directory, e.g.
+     cd /vagrant
+     make <keyboard>:default
 
-  QMK's make format recently changed to use folder locations and colons:
-     make project_folder:keymap[:target]
   Examples:
      make planck/rev4:default:dfu
      make planck:default

build_keyboard.mk

@@ -16,6 +16,7 @@ include common.mk
 KEYBOARD_FILESAFE := $(subst /,_,$(KEYBOARD))
 TARGET ?= $(KEYBOARD_FILESAFE)_$(KEYMAP)
 KEYBOARD_OUTPUT := $(BUILD_DIR)/obj_$(KEYBOARD_FILESAFE)
+STM32_PATH := quantum/stm32
 
 # Force expansion
 TARGET := $(TARGET)
@@ -34,6 +35,10 @@ $(error MASTER does not have a valid value(left/right))
     endif
 endif
 
+ifdef SKIP_VERSION
+    OPT_DEFS += -DSKIP_VERSION
+endif
+
 # Determine which subfolders exist.
 KEYBOARD_FOLDER_PATH_1 := $(KEYBOARD)
 KEYBOARD_FOLDER_PATH_2 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_1)))
@@ -68,6 +73,7 @@ ifneq ("$(wildcard $(KEYBOARD_PATH_1)/)","")
     KEYBOARD_PATHS += $(KEYBOARD_PATH_1)
 endif
 
+
 # Pull in rules.mk files from all our subfolders
 ifneq ("$(wildcard $(KEYBOARD_PATH_5)/rules.mk)","")
     include $(KEYBOARD_PATH_5)/rules.mk
@@ -85,6 +91,62 @@ ifneq ("$(wildcard $(KEYBOARD_PATH_1)/rules.mk)","")
     include $(KEYBOARD_PATH_1)/rules.mk
 endif
 
+
+MAIN_KEYMAP_PATH_1 := $(KEYBOARD_PATH_1)/keymaps/$(KEYMAP)
+MAIN_KEYMAP_PATH_2 := $(KEYBOARD_PATH_2)/keymaps/$(KEYMAP)
+MAIN_KEYMAP_PATH_3 := $(KEYBOARD_PATH_3)/keymaps/$(KEYMAP)
+MAIN_KEYMAP_PATH_4 := $(KEYBOARD_PATH_4)/keymaps/$(KEYMAP)
+MAIN_KEYMAP_PATH_5 := $(KEYBOARD_PATH_5)/keymaps/$(KEYMAP)
+
+ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_5)/keymap.c)","")
+    -include $(MAIN_KEYMAP_PATH_5)/rules.mk
+    KEYMAP_C := $(MAIN_KEYMAP_PATH_5)/keymap.c
+    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_5)
+else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_4)/keymap.c)","")
+    -include $(MAIN_KEYMAP_PATH_4)/rules.mk
+    KEYMAP_C := $(MAIN_KEYMAP_PATH_4)/keymap.c
+    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_4)
+else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_3)/keymap.c)","")
+    -include $(MAIN_KEYMAP_PATH_3)/rules.mk
+    KEYMAP_C := $(MAIN_KEYMAP_PATH_3)/keymap.c
+    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_3)
+else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_2)/keymap.c)","")
+    -include $(MAIN_KEYMAP_PATH_2)/rules.mk
+    KEYMAP_C := $(MAIN_KEYMAP_PATH_2)/keymap.c
+    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_2)
+else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_1)/keymap.c)","")
+    -include $(MAIN_KEYMAP_PATH_1)/rules.mk
+    KEYMAP_C := $(MAIN_KEYMAP_PATH_1)/keymap.c
+    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_1)
+else ifneq ($(LAYOUTS),)
+    include build_layout.mk
+else
+    $(error Could not find keymap)
+    # this state should never be reached
+endif
+
+ifeq ($(strip $(CTPC)), yes)
+  CONVERT_TO_PROTON_C=yes
+endif
+
+ifeq ($(strip $(CONVERT_TO_PROTON_C)), yes)
+    TARGET := $(TARGET)_proton_c
+    include $(STM32_PATH)/proton_c.mk
+    OPT_DEFS += -DCONVERT_TO_PROTON_C
+endif
+
+ifneq ($(FORCE_LAYOUT),)
+    TARGET := $(TARGET)_$(FORCE_LAYOUT)
+endif
+
+include quantum/mcu_selection.mk
+
+ifdef MCU_FAMILY
+    OPT_DEFS += -DQMK_STM32
+    KEYBOARD_PATHS += $(STM32_PATH)
+endif
+
+
 # Find all the C source files to be compiled in subfolders.
 KEYBOARD_SRC :=
 
@@ -223,39 +285,6 @@ PROJECT_DEFS := $(OPT_DEFS)
 PROJECT_INC := $(VPATH) $(EXTRAINCDIRS) $(KEYBOARD_PATHS)
 PROJECT_CONFIG := $(CONFIG_H)
 
-MAIN_KEYMAP_PATH_1 := $(KEYBOARD_PATH_1)/keymaps/$(KEYMAP)
-MAIN_KEYMAP_PATH_2 := $(KEYBOARD_PATH_2)/keymaps/$(KEYMAP)
-MAIN_KEYMAP_PATH_3 := $(KEYBOARD_PATH_3)/keymaps/$(KEYMAP)
-MAIN_KEYMAP_PATH_4 := $(KEYBOARD_PATH_4)/keymaps/$(KEYMAP)
-MAIN_KEYMAP_PATH_5 := $(KEYBOARD_PATH_5)/keymaps/$(KEYMAP)
-
-ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_5)/keymap.c)","")
-    -include $(MAIN_KEYMAP_PATH_5)/rules.mk
-    KEYMAP_C := $(MAIN_KEYMAP_PATH_5)/keymap.c
-    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_5)
-else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_4)/keymap.c)","")
-    -include $(MAIN_KEYMAP_PATH_4)/rules.mk
-    KEYMAP_C := $(MAIN_KEYMAP_PATH_4)/keymap.c
-    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_4)
-else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_3)/keymap.c)","")
-    -include $(MAIN_KEYMAP_PATH_3)/rules.mk
-    KEYMAP_C := $(MAIN_KEYMAP_PATH_3)/keymap.c
-    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_3)
-else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_2)/keymap.c)","")
-    -include $(MAIN_KEYMAP_PATH_2)/rules.mk
-    KEYMAP_C := $(MAIN_KEYMAP_PATH_2)/keymap.c
-    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_2)
-else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_1)/keymap.c)","")
-    -include $(MAIN_KEYMAP_PATH_1)/rules.mk
-    KEYMAP_C := $(MAIN_KEYMAP_PATH_1)/keymap.c
-    KEYMAP_PATH := $(MAIN_KEYMAP_PATH_1)
-else ifneq ($(LAYOUTS),)
-    include build_layout.mk
-else
-    $(error Could not find keymap)
-    # this state should never be reached
-endif
-
 # Userspace setup and definitions
 ifeq ("$(USER_NAME)","")
     USER_NAME := $(KEYMAP)
@@ -278,6 +307,7 @@ ifneq ("$(wildcard $(KEYMAP_PATH)/config.h)","")
 endif
 
 # # project specific files
+SRC += $(patsubst %.c,%.clib,$(LIB_SRC))
 SRC += $(KEYBOARD_SRC) \
     $(KEYMAP_C) \
     $(QUANTUM_SRC)
@@ -296,6 +326,7 @@ include $(TMK_PATH)/protocol.mk
 include $(TMK_PATH)/common.mk
 include bootloader.mk
 
+SRC += $(patsubst %.c,%.clib,$(QUANTUM_LIB_SRC))
 SRC += $(TMK_COMMON_SRC)
 OPT_DEFS += $(TMK_COMMON_DEFS)
 EXTRALDFLAGS += $(TMK_COMMON_LDFLAGS)
@@ -342,5 +373,7 @@ $(KEYBOARD_OUTPUT)_CONFIG := $(PROJECT_CONFIG)
 # Default target.
 all: build check-size
 build: elf cpfirmware
+check-size: build
 
+include show_options.mk
 include $(TMK_PATH)/rules.mk

build_layout.mk

@@ -15,4 +15,13 @@ define SEARCH_LAYOUTS
     $$(foreach LAYOUTS_REPO,$$(LAYOUTS_REPOS),$$(eval $$(call SEARCH_LAYOUTS_REPO)))
 endef
 
+ifneq ($(FORCE_LAYOUT),)
+    ifneq (,$(findstring $(FORCE_LAYOUT),$(LAYOUTS)))
+        $(info Forcing layout: $(FORCE_LAYOUT))
+        LAYOUTS := $(FORCE_LAYOUT)
+    else
+        $(error Forced layout does not exist)
+    endif
+endif
+
 $(foreach LAYOUT,$(LAYOUTS),$(eval $(call SEARCH_LAYOUTS)))

common.mk

@@ -21,5 +21,4 @@ COMMON_VPATH += $(QUANTUM_PATH)/keymap_extras
 COMMON_VPATH += $(QUANTUM_PATH)/audio
 COMMON_VPATH += $(QUANTUM_PATH)/process_keycode
 COMMON_VPATH += $(QUANTUM_PATH)/api
-COMMON_VPATH += $(QUANTUM_PATH)/split_common
 COMMON_VPATH += $(DRIVER_PATH)

common_features.mk

@@ -114,8 +114,27 @@ ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
     endif
 endif
 
-RGB_MATRIX_ENABLE ?= no
 VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 custom
+
+LED_MATRIX_ENABLE ?= no
+ifneq ($(strip $(LED_MATRIX_ENABLE)), no)
+    ifeq ($(filter $(LED_MATRIX_ENABLE),$(VALID_MATRIX_TYPES)),)
+        $(error LED_MATRIX_ENABLE="$(LED_MATRIX_ENABLE)" is not a valid matrix type)
+    else
+        OPT_DEFS += -DLED_MATRIX_ENABLE -DBACKLIGHT_ENABLE -DBACKLIGHT_CUSTOM_DRIVER
+        SRC += $(QUANTUM_DIR)/led_matrix.c
+        SRC += $(QUANTUM_DIR)/led_matrix_drivers.c
+    endif
+endif
+
+ifeq ($(strip $(LED_MATRIX_ENABLE)), IS31FL3731)
+    OPT_DEFS += -DIS31FL3731
+    COMMON_VPATH += $(DRIVER_PATH)/issi
+    SRC += is31fl3731-simple.c
+    SRC += i2c_master.c
+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)
@@ -191,7 +210,7 @@ ifeq ($(strip $(BACKLIGHT_ENABLE)), yes)
     ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
         CIE1931_CURVE = yes
     endif
-        ifeq ($(strip $(BACKLIGHT_CUSTOM_DRIVER)), yes)
+    ifeq ($(strip $(BACKLIGHT_CUSTOM_DRIVER)), yes)
         OPT_DEFS += -DBACKLIGHT_CUSTOM_DRIVER
     endif
 endif
@@ -225,6 +244,13 @@ ifeq ($(strip $(ENCODER_ENABLE)), yes)
     OPT_DEFS += -DENCODER_ENABLE
 endif
 
+ifeq ($(strip $(HAPTIC_ENABLE)), DRV2605L)
+    COMMON_VPATH += $(DRIVER_PATH)/haptic
+    SRC += DRV2605L.c
+    SRC += i2c_master.c
+    OPT_DEFS += -DDRV2605L
+endif
+
 ifeq ($(strip $(HD44780_ENABLE)), yes)
     SRC += drivers/avr/hd44780.c
     OPT_DEFS += -DHD44780_ENABLE
@@ -240,11 +266,14 @@ ifeq ($(strip $(LEADER_ENABLE)), yes)
   OPT_DEFS += -DLEADER_ENABLE
 endif
 
+include $(DRIVER_PATH)/qwiic/qwiic.mk
+
 QUANTUM_SRC:= \
     $(QUANTUM_DIR)/quantum.c \
     $(QUANTUM_DIR)/keymap_common.c \
     $(QUANTUM_DIR)/keycode_config.c
 
+# Include the standard or split matrix code if needed
 ifneq ($(strip $(CUSTOM_MATRIX)), yes)
     ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
         QUANTUM_SRC += $(QUANTUM_DIR)/split_common/matrix.c
@@ -253,10 +282,35 @@ ifneq ($(strip $(CUSTOM_MATRIX)), yes)
     endif
 endif
 
+DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce
+# Debounce Modules. If implemented in matrix.c, don't use these.
+DEBOUNCE_TYPE?= sym_g
+VALID_DEBOUNCE_TYPES := sym_g eager_pk custom
+ifeq ($(filter $(DEBOUNCE_TYPE),$(VALID_DEBOUNCE_TYPES)),)
+    $(error DEBOUNCE_TYPE="$(DEBOUNCE_TYPE)" is not a valid debounce algorithm)
+endif
+ifeq ($(strip $(DEBOUNCE_TYPE)), sym_g)
+    QUANTUM_SRC += $(DEBOUNCE_DIR)/debounce_sym_g.c
+else ifeq ($(strip $(DEBOUNCE_TYPE)), eager_pk)
+    QUANTUM_SRC += $(DEBOUNCE_DIR)/debounce_eager_pk.c
+endif
+
+
+
 ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
     OPT_DEFS += -DSPLIT_KEYBOARD
+
+    # Include files used by all split keyboards
     QUANTUM_SRC += $(QUANTUM_DIR)/split_common/split_flags.c \
-                $(QUANTUM_DIR)/split_common/split_util.c \
-                $(QUANTUM_DIR)/split_common/i2c.c \
-                $(QUANTUM_DIR)/split_common/serial.c
+                   $(QUANTUM_DIR)/split_common/split_util.c
+
+    # Determine which (if any) transport files are required
+    ifneq ($(strip $(SPLIT_TRANSPORT)), custom)
+        QUANTUM_SRC += $(QUANTUM_DIR)/split_common/transport.c
+        # Functions added via QUANTUM_LIB_SRC are only included in the final binary if they're called.
+        # Unused functions are pruned away, which is why we can add both drivers here without bloat.
+        QUANTUM_LIB_SRC += $(QUANTUM_DIR)/split_common/i2c.c \
+                           $(QUANTUM_DIR)/split_common/serial.c
+    endif
+    COMMON_VPATH += $(QUANTUM_PATH)/split_common
 endif

docs/LANGS.md

@@ -0,0 +1,4 @@
+# Languages
+
+* [English](/)
+* [Chinese](zh/)

docs/_sidebar.md

@@ -1,98 +0,0 @@
-* [Complete Newbs Guide](newbs.md)
-  * [Getting Started](newbs_getting_started.md)
-  * [Building Your First Firmware](newbs_building_firmware.md)
-  * [Flashing Firmware](newbs_flashing.md)
-  * [Testing and Debugging](newbs_testing_debugging.md)
-  * [Best Practices](newbs_best_practices.md)
-  * [Learning Resources](newbs_learn_more_resources.md)
-
-* [QMK Basics](README.md)
-  * [QMK Introduction](getting_started_introduction.md)
-  * [Contributing to QMK](contributing.md)
-  * [How to Use Github](getting_started_github.md)
-  * [Getting Help](getting_started_getting_help.md)
-
-* [FAQ](faq.md)
-  * [General FAQ](faq_general.md)
-  * [Build/Compile QMK](faq_build.md)
-  * [Debugging/Troubleshooting QMK](faq_debug.md)
-  * [Keymap](faq_keymap.md)
-
-* Detailed Guides
-  * [Install Build Tools](getting_started_build_tools.md)
-  * [Vagrant Guide](getting_started_vagrant.md)
-  * [Build/Compile Instructions](getting_started_make_guide.md)
-  * [Flashing Firmware](flashing.md)
-  * [Customizing Functionality](custom_quantum_functions.md)
-  * [Keymap Overview](keymap.md)
-
-* [Hardware](hardware.md)
-  * [AVR Processors](hardware_avr.md)
-  * [Drivers](hardware_drivers.md)
-
-* Reference
-  * [Keyboard Guidelines](hardware_keyboard_guidelines.md)
-  * [Config Options](config_options.md)
-  * [Keycodes](keycodes.md)
-  * [Documentation Best Practices](documentation_best_practices.md)
-  * [Documentation Templates](documentation_templates.md)
-  * [Glossary](reference_glossary.md)
-  * [Unit Testing](unit_testing.md)
-  * [Useful Functions](ref_functions.md)
-
-* [Features](features.md)
-  * [Basic Keycodes](keycodes_basic.md)
-  * [Quantum Keycodes](quantum_keycodes.md)
-  * [Advanced Keycodes](feature_advanced_keycodes.md)
-  * [Audio](feature_audio.md)
-  * [Auto Shift](feature_auto_shift.md)
-  * [Backlight](feature_backlight.md)
-  * [Bluetooth](feature_bluetooth.md)
-  * [Bootmagic](feature_bootmagic.md)
-  * [Combos](feature_combo)
-  * [Command](feature_command.md)
-  * [Dynamic Macros](feature_dynamic_macros.md)
-  * [Encoders](feature_encoders.md)
-  * [Grave Escape](feature_grave_esc.md)
-  * [Key Lock](feature_key_lock.md)
-  * [Layouts](feature_layouts.md)
-  * [Leader Key](feature_leader_key.md)
-  * [Macros](feature_macros.md)
-  * [Mouse Keys](feature_mouse_keys.md)
-  * [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)
-  * [Stenography](feature_stenography.md)
-  * [Swap Hands](feature_swap_hands.md)
-  * [Tap Dance](feature_tap_dance.md)
-  * [Terminal](feature_terminal.md)
-  * [Thermal Printer](feature_thermal_printer.md)
-  * [Unicode](feature_unicode.md)
-  * [Userspace](feature_userspace.md)
-  * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
-
-* For Makers and Modders
-  * [Hand Wiring Guide](hand_wire.md)
-  * [ISP Flashing Guide](isp_flashing_guide.md)
-  * [ARM Debugging Guide](arm_debugging.md)
-  * [I2C Driver](i2c_driver.md)
-
-* For a Deeper Understanding
-  * [How Keyboards Work](how_keyboards_work.md)
-  * [Understanding QMK](understanding_qmk.md)
-
-* Other Topics
-  * [Using Eclipse with QMK](eclipse.md)
-
-* QMK Internals (In Progress)
-  * [Defines](internals_defines.md)
-  * [Input Callback Reg](internals_input_callback_reg.md)
-  * [Midi Device](internals_midi_device.md)
-  * [Midi Device Setup Process](internals_midi_device_setup_process.md)
-  * [Midi Util](internals_midi_util.md)
-  * [Send Functions](internals_send_functions.md)
-  * [Sysex Tools](internals_sysex_tools.md)

docs/_summary.md

@@ -39,9 +39,12 @@
   * [Glossary](reference_glossary.md)
   * [Unit Testing](unit_testing.md)
   * [Useful Functions](ref_functions.md)
+  * [Configurator Support](reference_configurator_support.md)
+  * [info.json Format](reference_info_json.md)
 
 * [Features](features.md)
   * [Basic Keycodes](keycodes_basic.md)
+  * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
   * [Quantum Keycodes](quantum_keycodes.md)
   * [Advanced Keycodes](feature_advanced_keycodes.md)
   * [Audio](feature_audio.md)
@@ -73,13 +76,14 @@
   * [Thermal Printer](feature_thermal_printer.md)
   * [Unicode](feature_unicode.md)
   * [Userspace](feature_userspace.md)
-  * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
 
 * For Makers and Modders
   * [Hand Wiring Guide](hand_wire.md)
   * [ISP Flashing Guide](isp_flashing_guide.md)
   * [ARM Debugging Guide](arm_debugging.md)
   * [I2C Driver](i2c_driver.md)
+  * [GPIO Controls](internals_gpio_control.md)
+  * [Proton C Conversion](proton_c_conversion.md)
 
 * For a Deeper Understanding
   * [How Keyboards Work](how_keyboards_work.md)
@@ -87,6 +91,7 @@
 
 * Other Topics
   * [Using Eclipse with QMK](eclipse.md)
+  * [Support](support.md)
 
 * QMK Internals (In Progress)
   * [Defines](internals_defines.md)

docs/config_options.md

@@ -87,7 +87,7 @@ This is a C header file that is one of the first things included, and will persi
   * mechanical locking support. Use KC_LCAP, KC_LNUM or KC_LSCR instead in keymap
 * `#define LOCKING_RESYNC_ENABLE`
   * tries to keep switch state consistent with keyboard LED state
-* `#define IS_COMMAND() ( keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)) )`
+* `#define IS_COMMAND() (get_mods() == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)))`
   * key combination that allows the use of magic commands (useful for debugging)
 * `#define USB_MAX_POWER_CONSUMPTION`
   * sets the maximum power (in mA) over USB for the device (default: 500)
@@ -109,9 +109,9 @@ If you define these options you will disable the associated feature, which can s
 * `#define NO_ACTION_ONESHOT`
   * disable one-shot modifiers
 * `#define NO_ACTION_MACRO`
-  * disable all macro handling
+  * disable old style macro handling: MACRO() & action_get_macro
 * `#define NO_ACTION_FUNCTION`
-  * disable the action function (deprecated)
+  * disable calling of action_function() from the fn_actions array (deprecated)
 
 ## Features That Can Be Enabled
 
@@ -143,6 +143,11 @@ If you define these options you will enable the associated feature, which may in
   * Breaks any Tap Toggle functionality (`TT` or the One Shot Tap Toggle)
 * `#define LEADER_TIMEOUT 300`
   * how long before the leader key times out
+    * If you're having issues finishing the sequence before it times out, you may need to increase the timeout setting. Or you may want to enable the `LEADER_PER_KEY_TIMING` option, which resets the timeout after each key is tapped.
+* `#define LEADER_PER_KEY_TIMING`
+  * sets the timer for leader key chords to run on each key press rather than overall
+* `#define LEADER_KEY_STRICT_KEY_PROCESSING`
+  * Disables keycode filtering for Mod-Tap and Layer-Tap keycodes. Eg, if you enable this, you would need to specify `MT(MOD_CTL, KC_A)` if you want to use `KC_A`.
 * `#define ONESHOT_TIMEOUT 300`
   * how long before oneshot times out
 * `#define ONESHOT_TAP_TOGGLE 2`
@@ -160,6 +165,8 @@ If you define these options you will enable the associated feature, which may in
   * Set this to the number of combos that you're using in the [Combo](feature_combo.md) feature.
 * `#define COMBO_TERM 200`
   * how long for the Combo keys to be detected. Defaults to `TAPPING_TERM` if not defined.
+* `#define TAP_CODE_DELAY 100`
+  * Sets the delay between `register_code` and `unregister_code`, if you're having issues with it registering properly (common on VUSB boards). The value is in milliseconds.
 
 ## RGB Light Configuration
 
@@ -190,12 +197,51 @@ If you define these options you will enable the associated feature, which may in
 
 Split Keyboard specific options, make sure you have 'SPLIT_KEYBOARD = yes' in your rules.mk
 
+* `SPLIT_TRANSPORT = custom`
+  * Allows replacing the standard split communication routines with a custom one. ARM based split keyboards must use this at present.
+
+### Setting Handedness
+
+One thing to remember, the side that the USB port is plugged into is always the master half. The side not plugged into USB is the slave.
+
+There are a few different ways to set handedness for split keyboards (listed in order of precedence):
+
+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
+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
+
 * `#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 you can still use the EEHANDS method or MASTER_LEFT / MASTER_RIGHT defines like the stock Let's Split uses.
-  
+  * 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.
+
+* `#define EE_HANDS` (only works if `SPLIT_HAND_PIN` is not defined)
+  * Reads the handedness value stored in the EEPROM after `eeprom-lefthand.eep`/`eeprom-righthand.eep` has been flashed to their respective halves.
+
+* `#define MASTER_RIGHT`
+  * Master half is defined to be the right half.
+
+### Other Options
+
 * `#define USE_I2C`
   * For using I2C instead of Serial (defaults to serial)
 
+* `#define SOFT_SERIAL_PIN D0`
+  * When using serial, define this. `D0` or `D1`,`D2`,`D3`,`E6`.
+
+* `#define MATRIX_ROW_PINS_RIGHT { <row pins> }`
+* `#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 SELECT_SOFT_SERIAL_SPEED <speed>` (default speed is 1)
+  * Sets the protocol speed when using serial communication
+  * Speeds:
+    * 0: about 189kbps (Experimental only)
+    * 1: about 137kbps (default)
+    * 2: about 75kbps
+    * 3: about 39kbps
+    * 4: about 26kbps
+    * 5: about 20kbps
+
 # The `rules.mk` File
 
 This is a [make](https://www.gnu.org/software/make/manual/make.html) file that is included by the top-level `Makefile`. It is used to set some information about the MCU that we will be compiling for as well as enabling and disabling certain features.
@@ -247,6 +293,8 @@ Use these to enable or disable building certain features. The more you have enab
   * Enable the audio subsystem.
 * `RGBLIGHT_ENABLE`
   * Enable keyboard underlight functionality
+* `LEADER_ENABLE`
+  * Enable leader key chording
 * `MIDI_ENABLE`
   * MIDI controls
 * `UNICODE_ENABLE`
@@ -257,7 +305,40 @@ Use these to enable or disable building certain features. The more you have enab
   * Current options are AdafruitEzKey, AdafruitBLE, RN42
 * `SPLIT_KEYBOARD`
   * Enables split keyboard support (dual MCU like the let's split and bakingpy's boards) and includes all necessary files located at quantum/split_common
+* `CUSTOM_MATRIX`
+  * Allows replacing the standard matrix scanning routine with a custom one.
+* `CUSTOM_DEBOUNCE`
+  * Allows replacing the standard key debouncing routine with a custom one.
 * `WAIT_FOR_USB`
   * Forces the keyboard to wait for a USB connection to be established before it starts up
 * `NO_USB_STARTUP_CHECK`
   * Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master.
+
+## USB Endpoint Limitations
+
+In order to provide services over USB, QMK has to use USB endpoints.
+These are a finite resource: each microcontroller has only a certain number.
+This limits what features can be enabled together.
+If the available endpoints are exceeded, a build error is thrown.
+
+The following features can require separate endpoints:
+
+* `MOUSEKEY_ENABLE`
+* `EXTRAKEY_ENABLE`
+* `CONSOLE_ENABLE`
+* `NKRO_ENABLE`
+* `MIDI_ENABLE`
+* `RAW_ENABLE`
+* `VIRTSER_ENABLE`
+
+In order to improve utilisation of the endpoints, the HID features can be combined to use a single endpoint.
+By default, `MOUSEKEY`, `EXTRAKEY`, and `NKRO` are combined into a single endpoint.
+
+The base keyboard functionality can also be combined into the endpoint,
+by setting `KEYBOARD_SHARED_EP = yes`.
+This frees up one more endpoint,
+but it can prevent the keyboard working in some BIOSes,
+as they do not implement Boot Keyboard protocol switching.
+
+Combining the mouse also breaks Boot Mouse compatibility.
+The mouse can be uncombined by setting `MOUSE_SHARED_EP = no` if this functionality is required.

docs/custom_quantum_functions.md

@@ -90,7 +90,7 @@ keyrecord_t record {
 
 # LED Control
 
-This allows you to control the 5 LED's defined as part of the USB Keyboard spec. It will be called when the state of one of those 5 LEDs changes.
+QMK provides methods to read the 5 LEDs defined as part of the HID spec:
 
 * `USB_LED_NUM_LOCK`
 * `USB_LED_CAPS_LOCK`
@@ -98,31 +98,44 @@ This allows you to control the 5 LED's defined as part of the USB Keyboard spec.
 * `USB_LED_COMPOSE`
 * `USB_LED_KANA`
 
+These five constants correspond to the positional bits of the host LED state.
+There are two ways to get the host LED state:
+
+* by implementing `led_set_user()`
+* by calling `host_keyboard_leds()`
+
+## `led_set_user()`
+
+This function will be called when the state of one of those 5 LEDs changes. It receives the LED state as a parameter.
+Use the `IS_LED_ON(usb_led, led_name)` and `IS_LED_OFF(usb_led, led_name)` macros to check the LED status.
+
+!> `host_keyboard_leds()` may already reflect a new value before `led_set_user()` is called.
+
 ### Example `led_set_user()` Implementation
 
 ```c
 void led_set_user(uint8_t usb_led) {
-    if (usb_led & (1<<USB_LED_NUM_LOCK)) {
+    if (IS_LED_ON(usb_led, USB_LED_NUM_LOCK)) {
         PORTB |= (1<<0);
     } else {
         PORTB &= ~(1<<0);
     }
-    if (usb_led & (1<<USB_LED_CAPS_LOCK)) {
+    if (IS_LED_ON(usb_led, USB_LED_CAPS_LOCK)) {
         PORTB |= (1<<1);
     } else {
         PORTB &= ~(1<<1);
     }
-    if (usb_led & (1<<USB_LED_SCROLL_LOCK)) {
+    if (IS_LED_ON(usb_led, USB_LED_SCROLL_LOCK)) {
         PORTB |= (1<<2);
     } else {
         PORTB &= ~(1<<2);
     }
-    if (usb_led & (1<<USB_LED_COMPOSE)) {
+    if (IS_LED_ON(usb_led, USB_LED_COMPOSE)) {
         PORTB |= (1<<3);
     } else {
         PORTB &= ~(1<<3);
     }
-    if (usb_led & (1<<USB_LED_KANA)) {
+    if (IS_LED_ON(usb_led, USB_LED_KANA)) {
         PORTB |= (1<<4);
     } else {
         PORTB &= ~(1<<4);
@@ -135,19 +148,52 @@ void led_set_user(uint8_t usb_led) {
 * Keyboard/Revision: `void led_set_kb(uint8_t usb_led)`
 * Keymap: `void led_set_user(uint8_t usb_led)`
 
+## `host_keyboard_leds()`
 
-# Matrix Initialization Code
+Call this function to get the last received LED state. This is useful for reading the LED state outside `led_set_*`, e.g. in [`matrix_scan_user()`](#matrix-scanning-code).
+For convenience, you can use the `IS_HOST_LED_ON(led_name)` and `IS_HOST_LED_OFF(led_name)` macros instead of calling and checking `host_keyboard_leds()` directly.
 
-Before a keyboard can be used the hardware must be initialized. QMK handles initialization of the keyboard matrix itself, but if you have other hardware like LED's or i&#xb2;c controllers you will need to set up that hardware before it can be used.
+## Setting Physical LED State
 
+Some keyboard implementations provide convenience methods for setting the state of the physical LEDs.
 
-### Example `matrix_init_user()` Implementation
+### Ergodox Boards
+
+The Ergodox implementations provide `ergodox_right_led_1`/`2`/`3_on`/`off()` to turn individual LEDs on or off, as well as `ergodox_right_led_on`/`off(uint8_t led)` to turn them on or off by their index.
+
+In addition, it is possible to specify the brightness level of all LEDs with `ergodox_led_all_set(uint8_t n)`; of individual LEDs with `ergodox_right_led_1`/`2`/`3_set(uint8_t n)`; or by index with `ergodox_right_led_set(uint8_t led, uint8_t n)`.
+
+Ergodox boards also define `LED_BRIGHTNESS_LO` for the lowest brightness and `LED_BRIGHTNESS_HI` for the highest brightness (which is the default).
+
+# Keyboard Initialization Code
+
+There are several steps in the keyboard initialization process.  Depending on what you want to do, it will influence which function you should use.
+
+These are the three main initialization functions, listed in the order that they're called.
+
+* `keyboard_pre_init_*` - Happens before most anything is started. Good for hardware setup that you want running very early.
+* `matrix_init_*` - Happens midway through the firmware's startup process. Hardware is initialized, but features may not be yet.
+* `keyboard_post_init_*` - Happens at the end of the firmware's startup process. This is where you'd want to put "customization" code, for the most part.
+
+!> For most people, the `keyboard_post_init_user` function is what you want to call.  For instance, this is where you want to set up things for RGB Underglow.
+
+## Keyboard Pre Initialization code
+
+This runs very early during startup, even before the USB has been started. 
+
+Shortly after this, the matrix is initialized.
+
+For most users, this shouldn't be used, as it's primarily for hardware oriented initialization. 
+
+However, if you have hardware stuff that you need initialized, this is the best place for it (such as initializing LED pins).
+
+### Example `keyboard_pre_init_user()` Implementation
 
 This example, at the keyboard level, sets up B1, B2, and B3 as LED pins.
 
 ```c
-void matrix_init_user(void) {
-  // Call the keymap level matrix init.
+void keyboard_pre_init_user(void) {
+  // Call the keyboard pre init code.
 
   // Set our LED pins as output
   DDRB |= (1<<1);
@@ -156,11 +202,47 @@ void matrix_init_user(void) {
 }
 ```
 
+### `keyboard_pre_init_*` Function Documentation
+
+* Keyboard/Revision: `void keyboard_pre_init_kb(void)`
+* Keymap: `void keyboard_pre_init_user(void)`
+
+## Matrix Initialization Code
+
+This is called when the matrix is initialized, and after some of the hardware has been set up, but before many of the features have been initialized. 
+
+This is useful for setting up stuff that you may need elsewhere, but isn't hardware related nor is dependant on where it's started. 
+
+
 ### `matrix_init_*` Function Documentation
 
 * Keyboard/Revision: `void matrix_init_kb(void)`
 * Keymap: `void matrix_init_user(void)`
 
+
+## Keyboard Post Initialization code
+
+This is ran as the very last task in the keyboard initialization process. This is useful if you want to make changes to certain features, as they should be initialized by this point.
+
+
+### Example `keyboard_post_init_user()` Implementation
+
+This example, running after everything else has initialized, sets up the rgb underglow configuration.
+
+```c
+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_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // sets mode to Fast breathing without saving
+}
+```
+
+### `keyboard_post_init_*` Function Documentation
+
+* Keyboard/Revision: `void keyboard_post_init_kb(void)`
+* Keymap: `void keyboard_post_init_user(void)`
+
 # Matrix Scanning Code
 
 Whenever possible you should customize your keyboard by using `process_record_*()` and hooking into events that way, to ensure that your code does not have a negative performance impact on your keyboard. However, in rare cases it is necessary to hook into the matrix scanning. Be extremely careful with the performance of code in these functions, as it will be called at least 10 times per second.
@@ -176,7 +258,7 @@ This example has been deliberately omitted. You should understand enough about Q
 
 This function gets called at every matrix scan, which is basically as often as the MCU can handle. Be careful what you put here, as it will get run a lot.
 
-You should use this function if you need custom matrix scanning code. It can also be used for custom status output (such as LED's or a display) or other functionality that you want to trigger regularly even when the user isn't typing.
+You should use this function if you need custom matrix scanning code. It can also be used for custom status output (such as LEDs or a display) or other functionality that you want to trigger regularly even when the user isn't typing.
 
 
 # Keyboard Idling/Wake Code
@@ -200,10 +282,9 @@ void suspend_wakeup_init_user(void)
 {
     rgb_matrix_set_suspend_state(false);
 }
-
 ```
 
-### `keyboard_init_*` Function Documentation
+### Keyboard suspend/wake  Function Documentation
 
 * Keyboard/Revision: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)`
 * Keymap: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)`
@@ -256,7 +337,7 @@ Keep in mind that EEPROM has a limited number of writes. While this is very high
 
 * If you don't understand the example, then you may want to avoid using this feature, as it is rather complicated. 
 
-### Example  Implementation
+### Example Implementation
 
 This is an example of how to add settings, and read and write it. We're using the user keymap for the example here.  This is a complex function, and has a lot going on.  In fact, it uses a lot of the above functions to work! 
 

docs/faq_build.md

@@ -37,6 +37,10 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="066
 SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", 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 
+Pro Micro (Atmega32u4), make sure to include `CONFIG_USB_ACM=y`. Other devices may require `USB_SERIAL` and any of its sub options.
+
 ## Unknown Device for DFU Bootloader
 
 If you're using Windows to flash your keyboard, and you are running into issues, check the Device Manager.  If you see an "Unknown Device" when the keyboard is in "bootloader mode", then you may have a driver issue. 

docs/faq_keymap.md

@@ -11,8 +11,8 @@ Keycodes are actually defined in [common/keycode.h](https://github.com/qmk/qmk_f
 
 There are 3 standard keyboard layouts in use around the world- ANSI, ISO, and JIS. North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS. Regions not mentioned typically use either ANSI or ISO. The keycodes corresponding to these layouts are shown here:
 
-<!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/070a530eedaed36a2d77f3f6fd455677 -->
-![Keyboard Layout Image](https://i.imgur.com/gvlNUpQ.png)
+<!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
+![Keyboard Layout Image](https://i.imgur.com/5wsh5wM.png)
 
 ## Some Of My Keys Are Swapped Or Not Working
 
@@ -211,20 +211,3 @@ here real_mods lost state for 'physical left shift'.
 
 weak_mods is ORed with real_mods when keyboard report is sent.
 https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57
-
-## Timer Functionality
-
-It's possible to start timers and read values for time-specific events - here's an example:
-
-```c
-static uint16_t key_timer;
-key_timer = timer_read();
-
-if (timer_elapsed(key_timer) < 100) {
-  // do something if less than 100ms have passed
-} else {
-  // do something if 100ms or more have passed
-}
-```
-
-It's best to declare the `static uint16_t key_timer;` at the top of the file, outside of any code blocks you're using it in.

docs/feature_advanced_keycodes.md

@@ -21,11 +21,11 @@ Additionally, if at least one right-handed modifier is specified in a Mod Tap or
 
 # Switching and Toggling Layers
 
-These functions allow you to activate layers in various ways. Note that layers are not generally independent layouts -- multiple layers can be activated at once, and it's typical for layers to use `KC_TRNS` to allow keypresses to pass through to lower layers. For a detailed explanation of layers, see [Keymap Overview](keymap.md#keymap-and-layers)
+These functions allow you to activate layers in various ways. Note that layers are not generally independent layouts -- multiple layers can be activated at once, and it's typical for layers to use `KC_TRNS` to allow keypresses to pass through to lower layers. For a detailed explanation of layers, see [Keymap Overview](keymap.md#keymap-and-layers). When using momentary layer switching with MO(), LM(), TT(), or LT(), make sure to leave the key on the above layers transparent or it may not work as intended.
 
 * `DF(layer)` - switches the default layer. The default layer is the always-active base layer that other layers stack on top of. See below for more about the default layer. This might be used to switch from QWERTY to Dvorak layout. (Note that this is a temporary switch that only persists until the keyboard loses power. To modify the default layer in a persistent way requires deeper customization, such as calling the `set_single_persistent_default_layer` function inside of [process_record_user](custom_quantum_functions.md#programming-the-behavior-of-any-keycode).)
 * `MO(layer)` - momentarily activates *layer*. As soon as you let go of the key, the layer is deactivated. 
-* `LM(layer, mod)` - Momentarily activates *layer* (like `MO`), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers.
+* `LM(layer, mod)` - Momentarily activates *layer* (like `MO`), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers: `MOD_LCTL`, `MOD_LSFT`, `MOD_LALT`, `MOD_LGUI` (note the use of `MOD_` constants instead of `KC_`). These modifiers can be combined using bitwise OR, e.g. `LM(_RAISE, MOD_LCTL | MOD_LALT)`.
 * `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped. Only supports layers 0-15.
 * `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys](#one-shot-keys) for details and additional functionality.
 * `TG(layer)` - toggles *layer*, activating it if it's inactive and vice versa
@@ -60,21 +60,21 @@ Sometimes, you might want to switch between layers in a macro or as part of a ta
 
 These allow you to combine a modifier with a keycode. When pressed, the keydown event for the modifier, then `kc` will be sent. On release, the keyup event for `kc`, then the modifier will be sent.
 
-|Key       |Aliases               |Description                                         |
-|----------|----------------------|----------------------------------------------------|
-|`LCTL(kc)`|                      |Hold Left Control and press `kc`                    |
-|`LSFT(kc)`|`S(kc)`               |Hold Left Shift and press `kc`                      |
-|`LALT(kc)`|                      |Hold Left Alt and press `kc`                        |
-|`LGUI(kc)`|`LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc`                        |
-|`RCTL(kc)`|                      |Hold Right Control and press `kc`                   |
-|`RSFT(kc)`|                      |Hold Right Shift and press `kc`                     |
-|`RALT(kc)`|                      |Hold Right Alt and press `kc`                       |
-|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)`|Hold Right GUI and press `kc`                       |
-|`HYPR(kc)`|                      |Hold Left Control, Shift, Alt and GUI and press `kc`|
-|`MEH(kc)` |                      |Hold Left Control, Shift and Alt and press `kc`     |
-|`LCAG(kc)`|                      |Hold Left Control, Alt and GUI and press `kc`       |
-|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`|Hold Left Shift and GUI and press `kc`              |
-|`LCA(kc)` |                      |Hold Left Control and Alt and press `kc`            |
+|Key       |Aliases                        |Description                                         |
+|----------|-------------------------------|----------------------------------------------------|
+|`LCTL(kc)`|`C(kc)`                        |Hold Left Control and press `kc`                    |
+|`LSFT(kc)`|`S(kc)`                        |Hold Left Shift and press `kc`                      |
+|`LALT(kc)`|`A(kc)`                        |Hold Left Alt and press `kc`                        |
+|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc`                        |
+|`RCTL(kc)`|                               |Hold Right Control and press `kc`                   |
+|`RSFT(kc)`|                               |Hold Right Shift and press `kc`                     |
+|`RALT(kc)`|`ALGR(kc)`                     |Hold Right Alt and press `kc`                       |
+|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)`         |Hold Right GUI and press `kc`                       |
+|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`         |Hold Left Shift and GUI and press `kc`              |
+|`LCA(kc)` |                               |Hold Left Control and Alt and press `kc`            |
+|`LCAG(kc)`|                               |Hold Left Control, Alt and GUI and press `kc`       |
+|`MEH(kc)` |                               |Hold Left Control, Shift and Alt and press `kc`     |
+|`HYPR(kc)`|                               |Hold Left Control, Shift, Alt and GUI and press `kc`|
 
 You can also chain them, for example `LCTL(LALT(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress.
 
@@ -92,7 +92,7 @@ The modifiers this keycode and `OSM()` accept are prefixed with `MOD_`, not `KC_
 |`MOD_LGUI`|Left GUI (Windows/Command/Meta key)     |
 |`MOD_RCTL`|Right Control                           |
 |`MOD_RSFT`|Right Shift                             |
-|`MOD_RALT`|Right Alt                               |
+|`MOD_RALT`|Right Alt (AltGr)                       |
 |`MOD_RGUI`|Right GUI (Windows/Command/Meta key)    |
 |`MOD_HYPR`|Hyper (Left Control, Shift, Alt and GUI)|
 |`MOD_MEH` |Meh (Left Control, Shift, and Alt)      |
@@ -107,23 +107,23 @@ This key would activate Left Control and Left Shift when held, and send Escape w
 
 For convenience, QMK includes some Mod-Tap shortcuts to make common combinations more compact in your keymap:
 
-|Key         |Aliases                                |Description                                            |
-|------------|---------------------------------------|-------------------------------------------------------|
-|`LCTL_T(kc)`|`CTL_T(kc)`                            |Left Control when held, `kc` when tapped               |
-|`RCTL_T(kc)`|                                       |Right Control when held, `kc` when tapped              |
-|`LSFT_T(kc)`|`SFT_T(kc)`                            |Left Shift when held, `kc` when tapped                 |
-|`RSFT_T(kc)`|                                       |Right Shift when held, `kc` when tapped                |
-|`LALT_T(kc)`|`ALT_T(kc)`                            |Left Alt when held, `kc` when tapped                   |
-|`RALT_T(kc)`|`ALGR_T(kc)`                           |Right Alt when held, `kc` when tapped                  |
-|`LGUI_T(kc)`|`LCMD_T(kc)`, `RWIN_T(kc)`, `GUI_T(kc)`|Left GUI when held, `kc` when tapped                   |
-|`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)`             |Right GUI when held, `kc` when tapped                  |
-|`C_S_T(kc)` |                                       |Left Control and Shift when held, `kc` when tapped     |
-|`MEH_T(kc)` |                                       |Left Control, Shift and Alt when held, `kc` when tapped|
-|`LCAG_T(kc)`|                                       |Left Control, Alt and GUI when held, `kc` when tapped  |
-|`RCAG_T(kc)`|                                       |Right Control, Alt and GUI when held, `kc` when tapped |
-|`ALL_T(kc)` |                                       |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)|
-|`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)`             |Left Shift and GUI when held, `kc` when tapped         |
-|`LCA_T(kc)` |                                       |Left Control and Alt when held, `kc` when tapped       |
+|Key         |Aliases                                                          |Description                                            |
+|------------|-----------------------------------------------------------------|-------------------------------------------------------|
+|`LCTL_T(kc)`|`CTL_T(kc)`                                                      |Left Control when held, `kc` when tapped               |
+|`LSFT_T(kc)`|`SFT_T(kc)`                                                      |Left Shift when held, `kc` when tapped                 |
+|`LALT_T(kc)`|`ALT_T(kc)`                                                      |Left Alt when held, `kc` when tapped                   |
+|`LGUI_T(kc)`|`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|Left GUI when held, `kc` when tapped                   |
+|`RCTL_T(kc)`|                                                                 |Right Control when held, `kc` when tapped              |
+|`RSFT_T(kc)`|                                                                 |Right Shift when held, `kc` when tapped                |
+|`RALT_T(kc)`|`ALGR_T(kc)`                                                     |Right Alt when held, `kc` when tapped                  |
+|`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)`                                       |Right GUI when held, `kc` when tapped                  |
+|`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)`                                       |Left Shift and GUI when held, `kc` when tapped         |
+|`LCA_T(kc)` |                                                                 |Left Control and Alt when held, `kc` when tapped       |
+|`LCAG_T(kc)`|                                                                 |Left Control, Alt and GUI when held, `kc` when tapped  |
+|`RCAG_T(kc)`|                                                                 |Right Control, Alt and GUI when held, `kc` when tapped |
+|`C_S_T(kc)` |                                                                 |Left Control and Shift when held, `kc` when tapped     |
+|`MEH_T(kc)` |                                                                 |Left Control, Shift and Alt when held, `kc` when tapped|
+|`HYPR_T(kc)`|`ALL_T(kc)`                                                      |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)|
 
 ## Caveats
 
@@ -161,8 +161,88 @@ For one shot mods, you need to call `set_oneshot_mods(MOD)` to set it, or `clear
 
 !> If you're having issues with OSM translating over Remote Desktop Connection, this can be fixed by opening the settings, going to the "Local Resources" tap, and in the keyboard section, change the drop down to "On this Computer".  This will fix the issue and allow OSM to function properly over Remote Desktop.
 
+## Callbacks
 
-# Permissive Hold
+When you'd like to perform custom logic when pressing a one shot key, there are several callbacks you can choose to implement. You could indicate changes in one shot keys by flashing an LED or making a sound, for example.
+
+There is a callback for `OSM(mod)`. It is called whenever the state of any one shot modifier key is changed: when it toggles on, but also when it is toggled off. You can use it like this:
+
+```c
+void oneshot_mods_changed_user(uint8_t mods) {
+  if (mods & MOD_MASK_SHIFT) {
+    println("Oneshot mods SHIFT");
+  }
+  if (mods & MOD_MASK_CTRL) {
+    println("Oneshot mods CTRL");
+  }
+  if (mods & MOD_MASK_ALT) {
+    println("Oneshot mods ALT");
+  }
+  if (mods & MOD_MASK_GUI) {
+    println("Oneshot mods GUI");
+  }
+  if (!mods) {
+    println("Oneshot mods off");
+  }
+}
+```
+
+The `mods` argument contains the active mods after the change, so it reflects the current state.
+
+When you use One Shot Tap Toggle (by adding `#define ONESHOT_TAP_TOGGLE 2` in your `config.h` file), you may lock a modifier key by pressing it the specified amount of times. There's a callback for that, too:
+
+```c
+void oneshot_locked_mods_changed_user(uint8_t mods) {
+  if (mods & MOD_MASK_SHIFT) {
+    println("Oneshot locked mods SHIFT");
+  }
+  if (mods & MOD_MASK_CTRL) {
+    println("Oneshot locked mods CTRL");
+  }
+  if (mods & MOD_MASK_ALT) {
+    println("Oneshot locked mods ALT");
+  }
+  if (mods & MOD_MASK_GUI) {
+    println("Oneshot locked mods GUI");
+  }
+  if (!mods) {
+    println("Oneshot locked mods off");
+  }
+}
+```
+
+Last, there is also a callback for the `OSL(layer)` one shot key:
+
+```c
+void oneshot_layer_changed_user(uint8_t layer) {
+  if (layer == 1) {
+    println("Oneshot layer 1 on");
+  }
+  if (!layer) {
+    println("Oneshot layer off");
+  }
+}
+```
+
+If any one shot layer is switched off, `layer` will be zero. When you're looking to do something on any layer change instead of one shot layer changes, `layer_state_set_user` is a better callback to use.
+
+If you are making your own keyboard, there are also `_kb` equivalent functions:
+
+```c
+void oneshot_locked_mods_changed_kb(uint8_t mods);
+void oneshot_mods_changed_kb(uint8_t mods);
+void oneshot_layer_changed_kb(uint8_t layer);
+```
+
+As with any callback, be sure to call the `_user` variant to allow for further customizability.
+
+# Tap-Hold Configuration Options
+
+While Tap-Hold options are fantastic, they are not without their issues.  We have tried to configure them with reasonal defaults, but that may still cause issues for some people. 
+
+These options let you modify the behavior of the Tap-Hold keys.
+
+## Permissive Hold
 
 As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new `config.h` option:
 
@@ -185,7 +265,7 @@ Normally, if you do all this within the `TAPPING_TERM` (default: 200ms) this wil
 
 ?> If you have `Ignore Mod Tap Interrupt` enabled, as well, this will modify how both work. The regular key has the modifier added if the first key is released first or if both keys are held longer than the `TAPPING_TERM`.
 
-# Ignore Mod Tap Interrupt
+## Ignore Mod Tap Interrupt
 
 To enable this setting, add this to your `config.h`:
 
@@ -211,7 +291,7 @@ Normally, this would send `X` (`SHIFT`+`x`). With `Ignore Mod Tap Interrupt` ena
 
 ?> If you have `Permissive Hold` enabled, as well, this will modify how both work. The regular key has the modifier added if the first key is released first or if both keys are held longer than the `TAPPING_TERM`.
 
-# Tapping Force Hold
+## Tapping Force Hold
 
 To enable `tapping force hold`, add the following to your `config.h`: 
 
@@ -235,7 +315,7 @@ With `TAPPING_FORCE_HOLD`, the second press will be interpreted as a Shift, allo
 
 !> `TAPPING_FORCE_HOLD` will break anything that uses tapping toggles (Such as the `TT` layer keycode, and the One Shot Tapping Toggle).
 
-# Retro Tapping
+## Retro Tapping
 
 To enable `retro tapping`, add the following to your `config.h`: 
 

docs/feature_audio.md

@@ -61,10 +61,19 @@ It's advised that you wrap all audio features in `#ifdef AUDIO_ENABLE` / `#endif
 
 The available keycodes for audio are: 
 
-* `AU_ON` - Turn audio mode on
-* `AU_OFF` - Turn audio mode off
-* `AU_TOG` - Toggle audio mode
+* `AU_ON` - Turn Audio Feature on
+* `AU_OFF` - Turn Audio Feature off
+* `AU_TOG` - Toggle Audio Feature state
 
+!> These keycodes turn all of the audio functionality on and off.  Turning it off means that audio feedback, audio clicky, music mode, etc. are disabled, completely. 
+
+## ARM Audio Volume
+
+For ARM devices, you can adjust the DAC sample values. If your board is too loud for you or your coworkers, you can set the max using `DAC_SAMPLE_MAX` in your `config.h`:
+
+```c
+#define DAC_SAMPLE_MAX 65535U
+```
 
 ## Music Mode
 
@@ -151,7 +160,7 @@ You can configure the default, min and max frequencies, the stepping and built i
 
 ## MIDI Functionality
 
-This is still a WIP, but check out `quantum/keymap_midi.c` to see what's happening. Enable from the Makefile.
+This is still a WIP, but check out `quantum/process_keycode/process_midi.c` to see what's happening. Enable from the Makefile.
 
 
 ## Audio Keycodes

docs/feature_backlight.md

@@ -40,6 +40,7 @@ To change the behaviour of the backlighting, `#define` these in your `config.h`:
 |---------------------|-------------|-------------------------------------------------------------------------------------------------------------|
 |`BACKLIGHT_PIN`      |`B7`         |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this|
 |`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                                                          |
 |`BREATHING_PERIOD`   |`6`          |The length of one backlight "breath" in seconds                                                              |
 
@@ -54,14 +55,17 @@ In this handler, the value of an incrementing counter is mapped onto a precomput
 
 ## Backlight Functions
 
-|Function  |Description                                               |
-|----------|----------------------------------------------------------|
-|`backlight_toggle()`   |Turn the backlight on or off                 |
-|`backlight_step()`     |Cycle through backlight levels               |
-|`backlight_increase()` |Increase the backlight level                 |
-|`backlight_decrease()` |Decrease the backlight level                 |
-|`backlight_level(x)`   |Sets the backlight level to specified level  |
-|`get_backlight_level()`|Return the current backlight level           |
+|Function  |Description                                                |
+|----------|-----------------------------------------------------------|
+|`backlight_toggle()`    |Turn the backlight on or off                 |
+|`backlight_enable()`    |Turn the backlight on                        |
+|`backlight_disable()`   |Turn the backlight off                       |
+|`backlight_step()`      |Cycle through backlight levels               |
+|`backlight_increase()`  |Increase the backlight level                 |
+|`backlight_decrease()`  |Decrease the backlight level                 |
+|`backlight_level(x)`    |Sets the backlight level to specified level  |
+|`get_backlight_level()` |Return the current backlight level           |
+|`is_backlight_enabled()`|Return whether the backlight is currently on |
 
 ### Backlight Breathing Functions
 

docs/feature_bootmagic.md

@@ -127,7 +127,9 @@ Additionally, you may want to specify which key to use.  This is especially usef
 
 By default, these are set to 0 and 0, which is usually the "ESC" key on a majority of keyboards.
 
-And to trigger the bootloader, you hold this key down when plugging the keyboard in. Just the single key. 
+And to trigger the bootloader, you hold this key down when plugging the keyboard in. Just the single key.
+
+!> Using bootmagic lite will **always reset** the EEPROM, so you will lose any settings that have been saved.
 
 ## Advanced Bootmagic Lite
 

docs/feature_combo.md

@@ -29,7 +29,7 @@ If you want to add a list, then you'd use something like this:
 enum combos {
   AB_ESC,
   JK_TAB
-}
+};
 const uint16_t PROGMEM ab_combo[] = {KC_A, KC_B, COMBO_END};
 const uint16_t PROGMEM jk_combo[] = {KC_J, KC_K, COMBO_END};
 

docs/feature_command.md

@@ -16,35 +16,35 @@ To use Command, hold down the key combination defined by the `IS_COMMAND()` macr
 
 If you would like to change the key assignments for Command, `#define` these in your `config.h` at either the keyboard or keymap level. All keycode assignments here must omit the `KC_` prefix.
 
-|Define                              |Default                                                                               |Description                                     |
-|------------------------------------|--------------------------------------------------------------------------------------|------------------------------------------------|
-|`IS_COMMAND()`                      |<code>(keyboard_report->mods == (MOD_BIT(KC_LSHIFT) &#124; MOD_BIT(KC_RSHIFT)))</code>|The key combination to activate Command         |
-|`MAGIC_KEY_SWITCH_LAYER_WITH_FKEYS` |`true`                                                                                |Set default layer with the Function row         |
-|`MAGIC_KEY_SWITCH_LAYER_WITH_NKEYS` |`true`                                                                                |Set default layer with the number keys          |
-|`MAGIC_KEY_SWITCH_LAYER_WITH_CUSTOM`|`false`                                                                               |Set default layer with `MAGIC_KEY_LAYER0..9`    |
-|`MAGIC_KEY_DEBUG`                   |`D`                                                                                   |Toggle debugging over serial                    |
-|`MAGIC_KEY_DEBUG_MATRIX`            |`X`                                                                                   |Toggle key matrix debugging                     |
-|`MAGIC_KEY_DEBUG_KBD`               |`K`                                                                                   |Toggle keyboard debugging                       |
-|`MAGIC_KEY_DEBUG_MOUSE`             |`M`                                                                                   |Toggle mouse debugging                          |
-|`MAGIC_KEY_CONSOLE`                 |`C`                                                                                   |Enable the Command console                      |
-|`MAGIC_KEY_VERSION`                 |`V`                                                                                   |Print the running QMK version to the console    |
-|`MAGIC_KEY_STATUS`                  |`S`                                                                                   |Print the current keyboard status to the console|
-|`MAGIC_KEY_HELP1`                   |`H`                                                                                   |Print Command help to the console               |
-|`MAGIC_KEY_HELP2`                   |`SLASH`                                                                               |Print Command help to the console (alternate)   |
-|`MAGIC_KEY_LAYER0`                  |`0`                                                                                   |Make layer 0 the default layer                  |
-|`MAGIC_KEY_LAYER1`                  |`1`                                                                                   |Make layer 1 the default layer                  |
-|`MAGIC_KEY_LAYER2`                  |`2`                                                                                   |Make layer 2 the default layer                  |
-|`MAGIC_KEY_LAYER3`                  |`3`                                                                                   |Make layer 3 the default layer                  |
-|`MAGIC_KEY_LAYER4`                  |`4`                                                                                   |Make layer 4 the default layer                  |
-|`MAGIC_KEY_LAYER5`                  |`5`                                                                                   |Make layer 5 the default layer                  |
-|`MAGIC_KEY_LAYER6`                  |`6`                                                                                   |Make layer 6 the default layer                  |
-|`MAGIC_KEY_LAYER7`                  |`7`                                                                                   |Make layer 7 the default layer                  |
-|`MAGIC_KEY_LAYER8`                  |`8`                                                                                   |Make layer 8 the default layer                  |
-|`MAGIC_KEY_LAYER9`                  |`9`                                                                                   |Make layer 9 the default layer                  |
-|`MAGIC_KEY_LAYER0_ALT1`             |`ESC`                                                                                 |Make layer 0 the default layer (alternate)      |
-|`MAGIC_KEY_LAYER0_ALT2`             |`GRAVE`                                                                               |Make layer 0 the default layer (alternate)      |
-|`MAGIC_KEY_BOOTLOADER`              |`PAUSE`                                                                               |Enter the bootloader                            |
-|`MAGIC_KEY_LOCK`                    |`CAPS`                                                                                |Lock the keyboard so nothing can be typed       |
-|`MAGIC_KEY_EEPROM`                  |`E`                                                                                   |Clear the EEPROM                                |
-|`MAGIC_KEY_NKRO`                    |`N`                                                                                   |Toggle N-Key Rollover (NKRO)                    |
-|`MAGIC_KEY_SLEEP_LED`               |`Z`                                                                                   |Toggle LED when computer is sleeping            |
+|Define                              |Default                                                                    |Description                                     |
+|------------------------------------|---------------------------------------------------------------------------|------------------------------------------------|
+|`IS_COMMAND()`                      |<code>(get_mods() == (MOD_BIT(KC_LSHIFT) &#124; MOD_BIT(KC_RSHIFT)))</code>|The key combination to activate Command         |
+|`MAGIC_KEY_SWITCH_LAYER_WITH_FKEYS` |`true`                                                                     |Set default layer with the Function row         |
+|`MAGIC_KEY_SWITCH_LAYER_WITH_NKEYS` |`true`                                                                     |Set default layer with the number keys          |
+|`MAGIC_KEY_SWITCH_LAYER_WITH_CUSTOM`|`false`                                                                    |Set default layer with `MAGIC_KEY_LAYER0..9`    |
+|`MAGIC_KEY_DEBUG`                   |`D`                                                                        |Toggle debugging over serial                    |
+|`MAGIC_KEY_DEBUG_MATRIX`            |`X`                                                                        |Toggle key matrix debugging                     |
+|`MAGIC_KEY_DEBUG_KBD`               |`K`                                                                        |Toggle keyboard debugging                       |
+|`MAGIC_KEY_DEBUG_MOUSE`             |`M`                                                                        |Toggle mouse debugging                          |
+|`MAGIC_KEY_CONSOLE`                 |`C`                                                                        |Enable the Command console                      |
+|`MAGIC_KEY_VERSION`                 |`V`                                                                        |Print the running QMK version to the console    |
+|`MAGIC_KEY_STATUS`                  |`S`                                                                        |Print the current keyboard status to the console|
+|`MAGIC_KEY_HELP1`                   |`H`                                                                        |Print Command help to the console               |
+|`MAGIC_KEY_HELP2`                   |`SLASH`                                                                    |Print Command help to the console (alternate)   |
+|`MAGIC_KEY_LAYER0`                  |`0`                                                                        |Make layer 0 the default layer                  |
+|`MAGIC_KEY_LAYER1`                  |`1`                                                                        |Make layer 1 the default layer                  |
+|`MAGIC_KEY_LAYER2`                  |`2`                                                                        |Make layer 2 the default layer                  |
+|`MAGIC_KEY_LAYER3`                  |`3`                                                                        |Make layer 3 the default layer                  |
+|`MAGIC_KEY_LAYER4`                  |`4`                                                                        |Make layer 4 the default layer                  |
+|`MAGIC_KEY_LAYER5`                  |`5`                                                                        |Make layer 5 the default layer                  |
+|`MAGIC_KEY_LAYER6`                  |`6`                                                                        |Make layer 6 the default layer                  |
+|`MAGIC_KEY_LAYER7`                  |`7`                                                                        |Make layer 7 the default layer                  |
+|`MAGIC_KEY_LAYER8`                  |`8`                                                                        |Make layer 8 the default layer                  |
+|`MAGIC_KEY_LAYER9`                  |`9`                                                                        |Make layer 9 the default layer                  |
+|`MAGIC_KEY_LAYER0_ALT1`             |`ESC`                                                                      |Make layer 0 the default layer (alternate)      |
+|`MAGIC_KEY_LAYER0_ALT2`             |`GRAVE`                                                                    |Make layer 0 the default layer (alternate)      |
+|`MAGIC_KEY_BOOTLOADER`              |`PAUSE`                                                                    |Enter the bootloader                            |
+|`MAGIC_KEY_LOCK`                    |`CAPS`                                                                     |Lock the keyboard so nothing can be typed       |
+|`MAGIC_KEY_EEPROM`                  |`E`                                                                        |Clear the EEPROM                                |
+|`MAGIC_KEY_NKRO`                    |`N`                                                                        |Toggle N-Key Rollover (NKRO)                    |
+|`MAGIC_KEY_SLEEP_LED`               |`Z`                                                                        |Toggle LED when computer is sleeping            |

docs/feature_debounce_type.md

@@ -0,0 +1,46 @@
+# Debounce algorithm
+
+QMK supports multiple debounce algorithms through its debounce API.
+
+The underlying debounce algorithm is determined by which matrix.c file you are using.
+
+The logic for which debounce method called is below. It checks various defines that you have set in rules.mk
+
+```
+DEBOUNCE_TYPE?= sym_g
+VALID_DEBOUNCE_TYPES := sym_g eager_pk custom
+ifeq ($(filter $(DEBOUNCE_TYPE),$(VALID_DEBOUNCE_TYPES)),)
+    $(error DEBOUNCE_TYPE="$(DEBOUNCE_TYPE)" is not a valid debounce algorithm)
+endif
+ifeq ($(strip $(DEBOUNCE_TYPE)), sym_g)
+    QUANTUM_SRC += $(DEBOUNCE_DIR)/debounce_sym_g.c
+else ifeq ($(strip $(DEBOUNCE_TYPE)), eager_pk)
+    QUANTUM_SRC += $(DEBOUNCE_DIR)/debounce_eager_pk.c
+endif
+```
+
+# Debounce selection
+
+| DEBOUNCE_ALGO    | Description                                                 | What to do                    |
+| -------------    | ---------------------------------------------------         | ----------------------------- |
+| Not defined      | You are using the included matrix.c and debounce.c          | Nothing. Debounce_sym_g will be compiled, and used if necessary |
+| custom           | Use your own debounce.c                                     | ```SRC += debounce.c``` add your own debounce.c and implement necessary functions |
+| sym_g / eager_pk | You are using the included matrix.c and debounce.c          | Use an alternative debounce algorithm |
+
+**Regarding split keyboards**: 
+The debounce code is compatible with split keyboards.
+
+# Use your own debouncing code
+* Set ```DEBOUNCE_TYPE = custom ```.
+* Add ```SRC += debounce.c```
+* Add your own ```debounce.c```. Look at included ```debounce_sym_g.c```s for sample implementations.
+* Debouncing occurs after every raw matrix scan.
+* Use num_rows rather than MATRIX_ROWS, so that split keyboards are supported correctly.
+
+# 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:
+* debounce_eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE_DELAY``` millseconds of no further input for that key
+* debounce_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_encoders.md

@@ -13,7 +13,7 @@ and this to your `config.h`:
 Each PAD_A/B variable defines an array so multiple encoders can be defined, e.g.:
 
     #define ENCODERS_PAD_A { encoder1a, encoder2a }
-    #define ENCODERS_PAD_B { encoder1a, encoder2b }
+    #define ENCODERS_PAD_B { encoder1b, encoder2b }
 
 If your encoder's clockwise directions are incorrect, you can swap the A & B pad definitions.
 
@@ -32,15 +32,19 @@ The callback functions can be inserted into your `<keyboard>.c`:
 or `keymap.c`:
 
     void encoder_update_user(uint8_t index, bool clockwise) {
-        if (index == 0) {
-            if (clockwise) {
-                register_code(KC_PGDN);
-                unregister_code(KC_PGDN);
-            } else {
-                register_code(KC_PGUP);
-                unregister_code(KC_PGUP);
-            }
+      if (index == 0) { /* First encoder */
+        if (clockwise) {
+          tap_code(KC_PGDN);
+        } else {
+          tap_code(KC_PGUP);
         }
+      } else if (index == 1) { /* Second encoder
+        if (clockwise) {
+          tap_code(KC_UP);
+        } else {
+          tap_code(KC_DOWN);
+        }
+      }
     }
 
 ## Hardware

docs/feature_grave_esc.md

@@ -4,7 +4,11 @@ If you're using a 60% keyboard, or any other layout with no F-row, you will have
 
 ## Usage
 
-Replace the `KC_GRAVE` key in your keymap (usually to the left of the `1` key) with `KC_GESC`. When pressed it will behave like `KC_ESC`, but with Shift or GUI held it will send `KC_GRAVE`.
+Replace the `KC_GRAVE` key in your keymap (usually to the left of the `1` key) with `KC_GESC`. Most of the time this key will output `KC_ESC` when pressed. However, when Shift or GUI are held down it will output `KC_GRV` instead.
+
+## What Your OS Sees
+
+If Mary presses GESC on her keyboard, the OS will see an KC_ESC character. Now if Mary holds Shift down and presses GESC it will output `~`, or a shifted backtick. Now if she holds GUI/CMD/WIN, it will output a simple <code>&#96;</code> character.
 
 ## Keycodes
 
@@ -12,6 +16,10 @@ Replace the `KC_GRAVE` key in your keymap (usually to the left of the `1` key) w
 |---------|-----------|------------------------------------------------------------------|
 |`KC_GESC`|`GRAVE_ESC`|Escape when pressed, <code>&#96;</code> when Shift or GUI are held|
 
+### Caveats
+
+ * On macOS CMD/GUI + KC_GRV is actually mapped to a hot key so it will not output a backtick.
+
 ## Configuration
 
 There are several possible key combinations this will break, among them Control+Shift+Escape on Windows and Command+Option+Escape on macOS. To work around this, you can `#define` these options in your `config.h`: