command.h include was not set correctly

* Add EEPROM Reset keycode

* Add keycode to docs

* Move EEPROM Reset code to the end of the enum

* Cleanup and naming change

CODE_OF_CONDUCT.md

@@ -1,10 +1,10 @@
 # Code Of Conduct
 
-QMK strives to be an inclusive and tolerant community. We welcome participation from anyone regardless of age, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, political belief, race, religion, or sexual identity and orientation. 
+QMK strives to be an inclusive, tolerant, and welcoming community. We encourage participation from anyone regardless of age, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, political belief, race, religion, or sexual identity and orientation.
 
-> “A gentle word turns away wrath, but a harsh word stirs up anger.”
+> “A gentle word turns away wrath, but a harsh word stirs up anger."
 
-Our users, contributors, and collaborators are expected to treat each other with respect, to assume good intentions, and to gently correct, where possible, rather than react with escalation. Some examples of behavior we will not tolerate include, but is not limited to:
+Our users, contributors, and collaborators are expected to treat each other with kindness and respect, to assume good intentions, and to gently correct, where possible, rather than react with escalation. While our goal is to be as accurate as possible, kindness and understanding are more valuable than correctness. Some examples of behavior we will not tolerate include, but is not limited to:
 
 * The use of sexualized language or imagery
 * Unwelcome advances, sexual or otherwise

Makefile

@@ -67,7 +67,7 @@ $(eval $(call NEXT_PATH_ELEMENT))
 # It's really a very simple if else chain, if you squint enough,
 # but the makefile syntax makes it very verbose.
 # If we are in a subfolder of keyboards
-# 
+#
 # *** No longer needed **
 #
 # ifeq ($(CURRENT_PATH_ELEMENT),keyboards)
@@ -307,11 +307,6 @@ define PARSE_KEYBOARD
     KEYBOARD_FOLDER_PATH_3 := $$(patsubst %/,%,$$(dir $$(KEYBOARD_FOLDER_PATH_2)))
     KEYBOARD_FOLDER_PATH_4 := $$(patsubst %/,%,$$(dir $$(KEYBOARD_FOLDER_PATH_3)))
     KEYBOARD_FOLDER_PATH_5 := $$(patsubst %/,%,$$(dir $$(KEYBOARD_FOLDER_PATH_4)))
-    KEYBOARD_FOLDER_1 := $$(notdir $$(KEYBOARD_FOLDER_PATH_1))
-    KEYBOARD_FOLDER_2 := $$(notdir $$(KEYBOARD_FOLDER_PATH_2))
-    KEYBOARD_FOLDER_3 := $$(notdir $$(KEYBOARD_FOLDER_PATH_3))
-    KEYBOARD_FOLDER_4 := $$(notdir $$(KEYBOARD_FOLDER_PATH_4))
-    KEYBOARD_FOLDER_5 := $$(notdir $$(KEYBOARD_FOLDER_PATH_5))
 
     KEYMAPS :=
     # get a list of all keymaps
@@ -325,35 +320,35 @@ define PARSE_KEYBOARD
         $$(KEYBOARD_FOLDER_3) $$(KEYBOARD_FOLDER_4) $$(KEYBOARD_FOLDER_5), $$(KEYMAPS)))
 
     KEYBOARD_LAYOUTS :=
-    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_5)/rules.mk)","")
+    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_5)/rules.mk)","")
       LAYOUTS :=
-      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_5)/rules.mk)
+      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_5)/rules.mk)
       KEYBOARD_LAYOUTS := $$(sort $$(LAYOUTS) $$(KEYBOARD_LAYOUTS))
     endif
-    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_4)/rules.mk)","")
+    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_4)/rules.mk)","")
       LAYOUTS :=
-      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_4)/rules.mk)
+      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_4)/rules.mk)
       KEYBOARD_LAYOUTS := $$(sort $$(LAYOUTS) $$(KEYBOARD_LAYOUTS))
     endif
-    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_3)/rules.mk)","")
+    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_3)/rules.mk)","")
       LAYOUTS :=
-      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_3)/rules.mk)
+      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_3)/rules.mk)
       KEYBOARD_LAYOUTS := $$(sort $$(LAYOUTS) $$(KEYBOARD_LAYOUTS))
     endif
-    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_2)/rules.mk)","")
+    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_2)/rules.mk)","")
       LAYOUTS :=
-      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_2)/rules.mk)
+      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_2)/rules.mk)
       KEYBOARD_LAYOUTS := $$(sort $$(LAYOUTS) $$(KEYBOARD_LAYOUTS))
     endif
-    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_1)/rules.mk)","")
+    ifneq ("$$(wildcard $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_1)/rules.mk)","")
       LAYOUTS :=
-      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_1)/rules.mk)
+      $$(eval include $(ROOT_DIR)/keyboards/$$(KEYBOARD_FOLDER_PATH_1)/rules.mk)
       KEYBOARD_LAYOUTS := $$(sort $$(LAYOUTS) $$(KEYBOARD_LAYOUTS))
     endif
 
     LAYOUT_KEYMAPS :=
     $$(foreach LAYOUT,$$(KEYBOARD_LAYOUTS),$$(eval LAYOUT_KEYMAPS += $$(notdir $$(patsubst %/.,%,$$(wildcard $(ROOT_DIR)/layouts/*/$$(LAYOUT)/*/.)))))
-    
+
     KEYMAPS := $$(sort $$(KEYMAPS) $$(LAYOUT_KEYMAPS))
 
     # if the rule after removing the start of it is empty (we haven't specified a kemap or target)
@@ -583,7 +578,7 @@ lib/%:
 
 git-submodule:
 	git submodule sync --recursive
-	git submodule update --init --recursive
+	git submodule update --init --recursive --progress
 
 ifdef SKIP_VERSION
 SKIP_GIT := yes

Vagrantfile

@@ -2,27 +2,8 @@
 # vi: set ft=ruby :
 
 Vagrant.configure(2) do |config|
-  # You can only have one config.vm.box uncommented at a time
-
-  # Comment this and uncomment another if you don't want to use the minimal Arch box
-  #config.vm.box = "dragon788/arch-ala-elasticdog"
-
   # VMware/Virtualbox 64 bit
   config.vm.box = "phusion/ubuntu-14.04-amd64"
-  #
-  # VMware/Virtualbox 64 bit
-  #config.vm.box = "puphpet/centos65-x64"
-  #
-  # The opensuse boxes don't have dfu-util in their default repositories
-  #
-  # The virtualbox version has tools issues
-  # VMware/Virtualbox 64 bit
-  #config.vm.box = "bento/opensuse-13.2-x86_64"
-  #
-  # Virtualbox only
-  #config.vm.box = "bento/opensuse-13.2-i386"
-  # config.vm.box = ""
-  # config.vm.box = ""
 
   # This section allows you to customize the Virtualbox VM
   # settings, ie showing the GUI or upping the memory
@@ -78,21 +59,19 @@ Vagrant.configure(2) do |config|
   # add a # before ,args: and run 'vagrant up' to get a working
   # non-updated box and then attempt to troubleshoot or open a Github issue
 
-  config.vm.provision "shell", run: "always", path: "./util/install_dependencies.sh", args: "-update"
+  config.vm.provision "shell", run: "always", path: "./util/qmk_install.sh", args: "-update"
 
   config.vm.post_up_message = <<-EOT
-  Log into the VM using 'vagrant ssh' on OSX or from Git Bash (Win)
-  or 'vagrant ssh-config' and Putty or Bitvise SSH or another SSH tool
 
-  Change directory (cd) to the keyboard you wish to program
-  (Optionally) modify your layout,
-  then run 'make clean'
-  and then 'make' to compile the .eep and .hex files.
-
-  Or you can copy and paste the example line below.
-
-  cd /vagrant; cd keyboards; cd ergodox; make clean; make
+  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.
 
+  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
 
   EOT
 end

build_keyboard.mk

@@ -1,3 +1,9 @@
+# Determine what keyboard we are building and setup the build environment.
+#
+# We support folders up to 5 levels deep below `keyboards/`. This file is
+# responsible for determining which folder is being used and doing the
+# corresponding environment setup.
+
 ifndef VERBOSE
 .SILENT:
 endif
@@ -6,26 +12,15 @@ endif
 
 include common.mk
 
-# 5/4/3/2/1
-KEYBOARD_FOLDER_PATH_1 := $(KEYBOARD)
-KEYBOARD_FOLDER_PATH_2 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_1)))
-KEYBOARD_FOLDER_PATH_3 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_2)))
-KEYBOARD_FOLDER_PATH_4 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_3)))
-KEYBOARD_FOLDER_PATH_5 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_4)))
-KEYBOARD_FOLDER_1 := $(notdir $(KEYBOARD_FOLDER_PATH_1))
-KEYBOARD_FOLDER_2 := $(notdir $(KEYBOARD_FOLDER_PATH_2))
-KEYBOARD_FOLDER_3 := $(notdir $(KEYBOARD_FOLDER_PATH_3))
-KEYBOARD_FOLDER_4 := $(notdir $(KEYBOARD_FOLDER_PATH_4))
-KEYBOARD_FOLDER_5 := $(notdir $(KEYBOARD_FOLDER_PATH_5))
-
+# Set the filename for the final firmware binary
 KEYBOARD_FILESAFE := $(subst /,_,$(KEYBOARD))
-
 TARGET ?= $(KEYBOARD_FILESAFE)_$(KEYMAP)
 KEYBOARD_OUTPUT := $(BUILD_DIR)/obj_$(KEYBOARD_FILESAFE)
 
 # Force expansion
 TARGET := $(TARGET)
 
+# For split boards we need to set a master half.
 MASTER ?= left
 ifdef master
     MASTER = $(master)
@@ -39,35 +34,58 @@ $(error MASTER does not have a valid value(left/right))
     endif
 endif
 
+# Determine which subfolders exist.
+KEYBOARD_FOLDER_PATH_1 := $(KEYBOARD)
+KEYBOARD_FOLDER_PATH_2 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_1)))
+KEYBOARD_FOLDER_PATH_3 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_2)))
+KEYBOARD_FOLDER_PATH_4 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_3)))
+KEYBOARD_FOLDER_PATH_5 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_4)))
+KEYBOARD_FOLDER_1 := $(notdir $(KEYBOARD_FOLDER_PATH_1))
+KEYBOARD_FOLDER_2 := $(notdir $(KEYBOARD_FOLDER_PATH_2))
+KEYBOARD_FOLDER_3 := $(notdir $(KEYBOARD_FOLDER_PATH_3))
+KEYBOARD_FOLDER_4 := $(notdir $(KEYBOARD_FOLDER_PATH_4))
+KEYBOARD_FOLDER_5 := $(notdir $(KEYBOARD_FOLDER_PATH_5))
 KEYBOARD_PATHS :=
-
 KEYBOARD_PATH_1 := keyboards/$(KEYBOARD_FOLDER_PATH_1)
 KEYBOARD_PATH_2 := keyboards/$(KEYBOARD_FOLDER_PATH_2)
 KEYBOARD_PATH_3 := keyboards/$(KEYBOARD_FOLDER_PATH_3)
 KEYBOARD_PATH_4 := keyboards/$(KEYBOARD_FOLDER_PATH_4)
 KEYBOARD_PATH_5 := keyboards/$(KEYBOARD_FOLDER_PATH_5)
 
-ifneq ("$(wildcard $(KEYBOARD_PATH_5)/rules.mk)","")
+ifneq ("$(wildcard $(KEYBOARD_PATH_5)/)","")
     KEYBOARD_PATHS += $(KEYBOARD_PATH_5)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_4)/)","")
+    KEYBOARD_PATHS += $(KEYBOARD_PATH_4)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_3)/)","")
+    KEYBOARD_PATHS += $(KEYBOARD_PATH_3)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_2)/)","")
+    KEYBOARD_PATHS += $(KEYBOARD_PATH_2)
+endif
+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
 endif
 ifneq ("$(wildcard $(KEYBOARD_PATH_4)/rules.mk)","")
-    KEYBOARD_PATHS += $(KEYBOARD_PATH_4)
     include $(KEYBOARD_PATH_4)/rules.mk
 endif
 ifneq ("$(wildcard $(KEYBOARD_PATH_3)/rules.mk)","")
-    KEYBOARD_PATHS += $(KEYBOARD_PATH_3)
     include $(KEYBOARD_PATH_3)/rules.mk
 endif
 ifneq ("$(wildcard $(KEYBOARD_PATH_2)/rules.mk)","")
-    KEYBOARD_PATHS += $(KEYBOARD_PATH_2)
     include $(KEYBOARD_PATH_2)/rules.mk
 endif
 ifneq ("$(wildcard $(KEYBOARD_PATH_1)/rules.mk)","")
-    KEYBOARD_PATHS += $(KEYBOARD_PATH_1)
     include $(KEYBOARD_PATH_1)/rules.mk
 endif
 
+# Find all the C source files to be compiled in subfolders.
 KEYBOARD_SRC :=
 
 KEYBOARD_C_1 := $(KEYBOARD_PATH_1)/$(KEYBOARD_FOLDER_1).c
@@ -92,9 +110,38 @@ ifneq ("$(wildcard $(KEYBOARD_C_1))","")
     KEYBOARD_SRC += $(KEYBOARD_C_1)
 endif
 
-OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE)
+# Generate KEYBOARD_name_subname for all levels of the keyboard folder
+KEYBOARD_FILESAFE_1 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_1)))
+KEYBOARD_FILESAFE_2 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_2)))
+KEYBOARD_FILESAFE_3 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_3)))
+KEYBOARD_FILESAFE_4 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_4)))
+KEYBOARD_FILESAFE_5 := $(subst .,,$(subst /,_,$(KEYBOARD_FOLDER_PATH_5)))
 
+ifneq ("$(wildcard $(KEYBOARD_PATH_5)/)","")
+    OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_5)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_4)/)","")
+    OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_4)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_3)/)","")
+    OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_3)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_2)/)","")
+    OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_2)
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_1)/)","")
+    OPT_DEFS += -DKEYBOARD_$(KEYBOARD_FILESAFE_1)
+endif
 
+# Setup the define for QMK_KEYBOARD_H. This is used inside of keymaps so
+# that the same keymap may be used on multiple keyboards.
+#
+# We grab the most top-level include file that we can. That file should
+# use #ifdef statements to include all the neccesary subfolder includes,
+# as described here:
+#
+#    https://docs.qmk.fm/#/feature_layouts?id=tips-for-making-layouts-keyboard-agnostic
+#
 ifneq ("$(wildcard $(KEYBOARD_PATH_1)/$(KEYBOARD_FOLDER_1).h)","")
     QMK_KEYBOARD_H = $(KEYBOARD_FOLDER_1).h
 endif
@@ -111,13 +158,18 @@ ifneq ("$(wildcard $(KEYBOARD_PATH_5)/$(KEYBOARD_FOLDER_5).h)","")
     QMK_KEYBOARD_H = $(KEYBOARD_FOLDER_5).h
 endif
 
-# We can assume a ChibiOS target When MCU_FAMILY is defined , since it's not used for LUFA
+# Determine and set parameters based on the keyboard's processor family.
+# We can assume a ChibiOS target When MCU_FAMILY is defined since it's
+# not used for LUFA
 ifdef MCU_FAMILY
-    FIRMWARE_FORMAT=bin
+    FIRMWARE_FORMAT?=bin
     PLATFORM=CHIBIOS
+else ifdef ARM_ATSAM
+    PLATFORM=ARM_ATSAM
+    FIRMWARE_FORMAT=bin
 else
     PLATFORM=AVR
-    FIRMWARE_FORMAT=hex
+    FIRMWARE_FORMAT?=hex
 endif
 
 ifeq ($(PLATFORM),CHIBIOS)
@@ -148,6 +200,7 @@ ifeq ($(PLATFORM),CHIBIOS)
     endif
 endif
 
+# Find all of the config.h files and add them to our CONFIG_H define.
 CONFIG_H :=
 ifneq ("$(wildcard $(KEYBOARD_PATH_5)/config.h)","")
     CONFIG_H += $(KEYBOARD_PATH_5)/config.h
@@ -203,7 +256,7 @@ else
     # this state should never be reached
 endif
 
-# User space stuff
+# Userspace setup and definitions
 ifeq ("$(USER_NAME)","")
     USER_NAME := $(KEYMAP)
 endif
@@ -256,6 +309,11 @@ endif
     include $(TMK_PATH)/avr.mk
 endif
 
+ifeq ($(PLATFORM),ARM_ATSAM)
+    include $(TMK_PATH)/arm_atsam.mk
+    include $(TMK_PATH)/protocol/arm_atsam.mk
+endif
+
 ifeq ($(PLATFORM),CHIBIOS)
     include $(TMK_PATH)/protocol/chibios.mk
 endif
@@ -283,11 +341,6 @@ $(KEYBOARD_OUTPUT)_CONFIG := $(PROJECT_CONFIG)
 
 # Default target.
 all: build check-size
-
-# Change the build target to build a HEX file or a library.
 build: elf cpfirmware
-#build: elf hex eep lss sym
-#build: lib
-
 
 include $(TMK_PATH)/rules.mk

common.mk

@@ -3,16 +3,16 @@ include message.mk
 # Directory common source files exist
 TOP_DIR = .
 TMK_DIR = tmk_core
-TMK_PATH = $(TOP_DIR)/$(TMK_DIR)
-LIB_PATH = $(TOP_DIR)/lib
+TMK_PATH = $(TMK_DIR)
+LIB_PATH = lib
 
 QUANTUM_DIR = quantum
-QUANTUM_PATH = $(TOP_DIR)/$(QUANTUM_DIR)
+QUANTUM_PATH = $(QUANTUM_DIR)
 
 DRIVER_DIR = drivers
-DRIVER_PATH = $(TOP_DIR)/$(DRIVER_DIR)
+DRIVER_PATH = $(DRIVER_DIR)
 
-BUILD_DIR := $(TOP_DIR)/.build
+BUILD_DIR := .build
 
 COMMON_VPATH := $(TOP_DIR)
 COMMON_VPATH += $(TMK_PATH)
@@ -21,4 +21,5 @@ COMMON_VPATH += $(QUANTUM_PATH)/keymap_extras
 COMMON_VPATH += $(QUANTUM_PATH)/audio
 COMMON_VPATH += $(QUANTUM_PATH)/process_keycode
 COMMON_VPATH += $(QUANTUM_PATH)/api
-COMMON_VPATH += $(DRIVER_PATH)
+COMMON_VPATH += $(QUANTUM_PATH)/split_common
+COMMON_VPATH += $(DRIVER_PATH)

common_features.mk

@@ -61,8 +61,8 @@ endif
 
 ifeq ($(strip $(STENO_ENABLE)), yes)
     OPT_DEFS += -DSTENO_ENABLE
-	VIRTSER_ENABLE := yes
-	SRC += $(QUANTUM_DIR)/process_keycode/process_steno.c
+    VIRTSER_ENABLE := yes
+    SRC += $(QUANTUM_DIR)/process_keycode/process_steno.c
 endif
 
 ifeq ($(strip $(VIRTSER_ENABLE)), yes)
@@ -75,9 +75,9 @@ ifeq ($(strip $(FAUXCLICKY_ENABLE)), yes)
 endif
 
 ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
-	OPT_DEFS += -DPOINTING_DEVICE_ENABLE
-	OPT_DEFS += -DMOUSE_ENABLE
-	SRC += $(QUANTUM_DIR)/pointing_device.c
+    OPT_DEFS += -DPOINTING_DEVICE_ENABLE
+    OPT_DEFS += -DMOUSE_ENABLE
+    SRC += $(QUANTUM_DIR)/pointing_device.c
 endif
 
 ifeq ($(strip $(UCIS_ENABLE)), yes)
@@ -110,19 +110,41 @@ ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
     ifeq ($(strip $(RGBLIGHT_CUSTOM_DRIVER)), yes)
         OPT_DEFS += -DRGBLIGHT_CUSTOM_DRIVER
     else
-	    SRC += ws2812.c
+        SRC += ws2812.c
     endif
 endif
 
-ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
+RGB_MATRIX_ENABLE ?= no
+VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 custom
+ifneq ($(strip $(RGB_MATRIX_ENABLE)), no)
+ifeq ($(filter $(RGB_MATRIX_ENABLE),$(VALID_MATRIX_TYPES)),)
+    $(error RGB_MATRIX_ENABLE="$(RGB_MATRIX_ENABLE)" is not a valid matrix type)
+endif
     OPT_DEFS += -DRGB_MATRIX_ENABLE
-    SRC += is31fl3731.c
-    SRC += i2c_master.c
     SRC += $(QUANTUM_DIR)/color.c
     SRC += $(QUANTUM_DIR)/rgb_matrix.c
+    SRC += $(QUANTUM_DIR)/rgb_matrix_drivers.c
     CIE1931_CURVE = yes
 endif
 
+ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
+	RGB_MATRIX_ENABLE = IS31FL3731
+endif
+
+ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3731)
+    OPT_DEFS += -DIS31FL3731
+    COMMON_VPATH += $(DRIVER_PATH)/issi
+    SRC += is31fl3731.c
+    SRC += i2c_master.c
+endif
+
+ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3733)
+    OPT_DEFS += -DIS31FL3733
+    COMMON_VPATH += $(DRIVER_PATH)/issi
+    SRC += is31fl3733.c
+    SRC += i2c_master.c
+endif
+
 ifeq ($(strip $(TAP_DANCE_ENABLE)), yes)
     OPT_DEFS += -DTAP_DANCE_ENABLE
     SRC += $(QUANTUM_DIR)/process_keycode/process_tap_dance.c
@@ -169,7 +191,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
@@ -191,18 +213,50 @@ endif
 ifeq ($(strip $(TERMINAL_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/process_keycode/process_terminal.c
     OPT_DEFS += -DTERMINAL_ENABLE
+    OPT_DEFS += -DUSER_PRINT
 endif
 
 ifeq ($(strip $(USB_HID_ENABLE)), yes)
     include $(TMK_DIR)/protocol/usb_hid.mk
 endif
 
+ifeq ($(strip $(ENCODER_ENABLE)), yes)
+    SRC += $(QUANTUM_DIR)/encoder.c
+    OPT_DEFS += -DENCODER_ENABLE
+endif
+
+ifeq ($(strip $(HD44780_ENABLE)), yes)
+    SRC += drivers/avr/hd44780.c
+    OPT_DEFS += -DHD44780_ENABLE
+endif
+
+ifeq ($(strip $(DYNAMIC_KEYMAP_ENABLE)), yes)
+    OPT_DEFS += -DDYNAMIC_KEYMAP_ENABLE
+    SRC += $(QUANTUM_DIR)/dynamic_keymap.c
+endif
+
+ifeq ($(strip $(LEADER_ENABLE)), yes)
+  SRC += $(QUANTUM_DIR)/process_keycode/process_leader.c
+  OPT_DEFS += -DLEADER_ENABLE
+endif
+
 QUANTUM_SRC:= \
     $(QUANTUM_DIR)/quantum.c \
     $(QUANTUM_DIR)/keymap_common.c \
-    $(QUANTUM_DIR)/keycode_config.c \
-    $(QUANTUM_DIR)/process_keycode/process_leader.c
+    $(QUANTUM_DIR)/keycode_config.c
 
-ifndef CUSTOM_MATRIX
-    QUANTUM_SRC += $(QUANTUM_DIR)/matrix.c
+ifneq ($(strip $(CUSTOM_MATRIX)), yes)
+    ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
+        QUANTUM_SRC += $(QUANTUM_DIR)/split_common/matrix.c
+    else
+        QUANTUM_SRC += $(QUANTUM_DIR)/matrix.c
+    endif
+endif
+
+ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
+    OPT_DEFS += -DSPLIT_KEYBOARD
+    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
 endif

docs/_sidebar.md

@@ -1,18 +1,16 @@
-* [Getting Started](README.md)
-  * [QMK Introduction](getting_started_introduction.md)
-  * [Install Build Tools](getting_started_build_tools.md)
-    * Alternative: [Vagrant Guide](getting_started_vagrant.md)
-  * [Build/Compile Instructions](getting_started_make_guide.md)
-  * [Flashing Firmware](flashing.md)
-  * [Contributing to QMK](contributing.md)
-  * [How to Use Github](getting_started_github.md)
-  * [Getting Help](getting_started_getting_help.md)
-
 * [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)
@@ -20,32 +18,54 @@
   * [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)
-  * [Keyboard Guidelines](hardware_keyboard_guidelines.md)
   * [AVR Processors](hardware_avr.md)
-  * ARM Processors (TBD)
   * [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.md)
-  * [Space Cadet Shift Enter](feature_space_shift_cadet.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)
@@ -53,35 +73,12 @@
   * [Thermal Printer](feature_thermal_printer.md)
   * [Unicode](feature_unicode.md)
   * [Userspace](feature_userspace.md)
-
-* [Keycodes](keycodes.md)
-  * [Backlight](feature_backlight.md#backlight-keycodes)
-  * [Basic](keycodes_basic.md)
-  * [Bluetooth](feature_bluetooth.md#bluetooth-keycodes)
-  * [Bootmagic](feature_bootmagic.md#bootmagic-keycodes)
-  * [Layer Switching](feature_advanced_keycodes.md#switching-and-toggling-layers)
-  * [Mod+Key](feature_advanced_keycodes.md#modifier-keys)
-  * [Mod Tap](feature_advanced_keycodes.md#mod-tap)
-  * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
-  * [Quantum](quantum_keycodes.md)
-  * [RGB Light](feature_rgblight.md#rgblight-keycodes)
-  * [Shifted Keys](feature_advanced_keycodes.md#shifted-keycodes)
-  * [Stenography](feature_stenography.md#keycode-reference)
-  * [Thermal Printer](feature_thermal_printer.md#thermal-printer-keycodes)
   * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
 
-* Reference
-  * [Config Options](config_options.md)
-  * [Customizing Functionality](custom_quantum_functions.md)
-  * [Documentation Best Practices](documentation_best_practices.md)
-  * [Documentation Templates](documentation_templates.md)
-  * [Glossary](reference_glossary.md)
-  * [Keymap Overview](keymap.md)
-  * [Unit Testing](unit_testing.md)
-
 * For Makers and Modders
   * [Hand Wiring Guide](hand_wire.md)
   * [ISP Flashing Guide](isp_flashing_guide.md)
+  * [ARM Debugging Guide](arm_debugging.md)
 
 * For a Deeper Understanding
   * [How Keyboards Work](how_keyboards_work.md)

docs/_summary.md

@@ -1,18 +1,16 @@
-* [Getting Started](README.md)
-  * [QMK Introduction](getting_started_introduction.md)
-  * [Install Build Tools](getting_started_build_tools.md)
-    * Alternative: [Vagrant Guide](getting_started_vagrant.md)
-  * [Build/Compile Instructions](getting_started_make_guide.md)
-  * [Flashing Firmware](flashing.md)
-  * [Contributing to QMK](contributing.md)
-  * [How to Use Github](getting_started_github.md)
-  * [Getting Help](getting_started_getting_help.md)
-
 * [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)
@@ -20,30 +18,54 @@
   * [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)
-  * [Keyboard Guidelines](hardware_keyboard_guidelines.md)
   * [AVR Processors](hardware_avr.md)
-  * ARM Processors (TBD)
   * [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)
-  * [Space Cadet](feature_space_cadet.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)
@@ -51,35 +73,12 @@
   * [Thermal Printer](feature_thermal_printer.md)
   * [Unicode](feature_unicode.md)
   * [Userspace](feature_userspace.md)
-
-* [Keycodes](keycodes.md)
-  * [Backlight](feature_backlight.md#backlight-keycodes)
-  * [Basic](keycodes_basic.md)
-  * [Bluetooth](feature_bluetooth.md#bluetooth-keycodes)
-  * [Bootmagic](feature_bootmagic.md#bootmagic-keycodes)
-  * [Layer Switching](feature_advanced_keycodes.md#switching-and-toggling-layers)
-  * [Mod+Key](feature_advanced_keycodes.md#modifier-keys)
-  * [Mod Tap](feature_advanced_keycodes.md#mod-tap)
-  * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
-  * [Quantum](quantum_keycodes.md)
-  * [RGB Light](feature_rgblight.md#rgblight-keycodes)
-  * [Shifted Keys](feature_advanced_keycodes.md#shifted-keycodes)
-  * [Stenography](feature_stenography.md#keycode-reference)
-  * [Thermal Printer](feature_thermal_printer.md#thermal-printer-keycodes)
   * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
 
-* Reference
-  * [Config Options](config_options.md)
-  * [Customizing Functionality](custom_quantum_functions.md)
-  * [Documentation Best Practices](documentation_best_practices.md)
-  * [Documentation Templates](documentation_templates.md)
-  * [Glossary](reference_glossary.md)
-  * [Keymap Overview](keymap.md)
-  * [Unit Testing](unit_testing.md)
-
 * For Makers and Modders
   * [Hand Wiring Guide](hand_wire.md)
   * [ISP Flashing Guide](isp_flashing_guide.md)
+  * [ARM Debugging Guide](arm_debugging.md)
 
 * For a Deeper Understanding
   * [How Keyboards Work](how_keyboards_work.md)

docs/arm_debugging.md

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

docs/becoming_a_qmk_collaborator.md

@@ -1,7 +1,9 @@
-A QMK collaborator is a keyboard maker/designer that is interested in helping QMK grow and fully support their keyboard(s), and encouraging their users/customers to submit features, ideas, and keymaps. We're always looking to add more keyboards and collaborators, but we ask that they fulfill these requirements:
+# Becoming a QMK Collaborator
 
-* **Have a PCB available for sale** - unfortunately there's just too much variation and complications with handwired keyboards.
-* **Maintain the your keyboard's directory** - this may just require an initial setup to get your keyboard working, but it could also include accommodating changes made to QMK's core.
-* **Approve and merge your keyboard's keymap pull requests** - we like to encourage users to contribute their keymaps for others to see and work from when creating their own.
+A QMK collaborator is a keyboard maker or designer that is interested in helping QMK grow and fully support their keyboard(s), and encouraging their users and customers to submit features, ideas, and keymaps. We're always looking to add more keyboards and collaborators, but we ask that they fulfill these requirements:
+
+* **Have a PCB available for sale.** Unfortunately there's just too much variation and complications with handwired keyboards.
+* **Maintain your keyboard in QMK.** This may just require an initial setup to get your keyboard working, but it could also include accommodating changes made to QMK's core that might break or render any custom code redundant.
+* **Approve and merge keymap pull requests for your keyboard.** We like to encourage users to contribute their keymaps for others to see and work from when creating their own.
 
 If you feel you meet these requirements, shoot us an email at hello@qmk.fm with an introduction and some links to your keyboard!

docs/config_options.md

@@ -91,6 +91,8 @@ This is a C header file that is one of the first things included, and will persi
   * 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)
+* `#define SCL_CLOCK 100000L`
+  * sets the SCL_CLOCK speed for split keyboards. The default is `100000L` but some boards can be set to `400000L`.
 
 ## Features That Can Be Disabled
 
@@ -117,27 +119,34 @@ If you define these options you will enable the associated feature, which may in
 
 * `#define FORCE_NKRO`
   * NKRO by default requires to be turned on, this forces it on during keyboard startup regardless of EEPROM setting. NKRO can still be turned off but will be turned on again if the keyboard reboots.
-* `#define PREVENT_STUCK_MODIFIERS`
-  * stores the layer a key press came from so the same layer is used when the key is released, regardless of which layers are enabled
+* `#define STRICT_LAYER_RELEASE`
+  * force a key release to be evaluated using the current layer stack instead of remembering which layer it came from (used for advanced cases)
 
 ## Behaviors That Can Be Configured
 
 * `#define TAPPING_TERM 200`
-  * how long before a tap becomes a hold
+  * 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 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
 * `#define TAPPING_TOGGLE 2`
   * how many taps before triggering the toggle
 * `#define PERMISSIVE_HOLD`
-  * makes tap and hold keys work better for fast typers who don't want tapping term set above 500
+  * makes tap and hold keys trigger the hold if another key is pressed before releasing, even if it hasn't hit the `TAPPING_TERM`
+  * See [Permissive Hold](feature_advanced_keycodes.md#permissive-hold) for details
+* `#define IGNORE_MOD_TAP_INTERRUPT`
+  * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold, by enforcing the `TAPPING_TERM` for both keys.
+  * See [Mod tap interrupt](feature_advanced_keycodes.md#ignore-mod-tap-interrupt) for details
+* `#define TAPPING_FORCE_HOLD`
+  * makes it possible to use a dual role key as modifier shortly after having been tapped
+  * See [Hold after tap](feature_advanced_keycodes.md#tapping-force-hold)
+  * Breaks any Tap Toggle functionality (`TT` or the One Shot Tap Toggle)
 * `#define LEADER_TIMEOUT 300`
   * how long before the leader key times out
 * `#define ONESHOT_TIMEOUT 300`
   * how long before oneshot times out
 * `#define ONESHOT_TAP_TOGGLE 2`
   * how many taps before oneshot toggle is triggered
-* `#define IGNORE_MOD_TAP_INTERRUPT`
-  * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold
 * `#define QMK_KEYS_PER_SCAN 4`
   * Allows sending more than one key per scan. By default, only one key event gets
     sent via `process_record()` per scan. This has little impact on most typing, but
@@ -147,6 +156,10 @@ If you define these options you will enable the associated feature, which may in
     going to produce the 500 keystrokes a second needed to actually get more than a
     few ms of delay from this. But if you're doing chording on something with 3-4ms
     scan times? You probably want this.
+* `#define COMBO_COUNT 2`
+  * Set this to the number of combos that you're using in the [Combo](feature_combo.md) feature.
+* `#define COMBO_TERM 200`
+  * how long for the Combo keys to be detected. Defaults to `TAPPING_TERM` if not defined.
 
 ## RGB Light Configuration
 
@@ -173,6 +186,16 @@ If you define these options you will enable the associated feature, which may in
 * `#define MOUSEKEY_MAX_SPEED 7`
 * `#define MOUSEKEY_WHEEL_DELAY 0`
 
+## Split Keyboard Options
+
+Split Keyboard specific options, make sure you have 'SPLIT_KEYBOARD = yes' in your rules.mk
+
+* `#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.
+  
+* `#define USE_I2C`
+  * For using I2C instead of Serial (defaults to serial)
+
 # 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.
@@ -181,6 +204,8 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
 
 * `DEFAULT_FOLDER`
   * Used to specify a default folder when a keyboard has more than one sub-folder.
+* `FIRMWARE_FORMAT`
+  * Defines which format (bin, hex) is copied to the root `qmk_firmware` folder after building.
 * `SRC`
   * Used to add files to the compilation/linking list.
 * `LAYOUTS`
@@ -214,6 +239,8 @@ Use these to enable or disable building certain features. The more you have enab
   * Console for debug(+400)
 * `COMMAND_ENABLE`
   * Commands for debug and configuration
+* `COMBO_ENABLE`
+  * Key combo feature
 * `NKRO_ENABLE`
   * USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
 * `AUDIO_ENABLE`
@@ -225,4 +252,12 @@ Use these to enable or disable building certain features. The more you have enab
 * `UNICODE_ENABLE`
   * Unicode
 * `BLUETOOTH_ENABLE`
-  * Enable Bluetooth with the Adafruit EZ-Key HID
+  * Legacy option to Enable Bluetooth with the Adafruit EZ-Key HID. See BLUETOOTH
+* `BLUETOOTH`
+  * Current options are AdafruitEzKey, AdafruitBLE, RN42
+* `SPLIT_KEYBOARD`
+  * Enables split keyboard support (dual MCU like the let's split and bakingpy's boards) and includes all necessary files located at quantum/split_common
+* `WAIT_FOR_USB`
+  * Forces the keyboard to wait for a USB connection to be established before it starts up
+* `NO_USB_STARTUP_CHECK`
+  * Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master.

docs/contributing.md

@@ -11,7 +11,7 @@ Third-party contributions help us grow and improve QMK. We want to make the pull
 
 ## I Don't Want to Read This Whole Thing! I Just Have a Question!
 
-If you'd like to ask questions about QMK you can do so on the [OLKB Subreddit](https://reddit.com/r/olkb) or on [Gitter](https://gitter.im/qmk/qmk_firmware).
+If you'd like to ask questions about QMK you can do so on the [OLKB Subreddit](https://reddit.com/r/olkb) or on [Discord](https://discord.gg/Uq7gcHh).
 
 Please keep these things in mind:
 
@@ -29,7 +29,7 @@ QMK is largely written in C, with specific features and parts written in C++. It
 
 # Where Can I Go for Help?
 
-If you need help you can [open an issue](https://github.com/qmk/qmk_firmware/issues) or [chat on gitter](http://gitter.im/QMK/qmk_firmware).
+If you need help you can [open an issue](https://github.com/qmk/qmk_firmware/issues) or [chat on Discord](https://discord.gg/Uq7gcHh).
 
 # How Do I Make a Contribution?
 
@@ -57,19 +57,39 @@ Never made an open source contribution before? Wondering how contributions work
 Most of our style is pretty easy to pick up on, but right now it's not entirely consistent. You should match the style of the code surrounding your change, but if that code is inconsistent or unclear use the following guidelines:
 
 * We indent using two spaces (soft tabs)
-* We use One True Brace Style
+* We use a modified One True Brace Style
   * Opening Brace: At the end of the same line as the statement that opens the block
   * Closing Brace: Lined up with the first character of the statement that opens the block
   * Else If: Place the closing brace at the beginning of the line and the next opening brace at the end of the same line.
   * Optional Braces: Always include optional braces.
     * Good: if (condition) { return false; }
     * Bad: if (condition) return false;
-* We use C style comments: `/* */`
+* We encourage use of C style comments: `/* */`
   * Think of them as a story describing the feature
   * Use them liberally to explain why particular decisions were made.
   * Do not write obvious comments
   * If you not sure if a comment is obvious, go ahead and include it.
 * In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns.
+* We use `#pragma once` at the start of header files rather than old-style include guards (`#ifndef THIS_FILE_H`, `#define THIS_FILE_H`, ..., `#endif`)
+
+Here is an example for easy reference:
+
+```c
+/* Enums for foo */
+enum foo_state {
+  FOO_BAR,
+  FOO_BAZ,
+};
+
+/* Returns a value */
+int foo(void) {
+  if (some_condition) {
+    return FOO_BAR;
+  } else {
+    return -1;
+  }
+}
+```
 
 # General Guidelines
 
@@ -124,7 +144,7 @@ We also ask that you follow these guidelines:
 
 Before you put a lot of work into building your new feature you should make sure you are implementing it in the best way. You can get a basic understanding of QMK by reading [Understanding QMK](understanding_qmk.md), which will take you on a tour of the QMK program flow. From here you should talk to us to get a sense of the best way to implement your idea. There are two main ways to do this:
 
-* [Chat on Gitter](https://gitter.im/qmk/qmk_firmware)
+* [Chat on Discord](https://discord.gg/Uq7gcHh)
 * [Open an Issue](https://github.com/qmk/qmk_firmware/issues/new)
 
 Feature and Bug Fix PR's affect all keyboards. We are also in the process of restructuring QMK. For this reason it is especially important for significant changes to be discussed before implementation has happened. If you open a PR without talking to us first please be prepared to do some significant rework if your choices do not mesh well with our planned direction.

docs/custom_quantum_functions.md

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

docs/documentation_templates.md

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

docs/faq_build.md

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

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/9ce023dc6caadc0cf11c88c782350a8c -->
-![Keyboard Layout Image](https://i.imgur.com/45m4mRf.png)
+<!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/070a530eedaed36a2d77f3f6fd455677 -->
+![Keyboard Layout Image](https://i.imgur.com/gvlNUpQ.png)
 
 ## Some Of My Keys Are Swapped Or Not Working
 
@@ -34,12 +34,11 @@ See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and
 * http://en.wikipedia.org/wiki/Magic_SysRq_key
 * http://en.wikipedia.org/wiki/System_request
 
-## Power Key Doesn't Work
-Use `KC_PWR` instead of `KC_POWER` or vice versa.
-* `KC_PWR` works with Windows and Linux, not with OSX.
-* `KC_POWER` works with OSX and Linux, not with Windows.
+## Power Keys Aren't Working
 
-More info: http://geekhack.org/index.php?topic=14290.msg1327264#msg1327264
+Somewhat confusingly, there are two "Power" keycodes in QMK: `KC_POWER` in the Keyboard/Keypad HID usage page, and `KC_SYSTEM_POWER` (or `KC_PWR`) in the Consumer page.
+
+The former is only recognized on macOS, while the latter, `KC_SLEP` and `KC_WAKE` are supported by all three major operating systems, so it is recommended to use those instead. Under Windows, these keys take effect immediately, however on macOS they must be held down until a dialog appears.
 
 ## One Shot Modifier
 Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'.  One Shot Shift mitigates this for me.
@@ -87,14 +86,14 @@ On **Xorg** you can use `compose` key, instead.
 And see this for **Unicode** input.
 * http://en.wikipedia.org/wiki/Unicode_input
 
+## `Fn` Key on macOS
 
-## Apple/Mac Keyboard `Fn`
-Not supported.
+Unlike most Fn keys, the one on Apple keyboards actually has its own keycode... sort of. It takes the place of the sixth keycode in a basic 6KRO HID report -- so an Apple keyboard is in fact only 5KRO.
 
-Apple/Mac keyboard sends keycode for Fn unlike most of other keyboards.
-I think you can send Apple Fn key using Apple venter specific Page 0xff01 and usage 0x0003. But you have to change HID Report Descriptor for this, of course.
+It is technically possible to get QMK to send this key. However, doing so requires modification of the report format to add the state of the Fn key.
+Even worse, it is not recognized unless the keyboard's VID and PID match that of a real Apple keyboard. The legal issues that official QMK support for this feature may create mean it is unlikely to happen.
 
-https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/AppleHIDUsageTables.h
+See [this issue](https://github.com/qmk/qmk_firmware/issues/2179) for detailed information.
 
 
 ## Media Control Keys in Mac OSX

docs/feature_advanced_keycodes.md

@@ -1,8 +1,8 @@
 # Advanced Keycodes
 
-Your keymap can include keycodes that are more advanced than normal, for example shifted keys. This page documents the functions that are available to you.
+Your keymap can include keycodes that are more advanced than normal, for example keys that switch layers or send modifiers when held, but send regular keycodes when tapped. This page documents the functions that are available to you.
 
-### Assigning Custom Names
+## Assigning Custom Names
 
 People often define custom names using `#define`. For example:
 
@@ -13,9 +13,11 @@ People often define custom names using `#define`. For example:
 
 This will allow you to use `FN_CAPS` and `ALT_TAB` in your `KEYMAP()`, keeping it more readable.
 
-### Limits of These Aliases
+## Caveats
 
-Currently, the keycodes able to used with these functions are limited to the [Basic Keycodes](keycodes_basic.md), meaning you can't use keycodes like `KC_TILD`, or anything greater than 0xFF. For a full list of the keycodes able to be used see [Basic Keycodes](keycodes_basic.md).
+Currently, `LT()` and `MT()` are limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. Modifiers specified as part of a Layer Tap or Mod Tap's keycode will be ignored.
+
+Additionally, if at least one right-handed modifier is specified in a Mod Tap or Layer Tap, it will cause all modifiers specified to become right-handed, so it is not possible to mix and match the two.
 
 # Switching and Toggling Layers
 
@@ -24,7 +26,8 @@ These functions allow you to activate layers in various ways. Note that layers a
 * `DF(layer)` - switches the default layer. The default layer is the always-active base layer that other layers stack on top of. See below for more about the default layer. This might be used to switch from QWERTY to Dvorak layout. (Note that this is a temporary switch that only persists until the keyboard loses power. To modify the default layer in a persistent way requires deeper customization, such as calling the `set_single_persistent_default_layer` function inside of [process_record_user](custom_quantum_functions.md#programming-the-behavior-of-any-keycode).)
 * `MO(layer)` - momentarily activates *layer*. As soon as you let go of the key, the layer is deactivated. 
 * `LM(layer, mod)` - Momentarily activates *layer* (like `MO`), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers.
-* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped.
+* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped. Only supports layers 0-15.
+* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys](#one-shot-keys) for details and additional functionality.
 * `TG(layer)` - toggles *layer*, activating it if it's inactive and vice versa
 * `TO(layer)` - activates *layer* and de-activates all other layers (except your default layer). This function is special, because instead of just adding/removing one layer to your active layer stack, it will completely replace your current active layers, uniquely allowing you to replace higher layers with a lower one. This is activated on keydown (as soon as the key is pressed).
 * `TT(layer)` - Layer Tap-Toggle. If you hold the key down, *layer* is activated, and then is de-activated when you let go (like `MO`). If you repeatedly tap it, the layer will be toggled on or off (like `TG`). It needs 5 taps by default, but you can change this by defining `TAPPING_TOGGLE` -- for example, `#define TAPPING_TOGGLE 2` to toggle on just two taps.
@@ -33,7 +36,7 @@ These functions allow you to activate layers in various ways. Note that layers a
 
 Care must be taken when switching layers, it's possible to lock yourself into a layer with no way to deactivate that layer (without unplugging your keyboard.) We've created some guidelines to help users avoid the most common problems.
 
-### Beginners
+## Beginners
 
 If you are just getting started with QMK you will want to keep everything simple. Follow these guidelines when setting up your layers:
 
@@ -41,11 +44,11 @@ If you are just getting started with QMK you will want to keep everything simple
 * Arrange your layers in a "tree" layout, with layer 0 as the root. Do not try to enter the same layer from more than one other layer.
 * In a layer's keymap, only reference higher-numbered layers. Because layers are processed from the highest-numbered (topmost) active layer down, modifying the state of lower layers can be tricky and error-prone.
 
-### Intermediate Users
+## Intermediate Users
 
 Sometimes you need more than one base layer. For example, if you want to switch between QWERTY and Dvorak, switch between layouts for different countries, or switch your layout for different videogames. Your base layers should always be the lowest numbered layers. When you have multiple base layers you should always treat them as mutually exclusive. When one base layer is on the others are off.
 
-### Advanced Users
+## Advanced Users
 
 Once you have a good feel for how layers work and what you can do, you can get more creative. The rules listed in the beginner section will help you be successful by avoiding some of the tricker details but they can be constraining, especially for ultra-compact keyboard users. Understanding how layers work will allow you to use them in more advanced ways.
 
@@ -55,85 +58,80 @@ Sometimes, you might want to switch between layers in a macro or as part of a ta
 
 # Modifier Keys
 
-These functions allow you to combine a mod with a keycode. When pressed the keydown for the mod will be sent first, and then *kc* will be sent. When released the keyup for *kc* will be sent and then the mod will be sent.
+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.
 
-* `LSFT(kc)` or `S(kc)` - applies left Shift to *kc* (keycode)
-* `RSFT(kc)` - applies right Shift to *kc*
-* `LCTL(kc)` - applies left Control to *kc*
-* `RCTL(kc)` - applies right Control to *kc*
-* `LALT(kc)` - applies left Alt to *kc*
-* `RALT(kc)` - applies right Alt to *kc*
-* `LGUI(kc)` - applies left GUI (command/win) to *kc*
-* `RGUI(kc)` - applies right GUI (command/win) to *kc*
-* `HYPR(kc)` - applies Hyper (all modifiers) to *kc*
-* `MEH(kc)`  - applies Meh (all modifiers except Win/Cmd) to *kc*
-* `LCAG(kc)` - applies CtrlAltGui to *kc*
+|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`            |
 
-You can also chain these, like this:
+You can also chain them, for example `LCTL(LALT(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress.
 
-    LALT(LCTL(KC_DEL)) -- this makes a key that sends Alt, Control, and Delete in a single keypress.
+# Mod-Tap
 
-# Shifted Keycodes
+The Mod-Tap key `MT(mod, kc)` acts like a modifier when held, and a regular keycode when tapped. In other words, you can have a key that sends Escape when you tap it, but functions as a Control or Shift key when you hold it down.
 
-The following shortcuts automatically add `LSFT()` to keycodes to get commonly used symbols.
+The modifiers this keycode and `OSM()` accept are prefixed with `MOD_`, not `KC_`:
 
-|Key                     |Aliases           |Description        |
-|------------------------|------------------|-------------------|
-|`KC_TILDE`              |`KC_TILD`         |`~`                |
-|`KC_EXCLAIM`            |`KC_EXLM`         |`!`                |
-|`KC_AT`                 |                  |`@`                |
-|`KC_HASH`               |                  |`#`                |
-|`KC_DOLLAR`             |`KC_DLR`          |`$`                |
-|`KC_PERCENT`            |`KC_PERC`         |`%`                |
-|`KC_CIRCUMFLEX`         |`KC_CIRC`         |`^`                |
-|`KC_AMPERSAND`          |`KC_AMPR`         |`&`                |
-|`KC_ASTERISK`           |`KC_ASTR`         |`*`                |
-|`KC_LEFT_PAREN`         |`KC_LPRN`         |`(`                |
-|`KC_RIGHT_PAREN`        |`KC_RPRN`         |`)`                |
-|`KC_UNDERSCORE`         |`KC_UNDS`         |`_`                |
-|`KC_PLUS`               |                  |`+`                |
-|`KC_LEFT_CURLY_BRACE`   |`KC_LCBR`         |`{`                |
-|`KC_RIGHT_CURLY_BRACE`  |`KC_RCBR`         |`}`                |
-|`KC_PIPE`               |                  |<code>&#124;</code>|
-|`KC_COLON`              |`KC_COLN`         |`:`                |
-|`KC_DOUBLE_QUOTE`       |`KC_DQT`/`KC_DQUO`|`"`                |
-|`KC_LEFT_ANGLE_BRACKET` |`KC_LT`/`KC_LABK` |`<`                |
-|`KC_RIGHT_ANGLE_BRACKET`|`KC_GT`/`KC_RABK` |`>`                |
-|`KC_QUESTION`           |`KC_QUES`         |`?`                |
+|Modifier  |Description                             |
+|----------|----------------------------------------|
+|`MOD_LCTL`|Left Control                            |
+|`MOD_LSFT`|Left Shift                              |
+|`MOD_LALT`|Left Alt                                |
+|`MOD_LGUI`|Left GUI (Windows/Command/Meta key)     |
+|`MOD_RCTL`|Right Control                           |
+|`MOD_RSFT`|Right Shift                             |
+|`MOD_RALT`|Right Alt                               |
+|`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)      |
 
-# Mod Tap
+You can combine these by ORing them together like so:
 
-`MT(mod, kc)` - is *mod* (modifier key - MOD_LCTL, MOD_LSFT) when held, and *kc* when tapped. In other words, you can have a key that sends Esc (or the letter O or whatever) when you tap it, but works as a Control key or a Shift key when you hold it down.
+```c
+MT(MOD_LCTL | MOD_LSFT, KC_ESC)
+```
 
-These are the values you can use for the `mod` in `MT()` and `OSM()`:
+This key would activate Left Control and Left Shift when held, and send Escape when tapped.
 
-  * MOD_LCTL
-  * MOD_LSFT
-  * MOD_LALT
-  * MOD_LGUI
-  * MOD_RCTL
-  * MOD_RSFT
-  * MOD_RALT
-  * MOD_RGUI
-  * MOD_HYPR
-  * MOD_MEH
+For convenience, QMK includes some Mod-Tap shortcuts to make common combinations more compact in your keymap:
 
-These can also be combined like `MOD_LCTL | MOD_LSFT` e.g. `MT(MOD_LCTL | MOD_LSFT, KC_ESC)` which would activate Control and Shift when held, and send Escape when tapped.
+|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       |
 
-We've added shortcuts to make common modifier/tap (mod-tap) mappings more compact:
+## Caveats
 
-  * `CTL_T(kc)` - is LCTL when held and *kc* when tapped
-  * `SFT_T(kc)` - is LSFT when held and *kc* when tapped
-  * `ALT_T(kc)` - is LALT when held and *kc* when tapped
-  * `ALGR_T(kc)` - is AltGr when held and *kc* when tapped
-  * `GUI_T(kc)` - is LGUI when held and *kc* when tapped
-  * `ALL_T(kc)` - is Hyper (all mods) when held and *kc* when tapped. To read more about what you can do with a Hyper key, see [this blog post by Brett Terpstra](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)
-  * `LCAG_T(kc)` - is CtrlAltGui when held and *kc* when tapped
-  * `MEH_T(kc)` - is like Hyper, but not as cool -- does not include the Cmd/Win key, so just sends Alt+Ctrl+Shift.
+Unfortunately, these keycodes cannot be used in Mod-Taps or Layer-Taps, since any modifiers specified in the keycode are ignored.
 
-?> Due to the way that keycodes are structured, any modifiers specified as part of `kc`, such as `LCTL()` or `KC_LPRN`, will only activate when held instead of tapped.
+Additionally, you may run into issues when using Remote Desktop Connection on Windows. Because these codes send shift very fast, Remote Desktop may miss the codes.
 
-?> Additionally, if there is at least one right modifier, any other modifiers will turn into their right equivalents, so it is not possible to "mix and match" the two.
+To fix this, open Remote Desktop Connection, click on "Show Options", open the the "Local Resources" tab. In the keyboard section, change the drop down to "On this Computer". This will fix the issue, and allow the characters to work correctly.
 
 # One Shot Keys
 
@@ -143,6 +141,8 @@ For example, if you define a key as `OSM(MOD_LSFT)`, you can type a capital A ch
 
 One shot keys also work as normal modifiers. If you hold down a one shot key and type other keys, your one shot will be released immediately after you let go of the key.
 
+Additionally, hitting keys five times in a short period will lock that key. This applies for both One Shot Modifiers and One Shot Layers, and is controlled by the `ONESHOT_TAP_TOGGLE` define.
+
 You can control the behavior of one shot keys by defining these in `config.h`:
 
 ```c
@@ -153,25 +153,96 @@ You can control the behavior of one shot keys by defining these in `config.h`:
 * `OSM(mod)` - Momentarily hold down *mod*. You must use the `MOD_*` keycodes as shown in [Mod Tap](#mod-tap), not the `KC_*` codes.
 * `OSL(layer)` - momentary switch to *layer*.
 
-Sometimes, you want to activate a one-shot layer as part of a macro or tap dance routine. To do this, you need to call `set_oneshot_layer(LAYER, ONESHOT_START)` on key down, and `set_oneshot_layer(ONESHOT_PRESSED)` on key up. If you want to cancel the oneshot, call `reset_oneshot_layer()`. For more complicated actions, take a look at the oneshot implementation in [`process_record`](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action.c#L429).
+Sometimes, you want to activate a one-shot key as part of a macro or tap dance routine.  
+
+For one shot layers, you need to call `set_oneshot_layer(LAYER, ONESHOT_START)` on key down, and `set_oneshot_layer(ONESHOT_PRESSED)` on key up. If you want to cancel the oneshot, call `reset_oneshot_layer()`.
+
+For one shot mods, you need to call `set_oneshot_mods(MOD)` to set it, or `clear_oneshot_mods()` to cancel it.
+
+!> If you're having issues with OSM translating over Remote Desktop Connection, this can be fixed by opening the settings, going to the "Local Resources" tap, and in the keyboard section, change the drop down to "On this Computer".  This will fix the issue and allow OSM to function properly over Remote Desktop.
 
-If you're having issues with OSM translating over Remote Desktop Connection, this can be fixed by opening the settings, going to the "Local Resources" tap, and in the keyboard section, change the drop down to "On this Computer".  This will fix the issue and allow OSM to function properly over Remote Desktop.
 
 # Permissive Hold
 
 As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new `config.h` option:
 
-```
+```c
 #define PERMISSIVE_HOLD
 ```
 
-This makes it easier for fast typists to use dual-function keys. Without this, if you let go of a held key inside the tapping term, it won't register.
+This makes tap and hold keys (like Mod Tap) work better for fast typist, or for high `TAPPING_TERM` settings. 
 
-Example: (Tapping Term = 200ms)
+If you press a Mod Tap key, tap another key (press and release) and then release the Mod Tap key, all within the tapping term, it will output the "tapping" function for both keys.
+
+For Instance:
+
+- `SHFT_T(KC_A)` Down
+- `KC_X` Down
+- `KC_X` Up
+- `SHFT_T(KC_A)` Up
+
+Normally, if you do all this within the `TAPPING_TERM` (default: 200ms) this will be registered as `ax` by the firmware and host system. With permissive hold enabled, this modifies how this is handled by considering the Mod Tap keys as a Mod if another key is tapped, and would registered as `X` (`SHIFT`+`x`). 
+
+?> 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
+
+To enable this setting, add this to your `config.h`:
+
+```c
+#define IGNORE_MOD_TAP_INTERRUPT
+```
+
+Similar to Permissive Hold, this alters how the firmware processes input for fast typist. If you press a Mod Tap key, press another key, release the Mod Tap key, and then release the normal key, it would normally output the "tapping" function for both keys. This may not be desirable for rolling combo keys. 
+
+Setting `Ignore Mod Tap Interrupt` requires  holding both keys for the `TAPPING_TERM` to trigger the hold function (the mod).
+
+For Instance:
+
+- `SHFT_T(KC_A)` Down
+- `KC_X` Down
+- `SHFT_T(KC_A)` Up
+- `KC_X` Up
+
+Normally, this would send `X` (`SHIFT`+`x`). With `Ignore Mod Tap Interrupt` enabled, holding both keys are required for the `TAPPING_TERM` to register the hold action. A quick tap will output `ax` in this case, while a hold on both will still output `X`  (`SHIFT`+`x`).
+
+
+?> __Note__: This only concerns modifiers and not layer switching keys.
+
+?> If you have `Permissive Hold` enabled, as well, this will modify how both work. The regular key has the modifier added if the first key is released first or if both keys are held longer than the `TAPPING_TERM`.
+
+# Tapping Force Hold
+
+To enable `tapping force hold`, add the following to your `config.h`: 
+
+```c
+#define TAPPING_FORCE_HOLD
+```
+
+When the user holds a key after tap, this repeats the tapped key rather to hold a modifier key.  This allows to use auto repeat for the tapped key.  
+
+Example:
 
 - SHFT_T(KC_A) Down
-- KC_X Down
-- KC_X Up
+- SHFT_T(KC_A) Up
+- SHFT_T(KC_A) Down
+- wait more than tapping term...
 - SHFT_T(KC_A) Up
 
-With defaults, if above is typed within tapping term, this will emit `ax`. With permissive hold, if above is typed within tapping term, this will emit `X` (so, Shift+X).
+With default settings, `a` will be sent on the first release, then `a` will be sent on the second press allowing the computer to trigger its auto repeat function.
+
+With `TAPPING_FORCE_HOLD`, the second press will be interpreted as a Shift, allowing to use it as a modifier shortly after having used it as a tap.
+
+!> `TAPPING_FORCE_HOLD` will break anything that uses tapping toggles (Such as the `TT` layer keycode, and the One Shot Tapping Toggle).
+
+# Retro Tapping
+
+To enable `retro tapping`, add the following to your `config.h`: 
+
+```c
+#define RETRO_TAPPING
+```
+
+Holding and releasing a dual function key without pressing another key will result in nothing happening. With retro tapping enabled, releasing the key without pressing another will send the original keycode even if it is outside the tapping term.
+
+For instance, holding and releasing `LT(2, KC_SPACE)` without hitting another key will result in nothing happening. With this enabled, it will send `KC_SPACE` instead.

docs/feature_audio.md

@@ -3,6 +3,7 @@
 Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any AVR keyboard that allows access to certain PWM-capable pins, you can hook up a simple speaker and make it beep. You can use those beeps to indicate layer transitions, modifiers, special keys, or just to play some funky 8bit tunes.
 
 Up to two simultaneous audio voices are supported, one driven by timer 1 and another driven by timer 3.  The following pins can be defined as audio outputs in config.h:
+
 Timer 1:
 `#define B5_AUDIO`
 `#define B6_AUDIO`
@@ -58,6 +59,13 @@ PLAY_LOOP(my_song);
 
 It's advised that you wrap all audio features in `#ifdef AUDIO_ENABLE` / `#endif` to avoid causing problems when audio isn't built into the keyboard.
 
+The available keycodes for audio are: 
+
+* `AU_ON` - Turn audio mode on
+* `AU_OFF` - Turn audio mode off
+* `AU_TOG` - Toggle audio mode
+
+
 ## Music Mode
 
 The music mode maps your columns to a chromatic scale, and your rows to octaves. This works best with ortholinear keyboards, but can be made to work with others. All keycodes less than `0xFF` get blocked, so you won't type while playing notes - if you have special keys/mods, those will still work. A work-around for this is to jump to a different layer with KC_NOs before (or after) enabling music mode.
@@ -111,22 +119,22 @@ You can completely disable Music Mode as well. This is useful, if you're pressed
 
     #define NO_MUSIC_MODE
 
-## Faux Click
+## Audio Click
 
 This adds a click sound each time you hit a button, to simulate click sounds from the keyboard. And the sounds are slightly different for each keypress, so it doesn't sound like a single long note, if you type rapidly. 
 
 * `CK_TOGG` - Toggles the status (will play sound if enabled)
-* `CK_RST` - Resets the frequency to the default state 
-* `CK_UP` - Increases the frequency of the clicks
-* `CK_DOWN` - Decreases the frequency of the clicks
+* `CK_ON` - Turns on Audio Click (plays sound)
+* `CK_OFF` - Turns off Audio Click (doesn't play sound)
+* `CK_RST` - Resets the frequency to the default state (plays sound at default frequency)
+* `CK_UP` - Increases the frequency of the clicks (plays sound at new frequency)
+* `CK_DOWN` - Decreases the frequency of the clicks (plays sound at new frequency)
+
 
 The feature is disabled by default, to save space.  To enable it, add this to your `config.h`:
 
     #define AUDIO_CLICKY
 
-Additionally, even when enabled, the feature is not enabled by default, so you would need to turn it on first.  And since we don't use EEPROM to store the setting (yet), you can default this to on by adding this to your `config.h`:
-
-    #define AUDIO_CLICKY_ON
 
 You can configure the default, min and max frequencies, the stepping and built in randomness by defining these values: 
 
@@ -136,7 +144,7 @@ You can configure the default, min and max frequencies, the stepping and built i
 | `AUDIO_CLICKY_FREQ_MIN` | 65.0f | Sets the lowest frequency (under 60f are a bit buggy). |
 | `AUDIO_CLICKY_FREQ_MAX` | 1500.0f | Sets the the highest frequency. Too high may result in coworkers attacking you. |
 | `AUDIO_CLICKY_FREQ_FACTOR` | 1.18921f| Sets the stepping of UP/DOWN key codes. |
-| `AUDIO_CLICKY_FREQ_RANDOMNESS`     |  0.05f |  Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical. | 
+| `AUDIO_CLICKY_FREQ_RANDOMNESS`     |  0.05f |  Sets a factor of randomness for the clicks, Setting this to `0f` will make each click identical, and `1.0f` will make this sound much like the 90's computer screen scrolling/typing effect. | 
 
 
 
@@ -145,6 +153,23 @@ You can configure the default, min and max frequencies, the stepping and built i
 
 This is still a WIP, but check out `quantum/keymap_midi.c` to see what's happening. Enable from the Makefile.
 
+
+## Audio Keycodes
+
+|Key             |Aliases  |Description                       |
+|----------------|---------|----------------------------------|
+|`AU_ON`         |         |Audio mode on                     |
+|`AU_OFF`        |         |Audio mode off                    |
+|`AU_TOG`        |         |Toggles Audio mode                |
+|`CLICKY_TOGGLE` |`CK_TOGG`|Toggles Audio clicky mode         |
+|`CLICKY_UP`     |`CK_UP`  |Increases frequency of the clicks |
+|`CLICKY_DOWN`   |`CK_DOWN`|Decreases frequency of the clicks |
+|`CLICKY_RESET`  |`CK_RST` |Resets frequency to default       |
+|`MU_ON`         |         |Turns on Music Mode               |
+|`MU_OFF`        |         |Turns off Music Mode              |
+|`MU_TOG`        |         |Toggles Music Mode                |
+|`MU_MOD`        |         |Cycles through the music modes    |
+
 <!-- FIXME: this formatting needs work
 
 ## Audio

docs/feature_backlight.md

@@ -1,10 +1,20 @@
 # Backlighting
 
-<!-- FIXME: Describe how backlighting works in QMK -->
+Many keyboards support backlit keys by way of individual LEDs placed through or underneath the keyswitches. QMK is able to control the brightness of these LEDs by switching them on and off rapidly in a certain ratio, a technique known as *Pulse Width Modulation*, or PWM. By altering the duty cycle of the PWM signal, it creates the illusion of dimming.
 
-## Backlight Keycodes
+The MCU can only supply so much current to its GPIO pins. Instead of powering the backlight directly from the MCU, the backlight pin is connected to a transistor or MOSFET that switches the power to the LEDs.
 
-These keycodes control the backlight. Most keyboards use this for single color in-switch lighting.
+## Usage
+
+Most keyboards have backlighting enabled by default if they support it, but if it is not working for you, check that your `rules.mk` includes the following:
+
+```make
+BACKLIGHT_ENABLE = yes
+```
+
+You should then be able to use the keycodes below to change the backlight level.
+
+## Keycodes
 
 |Key      |Description                               |
 |---------|------------------------------------------|
@@ -16,24 +26,47 @@ These keycodes control the backlight. Most keyboards use this for single color i
 |`BL_DEC` |Decrease the backlight level              |
 |`BL_BRTG`|Toggle backlight breathing                |
 
-Note that for backlight breathing, you need to have `#define BACKLIGHT_BREATHING` in your config.h.
+## Caveats
 
-## Configuration Options in `config.h`
+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.
 
-* `BACKLIGHT_PIN B7` defines the pin that controlls the LEDs. Unless you design your own keyboard, you don't need to set this.
-* `BACKLIGHT_LEVELS 3` defines the number of brightness levels (maximum 15 excluding off).
-* `BACKLIGHT_BREATHING` if defined, enables backlight breathing. Note that this is only available if `BACKLIGHT_PIN` is B5, B6 or B7.
-* `BREATHING_PERIOD 6` defines the length of one backlight "breath" in seconds.
+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`.
 
-## Notes on Implementation
+## Configuration
 
-To change the brightness when using pins B5, B6 or B7, the PWM (Pulse Width Modulation) functionality of the on-chip timer is used.
-The timer is a counter that counts up to a certain TOP value (`0xFFFF` set in ICR1) before resetting to 0.
-We also set an OCR1x register.
-When the counter reaches the value stored in that register, the PWM pin drops to low.
-The PWM pin is pulled high again when the counter resets to 0.
-Therefore, OCR1x basically sets the duty cycle of the LEDs and as such the brightness where `0` is the darkest and `0xFFFF` the brightest setting.
+To change the behaviour of the backlighting, `#define` these in your `config.h`:
 
-To enable the breathing effect, we register an interrupt handler to be called whenever the counter resets (with `ISR(TIMER1_OVF_vect)`).
-In this handler, which gets called roughly 244 times per second, we compute the desired brightness using a precomputed brightness curve.
-To disable breathing, we can just disable the respective interrupt vector and reset the brightness to the desired level.
+|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_LEVELS`   |`3`          |The number of brightness levels (maximum 15 excluding off)                                                   |
+|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if hardware PWM is used                                                          |
+|`BREATHING_PERIOD`   |`6`          |The length of one backlight "breath" in seconds                                                              |
+
+## 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.
+The desired brightness is calculated and stored in the `OCRxx` register. When the counter reaches this value, the backlight pin will go low, and is pulled high again when the counter resets.
+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 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.
+
+## 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           |
+
+### Backlight Breathing Functions
+
+|Function  |Description                                               |
+|----------|----------------------------------------------------------|
+|`breathing_toggle()`  |Turn the backlight breathing on or off        |
+|`breathing_enable()`  |Turns on backlight breathing                  |
+|`breathing_disable()` |Turns off backlight breathing                 |

docs/feature_bluetooth.md

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

docs/feature_bootmagic.md

@@ -1,89 +1,151 @@
-# Bootmagic and Magic Keycodes
+# Bootmagic
 
-There are 3 separate but related features that allow you to change the behavior of your keyboard without reflashing. While each of them have similar functionality you access that functionality in different ways depending on how your keyboard is configured.
+There are three separate but related features that allow you to change the behavior of your keyboard without reflashing. While each of them have similar functionality, it is accessed in different ways depending on how your keyboard is configured.
 
-Bootmagic is a system for configuring your keyboard while it initializes. To trigger a Bootmagic command you hold down the bootmagic key (`KC_SPACE` on most keyboards) and one or more command keys.
+**Bootmagic** is a system for configuring your keyboard while it initializes. To trigger a Bootmagic command, hold down the Bootmagic key and one or more command keys.
 
-Bootmagic Keycodes allow you to access the Bootmagic functionality after your keyboard has initialized. To use Bootmagic Keycodes you assign keycodes starting with `MAGIC_`, much in the same way you define any other key.
+**Bootmagic Keycodes** are prefixed with `MAGIC_`, and allow you to access the Bootmagic functionality *after* your keyboard has initialized. To use the keycodes, assign them to your keymap as you would any other keycode.
 
-Command is a feature that allows you to control different aspects of your keyboard. Command used to be called Magic. Command is typically accessed by holding Left and Right Shift at the same time, although that can be customized. While it shares some functionality with Bootmagic it also allows you to access functionality that Bootmagic does not. For more information see the [Command](feature_command.md) documentation page.
+**Command**, formerly known as **Magic**, is another feature that allows you to control different aspects of your keyboard. While it shares some functionality with Bootmagic, it also allows you to do things that Bootmagic does not, such as printing version information to the console. For more information, see [Command](feature_command.md).
 
-## Enabling Bootmagic
+On some keyboards Bootmagic is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk` with:
 
-Bootmagic is disabled by default. To use Bootmagic you need to enable it in your `rules.mk` file:
+```make
+BOOTMAGIC_ENABLE = full
+```
 
-    BOOTMAGIC_ENABLE = yes
+?> You may see `yes` being used in place of `full`, and this is okay. However, `yes` is deprecated, and ideally `full` (or `lite`) should be used instead.
 
-## Bootmagic Hotkeys and Keycodes
+Additionally, you can use [Bootmagic Lite](#bootmagic-lite) (a scaled down, very basic version of Bootmagic) by adding the following to your `rules.mk` file:
 
-This table describes the default Hotkeys for Bootmagic and the Keycodes for Magic. These may be overriden at the Keyboard or Keymap level. Some functionality is not available in both methods.
+```make
+BOOTMAGIC_ENABLE = lite
+```
 
-To use the Hotkey hold down `BOOTMAGIC_KEY_SALT` (`KC_SPACE` by default) and the Hotkey while plugging in your keyboard. To use the Keycode assign that keycode to a layer. For example, if you hold down Space+B while plugging in most keyboards, you will enter bootloader mode.
+## Hotkeys
 
-|Hotkey     |Keycode                           |Description                                             |
-|-----------|----------------------------------|--------------------------------------------------------|
-|`ESC`      |                                  |Skip bootmagic and saved eeprom configuration           |
-|`B`        |`RESET`                           |Enter bootloader instead of firmware                    |
-|`D`        |`DEBUG`                           |Enable debugging (writes messages to serial)            |
-|`X`        |                                  |Enable matrix debugging                                 |
-|`K`        |                                  |Enable keyboard debugging                               |
-|`M`        |                                  |Enable mouse debugging                                  |
-|`BACKSPACE`|                                  |Clear the saved settings from flash                     |
-|`CAPSLOCK` |`MAGIC_CAPSLOCK_TO_CONTROL`       |Treat `Capslock` as `Control`                           |
-|           |`MAGIC_UNCAPSLOCK_TO_CONTROL`     |Stop treating CapsLock as Control                       |
-|`LCTRL`    |`MAGIC_SWAP_CONTROL_CAPSLOCK`     |Swap `Control` and `Capslock`                           |
-|           |`MAGIC_UNSWAP_CONTROL_CAPSLOCK`   |Unswap Left Control and Caps Lock                       |
-|           |`MAGIC_SWAP_ALT_GUI`              |Swap Alt and GUI on both sides                          |
-|           |`MAGIC_UNSWAP_ALT_GUI`            |Unswap Left Alt and GUI                                 |
-|`LALT`     |`MAGIC_SWAP_LALT_LGUI`            |Swap Left `Alt` and `GUI`, e.g. for OSX Opt and Cmd     |
-|           |`MAGIC_UNSWAP_LALT_LGUI`          |Unswap Left Alt and GUI                                 |
-|`RALT`     |`MAGIC_SWAP_RALT_RGUI`            |Swap Right `Alt` and `GUI`                              |
-|           |`MAGIC_UNSWAP_RALT_RGUI`          |Unswap Right Alt and GUI                                |
-|`LGUI`     |`MAGIC_NO_GUI`                    |Disable GUI key - e.g. disable Windows key during gaming|
-|           |`MAGIC_UNNO_GUI`                  |Enable the GUI key                                      |
-|`GRAVE`    |`MAGIC_SWAP_GRAVE_ESC`            |Swap `\`~` and `ESC`                                    |
-|           |`MAGIC_UNSWAP_GRAVE_ESC`          |Unswap `\`~` and Escape                                 |
-|`BACKSLASH`|`MAGIC_SWAP_BACKSLASH_BACKSPACE`  |Swap Blackslash and Backspace                           |
-|           |`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|Unswap Backslash and Backspace                          |
-|`N`        |`MAGIC_HOST_NKRO`                 |Force N-Key Rollover (NKRO) on                          |
-|           |`MAGIC_UNHOST_NKRO`               |Force NKRO off                                          |
-|           |`MAGIC_TOGGLE_NKRO`               |Toggle NKRO on or off                                   |
-|`0`        |`DF(0)`                           |Make Layer 0 the default layer at bootup                |
-|`1`        |`DF(1)`                           |Make Layer 1 the default layer at bootup                |
-|`2`        |`DF(2)`                           |Make Layer 2 the default layer at bootup                |
-|`3`        |`DF(3)`                           |Make Layer 3 the default layer at bootup                |
-|`4`        |`DF(4)`                           |Make Layer 4 the default layer at bootup                |
-|`5`        |`DF(5)`                           |Make Layer 5 the default layer at bootup                |
-|`6`        |`DF(6)`                           |Make Layer 6 the default layer at bootup                |
-|`7`        |`DF(7)`                           |Make Layer 7 the default layer at bootup                |
+Hold down the Bootmagic key (Space by default) and the desired hotkey while plugging in your keyboard. For example, holding Space+`B` should cause it to enter the bootloader.
 
-## Bootmagic Configuration
+|Hotkey            |Description                                  |
+|------------------|---------------------------------------------|
+|Escape            |Ignore Bootmagic configuration in EEPROM     |
+|`B`               |Enter the bootloader                         |
+|`D`               |Toggle debugging over serial                 |
+|`X`               |Toggle key matrix debugging                  |
+|`K`               |Toggle keyboard debugging                    |
+|`M`               |Toggle mouse debugging                       |
+|Backspace         |Clear the EEPROM                             |
+|Caps Lock         |Toggle treating Caps Lock as Left Control    |
+|Left Control      |Toggle swapping Caps Lock and Left Control   |
+|Left Alt          |Toggle swapping Left Alt and Left GUI        |
+|Right Alt         |Toggle swapping Right Alt and Right GUI      |
+|Left GUI          |Toggle the GUI keys (useful when gaming)     |
+|<code>&#96;</code>|Toggle swapping <code>&#96;</code> and Escape|
+|`\`               |Toggle swapping `\` and Backspace            |
+|`N`               |Toggle N-Key Rollover (NKRO)                 |
+|`0`               |Make layer 0 the default layer               |
+|`1`               |Make layer 1 the default layer               |
+|`2`               |Make layer 2 the default layer               |
+|`3`               |Make layer 3 the default layer               |
+|`4`               |Make layer 4 the default layer               |
+|`5`               |Make layer 5 the default layer               |
+|`6`               |Make layer 6 the default layer               |
+|`7`               |Make layer 7 the default layer               |
 
-When setting up your keyboard and/or keymap there are a number of `#define`s that control the behavior of Bootmagic. To use these put them in your `config.h`, either at the keyboard or keymap level.
+## Keycodes
 
-|Define |Default|Description |
-|-------|-------|------------|
-|`BOOTMAGIC_KEY_SALT`|`KC_SPACE`|The key to hold down to trigger Bootmagic during initialization.|
-|`BOOTMAGIC_KEY_SKIP`|`KC_ESC`|The Hotkey to ignore saved eeprom configuration.|
-|`BOOTMAGIC_KEY_EEPROM_CLEAR`|`KC_BSPACE`|The hotkey to clear the saved eeprom configuration.|
-|`BOOTMAGIC_KEY_BOOTLOADER`|`KC_B`|The hotkey to enter the bootloader.|
-|`BOOTMAGIC_KEY_DEBUG_ENABLE`|`KC_D`|The hotkey to enable debug mode.|
-|`BOOTMAGIC_KEY_DEBUG_MATRIX`|`KC_X`|The hotkey to enable matrix debugging mode.|
-|`BOOTMAGIC_KEY_DEBUG_KEYBOARD`|`KC_K`|The hotkey to enable keyboard debugging mode.|
-|`BOOTMAGIC_KEY_DEBUG_MOUSE`|`KC_M`|The hotkey to enable mouse debugging mode.|
-|`BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK`|`KC_LCTRL`||
-|`BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL`|`KC_CAPSLOCK`||
-|`BOOTMAGIC_KEY_SWAP_LALT_LGUI`|`KC_LALT`||
-|`BOOTMAGIC_KEY_SWAP_RALT_RGUI`|`KC_RALT`||
-|`BOOTMAGIC_KEY_NO_GUI`|`KC_LGUI`||
-|`BOOTMAGIC_KEY_SWAP_GRAVE_ESC`|`KC_GRAVE`||
-|`BOOTMAGIC_KEY_SWAP_BACKSLASH_BACKSPACE`|`KC_BSLASH`||
-|`BOOTMAGIC_HOST_NKRO`|`KC_N`||
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_0`|`KC_0`|Hotkey to set Layer 0 as the default layer|
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_1`|`KC_1`|Hotkey to set Layer 1 as the default layer|
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_2`|`KC_2`|Hotkey to set Layer 2 as the default layer|
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_3`|`KC_3`|Hotkey to set Layer 3 as the default layer|
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_4`|`KC_4`|Hotkey to set Layer 4 as the default layer|
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_5`|`KC_5`|Hotkey to set Layer 5 as the default layer|
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_6`|`KC_6`|Hotkey to set Layer 6 as the default layer|
-|`BOOTMAGIC_KEY_DEFAULT_LAYER_7`|`KC_7`|Hotkey to set Layer 7 as the default layer|
+|Keycode                           |Aliases  |Description                               |
+|----------------------------------|---------|------------------------------------------|
+|`MAGIC_CAPSLOCK_TO_CONTROL`       |         |Treat Caps Lock as Left Control           |
+|`MAGIC_UNCAPSLOCK_TO_CONTROL`     |         |Stop treating Caps Lock as Left Control   |
+|`MAGIC_HOST_NKRO`                 |         |Force N-Key Rollover (NKRO) on            |
+|`MAGIC_UNHOST_NKRO`               |         |Force NKRO off                            |
+|`MAGIC_TOGGLE_NKRO`               |         |Turn NKRO on or off                       |
+|`MAGIC_NO_GUI`                    |         |Disable the GUI keys (useful when gaming) |
+|`MAGIC_UNNO_GUI`                  |         |Enable the GUI keys                       |
+|`MAGIC_SWAP_ALT_GUI`              |`AG_SWAP`|Swap Alt and GUI on both sides (for macOS)|
+|`MAGIC_UNSWAP_ALT_GUI`            |`AG_NORM`|Unswap Left Alt and Left GUI              |
+|`MAGIC_TOGGLE_ALT_GUI`            |`AG_TOGG`|Toggle Left Alt and GUI swap              |
+|`MAGIC_SWAP_BACKSLASH_BACKSPACE`  |         |Swap `\` and Backspace                    |
+|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|         |Unswap `\` and Backspace                  |
+|`MAGIC_SWAP_CONTROL_CAPSLOCK`     |         |Swap Left Control and Caps Lock           |
+|`MAGIC_UNSWAP_CONTROL_CAPSLOCK`   |         |Unswap Left Control and Caps Lock         |
+|`MAGIC_SWAP_GRAVE_ESC`            |         |Swap <code>&#96;</code> and Escape        |
+|`MAGIC_UNSWAP_GRAVE_ESC`          |         |Unswap <code>&#96;</code> and Escape      |
+|`MAGIC_SWAP_LALT_LGUI`            |         |Swap Left Alt and Left GUI                |
+|`MAGIC_UNSWAP_LALT_LGUI`          |         |Unswap Left Alt and Left GUI              |
+|`MAGIC_SWAP_RALT_RGUI`            |         |Swap Right Alt and Right GUI              |
+|`MAGIC_UNSWAP_RALT_RGUI`          |         |Unswap Right Alt and Right GUI            |
+
+## Configuration
+
+If you would like to change the hotkey assignments for Bootmagic, `#define` these in your `config.h` at either the keyboard or keymap level.
+
+|Define                                  |Default      |Description                                        |
+|----------------------------------------|-------------|---------------------------------------------------|
+|`BOOTMAGIC_KEY_SALT`                    |`KC_SPACE`   |The Bootmagic key                                  |
+|`BOOTMAGIC_KEY_SKIP`                    |`KC_ESC`     |Ignore Bootmagic configuration in EEPROM           |
+|`BOOTMAGIC_KEY_EEPROM_CLEAR`            |`KC_BSPACE`  |Clear the EEPROM configuration                     |
+|`BOOTMAGIC_KEY_BOOTLOADER`              |`KC_B`       |Enter the bootloader                               |
+|`BOOTMAGIC_KEY_DEBUG_ENABLE`            |`KC_D`       |Toggle debugging over serial                       |
+|`BOOTMAGIC_KEY_DEBUG_MATRIX`            |`KC_X`       |Toggle matrix debugging                            |
+|`BOOTMAGIC_KEY_DEBUG_KEYBOARD`          |`KC_K`       |Toggle keyboard debugging                          |
+|`BOOTMAGIC_KEY_DEBUG_MOUSE`             |`KC_M`       |Toggle mouse debugging                             |
+|`BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK`   |`KC_LCTRL`   |Swap Left Control and Caps Lock                    |
+|`BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL`     |`KC_CAPSLOCK`|Toggle treating Caps Lock as Left Control          |
+|`BOOTMAGIC_KEY_SWAP_LALT_LGUI`          |`KC_LALT`    |Toggle swapping Left Alt and Left GUI (for macOS)  |
+|`BOOTMAGIC_KEY_SWAP_RALT_RGUI`          |`KC_RALT`    |Toggle swapping Right Alt and Right GUI (for macOS)|
+|`BOOTMAGIC_KEY_NO_GUI`                  |`KC_LGUI`    |Toggle the GUI keys (useful when gaming)           |
+|`BOOTMAGIC_KEY_SWAP_GRAVE_ESC`          |`KC_GRAVE`   |Toggle swapping <code>&#96;</code> and Escape      |
+|`BOOTMAGIC_KEY_SWAP_BACKSLASH_BACKSPACE`|`KC_BSLASH`  |Toggle swapping `\` and Backspace                  |
+|`BOOTMAGIC_HOST_NKRO`                   |`KC_N`       |Toggle N-Key Rollover (NKRO)                       |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_0`         |`KC_0`       |Make layer 0 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_1`         |`KC_1`       |Make layer 1 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_2`         |`KC_2`       |Make layer 2 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_3`         |`KC_3`       |Make layer 3 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_4`         |`KC_4`       |Make layer 4 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_5`         |`KC_5`       |Make layer 5 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_6`         |`KC_6`       |Make layer 6 the default layer                     |
+|`BOOTMAGIC_KEY_DEFAULT_LAYER_7`         |`KC_7`       |Make layer 7 the default layer                     |
+
+# Bootmagic Lite
+
+In addition to the full blown Bootmagic feature, is the Bootmagic Lite feature that only handles jumping into the bootloader.  This is great for boards that don't have a physical reset button but you need a way to jump into the bootloader, and don't want to deal with the headache that Bootmagic can cause.
+
+To enable this version of Bootmagic, you need to enable it in your `rules.mk` with:
+
+```make
+BOOTMAGIC_ENABLE = lite
+```
+
+Additionally, you may want to specify which key to use.  This is especially useful for keyboards that have unusual matrices.  To do so, you need to specify the row and column of the key that you want to use. Add these entries to your `config.h` file:
+
+```c
+#define BOOTMAGIC_LITE_ROW 0
+#define BOOTMAGIC_LITE_COLUMN 1
+```
+
+By default, these are set to 0 and 0, which is usually the "ESC" key on a majority of keyboards.
+
+And to trigger the bootloader, you hold this key down when plugging the keyboard in. Just the single key. 
+
+## Advanced Bootmagic Lite
+
+The `bootmagic_lite` function is defined weakly, so that you can replace this in your code, if you need.  A great example of this is the Zeal60 boards that have some additional handling needed.
+
+To replace the function, all you need to do is add something like this to your code:
+
+```c
+void bootmagic_lite(void) {
+    matrix_scan();
+    wait_ms(DEBOUNCING_DELAY * 2);
+    matrix_scan();
+
+    if (matrix_get_row(BOOTMAGIC_LITE_ROW) & (1 << BOOTMAGIC_LITE_COLUMN)) {
+      // Jump to bootloader.
+      bootloader_jump();
+    }
+}
+```
+
+You can additional feature here. For instance, resetting the eeprom or requiring additional keys to be pressed to trigger bootmagic.  Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware.

docs/feature_combo.md

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

docs/feature_command.md

@@ -1,52 +1,50 @@
-# Command (Formerly known as Magic)
+# Command
 
-Command is a way to change your keyboard's behavior without having to flash or unplug it to use [Bootmagic](feature_bootmagic.md). There is a lot of overlap between this functionality and the [Bootmagic Keycodes](feature_bootmagic.md). Whenever possible we encourage you to use that functionality instead of Command.
+Command, formerly known as Magic, is a way to change your keyboard's behavior without having to flash or unplug it to use [Bootmagic](feature_bootmagic.md). There is a lot of overlap between this functionality and the [Bootmagic Keycodes](feature_bootmagic.md#keycodes). Wherever possible we encourage you to use that feature instead of Command.
 
-## Enabling Command
+On some keyboards Command is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk`:
 
-By default Command is disabled. You can enable it in your `rules.mk` file:
-
-    COMMAND_ENABLE = yes
+```make
+COMMAND_ENABLE = yes
+```
 
 ## Usage
 
-To use Command you hold down the key combination defined by `IS_COMMAND`. By default that combination is both shift keys. While holding the key combination press the key corresponding to the command you want.
-
-For example, to write the current QMK version to the QMK Toolbox console, you can press `Left Shift`+`Right Shift`+`V`.
+To use Command, hold down the key combination defined by the `IS_COMMAND()` macro. By default this is Left Shift+Right Shift. Then, press the key corresponding to the command you want. For example, to output the current QMK version to the QMK Toolbox console, press Left Shift+Right Shift+`V`.
 
 ## Configuration
 
-The following values can be defined in `config.h` to control the behavior of Command.
+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()`                      |`(keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)))`|Key combination to activate Command|
-|`MAGIC_KEY_SWITCH_LAYER_WITH_FKEYS` |`true`                                                                |Do layer switching with Function row|
-|`MAGIC_KEY_SWITCH_LAYER_WITH_NKEYS` |`true`                                                                |Do layer switching with number keys.|
-|`MAGIC_KEY_SWITCH_LAYER_WITH_CUSTOM`|`false`                                                               |Do layer switching with custom keys (`MAGIC_KEY_LAYER0..9` below.)|
-|`MAGIC_KEY_HELP1`                   |`H`                                                                   |Show help.|
-|`MAGIC_KEY_HELP2`                   |`SLASH`                                                               |Show help.|
-|`MAGIC_KEY_DEBUG`                   |`D`                                                                   |Turn on debug mode.|
-|`MAGIC_KEY_DEBUG_MATRIX`            |`X`                                                                   |Turn on matrix debugging.|
-|`MAGIC_KEY_DEBUG_KBD`               |`K`                                                                   |Turn on keyboard debugging.|
-|`MAGIC_KEY_DEBUG_MOUSE`             |`M`                                                                   |Turn on mouse debugging.|
-|`MAGIC_KEY_VERSION`                 |`V`                                                                   |Write the QMK version to the console|
-|`MAGIC_KEY_STATUS`                  |`S`                                                                   |Show the current keyboard status|
-|`MAGIC_KEY_CONSOLE`                 |`C`                                                                   |Enable the Command Console|
-|`MAGIC_KEY_LAYER0_ALT1`             |`ESC`                                                                 |Alternate access to layer 0|
-|`MAGIC_KEY_LAYER0_ALT2`             |`GRAVE`                                                               |Alternate access to layer 0|
-|`MAGIC_KEY_LAYER0`                  |`0`                                                                   |Change default layer to 0|
-|`MAGIC_KEY_LAYER1`                  |`1`                                                                   |Change default layer to 1|
-|`MAGIC_KEY_LAYER2`                  |`2`                                                                   |Change default layer to 2|
-|`MAGIC_KEY_LAYER3`                  |`3`                                                                   |Change default layer to 3|
-|`MAGIC_KEY_LAYER4`                  |`4`                                                                   |Change default layer to 4|
-|`MAGIC_KEY_LAYER5`                  |`5`                                                                   |Change default layer to 5|
-|`MAGIC_KEY_LAYER6`                  |`6`                                                                   |Change default layer to 6|
-|`MAGIC_KEY_LAYER7`                  |`7`                                                                   |Change default layer to 7|
-|`MAGIC_KEY_LAYER8`                  |`8`                                                                   |Change default layer to 8|
-|`MAGIC_KEY_LAYER9`                  |`9`                                                                   |Change default layer to 9|
-|`MAGIC_KEY_BOOTLOADER`              |`PAUSE`                                                               |Exit keyboard and enter bootloader|
-|`MAGIC_KEY_LOCK`                    |`CAPS`                                                                |Lock the keyboard so nothing can be typed|
-|`MAGIC_KEY_EEPROM`                  |`E`                                                                   |Erase EEPROM settings|
-|`MAGIC_KEY_NKRO`                    |`N`                                                                   |Toggle NKRO on/off|
-|`MAGIC_KEY_SLEEP_LED`               |`Z`                                                                   |Toggle LED when computer is sleeping on/off|
+|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            |

docs/feature_dynamic_macros.md

@@ -4,10 +4,10 @@ QMK supports temporary macros created on the fly. We call these Dynamic Macros.
 
 You can store one or two macros and they may have a combined total of 128 keypresses. You can increase this size at the cost of RAM.
 
-To enable them, first add a new element to the `planck_keycodes` enum — `DYNAMIC_MACRO_RANGE`:
+To enable them, first add a new element to the end of your `keycodes` enum — `DYNAMIC_MACRO_RANGE`:
 
 ```c
-enum planck_keycodes {
+enum keycodes {
 	QWERTY = SAFE_RANGE,
 	COLEMAK,
 	DVORAK,
@@ -20,7 +20,7 @@ enum planck_keycodes {
 };
 ```
 
-It must be the last element because `dynamic_macros.h` will add some more keycodes after it.
+Your `keycodes` enum may have a slightly different name. You must add `DYNAMIC_MACRO_RANGE` as the last element because `dynamic_macros.h` will add some more keycodes after it.
 
 Below it, include the `dynamic_macro.h` header:
 

docs/feature_encoders.md

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

docs/feature_grave_esc.md

@@ -1,17 +1,24 @@
 # Grave Escape
 
-Grave Escape is a feature that allows you to share the grave key (<code>&#96;</code> and `~`) on the same key as Escape. When `KC_GESC` is used it will act as `KC_ESC`, unless Shift or GUI is pressed, in which case it will act as `KC_GRAVE`.
+If you're using a 60% keyboard, or any other layout with no F-row, you will have noticed that there is no dedicated Escape key. Grave Escape is a feature that allows you to share the grave key (<code>&#96;</code> and `~`) with Escape.
 
+## 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`.
+
+## Keycodes
 
 |Key      |Aliases    |Description                                                       |
 |---------|-----------|------------------------------------------------------------------|
 |`KC_GESC`|`GRAVE_ESC`|Escape when pressed, <code>&#96;</code> when Shift or GUI are held|
 
-There are several possible key combinations this will break, among them Ctrl+Shift+Esc on Windows and Cmd+Opt+Esc on macOS. You can use these options in your `config.h` to work around this:
+## Configuration
 
-| Option | Description |
-|--------|-------------|
-| `GRAVE_ESC_ALT_OVERRIDE` | Always send Escape if Alt is pressed. |
-| `GRAVE_ESC_CTRL_OVERRIDE` | Always send Escape if Ctrl is pressed. |
-| `GRAVE_ESC_GUI_OVERRIDE` | Always send Escape if GUI is pressed. |
-| `GRAVE_ESC_SHIFT_OVERRIDE` | Always send Escape if SHIFT is pressed. |
+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`:
+
+|Define                    |Description                              |
+|--------------------------|-----------------------------------------|
+|`GRAVE_ESC_ALT_OVERRIDE`  |Always send Escape if Alt is pressed     |
+|`GRAVE_ESC_CTRL_OVERRIDE` |Always send Escape if Control is pressed |
+|`GRAVE_ESC_GUI_OVERRIDE`  |Always send Escape if GUI is pressed     |
+|`GRAVE_ESC_SHIFT_OVERRIDE`|Always send Escape if Shift is pressed   |

docs/feature_hd44780.md

@@ -0,0 +1,56 @@
+# HD44780 LCD Displays
+
+This is an integration of Peter Fleury's LCD library. This page will explain the basics. [For in depth documentation visit his page.](http://homepage.hispeed.ch/peterfleury/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)
+
+You can enable support for HD44780 Displays by setting the `HD44780_ENABLE` flag in your keyboards `rules.mk` to yes. This will use about 400 KB of extra space.
+
+## Configuration
+
+You will need to configure the pins used by your display and its number of lines and collumn in your keyboards `config.h`.
+
+Uncomment the section labled HD44780 and change the parameters as needed.
+````
+/*
+ * HD44780 LCD Display Configuration
+ */
+
+#define LCD_LINES           2     //< number of visible lines of the display
+#define LCD_DISP_LENGTH    16     //< visibles characters per line of the display
+#define LCD_IO_MODE      1            //< 0: memory mapped mode, 1: IO port mode
+#if LCD_IO_MODE
+#define LCD_PORT         PORTB        //< port for the LCD lines
+#define LCD_DATA0_PORT   LCD_PORT     //< port for 4bit data bit 0
+#define LCD_DATA1_PORT   LCD_PORT     //< port for 4bit data bit 1
+#define LCD_DATA2_PORT   LCD_PORT     //< port for 4bit data bit 2
+#define LCD_DATA3_PORT   LCD_PORT     //< port for 4bit data bit 3
+#define LCD_DATA0_PIN    4            //< pin for 4bit data bit 0
+#define LCD_DATA1_PIN    5            //< pin for 4bit data bit 1
+#define LCD_DATA2_PIN    6            //< pin for 4bit data bit 2 
+#define LCD_DATA3_PIN    7            //< pin for 4bit data bit 3
+#define LCD_RS_PORT      LCD_PORT     //< port for RS line        
+#define LCD_RS_PIN       3            //< pin  for RS line        
+#define LCD_RW_PORT      LCD_PORT     //< port for RW line        
+#define LCD_RW_PIN       2            //< pin  for RW line        
+#define LCD_E_PORT       LCD_PORT     //< port for Enable line     
+#define LCD_E_PIN        1            //< pin  for Enable line    
+#endif
+````
+
+Should you need to configure other properties you can copy them from `quantum/hd44780.h` and set them in your `config.h`
+
+## Usage 
+
+To initialize your display call lcd_init() with one of these parameters:
+````
+LCD_DISP_OFF             : display off
+LCD_DISP_ON              : display on, cursor off
+LCD_DISP_ON_CURSOR       : display on, cursor on
+LCD_DISP_ON_CURSOR_BLINK : display on, cursor on flashing 
+````
+This is best done in your keyboards `matrix_init_kb` or your keymaps `matrix_init_user`.  
+It is advised to clear the display before use.  
+To do so call `lcd_clrsrc()`.
+
+To now print something to your Display you first call `lcd_gotoxy(column, line)`. To go to the start of the first line you would call `lcd_gotoxy(0, 0)` and then print a string with `lcd_puts("example string")`.
+
+There are more posible methods to control the display. [For in depth documentation please visit the linked page.](http://homepage.hispeed.ch/peterfleury/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)

docs/feature_key_lock.md

@@ -1,11 +1,22 @@
-## Key Lock: Holding Down Keys for You
+# Key Lock
 
-Sometimes, you need to hold down a specific key for a long period of time. Whether this is while typing in ALL CAPS, or playing a video game that hasn't implemented auto-run, Key Lock is here to help. Key Lock adds a new keycode, `KC_LOCK`, that will hold down the next key you hit for you. The key is released when you hit it again. Here's an example: let's say you need to type in all caps for a few sentences. You hit KC_LOCK, and then shift. Now, shift will be considered held until you hit it again. You can think of key lock as caps lock, but supercharged.
+Sometimes you may find yourself needing to hold down a specific key for a long period of time. Key Lock holds down the next key you press for you. Press it again, and it will be released.
 
-Here's how to use it:
+Let's say you need to type in ALL CAPS for a few sentences. Hit `KC_LOCK`, and then Shift. Now, Shift will be considered held until you tap it again. You can think of Key Lock as Caps Lock, but supercharged.
 
-1. Pick a key on your keyboard. This will be the key lock key. Assign it the keycode `KC_LOCK`. This will be a single-action key: you won't be able to use it for anything else.
-2. Enable key lock by including `KEY_LOCK_ENABLE = yes` in your Makefile.
-3. That's it!
+## Usage
 
-Important: switching layers does not cancel the key lock. Additionally, key lock is only able to hold standard action keys and One Shot modifier keys (for example, if you have your shift defined as `OSM(KC_LSFT)`; see [One Shot Keys](quantum_keycodes.md#one-shot-keys)). This does not include any of the QMK special functions (except One Shot modifiers), or shifted versions of keys such as KC_LPRN. If it's in the [Basic Keycodes](keycodes_basic.md) list, it can be held. If it's not, then it can't be.
+First, enable Key Lock by setting `KEY_LOCK_ENABLE = yes` in your `rules.mk`. Then pick a key in your keymap and assign it the keycode `KC_LOCK`.
+
+## Keycodes
+
+|Keycode  |Description                                                   |
+|---------|--------------------------------------------------------------|
+|`KC_LOCK`|Hold down the next key pressed, until the key is pressed again|
+
+## Caveats
+
+Key Lock is only able to hold standard action keys and [One Shot modifier](quantum_keycodes.md#one-shot-keys) keys (for example, if you have your Shift defined as `OSM(KC_LSFT)`).
+This does not include any of the QMK special functions (except One Shot modifiers), or shifted versions of keys such as `KC_LPRN`. If it's in the [Basic Keycodes](keycodes_basic.md) list, it can be held.
+
+Switching layers will not cancel the Key Lock.

docs/feature_layouts.md

@@ -53,6 +53,8 @@ but the `LAYOUT_<layout>` variable must be defined in `<folder>.h` as well.
 
 ## Tips for Making Layouts Keyboard-Agnostic
 
+### Includes
+
 Instead of using `#include "planck.h"`, you can use this line to include whatever `<keyboard>.h` (`<folder>.h` should not be included here) file that is being compiled:
 
     #include QMK_KEYBOARD_H
@@ -72,3 +74,7 @@ For example:
 ```
 
 Note that the names are lowercase and match the folder/file names for the keyboard/revision exactly.
+
+### Keymaps
+
+In order to support both split and non-split keyboards with the same layout, you need to use the keyboard agnostic `LAYOUT_<layout name>` macro in your keymap. For instance, in order for a Let's Split and Planck to share the same layout file, you need to use `LAYOUT_ortho_4x12` instead of `LAYOUT_planck_grid` or just `{}` for a C array.

docs/feature_leader_key.md

@@ -5,7 +5,7 @@ If you've ever used Vim, you know what a Leader key is. If not, you're about to
 That's what `KC_LEAD` does. Here's an example:
 
 1. Pick a key on your keyboard you want to use as the Leader key. Assign it the keycode `KC_LEAD`. This key would be dedicated just for this -- it's a single action key, can't be used for anything else.
-2. Include the line `#define LEADER_TIMEOUT 300` somewhere in your keymap.c file, probably near the top. The 300 there is 300ms -- that's how long you have for the sequence of keys following the leader. You can tweak this value for comfort, of course.
+2. Include the line `#define LEADER_TIMEOUT 300` in your config.h. The 300 there is 300ms -- that's how long you have for the sequence of keys following the leader. You can tweak this value for comfort, of course.
 3. Within your `matrix_scan_user` function, do something like this:
 
 ```
@@ -39,3 +39,11 @@ void matrix_scan_user(void) {
 As you can see, you have a few function. You can use `SEQ_ONE_KEY` for single-key sequences (Leader followed by just one key), and `SEQ_TWO_KEYS`, `SEQ_THREE_KEYS` up to `SEQ_FIVE_KEYS` for longer sequences.
 
 Each of these accepts one or more keycodes as arguments. This is an important point: You can use keycodes from **any layer on your keyboard**. That layer would need to be active for the leader macro to fire, obviously.
+
+## Adding Leader Key Support in the `rules.mk`
+
+To add support for Leader Key you simply need to add a single line to your keymap's `rules.mk`:
+
+```
+LEADER_ENABLE = yes
+```

docs/feature_macros.md

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

docs/feature_ps2_mouse.md

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

docs/feature_rgb_matrix.md

@@ -1,8 +1,12 @@
 # RGB Matrix Lighting
 
+## Driver configuration
+
+### IS31FL3731
+
 There is basic support for addressable RGB matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`:
 
-    RGB_MATRIX_ENABLE = yes
+    RGB_MATRIX_ENABLE = IS31FL3731
 
 Configure the hardware via your `config.h`:
 
@@ -36,7 +40,51 @@ Define these arrays listing all the LEDs in your `<keyboard>.c`:
 	    ....
 	}
 
-Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3731.pdf). The `driver` is the index of the driver you defined in your `config.h` (`0` or `1` right now).
+Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0` or `1` right now).
+
+###  IS31FL3733
+
+There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`:
+
+    RGB_MATRIX_ENABLE = IS31FL3733
+
+Configure the hardware via your `config.h`:
+
+	// This is a 7-bit address, that gets left-shifted and bit 0
+	// set to 0 for write, 1 for read (as per I2C protocol)
+	// The address will vary depending on your wiring:
+	// 00 <-> GND
+	// 01 <-> SCL
+	// 10 <-> SDA
+	// 11 <-> VCC
+	// ADDR1 represents A1:A0 of the 7-bit address.
+	// ADDR2 represents A3:A2 of the 7-bit address.
+	// The result is: 0b101(ADDR2)(ADDR1)
+	#define DRIVER_ADDR_1 0b1010000
+	#define DRIVER_ADDR_2 0b1010000 // this is here for compliancy reasons.
+
+	#define DRIVER_COUNT 1
+	#define DRIVER_1_LED_TOTAL 64
+	#define DRIVER_LED_TOTAL DRIVER_1_LED_TOTAL
+
+Currently only a single drivers is supported, but it would be trivial to support all 4 combinations. For now define `DRIVER_ADDR_2` as `DRIVER_ADDR_1`
+
+Define these arrays listing all the LEDs in your `<keyboard>.c`:
+
+	const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
+	/* Refer to IS31 manual for these locations
+	 *   driver
+	 *   |  R location
+	 *   |  |       G location
+	 *   |  |       |       B location
+	 *   |  |       |       | */
+	    {0, B_1,    A_1,    C_1},
+	    ....
+	}
+
+Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3733.pdf) and the header file `drivers/issi/is31fl3733.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0` right now).
+
+From this point forward the configuration is the same for all the drivers. 
 
 	const rgb_led g_rgb_leds[DRIVER_LED_TOTAL] = {
 	/* {row | col << 4}
@@ -80,7 +128,7 @@ All RGB keycodes are currently shared with the RGBLIGHT system:
 These are the effects that are currently available:
 
 	enum rgb_matrix_effects {
-		RGB_MATRIX_SOLID_COLOR = 1,
+	    RGB_MATRIX_SOLID_COLOR = 1,
 	    RGB_MATRIX_ALPHAS_MODS,
 	    RGB_MATRIX_DUAL_BEACON,
 	    RGB_MATRIX_GRADIENT_UP_DOWN,
@@ -92,8 +140,9 @@ These are the effects that are currently available:
 	    RGB_MATRIX_RAINBOW_PINWHEELS,
 	    RGB_MATRIX_RAINBOW_MOVING_CHEVRON,
 	    RGB_MATRIX_JELLYBEAN_RAINDROPS,
+	    RGB_MATRIX_DIGITAL_RAIN,
 	#ifdef RGB_MATRIX_KEYPRESSES
-		RGB_MATRIX_SOLID_REACTIVE,
+	    RGB_MATRIX_SOLID_REACTIVE,
 	    RGB_MATRIX_SPLASH,
 	    RGB_MATRIX_MULTISPLASH,
 	    RGB_MATRIX_SOLID_SPLASH,
@@ -107,7 +156,7 @@ These are the effects that are currently available:
 Custom layer effects can be done by defining this in your `<keyboard>.c`:
 
     void rgb_matrix_indicators_kb(void) {
-    	// rgb_matrix_set_color(index, red, green, blue);
+        rgb_matrix_set_color(index, red, green, blue);
     }
 
 A similar function works in the keymap as `rgb_matrix_indicators_user`.
@@ -119,6 +168,7 @@ A similar function works in the keymap as `rgb_matrix_indicators_user`.
 	#define RGB_DISABLE_AFTER_TIMEOUT 0 // number of ticks to wait until disabling effects
 	#define RGB_DISABLE_WHEN_USB_SUSPENDED false // turn off effects when suspended
     #define RGB_MATRIX_SKIP_FRAMES 1 // number of frames to skip when displaying animations (0 is full effect) if not defined defaults to 1
+    #define RGB_MATRIX_MAXIMUM_BRIGHTNESS 200 // limits maximum brightness of LEDs to 200 out of 255. If not defined maximum brightness is set to 255
 
 ## EEPROM storage
 

docs/feature_rgblight.md

@@ -1,131 +1,46 @@
 # RGB Lighting
 
-If you've installed addressable RGB lights on your keyboard you can control them with QMK. Currently we support the following addressable LEDs on Atmel AVR processors:
+QMK has the ability to control RGB LEDs attached to your keyboard. This is commonly called *underglow*, due to the LEDs often being mounted on the bottom of the keyboard, producing a nice diffused effect when combined with a translucent case.
 
-* WS2811 and variants (WS2812, WS2812B, WS2812C, etc)
-* SK6812RGBW
+![Planck with RGB Underglow](https://raw.githubusercontent.com/qmk/qmk_firmware/3774a7fcdab5544fc787f4c200be05fcd417e31f/keyboards/planck/keymaps/yang/planck-with-rgb-underglow.jpg)
 
-Some keyboards come with RGB LEDs pre-installed. Others have to have LEDs installed after the fact. See below for information on modifying your keyboard.
+Some keyboards come with RGB LEDs preinstalled. Others must have them installed after the fact. See the [Hardware Modification](#hardware-modification) section for information on adding RGB lighting to your keyboard.
 
-## Selecting Colors
+Currently QMK supports the following addressable LEDs on AVR microcontrollers (however, the white LED in RGBW variants is not supported):
 
-QMK uses Hue, Saturation, and Value to set color rather than using RGB. You can use the color wheel below to see how this works. Changing the Hue will cycle around the circle. Saturation will affect the intensity of the color, which you can see as you move from the inner part to the outer part of the wheel. Value sets the overall brightness.
+ * WS2811, WS2812, WS2812B, WS2812C, etc.
+ * SK6812, SK6812MINI, SK6805
 
-<img src="gitbook/images/color-wheel.svg" alt="HSV Color Wheel" width="250">
+These LEDs are called "addressable" because instead of using a wire per color, each LED contains a small microchip that understands a special protocol sent over a single wire. The chip passes on the remaining data to the next LED, allowing them to be chained together. In this way, you can easily control the color of the individual LEDs.
 
-If you would like to learn more about HSV you can start with the [Wikipedia article](https://en.wikipedia.org/wiki/HSL_and_HSV).
+## Usage
 
-## Configuration
+On keyboards with onboard RGB LEDs, it is usually enabled by default. If it is not working for you, check that your `rules.mk` includes the following:
 
-Before RGB Lighting can be used you have to enable it in `rules.mk`:
-
-    RGBLIGHT_ENABLE = yes
-
-You can configure the behavior of the RGB lighting by defining values inside `config.h`.
-
-### Required Configuration
-
-At minimum you have to define the pin your LED strip is connected to and the number of LEDs connected.
-
-```c
-#define RGB_DI_PIN D7     // The pin the LED strip is connected to
-#define RGBLED_NUM 14     // Number of LEDs in your strip
+```make
+RGBLIGHT_ENABLE = yes
 ```
 
-### Optional Configuration
+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.
 
-You can change the behavior of the RGB Lighting by setting these configuration values. Use `#define <Option> <Value>` in a `config.h` at the keyboard, revision, or keymap level.
+|Define      |Description                                  |
+|------------|---------------------------------------------|
+|`RGB_DI_PIN`|The pin connected to the data pin of the LEDs|
+|`RGBLED_NUM`|The number of LEDs connected                 |
 
-| Option | Default Value | Description |
-|--------|---------------|-------------|
-| `RGBLIGHT_HUE_STEP` | 10 | How many hues you want to have available. |
-| `RGBLIGHT_SAT_STEP` | 17 | How many steps of saturation you'd like. |
-| `RGBLIGHT_VAL_STEP` | 17 | The number of levels of brightness you want. |
-| `RGBLIGHT_LIMIT_VAL` | 255 | Limit the val of HSV to limit the maximum brightness simply. |
-| `RGBLIGHT_SLEEP`     |    |  `#define` this will shut off the lights when the host goes to sleep | 
+Then you should be able to use the keycodes below to change the RGB lighting to your liking.
 
+### Color Selection
 
-### Animations
+QMK uses [Hue, Saturation, and Value](https://en.wikipedia.org/wiki/HSL_and_HSV) to select colors rather than RGB. The color wheel below demonstrates how this works.
 
-If you have `#define RGBLIGHT_ANIMATIONS` in your `config.h` you will have a number of animation modes you can cycle through using the `RGB_MOD` key. You can also `#define` other options to tweak certain animations.
+<img src="gitbook/images/color-wheel.svg" alt="HSV Color Wheel" width="250"/>
 
-| Option | Default Value | Description |
-|--------|---------------|-------------|
-| `RGBLIGHT_ANIMATIONS` | | `#define` this to enable animation modes. |
-| `RGBLIGHT_EFFECT_BREATHE_CENTER` | 1.85 | Used to calculate the curve for the breathing animation. Valid values 1.0-2.7. |
-| `RGBLIGHT_EFFECT_BREATHE_MAX` | 255 | The maximum brightness for the breathing mode. Valid values 1-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. |
-| `RGBLIGHT_EFFECT_KNIGHT_OFFSET` | 0 | Start the knight animation this many LEDs from the start of the strip. |
-| `RGBLIGHT_EFFECT_KNIGHT_LED_NUM` | RGBLED_NUM | The number of LEDs to have the "knight" animation travel. |
-| `RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL` | 1000 | How long to wait between light changes for the "christmas" animation. Specified in ms. |
-| `RGBLIGHT_EFFECT_CHRISTMAS_STEP` | 2 | How many LED's to group the red/green colors by for the christmas mode. |
+Changing the **Hue** cycles around the circle.  
+Changing the **Saturation** moves between the inner and outer sections of the wheel, affecting the intensity of the color.  
+Changing the **Value** sets the overall brightness.
 
-You can also tweak the behavior of the animations by defining these consts in your `keymap.c`. These mostly affect the speed different modes animate at.
-
-```c
-// How long (in ms) to wait between animation steps for the breathing mode
-const uint8_t RGBLED_BREATHING_INTERVALS[] PROGMEM = {30, 20, 10, 5};
-
-// How long (in ms) to wait between animation steps for the rainbow mode
-const uint8_t RGBLED_RAINBOW_MOOD_INTERVALS[] PROGMEM = {120, 60, 30};
-
-// How long (in ms) to wait between animation steps for the swirl mode
-const uint8_t RGBLED_RAINBOW_SWIRL_INTERVALS[] PROGMEM = {100, 50, 20};
-
-// How long (in ms) to wait between animation steps for the snake mode
-const uint8_t RGBLED_SNAKE_INTERVALS[] PROGMEM = {100, 50, 20};
-
-// How long (in ms) to wait between animation steps for the knight modes
-const uint8_t RGBLED_KNIGHT_INTERVALS[] PROGMEM = {127, 63, 31};
-
-// These control which colors are selected for the gradient mode
-const uint16_t RGBLED_GRADIENT_RANGES[] PROGMEM = {360, 240, 180, 120, 90};
-```
-
-### LED Control
-
-Look in `rgblights.h` for all available functions, but if you want to control all or some LEDs your goto functions are:
-
-```c
-// turn all lights off (stored in EEPROM)
-rgblight_disable();
-// turn lights on, based on their previous state (stored in EEPROM)
-rgblight_enable(); 
-
-// turn all lights off (not stored in EEPROM)
-rgblight_disable_noeeprom();
-// turn lights on, based on their previous state (not stored in EEPROM)
-rgblight_enable_noeeprom();
-
-// where r/g/b is a number from 0..255.  Turns all the LEDs to this color (ignores mode, not stored in EEPROM). 
-rgblight_setrgb(r, g, b); 
-// HSV color control - h is a value from 0..360 and s/v is a value from 0..255 (stored in EEPROM)
-rgblight_sethsv(h, s, v);  
-// HSV color control - h is a value from 0..360 and s/v is a value from 0..255 (not stored in EEPROM)
-rgblight_sethsv_noeeprom(h, s, v);  
-
-// Sets the mode, if rgb animations are enabled (stored in eeprom)
-rgblight_mode(x);
-// Sets the mode, if rgb animations are enabled (not stored in eeprom)
-rgblight_mode_noeeprom(x);
-// MODE 1, solid color
-// MODE 2-5, breathing
-// MODE 6-8, rainbow mood
-// MODE 9-14, rainbow swirl
-// MODE 15-20, snake
-// MODE 21-23, knight
-// MODE 24, xmas
-// MODE 25-34, static rainbow
-
-rgblight_setrgb_at(r,g,b, LED);  // control a single LED.  0 <= LED < RGBLED_NUM
-rgblight_sethsv_at(h,s,v, LED);  // control a single LED.  0 <= LED < RGBLED_NUM
-```
-You can find a list of predefined colors at [`quantum/rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Free to add to this list!
-
-## RGB Lighting Keycodes
-
-These control the RGB Lighting functionality.
+## Keycodes
 
 |Key                |Aliases   |Description                                                         |
 |-------------------|----------|--------------------------------------------------------------------|
@@ -146,25 +61,110 @@ These control the RGB Lighting functionality.
 |`RGB_MODE_KNIGHT`  |`RGB_M_K` |"Knight Rider" animation mode                                       |
 |`RGB_MODE_XMAS`    |`RGB_M_X` |Christmas animation mode                                            |
 |`RGB_MODE_GRADIENT`|`RGB_M_G` |Static gradient animation mode                                      |
-|`RGB_MODE_RGBTEST `|`RGB_M_T` |Red,Green,Blue test animation mode                                  |
+|`RGB_MODE_RGBTEST` |`RGB_M_T` |Red, Green, Blue test animation mode                                |
 
-note: for backwards compatibility, `RGB_SMOD` is an alias for `RGB_MOD`.
+?> For backwards compatibility, `RGB_SMOD` is another alias of `RGB_MOD`.
+
+## Configuration
+
+Your RGB lighting can be configured by placing these `#define`s in your `config.h`:
+
+|Define               |Default      |Description                                                                  |
+|---------------------|-------------|-----------------------------------------------------------------------------|
+|`RGBLIGHT_HUE_STEP`  |`10`         |The number of steps to cycle through the hue by                              |
+|`RGBLIGHT_SAT_STEP`  |`17`         |The number of steps to increment the saturation by                           |
+|`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|
+
+## Animations
+
+
+Not only can this lighting be whatever color you want,
+if `RGBLIGHT_EFFECT_xxxx` or `RGBLIGHT_ANIMATIONS` is defined, you also have a number of animation modes at your disposal:
+
+|Mode number symbol           |Additional number  |Description                            |
+|-----------------------------|-------------------|---------------------------------------|
+|`RGBLIGHT_MODE_STATIC_LIGHT` | *None*            |Solid color (this mode is always enabled) |
+|`RGBLIGHT_MODE_BREATHING`    | 0,1,2,3           |Solid color breathing                  |
+|`RGBLIGHT_MODE_RAINBOW_MOOD` | 0,1,2             |Cycling rainbow                        |
+|`RGBLIGHT_MODE_RAINBOW_SWIRL`| 0,1,2,3,4,5       |Swirling rainbow                       |
+|`RGBLIGHT_MODE_SNAKE`        | 0,1,2,3,4,5       |Snake                                  |
+|`RGBLIGHT_MODE_KNIGHT`       | 0,1,2             |Knight                                 |
+|`RGBLIGHT_MODE_CHRISTMAS`    | *None*            |Christmas                              |
+|`RGBLIGHT_MODE_STATIC_GRADIENT`| 0,1,..,9        |Static gradient                        |
+|`RGBLIGHT_MODE_RGB_TEST`     | *None*            |RGB Test                               |
+|`RGBLIGHT_MODE_ALTERNATING`  | *None*            |Alternating                            |
+
+Check out [this video](https://youtube.com/watch?v=VKrpPAHlisY) for a demonstration.
+
+Note: For versions older than 0.6.117, The mode numbers were written directly. In `quantum/rgblight.h` there is a contrast table between the old mode number and the current symbol.
+
+The following options can be used to tweak the various animations:
+
+|Define                              |Default      |Description                                                                          |
+|------------------------------------|-------------|-------------------------------------------------------------------------------------|
+|`RGBLIGHT_EFFECT_BREATHING`         |*Not defined*|If defined, enable breathing animation mode.                                         |
+|`RGBLIGHT_EFFECT_RAINBOW_MOOD`      |*Not defined*|If defined, enable rainbow mood animation mode.                                      |
+|`RGBLIGHT_EFFECT_RAINBOW_SWIRL`     |*Not defined*|If defined, enable rainbow swirl animation mode.                                     |
+|`RGBLIGHT_EFFECT_SNAKE`             |*Not defined*|If defined, enable snake animation mode.                                             |
+|`RGBLIGHT_EFFECT_KNIGHT`            |*Not defined*|If defined, enable knight animation mode.                                            |
+|`RGBLIGHT_EFFECT_CHRISTMAS`         |*Not defined*|If defined, enable christmas animation mode.                                         |
+|`RGBLIGHT_EFFECT_STATIC_GRADIENT`   |*Not defined*|If defined, enable static gradient mode.                                             |
+|`RGBLIGHT_EFFECT_RGB_TEST`          |*Not defined*|If defined, enable RGB test animation mode.                                          |
+|`RGBLIGHT_EFFECT_ALTERNATING`       |*Not defined*|If defined, enable alternating animation mode.                                       |
+|`RGBLIGHT_ANIMATIONS`               |*Not defined*|If defined, enables all additional animation modes                                   |
+|`RGBLIGHT_EFFECT_BREATHE_CENTER`    |`1.85`       |Used to calculate the curve for the breathing animation. Valid values are 1.0 to 2.7 |
+|`RGBLIGHT_EFFECT_BREATHE_MAX`       |`255`        |The maximum brightness for the breathing mode. Valid values are 1 to 255             |
+|`RGBLIGHT_EFFECT_SNAKE_LENGTH`      |`4`          |The number of LEDs to light up for the "Snake" animation                             |
+|`RGBLIGHT_EFFECT_KNIGHT_LENGTH`     |`3`          |The number of LEDs to light up for the "Knight" animation                            |
+|`RGBLIGHT_EFFECT_KNIGHT_OFFSET`     |`0`          |The number of LEDs to start the "Knight" animation from the start of the strip by    |
+|`RGBLIGHT_EFFECT_KNIGHT_LED_NUM`    |`RGBLED_NUM` |The number of LEDs to have the "Knight" animation travel                             |
+|`RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL`|`1000`       |How long to wait between light changes for the "Christmas" animation, in milliseconds|
+|`RGBLIGHT_EFFECT_CHRISTMAS_STEP`    |`2`          |The number of LEDs to group the red/green colors by for the "Christmas" animation    |
+
+You can also modify the speeds that the different modes animate at:
+
+```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};
+
+// How long (in milliseconds) to wait between animation steps for each of the "Cycling rainbow" animations
+const uint8_t RGBLED_RAINBOW_MOOD_INTERVALS[] PROGMEM = {120, 60, 30};
+
+// How long (in milliseconds) to wait between animation steps for each of the "Swirling rainbow" animations
+const uint8_t RGBLED_RAINBOW_SWIRL_INTERVALS[] PROGMEM = {100, 50, 20};
+
+// How long (in milliseconds) to wait between animation steps for each of the "Snake" animations
+const uint8_t RGBLED_SNAKE_INTERVALS[] PROGMEM = {100, 50, 20};
+
+// How long (in milliseconds) to wait between animation steps for each of the "Knight" animations
+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};
+```
+
+## Functions
+
+If you need to change your RGB lighting in code, for example in a macro to change the color whenever you switch layers, QMK provides a set of functions to assist you. See [`rgblight.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight.h) for the full list, but the most commonly used functions include:
+
+|Function                           |Description                                                                                                                                                            |
+|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+|`rgblight_enable()`                |Turn LEDs on, based on their previous state                                                                                                                            |
+|`rgblight_enable_noeeprom()`       |Turn LEDs on, based on their previous state (not written to EEPROM)                                                                                                    |
+|`rgblight_disable()`               |Turn LEDs off                                                                                                                                                          |
+|`rgblight_disable_noeeprom()`      |Turn LEDs off (not written to EEPROM)                                                                                                                                  |
+|`rgblight_mode(x)`                 |Set the mode, if RGB animations are enabled                                                                                                                            |
+|`rgblight_mode_noeeprom(x)`        |Set the mode, if RGB animations are enabled (not written to EEPROM)                                                                                                    |
+|`rgblight_setrgb(r, g, b)`         |Set all LEDs to the given RGB value where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM)                                                                    |
+|`rgblight_setrgb_at(r, g, b, led)` |Set a single LED to the given RGB value, where `r`/`g`/`b` are between 0 and 255 and `led` is between 0 and `RGBLED_NUM` (not written to EEPROM)                       |
+|`rgblight_sethsv(h, s, v)`         |Set all LEDs to the given HSV value where `h` is between 0 and 360 and `s`/`v` are between 0 and 255                                                                   |
+|`rgblight_sethsv_noeeprom(h, s, v)`|Set all LEDs to the given HSV value where `h` is between 0 and 360 and `s`/`v` are between 0 and 255 (not written to EEPROM)                                           |
+|`rgblight_sethsv_at(h, s, v, led)` |Set a single LED to the given HSV value, where `h` is between 0 and 360, `s`/`v` are between 0 and 255, and `led` is between 0 and `RGBLED_NUM` (not written to EEPROM)|
+
+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!
 
 ## Hardware Modification
 
-![Planck with RGB Underglow](https://raw.githubusercontent.com/qmk/qmk_firmware/3774a7fcdab5544fc787f4c200be05fcd417e31f/keyboards/planck/keymaps/yang/planck-with-rgb-underglow.jpg)
-
-Here is a quick demo on Youtube (with NPKC KC60) (https://www.youtube.com/watch?v=VKrpPAHlisY).
-
-For this mod, you need an unused pin wiring to DI of WS2812 strip. After wiring the VCC, GND, and DI, you can enable the underglow in your Makefile.
-
-    RGBLIGHT_ENABLE = yes
-
-In order to use the underglow animation functions, you need to have `#define RGBLIGHT_ANIMATIONS` in your `config.h`.
-
-Please add the following options into your config.h, and set them up according your hardware configuration. These settings are for the `F4` pin by default:
-
-    #define RGB_DI_PIN F4     // The pin your RGB strip is wired to
-    #define RGBLED_NUM 14     // Number of LEDs
-
-You'll need to edit `RGB_DI_PIN` to the pin you have your `DI` on your RGB strip wired to.
+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

@@ -1,24 +0,0 @@
-## Space Cadet Shift: The Future, Built In
-
-Steve Losh [described](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) the Space Cadet Shift quite well. Essentially, you hit the left Shift on its own, and you get an opening parenthesis; hit the right Shift on its own, and you get the closing one. When hit with other keys, the Shift key keeps working as it always does. Yes, it's as cool as it sounds.
-
-To use it, use `KC_LSPO` (Left Shift, Parenthesis Open) for your left Shift on your keymap, and `KC_RSPC` (Right Shift, Parenthesis Close) for your right Shift.
-
-It's defaulted to work on US keyboards, but if your layout uses different keys for parenthesis, you can define those in your `config.h` like this:
-
-    #define LSPO_KEY KC_9
-    #define RSPC_KEY KC_0
-
-You can also choose between different rollover behaviors of the shift keys by defining:
-
-    #define DISABLE_SPACE_CADET_ROLLOVER
-
-in your `config.h`. Disabling rollover allows 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.
-
-The only other thing you're going to want to do is create a `Makefile` in your keymap directory and set the following:
-
-```
-COMMAND_ENABLE   = no  # Commands for debug and configuration
-```
-
-This is just to keep the keyboard from going into command mode when you hold both Shift keys at the same time.

docs/feature_space_cadet_shift.md

@@ -0,0 +1,33 @@
+# 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.
+
+|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              |
+|`DISABLE_SPACE_CADET_ROLLOVER`|*Not defined*|If defined, use the opposite Shift key to cancel Space Cadet|

docs/feature_space_cadet_shift_enter.md

@@ -0,0 +1,31 @@
+# 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_space_shift_cadet.md

@@ -1,26 +0,0 @@
-## Space Cadet Shift Enter: The future, built in
-
-Based on the Space Cadet Shift by Steve Losh [described](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) 
-Essentially, you hit the Shift on its own, and it acts as the enter key. When hit with other keys, the Shift key keeps working as it always does. Yes, it's as cool as it sounds. This solution works better than using a macro since the timers defined in quantum allow us to tell when another key is pressed, rather than just having a janky timer than results in accidental endlines. 
-
-To use it, use `KC_SFTENT` (Shift, Enter) for any Shift on your keymap.
-
-It's defaulted to work on US keyboards, but if you'd like to use a different key for Enter, you can define those in your `config.h` like this:
-
-    #define SFTENT_KEY KC_ENT
-
-
-The only other thing you're going to want to do is create a `rules.mk` in your keymap directory and set the following:
-
-```
-COMMAND_ENABLE   = no  # Commands for debug and configuration
-```
-
-This is just to keep the keyboard from going into command mode when you hold both Shift keys at the same time.
-
-
-
-
-
-PLEASE NOTE: this feature uses the same timers as the Space Cadet Shift feature, so using them in tandem may produce unwanted results. 
-

docs/feature_swap_hands.md

@@ -22,9 +22,9 @@ Note that the array indices are reversed same as the matrix and the values are o
 |Key        |Description                                                              |
 |-----------|-------------------------------------------------------------------------|
 |`SH_T(key)`|Sends `key` with a tap; momentary swap when held.                        |
-|`SW_ON`    |Turns on swapping and leaves it on.                                      |
-|`SW_OFF`   |Turn off swapping and leaves it off. Good for returning to a known state.|
-|`SW_MON`   |Swaps hands when pressed, returns to normal when released (momentary).   |
-|`SW_MOFF`  |Momentarily turns off swap.                                              |
+|`SH_ON`    |Turns on swapping and leaves it on.                                      |
+|`SH_OFF`   |Turn off swapping and leaves it off. Good for returning to a known state.|
+|`SH_MON`   |Swaps hands when pressed, returns to normal when released (momentary).   |
+|`SH_MOFF`  |Momentarily turns off swap.                                              |
 |`SH_TG`    |Toggles swap on and off with every key press.                            |
 |`SH_TT`    |Toggles with a tap; momentary when held.                                 |

docs/feature_tap_dance.md

@@ -26,6 +26,8 @@ This array specifies what actions shall be taken when a tap-dance key is in acti
 
 The first option is enough for a lot of cases, that just want dual roles. For example, `ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT)` will result in `Space` being sent on single-tap, `Enter` otherwise.
 
+!> Keep in mind that only [basic keycodes](keycodes_basic.md) are supported here. Custom keycodes are not supported.
+
 And that's the bulk of it!
 
 And now, on to the explanation of how it works!
@@ -196,22 +198,20 @@ SRC += your_name.c
 Pretty simple. It is a nice way to keep some rules common on all your keymaps.
 
 
-### In `/qmk_firmware/users/<your_name>/<you_name>.h`
+### In `/qmk_firmware/users/<your_name>/<your_name>.h`
 
 You will need a few things in this file:
 
 ```c
-#ifndef YOUR_NAME
-#define YOUR_NAME
+#pragma once
 
 #include "quantum.h"
 #include "process_keycode/process_tap_dance.h"
 
-
 typedef struct {
   bool is_press_action;
   int state;
-} xtap;
+} tap;
 
 enum {
   SINGLE_TAP = 1,
@@ -225,9 +225,9 @@ enum {
 
 //Tap dance enums
 enum {
-    CTL_X = 0,
-    SOME_OTHER_DANCE
-}
+  X_CTL = 0,
+  SOME_OTHER_DANCE
+};
 
 int cur_dance (qk_tap_dance_state_t *state);
 
@@ -241,7 +241,7 @@ void x_reset (qk_tap_dance_state_t *state, void *user_data);
 And then in your user's `.c` file you implement the functions above:
 
 ```c
-#include "gordon.h"
+#include "<your_name>.h"
 #include "quantum.h"
 #include "action.h"
 #include "process_keycode/process_tap_dance.h"
@@ -335,4 +335,4 @@ qk_tap_dance_action_t tap_dance_actions[] = {
 };
 ```
 
-And then simply use TD(X_CTL) anywhere in your keymap.
+And then simply use `TD(X_CTL)` anywhere in your keymap after including `<your_name>.h`.

docs/feature_unicode.md

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

docs/feature_userspace.md

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

docs/features.md

@@ -3,22 +3,27 @@
 QMK has a staggering number of features for building your keyboard. It can take some time to understand all of them and determine which one will achieve your goal.
 
 
-* [Advanced Keycodes](feature_advanced_keycodes.md) - Change layers, type shifted keys, and more. Go beyond typing simple characters.
+* [Advanced Keycodes](feature_advanced_keycodes.md) - Change layers, dual-action keys, and more. Go beyond typing simple characters.
 * [Audio](feature_audio.md) - Connect a speaker to your keyboard for audio feedback, midi support, and music mode.
 * [Auto Shift](feature_auto_shift.md) - Tap for the normal key, hold slightly longer for its shifted state.
 * [Backlight](feature_backlight.md) - LED lighting support for your keyboard.
 * [Bootmagic](feature_bootmagic.md) - Adjust the behavior of your keyboard using hotkeys.
+* [Combos](feature_combos.md) - Custom actions for multiple key holds.
+* [Command](feature_command.md) - Runtime version of bootmagic (Formerly known as "Magic").
 * [Dynamic Macros](feature_dynamic_macros.md) - Record and playback macros from the keyboard itself.
+* [Grave Escape](feature_grave_esc.md) - Lets you use a single key for Esc and Grave. 
+* [HD44780 LCD Display](feature_hd44780.md) - Support for LCD character displays using the HD44780 standard.
 * [Key Lock](feature_key_lock.md) - Lock a key in the "down" state.
 * [Layouts](feature_layouts.md) - Use one keymap with any keyboard that supports your layout.
 * [Leader Key](feature_leader_key.md) - Tap the leader key followed by a sequence to trigger custom behavior.
 * [Macros](feature_macros.md) - Send multiple key presses when pressing only one physical key.
 * [Mouse keys](feature_mouse_keys.md) - Control your mouse pointer from your keyboard.
+* [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys) - Sticky Keys, lets hit a key rather than holding it.
 * [Pointing Device](feature_pointing_device.md) - Framework for connecting your custom pointing device to your keyboard.
 * [PS2 Mouse](feature_ps2_mouse.md) - Driver for connecting a PS/2 mouse directly to your keyboard.
 * [RGB Light](feature_rgblight.md) - RGB lighting for your keyboard.
 * [RGB Matrix](feature_rgb_matrix.md) - RGB Matrix lights for per key lighting.
-* [Space Cadet](feature_space_cadet.md) - Use your left/right shift keys to type parenthesis and brackets.
+* [Space Cadet](feature_space_cadet_shift.md) - Use your left/right shift keys to type parenthesis and brackets.
 * [Stenography](feature_stenography.md) - Put your keyboard into Plover mode for stenography use.
 * [Swap Hands](feature_swap_hands.md) - Mirror your keyboard for one handed usage.
 * [Tap Dance](feature_tap_dance.md) - Make a single key do as many things as you want.

docs/flashing.md

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

docs/getting_started_build_tools.md

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

docs/getting_started_getting_help.md

@@ -4,13 +4,7 @@ There are a lot of resources for getting help with QMK.
 
 ## Realtime Chat
 
-You can find QMK developers and users on our main [gitter chat room](https://gitter.im/qmk/qmk_firmware). We also have other rooms for more specific discussion:
-
-* [Main Firmware Chat](https://gitter.im/qmk/qmk_firmware)
-* [QMK Toolbox](https://gitter.im/qmk/qmk_toolbox)
-* [Hardware Design Discussion](https://gitter.im/qmk/qmk_hardware)
-* [Web Configurator](https://gitter.im/qmk/qmk_configurator)
-* [Compiler API](https://gitter.im/qmk/qmk_compiler_api)
+You can find QMK developers and users on our main [Discord server](https://discord.gg/Uq7gcHh). There are specific channels in the server for chatting about the firmware, Toolbox, hardware, and configurator.
 
 ## OLKB Subreddit
 

docs/getting_started_github.md

@@ -8,7 +8,7 @@ Start on the [QMK Github page](https://github.com/qmk/qmk_firmware), and you'll
 
 ![Fork on Github](http://i.imgur.com/8Toomz4.jpg)
 
-If you're apart of an organization, you'll need to choose which account to fork it to. In most circumstances, you'll want to fork it to your personal account. Once your fork is completed (sometimes this takes a little while), click the "Clone or Download" button:
+If you're a part of an organization, you'll need to choose which account to fork it to. In most circumstances, you'll want to fork it to your personal account. Once your fork is completed (sometimes this takes a little while), click the "Clone or Download" button:
 
 ![Download from Github](http://i.imgur.com/N1NYcSz.jpg)
 
@@ -19,8 +19,7 @@ And be sure to select "HTTPS", and select the link and copy it:
 From here, enter `git clone ` into the command line, and then paste your link:
 
 ```
-**[terminal]
-**[prompt you@computer]**[path ~]**[delimiter  $ ]**[command git clone https://github.com/whoeveryouare/qmk_firmware.git]
+user@computer:~$ git clone https://github.com/whoeveryouare/qmk_firmware.git
 Cloning into 'qmk_firmware'...
 remote: Counting objects: 46625, done.
 remote: Compressing objects: 100% (2/2), done.
@@ -33,13 +32,12 @@ Checking out files: 100% (2799/2799), done.
 You now have your QMK fork on your local machine, and you can add your keymap, compile it and flash it to your board. Once you're happy with your changes, you can add, commit, and push them to your fork like this:
 
 ```
-**[terminal]
-**[prompt you@computer]**[path ~/qmk_firmware]**[delimiter  $ ]**[command git add .]
-**[prompt you@computer]**[path ~/qmk_firmware]**[delimiter  $ ]**[command git commit -m "adding my keymap"]
+user@computer:~$ git add .
+user@computer:~$ git commit -m "adding my keymap"
 [master cccb1608] adding my keymap
  1 file changed, 1 insertion(+)
  create mode 100644 keyboards/planck/keymaps/mine/keymap.c
-**[prompt you@computer]**[path ~/qmk_firmware]**[delimiter  $ ]**[command git push]
+user@computer:~$ git push
 Counting objects: 1, done.
 Delta compression using up to 4 threads.
 Compressing objects: 100% (1/1), done.

docs/getting_started_introduction.md

@@ -6,12 +6,16 @@ This page attempts to explain the basic information you need to know to work wit
 
 QMK is a fork of [Jun Wako](https://github.com/tmk)'s [tmk_keyboard](https://github.com/tmk/tmk_keyboard) project. The original TMK code, with modifications, can be found in the `tmk` folder. The QMK additions to the project may be found in the `quantum` folder. Keyboard projects may be found in the `handwired` and `keyboard` folders.
 
+### Userspace Structure
+
+Within the folder `users` is a directory for each user. This is a place for users to put code that they might use between keyboards. See the docs for [Userspace feature](feature_userspace.md) for more information.
+
 ### Keyboard Project Structure
 
 Within the folder `keyboards` and its subfolder `handwired` is a directory for each keyboard project, for example `qmk_firmware/keyboards/clueboard`. Within it you'll find the following structure:
 
 * `keymaps/`: Different keymaps that can be built
-* `rules.mk`: The file that sets the default "make" options. Do not edit this file directly, instead use a keymap specific `Makefile`
+* `rules.mk`: The file that sets the default "make" options. Do not edit this file directly, instead use a keymap specific `rules.mk`.
 * `config.h`: The file that sets the default compile time options. Do not edit this file directly, instead use a keymap specific `config.h`.
 
 ### Keymap Structure
@@ -25,23 +29,26 @@ In every keymap folder, the following files may be found. Only `keymap.c` is req
 
 # The `config.h` File
 
-There are 2 `config.h` locations:
+There are 3 possible `config.h` locations:
 
 * keyboard (`/keyboards/<keyboard>/config.h`)
+* userspace (`/users/<user>/config.h`)
 * keymap (`/keyboards/<keyboard>/keymaps/<keymap>/config.h`)
 
-If the keymap `config.h` exists, that file is included by the build system and the keyboard `config.h` is not included. If you wish to override settings in your keymap's `config.h` you will need to include some glue code:
+The build system automatically picks up the config files in the above order. If you wish to override any setting set by a previous `config.h` you will need to first include some boilerplate code for the settings you wish to change.
 
 ```
-#ifndef CONFIG_USER_H
-#define CONFIG_USER_H
-
-#include "config_common.h"
+#pragma once
 ```
 
-If you want to override a setting from the parent `config.h` file, you need to `#undef` and then `#define` the setting again, like this:
+Then to override a setting from the previous `config.h` file you must `#undef` and then `#define` the setting again.
 
-```c
+The boilerplate code and setting look like this together:
+
+```
+#pragma once
+
+// overrides go here!
 #undef MY_SETTING
 #define MY_SETTING 4
 ```

docs/getting_started_make_guide.md

@@ -133,6 +133,10 @@ This consumes about 5390 bytes.
 
 This enables [key lock](feature_key_lock.md). This consumes an additional 260 bytes.
 
+`SPLIT_KEYBOARD`
+
+This 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
+
 ## Customizing Makefile Options on a Per-Keymap Basis
 
 If your keymap directory has a file called `rules.mk` any options you set in that file will take precedence over other `rules.mk` options for your particular keyboard.

docs/hardware_avr.md

@@ -8,7 +8,7 @@ If you have not yet you should read the [Keyboard Guidelines](hardware_keyboard_
 
 QMK has a number of features to simplify working with AVR keyboards. For most keyboards you don't have to write a single line of code. To get started run the `util/new_project.sh` script:
 
-```
+```bash
 $ util/new_project.sh my_awesome_keyboard
 ######################################################
 # /keyboards/my_awesome_keyboard project created. To start
@@ -30,7 +30,7 @@ This is where all the custom logic for your keyboard goes. Many keyboards do not
 
 This is the file you define your [Layout Macro(s)](feature_layouts.md) in. At minimum you should have a `#define LAYOUT` for your keyboard that looks something like this:
 
-```
+```c
 #define LAYOUT(          \
       k00, k01, k02,     \
       k10,   k11         \
@@ -57,7 +57,7 @@ At the top of the `config.h` you'll find USB related settings. These control how
 
 Do change the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` lines to accurately reflect your keyboard.
 
-```
+```c
 #define VENDOR_ID       0xFEED
 #define PRODUCT_ID      0x6060
 #define DEVICE_VER      0x0001
@@ -66,20 +66,20 @@ Do change the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` lines to accurately r
 #define DESCRIPTION     A custom keyboard
 ```
 
-?> Note: On Windows and macOS the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` fields will be displayed in the list of USB devices. On Linux these values will not be visible in `lsusb`, since Linux takes that information from the list published by the USB-IF.
+?> Note: On Windows and macOS the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` fields will be displayed in the list of USB devices. ?> On Linux these values will not be visible in lsusb by default, since Linux takes the information from the list maintained by [USB ID Repository](http://www.linux-usb.org/usb-ids.html) by default. lsusb will show the information reported by the device when executed with -v option. It is also present in kernel logs after plugging in the device.
 
 ### Keyboard Matrix Configuration
 
 The next section of the `config.h` file deals with your keyboard's matrix. The first thing you should set is the matrix's size. This is usually, but not always, the same number of rows and columns as the physical key arrangement.
 
-```
+```c
 #define MATRIX_ROWS 2
 #define MATRIX_COLS 3
 ```
 
 Once you've defined the size of your matrix you need to define which pins on your MCU are connected to rows and columns. To do so simply specify the names of those pins:
 
-```
+```c
 #define MATRIX_ROW_PINS { D0, D5 }
 #define MATRIX_COL_PINS { F1, F0, B0 }
 #define UNUSED_PINS
@@ -89,7 +89,7 @@ The number of `MATRIX_ROW_PINS` entries must be the same as the number you assig
 
 Finally, you can specify the direction your diodes point. This can be `COL2ROW`, `ROW2COL`, or `CUSTOM_MATRIX`.
 
-```
+```c
 #define DIODE_DIRECTION COL2ROW
 ```
 
@@ -97,16 +97,14 @@ Finally, you can specify the direction your diodes point. This can be `COL2ROW`,
 
 By default QMK supports backlighting on pins `B5`, `B6`, and `B7`. If you are using one of those you can simply enable it here. For more details see the [Backlight Documentation](feature_backlight.md).
 
-```
+```c
 #define BACKLIGHT_PIN B7
 #define BACKLIGHT_LEVELS 3
 #define BACKLIGHT_BREATHING
 #define BREATHING_PERIOD 6
 ```
 
-{% hint style='info' %}
-You can use backlighting on any pin you like, but you will have to do more work to support that. See the [Backlight Documentation](feature_backlight.md) for more details.
-{% endhint %}
+?> You can use backlighting on any pin you like, but you will have to do more work to support that. See the [Backlight Documentation](feature_backlight.md) for more details.
 
 ### Other Configuration Options
 
@@ -120,7 +118,7 @@ You use the `rules.mk` file to tell QMK what files to build and what features to
 
 These options tell the build system what CPU to build for. Be very careful if you change any of these settings, you can render your keyboard inoperable.
 
-```
+```make
 MCU = atmega32u4
 F_CPU = 16000000
 ARCH = AVR8
@@ -128,26 +126,26 @@ F_USB = $(F_CPU)
 OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT
 ```
 
-### Bootloader Size
+### Bootloaders
 
-The bootloader is a special section of your MCU that allows you to upgrade the code stored on the MCU. Think of it like a Rescue Partition for your keyboard. If you are using a teensy 2.0, or a device like the Ergodox EZ that uses the teensy bootloader you should set this to `512`. Most other bootloaders should be set to `4096`, but `1024` and `2048` are other possible values you may encounter.
+The bootloader is a special section of your MCU that allows you to upgrade the code stored on the MCU. Think of it like a Rescue Partition for your keyboard. 
 
-#### Teensy 2.0 Bootloader Example
+#### Teensy Bootloader Example
 
-```
-OPT_DEFS += -DBOOTLOADER_SIZE=512
-```
-
-#### Teensy 2.0++ Bootloader Example
-
-```
-OPT_DEFS += -DBOOTLOADER_SIZE=1024
+```make
+BOOTLOADER = halfkay
 ```
 
 #### Atmel DFU Loader Example
 
+```make
+BOOTLOADER = atmel-dfu
 ```
-OPT_DEFS += -DBOOTLOADER_SIZE=4096
+
+#### Pro Micro Bootloader Example
+
+```make
+BOOTLOADER = caterina
 ```
 
 ### Build Options

docs/hardware_drivers.md

@@ -25,3 +25,11 @@ You can make use of uGFX within QMK to drive character and graphic LCD's, LED ar
 ## WS2812 (AVR Only)
 
 Support for WS2811/WS2812{a,b,c} LED's. For more information see the [RGB Light](feature_rgblight.md) page.
+
+## IS31FL3731
+
+Support for up to 2 drivers. Each driver impliments 2 charlieplex matrices to individually address LEDs using I2C. This allows up to 144 same color LEDs or 32 RGB LEDs. For more information on how to setup the driver see the [RGB Matrix](feature_rgb_matrix.md) page.
+
+## IS31FL3733
+
+Support for up to a single driver with room for expansion. Each driver can control 192 individual LEDs or 64 RGB LEDs. For more information on how to setup the driver see the [RGB Matrix](feature_rgb_matrix.md) page.

docs/how_keyboards_work.md

@@ -27,17 +27,17 @@ This usually happens with a periodic scan of key presses. This speed often is li
 
 ## 2. What the Firmware Sends
 
-The [HID specification](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) tells what a keyboard can actually send through USB to have a chance to be properly recognised. This includes a pre-defined list of scancodes which are simple numbers from `0x00` to `0xE7`. The firmware assigns a scancode to each key of the keyboard.
+The [HID specification](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf) tells what a keyboard can actually send through USB to have a chance to be properly recognised. This includes a pre-defined list of scancodes which are simple numbers from `0x00` to `0xE7`. The firmware assigns a scancode to each key of the keyboard.
 
-The firmware does not send actually letters or characters, but only scancodes.
-Thus, by modifying the firmware, you only can modify what scancode is sent over
+The firmware does not send actual letters or characters, but only scancodes.
+Thus, by modifying the firmware, you can only modify what scancode is sent over
 USB for a given key.
 
 ## 3. What the Operating System Does
 
 Once the keycode reaches the operating system, a piece of software has to have
 it match an actual character thanks to a keyboard layout. For example, if your
-layout is set to QWERTY, a sample of the matching table is as follow:
+layout is set to QWERTY, a sample of the matching table is as follows:
 
 | keycode | character |
 |---------|-----------|
@@ -55,11 +55,11 @@ As the layout is generally fixed (unless you create your own), the firmware can
 
 ## List of Characters You Can Send
 
-Putting aside shortcuts, having a limited set of keycodes mapped to a limited layout means that **the list of characters you can assign to a given key only is the ones present in the layout**.
+Putting aside shortcuts, having a limited set of keycodes mapped to a limited layout means that **the list of characters you can assign to a given key are only the ones present in the layout**.
 
-For example, this means that if you have a QWERTY US layout, and you want to assign 1 key to produce `€` (euro currency symbol), you are unable to do so, because the QWERTY US layout does not have such mapping. You could fix that by using a QWERTY UK layout, or a QWERTY US International.
+For example, this means that if you have a QWERTY US layout, and you want to assign one key to produce `€` (euro currency symbol), you are unable to do so, because the QWERTY US layout does not have such mapping. You could fix that by using a QWERTY UK layout, or a QWERTY US International.
 
-You may wonder why a keyboard layout containing all of Unicode is not devised then? The limited number of keycode available through USB simply disallow such a thing.
+You may wonder why a keyboard layout containing all of Unicode is not devised then? The limited number of keycodes available through USB simply disallows such a thing.
 
 ## How to (Maybe) Enter Unicode Characters
 

docs/internals_gpio_control.md

@@ -0,0 +1,23 @@
+# GPIO Control
+
+QMK has a GPIO control abstraction layer which is micro-controller agnostic. This is done to allow easy access to pin control across different platforms.
+
+## Functions
+
+The following functions can provide basic control of GPIOs and are found in `quantum/quantum.h`.
+
+|Function              |Description                                                       |
+|----------------------|------------------------------------------------------------------|
+|`setPinInput(pin)`    |Set pin as input with high impedance (High-Z)                     |
+|`setPinInputHigh(pin)`|Set pin as input with build in pull-up                            |
+|`setPinInputLow(pin)` |Set pin as input with build in pull-down (Supported only on STM32)|
+|`setPinOutput(pin)`   |Set pin as output                                                 |
+|`writePinHigh(pin)`   |Set pin level as high, assuming it is an output                   |
+|`writePinLow(pin)`    |Set pin level as low, assuming it is an output                    |
+|`writePin(pin, level)`|Set pin level, assuming it is an output                           |
+|`readPin(pin)`        |Returns the level of the pin                                      |
+
+## Advance settings
+
+Each micro-controller can have multiple advance settings regarding its GPIO. This abstraction layer does not limit the use of architecture specific functions. Advance users should consult the datasheet of there desired device and include any needed libraries. For AVR the standard avr/io.h library is used and for STM32 the Chibios [PAL library](http://chibios.sourceforge.net/docs3/hal/group___p_a_l.html) is used.
+

docs/isp_flashing_guide.md

@@ -19,58 +19,79 @@ If you're having trouble flashing/erasing your board, and running into cryptic e
     Memory write error, use debug for more info.
     commands.c:360: Error writing memory data. (err -4)
 
-You're likely going to need to ISP flash your board/device to get it working again. Luckily, this process is pretty straight-forward, provided you have any extra programmable keyboard, Arduino, or Teensy 2.0/Teensy 2.0++. There are also dedicated ISP flashers available for this, but most cost >$15, and it's assumed that if you are googling this error, this is the first you've heard about ISP flashing, and don't have one readily available (whereas you might have some other AVR board). __We'll be using a Teensy 2.0 with Windows 10 in this guide__ - if you are comfortable doing this on another system, please consider editing this guide and contributing those instructions!
+You're likely going to need to ISP flash your board/device to get it working again. Luckily, this process is pretty straight-forward, provided you have any extra programmable keyboard, Pro Micro, or Teensy 2.0/Teensy 2.0++. There are also dedicated ISP flashers available for this, but most cost >$15, and it's assumed that if you are googling this error, this is the first you've heard about ISP flashing, and don't have one readily available (whereas you might have some other AVR board). __We'll be using a Teensy 2.0 or Pro Micro with Windows 10 in this guide__ - if you are comfortable doing this on another system, please consider editing this guide and contributing those instructions!   
 
 ## Software Needed
 
-* [The Arduino IDE](https://www.arduino.cc/en/Main/Software)
-* [Teensyduino](https://www.pjrc.com/teensy/td_download.html) (if you're using a Teensy)
-* [WinAVR](http://www.ladyada.net/learn/avr/setup-win.html) (Windows)
+* [Teensy Loader](https://www.pjrc.com/teensy/loader.html) (if using a Teensy)
+* QMK Toolbox (flash as usual - be sure to select the correct MCU) or `avrdude` via [WinAVR](http://www.ladyada.net/learn/avr/setup-win.html) (for Teensy & Pro Micro)
 
 ## Wiring
 
 This is pretty straight-forward - we'll be connecting like-things to like-things in the following manner:
 
-    Flasher B0  <-> Keyboard RESET
-    Flasher B1  <-> Keyboard B1 (SCLK)
-    Flasher B2  <-> Keyboard B2 (MOSI)
-    Flasher B3  <-> Keyboard B3 (MISO)
-    Flasher VCC <-> Keyboard VCC
-    Flasher GND <-> Keyboard GND
+### Teensy 2.0
 
-## The ISP Firmware
+    Teensy B0  <-> Keyboard RESET
+    Teensy B1  <-> Keyboard B1 (SCLK)
+    Teensy B2  <-> Keyboard B2 (MOSI)
+    Teensy B3  <-> Keyboard B3 (MISO)
+    Teensy VCC <-> Keyboard VCC
+    Teensy GND <-> Keyboard GND
+    
+### Pro Micro
+
+    Pro Micro 10 (B6)  <-> Keyboard RESET
+    Pro Micro 15 (B1)  <-> Keyboard B1 (SCLK)
+    Pro Micro 16 (B2)  <-> Keyboard B2 (MOSI)
+    Pro Micro 14 (B3)  <-> Keyboard B3 (MISO)
+    Pro Micro VCC      <-> Keyboard VCC
+    Pro Micro GND      <-> Keyboard GND
+
+## The ISP Firmware (now pre-compiled)
+
+The only difference between the .hex files below is which pin is connected to RESET. You can use them on other boards as well, as long as you're aware of the pins being used. If for some reason neither of these pins are available, [create an issue](https://github.com/qmk/qmk_firmware/issues/new), and we can generate one for you!
+
+* Teensy 2.0: [`util/teensy_2.0_ISP_B0.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/teensy_2.0_ISP_B0.hex) (`B0`)
+* Pro Micro: [`util/pro_micro_ISP_B6_10.hex`](https://github.com/qmk/qmk_firmware/blob/master/util/pro_mico_ISP_B6_10.hex) (`B6/10`)
+
+**Flash your Teenys/Pro Micro with one of these and continue - you won't need the file after flashing your ISP device.**
+
+## Just the Bootloader File
+
+If you just want to get things back to normal, you can flash only a bootloader from [`util/` folder](https://github.com/qmk/qmk_firmware/tree/master/util), and use your normal process to flash the firmware afterwards. Be sure to flash the correct bootloader for your chip:
+
+* [`atmega32u4`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32u4_1_0_0.hex) - Most keyboards, Planck Rev 1-5, Preonic Rev 1-2
+* [`at90usb1286`](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_at90usb128x_1_0_1.hex) - Planck Light Rev 1
+
+If you're not sure what your board uses, look in the `rules.mk` file for the keyboard in QMK. The `MCU =` line will have the value you need. It may differ between different versions of the board.
+
+### Advanced/Production Techniques
+
+If you'd like to flash both the bootloader **and** the regular firmware at the same time, you need to combine the files. 
+
+1. Open the original firmware .hex file in a text editor
+2. Remove the last line (which should be `:00000001FF` - this is an EOF message)
+3. Copy the entire bootloader's contents onto a new line (with no empty lines between) and paste it at the end of the original file
+4. Save it as a new file by naming it `<keyboard>_<keymap>_production.hex`
+
+It's possible to use other bootloaders here in the same way, but __you need a bootloader__, otherwise you'll have to use ISP again to write new firmware to your keyboard.
+
+## Flashing Your Bootloader/Production File
 
 Make sure your keyboard is unplugged from any device, and plug in your Teensy.
 
-1. Run Arduino after you have everything installed
-2. Select `Tools > Board * > Teensy 2.0`
-3. Click `File > Examples > 11.ArduinoISP > ArduinoISP`
+### QMK Toolbox
 
-Then scroll down until you see something that looks like this block of code:
+1. `AVRISP device connected` will show up in yellow
+2. Select the correct bootloader/production .hex file with the `Open` dialog (spaces can't be in the path)
+3. Be sure the correct `Microcontroller` option is selected
+4. Hit `Flash`
+5. Wait, as nothing will output for a while, especially with production files
 
-    // Configure which pins to use:
+If the verification and fuse checks are ok, you're done! Your board may restart automatically, otherwise, unplug your Teensy and plug in your keyboard - you can leave your Teensy wired to your keyboard while testing things, but it's recommended that you desolder it/remove the wiring once you're sure everything works.
 
-    // The standard pin configuration.
-    #ifndef ARDUINO_HOODLOADER2
-
-    #define RESET     0  // Use 0 (B0) instead of 10
-    #define LED_HB    11 // Use 11 (LED on the Teensy 2.0)
-    #define LED_ERR   8  // This won't be used unless you have an LED hooked-up to 8 (D3)
-    #define LED_PMODE 7  // This won't be used unless you have an LED hooked-up to 7 (D2)
-
-And make the changes in the last four lines. If you're using something besides the Teensy 2.0, you'll want to choose something else that makes sense for `LED_HB`. We define `RESET` as `0`/`B0` because that's what's close - if you want to use another pin for some reason, [you can use the pinouts to choose something else](https://www.pjrc.com/teensy/pinout.html).
-
-Once you've made your changes, you can click the Upload button (right arrow), which will open up the Teensy flasher app - you'll need to press the reset button on the Teensy the first time, but after that, it's automatic (you shouldn't be flashing this more than once, though). Once flashed, the orange LED on the Teensy will flash on and off, indicating it's ready for some action.
-
-## The `.hex` File
-
-Before flashing your firmware, you're going to need to and do a little preparation. We'll be appending [this bootloader (also a .hex file)](https://github.com/qmk/qmk_firmware/blob/master/util/bootloader_atmega32u4_1_0_0.hex) to the end of our firmware by opening the original .hex file in a text editor, and removing the last line, which should be `:00000001FF` (this is an EOF message). After that's been removed, copy the entire bootloader's contents and paste it at the end of the original file, and save it.
-
-It's possible to use other bootloaders here in the same way, but __you need a bootloader__, otherwise you'll have to ISP to write new firmware to your keyboard.
-
-## Flashing Your Firmware
-
-Make sure your keyboard is unplugged from any device, and plug in your Teensy.
+### Command Line
 
 Open `cmd` and navigate to your where your modified .hex file is. We'll pretend this file is called `main.hex`, and that your Teensy 2.0 is on the `COM3` port - if you're unsure, you can open your Device Manager, and look for `Ports > USB Serial Device`. Use that COM port here. You can confirm it's the right port with:
 

docs/keycodes.md

@@ -8,40 +8,8 @@ This is a reference only. Each group of keys links to the page documenting their
 
 |Key                    |Aliases             |Description                                    |
 |-----------------------|--------------------|-----------------------------------------------|
-|`KC_1`                 |                    |`1` and `!`                                    |
-|`KC_2`                 |                    |`2` and `@`                                    |
-|`KC_3`                 |                    |`3` and `#`                                    |
-|`KC_4`                 |                    |`4` and `$`                                    |
-|`KC_5`                 |                    |`5` and `%`                                    |
-|`KC_6`                 |                    |`6` and `^`                                    |
-|`KC_7`                 |                    |`7` and `&`                                    |
-|`KC_8`                 |                    |`8` and `*`                                    |
-|`KC_9`                 |                    |`9` and `(`                                    |
-|`KC_0`                 |                    |`0` and `)`                                    |
-|`KC_F1`                |                    |                                               |
-|`KC_F2`                |                    |                                               |
-|`KC_F3`                |                    |                                               |
-|`KC_F4`                |                    |                                               |
-|`KC_F5`                |                    |                                               |
-|`KC_F6`                |                    |                                               |
-|`KC_F7`                |                    |                                               |
-|`KC_F8`                |                    |                                               |
-|`KC_F9`                |                    |                                               |
-|`KC_F10`               |                    |                                               |
-|`KC_F11`               |                    |                                               |
-|`KC_F12`               |                    |                                               |
-|`KC_F13`               |                    |                                               |
-|`KC_F14`               |                    |                                               |
-|`KC_F15`               |                    |                                               |
-|`KC_F16`               |                    |                                               |
-|`KC_F17`               |                    |                                               |
-|`KC_F18`               |                    |                                               |
-|`KC_F19`               |                    |                                               |
-|`KC_F20`               |                    |                                               |
-|`KC_F21`               |                    |                                               |
-|`KC_F22`               |                    |                                               |
-|`KC_F23`               |                    |                                               |
-|`KC_F24`               |                    |                                               |
+|`KC_NO`                |`XXXXXXX`           |Ignore this key (NOOP)                         |
+|`KC_TRANSPARENT`       |`KC_TRNS`, `_______`|Use the next lowest non-transparent key        |
 |`KC_A`                 |                    |`a` and `A`                                    |
 |`KC_B`                 |                    |`b` and `B`                                    |
 |`KC_C`                 |                    |`c` and `C`                                    |
@@ -68,6 +36,16 @@ This is a reference only. Each group of keys links to the page documenting their
 |`KC_X`                 |                    |`x` and `X`                                    |
 |`KC_Y`                 |                    |`y` and `Y`                                    |
 |`KC_Z`                 |                    |`z` and `Z`                                    |
+|`KC_1`                 |                    |`1` and `!`                                    |
+|`KC_2`                 |                    |`2` and `@`                                    |
+|`KC_3`                 |                    |`3` and `#`                                    |
+|`KC_4`                 |                    |`4` and `$`                                    |
+|`KC_5`                 |                    |`5` and `%`                                    |
+|`KC_6`                 |                    |`6` and `^`                                    |
+|`KC_7`                 |                    |`7` and `&`                                    |
+|`KC_8`                 |                    |`8` and `*`                                    |
+|`KC_9`                 |                    |`9` and `(`                                    |
+|`KC_0`                 |                    |`0` and `)`                                    |
 |`KC_ENTER`             |`KC_ENT`            |Return (Enter)                                 |
 |`KC_ESCAPE`            |`KC_ESC`            |Escape                                         |
 |`KC_BSPACE`            |`KC_BSPC`           |Delete (Backspace)                             |
@@ -79,33 +57,28 @@ This is a reference only. Each group of keys links to the page documenting their
 |`KC_RBRACKET`          |`KC_RBRC`           |`]` and `}`                                    |
 |`KC_BSLASH`            |`KC_BSLS`           |`\` and <code>&#124;</code>                    |
 |`KC_NONUS_HASH`        |`KC_NUHS`           |Non-US `#` and `~`                             |
-|`KC_NONUS_BSLASH`      |`KC_NUBS`           |Non-US `\` and <code>&#124;</code>             |
-|`KC_INT1`              |`KC_RO`             |JIS `\` and <code>&#124;</code>                |
-|`KC_INT2`              |`KC_KANA`           |JIS Katakana/Hiragana                          |
-|`KC_INT3`              |`KC_JYEN`           |JIS `¥`                                        |
 |`KC_SCOLON`            |`KC_SCLN`           |`;` and `:`                                    |
 |`KC_QUOTE`             |`KC_QUOT`           |`'` and `"`                                    |
-|`KC_GRAVE`             |`KC_GRV`            |<code>&#96;</code> and `~`                     |
+|`KC_GRAVE`             |`KC_GRV`, `KC_ZKHK` |<code>&#96;</code> and `~`, JIS Zenkaku/Hankaku|
 |`KC_COMMA`             |`KC_COMM`           |`,` and `<`                                    |
 |`KC_DOT`               |                    |`.` and `>`                                    |
 |`KC_SLASH`             |`KC_SLSH`           |`/` and `?`                                    |
-|`KC_CAPSLOCK`          |`KC_CAPS`           |Caps Lock                                      |
-|`KC_LCTRL`             |`KC_LCTL`           |Left Control                                   |
-|`KC_LSHIFT`            |`KC_LSFT`           |Left Shift                                     |
-|`KC_LALT`              |                    |Left Alt                                       |
-|`KC_LGUI`              |`KC_LCMD`, `KC_LWIN`|Left GUI (Windows/Command/Meta key)            |
-|`KC_RCTRL`             |`KC_RCTL`           |Right Control                                  |
-|`KC_RSHIFT`            |`KC_RSFT`           |Right Shift                                    |
-|`KC_RALT`              |                    |Right Alt                                      |
-|`KC_RGUI`              |`KC_RCMD`, `KC_RWIN`|Right GUI (Windows/Command/Meta key)           |
-|`KC_LOCKING_CAPS`      |`KC_LCAP`           |Locking Caps Lock                              |
-|`KC_LOCKING_NUM`       |`KC_LNUM`           |Locking Num Lock                               |
-|`KC_LOCKING_SCROLL`    |`KC_LSCR`           |Locking Scroll Lock                            |
-|`KC_INT4`              |`KC_HENK`           |JIS Henkan                                     |
-|`KC_INT5`              |`KC_MHEN`           |JIS Muhenkan                                   |
+|`KC_CAPSLOCK`          |`KC_CLCK`, `KC_CAPS`|Caps Lock                                      |
+|`KC_F1`                |                    |F1                                             |
+|`KC_F2`                |                    |F2                                             |
+|`KC_F3`                |                    |F3                                             |
+|`KC_F4`                |                    |F4                                             |
+|`KC_F5`                |                    |F5                                             |
+|`KC_F6`                |                    |F6                                             |
+|`KC_F7`                |                    |F7                                             |
+|`KC_F8`                |                    |F8                                             |
+|`KC_F9`                |                    |F9                                             |
+|`KC_F10`               |                    |F10                                            |
+|`KC_F11`               |                    |F11                                            |
+|`KC_F12`               |                    |F12                                            |
 |`KC_PSCREEN`           |`KC_PSCR`           |Print Screen                                   |
 |`KC_SCROLLLOCK`        |`KC_SLCK`           |Scroll Lock                                    |
-|`KC_PAUSE`             |`KC_PAUS`           |Pause                                          |
+|`KC_PAUSE`             |`KC_PAUS`, `KC_BRK` |Pause                                          |
 |`KC_INSERT`            |`KC_INS`            |Insert                                         |
 |`KC_HOME`              |                    |Home                                           |
 |`KC_PGUP`              |                    |Page Up                                        |
@@ -116,57 +89,6 @@ This is a reference only. Each group of keys links to the page documenting their
 |`KC_LEFT`              |                    |Left Arrow                                     |
 |`KC_DOWN`              |                    |Down Arrow                                     |
 |`KC_UP`                |                    |Up Arrow                                       |
-|`KC_APPLICATION`       |`KC_APP`            |Application (Windows Menu Key)                 |
-|`KC_POWER`             |                    |Deprecated by MS in favor of `KC_SYSTEM_POWER`.|
-|`KC_EXECUTE`           |                    |Execute                                        |
-|`KC_HELP`              |                    |Help                                           |
-|`KC_MENU`              |                    |Menu                                           |
-|`KC_SELECT`            |                    |Select                                         |
-|`KC_AGAIN`             |                    |Again                                          |
-|`KC_UNDO`              |                    |Undo                                           |
-|`KC_CUT`               |                    |Cut                                            |
-|`KC_COPY`              |                    |Copy                                           |
-|`KC_PASTE`             |                    |Paste                                          |
-|`KC_FIND`              |                    |Find                                           |
-|`KC_ALT_ERASE`         |                    |Alternate Erase                                |
-|`KC_SYSREQ`            |                    |SysReq/Attention                               |
-|`KC_CANCEL`            |                    |Cancel                                         |
-|`KC_CLEAR`             |                    |Clear                                          |
-|`KC_PRIOR`             |                    |Prior                                          |
-|`KC_RETURN`            |                    |Return                                         |
-|`KC_SEPARATOR`         |                    |Separator                                      |
-|`KC_OUT`               |                    |Out                                            |
-|`KC_OPER`              |                    |Oper                                           |
-|`KC_CLEAR_AGAIN`       |                    |Clear/Again                                    |
-|`KC_CRSEL`             |                    |CrSel/Props                                    |
-|`KC_EXSEL`             |                    |ExSel                                          |
-|`KC_SYSTEM_POWER`      |`KC_PWR`            |System Power Down. Recommended over `KC_POWER`.|
-|`KC_SYSTEM_SLEEP`      |`KC_SLEP`           |System Sleep                                   |
-|`KC_SYSTEM_WAKE`       |`KC_WAKE`           |System Wake                                    |
-|`KC_MAIL`              |`KC_MAIL`           |                                               |
-|`KC_CALCULATOR`        |`KC_CALC`           |                                               |
-|`KC_MY_COMPUTER`       |`KC_MYCM`           |                                               |
-|`KC_WWW_SEARCH`        |`KC_WSCH`           |                                               |
-|`KC_WWW_HOME`          |`KC_WHOM`           |                                               |
-|`KC_WWW_BACK`          |`KC_WBAK`           |                                               |
-|`KC_WWW_FORWARD`       |`KC_WFWD`           |                                               |
-|`KC_WWW_STOP`          |`KC_WSTP`           |                                               |
-|`KC_WWW_REFRESH`       |`KC_WREF`           |                                               |
-|`KC_WWW_FAVORITES`     |`KC_WFAV`           |                                               |
-|`KC_STOP`              |                    |Stop                                           |
-|`KC__MUTE`             |                    |Mute (macOS)                                   |
-|`KC__VOLUP`            |                    |Volume Up (macOS)                              |
-|`KC__VOLDOWN`          |                    |Volume Down (macOS)                            |
-|`KC_AUDIO_MUTE`        |`KC_MUTE`           |Mute (Windows/macOS/Linux)                     |
-|`KC_AUDIO_VOL_UP`      |`KC_VOLU`           |Volume Up (Windows/macOS/Linux)                |
-|`KC_AUDIO_VOL_DOWN`    |`KC_VOLD`           |Volume Down (Windows/macOS/Linux)              |
-|`KC_MEDIA_NEXT_TRACK`  |`KC_MNXT`           |Next Track (Windows)                           |
-|`KC_MEDIA_PREV_TRACK`  |`KC_MPRV`           |Previous Track (Windows)                       |
-|`KC_MEDIA_FAST_FORWARD`|`KC_MFFD`           |Next Track (macOS)                             |
-|`KC_MEDIA_REWIND`      |`KC_MRWD`           |Previous Track (macOS)                         |
-|`KC_MEDIA_STOP`        |`KC_MSTP`           |Stop Track                                     |
-|`KC_MEDIA_PLAY_PAUSE`  |`KC_MPLY`           |Play/Pause Track                               |
-|`KC_MEDIA_SELECT`      |`KC_MSEL`           |                                               |
 |`KC_NUMLOCK`           |`KC_NLCK`           |Keypad Num Lock and Clear                      |
 |`KC_KP_SLASH`          |`KC_PSLS`           |Keypad `/`                                     |
 |`KC_KP_ASTERISK`       |`KC_PAST`           |Keypad `*`                                     |
@@ -184,32 +106,103 @@ This is a reference only. Each group of keys links to the page documenting their
 |`KC_KP_9`              |`KC_P9`             |Keypad `9` and Page Up                         |
 |`KC_KP_0`              |`KC_P0`             |Keypad `0` and Insert                          |
 |`KC_KP_DOT`            |`KC_PDOT`           |Keypad `.` and Delete                          |
+|`KC_NONUS_BSLASH`      |`KC_NUBS`           |Non-US `\` and <code>&#124;</code>             |
+|`KC_APPLICATION`       |`KC_APP`            |Application (Windows Menu Key)                 |
+|`KC_POWER`             |                    |System Power (macOS)                           |
 |`KC_KP_EQUAL`          |`KC_PEQL`           |Keypad `=`                                     |
+|`KC_F13`               |                    |F13                                            |
+|`KC_F14`               |                    |F14                                            |
+|`KC_F15`               |                    |F15                                            |
+|`KC_F16`               |                    |F16                                            |
+|`KC_F17`               |                    |F17                                            |
+|`KC_F18`               |                    |F18                                            |
+|`KC_F19`               |                    |F19                                            |
+|`KC_F20`               |                    |F20                                            |
+|`KC_F21`               |                    |F21                                            |
+|`KC_F22`               |                    |F22                                            |
+|`KC_F23`               |                    |F23                                            |
+|`KC_F24`               |                    |F24                                            |
+|`KC_EXECUTE`           |`KC_EXEC`           |Execute                                        |
+|`KC_HELP`              |                    |Help                                           |
+|`KC_MENU`              |                    |Menu                                           |
+|`KC_SELECT`            |`KC_SLCT`           |Select                                         |
+|`KC_STOP`              |                    |Stop                                           |
+|`KC_AGAIN`             |`KC_AGIN`           |Again                                          |
+|`KC_UNDO`              |                    |Undo                                           |
+|`KC_CUT`               |                    |Cut                                            |
+|`KC_COPY`              |                    |Copy                                           |
+|`KC_PASTE`             |`KC_PSTE`           |Paste                                          |
+|`KC_FIND`              |                    |Find                                           |
+|`KC__MUTE`             |                    |Mute (macOS)                                   |
+|`KC__VOLUP`            |                    |Volume Up (macOS)                              |
+|`KC__VOLDOWN`          |                    |Volume Down (macOS)                            |
+|`KC_LOCKING_CAPS`      |`KC_LCAP`           |Locking Caps Lock                              |
+|`KC_LOCKING_NUM`       |`KC_LNUM`           |Locking Num Lock                               |
+|`KC_LOCKING_SCROLL`    |`KC_LSCR`           |Locking Scroll Lock                            |
 |`KC_KP_COMMA`          |`KC_PCMM`           |Keypad `,`                                     |
 |`KC_KP_EQUAL_AS400`    |                    |Keypad `=` on AS/400 keyboards                 |
-|`KC_NO`                |                    |Ignore this key (NOOP)                         |
-|`KC_TRANSPARENT`       |`KC_TRNS`           |Use the next lowest non-transparent key        |
-
-## [Mouse Keys](feature_mouse_keys.md)
-
-|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|
+|`KC_INT1`              |`KC_RO`             |JIS `\` and <code>&#124;</code>                |
+|`KC_INT2`              |`KC_KANA`           |JIS Katakana/Hiragana                          |
+|`KC_INT3`              |`KC_JYEN`           |JIS `¥`                                        |
+|`KC_INT4`              |`KC_HENK`           |JIS Henkan                                     |
+|`KC_INT5`              |`KC_MHEN`           |JIS Muhenkan                                   |
+|`KC_INT6`              |                    |JIS Numpad `,`                                 |
+|`KC_INT7`              |                    |International 7                                |
+|`KC_INT8`              |                    |International 8                                |
+|`KC_INT9`              |                    |International 9                                |
+|`KC_LANG1`             |`KC_HAEN`           |Hangul/English                                 |
+|`KC_LANG2`             |`KC_HANJ`           |Hanja                                          |
+|`KC_LANG3`             |                    |JIS Katakana                                   |
+|`KC_LANG4`             |                    |JIS Hiragana                                   |
+|`KC_LANG5`             |                    |JIS Zenkaku/Hankaku                            |
+|`KC_LANG6`             |                    |Language 6                                     |
+|`KC_LANG7`             |                    |Language 7                                     |
+|`KC_LANG8`             |                    |Language 8                                     |
+|`KC_LANG9`             |                    |Language 9                                     |
+|`KC_ALT_ERASE`         |`KC_ERAS`           |Alternate Erase                                |
+|`KC_SYSREQ`            |                    |SysReq/Attention                               |
+|`KC_CANCEL`            |                    |Cancel                                         |
+|`KC_CLEAR`             |`KC_CLR`            |Clear                                          |
+|`KC_PRIOR`             |                    |Prior                                          |
+|`KC_RETURN`            |                    |Return                                         |
+|`KC_SEPARATOR`         |                    |Separator                                      |
+|`KC_OUT`               |                    |Out                                            |
+|`KC_OPER`              |                    |Oper                                           |
+|`KC_CLEAR_AGAIN`       |                    |Clear/Again                                    |
+|`KC_CRSEL`             |                    |CrSel/Props                                    |
+|`KC_EXSEL`             |                    |ExSel                                          |
+|`KC_LCTRL`             |`KC_LCTL`           |Left Control                                   |
+|`KC_LSHIFT`            |`KC_LSFT`           |Left Shift                                     |
+|`KC_LALT`              |                    |Left Alt                                       |
+|`KC_LGUI`              |`KC_LCMD`, `KC_LWIN`|Left GUI (Windows/Command/Meta key)            |
+|`KC_RCTRL`             |`KC_RCTL`           |Right Control                                  |
+|`KC_RSHIFT`            |`KC_RSFT`           |Right Shift                                    |
+|`KC_RALT`              |                    |Right Alt                                      |
+|`KC_RGUI`              |`KC_RCMD`, `KC_RWIN`|Right GUI (Windows/Command/Meta key)           |
+|`KC_SYSTEM_POWER`      |`KC_PWR`            |System Power Down                              |
+|`KC_SYSTEM_SLEEP`      |`KC_SLEP`           |System Sleep                                   |
+|`KC_SYSTEM_WAKE`       |`KC_WAKE`           |System Wake                                    |
+|`KC_AUDIO_MUTE`        |`KC_MUTE`           |Mute                                           |
+|`KC_AUDIO_VOL_UP`      |`KC_VOLU`           |Volume Up                                      |
+|`KC_AUDIO_VOL_DOWN`    |`KC_VOLD`           |Volume Down                                    |
+|`KC_MEDIA_NEXT_TRACK`  |`KC_MNXT`           |Next Track (Windows)                           |
+|`KC_MEDIA_PREV_TRACK`  |`KC_MPRV`           |Previous Track (Windows)                       |
+|`KC_MEDIA_STOP`        |`KC_MSTP`           |Stop Track (Windows)                           |
+|`KC_MEDIA_PLAY_PAUSE`  |`KC_MPLY`           |Play/Pause Track                               |
+|`KC_MEDIA_SELECT`      |`KC_MSEL`           |Launch Media Player (Windows)                  |
+|`KC_MEDIA_EJECT`       |`KC_EJCT`           |Eject (macOS)                                  |
+|`KC_MAIL`              |                    |Launch Mail (Windows)                          |
+|`KC_CALCULATOR`        |`KC_CALC`           |Launch Calculator (Windows)                    |
+|`KC_MY_COMPUTER`       |`KC_MYCM`           |Launch My Computer (Windows)                   |
+|`KC_WWW_SEARCH`        |`KC_WSCH`           |Browser Search (Windows)                       |
+|`KC_WWW_HOME`          |`KC_WHOM`           |Browser Home (Windows)                         |
+|`KC_WWW_BACK`          |`KC_WBAK`           |Browser Back (Windows)                         |
+|`KC_WWW_FORWARD`       |`KC_WFWD`           |Browser Forward (Windows)                      |
+|`KC_WWW_STOP`          |`KC_WSTP`           |Browser Stop (Windows)                         |
+|`KC_WWW_REFRESH`       |`KC_WREF`           |Browser Refresh (Windows)                      |
+|`KC_WWW_FAVORITES`     |`KC_WFAV`           |Browser Favorites (Windows)                    |
+|`KC_MEDIA_FAST_FORWARD`|`KC_MFFD`           |Next Track (macOS)                             |
+|`KC_MEDIA_REWIND`      |`KC_MRWD`           |Previous Track (macOS)                         |
 
 ## [Quantum Keycodes](quantum_keycodes.md#qmk-keycodes)
 
@@ -226,6 +219,36 @@ This is a reference only. Each group of keys links to the page documenting their
 |`M(n)`       |           |Call macro `n`                                                       |
 |`MACROTAP(n)`|           |Macro-tap `n` idk FIXME                                              |
 
+## [Audio Keys](feature_audio.md)
+
+|Key             |Aliases  |Description                       |
+|----------------|---------|----------------------------------|
+|`AU_ON`         |         |Audio mode on                     |
+|`AU_OFF`        |         |Audio mode off                    |
+|`AU_TOG`        |         |Toggles Audio mode                |
+|`CLICKY_TOGGLE` |`CK_TOGG`|Toggles Audio clicky mode         |
+|`CLICKY_UP`     |`CK_UP`  |Increases frequency of the clicks |
+|`CLICKY_DOWN`   |`CK_DOWN`|Decreases frequency of the clicks |
+|`CLICKY_RESET`  |`CK_RST` |Resets frequency to default       |
+|`MU_ON`         |         |Turns on Music Mode               |
+|`MU_OFF`        |         |Turns off Music Mode              |
+|`MU_TOG`        |         |Toggles Music Mode                |
+|`MU_MOD`        |         |Cycles through the music modes    |
+
+
+
+## [Backlighting](feature_backlight.md)
+
+|Key      |Description                               |
+|---------|------------------------------------------|
+|`BL_TOGG`|Turn the backlight on or off              |
+|`BL_STEP`|Cycle through backlight levels            |
+|`BL_ON`  |Set the backlight to max brightness       |
+|`BL_OFF` |Turn the backlight off                    |
+|`BL_INC` |Increase the backlight level              |
+|`BL_DEC` |Decrease the backlight level              |
+|`BL_BRTG`|Toggle backlight breathing                |
+
 ## [Bootmagic](feature_bootmagic.md)
 
 |Key                               |Aliases  |Description                         |
@@ -248,19 +271,90 @@ This is a reference only. Each group of keys links to the page documenting their
 |`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|         |Unswap `\` and Backspace            |
 |`MAGIC_UNHOST_NKRO`               |         |Force NKRO off                      |
 |`MAGIC_UNSWAP_ALT_GUI`            |`AG_NORM`|Unswap Alt and GUI on both sides    |
+|`MAGIC_TOGGLE_ALT_GUI`            |`AG_TOGG`|Toggle Alt and GUI swap on both sides|
 |`MAGIC_TOGGLE_NKRO`               |         |Turn NKRO on or off                 |
 
-## [Backlighting](feature_backlight.md)
+## [Bluetooth](feature_bluetooth.md)
 
-|Key      |Description                               |
-|---------|------------------------------------------|
-|`BL_TOGG`|Turn the backlight on or off              |
-|`BL_STEP`|Cycle through backlight levels            |
-|`BL_ON`  |Set the backlight to max brightness       |
-|`BL_OFF` |Turn the backlight off                    |
-|`BL_INC` |Increase the backlight level              |
-|`BL_DEC` |Decrease the backlight level              |
-|`BL_BRTG`|Toggle backlight breathing                |
+|Key       |Description                                   |
+|----------|----------------------------------------------|
+|`OUT_AUTO`|Automatically switch between USB and Bluetooth|
+|`OUT_USB` |USB only                                      |
+|`OUT_BT`  |Bluetooth only                                |
+
+
+## [Layer Switching](feature_advanced_keycodes.md#switching-and-toggling-layers)
+
+|Key         |Description                                                               |
+|-----------------|---------------------------------------------------------------------|
+|`DF(layer)`      |Switches the default layer                                           |
+|`MO(layer)`      |Momentarily activates layer, switches off when you let go            |
+|`LM(layer, mod)` |As `MO(layer)` but with `mod` active                                 |
+|`LT(layer, kc)`  |Momentarily activates layer if held, sends kc if tapped              |
+|`TG(layer)`      |Toggles the layer (enables it if no active, and vise versa)          |
+|`TO(layer)`      |Activates layer and deactivates all other layers                     |
+|`TT(layer)`      |Momentarily activates layer if held, toggles it if tapped repeatedly |
+
+## [Mouse Keys](feature_mouse_keys.md)
+
+|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|
+
+## [Modifiers](feature_advanced_keycodes.md#modifier-keys)
+
+|Key       |Aliases               |Description                                         |
+|----------|----------------------|----------------------------------------------------|
+|`KC_HYPR` |                      |Hold Left Control, Shift, Alt and GUI               |
+|`KC_MEH`  |                      |Hold Left Control, Shift and Alt                    |
+|`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`            |
+
+## [Mod-Tap Keys](feature_advanced_keycodes.md#mod-tap)
+
+|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       |
 
 ## [RGB Lighting](feature_rgblight.md)
 
@@ -308,80 +402,31 @@ This is a reference only. Each group of keys links to the page documenting their
 |`PRINT_ON` |Start printing everything the user types|
 |`PRINT_OFF`|Stop printing everything the user types |
 
-## [Bluetooth](feature_bluetooth.md)
+## [US ANSI Shifted Symbols](keycodes_us_ansi_shifted.md)
 
-|Key       |Description                                   |
-|----------|----------------------------------------------|
-|`OUT_AUTO`|Automatically switch between USB and Bluetooth|
-|`OUT_USB` |USB only                                      |
-|`OUT_BT`  |Bluetooth only                                |
-
-## [Modifiers](quantum_keycodes.md#modifiers)
-
-|Key       |Aliases               |Description                                         |
-|----------|----------            |----------------------------------------------------|
-|`KC_HYPR` |                      |Hold Left Control, Shift, Alt and GUI               |
-|`KC_MEH`  |                      |Hold Left Control, Shift and Alt                    |
-|`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`       |
-|`ALTG(kc)`|                      |Hold Right Control and Alt and press `kc`           |
-|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)`|Hold Left Shift and GUI and press `kc`              |
-|`LCA(kc)` |                      |Hold Left Control and Alt and press `kc`            |
-
-## [Mod-Tap Keys](quantum_keycodes.md#mod-tap-keys)
-
-|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/)|
-|`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       |
-
-## [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
-
-|Key                     |Aliases           |Description        |
-|------------------------|------------------|-------------------|
-|`KC_TILDE`              |`KC_TILD`         |`~`                |
-|`KC_EXCLAIM`            |`KC_EXLM`         |`!`                |
-|`KC_AT`                 |                  |`@`                |
-|`KC_HASH`               |                  |`#`                |
-|`KC_DOLLAR`             |`KC_DLR`          |`$`                |
-|`KC_PERCENT`            |`KC_PERC`         |`%`                |
-|`KC_CIRCUMFLEX`         |`KC_CIRC`         |`^`                |
-|`KC_AMPERSAND`          |`KC_AMPR`         |`&`                |
-|`KC_ASTERISK`           |`KC_ASTR`         |`*`                |
-|`KC_LEFT_PAREN`         |`KC_LPRN`         |`(`                |
-|`KC_RIGHT_PAREN`        |`KC_RPRN`         |`)`                |
-|`KC_UNDERSCORE`         |`KC_UNDS`         |`_`                |
-|`KC_PLUS`               |                  |`+`                |
-|`KC_LEFT_CURLY_BRACE`   |`KC_LCBR`         |`{`                |
-|`KC_RIGHT_CURLY_BRACE`  |`KC_RCBR`         |`}`                |
-|`KC_PIPE`               |                  |<code>&#124;</code>|
-|`KC_COLON`              |`KC_COLN`         |`:`                |
-|`KC_DOUBLE_QUOTE`       |`KC_DQT`/`KC_DQUO`|`"`                |
-|`KC_LEFT_ANGLE_BRACKET` |`KC_LT`/`KC_LABK` |`<`                |
-|`KC_RIGHT_ANGLE_BRACKET`|`KC_GT`/`KC_RABK` |`>`                |
-|`KC_QUESTION`           |`KC_QUES`         |`?`                |
+|Key                     |Aliases            |Description        |
+|------------------------|-------------------|-------------------|
+|`KC_TILDE`              |`KC_TILD`          |`~`                |
+|`KC_EXCLAIM`            |`KC_EXLM`          |`!`                |
+|`KC_AT`                 |                   |`@`                |
+|`KC_HASH`               |                   |`#`                |
+|`KC_DOLLAR`             |`KC_DLR`           |`$`                |
+|`KC_PERCENT`            |`KC_PERC`          |`%`                |
+|`KC_CIRCUMFLEX`         |`KC_CIRC`          |`^`                |
+|`KC_AMPERSAND`          |`KC_AMPR`          |`&`                |
+|`KC_ASTERISK`           |`KC_ASTR`          |`*`                |
+|`KC_LEFT_PAREN`         |`KC_LPRN`          |`(`                |
+|`KC_RIGHT_PAREN`        |`KC_RPRN`          |`)`                |
+|`KC_UNDERSCORE`         |`KC_UNDS`          |`_`                |
+|`KC_PLUS`               |                   |`+`                |
+|`KC_LEFT_CURLY_BRACE`   |`KC_LCBR`          |`{`                |
+|`KC_RIGHT_CURLY_BRACE`  |`KC_RCBR`          |`}`                |
+|`KC_PIPE`               |                   |<code>&#124;</code>|
+|`KC_COLON`              |`KC_COLN`          |`:`                |
+|`KC_DOUBLE_QUOTE`       |`KC_DQUO`, `KC_DQT`|`"`                |
+|`KC_LEFT_ANGLE_BRACKET` |`KC_LABK`, `KC_LT` |`<`                |
+|`KC_RIGHT_ANGLE_BRACKET`|`KC_RABK`, `KC_GT` |`>`                |
+|`KC_QUESTION`           |`KC_QUES`          |`?`                |
 
 ## [Switching and Toggling Layers](feature_advanced_keycodes.md#switching-and-toggling-layers)
 
@@ -395,19 +440,13 @@ This is a reference only. Each group of keys links to the page documenting their
 |`TT(layer)`     |Normally acts like MO unless it's tapped multiple times, which toggles `layer` on |
 |`LM(layer, mod)`|Momentarily turn on `layer` (like MO) with `mod` active as well.                  |
 
-## [One Shot Keys](quantum_keycodes.md#one-shot-keys)
+## [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
 
 |Key         |Description                       |
 |------------|----------------------------------|
 |`OSM(mod)`  |Hold `mod` for one keypress       |
 |`OSL(layer)`|Switch to `layer` for one keypress|
 
-## [Unicode Support](feature_unicode.md)
-
-|Key         |Aliases|                                                 |
-|------------|-------|-------------------------------------------------|
-|`UNICODE(n)`|`UC(n)`|Send Unicode character `n`                       |
-|`X(n)`      |       |Send Unicode character `n` via a different method|
 
 ## [Swap Hands](feature_swap_hands.md)
 
@@ -420,3 +459,9 @@ This is a reference only. Each group of keys links to the page documenting their
 |`SH_MOFF`  |Momentarily turns off swap.                                              |
 |`SH_TG`    |Toggles swap on and off with every key press.                            |
 |`SH_TT`    |Toggles with a tap; momentary when held.                                 |
+## [Unicode Support](feature_unicode.md)
+
+|Key         |Aliases|                                                 |
+|------------|-------|-------------------------------------------------|
+|`UNICODE(n)`|`UC(n)`|Send Unicode character `n`                       |
+|`X(n)`      |       |Send Unicode character `n` via a different method|

docs/keycodes_basic.md

@@ -1,6 +1,6 @@
 # Basic Keycodes
 
-The basic set of keycodes are based on the [HID Keyboard/Keypad Usage Page (0x07)](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) with the exception of `KC_NO`, `KC_TRNS` and keycodes in the `0xA5-DF` range. See below for more details.
+The basic set of keycodes are based on the [HID Keyboard/Keypad Usage Page (0x07)](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf) with the exception of `KC_NO`, `KC_TRNS` and keycodes in the `0xA5-DF` range. See below for more details.
 
 ## Letters and Numbers
 
@@ -47,117 +47,145 @@ The basic set of keycodes are based on the [HID Keyboard/Keypad Usage Page (0x07
 
 |Key     |Description|
 |--------|-----------|
-|`KC_F1` |           |
-|`KC_F2` |           |
-|`KC_F3` |           |
-|`KC_F4` |           |
-|`KC_F5` |           |
-|`KC_F6` |           |
-|`KC_F7` |           |
-|`KC_F8` |           |
-|`KC_F9` |           |
-|`KC_F10`|           |
-|`KC_F11`|           |
-|`KC_F12`|           |
-|`KC_F13`|           |
-|`KC_F14`|           |
-|`KC_F15`|           |
-|`KC_F16`|           |
-|`KC_F17`|           |
-|`KC_F18`|           |
-|`KC_F19`|           |
-|`KC_F20`|           |
-|`KC_F21`|           |
-|`KC_F22`|           |
-|`KC_F23`|           |
-|`KC_F24`|           |
+|`KC_F1` |F1         |
+|`KC_F2` |F2         |
+|`KC_F3` |F3         |
+|`KC_F4` |F4         |
+|`KC_F5` |F5         |
+|`KC_F6` |F6         |
+|`KC_F7` |F7         |
+|`KC_F8` |F8         |
+|`KC_F9` |F9         |
+|`KC_F10`|F10        |
+|`KC_F11`|F11        |
+|`KC_F12`|F12        |
+|`KC_F13`|F13        |
+|`KC_F14`|F14        |
+|`KC_F15`|F15        |
+|`KC_F16`|F16        |
+|`KC_F17`|F17        |
+|`KC_F18`|F18        |
+|`KC_F19`|F19        |
+|`KC_F20`|F20        |
+|`KC_F21`|F21        |
+|`KC_F22`|F22        |
+|`KC_F23`|F23        |
+|`KC_F24`|F24        |
 
 ## Punctuation
 
-|Key              |Aliases  |Description                       |
-|-----------------|---------|----------------------------------|
-|`KC_ENTER`       |`KC_ENT` |Return (Enter)                    |
-|`KC_ESCAPE`      |`KC_ESC` |Escape                            |
-|`KC_BSPACE`      |`KC_BSPC`|Delete (Backspace)                |
-|`KC_TAB`         |         |Tab                               |
-|`KC_SPACE`       |`KC_SPC` |Spacebar                          |
-|`KC_MINUS`       |`KC_MINS`|`-` and `_`                       |
-|`KC_EQUAL`       |`KC_EQL` |`=` and `+`                       |
-|`KC_LBRACKET`    |`KC_LBRC`|`[` and `{`                       |
-|`KC_RBRACKET`    |`KC_RBRC`|`]` and `}`                       |
-|`KC_BSLASH`      |`KC_BSLS`|`\` and <code>&#124;</code>       |
-|`KC_NONUS_HASH`  |`KC_NUHS`|Non-US `#` and `~`                |
-|`KC_NONUS_BSLASH`|`KC_NUBS`|Non-US `\` and <code>&#124;</code>|
-|`KC_INT1`        |`KC_RO`  |JIS `\` and <code>&#124;</code>   |
-|`KC_INT2`        |`KC_KANA`|JIS Katakana/Hiragana             |
-|`KC_INT3`        |`KC_JYEN`|JIS `¥`                           |
-|`KC_SCOLON`      |`KC_SCLN`|`;` and `:`                       |
-|`KC_QUOTE`       |`KC_QUOT`|`'` and `"`                       |
-|`KC_GRAVE`       |`KC_GRV` |<code>&#96;</code> and `~`        |
-|`KC_COMMA`       |`KC_COMM`|`,` and `<`                       |
-|`KC_DOT`         |         |`.` and `>`                       |
-|`KC_SLASH`       |`KC_SLSH`|`/` and `?`                       |
-|`KC_CAPSLOCK`    |`KC_CAPS`|Caps Lock                         |
+|Key              |Aliases            |Description                                    |
+|-----------------|-------------------|-----------------------------------------------|
+|`KC_ENTER`       |`KC_ENT`           |Return (Enter)                                 |
+|`KC_ESCAPE`      |`KC_ESC`           |Escape                                         |
+|`KC_BSPACE`      |`KC_BSPC`          |Delete (Backspace)                             |
+|`KC_TAB`         |                   |Tab                                            |
+|`KC_SPACE`       |`KC_SPC`           |Spacebar                                       |
+|`KC_MINUS`       |`KC_MINS`          |`-` and `_`                                    |
+|`KC_EQUAL`       |`KC_EQL`           |`=` and `+`                                    |
+|`KC_LBRACKET`    |`KC_LBRC`          |`[` and `{`                                    |
+|`KC_RBRACKET`    |`KC_RBRC`          |`]` and `}`                                    |
+|`KC_BSLASH`      |`KC_BSLS`          |`\` and <code>&#124;</code>                    |
+|`KC_NONUS_HASH`  |`KC_NUHS`          |Non-US `#` and `~`                             |
+|`KC_SCOLON`      |`KC_SCLN`          |`;` and `:`                                    |
+|`KC_QUOTE`       |`KC_QUOT`          |`'` and `"`                                    |
+|`KC_GRAVE`       |`KC_GRV`, `KC_ZKHK`|<code>&#96;</code> and `~`, JIS Zenkaku/Hankaku|
+|`KC_COMMA`       |`KC_COMM`          |`,` and `<`                                    |
+|`KC_DOT`         |                   |`.` and `>`                                    |
+|`KC_SLASH`       |`KC_SLSH`          |`/` and `?`                                    |
+|`KC_NONUS_BSLASH`|`KC_NUBS`          |Non-US `\` and <code>&#124;</code>             |
+
+## Lock Keys
+
+|Key                |Aliases             |Description              |
+|-------------------|--------------------|-------------------------|
+|`KC_CAPSLOCK`      |`KC_CLCK`, `KC_CAPS`|Caps Lock                |
+|`KC_SCROLLLOCK`    |`KC_SLCK`           |Scroll Lock              |
+|`KC_NUMLOCK`       |`KC_NLCK`           |Keypad Num Lock and Clear|
+|`KC_LOCKING_CAPS`  |`KC_LCAP`           |Locking Caps Lock        |
+|`KC_LOCKING_NUM`   |`KC_LNUM`           |Locking Num Lock         |
+|`KC_LOCKING_SCROLL`|`KC_LSCR`           |Locking Scroll Lock      |
 
 ## Modifiers
 
-|Key                |Aliases             |Description                         |
-|-------------------|--------------------|------------------------------------|
-|`KC_LCTRL`         |`KC_LCTL`           |Left Control                        |
-|`KC_LSHIFT`        |`KC_LSFT`           |Left Shift                          |
-|`KC_LALT`          |                    |Left Alt                            |
-|`KC_LGUI`          |`KC_LCMD`, `KC_LWIN`|Left GUI (Windows/Command/Meta key) |
-|`KC_RCTRL`         |`KC_RCTL`           |Right Control                       |
-|`KC_RSHIFT`        |`KC_RSFT`           |Right Shift                         |
-|`KC_RALT`          |                    |Right Alt                           |
-|`KC_RGUI`          |`KC_RCMD`, `KC_RWIN`|Right GUI (Windows/Command/Meta key)|
-|`KC_LOCKING_CAPS`  |`KC_LCAP`           |Locking Caps Lock                   |
-|`KC_LOCKING_NUM`   |`KC_LNUM`           |Locking Num Lock                    |
-|`KC_LOCKING_SCROLL`|`KC_LSCR`           |Locking Scroll Lock                 |
-|`KC_INT4`          |`KC_HENK`           |JIS Henkan                          |
-|`KC_INT5`          |`KC_MHEN`           |JIS Muhenkan                        |
+|Key        |Aliases             |Description                         |
+|-----------|--------------------|------------------------------------|
+|`KC_LCTRL` |`KC_LCTL`           |Left Control                        |
+|`KC_LSHIFT`|`KC_LSFT`           |Left Shift                          |
+|`KC_LALT`  |                    |Left Alt                            |
+|`KC_LGUI`  |`KC_LCMD`, `KC_LWIN`|Left GUI (Windows/Command/Meta key) |
+|`KC_RCTRL` |`KC_RCTL`           |Right Control                       |
+|`KC_RSHIFT`|`KC_RSFT`           |Right Shift                         |
+|`KC_RALT`  |                    |Right Alt                           |
+|`KC_RGUI`  |`KC_RCMD`, `KC_RWIN`|Right GUI (Windows/Command/Meta key)|
+
+## International
+
+|Key       |Aliases  |Description                    |
+|----------|---------|-------------------------------|
+|`KC_INT1` |`KC_RO`  |JIS `\` and <code>&#124;</code>|
+|`KC_INT2` |`KC_KANA`|JIS Katakana/Hiragana          |
+|`KC_INT3` |`KC_JYEN`|JIS `¥`                        |
+|`KC_INT4` |`KC_HENK`|JIS Henkan                     |
+|`KC_INT5` |`KC_MHEN`|JIS Muhenkan                   |
+|`KC_INT6` |         |JIS Numpad `,`                 |
+|`KC_INT7` |         |International 7                |
+|`KC_INT8` |         |International 8                |
+|`KC_INT9` |         |International 9                |
+|`KC_LANG1`|`KC_HAEN`|Hangul/English                 |
+|`KC_LANG2`|`KC_HANJ`|Hanja                          |
+|`KC_LANG3`|         |JIS Katakana                   |
+|`KC_LANG4`|         |JIS Hiragana                   |
+|`KC_LANG5`|         |JIS Zenkaku/Hankaku            |
+|`KC_LANG6`|         |Language 6                     |
+|`KC_LANG7`|         |Language 7                     |
+|`KC_LANG8`|         |Language 8                     |
+|`KC_LANG9`|         |Language 9                     |
 
 ## Commands
 
-|Key               |Aliases  |Description                   |
-|------------------|---------|------------------------------|
-|`KC_PSCREEN`      |`KC_PSCR`|Print Screen                  |
-|`KC_SCROLLLOCK`   |`KC_SLCK`|Scroll Lock                   |
-|`KC_PAUSE`        |`KC_PAUS`|Pause                         |
-|`KC_INSERT`       |`KC_INS` |Insert                        |
-|`KC_HOME`         |         |Home                          |
-|`KC_PGUP`         |         |Page Up                       |
-|`KC_DELETE`       |`KC_DEL` |Forward Delete                |
-|`KC_END`          |         |End                           |
-|`KC_PGDOWN`       |`KC_PGDN`|Page Down                     |
-|`KC_RIGHT`        |`KC_RGHT`|Right Arrow                   |
-|`KC_LEFT`         |         |Left Arrow                    |
-|`KC_DOWN`         |         |Down Arrow                    |
-|`KC_UP`           |         |Up Arrow                      |
-|`KC_APPLICATION`  |`KC_APP` |Application (Windows Menu Key)|
-|`KC_POWER`        |         |Power                         |
-|`KC_EXECUTE`      |         |Execute                       |
-|`KC_HELP`         |         |Help                          |
-|`KC_MENU`         |         |Menu                          |
-|`KC_SELECT`       |         |Select                        |
-|`KC_AGAIN`        |         |Again                         |
-|`KC_UNDO`         |         |Undo                          |
-|`KC_CUT`          |         |Cut                           |
-|`KC_COPY`         |         |Copy                          |
-|`KC_PASTE`        |         |Paste                         |
-|`KC_FIND`         |         |Find                          |
-|`KC_ALT_ERASE`    |         |Alternate Erase               |
-|`KC_SYSREQ`       |         |SysReq/Attention              |
-|`KC_CANCEL`       |         |Cancel                        |
-|`KC_CLEAR`        |         |Clear                         |
-|`KC_PRIOR`        |         |Prior                         |
-|`KC_RETURN`       |         |Return                        |
-|`KC_SEPARATOR`    |         |Separator                     |
-|`KC_OUT`          |         |Out                           |
-|`KC_OPER`         |         |Oper                          |
-|`KC_CLEAR_AGAIN`  |         |Clear/Again                   |
-|`KC_CRSEL`        |         |CrSel/Props                   |
-|`KC_EXSEL`        |         |ExSel                         |
+|Key               |Aliases            |Description                   |
+|------------------|-------------------|------------------------------|
+|`KC_PSCREEN`      |`KC_PSCR`          |Print Screen                  |
+|`KC_PAUSE`        |`KC_PAUS`, `KC_BRK`|Pause                         |
+|`KC_INSERT`       |`KC_INS`           |Insert                        |
+|`KC_HOME`         |                   |Home                          |
+|`KC_PGUP`         |                   |Page Up                       |
+|`KC_DELETE`       |`KC_DEL`           |Forward Delete                |
+|`KC_END`          |                   |End                           |
+|`KC_PGDOWN`       |`KC_PGDN`          |Page Down                     |
+|`KC_RIGHT`        |`KC_RGHT`          |Right Arrow                   |
+|`KC_LEFT`         |                   |Left Arrow                    |
+|`KC_DOWN`         |                   |Down Arrow                    |
+|`KC_UP`           |                   |Up Arrow                      |
+|`KC_APPLICATION`  |`KC_APP`           |Application (Windows Menu Key)|
+|`KC_POWER`        |                   |System Power (macOS/Linux)    |
+|`KC_EXECUTE`      |`KC_EXEC`          |Execute                       |
+|`KC_HELP`         |                   |Help                          |
+|`KC_MENU`         |                   |Menu                          |
+|`KC_SELECT`       |`KC_SLCT`          |Select                        |
+|`KC_STOP`         |                   |Stop                          |
+|`KC_AGAIN`        |`KC_AGIN`          |Again                         |
+|`KC_UNDO`         |                   |Undo                          |
+|`KC_CUT`          |                   |Cut                           |
+|`KC_COPY`         |                   |Copy                          |
+|`KC_PASTE`        |`KC_PSTE`          |Paste                         |
+|`KC_FIND`         |                   |Find                          |
+|`KC__MUTE`        |                   |Mute (macOS)                  |
+|`KC__VOLUP`       |                   |Volume Up (macOS)             |
+|`KC__VOLDOWN`     |                   |Volume Down (macOS)           |
+|`KC_ALT_ERASE`    |`KC_ERAS`          |Alternate Erase               |
+|`KC_SYSREQ`       |                   |SysReq/Attention              |
+|`KC_CANCEL`       |                   |Cancel                        |
+|`KC_CLEAR`        |`KC_CLR`           |Clear                         |
+|`KC_PRIOR`        |                   |Prior                         |
+|`KC_RETURN`       |                   |Return                        |
+|`KC_SEPARATOR`    |                   |Separator                     |
+|`KC_OUT`          |                   |Out                           |
+|`KC_OPER`         |                   |Oper                          |
+|`KC_CLEAR_AGAIN`  |                   |Clear/Again                   |
+|`KC_CRSEL`        |                   |CrSel/Props                   |
+|`KC_EXSEL`        |                   |ExSel                         |
 
 ## Media Keys
 
@@ -165,41 +193,37 @@ These keycodes are not part of the Keyboard/Keypad usage page. The `SYSTEM_` key
 
 Windows and macOS use different keycodes for "next track" and "previous track". Make sure you choose the keycode that corresponds to your OS.
 
-|Key                    |Aliases  |Description                      |
-|-----------------------|---------|---------------------------------|
-|`KC_SYSTEM_POWER`      |`KC_PWR` |System Power Down                |
-|`KC_SYSTEM_SLEEP`      |`KC_SLEP`|System Sleep                     |
-|`KC_SYSTEM_WAKE`       |`KC_WAKE`|System Wake                      |
-|`KC_MAIL`              |`KC_MAIL`|                                 |
-|`KC_CALCULATOR`        |`KC_CALC`|                                 |
-|`KC_MY_COMPUTER`       |`KC_MYCM`|                                 |
-|`KC_WWW_SEARCH`        |`KC_WSCH`|                                 |
-|`KC_WWW_HOME`          |`KC_WHOM`|                                 |
-|`KC_WWW_BACK`          |`KC_WBAK`|                                 |
-|`KC_WWW_FORWARD`       |`KC_WFWD`|                                 |
-|`KC_WWW_STOP`          |`KC_WSTP`|                                 |
-|`KC_WWW_REFRESH`       |`KC_WREF`|                                 |
-|`KC_STOP`              |         |Stop                             |
-|`KC_WWW_FAVORITES`     |`KC_WFAV`|                                 |
-|`KC__MUTE`             |         |Mute (macOS)                     |
-|`KC__VOLUP`            |         |Volume Up (macOS)                |
-|`KC__VOLDOWN`          |         |Volume Down (macOS)              |
-|`KC_AUDIO_MUTE`        |`KC_MUTE`|Mute (Windows/macOS/Linux)       |
-|`KC_AUDIO_VOL_UP`      |`KC_VOLU`|Volume Up (Windows/macOS/Linux)  |
-|`KC_AUDIO_VOL_DOWN`    |`KC_VOLD`|Volume Down (Windows/macOS/Linux)|
-|`KC_MEDIA_NEXT_TRACK`  |`KC_MNXT`|Next Track (Windows)             |
-|`KC_MEDIA_PREV_TRACK`  |`KC_MPRV`|Previous Track (Windows)         |
-|`KC_MEDIA_FAST_FORWARD`|`KC_MFFD`|Next Track (macOS)               |
-|`KC_MEDIA_REWIND`      |`KC_MRWD`|Previous Track (macOS)           |
-|`KC_MEDIA_STOP`        |`KC_MSTP`|Stop Track                       |
-|`KC_MEDIA_PLAY_PAUSE`  |`KC_MPLY`|Play/Pause Track                 |
-|`KC_MEDIA_SELECT`      |`KC_MSEL`|                                 |
+|Key                    |Aliases  |Description                  |
+|-----------------------|---------|-----------------------------|
+|`KC_SYSTEM_POWER`      |`KC_PWR` |System Power Down            |
+|`KC_SYSTEM_SLEEP`      |`KC_SLEP`|System Sleep                 |
+|`KC_SYSTEM_WAKE`       |`KC_WAKE`|System Wake                  |
+|`KC_AUDIO_MUTE`        |`KC_MUTE`|Mute                         |
+|`KC_AUDIO_VOL_UP`      |`KC_VOLU`|Volume Up                    |
+|`KC_AUDIO_VOL_DOWN`    |`KC_VOLD`|Volume Down                  |
+|`KC_MEDIA_NEXT_TRACK`  |`KC_MNXT`|Next Track (Windows)         |
+|`KC_MEDIA_PREV_TRACK`  |`KC_MPRV`|Previous Track (Windows)     |
+|`KC_MEDIA_STOP`        |`KC_MSTP`|Stop Track (Windows)         |
+|`KC_MEDIA_PLAY_PAUSE`  |`KC_MPLY`|Play/Pause Track             |
+|`KC_MEDIA_SELECT`      |`KC_MSEL`|Launch Media Player (Windows)|
+|`KC_MEDIA_EJECT`       |`KC_EJCT`|Eject (macOS)                |
+|`KC_MAIL`              |         |Launch Mail (Windows)        |
+|`KC_CALCULATOR`        |`KC_CALC`|Launch Calculator (Windows)  |
+|`KC_MY_COMPUTER`       |`KC_MYCM`|Launch My Computer (Windows) |
+|`KC_WWW_SEARCH`        |`KC_WSCH`|Browser Search (Windows)     |
+|`KC_WWW_HOME`          |`KC_WHOM`|Browser Home (Windows)       |
+|`KC_WWW_BACK`          |`KC_WBAK`|Browser Back (Windows)       |
+|`KC_WWW_FORWARD`       |`KC_WFWD`|Browser Forward (Windows)    |
+|`KC_WWW_STOP`          |`KC_WSTP`|Browser Stop (Windows)       |
+|`KC_WWW_REFRESH`       |`KC_WREF`|Browser Refresh (Windows)    |
+|`KC_WWW_FAVORITES`     |`KC_WFAV`|Browser Favorites (Windows)  |
+|`KC_MEDIA_FAST_FORWARD`|`KC_MFFD`|Next Track (macOS)           |
+|`KC_MEDIA_REWIND`      |`KC_MRWD`|Previous Track (macOS)       |
 
 ## Number Pad
 
 |Key                |Aliases  |Description                   |
 |-------------------|---------|------------------------------|
-|`KC_NUMLOCK`       |`KC_NLCK`|Keypad Num Lock and Clear     |
 |`KC_KP_SLASH`      |`KC_PSLS`|Keypad `/`                    |
 |`KC_KP_ASTERISK`   |`KC_PAST`|Keypad `*`                    |
 |`KC_KP_MINUS`      |`KC_PMNS`|Keypad `-`                    |
@@ -224,7 +248,7 @@ Windows and macOS use different keycodes for "next track" and "previous track".
 
 In addition to these, keycodes in the range of `0xA5-DF` are reserved for internal use by TMK.
 
-|Key             |Aliases  |Description                            |
-|----------------|---------|---------------------------------------|
-|`KC_NO`         |         |Ignore this key (NOOP)                 |
-|`KC_TRANSPARENT`|`KC_TRNS`|Use the next lowest non-transparent key|
+|Key             |Aliases             |Description                            |
+|----------------|--------------------|---------------------------------------|
+|`KC_NO`         |`XXXXXXX`           |Ignore this key (NOOP)                 |
+|`KC_TRANSPARENT`|`KC_TRNS`, `_______`|Use the next lowest non-transparent key|

docs/keycodes_us_ansi_shifted.md

@@ -1,31 +1,37 @@
 # US ANSI Shifted Symbols
 
-These keycodes correspond to characters that are "shifted" on a standard US ANSI keyboards. They do not have dedicated keycodes but are instead typed by holding down shift and then sending a keycode.
+These keycodes correspond to characters that are "shifted" on a standard US ANSI keyboard. They do not have keycodes of their own but are simply shortcuts for `LSFT(kc)`, and as such send a Left Shift with the unshifted keycode, not the symbol itself.
 
-It's important to remember that all of these keycodes send a left shift - this may cause unintended actions if unaccounted for. The short code is preferred in most situations.
+## Caveats
 
-## US ANSI Shifted Keycodes
+Unfortunately, these keycodes cannot be used in Mod-Taps or Layer-Taps, since any modifiers specified in the keycode are ignored.
 
-|Key                     |Aliases           |Description        |
-|------------------------|------------------|-------------------|
-|`KC_TILDE`              |`KC_TILD`         |`~`                |
-|`KC_EXCLAIM`            |`KC_EXLM`         |`!`                |
-|`KC_AT`                 |                  |`@`                |
-|`KC_HASH`               |                  |`#`                |
-|`KC_DOLLAR`             |`KC_DLR`          |`$`                |
-|`KC_PERCENT`            |`KC_PERC`         |`%`                |
-|`KC_CIRCUMFLEX`         |`KC_CIRC`         |`^`                |
-|`KC_AMPERSAND`          |`KC_AMPR`         |`&`                |
-|`KC_ASTERISK`           |`KC_ASTR`         |`*`                |
-|`KC_LEFT_PAREN`         |`KC_LPRN`         |`(`                |
-|`KC_RIGHT_PAREN`        |`KC_RPRN`         |`)`                |
-|`KC_UNDERSCORE`         |`KC_UNDS`         |`_`                |
-|`KC_PLUS`               |                  |`+`                |
-|`KC_LEFT_CURLY_BRACE`   |`KC_LCBR`         |`{`                |
-|`KC_RIGHT_CURLY_BRACE`  |`KC_RCBR`         |`}`                |
-|`KC_PIPE`               |                  |<code>&#124;</code>|
-|`KC_COLON`              |`KC_COLN`         |`:`                |
-|`KC_DOUBLE_QUOTE`       |`KC_DQT`/`KC_DQUO`|`"`                |
-|`KC_LEFT_ANGLE_BRACKET` |`KC_LT`/`KC_LABK` |`<`                |
-|`KC_RIGHT_ANGLE_BRACKET`|`KC_GT`/`KC_RABK` |`>`                |
-|`KC_QUESTION`           |`KC_QUES`         |`?`                |
+Additionally, you may run into issues when using Remote Desktop Connection on Windows. Because these codes send shift very fast, Remote Desktop may miss the codes.
+
+To fix this, open Remote Desktop Connection, click on "Show Options", open the the "Local Resources" tab. In the keyboard section, change the drop down to "On this Computer". This will fix the issue, and allow the characters to work correctly.
+
+## Keycodes
+
+|Key                     |Aliases            |Description        |
+|------------------------|-------------------|-------------------|
+|`KC_TILDE`              |`KC_TILD`          |`~`                |
+|`KC_EXCLAIM`            |`KC_EXLM`          |`!`                |
+|`KC_AT`                 |                   |`@`                |
+|`KC_HASH`               |                   |`#`                |
+|`KC_DOLLAR`             |`KC_DLR`           |`$`                |
+|`KC_PERCENT`            |`KC_PERC`          |`%`                |
+|`KC_CIRCUMFLEX`         |`KC_CIRC`          |`^`                |
+|`KC_AMPERSAND`          |`KC_AMPR`          |`&`                |
+|`KC_ASTERISK`           |`KC_ASTR`          |`*`                |
+|`KC_LEFT_PAREN`         |`KC_LPRN`          |`(`                |
+|`KC_RIGHT_PAREN`        |`KC_RPRN`          |`)`                |
+|`KC_UNDERSCORE`         |`KC_UNDS`          |`_`                |
+|`KC_PLUS`               |                   |`+`                |
+|`KC_LEFT_CURLY_BRACE`   |`KC_LCBR`          |`{`                |
+|`KC_RIGHT_CURLY_BRACE`  |`KC_RCBR`          |`}`                |
+|`KC_PIPE`               |                   |<code>&#124;</code>|
+|`KC_COLON`              |`KC_COLN`          |`:`                |
+|`KC_DOUBLE_QUOTE`       |`KC_DQUO`, `KC_DQT`|`"`                |
+|`KC_LEFT_ANGLE_BRACKET` |`KC_LABK`, `KC_LT` |`<`                |
+|`KC_RIGHT_ANGLE_BRACKET`|`KC_RABK`, `KC_GT` |`>`                |
+|`KC_QUESTION`           |`KC_QUES`          |`?`                |

docs/keymap.md

@@ -89,11 +89,15 @@ There are 3 main sections of a `keymap.c` file you'll want to concern yourself w
 
 At the top of the file you'll find this:
 
-    #include "clueboard.h"
+    #include QMK_KEYBOARD_H
 
     // Helpful defines
     #define GRAVE_MODS  (MOD_BIT(KC_LSHIFT)|MOD_BIT(KC_RSHIFT)|MOD_BIT(KC_LGUI)|MOD_BIT(KC_RGUI)|MOD_BIT(KC_LALT)|MOD_BIT(KC_RALT))
-    #define _______ KC_TRNS
+
+    /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 
+     *  You can use _______ in place for KC_TRNS (transparent)   *
+     *  Or you can use XXXXXXX for KC_NO (NOOP)                  *
+     * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
     // Each layer gets a name for readability.
     // The underscores don't mean anything - you can
@@ -105,7 +109,9 @@ At the top of the file you'll find this:
     #define _FL 1
     #define _CL 2
 
-These are some handy definitions we can use when building our keymap and our custom function. The `GRAVE_MODS` definition will be used later in our custom function. The `_______` define makes it easier to see what keys a layer is overriding, while the `_BL`, `_FL`, and `_CL` defines make it easier to refer to each of our layers.
+These are some handy definitions we can use when building our keymap and our custom function. The `GRAVE_MODS` definition will be used later in our custom function, and the following `_BL`, `_FL`, and `_CL` defines make it easier to refer to each of our layers.
+
+Note: You may also find some older keymap files may also have a define(s) for `_______` and/or `XXXXXXX`. These can be used in place for `KC_TRNS` and `KC_NO` respectively, making it easier to see what keys a layer is overriding. These definitions are now unecessary, as they are included by default.
 
 ### Layers and Keymaps
 

docs/newbs.md

@@ -1,4 +1,4 @@
-# The Compelete Newbs Guide To QMK
+# The Complete Newbs Guide To QMK
 
 QMK is a powerful Open Source firmware for your mechanical keyboard. You can use QMK to customize your keyboard in ways both simple and powerful. People of all skill levels, from complete newbie to master programmer, have successfully used QMK to customize their keyboard. This guide will help you do the same, no matter your skill level.
 
@@ -6,11 +6,13 @@ Not sure if your keyboard can run QMK? If it's a mechanical keyboard you built y
 
 ## Overview
 
-There are 4 main sections to this guide:
+There are 5 main sections to this guide:
 
 * [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)
+* [Learn More with these Resources](newbs_learn_more_resources.md)
 
 This guide is focused on helping someone who has never compiled software before. It makes choices and recommendations based on that viewpoint. There are alternative methods for many of these procedures, and we support most of those alternatives. If you have any doubt about how to accomplish a task you can [ask us for guidance](getting_started_getting_help.md).

docs/newbs_best_practices.md

@@ -0,0 +1,163 @@
+# Best Practices
+
+## Or, "How I Learned to Stop Worrying and Love Git."
+
+This document aims to instruct novices in the best ways to have a smooth experience in contributing to QMK. We will walk through the process of contributing to QMK, detailing some ways to make this task easier, and then later we'll break some things in order to teach you how to fix them.
+
+This document assumes a few things:
+
+1. You have a GitHub account, and have [forked the qmk_firmware repository](getting_started_github.md) to your account.
+2. You've [set up your build environment](newbs_getting_started.md?id=environment-setup).
+
+
+## Your fork's master: Update Often, Commit Never
+
+It is highly recommended for QMK development, regardless of what is being done or where, to keep your `master` branch updated, but ***never*** commit to it. Instead, do all your changes in a development branch and issue pull requests from your branches when you're developing.
+
+To reduce the chances of merge conflicts — instances where two or more users have edited the same part of a file concurrently — keep your `master` branch relatively up-to-date, and start any new developments by creating a new branch.
+
+### Updating your master branch
+
+To keep your `master` branch updated, it is recommended to add the QMK Firmware repository ("repo") as a remote repository in git. To do this, open your Git command line interface and enter:
+
+```
+git remote add upstream https://github.com/qmk/qmk_firmware.git
+```
+
+To verify that the repository has been added, run `git remote -v`, which should return the following:
+
+```
+$ git remote -v
+origin  https://github.com/<your_username>/qmk_firmware.git (fetch)
+origin  https://github.com/<your_username>/qmk_firmware.git (push)
+upstream        https://github.com/qmk/qmk_firmware.git (fetch)
+upstream        https://github.com/qmk/qmk_firmware.git (push)
+```
+
+Now that this is done, you can check for updates to the repo by running `git fetch upstream`. This retrieves the branches and tags &mdash; collectively referred to as "refs" &mdash; from the QMK repo, which now has the nickname `upstream`. We can now compare the data on our fork `origin` to that held by QMK.
+
+To update your fork's master, run the following, hitting the Enter key after each line:
+
+```
+git checkout master
+git fetch upstream
+git pull upstream master
+git push origin master
+```
+
+This switches you to your `master` branch, retrieves the refs from the QMK repo, downloads the current QMK `master` branch to your computer, and then uploads it to your fork.
+
+### Making Changes
+
+To make changes, create a new branch by entering:
+
+```
+git checkout -b dev_branch
+git push --set-upstream origin dev_branch
+```
+
+This creates a new branch named `dev_branch`, checks it out, and then saves the new branch to your fork. The `--set-upstream` argument tells git to use your fork and the `dev_branch` branch every time you use `git push` or `git pull` from this branch. It only needs to be used on the first push; after that, you can safely use `git push` or `git pull`, without the rest of the arguments.
+
+!> With `git push`, you can use `-u` in place of `--set-upstream` &mdash; `-u` is an alias for `--set-upstream`.
+
+You can name your branch nearly anything you want, though it is recommended to name it something related to the changes you are going to make.
+
+By default `git checkout -b` will base your new branch on the branch that is checked out. You can base your new branch on an existing branch that is not checked out by adding the name of the existing branch to the command:
+
+```
+git checkout -b dev_branch master
+```
+
+Now that you have a development branch, open your text editor and make whatever changes you need to make. It is recommended to make many small commits to your branch; that way, any change that causes issues can be more easily traced and undone if needed. To make your changes, edit and save any files that need to be updated, add them to Git's *staging area*, and then commit them to your branch:
+
+```
+git add path/to/updated_file
+git commit -m "My commit message."
+```
+
+`git add` adds files that have been changed to Git's *staging area*, which is Git's "loading zone." This contains the changes that are going to be *committed* by `git commit`, which saves the changes to the repo. Use descriptive commit messages so you can know what was changed at a glance.
+
+!> If you've changed a lot of files, but all the files are part of the same change, you can use `git add .` to add all the changed files that are in your current directory, rather than having to add each file individually.
+
+### Publishing Your Changes
+
+The last step is to push your changes to your fork. To do this, enter `git push`. Git now publishes the current state of `dev_branch` to your fork.
+
+
+## Resolving Merge Conflicts
+
+Sometimes when your work in a branch takes a long time to complete, changes that have been made by others conflict with changes you have made to your branch when you open a pull request. This is called a *merge conflict*, and is what happens when multiple people edit the same parts of the same files.
+
+### Rebasing Your Changes
+
+A *rebase* is Git's way of taking changes that were applied at one point, reversing them, and then applying the same changes to another point. In the case of a merge conflict, you can rebase your branch to grab the changes that were made between when you created your branch and the present time.
+
+To start, run the following:
+
+```
+git fetch upstream
+git rev-list --left-right --count HEAD...upstream/master
+```
+
+The `git rev-list` command entered here returns the number of commits that differ between the current branch and QMK's master branch. We run `git fetch` first to make sure we have the refs that represent the current state of the upstream repo. The output of the `git rev-list` command entered returns two numbers:
+
+```
+$ git rev-list --left-right --count HEAD...upstream/master
+7       35
+```
+
+The first number represents the number of commits on the current branch since it was created, and the second number is the number of commits made to `upstream/master` since the current branch was created, and thus, the changes that are not recorded in the current branch.
+
+Now that the current states of both the current branch and the upstream repo are known, we can start a rebase operation:
+
+```
+git rebase upstream/master
+```
+
+This tells Git to undo the commits on the current branch, and then reapply them against QMK's master branch.
+
+```
+$ git rebase upstream/master
+First, rewinding head to replay your work on top of it...
+Applying: Commit #1
+Using index info to reconstruct a base tree...
+M       conflicting_file_1.txt
+Falling back to patching base and 3-way merge...
+Auto-merging conflicting_file_1.txt
+CONFLICT (content): Merge conflict in conflicting_file_1.txt
+error: Failed to merge in the changes.
+hint: Use 'git am --show-current-patch' to see the failed patch
+Patch failed at 0001 Commit #1
+
+Resolve all conflicts manually, mark them as resolved with
+"git add/rm <conflicted_files>", then run "git rebase --continue".
+You can instead skip this commit: run "git rebase --skip".
+To abort and get back to the state before "git rebase", run "git rebase --abort".
+```
+
+This tells us that we have a merge conflict, and gives the name of the file with the conflict. Open the conflicting file in your text editor, and somewhere in the file, you'll find something like this:
+
+```
+<<<<<<< HEAD
+<p>For help with any issues, email us at support@webhost.us.</p>
+=======
+<p>Need help? Email support@webhost.us.</p>
+>>>>>>> Commit #1
+```
+
+The line `<<<<<<< HEAD` marks the beginning of a merge conflict, and the `>>>>>>> Commit #1` line marks the end, with the conflicting sections separated by `=======`. The part on the `HEAD` side is from the QMK master version of the file, and the part marked with the commit message is from the current branch and commit.
+
+Because Git tracks *changes to files* rather than the contents of the files directly, if Git can't find the text that was in the file previous to the commit that was made, it won't know how to edit the file. Re-editing the file will solve the conflict. Make your changes, and then save the file.
+
+```
+<p>Need help? Email support@webhost.us.</p>
+```
+
+Now run:
+
+```
+git add conflicting_file_1.txt
+git rebase --continue
+```
+
+Git logs the changes to the conflicting file, and continues applying the commits from our branch until it reaches the end.

docs/newbs_building_firmware.md

@@ -16,12 +16,26 @@ Start by navigating to the `keymaps` folder for your keyboard.
 
 ?> Windows:
 
-    start keyboards/<keyboard_folder>/keymaps
+    start .\\keyboards\\<keyboard_folder>\\keymaps
 
 ## Create a Copy Of The `default` Keymap
 
 Once you have the `keymaps` folder open you will want to create a copy of the `default` folder. We highly recommend you name your folder the same as your GitHub username, but you can use any name you want as long as it contains only lower case letters, numbers, and the underscore character.
 
+To automate the process, you also have the option to run the `new_keymap.sh` script. 
+
+Navigate to the `qmk_firmware/util` directory and type the following:
+
+```
+./new_keymap.sh <keyboard path> <username>
+```
+
+For example, for a user named John, trying to make a new keymap for the 1up60hse, they would type in
+
+```
+./new_keymap.sh 1upkeyboards/1up60hse john
+```
+
 ## Open `keymap.c` In Your Favorite Text Editor
 
 Open up your `keymap.c`. Inside this file you'll find the structure that controls how your keyboard behaves. At the top of `keymap.c` there may be some defines and enums that make the keymap easier to read. Farther down you'll find a line that looks like this:

docs/newbs_learn_more_resources.md

@@ -0,0 +1,15 @@
+# Learning Resources
+
+These resources are aimed at giving new members in the QMK community more understanding to the information provided in the Newbs docs.
+
+Git resources:
+
+* [Great General Tutorial](https://www.codecademy.com/learn/learn-git)
+* [Git Game To Learn From Examples](https://learngitbranching.js.org/)
+* [Git Resources to Learn More About Github](getting_started_github.md)
+* [Git Resources Aimed Specifically toward QMK](contributing.md)
+
+
+Command Line resources:
+
+* [Good General Tutorial on Command Line](https://www.codecademy.com/learn/learn-the-command-line)

docs/quantum_keycodes.md

@@ -8,15 +8,16 @@ On this page we have documented keycodes between `0x00FF` and `0xFFFF` which are
 
 ## QMK Keycodes
 
-|Key          |Aliases    |Description                                                          |
-|-------------|-----------|---------------------------------------------------------------------|
-|`RESET`      |           |Put the keyboard into DFU mode for flashing                          |
-|`DEBUG`      |           |Toggle debug mode                                                    |
-|`KC_GESC`    |`GRAVE_ESC`|Escape when tapped, <code>&#96;</code> when pressed with Shift or GUI|
-|`KC_LSPO`    |           |Left Shift when held, `(` when tapped                                |
-|`KC_RSPC`    |           |Right Shift when held, `)` when tapped                               |
-|`KC_LEAD`    |           |The [Leader key](feature_leader_key.md)                              |
-|`KC_LOCK`    |           |The [Lock key](feature_key_lock.md)                                  |
-|`FUNC(n)`    |`F(n)`     |Call `fn_action(n)` (deprecated)                                     |
-|`M(n)`       |           |Call macro `n`                                                       |
-|`MACROTAP(n)`|           |Macro-tap `n` idk FIXME                                              |
+|Key            |Aliases    |Description                                                          |
+|---------------|-----------|---------------------------------------------------------------------|
+|`RESET`        |           |Put the keyboard into DFU mode for flashing                          |
+|`DEBUG`        |           |Toggle debug mode                                                    |
+|`EEPROM_RESET` |`EEP_RST`  |Resets EEPROM state by reinitializing it                             |
+|`KC_GESC`      |`GRAVE_ESC`|Escape when tapped, <code>&#96;</code> when pressed with Shift or GUI|
+|`KC_LSPO`      |           |Left Shift when held, `(` when tapped                                |
+|`KC_RSPC`      |           |Right Shift when held, `)` when tapped                               |
+|`KC_LEAD`      |           |The [Leader key](feature_leader_key.md)                              |
+|`KC_LOCK`      |           |The [Lock key](feature_key_lock.md)                                  |
+|`FUNC(n)`      |`F(n)`     |Call `fn_action(n)` (deprecated)                                     |
+|`M(n)`         |           |Call macro `n`                                                       |
+|`MACROTAP(n)`  |           |Macro-tap `n` idk FIXME                                              |

docs/redirects.json

@@ -34,7 +34,7 @@
             },
             {
                 "from": "space_cadet_shift.html",
-                "to": "feature_space_cadet.html"
+                "to": "feature_space_cadet_shift.html"
             },
             {
                 "from": "tap_dance.html",

docs/ref_functions.md

@@ -0,0 +1,98 @@
+# List of Useful Core Functions To Make Your Keyboard Better
+
+There are a lot of hidden functions in QMK that are incredible useful, or may add a bit of functionality that you've been wanting.  Functions that are specific to certain features are not included here, as those will be on their respective feature page.
+
+## (OLKB) Tri Layers
+
+There are actually separate functions that you can use there, depending on what you're after.
+
+### `update_tri_layer(x, y, z)`
+
+The first is the `update_tri_layer(x, y, z)` function.   This function check to see if layers `x` and `y` are both on. If they are both on, then it runs on layer `z`.  Otherwise, if both `x` and `y` are not both on (either only one is, or neither is), then it runs off layer `z`.
+
+This function is useful if you want to create specific keys that have this functionality, but other layer keycodes won't do this.
+
+#### Example
+
+```c
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case LOWER:
+      if (record->event.pressed) {
+        layer_on(_LOWER);
+        update_tri_layer(_LOWER, _RAISE, _ADJUST);
+      } else {
+        layer_off(_LOWER);
+        update_tri_layer(_LOWER, _RAISE, _ADJUST);
+      }
+      return false;
+      break;
+    case RAISE:
+      if (record->event.pressed) {
+        layer_on(_RAISE);
+        update_tri_layer(_LOWER, _RAISE, _ADJUST);
+      } else {
+        layer_off(_RAISE);
+        update_tri_layer(_LOWER, _RAISE, _ADJUST);
+      }
+      return false;
+      break;
+    }
+  return true;
+}
+```
+
+### `update_tri_layer_state(state, x, y, z)`
+The other function is `update_tri_layer_state(state, x, y, z)`.  This function is meant to be called from they [`layer_state_set_*` functions](custom_quantum_functions.md#layer-change-code).  This means that any time that you use a keycode to change the layer, this will be checked.  So you could use `LT(layer, kc)` to change the layer and it will trigger the same layer check.
+
+The caveat to this method is that you cannot access the `z` layer without having `x` and `y` layers on, since if you try to activate just layer `z`, it will run this code and turn off layer `z` before you could use it.
+
+#### Example
+
+```c
+uint32_t layer_state_set_user(uint32_t state) {
+  return update_tri_layer_state(state, _LOWER, _RAISE, _ADJUST);
+}
+```
+
+Alternatively, you don't have to immediately "return" the value.  This is useful if you want to add multiple tri layers, or if you want to add additional effects.
+
+```c
+uint32_t layer_state_set_user(uint32_t state) {
+  state = update_tri_layer_state(state, _LOWER, _RAISE, _ADJUST);
+  state = update_tri_layer_state(state, _RAISE, _SYMB, _SPECIAL);
+  return state;
+}
+```
+
+## Setting the Persistent Default Layer
+
+Do you want to set the default layer, so that it's retained even after you unplug the board?  If so, this is the function for you.
+
+To use this, you would use `set_single_persistent_default_layer(layer)`.  If you have a name defined for your layer, you can use that instead (such as _QWERTY, _DVORAK or _COLEMAK).
+
+This will set the default layer, update the persistent settings, and play a tune if you have [Audio](feature_audio.md) enabled on your board, and the default layer sounds set.
+
+To configure the default layer sounds, you would want to define this in your `config.h` file, like this:
+
+```c
+#define DEFAULT_LAYER_SONGS { SONG(QWERTY_SOUND), \
+                              SONG(COLEMAK_SOUND), \
+                              SONG(DVORAK_SOUND) \
+                            }
+```
+
+
+?> There are a large number of predefined songs in [quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) that you can use.
+
+## Reseting the keyboard
+
+There is the `RESET` quantum keycode that you can use. But if you want to reset the board as part of a macro, rather than hitting a key separately, you can do that.
+
+And to do so, add `reset_keyboard()` to your function or macro, and this will reset to bootloader.
+
+## Wiping the EEPROM (Persistent Storage)
+
+If you're having issues with Audio, RGB Underglow, backlighting or keys acting weird, then you can reset the EEPROM (persistent setting storage).  Bootmagic is one way to do this, but if that isn't enabled, then you can use a custom macro to do so.
+
+To wipe the EEPROM, run `eeconfig_init()` from your function or macro to reset most of the settings to default.

docs/reference_glossary.md

@@ -128,12 +128,12 @@ The standard Deutsche (German) keyboard layout. Named for the first 6 letters on
 The term for pressing a key while a key is already held down. Variants include 2KRO, 6KRO, and NKRO.
 
 ## Scancode
-A 1 byte number that is sent as part of a HID report over USB that represents a single key. These numbers are documented in the [HID Usage Tables](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) published by the [USB-IF](http://www.usb.org/).
+A 1 byte number that is sent as part of a HID report over USB that represents a single key. These numbers are documented in the [HID Usage Tables](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf) published by the [USB-IF](http://www.usb.org/).
 
 ## Space Cadet Shift
 A special set of shift keys which allow you to type various types of braces by tapping the left or right shift one or more times.
 
-* [Space Cadet Shift Documentation](feature_space_cadet.md)
+* [Space Cadet Shift Documentation](feature_space_cadet_shift.md)
 
 ## Tap
 Pressing and releasing a key. In some situations you will need to distinguish between a key down and a key up event, and Tap always refers to both at once.

docs/understanding_qmk.md

@@ -12,7 +12,7 @@ You can think of QMK as no different from any other computer program. It is star
 
 The reason for this is the different platforms that QMK supports. The most common platform is `lufa`, which runs on AVR processors such at the atmega32u4. We also support `chibios` and `vusb`.
 
-We'll focus on AVR processors for the moment, which use the `lufa` platform. You can find the `main()` function in [tmk_core/protocol/lufa/lufa.c](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/protocol/lufa/lufa.c#L1129). If you browse through that function you'll find that it initializes any hardware that has been configured (including USB to the host) and then it starts the core part of the program with a [`while(1)`](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/protocol/lufa/lufa.c#L1182). This is [The Main Loop](#the_main_loop).
+We'll focus on AVR processors for the moment, which use the `lufa` platform. You can find the `main()` function in [tmk_core/protocol/lufa/lufa.c](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/tmk_core/protocol/lufa/lufa.c#L1019). If you browse through that function you'll find that it initializes any hardware that has been configured (including USB to the host) and then it starts the core part of the program with a [`while(1)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/tmk_core/protocol/lufa/lufa.c#L1060). This is [The Main Loop](#the-main-loop).
 
 ## The Main Loop
 
@@ -22,7 +22,7 @@ This section of code is called "The Main Loop" because it's responsible for loop
     keyboard_task();
 ```
 
-This is where all the keyboard specific functionality is dispatched. The source code for `keyboard_task()` can be found in [tmk_core/common/keyboard.c](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keyboard.c#L154), and it is responsible for detecting changes in the matrix and turning status LED's on and off.
+This is where all the keyboard specific functionality is dispatched. The source code for `keyboard_task()` can be found in [tmk_core/common/keyboard.c](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/tmk_core/common/keyboard.c#L206), and it is responsible for detecting changes in the matrix and turning status LED's on and off.
 
 Within `keyboard_task()` you'll find code to handle:
 
@@ -77,7 +77,7 @@ At the keyboard level we define a C macro (typically named `KEYMAP()`) which map
 
 Notice how the second block of our `KEYMAP()` macro matches the Matrix Scanning array above? This macro is what will map the matrix scanning array to keycodes. However, if you look at a 17 key numpad you'll notice that it has 3 places where the matrix could have a switch but doesn't, due to larger keys. We have populated those spaces with `KC_NO` so that our keymap definition doesn't have to.
 
-You can also use this macro to handle unusual matrix layouts, for example the [Clueboard rev 2](https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/66/rev2/rev2.h). Explaining that is outside the scope of this document.
+You can also use this macro to handle unusual matrix layouts, for example the [Clueboard rev 2](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/keyboards/clueboard/66/rev2/rev2.h). Explaining that is outside the scope of this document.
 
 ##### Keycode Assignment
 
@@ -130,26 +130,31 @@ Comparing against our keymap we can see that the pressed key is KC_NLCK. From he
 
 ##### Process Record
 
-The `process_record()` function itself is deceptively simple, but hidden within is a gateway to overriding functionality at various levels of QMK. The chain of events is described below, using cluecard whenever we need to look at the keyboard/keymap level functions.
+The `process_record()` function itself is deceptively simple, but hidden within is a gateway to overriding functionality at various levels of QMK. The chain of events is listed below, using cluecard whenever we need to look at the keyboard/keymap level functions.  Depending on options set in rule.mk or elsewhere, only a subset of the functions below will be included in final firmware.
 
-* [`void process_record(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action.c#L128)
-  * [`bool process_record_quantum(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/quantum.c#L140)
-    * [Map this record to a keycode](https://github.com/qmk/qmk_firmware/blob/master/quantum/quantum.c#L143)
-    * [`bool process_record_kb(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/card/card.c#L20)
-      * [`bool process_record_user(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/card/keymaps/default/keymap.c#L58)
-    * [`bool process_midi(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_midi.c#L102)
-    * [`bool process_audio(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_audio.c#L10)
-    * [`bool process_music(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_music.c#L69)
-    * [`bool process_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_tap_dance.c#L75)
-    * [`bool process_leader(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_leader.c#L32)
-    * [`bool process_chording(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_chording.c#L41)
-    * [`bool process_combo(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_combo.c#L115)
-    * [`bool process_unicode(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_unicode.c#L22)
-    * [`bool process_ucis(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_ucis.c#L91)
-    * [`bool process_printer(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_printer.c#L77)
-    * [`bool process_auto_shift(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_auto_shift.c#L47)
-    * [`bool process_unicode_map(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_unicodemap.c#L47)
-    * [Identify and process quantum specific keycodes](https://github.com/qmk/qmk_firmware/blob/master/quantum/quantum.c#L211)
+* [`void process_record(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/tmk_core/common/action.c#L172)
+  * [`bool process_record_quantum(keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/quantum/quantum.c#L193)
+    * [Map this record to a keycode](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/quantum/quantum.c#L213)
+    * [`void preprocess_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/quantum/process_keycode/process_tap_dance.c#L115)
+    * [`bool process_key_lock(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/quantum/process_keycode/process_key_lock.c#L62)
+    * [`bool process_clicky(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/quantum/process_keycode/process_clicky.c#L44)
+    * [`bool process_record_kb(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/keyboards/clueboard/card/card.c#L20)
+      * [`bool process_record_user(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/08c682c193f43e5d54df990680ae93fc2e06150a/keyboards/clueboard/card/keymaps/default/keymap.c#L58)
+    * [`bool process_rgb_matrix(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/fdd0f915271f79b104aa5d216566bcc3fd134e85/quantum/rgb_matrix.c#L139)
+    * [`bool process_midi(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_midi.c#L81)
+    * [`bool process_audio(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_audio.c#L19)
+    * [`bool process_steno(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_steno.c#L160)
+    * [`bool process_music(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_music.c#L114)
+    * [`bool process_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_tap_dance.c#L136)
+    * [`bool process_leader(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_leader.c#L38)
+    * [`bool process_combo(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_combo.c#L115)
+    * [`bool process_unicode(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_unicode.c#L22)
+    * [`bool process_ucis(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_ucis.c#L91)
+    * [`bool process_printer(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_printer.c#L77)
+    * [`bool process_auto_shift(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_auto_shift.c#L94)
+    * [`bool process_unicode_map(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_unicodemap.c#L47)
+    * [`bool process_terminal(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/process_keycode/process_terminal.c#L264)
+    * [Identify and process quantum specific keycodes](https://github.com/qmk/qmk_firmware/blob/661ca4440cc42f3b60697e98985c44b0571ccfc1/quantum/quantum.c#L287)
 
 At any step during this chain of events a function (such as `process_record_kb()`) can `return false` to halt all further processing.
 

drivers/arm/i2c_master.c

@@ -0,0 +1,104 @@
+/* Copyright 2018 Jack Humbert
+ * Copyright 2018 Yiancar
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+/* This library is only valid for STM32 processors.
+ * This library follows the convention of the AVR i2c_master library.
+ * As a result addresses are expected to be already shifted (addr << 1).
+ * I2CD1 is the default driver which corresponds to pins B6 and B7. This
+ * can be changed.
+ * Please ensure that HAL_USE_I2C is TRUE in the halconf.h file and that
+ * STM32_I2C_USE_I2C1 is TRUE in the mcuconf.h file. Pins B6 and B7 are used
+ * but using any other I2C pins should be trivial.
+ */
+
+#include "i2c_master.h"
+#include <string.h>
+#include <hal.h>
+
+static uint8_t i2c_address;
+
+// This configures the I2C clock to 400Mhz assuming a 72Mhz clock
+// For more info : https://www.st.com/en/embedded-software/stsw-stm32126.html
+static const I2CConfig i2cconfig = {
+  STM32_TIMINGR_PRESC(15U) |
+  STM32_TIMINGR_SCLDEL(4U) | STM32_TIMINGR_SDADEL(2U) |
+  STM32_TIMINGR_SCLH(15U)  | STM32_TIMINGR_SCLL(21U),
+  0,
+  0
+};
+
+void i2c_init(void)
+{
+  palSetGroupMode(GPIOB, GPIOB_PIN6 | GPIOB_PIN7, 0, PAL_MODE_INPUT); // Try releasing special pins for a short time
+  chThdSleepMilliseconds(10);
+
+  palSetPadMode(GPIOB, 6, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP);
+  palSetPadMode(GPIOB, 7, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP);
+
+  //i2cInit(); //This is invoked by halInit() so no need to redo it.
+}
+
+// This is usually not needed
+uint8_t i2c_start(uint8_t address)
+{
+  i2c_address = address;
+  i2cStart(&I2C_DRIVER, &i2cconfig);
+  return 0;
+}
+
+uint8_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout)
+{
+  i2c_address = address;
+  i2cStart(&I2C_DRIVER, &i2cconfig);
+  return i2cMasterTransmitTimeout(&I2C_DRIVER, (i2c_address >> 1), data, length, 0, 0, MS2ST(timeout));
+}
+
+uint8_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout)
+{
+  i2c_address = address;
+  i2cStart(&I2C_DRIVER, &i2cconfig);
+  return i2cMasterReceiveTimeout(&I2C_DRIVER, (i2c_address >> 1), data, length, MS2ST(timeout));
+}
+
+uint8_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)
+{
+  i2c_address = devaddr;
+  i2cStart(&I2C_DRIVER, &i2cconfig);
+
+  uint8_t complete_packet[length + 1];
+  for(uint8_t i = 0; i < length; i++)
+  {
+    complete_packet[i+1] = data[i];
+  }
+  complete_packet[0] = regaddr;
+
+  return i2cMasterTransmitTimeout(&I2C_DRIVER, (i2c_address >> 1), complete_packet, length + 1, 0, 0, MS2ST(timeout));
+}
+
+uint8_t i2c_readReg(uint8_t devaddr, uint8_t* regaddr, uint8_t* data, uint16_t length, uint16_t timeout)
+{
+  i2c_address = devaddr;
+  i2cStart(&I2C_DRIVER, &i2cconfig);
+  return i2cMasterTransmitTimeout(&I2C_DRIVER, (i2c_address >> 1), regaddr, 1, data, length, MS2ST(timeout));
+}
+
+// This is usually not needed. It releases the driver to allow pins to become GPIO again.
+uint8_t i2c_stop(uint16_t timeout)
+{
+  i2cStop(&I2C_DRIVER);
+  return 0;
+}

drivers/arm/i2c_master.h

@@ -0,0 +1,39 @@
+/* Copyright 2018 Jack Humbert
+ * Copyright 2018 Yiancar
+ *
+ * This program is free sofare: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Sofare Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+/* This library follows the convention of the AVR i2c_master library.
+ * As a result addresses are expected to be already shifted (addr << 1).
+ * I2CD1 is the default driver which corresponds to pins B6 and B7. This
+ * can be changed.
+ * Please ensure that HAL_USE_I2C is TRUE in the halconf.h file and that
+ * STM32_I2C_USE_I2C1 is TRUE in the mcuconf.h file.
+ */
+
+#include "ch.h"
+#include <hal.h>
+
+#ifndef I2C_DRIVER
+  #define I2C_DRIVER I2CD1
+#endif
+
+void i2c_init(void);
+uint8_t i2c_start(uint8_t address);
+uint8_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);
+uint8_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);
+uint8_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);
+uint8_t i2c_readReg(uint8_t devaddr, uint8_t* regaddr, uint8_t* data, uint16_t length, uint16_t timeout);
+uint8_t i2c_stop(uint16_t timeout);

drivers/avr/hd44780.c

@@ -0,0 +1,592 @@
+/****************************************************************************
+ Title:     HD44780U LCD library
+ Author:    Peter Fleury <pfleury@gmx.ch>  http://tinyurl.com/peterfleury
+ License:   GNU General Public License Version 3
+ File:	    $Id: lcd.c,v 1.15.2.2 2015/01/17 12:16:05 peter Exp $
+ Software:  AVR-GCC 3.3 
+ Target:    any AVR device, memory mapped mode only for AT90S4414/8515/Mega
+
+ DESCRIPTION
+       Basic routines for interfacing a HD44780U-based text lcd display
+
+       Originally based on Volker Oth's lcd library,
+       changed lcd_init(), added additional constants for lcd_command(),
+       added 4-bit I/O mode, improved and optimized code.
+
+       Library can be operated in memory mapped mode (LCD_IO_MODE=0) or in 
+       4-bit IO port mode (LCD_IO_MODE=1). 8-bit IO port mode not supported.
+       
+       Memory mapped mode compatible with Kanda STK200, but supports also
+       generation of R/W signal through A8 address line.
+
+ USAGE
+       See the C include lcd.h file for a description of each function
+       
+*****************************************************************************/
+#include <inttypes.h>
+#include <avr/io.h>
+#include <avr/pgmspace.h>
+#include <util/delay.h>
+#include "hd44780.h"
+
+/* 
+** constants/macros 
+*/
+#define DDR(x) (*(&x - 1))      /* address of data direction register of port x */
+#if defined(__AVR_ATmega64__) || defined(__AVR_ATmega128__)
+    /* on ATmega64/128 PINF is on port 0x00 and not 0x60 */
+    #define PIN(x) ( &PORTF==&(x) ? _SFR_IO8(0x00) : (*(&x - 2)) )
+#else
+	#define PIN(x) (*(&x - 2))    /* address of input register of port x          */
+#endif
+
+
+#if LCD_IO_MODE
+#define lcd_e_delay()   _delay_us(LCD_DELAY_ENABLE_PULSE)
+#define lcd_e_high()    LCD_E_PORT  |=  _BV(LCD_E_PIN);
+#define lcd_e_low()     LCD_E_PORT  &= ~_BV(LCD_E_PIN);
+#define lcd_e_toggle()  toggle_e()
+#define lcd_rw_high()   LCD_RW_PORT |=  _BV(LCD_RW_PIN)
+#define lcd_rw_low()    LCD_RW_PORT &= ~_BV(LCD_RW_PIN)
+#define lcd_rs_high()   LCD_RS_PORT |=  _BV(LCD_RS_PIN)
+#define lcd_rs_low()    LCD_RS_PORT &= ~_BV(LCD_RS_PIN)
+#endif
+
+#if LCD_IO_MODE
+#if LCD_LINES==1
+#define LCD_FUNCTION_DEFAULT    LCD_FUNCTION_4BIT_1LINE 
+#else
+#define LCD_FUNCTION_DEFAULT    LCD_FUNCTION_4BIT_2LINES 
+#endif
+#else
+#if LCD_LINES==1
+#define LCD_FUNCTION_DEFAULT    LCD_FUNCTION_8BIT_1LINE
+#else
+#define LCD_FUNCTION_DEFAULT    LCD_FUNCTION_8BIT_2LINES
+#endif
+#endif
+
+#if LCD_CONTROLLER_KS0073
+#if LCD_LINES==4
+
+#define KS0073_EXTENDED_FUNCTION_REGISTER_ON  0x2C   /* |0|010|1100 4-bit mode, extension-bit RE = 1 */
+#define KS0073_EXTENDED_FUNCTION_REGISTER_OFF 0x28   /* |0|010|1000 4-bit mode, extension-bit RE = 0 */
+#define KS0073_4LINES_MODE                    0x09   /* |0|000|1001 4 lines mode */
+
+#endif
+#endif
+
+/* 
+** function prototypes 
+*/
+#if LCD_IO_MODE
+static void toggle_e(void);
+#endif
+
+/*
+** local functions
+*/
+
+
+/************************************************************************* 
+delay for a minimum of <us> microseconds
+the number of loops is calculated at compile-time from MCU clock frequency
+*************************************************************************/
+#define delay(us)  _delay_us(us) 
+
+
+#if LCD_IO_MODE
+/* toggle Enable Pin to initiate write */
+static void toggle_e(void)
+{
+    lcd_e_high();
+    lcd_e_delay();
+    lcd_e_low();
+}
+#endif
+
+
+/*************************************************************************
+Low-level function to write byte to LCD controller
+Input:    data   byte to write to LCD
+          rs     1: write data    
+                 0: write instruction
+Returns:  none
+*************************************************************************/
+#if LCD_IO_MODE
+static void lcd_write(uint8_t data,uint8_t rs) 
+{
+    unsigned char dataBits ;
+
+
+    if (rs) {        /* write data        (RS=1, RW=0) */
+       lcd_rs_high();
+    } else {         /* write instruction (RS=0, RW=0) */
+       lcd_rs_low();
+    }
+    lcd_rw_low();    /* RW=0  write mode      */
+
+    if ( ( &LCD_DATA0_PORT == &LCD_DATA1_PORT) && ( &LCD_DATA1_PORT == &LCD_DATA2_PORT ) && ( &LCD_DATA2_PORT == &LCD_DATA3_PORT )
+      && (LCD_DATA0_PIN == 0) && (LCD_DATA1_PIN == 1) && (LCD_DATA2_PIN == 2) && (LCD_DATA3_PIN == 3) )
+    {
+        /* configure data pins as output */
+        DDR(LCD_DATA0_PORT) |= 0x0F;
+
+        /* output high nibble first */
+        dataBits = LCD_DATA0_PORT & 0xF0;
+        LCD_DATA0_PORT = dataBits |((data>>4)&0x0F);
+        lcd_e_toggle();
+
+        /* output low nibble */
+        LCD_DATA0_PORT = dataBits | (data&0x0F);
+        lcd_e_toggle();
+
+        /* all data pins high (inactive) */
+        LCD_DATA0_PORT = dataBits | 0x0F;
+    }
+    else
+    {
+        /* configure data pins as output */
+        DDR(LCD_DATA0_PORT) |= _BV(LCD_DATA0_PIN);
+        DDR(LCD_DATA1_PORT) |= _BV(LCD_DATA1_PIN);
+        DDR(LCD_DATA2_PORT) |= _BV(LCD_DATA2_PIN);
+        DDR(LCD_DATA3_PORT) |= _BV(LCD_DATA3_PIN);
+        
+        /* output high nibble first */
+        LCD_DATA3_PORT &= ~_BV(LCD_DATA3_PIN);
+        LCD_DATA2_PORT &= ~_BV(LCD_DATA2_PIN);
+        LCD_DATA1_PORT &= ~_BV(LCD_DATA1_PIN);
+        LCD_DATA0_PORT &= ~_BV(LCD_DATA0_PIN);
+    	if(data & 0x80) LCD_DATA3_PORT |= _BV(LCD_DATA3_PIN);
+    	if(data & 0x40) LCD_DATA2_PORT |= _BV(LCD_DATA2_PIN);
+    	if(data & 0x20) LCD_DATA1_PORT |= _BV(LCD_DATA1_PIN);
+    	if(data & 0x10) LCD_DATA0_PORT |= _BV(LCD_DATA0_PIN);   
+        lcd_e_toggle();
+        
+        /* output low nibble */
+        LCD_DATA3_PORT &= ~_BV(LCD_DATA3_PIN);
+        LCD_DATA2_PORT &= ~_BV(LCD_DATA2_PIN);
+        LCD_DATA1_PORT &= ~_BV(LCD_DATA1_PIN);
+        LCD_DATA0_PORT &= ~_BV(LCD_DATA0_PIN);
+    	if(data & 0x08) LCD_DATA3_PORT |= _BV(LCD_DATA3_PIN);
+    	if(data & 0x04) LCD_DATA2_PORT |= _BV(LCD_DATA2_PIN);
+    	if(data & 0x02) LCD_DATA1_PORT |= _BV(LCD_DATA1_PIN);
+    	if(data & 0x01) LCD_DATA0_PORT |= _BV(LCD_DATA0_PIN);
+        lcd_e_toggle();        
+        
+        /* all data pins high (inactive) */
+        LCD_DATA0_PORT |= _BV(LCD_DATA0_PIN);
+        LCD_DATA1_PORT |= _BV(LCD_DATA1_PIN);
+        LCD_DATA2_PORT |= _BV(LCD_DATA2_PIN);
+        LCD_DATA3_PORT |= _BV(LCD_DATA3_PIN);
+    }
+}
+#else
+#define lcd_write(d,rs) if (rs) *(volatile uint8_t*)(LCD_IO_DATA) = d; else *(volatile uint8_t*)(LCD_IO_FUNCTION) = d;
+/* rs==0 -> write instruction to LCD_IO_FUNCTION */
+/* rs==1 -> write data to LCD_IO_DATA */
+#endif
+
+
+/*************************************************************************
+Low-level function to read byte from LCD controller
+Input:    rs     1: read data    
+                 0: read busy flag / address counter
+Returns:  byte read from LCD controller
+*************************************************************************/
+#if LCD_IO_MODE
+static uint8_t lcd_read(uint8_t rs) 
+{
+    uint8_t data;
+    
+    
+    if (rs)
+        lcd_rs_high();                       /* RS=1: read data      */
+    else
+        lcd_rs_low();                        /* RS=0: read busy flag */
+    lcd_rw_high();                           /* RW=1  read mode      */
+    
+    if ( ( &LCD_DATA0_PORT == &LCD_DATA1_PORT) && ( &LCD_DATA1_PORT == &LCD_DATA2_PORT ) && ( &LCD_DATA2_PORT == &LCD_DATA3_PORT )
+      && ( LCD_DATA0_PIN == 0 )&& (LCD_DATA1_PIN == 1) && (LCD_DATA2_PIN == 2) && (LCD_DATA3_PIN == 3) )
+    {
+        DDR(LCD_DATA0_PORT) &= 0xF0;         /* configure data pins as input */
+        
+        lcd_e_high();
+        lcd_e_delay();        
+        data = PIN(LCD_DATA0_PORT) << 4;     /* read high nibble first */
+        lcd_e_low();
+        
+        lcd_e_delay();                       /* Enable 500ns low       */
+        
+        lcd_e_high();
+        lcd_e_delay();
+        data |= PIN(LCD_DATA0_PORT)&0x0F;    /* read low nibble        */
+        lcd_e_low();
+    }
+    else
+    {
+        /* configure data pins as input */
+        DDR(LCD_DATA0_PORT) &= ~_BV(LCD_DATA0_PIN);
+        DDR(LCD_DATA1_PORT) &= ~_BV(LCD_DATA1_PIN);
+        DDR(LCD_DATA2_PORT) &= ~_BV(LCD_DATA2_PIN);
+        DDR(LCD_DATA3_PORT) &= ~_BV(LCD_DATA3_PIN);
+                
+        /* read high nibble first */
+        lcd_e_high();
+        lcd_e_delay();        
+        data = 0;
+        if ( PIN(LCD_DATA0_PORT) & _BV(LCD_DATA0_PIN) ) data |= 0x10;
+        if ( PIN(LCD_DATA1_PORT) & _BV(LCD_DATA1_PIN) ) data |= 0x20;
+        if ( PIN(LCD_DATA2_PORT) & _BV(LCD_DATA2_PIN) ) data |= 0x40;
+        if ( PIN(LCD_DATA3_PORT) & _BV(LCD_DATA3_PIN) ) data |= 0x80;
+        lcd_e_low();
+
+        lcd_e_delay();                       /* Enable 500ns low       */
+    
+        /* read low nibble */    
+        lcd_e_high();
+        lcd_e_delay();
+        if ( PIN(LCD_DATA0_PORT) & _BV(LCD_DATA0_PIN) ) data |= 0x01;
+        if ( PIN(LCD_DATA1_PORT) & _BV(LCD_DATA1_PIN) ) data |= 0x02;
+        if ( PIN(LCD_DATA2_PORT) & _BV(LCD_DATA2_PIN) ) data |= 0x04;
+        if ( PIN(LCD_DATA3_PORT) & _BV(LCD_DATA3_PIN) ) data |= 0x08;        
+        lcd_e_low();
+    }
+    return data;
+}
+#else
+#define lcd_read(rs) (rs) ? *(volatile uint8_t*)(LCD_IO_DATA+LCD_IO_READ) : *(volatile uint8_t*)(LCD_IO_FUNCTION+LCD_IO_READ)
+/* rs==0 -> read instruction from LCD_IO_FUNCTION */
+/* rs==1 -> read data from LCD_IO_DATA */
+#endif
+
+
+/*************************************************************************
+loops while lcd is busy, returns address counter
+*************************************************************************/
+static uint8_t lcd_waitbusy(void)
+
+{
+    register uint8_t c;
+    
+    /* wait until busy flag is cleared */
+    while ( (c=lcd_read(0)) & (1<<LCD_BUSY)) {}
+    
+    /* the address counter is updated 4us after the busy flag is cleared */
+    delay(LCD_DELAY_BUSY_FLAG);
+
+    /* now read the address counter */
+    return (lcd_read(0));  // return address counter
+    
+}/* lcd_waitbusy */
+
+
+/*************************************************************************
+Move cursor to the start of next line or to the first line if the cursor 
+is already on the last line.
+*************************************************************************/
+static inline void lcd_newline(uint8_t pos)
+{
+    register uint8_t addressCounter;
+
+
+#if LCD_LINES==1
+    addressCounter = 0;
+#endif
+#if LCD_LINES==2
+    if ( pos < (LCD_START_LINE2) )
+        addressCounter = LCD_START_LINE2;
+    else
+        addressCounter = LCD_START_LINE1;
+#endif
+#if LCD_LINES==4
+#if KS0073_4LINES_MODE
+    if ( pos < LCD_START_LINE2 )
+        addressCounter = LCD_START_LINE2;
+    else if ( (pos >= LCD_START_LINE2) && (pos < LCD_START_LINE3) )
+        addressCounter = LCD_START_LINE3;
+    else if ( (pos >= LCD_START_LINE3) && (pos < LCD_START_LINE4) )
+        addressCounter = LCD_START_LINE4;
+    else 
+        addressCounter = LCD_START_LINE1;
+#else
+    if ( pos < LCD_START_LINE3 )
+        addressCounter = LCD_START_LINE2;
+    else if ( (pos >= LCD_START_LINE2) && (pos < LCD_START_LINE4) )
+        addressCounter = LCD_START_LINE3;
+    else if ( (pos >= LCD_START_LINE3) && (pos < LCD_START_LINE2) )
+        addressCounter = LCD_START_LINE4;
+    else 
+        addressCounter = LCD_START_LINE1;
+#endif
+#endif
+    lcd_command((1<<LCD_DDRAM)+addressCounter);
+
+}/* lcd_newline */
+
+
+/*
+** PUBLIC FUNCTIONS 
+*/
+
+/*************************************************************************
+Send LCD controller instruction command
+Input:   instruction to send to LCD controller, see HD44780 data sheet
+Returns: none
+*************************************************************************/
+void lcd_command(uint8_t cmd)
+{
+    lcd_waitbusy();
+    lcd_write(cmd,0);
+}
+
+
+/*************************************************************************
+Send data byte to LCD controller 
+Input:   data to send to LCD controller, see HD44780 data sheet
+Returns: none
+*************************************************************************/
+void lcd_data(uint8_t data)
+{
+    lcd_waitbusy();
+    lcd_write(data,1);
+}
+
+
+
+/*************************************************************************
+Set cursor to specified position
+Input:    x  horizontal position  (0: left most position)
+          y  vertical position    (0: first line)
+Returns:  none
+*************************************************************************/
+void lcd_gotoxy(uint8_t x, uint8_t y)
+{
+#if LCD_LINES==1
+    lcd_command((1<<LCD_DDRAM)+LCD_START_LINE1+x);
+#endif
+#if LCD_LINES==2
+    if ( y==0 ) 
+        lcd_command((1<<LCD_DDRAM)+LCD_START_LINE1+x);
+    else
+        lcd_command((1<<LCD_DDRAM)+LCD_START_LINE2+x);
+#endif
+#if LCD_LINES==4
+    if ( y==0 )
+        lcd_command((1<<LCD_DDRAM)+LCD_START_LINE1+x);
+    else if ( y==1)
+        lcd_command((1<<LCD_DDRAM)+LCD_START_LINE2+x);
+    else if ( y==2)
+        lcd_command((1<<LCD_DDRAM)+LCD_START_LINE3+x);
+    else /* y==3 */
+        lcd_command((1<<LCD_DDRAM)+LCD_START_LINE4+x);
+#endif
+
+}/* lcd_gotoxy */
+
+
+/*************************************************************************
+*************************************************************************/
+int lcd_getxy(void)
+{
+    return lcd_waitbusy();
+}
+
+
+/*************************************************************************
+Clear display and set cursor to home position
+*************************************************************************/
+void lcd_clrscr(void)
+{
+    lcd_command(1<<LCD_CLR);
+}
+
+
+/*************************************************************************
+Set cursor to home position
+*************************************************************************/
+void lcd_home(void)
+{
+    lcd_command(1<<LCD_HOME);
+}
+
+
+/*************************************************************************
+Display character at current cursor position 
+Input:    character to be displayed                                       
+Returns:  none
+*************************************************************************/
+void lcd_putc(char c)
+{
+    uint8_t pos;
+
+
+    pos = lcd_waitbusy();   // read busy-flag and address counter
+    if (c=='\n')
+    {
+        lcd_newline(pos);
+    }
+    else
+    {
+#if LCD_WRAP_LINES==1
+#if LCD_LINES==1
+        if ( pos == LCD_START_LINE1+LCD_DISP_LENGTH ) {
+            lcd_write((1<<LCD_DDRAM)+LCD_START_LINE1,0);
+        }
+#elif LCD_LINES==2
+        if ( pos == LCD_START_LINE1+LCD_DISP_LENGTH ) {
+            lcd_write((1<<LCD_DDRAM)+LCD_START_LINE2,0);    
+        }else if ( pos == LCD_START_LINE2+LCD_DISP_LENGTH ){
+            lcd_write((1<<LCD_DDRAM)+LCD_START_LINE1,0);
+        }
+#elif LCD_LINES==4
+        if ( pos == LCD_START_LINE1+LCD_DISP_LENGTH ) {
+            lcd_write((1<<LCD_DDRAM)+LCD_START_LINE2,0);    
+        }else if ( pos == LCD_START_LINE2+LCD_DISP_LENGTH ) {
+            lcd_write((1<<LCD_DDRAM)+LCD_START_LINE3,0);
+        }else if ( pos == LCD_START_LINE3+LCD_DISP_LENGTH ) {
+            lcd_write((1<<LCD_DDRAM)+LCD_START_LINE4,0);
+        }else if ( pos == LCD_START_LINE4+LCD_DISP_LENGTH ) {
+            lcd_write((1<<LCD_DDRAM)+LCD_START_LINE1,0);
+        }
+#endif
+        lcd_waitbusy();
+#endif
+        lcd_write(c, 1);
+    }
+
+}/* lcd_putc */
+
+
+/*************************************************************************
+Display string without auto linefeed 
+Input:    string to be displayed
+Returns:  none
+*************************************************************************/
+void lcd_puts(const char *s)
+/* print string on lcd (no auto linefeed) */
+{
+    register char c;
+
+    while ( (c = *s++) ) {
+        lcd_putc(c);
+    }
+
+}/* lcd_puts */
+
+
+/*************************************************************************
+Display string from program memory without auto linefeed 
+Input:     string from program memory be be displayed                                        
+Returns:   none
+*************************************************************************/
+void lcd_puts_p(const char *progmem_s)
+/* print string from program memory on lcd (no auto linefeed) */
+{
+    register char c;
+
+    while ( (c = pgm_read_byte(progmem_s++)) ) {
+        lcd_putc(c);
+    }
+
+}/* lcd_puts_p */
+
+
+/*************************************************************************
+Initialize display and select type of cursor 
+Input:    dispAttr LCD_DISP_OFF            display off
+                   LCD_DISP_ON             display on, cursor off
+                   LCD_DISP_ON_CURSOR      display on, cursor on
+                   LCD_DISP_CURSOR_BLINK   display on, cursor on flashing
+Returns:  none
+*************************************************************************/
+void lcd_init(uint8_t dispAttr)
+{
+#if LCD_IO_MODE
+    /*
+     *  Initialize LCD to 4 bit I/O mode
+     */
+     
+    if ( ( &LCD_DATA0_PORT == &LCD_DATA1_PORT) && ( &LCD_DATA1_PORT == &LCD_DATA2_PORT ) && ( &LCD_DATA2_PORT == &LCD_DATA3_PORT )
+      && ( &LCD_RS_PORT == &LCD_DATA0_PORT) && ( &LCD_RW_PORT == &LCD_DATA0_PORT) && (&LCD_E_PORT == &LCD_DATA0_PORT)
+      && (LCD_DATA0_PIN == 0 ) && (LCD_DATA1_PIN == 1) && (LCD_DATA2_PIN == 2) && (LCD_DATA3_PIN == 3) 
+      && (LCD_RS_PIN == 4 ) && (LCD_RW_PIN == 5) && (LCD_E_PIN == 6 ) )
+    {
+        /* configure all port bits as output (all LCD lines on same port) */
+        DDR(LCD_DATA0_PORT) |= 0x7F;
+    }
+    else if ( ( &LCD_DATA0_PORT == &LCD_DATA1_PORT) && ( &LCD_DATA1_PORT == &LCD_DATA2_PORT ) && ( &LCD_DATA2_PORT == &LCD_DATA3_PORT )
+           && (LCD_DATA0_PIN == 0 ) && (LCD_DATA1_PIN == 1) && (LCD_DATA2_PIN == 2) && (LCD_DATA3_PIN == 3) )
+    {
+        /* configure all port bits as output (all LCD data lines on same port, but control lines on different ports) */
+        DDR(LCD_DATA0_PORT) |= 0x0F;
+        DDR(LCD_RS_PORT)    |= _BV(LCD_RS_PIN);
+        DDR(LCD_RW_PORT)    |= _BV(LCD_RW_PIN);
+        DDR(LCD_E_PORT)     |= _BV(LCD_E_PIN);
+    }
+    else
+    {
+        /* configure all port bits as output (LCD data and control lines on different ports */
+        DDR(LCD_RS_PORT)    |= _BV(LCD_RS_PIN);
+        DDR(LCD_RW_PORT)    |= _BV(LCD_RW_PIN);
+        DDR(LCD_E_PORT)     |= _BV(LCD_E_PIN);
+        DDR(LCD_DATA0_PORT) |= _BV(LCD_DATA0_PIN);
+        DDR(LCD_DATA1_PORT) |= _BV(LCD_DATA1_PIN);
+        DDR(LCD_DATA2_PORT) |= _BV(LCD_DATA2_PIN);
+        DDR(LCD_DATA3_PORT) |= _BV(LCD_DATA3_PIN);
+    }
+    delay(LCD_DELAY_BOOTUP);             /* wait 16ms or more after power-on       */
+    
+    /* initial write to lcd is 8bit */
+    LCD_DATA1_PORT |= _BV(LCD_DATA1_PIN);    // LCD_FUNCTION>>4;
+    LCD_DATA0_PORT |= _BV(LCD_DATA0_PIN);    // LCD_FUNCTION_8BIT>>4;
+    lcd_e_toggle();
+    delay(LCD_DELAY_INIT);               /* delay, busy flag can't be checked here */
+   
+    /* repeat last command */ 
+    lcd_e_toggle();      
+    delay(LCD_DELAY_INIT_REP);           /* delay, busy flag can't be checked here */
+    
+    /* repeat last command a third time */
+    lcd_e_toggle();      
+    delay(LCD_DELAY_INIT_REP);           /* delay, busy flag can't be checked here */
+
+    /* now configure for 4bit mode */
+    LCD_DATA0_PORT &= ~_BV(LCD_DATA0_PIN);   // LCD_FUNCTION_4BIT_1LINE>>4
+    lcd_e_toggle();
+    delay(LCD_DELAY_INIT_4BIT);          /* some displays need this additional delay */
+    
+    /* from now the LCD only accepts 4 bit I/O, we can use lcd_command() */    
+#else
+    /*
+     * Initialize LCD to 8 bit memory mapped mode
+     */
+    
+    /* enable external SRAM (memory mapped lcd) and one wait state */        
+    MCUCR = _BV(SRE) | _BV(SRW);
+
+    /* reset LCD */
+    delay(LCD_DELAY_BOOTUP);                    /* wait 16ms after power-on     */
+    lcd_write(LCD_FUNCTION_8BIT_1LINE,0);   /* function set: 8bit interface */                   
+    delay(LCD_DELAY_INIT);                      /* wait 5ms                     */
+    lcd_write(LCD_FUNCTION_8BIT_1LINE,0);   /* function set: 8bit interface */                 
+    delay(LCD_DELAY_INIT_REP);                  /* wait 64us                    */
+    lcd_write(LCD_FUNCTION_8BIT_1LINE,0);   /* function set: 8bit interface */                
+    delay(LCD_DELAY_INIT_REP);                  /* wait 64us                    */
+#endif
+
+#if KS0073_4LINES_MODE
+    /* Display with KS0073 controller requires special commands for enabling 4 line mode */
+	lcd_command(KS0073_EXTENDED_FUNCTION_REGISTER_ON);
+	lcd_command(KS0073_4LINES_MODE);
+	lcd_command(KS0073_EXTENDED_FUNCTION_REGISTER_OFF);
+#else
+    lcd_command(LCD_FUNCTION_DEFAULT);      /* function set: display lines  */
+#endif
+    lcd_command(LCD_DISP_OFF);              /* display off                  */
+    lcd_clrscr();                           /* display clear                */ 
+    lcd_command(LCD_MODE_DEFAULT);          /* set entry mode               */
+    lcd_command(dispAttr);                  /* display/cursor control       */
+
+}/* lcd_init */
+

drivers/avr/hd44780.h

@@ -0,0 +1,371 @@
+#ifndef LCD_H
+#define LCD_H
+/*************************************************************************
+ Title	:   C include file for the HD44780U LCD library (lcd.c)
+ Author:    Peter Fleury <pfleury@gmx.ch>  http://tinyurl.com/peterfleury
+ License:   GNU General Public License Version 3
+ File:	    $Id: lcd.h,v 1.14.2.4 2015/01/20 17:16:07 peter Exp $
+ Software:  AVR-GCC 4.x
+ Hardware:  any AVR device, memory mapped mode only for AVR with 
+            memory mapped interface (AT90S8515/ATmega8515/ATmega128)
+***************************************************************************/
+
+/**
+ @mainpage
+ Collection of libraries for AVR-GCC
+ @author Peter Fleury pfleury@gmx.ch http://tinyurl.com/peterfleury
+ @copyright (C) 2015 Peter Fleury, GNU General Public License Version 3
+ 
+ @file
+ @defgroup pfleury_lcd LCD library <lcd.h>
+ @code #include <lcd.h> @endcode
+ 
+ @brief Basic routines for interfacing a HD44780U-based character LCD display
+
+ LCD character displays can be found in many devices, like espresso machines, laser printers. 
+ The Hitachi HD44780 controller and its compatible controllers like Samsung KS0066U have become an industry standard for these types of displays. 
+ 
+ This library allows easy interfacing with a HD44780 compatible display and can be
+ operated in memory mapped mode (LCD_IO_MODE defined as 0 in the include file lcd.h.) or in 
+ 4-bit IO port mode (LCD_IO_MODE defined as 1). 8-bit IO port mode is not supported.
+
+ Memory mapped mode is compatible with old Kanda STK200 starter kit, but also supports
+ generation of R/W signal through A8 address line.
+
+ @see The chapter <a href=" http://homepage.hispeed.ch/peterfleury/avr-lcd44780.html" target="_blank">Interfacing a HD44780 Based LCD to an AVR</a>
+      on my home page, which shows example circuits how to connect an LCD to an AVR controller. 
+
+ @author Peter Fleury pfleury@gmx.ch http://tinyurl.com/peterfleury
+ 
+ @version   2.0
+ 
+ @copyright (C) 2015 Peter Fleury, GNU General Public License Version 3
+  
+*/
+
+#include <inttypes.h>
+#include <avr/pgmspace.h>
+
+#if (__GNUC__ * 100 + __GNUC_MINOR__) < 405
+#error "This library requires AVR-GCC 4.5 or later, update to newer AVR-GCC compiler !"
+#endif
+
+
+/**@{*/
+
+/*
+ * LCD and target specific definitions below can be defined in a separate include file with name lcd_definitions.h instead modifying this file 
+ * by adding -D_LCD_DEFINITIONS_FILE to the CDEFS section in the Makefile
+ * All definitions added to the file lcd_definitions.h will override the default definitions from lcd.h
+ */
+#ifdef _LCD_DEFINITIONS_FILE
+#include "lcd_definitions.h"
+#endif
+
+
+/**
+ * @name  Definition for LCD controller type
+ * Use 0 for HD44780 controller, change to 1 for displays with KS0073 controller.
+ */
+#ifndef LCD_CONTROLLER_KS0073 
+#define LCD_CONTROLLER_KS0073 0  /**< Use 0 for HD44780 controller, 1 for KS0073 controller */
+#endif
+
+/** 
+ * @name  Definitions for Display Size 
+ * Change these definitions to adapt setting to your display
+ *
+ * These definitions can be defined in a separate include file \b lcd_definitions.h instead modifying this file by 
+ * adding -D_LCD_DEFINITIONS_FILE to the CDEFS section in the Makefile.
+ * All definitions added to the file lcd_definitions.h will override the default definitions from lcd.h
+ *
+ */
+#ifndef LCD_LINES
+#define LCD_LINES           2     /**< number of visible lines of the display */
+#endif
+#ifndef LCD_DISP_LENGTH
+#define LCD_DISP_LENGTH    16     /**< visibles characters per line of the display */
+#endif
+#ifndef LCD_LINE_LENGTH
+#define LCD_LINE_LENGTH  0x40     /**< internal line length of the display    */
+#endif
+#ifndef LCD_START_LINE1
+#define LCD_START_LINE1  0x00     /**< DDRAM address of first char of line 1 */
+#endif
+#ifndef LCD_START_LINE2
+#define LCD_START_LINE2  0x40     /**< DDRAM address of first char of line 2 */
+#endif
+#ifndef LCD_START_LINE3
+#define LCD_START_LINE3  0x14     /**< DDRAM address of first char of line 3 */
+#endif
+#ifndef LCD_START_LINE4
+#define LCD_START_LINE4  0x54     /**< DDRAM address of first char of line 4 */
+#endif
+#ifndef LCD_WRAP_LINES
+#define LCD_WRAP_LINES      0     /**< 0: no wrap, 1: wrap at end of visibile line */
+#endif
+
+
+/**
+ * @name Definitions for 4-bit IO mode
+ *
+ * The four LCD data lines and the three control lines RS, RW, E can be on the 
+ * same port or on different ports. 
+ * Change LCD_RS_PORT, LCD_RW_PORT, LCD_E_PORT if you want the control lines on
+ * different ports. 
+ *
+ * Normally the four data lines should be mapped to bit 0..3 on one port, but it
+ * is possible to connect these data lines in different order or even on different
+ * ports by adapting the LCD_DATAx_PORT and LCD_DATAx_PIN definitions.
+ *
+ * Adjust these definitions to your target.\n 
+ * These definitions can be defined in a separate include file \b lcd_definitions.h instead modifying this file by 
+ * adding \b -D_LCD_DEFINITIONS_FILE to the \b CDEFS section in the Makefile.
+ * All definitions added to the file lcd_definitions.h will override the default definitions from lcd.h
+ *  
+ */
+#define LCD_IO_MODE      1            /**< 0: memory mapped mode, 1: IO port mode */
+
+#if LCD_IO_MODE
+
+#ifndef LCD_PORT
+#define LCD_PORT         PORTA        /**< port for the LCD lines   */
+#endif
+#ifndef LCD_DATA0_PORT
+#define LCD_DATA0_PORT   LCD_PORT     /**< port for 4bit data bit 0 */
+#endif
+#ifndef LCD_DATA1_PORT
+#define LCD_DATA1_PORT   LCD_PORT     /**< port for 4bit data bit 1 */
+#endif
+#ifndef LCD_DATA2_PORT
+#define LCD_DATA2_PORT   LCD_PORT     /**< port for 4bit data bit 2 */
+#endif
+#ifndef LCD_DATA3_PORT
+#define LCD_DATA3_PORT   LCD_PORT     /**< port for 4bit data bit 3 */
+#endif
+#ifndef LCD_DATA0_PIN
+#define LCD_DATA0_PIN    4            /**< pin for 4bit data bit 0  */
+#endif
+#ifndef LCD_DATA1_PIN
+#define LCD_DATA1_PIN    5            /**< pin for 4bit data bit 1  */
+#endif
+#ifndef LCD_DATA2_PIN
+#define LCD_DATA2_PIN    6            /**< pin for 4bit data bit 2  */
+#endif
+#ifndef LCD_DATA3_PIN
+#define LCD_DATA3_PIN    7            /**< pin for 4bit data bit 3  */
+#endif
+#ifndef LCD_RS_PORT
+#define LCD_RS_PORT      LCD_PORT     /**< port for RS line         */
+#endif
+#ifndef LCD_RS_PIN
+#define LCD_RS_PIN       3            /**< pin  for RS line         */
+#endif
+#ifndef LCD_RW_PORT
+#define LCD_RW_PORT      LCD_PORT     /**< port for RW line         */
+#endif
+#ifndef LCD_RW_PIN
+#define LCD_RW_PIN       2            /**< pin  for RW line         */
+#endif
+#ifndef LCD_E_PORT
+#define LCD_E_PORT       LCD_PORT     /**< port for Enable line     */
+#endif
+#ifndef LCD_E_PIN
+#define LCD_E_PIN        1            /**< pin  for Enable line     */
+#endif
+
+#elif defined(__AVR_AT90S4414__) || defined(__AVR_AT90S8515__) || defined(__AVR_ATmega64__) || \
+      defined(__AVR_ATmega8515__)|| defined(__AVR_ATmega103__) || defined(__AVR_ATmega128__) || \
+      defined(__AVR_ATmega161__) || defined(__AVR_ATmega162__)
+/*
+ * memory mapped mode is only supported when the device has an external data memory interface
+ */
+#define LCD_IO_DATA      0xC000    /* A15=E=1, A14=RS=1                 */
+#define LCD_IO_FUNCTION  0x8000    /* A15=E=1, A14=RS=0                 */
+#define LCD_IO_READ      0x0100    /* A8 =R/W=1 (R/W: 1=Read, 0=Write   */
+
+#else
+#error "external data memory interface not available for this device, use 4-bit IO port mode"
+
+#endif
+
+
+/**
+ * @name Definitions of delays
+ * Used to calculate delay timers.
+ * Adapt the F_CPU define in the Makefile to the clock frequency in Hz of your target
+ *
+ * These delay times can be adjusted, if some displays require different delays.\n 
+ * These definitions can be defined in a separate include file \b lcd_definitions.h instead modifying this file by 
+ * adding \b -D_LCD_DEFINITIONS_FILE to the \b CDEFS section in the Makefile.
+ * All definitions added to the file lcd_definitions.h will override the default definitions from lcd.h
+ */
+#ifndef LCD_DELAY_BOOTUP
+#define LCD_DELAY_BOOTUP   16000      /**< delay in micro seconds after power-on  */
+#endif
+#ifndef LCD_DELAY_INIT
+#define LCD_DELAY_INIT      5000      /**< delay in micro seconds after initialization command sent  */
+#endif
+#ifndef LCD_DELAY_INIT_REP
+#define LCD_DELAY_INIT_REP    64      /**< delay in micro seconds after initialization command repeated */
+#endif
+#ifndef LCD_DELAY_INIT_4BIT
+#define LCD_DELAY_INIT_4BIT   64      /**< delay in micro seconds after setting 4-bit mode */ 
+#endif
+#ifndef LCD_DELAY_BUSY_FLAG
+#define LCD_DELAY_BUSY_FLAG    4      /**< time in micro seconds the address counter is updated after busy flag is cleared */
+#endif
+#ifndef LCD_DELAY_ENABLE_PULSE
+#define LCD_DELAY_ENABLE_PULSE 1      /**< enable signal pulse width in micro seconds */
+#endif
+
+
+/**
+ * @name Definitions for LCD command instructions
+ * The constants define the various LCD controller instructions which can be passed to the 
+ * function lcd_command(), see HD44780 data sheet for a complete description.
+ */
+
+/* instruction register bit positions, see HD44780U data sheet */
+#define LCD_CLR               0      /* DB0: clear display                  */
+#define LCD_HOME              1      /* DB1: return to home position        */
+#define LCD_ENTRY_MODE        2      /* DB2: set entry mode                 */
+#define LCD_ENTRY_INC         1      /*   DB1: 1=increment, 0=decrement     */
+#define LCD_ENTRY_SHIFT       0      /*   DB2: 1=display shift on           */
+#define LCD_ON                3      /* DB3: turn lcd/cursor on             */
+#define LCD_ON_DISPLAY        2      /*   DB2: turn display on              */
+#define LCD_ON_CURSOR         1      /*   DB1: turn cursor on               */
+#define LCD_ON_BLINK          0      /*     DB0: blinking cursor ?          */
+#define LCD_MOVE              4      /* DB4: move cursor/display            */
+#define LCD_MOVE_DISP         3      /*   DB3: move display (0-> cursor) ?  */
+#define LCD_MOVE_RIGHT        2      /*   DB2: move right (0-> left) ?      */
+#define LCD_FUNCTION          5      /* DB5: function set                   */
+#define LCD_FUNCTION_8BIT     4      /*   DB4: set 8BIT mode (0->4BIT mode) */
+#define LCD_FUNCTION_2LINES   3      /*   DB3: two lines (0->one line)      */
+#define LCD_FUNCTION_10DOTS   2      /*   DB2: 5x10 font (0->5x7 font)      */
+#define LCD_CGRAM             6      /* DB6: set CG RAM address             */
+#define LCD_DDRAM             7      /* DB7: set DD RAM address             */
+#define LCD_BUSY              7      /* DB7: LCD is busy                    */
+
+/* set entry mode: display shift on/off, dec/inc cursor move direction */
+#define LCD_ENTRY_DEC            0x04   /* display shift off, dec cursor move dir */
+#define LCD_ENTRY_DEC_SHIFT      0x05   /* display shift on,  dec cursor move dir */
+#define LCD_ENTRY_INC_           0x06   /* display shift off, inc cursor move dir */
+#define LCD_ENTRY_INC_SHIFT      0x07   /* display shift on,  inc cursor move dir */
+
+/* display on/off, cursor on/off, blinking char at cursor position */
+#define LCD_DISP_OFF             0x08   /* display off                            */
+#define LCD_DISP_ON              0x0C   /* display on, cursor off                 */
+#define LCD_DISP_ON_BLINK        0x0D   /* display on, cursor off, blink char     */
+#define LCD_DISP_ON_CURSOR       0x0E   /* display on, cursor on                  */
+#define LCD_DISP_ON_CURSOR_BLINK 0x0F   /* display on, cursor on, blink char      */
+
+/* move cursor/shift display */
+#define LCD_MOVE_CURSOR_LEFT     0x10   /* move cursor left  (decrement)          */
+#define LCD_MOVE_CURSOR_RIGHT    0x14   /* move cursor right (increment)          */
+#define LCD_MOVE_DISP_LEFT       0x18   /* shift display left                     */
+#define LCD_MOVE_DISP_RIGHT      0x1C   /* shift display right                    */
+
+/* function set: set interface data length and number of display lines */
+#define LCD_FUNCTION_4BIT_1LINE  0x20   /* 4-bit interface, single line, 5x7 dots */
+#define LCD_FUNCTION_4BIT_2LINES 0x28   /* 4-bit interface, dual line,   5x7 dots */
+#define LCD_FUNCTION_8BIT_1LINE  0x30   /* 8-bit interface, single line, 5x7 dots */
+#define LCD_FUNCTION_8BIT_2LINES 0x38   /* 8-bit interface, dual line,   5x7 dots */
+
+
+#define LCD_MODE_DEFAULT     ((1<<LCD_ENTRY_MODE) | (1<<LCD_ENTRY_INC) )
+
+
+
+/** 
+ *  @name Functions
+ */
+
+
+/**
+ @brief    Initialize display and select type of cursor
+ @param    dispAttr \b LCD_DISP_OFF display off\n
+                    \b LCD_DISP_ON display on, cursor off\n
+                    \b LCD_DISP_ON_CURSOR display on, cursor on\n
+                    \b LCD_DISP_ON_CURSOR_BLINK display on, cursor on flashing             
+ @return  none
+*/
+extern void lcd_init(uint8_t dispAttr);
+
+
+/**
+ @brief    Clear display and set cursor to home position
+ @return   none
+*/
+extern void lcd_clrscr(void);
+
+
+/**
+ @brief    Set cursor to home position
+ @return   none
+*/
+extern void lcd_home(void);
+
+
+/**
+ @brief    Set cursor to specified position
+ 
+ @param    x horizontal position\n (0: left most position)
+ @param    y vertical position\n   (0: first line)
+ @return   none
+*/
+extern void lcd_gotoxy(uint8_t x, uint8_t y);
+
+
+/**
+ @brief    Display character at current cursor position
+ @param    c character to be displayed                                       
+ @return   none
+*/
+extern void lcd_putc(char c);
+
+
+/**
+ @brief    Display string without auto linefeed
+ @param    s string to be displayed                                        
+ @return   none
+*/
+extern void lcd_puts(const char *s);
+
+
+/**
+ @brief    Display string from program memory without auto linefeed
+ @param    progmem_s string from program memory be be displayed                                        
+ @return   none
+ @see      lcd_puts_P
+*/
+extern void lcd_puts_p(const char *progmem_s);
+
+
+/**
+ @brief    Send LCD controller instruction command
+ @param    cmd instruction to send to LCD controller, see HD44780 data sheet
+ @return   none
+*/
+extern void lcd_command(uint8_t cmd);
+
+
+/**
+ @brief    Send data byte to LCD controller 
+ 
+ Similar to lcd_putc(), but without interpreting LF
+ @param    data byte to send to LCD controller, see HD44780 data sheet
+ @return   none
+*/
+extern void lcd_data(uint8_t data);
+
+
+/**
+ @brief macros for automatically storing string constant in program memory
+*/
+#define lcd_puts_P(__s)         lcd_puts_p(PSTR(__s))
+
+/**@}*/
+
+#endif //LCD_H
+

drivers/avr/i2c_master.c

@@ -6,144 +6,215 @@
 #include <util/twi.h>
 
 #include "i2c_master.h"
+#include "timer.h"
 
+#ifndef F_SCL
 #define F_SCL 400000UL // SCL frequency
+#endif
 #define Prescaler 1
 #define TWBR_val ((((F_CPU / F_SCL) / Prescaler) - 16 ) / 2)
 
 void i2c_init(void)
 {
-	TWBR = (uint8_t)TWBR_val;
+  TWSR = 0;     /* no prescaler */
+  TWBR = (uint8_t)TWBR_val;
 }
 
-uint8_t i2c_start(uint8_t address)
+i2c_status_t i2c_start(uint8_t address, uint16_t timeout)
 {
-	// reset TWI control register
-	TWCR = 0;
-	// transmit START condition 
-	TWCR = (1<<TWINT) | (1<<TWSTA) | (1<<TWEN);
-	// wait for end of transmission
-	while( !(TWCR & (1<<TWINT)) );
-	
-	// check if the start condition was successfully transmitted
-	if((TWSR & 0xF8) != TW_START){ return 1; }
-	
-	// load slave address into data register
-	TWDR = address;
-	// start transmission of address
-	TWCR = (1<<TWINT) | (1<<TWEN);
-	// wait for end of transmission
-	while( !(TWCR & (1<<TWINT)) );
-	
-	// check if the device has acknowledged the READ / WRITE mode
-	uint8_t twst = TW_STATUS & 0xF8;
-	if ( (twst != TW_MT_SLA_ACK) && (twst != TW_MR_SLA_ACK) ) return 1;
-	
-	return 0;
+  // reset TWI control register
+  TWCR = 0;
+  // transmit START condition
+  TWCR = (1<<TWINT) | (1<<TWSTA) | (1<<TWEN);
+
+  uint16_t timeout_timer = timer_read();
+  while( !(TWCR & (1<<TWINT)) ) {
+    if ((timeout != I2C_TIMEOUT_INFINITE) && ((timer_read() - timeout_timer) >= timeout)) {
+      return I2C_STATUS_TIMEOUT;
+    }
+  }
+
+  // check if the start condition was successfully transmitted
+  if(((TW_STATUS & 0xF8) != TW_START) && ((TW_STATUS & 0xF8) != TW_REP_START)){ return I2C_STATUS_ERROR; }
+
+  // load slave address into data register
+  TWDR = address;
+  // start transmission of address
+  TWCR = (1<<TWINT) | (1<<TWEN);
+
+  timeout_timer = timer_read();
+  while( !(TWCR & (1<<TWINT)) ) {
+    if ((timeout != I2C_TIMEOUT_INFINITE) && ((timer_read() - timeout_timer) >= timeout)) {
+      return I2C_STATUS_TIMEOUT;
+    }
+  }
+
+  // check if the device has acknowledged the READ / WRITE mode
+  uint8_t twst = TW_STATUS & 0xF8;
+  if ( (twst != TW_MT_SLA_ACK) && (twst != TW_MR_SLA_ACK) ) return I2C_STATUS_ERROR;
+
+  return I2C_STATUS_SUCCESS;
 }
 
-uint8_t i2c_write(uint8_t data)
+i2c_status_t i2c_write(uint8_t data, uint16_t timeout)
 {
-	// load data into data register
-	TWDR = data;
-	// start transmission of data
-	TWCR = (1<<TWINT) | (1<<TWEN);
-	// wait for end of transmission
-	while( !(TWCR & (1<<TWINT)) );
-	
-	if( (TWSR & 0xF8) != TW_MT_DATA_ACK ){ return 1; }
-	
-	return 0;
+  // load data into data register
+  TWDR = data;
+  // start transmission of data
+  TWCR = (1<<TWINT) | (1<<TWEN);
+
+  uint16_t timeout_timer = timer_read();
+  while( !(TWCR & (1<<TWINT)) ) {
+    if ((timeout != I2C_TIMEOUT_INFINITE) && ((timer_read() - timeout_timer) >= timeout)) {
+      return I2C_STATUS_TIMEOUT;
+    }
+  }
+
+  if( (TW_STATUS & 0xF8) != TW_MT_DATA_ACK ){ return I2C_STATUS_ERROR; }
+
+  return I2C_STATUS_SUCCESS;
 }
 
-uint8_t i2c_read_ack(void)
+int16_t i2c_read_ack(uint16_t timeout)
 {
-	
-	// start TWI module and acknowledge data after reception
-	TWCR = (1<<TWINT) | (1<<TWEN) | (1<<TWEA); 
-	// wait for end of transmission
-	while( !(TWCR & (1<<TWINT)) );
-	// return received data from TWDR
-	return TWDR;
+
+  // start TWI module and acknowledge data after reception
+  TWCR = (1<<TWINT) | (1<<TWEN) | (1<<TWEA);
+
+  uint16_t timeout_timer = timer_read();
+  while( !(TWCR & (1<<TWINT)) ) {
+    if ((timeout != I2C_TIMEOUT_INFINITE) && ((timer_read() - timeout_timer) >= timeout)) {
+      return I2C_STATUS_TIMEOUT;
+    }
+  }
+
+  // return received data from TWDR
+  return TWDR;
 }
 
-uint8_t i2c_read_nack(void)
+int16_t i2c_read_nack(uint16_t timeout)
 {
-	
-	// start receiving without acknowledging reception
-	TWCR = (1<<TWINT) | (1<<TWEN);
-	// wait for end of transmission
-	while( !(TWCR & (1<<TWINT)) );
-	// return received data from TWDR
-	return TWDR;
+
+  // start receiving without acknowledging reception
+  TWCR = (1<<TWINT) | (1<<TWEN);
+
+  uint16_t timeout_timer = timer_read();
+  while( !(TWCR & (1<<TWINT)) ) {
+    if ((timeout != I2C_TIMEOUT_INFINITE) && ((timer_read() - timeout_timer) >= timeout)) {
+      return I2C_STATUS_TIMEOUT;
+    }
+  }
+
+  // return received data from TWDR
+  return TWDR;
 }
 
-uint8_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length)
+i2c_status_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout)
 {
-	if (i2c_start(address | I2C_WRITE)) return 1;
-	
-	for (uint16_t i = 0; i < length; i++)
-	{
-		if (i2c_write(data[i])) return 1;
-	}
-	
-	i2c_stop();
-	
-	return 0;
+  i2c_status_t status = i2c_start(address | I2C_WRITE, timeout);
+  if (status) return status;
+
+  for (uint16_t i = 0; i < length; i++) {
+    status = i2c_write(data[i], timeout);
+    if (status) return status;
+  }
+
+  status = i2c_stop(timeout);
+  if (status) return status;
+
+  return I2C_STATUS_SUCCESS;
 }
 
-uint8_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length)
+i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout)
 {
-	if (i2c_start(address | I2C_READ)) return 1;
-	
-	for (uint16_t i = 0; i < (length-1); i++)
-	{
-		data[i] = i2c_read_ack();
-	}
-	data[(length-1)] = i2c_read_nack();
-	
-	i2c_stop();
-	
-	return 0;
+  i2c_status_t status = i2c_start(address | I2C_READ, timeout);
+  if (status) return status;
+
+  for (uint16_t i = 0; i < (length-1); i++) {
+    status = i2c_read_ack(timeout);
+    if (status >= 0) {
+      data[i] = status;
+    } else {
+      return status;
+    }
+  }
+
+  status = i2c_read_nack(timeout);
+  if (status >= 0 ) {
+    data[(length-1)] = status;
+  } else {
+    return status;
+  }
+
+  status = i2c_stop(timeout);
+  if (status) return status;
+
+  return I2C_STATUS_SUCCESS;
 }
 
-uint8_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length)
+i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)
 {
-	if (i2c_start(devaddr | 0x00)) return 1;
+  i2c_status_t status = i2c_start(devaddr | 0x00, timeout);
+  if (status) return status;
 
-	i2c_write(regaddr);
+  status = i2c_write(regaddr, timeout);
+  if (status) return status;
 
-	for (uint16_t i = 0; i < length; i++)
-	{
-		if (i2c_write(data[i])) return 1;
-	}
+  for (uint16_t i = 0; i < length; i++) {
+    status = i2c_write(data[i], timeout);
+    if (status) return status;
+  }
 
-	i2c_stop();
+  status = i2c_stop(timeout);
+  if (status) return status;
 
-	return 0;
+  return I2C_STATUS_SUCCESS;
 }
 
-uint8_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length)
+i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)
 {
-	if (i2c_start(devaddr)) return 1;
+  i2c_status_t status = i2c_start(devaddr, timeout);
+  if (status) return status;
 
-	i2c_write(regaddr);
+  status = i2c_write(regaddr, timeout);
+  if (status) return status;
 
-	if (i2c_start(devaddr | 0x01)) return 1;
+  status = i2c_start(devaddr | 0x01, timeout);
+  if (status) return status;
 
-	for (uint16_t i = 0; i < (length-1); i++)
-	{
-		data[i] = i2c_read_ack();
-	}
-	data[(length-1)] = i2c_read_nack();
+  for (uint16_t i = 0; i < (length-1); i++) {
+    status = i2c_read_ack(timeout);
+    if (status >= 0) {
+      data[i] = status;
+    } else {
+      return status;
+    }
+  }
 
-	i2c_stop();
+  status = i2c_read_nack(timeout);
+  if (status >= 0 ) {
+    data[(length-1)] = status;
+  } else {
+    return status;
+  }
 
-	return 0;
+  status = i2c_stop(timeout);
+  if (status) return status;
+
+  return I2C_STATUS_SUCCESS;
 }
 
-void i2c_stop(void)
+i2c_status_t i2c_stop(uint16_t timeout)
 {
-	// transmit STOP condition
-	TWCR = (1<<TWINT) | (1<<TWEN) | (1<<TWSTO);
-}
+  // transmit STOP condition
+  TWCR = (1<<TWINT) | (1<<TWEN) | (1<<TWSTO);
+
+  uint16_t timeout_timer = timer_read();
+  while(TWCR & (1<<TWSTO)) {
+    if ((timeout != I2C_TIMEOUT_INFINITE) && ((timer_read() - timeout_timer) >= timeout)) {
+      return I2C_STATUS_TIMEOUT;
+    }
+  }
+
+  return I2C_STATUS_SUCCESS;
+}

drivers/avr/i2c_master.h

@@ -8,15 +8,24 @@
 #define I2C_READ 0x01
 #define I2C_WRITE 0x00
 
-void i2c_init(void);
-uint8_t i2c_start(uint8_t address);
-uint8_t i2c_write(uint8_t data);
-uint8_t i2c_read_ack(void);
-uint8_t i2c_read_nack(void);
-uint8_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length);
-uint8_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length);
-uint8_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length);
-uint8_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length);
-void i2c_stop(void);
+typedef int16_t i2c_status_t;
 
-#endif // I2C_MASTER_H
+#define I2C_STATUS_SUCCESS (0)
+#define I2C_STATUS_ERROR   (-1)
+#define I2C_STATUS_TIMEOUT (-2)
+
+#define I2C_TIMEOUT_IMMEDIATE (0)
+#define I2C_TIMEOUT_INFINITE (0xFFFF)
+
+void i2c_init(void);
+i2c_status_t i2c_start(uint8_t address, uint16_t timeout);
+i2c_status_t i2c_write(uint8_t data, uint16_t timeout);
+int16_t i2c_read_ack(uint16_t timeout);
+int16_t i2c_read_nack(uint16_t timeout);
+i2c_status_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);
+i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);
+i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);
+i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);
+i2c_status_t i2c_stop(uint16_t timeout);
+
+#endif // I2C_MASTER_H

drivers/avr/i2c_slave.c

@@ -0,0 +1,68 @@
+/* Library made by: g4lvanix
+ * Github repository: https://github.com/g4lvanix/I2C-slave-lib
+ */
+
+#include <avr/io.h>
+#include <util/twi.h>
+#include <avr/interrupt.h>
+#include <stdbool.h>
+
+#include "i2c_slave.h"
+
+void i2c_init(uint8_t address){
+    // load address into TWI address register
+    TWAR = (address << 1);
+    // set the TWCR to enable address matching and enable TWI, clear TWINT, enable TWI interrupt
+    TWCR = (1 << TWIE) | (1 << TWEA) | (1 << TWINT) | (1 << TWEN);
+}
+
+void i2c_stop(void){
+    // clear acknowledge and enable bits
+    TWCR &= ~((1 << TWEA) | (1 << TWEN));
+}
+
+ISR(TWI_vect){
+    uint8_t ack = 1;
+    // temporary stores the received data
+    //uint8_t data;
+    
+    switch(TW_STATUS){
+        case TW_SR_SLA_ACK:
+            // The device is now a slave receiver
+            slave_has_register_set = false;
+            break;
+
+        case TW_SR_DATA_ACK:
+            // This device is a slave receiver and has received data
+            // First byte is the location then the bytes will be writen in buffer with auto-incriment
+            if(!slave_has_register_set){
+                buffer_address = TWDR;
+
+                if (buffer_address >= RX_BUFFER_SIZE){ // address out of bounds dont ack
+                    ack = 0;
+                    buffer_address = 0;
+                }
+                slave_has_register_set = true; // address has been receaved now fill in buffer
+            } else {
+                rxbuffer[buffer_address] = TWDR;
+                buffer_address++;
+            }
+            break;
+
+        case TW_ST_SLA_ACK:
+        case TW_ST_DATA_ACK:
+            // This device is a slave transmitter and master has requested data
+            TWDR = txbuffer[buffer_address];
+            buffer_address++;
+            break;
+
+        case TW_BUS_ERROR:
+            // We got an error, reset i2c
+            TWCR = 0;
+        default:
+            break;
+    }
+
+    // Reset i2c state mahcine to be ready for next interrupt
+    TWCR |= (1 << TWIE) | (1 << TWINT) | (ack << TWEA) | (1 << TWEN);
+}

drivers/avr/i2c_slave.h

@@ -0,0 +1,23 @@
+/* Library made by: g4lvanix
+ * Github repository: https://github.com/g4lvanix/I2C-slave-lib
+
+ Info: Inititate the library by giving the required address.
+       Read or write to the necessary buffer according to the opperation.
+ */
+
+#ifndef I2C_SLAVE_H
+#define I2C_SLAVE_H
+
+#define TX_BUFFER_SIZE 30
+#define RX_BUFFER_SIZE 30
+
+volatile uint8_t buffer_address;
+static volatile bool slave_has_register_set = false;
+volatile uint8_t txbuffer[TX_BUFFER_SIZE];
+volatile uint8_t rxbuffer[RX_BUFFER_SIZE];
+
+void i2c_init(uint8_t address);
+void i2c_stop(void);
+ISR(TWI_vect);
+
+#endif // I2C_SLAVE_H

drivers/avr/is31fl3731.c

@@ -1,244 +0,0 @@
-/* Copyright 2017 Jason Williams
- * Copyright 2018 Jack Humbert
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- */
-
-#include "is31fl3731.h"
-#include <avr/interrupt.h>
-#include <avr/io.h>
-#include <util/delay.h>
-#include <string.h>
-#include "i2c_master.h"
-#include "progmem.h"
-
-// This is a 7-bit address, that gets left-shifted and bit 0
-// set to 0 for write, 1 for read (as per I2C protocol)
-// The address will vary depending on your wiring:
-// 0b1110100 AD <-> GND
-// 0b1110111 AD <-> VCC
-// 0b1110101 AD <-> SCL
-// 0b1110110 AD <-> SDA
-#define ISSI_ADDR_DEFAULT 0x74
-
-#define ISSI_REG_CONFIG  0x00
-#define ISSI_REG_CONFIG_PICTUREMODE 0x00
-#define ISSI_REG_CONFIG_AUTOPLAYMODE 0x08
-#define ISSI_REG_CONFIG_AUDIOPLAYMODE 0x18
-
-#define ISSI_CONF_PICTUREMODE 0x00
-#define ISSI_CONF_AUTOFRAMEMODE 0x04
-#define ISSI_CONF_AUDIOMODE 0x08
-
-#define ISSI_REG_PICTUREFRAME  0x01
-
-#define ISSI_REG_SHUTDOWN 0x0A
-#define ISSI_REG_AUDIOSYNC 0x06
-
-#define ISSI_COMMANDREGISTER 0xFD
-#define ISSI_BANK_FUNCTIONREG 0x0B    // helpfully called 'page nine'
-
-// Transfer buffer for TWITransmitData()
-uint8_t g_twi_transfer_buffer[20];
-
-// These buffers match the IS31FL3731 PWM registers 0x24-0xB3.
-// Storing them like this is optimal for I2C transfers to the registers.
-// We could optimize this and take out the unused registers from these
-// buffers and the transfers in IS31FL3731_write_pwm_buffer() but it's
-// probably not worth the extra complexity.
-uint8_t g_pwm_buffer[DRIVER_COUNT][144];
-bool g_pwm_buffer_update_required = false;
-
-uint8_t g_led_control_registers[DRIVER_COUNT][18] = { { 0 }, { 0 } };
-bool g_led_control_registers_update_required = false;
-
-// This is the bit pattern in the LED control registers
-// (for matrix A, add one to register for matrix B)
-//
-//  reg -  b7  b6  b5  b4  b3  b2  b1  b0
-// 0x00 - R08,R07,R06,R05,R04,R03,R02,R01
-// 0x02 - G08,G07,G06,G05,G04,G03,G02,R00
-// 0x04 - B08,B07,B06,B05,B04,B03,G01,G00
-// 0x06 -  - , - , - , - , - ,B02,B01,B00
-// 0x08 -  - , - , - , - , - , - , - , -
-// 0x0A - B17,B16,B15, - , - , - , - , -
-// 0x0C - G17,G16,B14,B13,B12,B11,B10,B09
-// 0x0E - R17,G15,G14,G13,G12,G11,G10,G09
-// 0x10 - R16,R15,R14,R13,R12,R11,R10,R09
-
-
-void IS31FL3731_write_register( uint8_t addr, uint8_t reg, uint8_t data )
-{
-	g_twi_transfer_buffer[0] = reg;
-	g_twi_transfer_buffer[1] = data;
-
-	//Transmit data until succesful
-	while(i2c_transmit(addr << 1, g_twi_transfer_buffer,2) != 0); 
-}
-
-void IS31FL3731_write_pwm_buffer( uint8_t addr, uint8_t *pwm_buffer )
-{
-	// assumes bank is already selected
-
-	// transmit PWM registers in 9 transfers of 16 bytes
-	// g_twi_transfer_buffer[] is 20 bytes
-
-	// iterate over the pwm_buffer contents at 16 byte intervals
-	for ( int i = 0; i < 144; i += 16 )
-	{
-		// set the first register, e.g. 0x24, 0x34, 0x44, etc.
-		g_twi_transfer_buffer[0] = 0x24 + i;
-		// copy the data from i to i+15
-		// device will auto-increment register for data after the first byte
-		// thus this sets registers 0x24-0x33, 0x34-0x43, etc. in one transfer
-		for ( int j = 0; j < 16; j++ )
-		{
-			g_twi_transfer_buffer[1 + j] = pwm_buffer[i + j];
-		}
-
-		//Transmit buffer until succesful
-		while(i2c_transmit(addr << 1, g_twi_transfer_buffer,17) != 0);
-	}
-}
-
-void IS31FL3731_init( uint8_t addr )
-{
-	// In order to avoid the LEDs being driven with garbage data
-	// in the LED driver's PWM registers, first enable software shutdown,
-	// then set up the mode and other settings, clear the PWM registers,
-	// then disable software shutdown.
-
-	// select "function register" bank
-	IS31FL3731_write_register( addr, ISSI_COMMANDREGISTER, ISSI_BANK_FUNCTIONREG );
-
-	// enable software shutdown
-	IS31FL3731_write_register( addr, ISSI_REG_SHUTDOWN, 0x00 );
-	// this delay was copied from other drivers, might not be needed
-	_delay_ms( 10 );
-
-	// picture mode
-	IS31FL3731_write_register( addr, ISSI_REG_CONFIG, ISSI_REG_CONFIG_PICTUREMODE );
-	// display frame 0
-	IS31FL3731_write_register( addr, ISSI_REG_PICTUREFRAME, 0x00 );
-	// audio sync off
-	IS31FL3731_write_register( addr, ISSI_REG_AUDIOSYNC, 0x00 );
-
-	// select bank 0
-	IS31FL3731_write_register( addr, ISSI_COMMANDREGISTER, 0 );
-
-	// turn off all LEDs in the LED control register
-	for ( int i = 0x00; i <= 0x11; i++ )
-	{
-		IS31FL3731_write_register( addr, i, 0x00 );
-	}
-
-	// turn off all LEDs in the blink control register (not really needed)
-	for ( int i = 0x12; i <= 0x23; i++ )
-	{
-		IS31FL3731_write_register( addr, i, 0x00 );
-	}
-
-	// set PWM on all LEDs to 0
-	for ( int i = 0x24; i <= 0xB3; i++ )
-	{
-		IS31FL3731_write_register( addr, i, 0x00 );
-	}
-
-	// select "function register" bank
-	IS31FL3731_write_register( addr, ISSI_COMMANDREGISTER, ISSI_BANK_FUNCTIONREG );
-
-	// disable software shutdown
-	IS31FL3731_write_register( addr, ISSI_REG_SHUTDOWN, 0x01 );
-
-	// select bank 0 and leave it selected.
-	// most usage after initialization is just writing PWM buffers in bank 0
-	// as there's not much point in double-buffering
-	IS31FL3731_write_register( addr, ISSI_COMMANDREGISTER, 0 );
-}
-
-void IS31FL3731_set_color( int index, uint8_t red, uint8_t green, uint8_t blue )
-{
-	if ( index >= 0 && index < DRIVER_LED_TOTAL ) {
-		is31_led led = g_is31_leds[index];
-
-		// Subtract 0x24 to get the second index of g_pwm_buffer
-		g_pwm_buffer[led.driver][led.r - 0x24] = red;
-		g_pwm_buffer[led.driver][led.g - 0x24] = green;
-		g_pwm_buffer[led.driver][led.b - 0x24] = blue;
-		g_pwm_buffer_update_required = true;
-	}
-}
-
-void IS31FL3731_set_color_all( uint8_t red, uint8_t green, uint8_t blue )
-{
-	for ( int i = 0; i < DRIVER_LED_TOTAL; i++ )
-	{
-		IS31FL3731_set_color( i, red, green, blue );
-	}
-}
-
-void IS31FL3731_set_led_control_register( uint8_t index, bool red, bool green, bool blue )
-{
-	is31_led led = g_is31_leds[index];
-
-  uint8_t control_register_r = (led.r - 0x24) / 8;
-  uint8_t control_register_g = (led.g - 0x24) / 8;
-  uint8_t control_register_b = (led.b - 0x24) / 8;
-  uint8_t bit_r = (led.r - 0x24) % 8;
-  uint8_t bit_g = (led.g - 0x24) % 8;
-  uint8_t bit_b = (led.b - 0x24) % 8;
-
-	if ( red ) {
-		g_led_control_registers[led.driver][control_register_r] |= (1 << bit_r);
-	} else {
-		g_led_control_registers[led.driver][control_register_r] &= ~(1 << bit_r);
-	}
-	if ( green ) {
-		g_led_control_registers[led.driver][control_register_g] |= (1 << bit_g);
-	} else {
-		g_led_control_registers[led.driver][control_register_g] &= ~(1 << bit_g);
-	}
-	if ( blue ) {
-		g_led_control_registers[led.driver][control_register_b] |= (1 << bit_b);
-	} else {
-		g_led_control_registers[led.driver][control_register_b] &= ~(1 << bit_b);
-	}
-
-	g_led_control_registers_update_required = true;
-
-
-}
-
-void IS31FL3731_update_pwm_buffers( uint8_t addr1, uint8_t addr2 )
-{
-	if ( g_pwm_buffer_update_required )
-	{
-		IS31FL3731_write_pwm_buffer( addr1, g_pwm_buffer[0] );
-		IS31FL3731_write_pwm_buffer( addr2, g_pwm_buffer[1] );
-	}
-	g_pwm_buffer_update_required = false;
-}
-
-void IS31FL3731_update_led_control_registers( uint8_t addr1, uint8_t addr2 )
-{
-	if ( g_led_control_registers_update_required )
-	{
-		for ( int i=0; i<18; i++ )
-		{
-			IS31FL3731_write_register(addr1, i, g_led_control_registers[0][i] );
-			IS31FL3731_write_register(addr2, i, g_led_control_registers[1][i] );
-		}
-	}
-}
-

drivers/avr/ws2812.h

@@ -69,7 +69,4 @@ void ws2812_sendarray_mask(uint8_t *array,uint16_t length, uint8_t pinmask);
 #define CONCAT_EXP(a, b)   CONCAT(a, b)
 #endif
 
-// #define ws2812_PORTREG  CONCAT_EXP(PORT,ws2812_port)
-// #define ws2812_DDRREG   CONCAT_EXP(DDR,ws2812_port)
-
 #endif /* LIGHT_WS2812_H_ */

drivers/issi/is31fl3218.c

@@ -0,0 +1,102 @@
+/* Copyright 2018 Jason Williams (Wilba)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+#include "is31fl3218.h"
+#include "i2c_master.h"
+
+// This is the full 8-bit address
+#define ISSI_ADDRESS 0b10101000
+
+// These are the register addresses
+#define ISSI_REG_SHUTDOWN 0x00
+#define ISSI_REG_PWM 0x01
+#define ISSI_REG_CONTROL 0x13
+#define ISSI_REG_UPDATE 0x16
+#define ISSI_REG_RESET 0x17
+
+// Default timeout if no I2C response
+#define ISSI_TIMEOUT 100
+
+// Reusable buffer for transfers
+uint8_t g_twi_transfer_buffer[20];
+
+// IS31FL3218 has 18 PWM outputs and a fixed I2C address, so no chaining.
+// If used as RGB LED driver, LEDs are assigned RGB,RGB,RGB,RGB,RGB,RGB
+uint8_t g_pwm_buffer[18];
+bool g_pwm_buffer_update_required = false;
+
+void IS31FL3218_write_register( uint8_t reg, uint8_t data )
+{
+	g_twi_transfer_buffer[0] = reg;
+	g_twi_transfer_buffer[1] = data;
+	i2c_transmit( ISSI_ADDRESS, g_twi_transfer_buffer, 2, ISSI_TIMEOUT);
+}
+
+void IS31FL3218_write_pwm_buffer( uint8_t *pwm_buffer )
+{
+	g_twi_transfer_buffer[0] = ISSI_REG_PWM;
+	for ( int i=0; i<18; i++ ) {
+		g_twi_transfer_buffer[1+i] = pwm_buffer[i];
+	}
+	
+	i2c_transmit( ISSI_ADDRESS, g_twi_transfer_buffer, 19, ISSI_TIMEOUT);
+}
+
+void IS31FL3218_init(void)
+{
+	// In case we ever want to reinitialize (?)
+	IS31FL3218_write_register( ISSI_REG_RESET, 0x00 );
+	
+	// Turn off software shutdown
+	IS31FL3218_write_register( ISSI_REG_SHUTDOWN, 0x01 );
+
+	// Set all PWM values to zero
+	for ( uint8_t i = 0; i < 18; i++ ) {
+		IS31FL3218_write_register( ISSI_REG_PWM+i, 0x00 );
+	}
+	
+	// Enable all channels
+	for ( uint8_t i = 0; i < 3; i++ ) {
+		IS31FL3218_write_register( ISSI_REG_CONTROL+i, 0b00111111 );
+	}
+	
+	// Load PWM registers and LED Control register data
+	IS31FL3218_write_register( ISSI_REG_UPDATE, 0x01 );
+}
+
+void IS31FL3218_set_color( int index, uint8_t red, uint8_t green, uint8_t blue )
+{
+	g_pwm_buffer[index * 3 + 0] = red;
+	g_pwm_buffer[index * 3 + 1] = green;
+	g_pwm_buffer[index * 3 + 2] = blue;
+	g_pwm_buffer_update_required = true;
+}
+
+void IS31FL3218_set_color_all( uint8_t red, uint8_t green, uint8_t blue )
+{
+	for ( int i = 0; i < 6; i++ ) {
+		IS31FL3218_set_color( i, red, green, blue );
+	}
+}
+
+void IS31FL3218_update_pwm_buffers(void)
+{
+	if ( g_pwm_buffer_update_required ) {
+		IS31FL3218_write_pwm_buffer( g_pwm_buffer );
+		// Load PWM registers and LED Control register data
+		IS31FL3218_write_register( ISSI_REG_UPDATE, 0x01 );
+	}
+	g_pwm_buffer_update_required = false;
+}

drivers/issi/is31fl3218.h

@@ -0,0 +1,24 @@
+/* Copyright 2018 Jason Williams (Wilba)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+#pragma once
+
+#include <stdint.h>
+#include <stdbool.h>
+
+void IS31FL3218_init(void);
+void IS31FL3218_set_color( int index, uint8_t red, uint8_t green, uint8_t blue );
+void IS31FL3218_set_color_all( uint8_t red, uint8_t green, uint8_t blue );
+void IS31FL3218_update_pwm_buffers(void);

drivers/issi/is31fl3731.c

@@ -0,0 +1,270 @@
+/* Copyright 2017 Jason Williams
+ * Copyright 2018 Jack Humbert
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifdef __AVR__
+#include <avr/interrupt.h>
+#include <avr/io.h>
+#include <util/delay.h>
+#else
+#include "wait.h"
+#endif
+
+#include "is31fl3731.h"
+#include <string.h>
+#include "i2c_master.h"
+#include "progmem.h"
+
+// This is a 7-bit address, that gets left-shifted and bit 0
+// set to 0 for write, 1 for read (as per I2C protocol)
+// The address will vary depending on your wiring:
+// 0b1110100 AD <-> GND
+// 0b1110111 AD <-> VCC
+// 0b1110101 AD <-> SCL
+// 0b1110110 AD <-> SDA
+#define ISSI_ADDR_DEFAULT 0x74
+
+#define ISSI_REG_CONFIG  0x00
+#define ISSI_REG_CONFIG_PICTUREMODE 0x00
+#define ISSI_REG_CONFIG_AUTOPLAYMODE 0x08
+#define ISSI_REG_CONFIG_AUDIOPLAYMODE 0x18
+
+#define ISSI_CONF_PICTUREMODE 0x00
+#define ISSI_CONF_AUTOFRAMEMODE 0x04
+#define ISSI_CONF_AUDIOMODE 0x08
+
+#define ISSI_REG_PICTUREFRAME  0x01
+
+#define ISSI_REG_SHUTDOWN 0x0A
+#define ISSI_REG_AUDIOSYNC 0x06
+
+#define ISSI_COMMANDREGISTER 0xFD
+#define ISSI_BANK_FUNCTIONREG 0x0B    // helpfully called 'page nine'
+
+#ifndef ISSI_TIMEOUT
+  #define ISSI_TIMEOUT 100
+#endif
+
+#ifndef ISSI_PERSISTENCE
+  #define ISSI_PERSISTENCE 0
+#endif
+
+// Transfer buffer for TWITransmitData()
+uint8_t g_twi_transfer_buffer[20];
+
+// These buffers match the IS31FL3731 PWM registers 0x24-0xB3.
+// Storing them like this is optimal for I2C transfers to the registers.
+// We could optimize this and take out the unused registers from these
+// buffers and the transfers in IS31FL3731_write_pwm_buffer() but it's
+// probably not worth the extra complexity.
+uint8_t g_pwm_buffer[DRIVER_COUNT][144];
+bool g_pwm_buffer_update_required = false;
+
+uint8_t g_led_control_registers[DRIVER_COUNT][18] = { { 0 }, { 0 } };
+bool g_led_control_registers_update_required = false;
+
+// This is the bit pattern in the LED control registers
+// (for matrix A, add one to register for matrix B)
+//
+//  reg -  b7  b6  b5  b4  b3  b2  b1  b0
+// 0x00 - R08,R07,R06,R05,R04,R03,R02,R01
+// 0x02 - G08,G07,G06,G05,G04,G03,G02,R00
+// 0x04 - B08,B07,B06,B05,B04,B03,G01,G00
+// 0x06 -  - , - , - , - , - ,B02,B01,B00
+// 0x08 -  - , - , - , - , - , - , - , -
+// 0x0A - B17,B16,B15, - , - , - , - , -
+// 0x0C - G17,G16,B14,B13,B12,B11,B10,B09
+// 0x0E - R17,G15,G14,G13,G12,G11,G10,G09
+// 0x10 - R16,R15,R14,R13,R12,R11,R10,R09
+
+
+void IS31FL3731_write_register( uint8_t addr, uint8_t reg, uint8_t data )
+{
+    g_twi_transfer_buffer[0] = reg;
+    g_twi_transfer_buffer[1] = data;
+
+  #if ISSI_PERSISTENCE > 0
+    for (uint8_t i = 0; i < ISSI_PERSISTENCE; i++) {
+      if (i2c_transmit(addr << 1, g_twi_transfer_buffer, 2, ISSI_TIMEOUT) == 0)
+        break;
+    }
+  #else
+    i2c_transmit(addr << 1, g_twi_transfer_buffer, 2, ISSI_TIMEOUT);
+  #endif
+}
+
+void IS31FL3731_write_pwm_buffer( uint8_t addr, uint8_t *pwm_buffer )
+{
+    // assumes bank is already selected
+
+    // transmit PWM registers in 9 transfers of 16 bytes
+    // g_twi_transfer_buffer[] is 20 bytes
+
+    // iterate over the pwm_buffer contents at 16 byte intervals
+    for ( int i = 0; i < 144; i += 16 ) {
+        // set the first register, e.g. 0x24, 0x34, 0x44, etc.
+        g_twi_transfer_buffer[0] = 0x24 + i;
+        // copy the data from i to i+15
+        // device will auto-increment register for data after the first byte
+        // thus this sets registers 0x24-0x33, 0x34-0x43, etc. in one transfer
+        for ( int j = 0; j < 16; j++ ) {
+            g_twi_transfer_buffer[1 + j] = pwm_buffer[i + j];
+        }
+
+    #if ISSI_PERSISTENCE > 0
+      for (uint8_t i = 0; i < ISSI_PERSISTENCE; i++) {
+        if (i2c_transmit(addr << 1, g_twi_transfer_buffer, 17, ISSI_TIMEOUT) == 0)
+          break;
+      }
+    #else
+      i2c_transmit(addr << 1, g_twi_transfer_buffer, 17, ISSI_TIMEOUT);
+    #endif
+    }
+}
+
+void IS31FL3731_init( uint8_t addr )
+{
+    // In order to avoid the LEDs being driven with garbage data
+    // in the LED driver's PWM registers, first enable software shutdown,
+    // then set up the mode and other settings, clear the PWM registers,
+    // then disable software shutdown.
+
+    // select "function register" bank
+    IS31FL3731_write_register( addr, ISSI_COMMANDREGISTER, ISSI_BANK_FUNCTIONREG );
+
+    // enable software shutdown
+    IS31FL3731_write_register( addr, ISSI_REG_SHUTDOWN, 0x00 );
+    // this delay was copied from other drivers, might not be needed
+    #ifdef __AVR__
+    _delay_ms( 10 );
+    #else
+    wait_ms(10);
+    #endif
+
+    // picture mode
+    IS31FL3731_write_register( addr, ISSI_REG_CONFIG, ISSI_REG_CONFIG_PICTUREMODE );
+    // display frame 0
+    IS31FL3731_write_register( addr, ISSI_REG_PICTUREFRAME, 0x00 );
+    // audio sync off
+    IS31FL3731_write_register( addr, ISSI_REG_AUDIOSYNC, 0x00 );
+
+    // select bank 0
+    IS31FL3731_write_register( addr, ISSI_COMMANDREGISTER, 0 );
+
+    // turn off all LEDs in the LED control register
+    for ( int i = 0x00; i <= 0x11; i++ )
+    {
+        IS31FL3731_write_register( addr, i, 0x00 );
+    }
+
+    // turn off all LEDs in the blink control register (not really needed)
+    for ( int i = 0x12; i <= 0x23; i++ )
+    {
+        IS31FL3731_write_register( addr, i, 0x00 );
+    }
+
+    // set PWM on all LEDs to 0
+    for ( int i = 0x24; i <= 0xB3; i++ )
+    {
+        IS31FL3731_write_register( addr, i, 0x00 );
+    }
+
+    // select "function register" bank
+    IS31FL3731_write_register( addr, ISSI_COMMANDREGISTER, ISSI_BANK_FUNCTIONREG );
+
+    // disable software shutdown
+    IS31FL3731_write_register( addr, ISSI_REG_SHUTDOWN, 0x01 );
+
+    // select bank 0 and leave it selected.
+    // most usage after initialization is just writing PWM buffers in bank 0
+    // as there's not much point in double-buffering
+    IS31FL3731_write_register( addr, ISSI_COMMANDREGISTER, 0 );
+
+}
+
+void IS31FL3731_set_color( int index, uint8_t red, uint8_t green, uint8_t blue )
+{
+    if ( index >= 0 && index < DRIVER_LED_TOTAL ) {
+        is31_led led = g_is31_leds[index];
+
+        // Subtract 0x24 to get the second index of g_pwm_buffer
+        g_pwm_buffer[led.driver][led.r - 0x24] = red;
+        g_pwm_buffer[led.driver][led.g - 0x24] = green;
+        g_pwm_buffer[led.driver][led.b - 0x24] = blue;
+        g_pwm_buffer_update_required = true;
+    }
+}
+
+void IS31FL3731_set_color_all( uint8_t red, uint8_t green, uint8_t blue )
+{
+    for ( int i = 0; i < DRIVER_LED_TOTAL; i++ )
+    {
+        IS31FL3731_set_color( i, red, green, blue );
+    }
+}
+
+void IS31FL3731_set_led_control_register( uint8_t index, bool red, bool green, bool blue )
+{
+    is31_led led = g_is31_leds[index];
+
+  uint8_t control_register_r = (led.r - 0x24) / 8;
+  uint8_t control_register_g = (led.g - 0x24) / 8;
+  uint8_t control_register_b = (led.b - 0x24) / 8;
+  uint8_t bit_r = (led.r - 0x24) % 8;
+  uint8_t bit_g = (led.g - 0x24) % 8;
+  uint8_t bit_b = (led.b - 0x24) % 8;
+
+    if ( red ) {
+        g_led_control_registers[led.driver][control_register_r] |= (1 << bit_r);
+    } else {
+        g_led_control_registers[led.driver][control_register_r] &= ~(1 << bit_r);
+    }
+    if ( green ) {
+        g_led_control_registers[led.driver][control_register_g] |= (1 << bit_g);
+    } else {
+        g_led_control_registers[led.driver][control_register_g] &= ~(1 << bit_g);
+    }
+    if ( blue ) {
+        g_led_control_registers[led.driver][control_register_b] |= (1 << bit_b);
+    } else {
+        g_led_control_registers[led.driver][control_register_b] &= ~(1 << bit_b);
+    }
+
+    g_led_control_registers_update_required = true;
+
+}
+
+void IS31FL3731_update_pwm_buffers( uint8_t addr1, uint8_t addr2 )
+{
+    if ( g_pwm_buffer_update_required )
+    {
+        IS31FL3731_write_pwm_buffer( addr1, g_pwm_buffer[0] );
+        IS31FL3731_write_pwm_buffer( addr2, g_pwm_buffer[1] );
+    }
+    g_pwm_buffer_update_required = false;
+}
+
+void IS31FL3731_update_led_control_registers( uint8_t addr1, uint8_t addr2 )
+{
+    if ( g_led_control_registers_update_required )
+    {
+        for ( int i=0; i<18; i++ )
+        {
+            IS31FL3731_write_register(addr1, i, g_led_control_registers[0][i] );
+            IS31FL3731_write_register(addr2, i, g_led_control_registers[1][i] );
+        }
+    }
+}

drivers/issi/is31fl3731.h

@@ -23,7 +23,7 @@
 #include <stdbool.h>
 
 typedef struct is31_led {
-	uint8_t driver:2;
+  uint8_t driver:2;
   uint8_t r;
   uint8_t g;
   uint8_t b;

drivers/issi/is31fl3733.c

@@ -0,0 +1,252 @@
+/* Copyright 2017 Jason Williams
+ * Copyright 2018 Jack Humbert
+ * Copyright 2018 Yiancar
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifdef __AVR__
+#include <avr/interrupt.h>
+#include <avr/io.h>
+#include <util/delay.h>
+#else
+#include "wait.h"
+#endif
+
+#include <string.h>
+#include "i2c_master.h"
+#include "progmem.h"
+#include "rgb_matrix.h"
+
+// This is a 7-bit address, that gets left-shifted and bit 0
+// set to 0 for write, 1 for read (as per I2C protocol)
+// The address will vary depending on your wiring:
+// 00 <-> GND
+// 01 <-> SCL
+// 10 <-> SDA
+// 11 <-> VCC
+// ADDR1 represents A1:A0 of the 7-bit address.
+// ADDR2 represents A3:A2 of the 7-bit address.
+// The result is: 0b101(ADDR2)(ADDR1)
+#define ISSI_ADDR_DEFAULT 0x50
+
+#define ISSI_COMMANDREGISTER 0xFD
+#define ISSI_COMMANDREGISTER_WRITELOCK 0xFE
+#define ISSI_INTERRUPTMASKREGISTER 0xF0
+#define ISSI_INTERRUPTSTATUSREGISTER 0xF1
+
+#define ISSI_PAGE_LEDCONTROL 0x00 //PG0
+#define ISSI_PAGE_PWM 0x01        //PG1
+#define ISSI_PAGE_AUTOBREATH 0x02 //PG2
+#define ISSI_PAGE_FUNCTION 0x03   //PG3
+
+#define ISSI_REG_CONFIGURATION 0x00 //PG3
+#define ISSI_REG_GLOBALCURRENT 0x01 //PG3
+#define ISSI_REG_RESET 0x11// PG3
+#define ISSI_REG_SWPULLUP 0x0F //PG3
+#define ISSI_REG_CSPULLUP 0x10 //PG3
+
+#ifndef ISSI_TIMEOUT
+  #define ISSI_TIMEOUT 100
+#endif
+
+#ifndef ISSI_PERSISTENCE
+  #define ISSI_PERSISTENCE 0
+#endif
+
+// Transfer buffer for TWITransmitData()
+uint8_t g_twi_transfer_buffer[20];
+
+// These buffers match the IS31FL3733 PWM registers.
+// The control buffers match the PG0 LED On/Off registers.
+// Storing them like this is optimal for I2C transfers to the registers.
+// We could optimize this and take out the unused registers from these
+// buffers and the transfers in IS31FL3733_write_pwm_buffer() but it's
+// probably not worth the extra complexity.
+uint8_t g_pwm_buffer[DRIVER_COUNT][192];
+bool g_pwm_buffer_update_required = false;
+
+uint8_t g_led_control_registers[DRIVER_COUNT][24] = { { 0 }, { 0 } };
+bool g_led_control_registers_update_required = false;
+
+void IS31FL3733_write_register( uint8_t addr, uint8_t reg, uint8_t data )
+{
+    g_twi_transfer_buffer[0] = reg;
+    g_twi_transfer_buffer[1] = data;
+
+  #if ISSI_PERSISTENCE > 0
+    for (uint8_t i = 0; i < ISSI_PERSISTENCE; i++) {
+      if (i2c_transmit(addr << 1, g_twi_transfer_buffer, 2, ISSI_TIMEOUT) == 0)
+        break;
+    }
+  #else
+    i2c_transmit(addr << 1, g_twi_transfer_buffer, 2, ISSI_TIMEOUT);
+  #endif
+}
+
+void IS31FL3733_write_pwm_buffer( uint8_t addr, uint8_t *pwm_buffer )
+{
+    // assumes PG1 is already selected
+
+    // transmit PWM registers in 12 transfers of 16 bytes
+    // g_twi_transfer_buffer[] is 20 bytes
+
+    // iterate over the pwm_buffer contents at 16 byte intervals
+    for ( int i = 0; i < 192; i += 16 ) {
+        g_twi_transfer_buffer[0] = i;
+        // copy the data from i to i+15
+        // device will auto-increment register for data after the first byte
+        // thus this sets registers 0x00-0x0F, 0x10-0x1F, etc. in one transfer
+        for ( int j = 0; j < 16; j++ ) {
+            g_twi_transfer_buffer[1 + j] = pwm_buffer[i + j];
+        }
+
+    #if ISSI_PERSISTENCE > 0
+      for (uint8_t i = 0; i < ISSI_PERSISTENCE; i++) {
+        if (i2c_transmit(addr << 1, g_twi_transfer_buffer, 17, ISSI_TIMEOUT) == 0)
+          break;
+      }
+    #else
+      i2c_transmit(addr << 1, g_twi_transfer_buffer, 17, ISSI_TIMEOUT);
+    #endif
+    }
+}
+
+void IS31FL3733_init( uint8_t addr )
+{
+    // In order to avoid the LEDs being driven with garbage data
+    // in the LED driver's PWM registers, shutdown is enabled last.
+    // Set up the mode and other settings, clear the PWM registers,
+    // then disable software shutdown.
+
+    // Unlock the command register.
+    IS31FL3733_write_register( addr, ISSI_COMMANDREGISTER_WRITELOCK, 0xC5 );
+
+    // Select PG0
+    IS31FL3733_write_register( addr, ISSI_COMMANDREGISTER, ISSI_PAGE_LEDCONTROL );
+    // Turn off all LEDs.
+    for ( int i = 0x00; i <= 0x17; i++ )
+    {
+        IS31FL3733_write_register( addr, i, 0x00 );
+    }
+
+    // Unlock the command register.
+    IS31FL3733_write_register( addr, ISSI_COMMANDREGISTER_WRITELOCK, 0xC5 );
+
+    // Select PG1
+    IS31FL3733_write_register( addr, ISSI_COMMANDREGISTER, ISSI_PAGE_PWM );
+    // Set PWM on all LEDs to 0
+    // No need to setup Breath registers to PWM as that is the default.
+    for ( int i = 0x00; i <= 0xBF; i++ )
+    {
+        IS31FL3733_write_register( addr, i, 0x00 );
+    }
+
+    // Unlock the command register.
+    IS31FL3733_write_register( addr, ISSI_COMMANDREGISTER_WRITELOCK, 0xC5 );
+
+    // Select PG3
+    IS31FL3733_write_register( addr, ISSI_COMMANDREGISTER, ISSI_PAGE_FUNCTION );
+    // Set global current to maximum.
+    IS31FL3733_write_register( addr, ISSI_REG_GLOBALCURRENT, 0xFF );
+    // Disable software shutdown.
+    IS31FL3733_write_register( addr, ISSI_REG_CONFIGURATION, 0x01 );
+
+    // Wait 10ms to ensure the device has woken up.
+    #ifdef __AVR__
+    _delay_ms( 10 );
+    #else
+    wait_ms(10);
+    #endif
+}
+
+void IS31FL3733_set_color( int index, uint8_t red, uint8_t green, uint8_t blue )
+{
+    if ( index >= 0 && index < DRIVER_LED_TOTAL ) {
+        is31_led led = g_is31_leds[index];
+
+        g_pwm_buffer[led.driver][led.r] = red;
+        g_pwm_buffer[led.driver][led.g] = green;
+        g_pwm_buffer[led.driver][led.b] = blue;
+        g_pwm_buffer_update_required = true;
+    }
+}
+
+void IS31FL3733_set_color_all( uint8_t red, uint8_t green, uint8_t blue )
+{
+    for ( int i = 0; i < DRIVER_LED_TOTAL; i++ )
+    {
+        IS31FL3733_set_color( i, red, green, blue );
+    }
+}
+
+void IS31FL3733_set_led_control_register( uint8_t index, bool red, bool green, bool blue )
+{
+    is31_led led = g_is31_leds[index];
+
+  uint8_t control_register_r = led.r / 8;
+  uint8_t control_register_g = led.g / 8;
+  uint8_t control_register_b = led.b / 8;
+  uint8_t bit_r = led.r % 8;
+  uint8_t bit_g = led.g % 8;
+  uint8_t bit_b = led.b % 8;
+
+    if ( red ) {
+        g_led_control_registers[led.driver][control_register_r] |= (1 << bit_r);
+    } else {
+        g_led_control_registers[led.driver][control_register_r] &= ~(1 << bit_r);
+    }
+    if ( green ) {
+        g_led_control_registers[led.driver][control_register_g] |= (1 << bit_g);
+    } else {
+        g_led_control_registers[led.driver][control_register_g] &= ~(1 << bit_g);
+    }
+    if ( blue ) {
+        g_led_control_registers[led.driver][control_register_b] |= (1 << bit_b);
+    } else {
+        g_led_control_registers[led.driver][control_register_b] &= ~(1 << bit_b);
+    }
+
+    g_led_control_registers_update_required = true;
+
+}
+
+void IS31FL3733_update_pwm_buffers( uint8_t addr1, uint8_t addr2 )
+{
+    if ( g_pwm_buffer_update_required )
+    {
+        // Firstly we need to unlock the command register and select PG1
+        IS31FL3733_write_register( addr1, ISSI_COMMANDREGISTER_WRITELOCK, 0xC5 );
+        IS31FL3733_write_register( addr1, ISSI_COMMANDREGISTER, ISSI_PAGE_PWM );
+
+        IS31FL3733_write_pwm_buffer( addr1, g_pwm_buffer[0] );
+        //IS31FL3733_write_pwm_buffer( addr2, g_pwm_buffer[1] );
+    }
+    g_pwm_buffer_update_required = false;
+}
+
+void IS31FL3733_update_led_control_registers( uint8_t addr1, uint8_t addr2 )
+{
+    if ( g_led_control_registers_update_required )
+    {
+        // Firstly we need to unlock the command register and select PG0
+        IS31FL3733_write_register( addr1, ISSI_COMMANDREGISTER_WRITELOCK, 0xC5 );
+        IS31FL3733_write_register( addr1, ISSI_COMMANDREGISTER, ISSI_PAGE_LEDCONTROL );
+        for ( int i=0; i<24; i++ )
+        {
+            IS31FL3733_write_register(addr1, i, g_led_control_registers[0][i] );
+            //IS31FL3733_write_register(addr2, i, g_led_control_registers[1][i] );
+        }
+    }
+}

drivers/issi/is31fl3733.h

@@ -0,0 +1,255 @@
+/* Copyright 2017 Jason Williams
+ * Copyright 2018 Jack Humbert
+ * Copyright 2018 Yiancar
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+
+#ifndef IS31FL3733_DRIVER_H
+#define IS31FL3733_DRIVER_H
+
+#include <stdint.h>
+#include <stdbool.h>
+
+typedef struct is31_led {
+  uint8_t driver:2;
+  uint8_t r;
+  uint8_t g;
+  uint8_t b;
+} __attribute__((packed)) is31_led;
+
+extern const is31_led g_is31_leds[DRIVER_LED_TOTAL];
+
+void IS31FL3733_init( uint8_t addr );
+void IS31FL3733_write_register( uint8_t addr, uint8_t reg, uint8_t data );
+void IS31FL3733_write_pwm_buffer( uint8_t addr, uint8_t *pwm_buffer );
+
+void IS31FL3733_set_color( int index, uint8_t red, uint8_t green, uint8_t blue );
+void IS31FL3733_set_color_all( uint8_t red, uint8_t green, uint8_t blue );
+
+void IS31FL3733_set_led_control_register( uint8_t index, bool red, bool green, bool blue );
+
+// This should not be called from an interrupt
+// (eg. from a timer interrupt).
+// Call this while idle (in between matrix scans).
+// If the buffer is dirty, it will update the driver with the buffer.
+void IS31FL3733_update_pwm_buffers( uint8_t addr1, uint8_t addr2 );
+void IS31FL3733_update_led_control_registers( uint8_t addr1, uint8_t addr2 );
+
+#define A_1  0x00
+#define A_2  0x01
+#define A_3  0x02
+#define A_4  0x03
+#define A_5  0x04
+#define A_6  0x05
+#define A_7  0x06
+#define A_8  0x07
+#define A_9  0x08
+#define A_10  0x09
+#define A_11  0x0A
+#define A_12  0x0B
+#define A_13  0x0C
+#define A_14  0x0D
+#define A_15  0x0E
+#define A_16  0x0F
+
+#define B_1  0x10
+#define B_2  0x11
+#define B_3  0x12
+#define B_4  0x13
+#define B_5  0x14
+#define B_6  0x15
+#define B_7  0x16
+#define B_8  0x17
+#define B_9  0x18
+#define B_10  0x19
+#define B_11  0x1A
+#define B_12  0x1B
+#define B_13  0x1C
+#define B_14  0x1D
+#define B_15  0x1E
+#define B_16  0x1F
+
+#define C_1  0x20
+#define C_2  0x21
+#define C_3  0x22
+#define C_4  0x23
+#define C_5  0x24
+#define C_6  0x25
+#define C_7  0x26
+#define C_8  0x27
+#define C_9  0x28
+#define C_10  0x29
+#define C_11  0x2A
+#define C_12  0x2B
+#define C_13  0x2C
+#define C_14  0x2D
+#define C_15  0x2E
+#define C_16  0x2F
+
+#define D_1  0x30
+#define D_2  0x31
+#define D_3  0x32
+#define D_4  0x33
+#define D_5  0x34
+#define D_6  0x35
+#define D_7  0x36
+#define D_8  0x37
+#define D_9  0x38
+#define D_10  0x39
+#define D_11  0x3A
+#define D_12  0x3B
+#define D_13  0x3C
+#define D_14  0x3D
+#define D_15  0x3E
+#define D_16  0x3F
+
+#define E_1  0x40
+#define E_2  0x41
+#define E_3  0x42
+#define E_4  0x43
+#define E_5  0x44
+#define E_6  0x45
+#define E_7  0x46
+#define E_8  0x47
+#define E_9  0x48
+#define E_10  0x49
+#define E_11  0x4A
+#define E_12  0x4B
+#define E_13  0x4C
+#define E_14  0x4D
+#define E_15  0x4E
+#define E_16  0x4F
+
+#define F_1  0x50
+#define F_2  0x51
+#define F_3  0x52
+#define F_4  0x53
+#define F_5  0x54
+#define F_6  0x55
+#define F_7  0x56
+#define F_8  0x57
+#define F_9  0x58
+#define F_10  0x59
+#define F_11  0x5A
+#define F_12  0x5B
+#define F_13  0x5C
+#define F_14  0x5D
+#define F_15  0x5E
+#define F_16  0x5F
+
+#define G_1  0x60
+#define G_2  0x61
+#define G_3  0x62
+#define G_4  0x63
+#define G_5  0x64
+#define G_6  0x65
+#define G_7  0x66
+#define G_8  0x67
+#define G_9  0x68
+#define G_10  0x69
+#define G_11  0x6A
+#define G_12  0x6B
+#define G_13  0x6C
+#define G_14  0x6D
+#define G_15  0x6E
+#define G_16  0x6F
+
+#define H_1  0x70
+#define H_2  0x71
+#define H_3  0x72
+#define H_4  0x73
+#define H_5  0x74
+#define H_6  0x75
+#define H_7  0x76
+#define H_8  0x77
+#define H_9  0x78
+#define H_10  0x79
+#define H_11  0x7A
+#define H_12  0x7B
+#define H_13  0x7C
+#define H_14  0x7D
+#define H_15  0x7E
+#define H_16  0x7F
+
+#define I_1  0x80
+#define I_2  0x81
+#define I_3  0x82
+#define I_4  0x83
+#define I_5  0x84
+#define I_6  0x85
+#define I_7  0x86
+#define I_8  0x87
+#define I_9  0x88
+#define I_10  0x89
+#define I_11  0x8A
+#define I_12  0x8B
+#define I_13  0x8C
+#define I_14  0x8D
+#define I_15  0x8E
+#define I_16  0x8F
+
+#define J_1  0x90
+#define J_2  0x91
+#define J_3  0x92
+#define J_4  0x93
+#define J_5  0x94
+#define J_6  0x95
+#define J_7  0x96
+#define J_8  0x97
+#define J_9  0x98
+#define J_10  0x99
+#define J_11  0x9A
+#define J_12  0x9B
+#define J_13  0x9C
+#define J_14  0x9D
+#define J_15  0x9E
+#define J_16  0x9F
+
+#define K_1  0xA0
+#define K_2  0xA1
+#define K_3  0xA2
+#define K_4  0xA3
+#define K_5  0xA4
+#define K_6  0xA5
+#define K_7  0xA6
+#define K_8  0xA7
+#define K_9  0xA8
+#define K_10  0xA9
+#define K_11  0xAA
+#define K_12  0xAB
+#define K_13  0xAC
+#define K_14  0xAD
+#define K_15  0xAE
+#define K_16  0xAF
+
+#define L_1  0xB0
+#define L_2  0xB1
+#define L_3  0xB2
+#define L_4  0xB3
+#define L_5  0xB4
+#define L_6  0xB5
+#define L_7  0xB6
+#define L_8  0xB7
+#define L_9  0xB8
+#define L_10  0xB9
+#define L_11  0xBA
+#define L_12  0xBB
+#define L_13  0xBC
+#define L_14  0xBD
+#define L_15  0xBE
+#define L_16  0xBF
+
+#endif // IS31FL3733_DRIVER_H

drivers/issi/is31fl3736.c

@@ -0,0 +1,306 @@
+/* Copyright 2018 Jason Williams (Wilba)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+
+#ifdef __AVR__
+#include <avr/interrupt.h>
+#include <avr/io.h>
+#include <util/delay.h>
+#else
+#include "wait.h"
+#endif
+
+#include "is31fl3736.h"
+#include <string.h>
+#include "i2c_master.h"
+#include "progmem.h"
+
+
+
+// This is a 7-bit address, that gets left-shifted and bit 0
+// set to 0 for write, 1 for read (as per I2C protocol)
+// The address will vary depending on your wiring:
+// 00 <-> GND
+// 01 <-> SCL
+// 10 <-> SDA
+// 11 <-> VCC
+// ADDR1 represents A1:A0 of the 7-bit address.
+// ADDR2 represents A3:A2 of the 7-bit address.
+// The result is: 0b101(ADDR2)(ADDR1)
+#define ISSI_ADDR_DEFAULT 0x50
+
+#define ISSI_COMMANDREGISTER 0xFD
+#define ISSI_COMMANDREGISTER_WRITELOCK 0xFE
+#define ISSI_INTERRUPTMASKREGISTER 0xF0
+#define ISSI_INTERRUPTSTATUSREGISTER 0xF1
+
+#define ISSI_PAGE_LEDCONTROL 0x00 //PG0
+#define ISSI_PAGE_PWM 0x01        //PG1
+#define ISSI_PAGE_AUTOBREATH 0x02 //PG2
+#define ISSI_PAGE_FUNCTION 0x03   //PG3
+
+#define ISSI_REG_CONFIGURATION 0x00 //PG3
+#define ISSI_REG_GLOBALCURRENT 0x01 //PG3
+#define ISSI_REG_RESET 0x11// PG3
+#define ISSI_REG_SWPULLUP 0x0F //PG3
+#define ISSI_REG_CSPULLUP 0x10 //PG3
+
+#ifndef ISSI_TIMEOUT
+  #define ISSI_TIMEOUT 100
+#endif
+
+#ifndef ISSI_PERSISTENCE
+  #define ISSI_PERSISTENCE 0
+#endif
+
+// Transfer buffer for TWITransmitData()
+uint8_t g_twi_transfer_buffer[20];
+
+// These buffers match the IS31FL3736 PWM registers.
+// The control buffers match the PG0 LED On/Off registers.
+// Storing them like this is optimal for I2C transfers to the registers.
+// We could optimize this and take out the unused registers from these
+// buffers and the transfers in IS31FL3736_write_pwm_buffer() but it's
+// probably not worth the extra complexity.
+uint8_t g_pwm_buffer[DRIVER_COUNT][192];
+bool g_pwm_buffer_update_required = false;
+
+uint8_t g_led_control_registers[DRIVER_COUNT][24] = { { 0 }, { 0 } };
+bool g_led_control_registers_update_required = false;
+
+void IS31FL3736_write_register( uint8_t addr, uint8_t reg, uint8_t data )
+{
+    g_twi_transfer_buffer[0] = reg;
+    g_twi_transfer_buffer[1] = data;
+
+  #if ISSI_PERSISTENCE > 0
+    for (uint8_t i = 0; i < ISSI_PERSISTENCE; i++) {
+      if (i2c_transmit(addr << 1, g_twi_transfer_buffer, 2, ISSI_TIMEOUT) == 0)
+        break;
+    }
+  #else
+    i2c_transmit(addr << 1, g_twi_transfer_buffer, 2, ISSI_TIMEOUT);
+  #endif
+}
+
+void IS31FL3736_write_pwm_buffer( uint8_t addr, uint8_t *pwm_buffer )
+{
+    // assumes PG1 is already selected
+
+    // transmit PWM registers in 12 transfers of 16 bytes
+    // g_twi_transfer_buffer[] is 20 bytes
+
+    // iterate over the pwm_buffer contents at 16 byte intervals
+    for ( int i = 0; i < 192; i += 16 ) {
+        g_twi_transfer_buffer[0] = i;
+        // copy the data from i to i+15
+        // device will auto-increment register for data after the first byte
+        // thus this sets registers 0x00-0x0F, 0x10-0x1F, etc. in one transfer
+        for ( int j = 0; j < 16; j++ ) {
+            g_twi_transfer_buffer[1 + j] = pwm_buffer[i + j];
+        }
+
+    #if ISSI_PERSISTENCE > 0
+      for (uint8_t i = 0; i < ISSI_PERSISTENCE; i++) {
+        if (i2c_transmit(addr << 1, g_twi_transfer_buffer, 17, ISSI_TIMEOUT) == 0)
+          break;
+      }
+    #else
+      i2c_transmit(addr << 1, g_twi_transfer_buffer, 17, ISSI_TIMEOUT);
+    #endif
+    }
+}
+
+void IS31FL3736_init( uint8_t addr )
+{
+    // In order to avoid the LEDs being driven with garbage data
+    // in the LED driver's PWM registers, shutdown is enabled last.
+    // Set up the mode and other settings, clear the PWM registers,
+    // then disable software shutdown.
+
+    // Unlock the command register.
+    IS31FL3736_write_register( addr, ISSI_COMMANDREGISTER_WRITELOCK, 0xC5 );
+
+    // Select PG0
+    IS31FL3736_write_register( addr, ISSI_COMMANDREGISTER, ISSI_PAGE_LEDCONTROL );
+    // Turn off all LEDs.
+    for ( int i = 0x00; i <= 0x17; i++ )
+    {
+        IS31FL3736_write_register( addr, i, 0x00 );
+    }
+
+    // Unlock the command register.
+    IS31FL3736_write_register( addr, ISSI_COMMANDREGISTER_WRITELOCK, 0xC5 );
+
+    // Select PG1
+    IS31FL3736_write_register( addr, ISSI_COMMANDREGISTER, ISSI_PAGE_PWM );
+    // Set PWM on all LEDs to 0
+    // No need to setup Breath registers to PWM as that is the default.
+    for ( int i = 0x00; i <= 0xBF; i++ )
+    {
+        IS31FL3736_write_register( addr, i, 0x00 );
+    }
+
+    // Unlock the command register.
+    IS31FL3736_write_register( addr, ISSI_COMMANDREGISTER_WRITELOCK, 0xC5 );
+
+    // Select PG3
+    IS31FL3736_write_register( addr, ISSI_COMMANDREGISTER, ISSI_PAGE_FUNCTION );
+    // Set global current to maximum.
+    IS31FL3736_write_register( addr, ISSI_REG_GLOBALCURRENT, 0xFF );
+    // Disable software shutdown.
+    IS31FL3736_write_register( addr, ISSI_REG_CONFIGURATION, 0x01 );
+
+    // Wait 10ms to ensure the device has woken up.
+    #ifdef __AVR__
+    _delay_ms( 10 );
+    #else
+    wait_ms(10);
+    #endif
+}
+
+void IS31FL3736_set_color( int index, uint8_t red, uint8_t green, uint8_t blue )
+{
+    if ( index >= 0 && index < DRIVER_LED_TOTAL ) {
+        is31_led led = g_is31_leds[index];
+
+        g_pwm_buffer[led.driver][led.r] = red;
+        g_pwm_buffer[led.driver][led.g] = green;
+        g_pwm_buffer[led.driver][led.b] = blue;
+        g_pwm_buffer_update_required = true;
+    }
+}
+
+void IS31FL3736_set_color_all( uint8_t red, uint8_t green, uint8_t blue )
+{
+    for ( int i = 0; i < DRIVER_LED_TOTAL; i++ )
+    {
+        IS31FL3736_set_color( i, red, green, blue );
+    }
+}
+
+void IS31FL3736_set_led_control_register( uint8_t index, bool red, bool green, bool blue )
+{
+    is31_led led = g_is31_leds[index];
+
+    // IS31FL3733
+    // The PWM register for a matrix position (0x00 to 0xBF) can be
+    // divided by 8 to get the LED control register (0x00 to 0x17),
+    // then mod 8 to get the bit position within that register.
+
+    // IS31FL3736
+    // The PWM register for a matrix position (0x00 to 0xBF) is interleaved, so:
+    // A1=0x00 A2=0x02 A3=0x04 A4=0x06 A5=0x08 A6=0x0A A7=0x0C A8=0x0E
+    // B1=0x10 B2=0x12 B3=0x14
+    // But also, the LED control registers (0x00 to 0x17) are also interleaved, so:
+    // A1-A4=0x00 A5-A8=0x01
+    // So, the same math applies.
+
+	uint8_t control_register_r = led.r / 8;
+	uint8_t control_register_g = led.g / 8;
+	uint8_t control_register_b = led.b / 8;
+
+	uint8_t bit_r = led.r % 8;
+	uint8_t bit_g = led.g % 8;
+	uint8_t bit_b = led.b % 8;
+
+    if ( red ) {
+        g_led_control_registers[led.driver][control_register_r] |= (1 << bit_r);
+    } else {
+        g_led_control_registers[led.driver][control_register_r] &= ~(1 << bit_r);
+    }
+    if ( green ) {
+        g_led_control_registers[led.driver][control_register_g] |= (1 << bit_g);
+    } else {
+        g_led_control_registers[led.driver][control_register_g] &= ~(1 << bit_g);
+    }
+    if ( blue ) {
+        g_led_control_registers[led.driver][control_register_b] |= (1 << bit_b);
+    } else {
+        g_led_control_registers[led.driver][control_register_b] &= ~(1 << bit_b);
+    }
+
+    g_led_control_registers_update_required = true;
+
+}
+
+void IS31FL3736_mono_set_brightness( int index, uint8_t value )
+{
+    if ( index >= 0 && index < 96 ) {
+    	// Index in range 0..95 -> A1..A8, B1..B8, etc.
+    	// Map index 0..95 to registers 0x00..0xBE (interleaved)
+    	uint8_t pwm_register = index * 2;
+        g_pwm_buffer[0][pwm_register] = value;
+        g_pwm_buffer_update_required = true;
+    }
+}
+
+void IS31FL3736_mono_set_brightness_all( uint8_t value )
+{
+    for ( int i = 0; i < 96; i++ )
+    {
+    	IS31FL3736_mono_set_brightness( i, value );
+    }
+}
+
+void IS31FL3736_mono_set_led_control_register( uint8_t index, bool enabled )
+{
+	// Index in range 0..95 -> A1..A8, B1..B8, etc.
+
+	// Map index 0..95 to registers 0x00..0xBE (interleaved)
+	uint8_t pwm_register = index * 2;
+	// Map register 0x00..0xBE (interleaved) into control register and bit
+	uint8_t control_register = pwm_register / 8;
+	uint8_t bit = pwm_register % 8;
+
+    if ( enabled ) {
+        g_led_control_registers[0][control_register] |= (1 << bit);
+    } else {
+        g_led_control_registers[0][control_register] &= ~(1 << bit);
+    }
+
+    g_led_control_registers_update_required = true;
+}
+
+void IS31FL3736_update_pwm_buffers( uint8_t addr1, uint8_t addr2 )
+{
+    if ( g_pwm_buffer_update_required )
+    {
+        // Firstly we need to unlock the command register and select PG1
+        IS31FL3736_write_register( addr1, ISSI_COMMANDREGISTER_WRITELOCK, 0xC5 );
+        IS31FL3736_write_register( addr1, ISSI_COMMANDREGISTER, ISSI_PAGE_PWM );
+
+        IS31FL3736_write_pwm_buffer( addr1, g_pwm_buffer[0] );
+        //IS31FL3736_write_pwm_buffer( addr2, g_pwm_buffer[1] );
+    }
+    g_pwm_buffer_update_required = false;
+}
+
+void IS31FL3736_update_led_control_registers( uint8_t addr1, uint8_t addr2 )
+{
+    if ( g_led_control_registers_update_required )
+    {
+        // Firstly we need to unlock the command register and select PG0
+        IS31FL3736_write_register( addr1, ISSI_COMMANDREGISTER_WRITELOCK, 0xC5 );
+        IS31FL3736_write_register( addr1, ISSI_COMMANDREGISTER, ISSI_PAGE_LEDCONTROL );
+        for ( int i=0; i<24; i++ )
+        {
+            IS31FL3736_write_register(addr1, i, g_led_control_registers[0][i] );
+            //IS31FL3736_write_register(addr2, i, g_led_control_registers[1][i] );
+        }
+    }
+}
+

drivers/issi/is31fl3736.h

@@ -0,0 +1,172 @@
+/* Copyright 2018 Jason Williams (Wilba)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include <stdbool.h>
+
+
+// Simple interface option.
+// If these aren't defined, just define them to make it compile
+
+
+#ifndef DRIVER_COUNT
+#define DRIVER_COUNT 2
+#endif
+
+#ifndef DRIVER_LED_TOTAL
+#define DRIVER_LED_TOTAL 96
+#endif
+
+
+typedef struct is31_led {
+  uint8_t driver:2;
+  uint8_t r;
+  uint8_t g;
+  uint8_t b;
+} __attribute__((packed)) is31_led;
+
+extern const is31_led g_is31_leds[DRIVER_LED_TOTAL];
+
+void IS31FL3736_init( uint8_t addr );
+void IS31FL3736_write_register( uint8_t addr, uint8_t reg, uint8_t data );
+void IS31FL3736_write_pwm_buffer( uint8_t addr, uint8_t *pwm_buffer );
+
+void IS31FL3736_set_color( int index, uint8_t red, uint8_t green, uint8_t blue );
+void IS31FL3736_set_color_all( uint8_t red, uint8_t green, uint8_t blue );
+
+void IS31FL3736_set_led_control_register( uint8_t index, bool red, bool green, bool blue );
+
+void IS31FL3736_mono_set_brightness( int index, uint8_t value );
+void IS31FL3736_mono_set_brightness_all( uint8_t value );
+void IS31FL3736_mono_set_led_control_register( uint8_t index, bool enabled );
+
+// This should not be called from an interrupt
+// (eg. from a timer interrupt).
+// Call this while idle (in between matrix scans).
+// If the buffer is dirty, it will update the driver with the buffer.
+void IS31FL3736_update_pwm_buffers( uint8_t addr1, uint8_t addr2 );
+void IS31FL3736_update_led_control_registers( uint8_t addr1, uint8_t addr2 );
+
+#define A_1  0x00
+#define A_2  0x02
+#define A_3  0x04
+#define A_4  0x06
+#define A_5  0x08
+#define A_6  0x0A
+#define A_7  0x0C
+#define A_8  0x0E
+
+#define B_1  0x10
+#define B_2  0x12
+#define B_3  0x14
+#define B_4  0x16
+#define B_5  0x18
+#define B_6  0x1A
+#define B_7  0x1C
+#define B_8  0x1E
+
+#define C_1  0x20
+#define C_2  0x22
+#define C_3  0x24
+#define C_4  0x26
+#define C_5  0x28
+#define C_6  0x2A
+#define C_7  0x2C
+#define C_8  0x2E
+
+#define D_1  0x30
+#define D_2  0x32
+#define D_3  0x34
+#define D_4  0x36
+#define D_5  0x38
+#define D_6  0x3A
+#define D_7  0x3C
+#define D_8  0x3E
+
+#define E_1  0x40
+#define E_2  0x42
+#define E_3  0x44
+#define E_4  0x46
+#define E_5  0x48
+#define E_6  0x4A
+#define E_7  0x4C
+#define E_8  0x4E
+
+#define F_1  0x50
+#define F_2  0x52
+#define F_3  0x54
+#define F_4  0x56
+#define F_5  0x58
+#define F_6  0x5A
+#define F_7  0x5C
+#define F_8  0x5E
+
+#define G_1  0x60
+#define G_2  0x62
+#define G_3  0x64
+#define G_4  0x66
+#define G_5  0x68
+#define G_6  0x6A
+#define G_7  0x6C
+#define G_8  0x6E
+
+#define H_1  0x70
+#define H_2  0x72
+#define H_3  0x74
+#define H_4  0x76
+#define H_5  0x78
+#define H_6  0x7A
+#define H_7  0x7C
+#define H_8  0x7E
+
+#define I_1  0x80
+#define I_2  0x82
+#define I_3  0x84
+#define I_4  0x86
+#define I_5  0x88
+#define I_6  0x8A
+#define I_7  0x8C
+#define I_8  0x8E
+
+#define J_1  0x90
+#define J_2  0x92
+#define J_3  0x94
+#define J_4  0x96
+#define J_5  0x98
+#define J_6  0x9A
+#define J_7  0x9C
+#define J_8  0x9E
+
+#define K_1  0xA0
+#define K_2  0xA2
+#define K_3  0xA4
+#define K_4  0xA6
+#define K_5  0xA8
+#define K_6  0xAA
+#define K_7  0xAC
+#define K_8  0xAE
+
+#define L_1  0xB0
+#define L_2  0xB2
+#define L_3  0xB4
+#define L_4  0xB6
+#define L_5  0xB8
+#define L_6  0xBA
+#define L_7  0xBC
+#define L_8  0xBE
+

keyboards/1up60rgb/readme.md

@@ -1,13 +0,0 @@
-# 1upkeyboards 60% RGB
-
-Firmware for custom keyboard PCB with 60% key layout.
-
-Keyboard Maintainer: [rempired](https://github.com/rempired)  
-Hardware Supported: 1upkeyboards 60% RGB  
-Hardware Availability: [1upkeyboards](https://1upkeyboards.com/rgb-underglow-1up-pcb.html)
-
-Make example for this keyboard (after setting up your build environment):
-
-    make 1up60rgb:default
-
-See [build environment setup](https://docs.qmk.fm/build_environment_setup.html) then the [make instructions](https://docs.qmk.fm/make_instructions.html) for more information.

keyboards/1upkeyboards/1up60hse/1up60hse.c

@@ -0,0 +1,43 @@
+/* Copyright 2018 MechMerlin
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+#include "1up60hse.h"
+
+void matrix_init_kb(void) {
+	// put your keyboard start-up code here
+	// runs once when the firmware starts up
+
+	matrix_init_user();
+}
+
+void matrix_scan_kb(void) {
+	// put your looping keyboard code here
+	// runs every cycle (a lot)
+
+	matrix_scan_user();
+}
+
+bool process_record_kb(uint16_t keycode, keyrecord_t *record) {
+	// put your per-action keyboard code here
+	// runs for every action, just before processing by the firmware
+
+	return process_record_user(keycode, record);
+}
+
+void led_set_kb(uint8_t usb_led) {
+	// put your keyboard LED indicator (ex: Caps Lock LED) toggling code here
+
+	led_set_user(usb_led);
+}

keyboards/1upkeyboards/1up60hse/1up60hse.h

@@ -0,0 +1,39 @@
+/* Copyright 2018 MechMerlin
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+#ifndef KB_H
+#define KB_H
+
+#include "quantum.h"
+
+// This a shortcut to help you visually see your layout.
+// The first section contains all of the arguments representing the physical
+// layout of the board and position of the keys
+// The second converts the arguments into a two-dimensional array which 
+// represents the switch matrix. 
+#define LAYOUT_60_ansi( \
+	K00, K01, K02, K03, K04, K05, K06, K07, K08, K09, K0A, K0B, K0C, K0D, \
+	K10, K11, K12, K13, K14, K15, K16, K17, K18, K19, K1A, K1B, K1C, K1D, \
+	K20, K21, K22, K23, K24, K25, K26, K27, K28, K29, K2A, K2B,      K2D, \
+	K30, K31, K32, K33, K34, K35, K36, K37, K38, K39, K3A,           K3D, \
+	K40, K41, K42,             K45,              K49, K4A, K4B,      K4D  \
+) { \
+	{ K00,  K01,  K02,  K03,   K04,   K05, K06,   K07,   K08,   K09, K0A, K0B,   K0C,   K0D }, \
+	{ K10,  K11,  K12,  K13,   K14,   K15, K16,   K17,   K18,   K19, K1A, K1B,   K1C,   K1D }, \
+	{ K20,  K21,  K22,  K23,   K24,   K25, K26,   K27,   K28,   K29, K2A, K2B,   KC_NO, K2D }, \
+	{ K30,  K31,  K32,  K33,   K34,   K35, K36,   K37,   K38,   K39, K3A, KC_NO, KC_NO, K3D }, \
+	{ K40,  K41,  K42,  KC_NO, KC_NO, K45, KC_NO, KC_NO, KC_NO, K49, K4A, K4B,   KC_NO, K4D }  \
+}
+#endif

keyboards/1upkeyboards/1up60hse/config.h

@@ -0,0 +1,224 @@
+/*
+Copyright 2018 MechMerlin
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+#pragma once
+
+#include "config_common.h"
+
+/* USB Device descriptor parameter */
+#define VENDOR_ID       0xFEED
+#define PRODUCT_ID      0x0000
+#define DEVICE_VER      0x0001
+#define MANUFACTURER    1upkeyboards
+#define PRODUCT         1up60hse
+#define DESCRIPTION     A custom 60% keyboard
+
+/* key matrix size */
+#define MATRIX_ROWS 5
+#define MATRIX_COLS 14
+
+/*
+ * Keyboard Matrix Assignments
+ *
+ * Change this to how you wired your keyboard
+ * COLS: AVR pins used for columns, left to right
+ * ROWS: AVR pins used for rows, top to bottom
+ * DIODE_DIRECTION: COL2ROW = COL = Anode (+), ROW = Cathode (-, marked on diode)
+ *                  ROW2COL = ROW = Anode (+), COL = Cathode (-, marked on diode)
+ *
+*/
+#define MATRIX_ROW_PINS { B3, B2, B1, B0, D4 }
+#define MATRIX_COL_PINS { C7, F7, F6, F5, F4, F1, E6, D1, D0, D2, D3, D5, D6, D7 }
+#define UNUSED_PINS
+
+/* COL2ROW, ROW2COL, or CUSTOM_MATRIX */
+#define DIODE_DIRECTION COL2ROW
+
+#define BACKLIGHT_PIN B7
+#define BACKLIGHT_BREATHING
+#define BACKLIGHT_LEVELS 5
+
+#define RGB_DI_PIN F0
+#ifdef RGB_DI_PIN
+#define RGBLIGHT_ANIMATIONS
+#define RGBLED_NUM 14
+#define RGBLIGHT_HUE_STEP 8
+#define RGBLIGHT_SAT_STEP 8
+#define RGBLIGHT_VAL_STEP 8
+#endif
+
+/* Debounce reduces chatter (unintended double-presses) - set 0 if debouncing is not needed */
+#define DEBOUNCING_DELAY 5
+
+/* define if matrix has ghost (lacks anti-ghosting diodes) */
+//#define MATRIX_HAS_GHOST
+
+/* number of backlight levels */
+
+/* Mechanical locking support. Use KC_LCAP, KC_LNUM or KC_LSCR instead in keymap */
+#define LOCKING_SUPPORT_ENABLE
+/* Locking resynchronize hack */
+#define LOCKING_RESYNC_ENABLE
+
+/* If defined, GRAVE_ESC will always act as ESC when CTRL is held.
+ * This is userful for the Windows task manager shortcut (ctrl+shift+esc).
+ */
+// #define GRAVE_ESC_CTRL_OVERRIDE
+
+/*
+ * Force NKRO
+ *
+ * Force NKRO (nKey Rollover) to be enabled by default, regardless of the saved
+ * state in the bootmagic EEPROM settings. (Note that NKRO must be enabled in the
+ * makefile for this to work.)
+ *
+ * If forced on, NKRO can be disabled via magic key (default = LShift+RShift+N)
+ * until the next keyboard reset.
+ *
+ * NKRO may prevent your keystrokes from being detected in the BIOS, but it is
+ * fully operational during normal computer usage.
+ *
+ * For a less heavy-handed approach, enable NKRO via magic key (LShift+RShift+N)
+ * or via bootmagic (hold SPACE+N while plugging in the keyboard). Once set by
+ * bootmagic, NKRO mode will always be enabled until it is toggled again during a
+ * power-up.
+ *
+ */
+//#define FORCE_NKRO
+
+/*
+ * Magic Key Options
+ *
+ * Magic keys are hotkey commands that allow control over firmware functions of
+ * the keyboard. They are best used in combination with the HID Listen program,
+ * found here: https://www.pjrc.com/teensy/hid_listen.html
+ *
+ * The options below allow the magic key functionality to be changed. This is
+ * useful if your keyboard/keypad is missing keys and you want magic key support.
+ *
+ */
+
+/* key combination for magic key command */
+#define IS_COMMAND() ( \
+    keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)) \
+)
+
+/* control how magic key switches layers */
+//#define MAGIC_KEY_SWITCH_LAYER_WITH_FKEYS  true
+//#define MAGIC_KEY_SWITCH_LAYER_WITH_NKEYS  true
+//#define MAGIC_KEY_SWITCH_LAYER_WITH_CUSTOM false
+
+/* override magic key keymap */
+//#define MAGIC_KEY_SWITCH_LAYER_WITH_FKEYS
+//#define MAGIC_KEY_SWITCH_LAYER_WITH_NKEYS
+//#define MAGIC_KEY_SWITCH_LAYER_WITH_CUSTOM
+//#define MAGIC_KEY_HELP1          H
+//#define MAGIC_KEY_HELP2          SLASH
+//#define MAGIC_KEY_DEBUG          D
+//#define MAGIC_KEY_DEBUG_MATRIX   X
+//#define MAGIC_KEY_DEBUG_KBD      K
+//#define MAGIC_KEY_DEBUG_MOUSE    M
+//#define MAGIC_KEY_VERSION        V
+//#define MAGIC_KEY_STATUS         S
+//#define MAGIC_KEY_CONSOLE        C
+//#define MAGIC_KEY_LAYER0_ALT1    ESC
+//#define MAGIC_KEY_LAYER0_ALT2    GRAVE
+//#define MAGIC_KEY_LAYER0         0
+//#define MAGIC_KEY_LAYER1         1
+//#define MAGIC_KEY_LAYER2         2
+//#define MAGIC_KEY_LAYER3         3
+//#define MAGIC_KEY_LAYER4         4
+//#define MAGIC_KEY_LAYER5         5
+//#define MAGIC_KEY_LAYER6         6
+//#define MAGIC_KEY_LAYER7         7
+//#define MAGIC_KEY_LAYER8         8
+//#define MAGIC_KEY_LAYER9         9
+//#define MAGIC_KEY_BOOTLOADER     PAUSE
+//#define MAGIC_KEY_LOCK           CAPS
+//#define MAGIC_KEY_EEPROM         E
+//#define MAGIC_KEY_NKRO           N
+//#define MAGIC_KEY_SLEEP_LED      Z
+
+/*
+ * Feature disable options
+ *  These options are also useful to firmware size reduction.
+ */
+
+/* disable debug print */
+//#define NO_DEBUG
+
+/* disable print */
+//#define NO_PRINT
+
+/* disable action features */
+//#define NO_ACTION_LAYER
+//#define NO_ACTION_TAPPING
+//#define NO_ACTION_ONESHOT
+//#define NO_ACTION_MACRO
+//#define NO_ACTION_FUNCTION
+
+/*
+ * MIDI options
+ */
+
+/* Prevent use of disabled MIDI features in the keymap */
+//#define MIDI_ENABLE_STRICT 1
+
+/* enable basic MIDI features:
+   - MIDI notes can be sent when in Music mode is on
+*/
+//#define MIDI_BASIC
+
+/* enable advanced MIDI features:
+   - MIDI notes can be added to the keymap
+   - Octave shift and transpose
+   - Virtual sustain, portamento, and modulation wheel
+   - etc.
+*/
+//#define MIDI_ADVANCED
+
+/* override number of MIDI tone keycodes (each octave adds 12 keycodes and allocates 12 bytes) */
+//#define MIDI_TONE_KEYCODE_OCTAVES 1
+
+/*
+ * HD44780 LCD Display Configuration
+ */
+/*
+#define LCD_LINES           2     //< number of visible lines of the display
+#define LCD_DISP_LENGTH    16     //< visibles characters per line of the display
+
+#define LCD_IO_MODE      1            //< 0: memory mapped mode, 1: IO port mode
+
+#if LCD_IO_MODE
+#define LCD_PORT         PORTB        //< port for the LCD lines
+#define LCD_DATA0_PORT   LCD_PORT     //< port for 4bit data bit 0
+#define LCD_DATA1_PORT   LCD_PORT     //< port for 4bit data bit 1
+#define LCD_DATA2_PORT   LCD_PORT     //< port for 4bit data bit 2
+#define LCD_DATA3_PORT   LCD_PORT     //< port for 4bit data bit 3
+#define LCD_DATA0_PIN    4            //< pin for 4bit data bit 0
+#define LCD_DATA1_PIN    5            //< pin for 4bit data bit 1
+#define LCD_DATA2_PIN    6            //< pin for 4bit data bit 2
+#define LCD_DATA3_PIN    7            //< pin for 4bit data bit 3
+#define LCD_RS_PORT      LCD_PORT     //< port for RS line
+#define LCD_RS_PIN       3            //< pin  for RS line
+#define LCD_RW_PORT      LCD_PORT     //< port for RW line
+#define LCD_RW_PIN       2            //< pin  for RW line
+#define LCD_E_PORT       LCD_PORT     //< port for Enable line
+#define LCD_E_PIN        1            //< pin  for Enable line
+#endif
+*/
+

keyboards/1upkeyboards/1up60hse/info.json

@@ -0,0 +1,12 @@
+{
+    "keyboard_name": "1up60hse",
+    "url": "",
+    "maintainer": "qmk",
+    "width": 15,
+    "height": 5,
+    "layouts": {
+        "LAYOUT_60_ansi": {
+            "layout": [{"label":"~", "x":0, "y":0}, {"label":"!", "x":1, "y":0}, {"label":"@", "x":2, "y":0}, {"label":"#", "x":3, "y":0}, {"label":"$", "x":4, "y":0}, {"label":"%", "x":5, "y":0}, {"label":"^", "x":6, "y":0}, {"label":"&", "x":7, "y":0}, {"label":"*", "x":8, "y":0}, {"label":"(", "x":9, "y":0}, {"label":")", "x":10, "y":0}, {"label":"_", "x":11, "y":0}, {"label":"+", "x":12, "y":0}, {"label":"Backspace", "x":13, "y":0, "w":2}, {"label":"Tab", "x":0, "y":1, "w":1.5}, {"label":"Q", "x":1.5, "y":1}, {"label":"W", "x":2.5, "y":1}, {"label":"E", "x":3.5, "y":1}, {"label":"R", "x":4.5, "y":1}, {"label":"T", "x":5.5, "y":1}, {"label":"Y", "x":6.5, "y":1}, {"label":"U", "x":7.5, "y":1}, {"label":"I", "x":8.5, "y":1}, {"label":"O", "x":9.5, "y":1}, {"label":"P", "x":10.5, "y":1}, {"label":"{", "x":11.5, "y":1}, {"label":"}", "x":12.5, "y":1}, {"label":"|", "x":13.5, "y":1, "w":1.5}, {"label":"Caps Lock", "x":0, "y":2, "w":1.75}, {"label":"A", "x":1.75, "y":2}, {"label":"S", "x":2.75, "y":2}, {"label":"D", "x":3.75, "y":2}, {"label":"F", "x":4.75, "y":2}, {"label":"G", "x":5.75, "y":2}, {"label":"H", "x":6.75, "y":2}, {"label":"J", "x":7.75, "y":2}, {"label":"K", "x":8.75, "y":2}, {"label":"L", "x":9.75, "y":2}, {"label":":", "x":10.75, "y":2}, {"label":"\"", "x":11.75, "y":2}, {"label":"Enter", "x":12.75, "y":2, "w":2.25}, {"label":"Shift", "x":0, "y":3, "w":2.25}, {"label":"Z", "x":2.25, "y":3}, {"label":"X", "x":3.25, "y":3}, {"label":"C", "x":4.25, "y":3}, {"label":"V", "x":5.25, "y":3}, {"label":"B", "x":6.25, "y":3}, {"label":"N", "x":7.25, "y":3}, {"label":"M", "x":8.25, "y":3}, {"label":"<", "x":9.25, "y":3}, {"label":">", "x":10.25, "y":3}, {"label":"?", "x":11.25, "y":3}, {"label":"Shift", "x":12.25, "y":3, "w":2.75}, {"label":"Ctrl", "x":0, "y":4, "w":1.25}, {"label":"Win", "x":1.25, "y":4, "w":1.25}, {"label":"Alt", "x":2.5, "y":4, "w":1.25}, {"x":3.75, "y":4, "w":6.25}, {"label":"Alt", "x":10, "y":4, "w":1.25}, {"label":"Win", "x":11.25, "y":4, "w":1.25}, {"label":"Menu", "x":12.5, "y":4, "w":1.25}, {"label":"Ctrl", "x":13.75, "y":4, "w":1.25}]
+        }
+    }
+}

keyboards/1upkeyboards/1up60hse/keymaps/default/config.h

@@ -0,0 +1,19 @@
+/* Copyright 2018 MechMerlin
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+// place overrides here

keyboards/1upkeyboards/1up60hse/keymaps/default/keymap.c

@@ -0,0 +1,44 @@
+/* Copyright 2018 MechMerlin
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+#include QMK_KEYBOARD_H
+
+const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+  [0] = LAYOUT_60_ansi(
+		KC_ESC, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_BSPC, 
+		KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS, 
+		MO(1), KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_ENT, 
+		KC_LSFT, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_LSFT, 
+		KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_RALT, MO(2), KC_RGUI, KC_RCTL),
+
+	[1] = LAYOUT_60_ansi(
+		KC_GRV, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, KC_TRNS, 
+		KC_TRNS, KC_TRNS, KC_UP, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, 
+		KC_TRNS, KC_LEFT, KC_DOWN, KC_RGHT, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, 
+		KC_LSFT, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, 
+		KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS),
+
+  [2] = LAYOUT_60_ansi(
+		RESET, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, 
+		KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, 
+		KC_CAPS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, BL_STEP, BL_DEC, BL_INC, BL_TOGG, KC_TRNS, KC_TRNS, KC_TRNS, 
+		KC_TRNS, KC_TRNS, KC_TRNS, RGB_VAD, RGB_VAI, RGB_SAI, RGB_HUD, RGB_HUI, RGB_MOD, RGB_TOG, KC_TRNS, KC_TRNS, 
+		KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS),
+};
+
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  return true;
+}
+

keyboards/1upkeyboards/1up60hse/keymaps/default/readme.md

@@ -0,0 +1,6 @@
+# 1up60hse default keymap
+
+This is the default keymap provided by [1upkeyboards](https://www.1upkeyboards.com).  
+
+## Notes
+- Software reset key is located on `Esc` on the third layer.

keyboards/1upkeyboards/1up60hse/readme.md

@@ -0,0 +1,15 @@
+# 1up60hse (hot swap edition)
+
+![1up60hse](https://i2.wp.com/www.1upkeyboards.com/wp-content/uploads/2018/08/PCB-1up-60-hotswap-group-RGB.jpg?fit=1280%2C1280&ssl=1)
+
+A 60% PCB with USB C, RGB underglow, backlighting, hotswappable switches, and a standard ANSI layout.
+
+Keyboard Maintainer: [MechMerlin](https://github.com/mechmerlin)  
+Hardware Supported: 1up60hse 60% PCB.  
+Hardware Availability: [1upkeyboards.com](https://www.1upkeyboards.com/shop/controllers/1up-rgb-pcb-hse/)
+
+Make example for this keyboard (after setting up your build environment):
+
+    make 1upkeyboards/1up60hse:default
+
+See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs).

keyboards/1upkeyboards/1up60hse/rules.mk

@@ -0,0 +1,72 @@
+# MCU name
+#MCU = at90usb1286
+MCU = atmega32u4
+
+# Processor frequency.
+#     This will define a symbol, F_CPU, in all source code files equal to the
+#     processor frequency in Hz. You can then use this symbol in your source code to
+#     calculate timings. Do NOT tack on a 'UL' at the end, this will be done
+#     automatically to create a 32-bit value in your source code.
+#
+#     This will be an integer division of F_USB below, as it is sourced by
+#     F_USB after it has run through any CPU prescalers. Note that this value
+#     does not *change* the processor frequency - it should merely be updated to
+#     reflect the processor speed set externally so that the code can use accurate
+#     software delays.
+F_CPU = 16000000
+
+
+#
+# LUFA specific
+#
+# Target architecture (see library "Board Types" documentation).
+ARCH = AVR8
+
+# Input clock frequency.
+#     This will define a symbol, F_USB, in all source code files equal to the
+#     input clock frequency (before any prescaling is performed) in Hz. This value may
+#     differ from F_CPU if prescaling is used on the latter, and is required as the
+#     raw input clock is fed directly to the PLL sections of the AVR for high speed
+#     clock generation for the USB and other AVR subsections. Do NOT tack on a 'UL'
+#     at the end, this will be done automatically to create a 32-bit value in your
+#     source code.
+#
+#     If no clock division is performed on the input clock inside the AVR (via the
+#     CPU clock adjust registers or the clock division fuses), this will be equal to F_CPU.
+F_USB = $(F_CPU)
+
+# Interrupt driven control endpoint task(+60)
+OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT
+
+
+# Boot Section Size in *bytes*
+#   Teensy halfKay   512
+#   Teensy++ halfKay 1024
+#   Atmel DFU loader 4096
+#   LUFA bootloader  4096
+#   USBaspLoader     2048
+OPT_DEFS += -DBOOTLOADER_SIZE=4096
+
+
+# Build Options
+#   change yes to no to disable
+#
+BOOTMAGIC_ENABLE = no      # Virtual DIP switch configuration(+1000)
+MOUSEKEY_ENABLE = no       # Mouse keys(+4700)
+EXTRAKEY_ENABLE = yes       # Audio control and System control(+450)
+CONSOLE_ENABLE = yes        # Console for debug(+400)
+COMMAND_ENABLE = yes        # Commands for debug and configuration
+# Do not enable SLEEP_LED_ENABLE. it uses the same timer as BACKLIGHT_ENABLE
+SLEEP_LED_ENABLE = no       # Breathing sleep LED during USB suspend
+# if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
+NKRO_ENABLE = no            # USB Nkey Rollover
+BACKLIGHT_ENABLE = yes       # Enable keyboard backlight functionality on B7 by default
+RGBLIGHT_ENABLE = yes        # Enable keyboard RGB underglow
+MIDI_ENABLE = no            # MIDI support (+2400 to 4200, depending on config)
+UNICODE_ENABLE = no         # Unicode
+BLUETOOTH_ENABLE = no       # Enable Bluetooth with the Adafruit EZ-Key HID
+AUDIO_ENABLE = no           # Audio output on port C6
+FAUXCLICKY_ENABLE = no      # Use buzzer to emulate clicky switches
+HD44780_ENABLE = no 		# Enable support for HD44780 based LCDs (+400)
+
+LAYOUTS = 60_ansi

keyboards/1upkeyboards/1up60rgb/config.h

@@ -43,9 +43,6 @@
     keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)) \
 )
 
-/* prevent stuck modifiers */
-#define PREVENT_STUCK_MODIFIERS
-
 #define RGB_DI_PIN E2
 #ifdef RGB_DI_PIN
 #define RGBLIGHT_ANIMATIONS