Merge remote-tracking branch 'origin/develop'

* Initial changelog pass

* update generate-develop-pr-list content

* Fix bad word-ness

* Fix generate-develop-pr-list ignores

* Update docs/ChangeLog/20220226.md

Co-authored-by: Sergey Vlasov <sigprof@gmail.com>

Co-authored-by: Sergey Vlasov <sigprof@gmail.com>

.clang-format

@@ -5,6 +5,9 @@ AlignConsecutiveAssignments: 'true'
 AlignConsecutiveDeclarations: 'true'
 AlignOperands: 'true'
 AllowAllParametersOfDeclarationOnNextLine: 'false'
+AllowShortCaseLabelsOnASingleLine: 'false'
+AllowShortFunctionsOnASingleLine: Empty
+AllowShortLoopsOnASingleLine: 'false'
 AlwaysBreakAfterDefinitionReturnType: None
 AlwaysBreakAfterReturnType: None
 AlwaysBreakBeforeMultilineStrings: 'false'
@@ -20,6 +23,7 @@ SortIncludes: 'false'
 SpaceBeforeAssignmentOperators: 'true'
 SpaceBeforeParens: ControlStatements
 SpaceInEmptyParentheses: 'false'
+SpacesBeforeTrailingComments: 1
 TabWidth: '4'
 UseTab: Never
 

.github/workflows/format.yaml

@@ -19,14 +19,14 @@ jobs:
     container: qmkfm/qmk_cli
 
     steps:
-    - name: Install dependencies
-      run: |
-        apt-get update && apt-get install -y dos2unix
-
     - uses: actions/checkout@v2
       with:
         fetch-depth: 0
 
+    - name: Install dependencies
+      run: |
+        pip3 install -r requirements-dev.txt
+
     - uses: trilom/file-changes-action@v1.2.4
       id: file_changes
       with:

.github/workflows/format_push.yaml

@@ -13,14 +13,14 @@ jobs:
     container: qmkfm/qmk_cli
 
     steps:
-    - name: Install dependencies
-      run: |
-        apt-get update && apt-get install -y dos2unix
-
     - uses: actions/checkout@v2
       with:
         fetch-depth: 0
 
+    - name: Install dependencies
+      run: |
+        pip3 install -r requirements-dev.txt
+
     - name: Run qmk formatters
       shell: 'bash {0}'
       run: |

.gitignore

@@ -3,6 +3,7 @@
 *.swp
 *~
 .DS_Store
+._*
 
 # Build artifacts
 .clang_complete
@@ -18,7 +19,6 @@
 
 # QMK-specific
 api_data/v1
-doxygen/
 quantum/version.h
 *.bin
 *.eep

Doxyfile

@@ -21,7 +21,7 @@ DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = "QMK Firmware"
 PROJECT_NUMBER         = https://github.com/qmk/qmk_firmware
 PROJECT_BRIEF          = "Keyboard controller firmware for Atmel AVR and ARM USB families"
-OUTPUT_DIRECTORY       = doxygen
+OUTPUT_DIRECTORY       = .build/doxygen
 ALLOW_UNICODE_NAMES    = NO
 OUTPUT_LANGUAGE        = English
 BRIEF_MEMBER_DESC      = YES
@@ -145,7 +145,7 @@ FILE_PATTERNS          = *.c \
 RECURSIVE              = YES
 EXCLUDE                = 
 EXCLUDE_SYMLINKS       = NO
-EXCLUDE_PATTERNS       = 
+EXCLUDE_PATTERNS       = */protocol/arm_atsam/*
 EXCLUDE_SYMBOLS        = 
 EXAMPLE_PATH           = 
 EXAMPLE_PATTERNS       = *
@@ -209,7 +209,7 @@ EXPAND_ONLY_PREDEF     = NO
 SEARCH_INCLUDES        = YES
 INCLUDE_PATH           = 
 INCLUDE_FILE_PATTERNS  = 
-PREDEFINED             = 
+PREDEFINED             = __DOXYGEN__ PROGMEM
 EXPAND_AS_DEFINED      = 
 SKIP_FUNCTION_MACROS   = YES
 

Makefile

@@ -19,6 +19,10 @@ endif
 # Otherwise the [OK], [ERROR] and [WARN] messages won't be displayed correctly
 override SILENT := false
 
+ifdef SKIP_VERSION
+    SKIP_GIT := yes
+endif
+
 ifndef SUB_IS_SILENT
 ifndef SKIP_GIT
     QMK_VERSION := $(shell git describe --abbrev=0 --tags 2>/dev/null)
@@ -50,48 +54,12 @@ ABS_ROOT_MAKEFILE := $(abspath $(ROOT_MAKEFILE))
 ABS_STARTING_DIR := $(dir $(ABS_STARTING_MAKEFILE))
 ABS_ROOT_DIR := $(dir $(ABS_ROOT_MAKEFILE))
 STARTING_DIR := $(subst $(ABS_ROOT_DIR),,$(ABS_STARTING_DIR))
-BUILD_DIR := $(ROOT_DIR)/.build
-TEST_DIR := $(BUILD_DIR)/test
+
+include paths.mk
+
+TEST_OUTPUT_DIR := $(BUILD_DIR)/test
 ERROR_FILE := $(BUILD_DIR)/error_occurred
 
-# Helper function to process the newt element of a space separated path
-# It works a bit like the traditional functional head tail
-# so the CURRENT_PATH_ELEMENT will become the new head
-# and the PATH_ELEMENTS are the rest that are still unprocessed
-define NEXT_PATH_ELEMENT
-    $$(eval CURRENT_PATH_ELEMENT := $$(firstword  $$(PATH_ELEMENTS)))
-    $$(eval PATH_ELEMENTS := $$(wordlist  2,9999,$$(PATH_ELEMENTS)))
-endef
-
-# We change the / to spaces so that we more easily can work with the elements
-# separately
-PATH_ELEMENTS := $(subst /, ,$(STARTING_DIR))
-# Initialize the path elements list for further processing
-$(eval $(call NEXT_PATH_ELEMENT))
-
-
-# Phony targets to enable a few simple make commands outside the main processing below.
-.PHONY: list-keyboards
-list-keyboards:
-	util/list_keyboards.sh | sort -u | tr '\n' ' '
-
-.PHONY: generate-keyboards-file
-generate-keyboards-file:
-	util/list_keyboards.sh | sort -u
-
-.PHONY: clean
-clean:
-	echo -n 'Deleting .build/ ... '
-	rm -rf $(BUILD_DIR)
-	echo 'done.'
-
-.PHONY: distclean
-distclean: clean
-	echo -n 'Deleting *.bin, *.hex, and *.uf2 ... '
-	rm -f *.bin *.hex *.uf2
-	echo 'done.'
-
-
 .DEFAULT_GOAL := all:all
 
 
@@ -119,53 +87,20 @@ endef
 # a function that returns the value
 COMPARE_AND_REMOVE_FROM_RULE = $(eval $(call COMPARE_AND_REMOVE_FROM_RULE_HELPER,$1))$(RULE_FOUND)
 
-
-# Recursively try to find a match for the start of the rule to be checked
-# $1 The list to be checked
-# If a match is found, then RULE_FOUND is set to true
-# and MATCHED_ITEM to the item that was matched
-define TRY_TO_MATCH_RULE_FROM_LIST_HELPER3
-    ifneq ($1,)
-        ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,$$(firstword $1)),true)
-            MATCHED_ITEM := $$(firstword $1)
-        else
-            $$(eval $$(call TRY_TO_MATCH_RULE_FROM_LIST_HELPER3,$$(wordlist 2,9999,$1)))
-        endif
-    endif
-endef
-
-# A recursive helper function for finding the longest match
-# $1 The list to be checked
-# It works by always removing the currently matched item from the list
-define TRY_TO_MATCH_RULE_FROM_LIST_HELPER2
-    # Stop the recursion when the list is empty
-    ifneq ($1,)
-        RULE_BEFORE := $$(RULE)
-        $$(eval $$(call TRY_TO_MATCH_RULE_FROM_LIST_HELPER3,$1))
-        # If a match is found in the current list, otherwise just return what we had before
-        ifeq ($$(RULE_FOUND),true)
-            # Save the best match so far and call itself recursively
-            BEST_MATCH := $$(MATCHED_ITEM)
-            BEST_MATCH_RULE := $$(RULE)
-            RULE_FOUND := false
-            RULE := $$(RULE_BEFORE)
-            $$(eval $$(call TRY_TO_MATCH_RULE_FROM_LIST_HELPER2,$$(filter-out $$(MATCHED_ITEM),$1)))
-        endif
-     endif
-endef
-
-
-# Recursively try to find the longest match for the start of the rule to be checked
+# Try to find a match for the start of the rule to be checked
 # $1 The list to be checked
 # If a match is found, then RULE_FOUND is set to true
 # and MATCHED_ITEM to the item that was matched
 define TRY_TO_MATCH_RULE_FROM_LIST_HELPER
-    BEST_MATCH :=
-    $$(eval $$(call TRY_TO_MATCH_RULE_FROM_LIST_HELPER2,$1))
-    ifneq ($$(BEST_MATCH),)
+    # Split on ":", padding with empty strings to avoid indexing issues
+    TOKEN1:=$$(shell python3 -c "import sys; print((sys.argv[1].split(':',1)+[''])[0])" $$(RULE))
+    TOKENr:=$$(shell python3 -c "import sys; print((sys.argv[1].split(':',1)+[''])[1])" $$(RULE))
+
+    FOUNDx:=$$(shell echo $1 | tr " " "\n" | grep -Fx $$(TOKEN1))
+    ifneq ($$(FOUNDx),)
+        RULE := $$(TOKENr)
         RULE_FOUND := true
-        RULE := $$(BEST_MATCH_RULE)
-        MATCHED_ITEM := $$(BEST_MATCH)
+        MATCHED_ITEM := $$(TOKEN1)
     else
         RULE_FOUND := false
         MATCHED_ITEM :=
@@ -340,7 +275,7 @@ define PARSE_KEYMAP
     # Specify the variables that we are passing forward to submake
     MAKE_VARS := KEYBOARD=$$(CURRENT_KB) KEYMAP=$$(CURRENT_KM) REQUIRE_PLATFORM_KEY=$$(REQUIRE_PLATFORM_KEY) QMK_BIN=$$(QMK_BIN)
     # And the first part of the make command
-    MAKE_CMD := $$(MAKE) -r -R -C $(ROOT_DIR) -f build_keyboard.mk $$(MAKE_TARGET)
+    MAKE_CMD := $$(MAKE) -r -R -C $(ROOT_DIR) -f $(BUILDDEFS_PATH)/build_keyboard.mk $$(MAKE_TARGET)
     # The message to display
     MAKE_MSG := $$(MSG_MAKE_KB)
     # We run the command differently, depending on if we want more output or not
@@ -382,12 +317,12 @@ define BUILD_TEST
     TEST_NAME := $$(notdir $$(TEST_PATH))
     MAKE_TARGET := $2
     COMMAND := $1
-    MAKE_CMD := $$(MAKE) -r -R -C $(ROOT_DIR) -f build_test.mk $$(MAKE_TARGET)
+    MAKE_CMD := $$(MAKE) -r -R -C $(ROOT_DIR) -f $(BUILDDEFS_PATH)/build_test.mk $$(MAKE_TARGET)
     MAKE_VARS := TEST=$$(TEST_NAME) TEST_PATH=$$(TEST_PATH) FULL_TESTS="$$(FULL_TESTS)"
     MAKE_MSG := $$(MSG_MAKE_TEST)
     $$(eval $$(call BUILD))
     ifneq ($$(MAKE_TARGET),clean)
-        TEST_EXECUTABLE := $$(TEST_DIR)/$$(TEST_NAME).elf
+        TEST_EXECUTABLE := $$(TEST_OUTPUT_DIR)/$$(TEST_NAME).elf
         TESTS += $$(TEST_NAME)
         TEST_MSG := $$(MSG_TEST)
         $$(TEST_NAME)_COMMAND := \
@@ -404,6 +339,7 @@ define PARSE_TEST
     TESTS :=
     TEST_NAME := $$(firstword $$(subst :, ,$$(RULE)))
     TEST_TARGET := $$(subst $$(TEST_NAME),,$$(subst $$(TEST_NAME):,,$$(RULE)))
+    include $(BUILDDEFS_PATH)/testlist.mk
     ifeq ($$(TEST_NAME),all)
         MATCHED_TESTS := $$(TEST_LIST)
     else
@@ -426,7 +362,6 @@ define SET_SILENT_MODE
     endif
 endef
 
-include paths.mk
 include $(BUILDDEFS_PATH)/message.mk
 
 ifeq ($(strip $(BREAK_ON_ERRORS)), yes)
@@ -496,14 +431,22 @@ git-submodule:
 	git submodule sync --recursive
 	git submodule update --init --recursive --progress
 
-# Generate the version.h file
-ifdef SKIP_GIT
-VERSION_H_FLAGS := --skip-git
-endif
-ifdef SKIP_VERSION
-VERSION_H_FLAGS := --skip-all
-SKIP_GIT := yes
-endif
-$(shell $(QMK_BIN) generate-version-h $(VERSION_H_FLAGS) -q -o quantum/version.h)
+.PHONY: list-keyboards
+list-keyboards:
+	util/list_keyboards.sh | sort -u | tr '\n' ' '
 
-include $(ROOT_DIR)/testlist.mk
+.PHONY: generate-keyboards-file
+generate-keyboards-file:
+	util/list_keyboards.sh | sort -u
+
+.PHONY: clean
+clean:
+	echo -n 'Deleting .build/ ... '
+	rm -rf $(BUILD_DIR)
+	echo 'done.'
+
+.PHONY: distclean
+distclean: clean
+	echo -n 'Deleting *.bin, *.hex, and *.uf2 ... '
+	rm -f *.bin *.hex *.uf2
+	echo 'done.'

builddefs/bootloader.mk

@@ -30,6 +30,7 @@
 #     bootloadhid  HIDBootFlash compatible (ATmega32A)
 #     usbasploader USBaspLoader (ATmega328P)
 # ARM:
+#     halfkay      PJRC Teensy
 #     kiibohd      Input:Club Kiibohd bootloader (only used on their boards)
 #     stm32duino   STM32Duino (STM32F103x8)
 #     stm32-dfu    STM32 USB DFU in ROM
@@ -37,12 +38,23 @@
 # RISC-V:
 #     gd32v-dfu    GD32V USB DFU in ROM
 #
+# If you need to provide your own implementation, you can set inside `rules.mk`
+# `BOOTLOADER = custom` -- you'll need to provide your own implementations. See
+# the respective file under `platforms/<PLATFORM>/bootloaders/custom.c` to see
+# which functions may be overridden.
+#
 # BOOTLOADER_SIZE can still be defined manually, but it's recommended
 # you add any possible configuration to this list
 
+ifeq ($(strip $(BOOTLOADER)), custom)
+    OPT_DEFS += -DBOOTLOADER_CUSTOM
+    BOOTLOADER_TYPE = custom
+endif
 ifeq ($(strip $(BOOTLOADER)), atmel-dfu)
     OPT_DEFS += -DBOOTLOADER_ATMEL_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
+    BOOTLOADER_TYPE = dfu
+
     ifneq (,$(filter $(MCU), at90usb162 atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647))
         BOOTLOADER_SIZE = 4096
     endif
@@ -53,6 +65,8 @@ endif
 ifeq ($(strip $(BOOTLOADER)), lufa-dfu)
     OPT_DEFS += -DBOOTLOADER_LUFA_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
+    BOOTLOADER_TYPE = dfu
+
     ifneq (,$(filter $(MCU), at90usb162 atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647))
         BOOTLOADER_SIZE ?= 4096
     endif
@@ -63,6 +77,8 @@ endif
 ifeq ($(strip $(BOOTLOADER)), qmk-dfu)
     OPT_DEFS += -DBOOTLOADER_QMK_DFU
     OPT_DEFS += -DBOOTLOADER_DFU
+    BOOTLOADER_TYPE = dfu
+
     ifneq (,$(filter $(MCU), at90usb162 atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647))
         BOOTLOADER_SIZE ?= 4096
     endif
@@ -73,10 +89,14 @@ endif
 ifeq ($(strip $(BOOTLOADER)), qmk-hid)
     OPT_DEFS += -DBOOTLOADER_QMK_HID
     OPT_DEFS += -DBOOTLOADER_HID
+    BOOTLOADER_TYPE = dfu
+
     BOOTLOADER_SIZE ?= 4096
 endif
 ifeq ($(strip $(BOOTLOADER)), halfkay)
     OPT_DEFS += -DBOOTLOADER_HALFKAY
+    BOOTLOADER_TYPE = halfkay
+
     ifeq ($(strip $(MCU)), atmega32u4)
         BOOTLOADER_SIZE = 512
     endif
@@ -86,18 +106,26 @@ ifeq ($(strip $(BOOTLOADER)), halfkay)
 endif
 ifeq ($(strip $(BOOTLOADER)), caterina)
     OPT_DEFS += -DBOOTLOADER_CATERINA
+    BOOTLOADER_TYPE = caterina
+
     BOOTLOADER_SIZE = 4096
 endif
 ifneq (,$(filter $(BOOTLOADER), bootloadhid bootloadHID))
     OPT_DEFS += -DBOOTLOADER_BOOTLOADHID
+    BOOTLOADER_TYPE = bootloadhid
+
     BOOTLOADER_SIZE = 4096
 endif
 ifneq (,$(filter $(BOOTLOADER), usbasploader USBasp))
     OPT_DEFS += -DBOOTLOADER_USBASP
+    BOOTLOADER_TYPE = usbasploader
+
     BOOTLOADER_SIZE = 4096
 endif
 ifeq ($(strip $(BOOTLOADER)), lufa-ms)
     OPT_DEFS += -DBOOTLOADER_MS
+    BOOTLOADER_TYPE = dfu
+
     BOOTLOADER_SIZE ?= 8192
     FIRMWARE_FORMAT = bin
 cpfirmware: lufa_warning
@@ -115,6 +143,7 @@ endif
 
 ifeq ($(strip $(BOOTLOADER)), stm32-dfu)
     OPT_DEFS += -DBOOTLOADER_STM32_DFU
+    BOOTLOADER_TYPE = stm32_dfu
 
     # Options to pass to dfu-util when flashing
     DFU_ARGS ?= -d 0483:DF11 -a 0 -s 0x08000000:leave
@@ -122,6 +151,7 @@ ifeq ($(strip $(BOOTLOADER)), stm32-dfu)
 endif
 ifeq ($(strip $(BOOTLOADER)), apm32-dfu)
     OPT_DEFS += -DBOOTLOADER_APM32_DFU
+    BOOTLOADER_TYPE = stm32_dfu
 
     # Options to pass to dfu-util when flashing
     DFU_ARGS ?= -d 314B:0106 -a 0 -s 0x08000000:leave
@@ -129,6 +159,7 @@ ifeq ($(strip $(BOOTLOADER)), apm32-dfu)
 endif
 ifeq ($(strip $(BOOTLOADER)), gd32v-dfu)
     OPT_DEFS += -DBOOTLOADER_GD32V_DFU
+    BOOTLOADER_TYPE = gd32v_dfu
 
     # Options to pass to dfu-util when flashing
     DFU_ARGS ?= -d 28E9:0189 -a 0 -s 0x08000000:leave
@@ -136,6 +167,8 @@ ifeq ($(strip $(BOOTLOADER)), gd32v-dfu)
 endif
 ifeq ($(strip $(BOOTLOADER)), kiibohd)
     OPT_DEFS += -DBOOTLOADER_KIIBOHD
+    BOOTLOADER_TYPE = kiibohd
+
     ifeq ($(strip $(MCU_ORIG)), MK20DX128)
         MCU_LDSCRIPT = MK20DX128BLDR4
     endif
@@ -151,8 +184,7 @@ ifeq ($(strip $(BOOTLOADER)), stm32duino)
     OPT_DEFS += -DBOOTLOADER_STM32DUINO
     MCU_LDSCRIPT = STM32F103x8_stm32duino_bootloader
     BOARD = STM32_F103_STM32DUINO
-    # STM32F103 does NOT have an USB bootloader in ROM (only serial), so setting anything here does not make much sense
-    STM32_BOOTLOADER_ADDRESS = 0x80000000
+    BOOTLOADER_TYPE = stm32duino
 
     # Options to pass to dfu-util when flashing
     DFU_ARGS = -d 1EAF:0003 -a 2 -R
@@ -160,4 +192,17 @@ ifeq ($(strip $(BOOTLOADER)), stm32duino)
 endif
 ifeq ($(strip $(BOOTLOADER)), tinyuf2)
     OPT_DEFS += -DBOOTLOADER_TINYUF2
+    BOOTLOADER_TYPE = tinyuf2
+endif
+ifeq ($(strip $(BOOTLOADER)), halfkay)
+    OPT_DEFS += -DBOOTLOADER_HALFKAY
+    BOOTLOADER_TYPE = halfkay
+endif
+ifeq ($(strip $(BOOTLOADER)), md-boot)
+    OPT_DEFS += -DBOOTLOADER_MD_BOOT
+    BOOTLOADER_TYPE = md_boot
+endif
+
+ifeq ($(strip $(BOOTLOADER_TYPE)),)
+    $(call CATASTROPHIC_ERROR,Invalid BOOTLOADER,No bootloader specified. Please set an appropriate 'BOOTLOADER' in your keyboard's 'rules.mk' file.)
 endif

builddefs/build_full_test.mk

@@ -14,7 +14,7 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 $(TEST)_INC := \
-	tests\test_common\common_config.h
+	tests/test_common/common_config.h
 
 $(TEST)_SRC := \
 	$(TMK_COMMON_SRC) \
@@ -33,4 +33,4 @@ $(TEST)_DEFS := $(TMK_COMMON_DEFS) $(OPT_DEFS)
 
 $(TEST)_CONFIG := $(TEST_PATH)/config.h
 
-VPATH += $(TOP_DIR)/tests/test_common
+VPATH += $(TOP_DIR)/tests/test_common

builddefs/build_keyboard.mk

@@ -37,6 +37,17 @@ ifdef SKIP_VERSION
     OPT_DEFS += -DSKIP_VERSION
 endif
 
+# Generate the version.h file
+ifdef SKIP_VERSION
+VERSION_H_FLAGS := --skip-all
+endif
+ifdef SKIP_GIT
+VERSION_H_FLAGS := --skip-git
+endif
+
+# Generate the board's version.h file.
+$(shell $(QMK_BIN) generate-version-h $(VERSION_H_FLAGS) -q -o $(KEYMAP_OUTPUT)/src/version.h)
+
 # Determine which subfolders exist.
 KEYBOARD_FOLDER_PATH_1 := $(KEYBOARD)
 KEYBOARD_FOLDER_PATH_2 := $(patsubst %/,%,$(dir $(KEYBOARD_FOLDER_PATH_1)))
@@ -100,7 +111,7 @@ INFO_RULES_MK = $(shell $(QMK_BIN) generate-rules-mk --quiet --escape --keyboard
 include $(INFO_RULES_MK)
 
 # Check for keymap.json first, so we can regenerate keymap.c
-include build_json.mk
+include $(BUILDDEFS_PATH)/build_json.mk
 
 # Pull in keymap level rules.mk
 ifeq ("$(wildcard $(KEYMAP_PATH))", "")
@@ -127,9 +138,9 @@ ifeq ("$(wildcard $(KEYMAP_PATH))", "")
         KEYMAP_PATH := $(MAIN_KEYMAP_PATH_1)
     else ifneq ($(LAYOUTS),)
         # If we haven't found a keymap yet fall back to community layouts
-        include build_layout.mk
+        include $(BUILDDEFS_PATH)/build_layout.mk
     else
-        $(error Could not find keymap)
+        $(call CATASTROPHIC_ERROR,Invalid keymap,Could not find keymap)
         # this state should never be reached
     endif
 endif
@@ -158,7 +169,7 @@ generated-files: $(KEYMAP_OUTPUT)/src/config.h $(KEYMAP_OUTPUT)/src/keymap.c
 endif
 
 ifeq ($(strip $(CTPC)), yes)
-  CONVERT_TO_PROTON_C=yes
+    CONVERT_TO_PROTON_C=yes
 endif
 
 ifeq ($(strip $(CONVERT_TO_PROTON_C)), yes)
@@ -384,8 +395,10 @@ VPATH += $(KEYMAP_PATH)
 VPATH += $(USER_PATH)
 VPATH += $(KEYBOARD_PATHS)
 VPATH += $(COMMON_VPATH)
+VPATH += $(KEYBOARD_OUTPUT)/src
+VPATH += $(KEYMAP_OUTPUT)/src
 
-include common_features.mk
+include $(BUILDDEFS_PATH)/common_features.mk
 include $(BUILDDEFS_PATH)/generic_features.mk
 include $(TMK_PATH)/protocol.mk
 include $(PLATFORM_PATH)/common.mk
@@ -425,8 +438,7 @@ OUTPUTS := $(KEYMAP_OUTPUT) $(KEYBOARD_OUTPUT)
 $(KEYMAP_OUTPUT)_SRC := $(SRC)
 $(KEYMAP_OUTPUT)_DEFS := $(OPT_DEFS) \
 -DQMK_KEYBOARD=\"$(KEYBOARD)\" -DQMK_KEYBOARD_H=\"$(QMK_KEYBOARD_H)\" \
--DQMK_KEYMAP=\"$(KEYMAP)\" -DQMK_KEYMAP_H=\"$(KEYMAP).h\" -DQMK_KEYMAP_CONFIG_H=\"$(KEYMAP_PATH)/config.h\" \
--DQMK_SUBPROJECT -DQMK_SUBPROJECT_H -DQMK_SUBPROJECT_CONFIG_H
+-DQMK_KEYMAP=\"$(KEYMAP)\" -DQMK_KEYMAP_H=\"$(KEYMAP).h\" -DQMK_KEYMAP_CONFIG_H=\"$(KEYMAP_PATH)/config.h\"
 $(KEYMAP_OUTPUT)_INC :=  $(VPATH) $(EXTRAINCDIRS)
 $(KEYMAP_OUTPUT)_CONFIG := $(CONFIG_H)
 $(KEYBOARD_OUTPUT)_SRC := $(PLATFORM_SRC)
@@ -448,7 +460,7 @@ check-md5: build
 objs-size: build
 
 include $(BUILDDEFS_PATH)/show_options.mk
-include $(TMK_PATH)/rules.mk
+include $(BUILDDEFS_PATH)/common_rules.mk
 
 # Ensure we have generated files available for each of the objects
 define GEN_FILES

builddefs/build_layout.mk

@@ -25,7 +25,7 @@ ifneq ($(FORCE_LAYOUT),)
         $(info Forcing layout: $(FORCE_LAYOUT))
         LAYOUTS := $(FORCE_LAYOUT)
     else
-        $(error Forced layout does not exist)
+        $(call CATASTROPHIC_ERROR,Invalid layout,Forced layout does not exist)
     endif
 endif
 

builddefs/build_test.mk

@@ -43,6 +43,7 @@ all: elf
 VPATH += $(COMMON_VPATH)
 PLATFORM:=TEST
 PLATFORM_KEY:=test
+BOOTLOADER_TYPE:=none
 
 ifeq ($(strip $(DEBUG)), 1)
 CONSOLE_ENABLE = yes
@@ -53,7 +54,7 @@ include tests/test_common/build.mk
 include $(TEST_PATH)/test.mk
 endif
 
-include common_features.mk
+include $(BUILDDEFS_PATH)/common_features.mk
 include $(BUILDDEFS_PATH)/generic_features.mk
 include $(PLATFORM_PATH)/common.mk
 include $(TMK_PATH)/protocol.mk
@@ -62,7 +63,7 @@ include $(QUANTUM_PATH)/encoder/tests/rules.mk
 include $(QUANTUM_PATH)/sequencer/tests/rules.mk
 include $(PLATFORM_PATH)/test/rules.mk
 ifneq ($(filter $(FULL_TESTS),$(TEST)),)
-include build_full_test.mk
+include $(BUILDDEFS_PATH)/build_full_test.mk
 endif
 
 $(TEST)_SRC += \
@@ -76,7 +77,7 @@ $(TEST_OBJ)/$(TEST)_DEFS := $($(TEST)_DEFS)
 $(TEST_OBJ)/$(TEST)_CONFIG := $($(TEST)_CONFIG)
 
 include $(PLATFORM_PATH)/$(PLATFORM_KEY)/platform.mk
-include $(TMK_PATH)/rules.mk
+include $(BUILDDEFS_PATH)/common_rules.mk
 
 
 $(shell mkdir -p $(BUILD_DIR)/test 2>/dev/null)

builddefs/common_features.mk

@@ -20,7 +20,6 @@ QUANTUM_SRC += \
     $(QUANTUM_DIR)/led.c \
     $(QUANTUM_DIR)/action.c \
     $(QUANTUM_DIR)/action_layer.c \
-    $(QUANTUM_DIR)/action_macro.c \
     $(QUANTUM_DIR)/action_tapping.c \
     $(QUANTUM_DIR)/action_util.c \
     $(QUANTUM_DIR)/eeconfig.c \
@@ -109,11 +108,10 @@ ifeq ($(strip $(MOUSEKEY_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/mousekey.c
 endif
 
-VALID_POINTING_DEVICE_DRIVER_TYPES := adns5050 adns9800 analog_joystick cirque_pinnacle_i2c cirque_pinnacle_spi pmw3360 pimoroni_trackball custom
-POINTING_DEVICE_DRIVER ?= custom
+VALID_POINTING_DEVICE_DRIVER_TYPES := adns5050 adns9800 analog_joystick cirque_pinnacle_i2c cirque_pinnacle_spi pmw3360 pmw3389 pimoroni_trackball custom
 ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
     ifeq ($(filter $(POINTING_DEVICE_DRIVER),$(VALID_POINTING_DEVICE_DRIVER_TYPES)),)
-        $(error POINTING_DEVICE_DRIVER="$(POINTING_DEVICE_DRIVER)" is not a valid pointing device type)
+        $(call CATASTROPHIC_ERROR,Invalid POINTING_DEVICE_DRIVER,POINTING_DEVICE_DRIVER="$(POINTING_DEVICE_DRIVER)" is not a valid pointing device type)
     else
         OPT_DEFS += -DPOINTING_DEVICE_ENABLE
         MOUSE_ENABLE := yes
@@ -144,6 +142,9 @@ ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
         else ifeq ($(strip $(POINTING_DEVICE_DRIVER)), pmw3360)
             OPT_DEFS += -DSTM32_SPI -DHAL_USE_SPI=TRUE
             QUANTUM_LIB_SRC += spi_master.c
+        else ifeq ($(strip $(POINTING_DEVICE_DRIVER)), pmw3389)
+            OPT_DEFS += -DSTM32_SPI -DHAL_USE_SPI=TRUE
+            QUANTUM_LIB_SRC += spi_master.c
         endif
     endif
 endif
@@ -151,56 +152,88 @@ endif
 VALID_EEPROM_DRIVER_TYPES := vendor custom transient i2c spi
 EEPROM_DRIVER ?= vendor
 ifeq ($(filter $(EEPROM_DRIVER),$(VALID_EEPROM_DRIVER_TYPES)),)
-  $(error EEPROM_DRIVER="$(EEPROM_DRIVER)" is not a valid EEPROM driver)
+  $(call CATASTROPHIC_ERROR,Invalid EEPROM_DRIVER,EEPROM_DRIVER="$(EEPROM_DRIVER)" is not a valid EEPROM driver)
 else
   OPT_DEFS += -DEEPROM_ENABLE
   ifeq ($(strip $(EEPROM_DRIVER)), custom)
+    # Custom EEPROM implementation -- only needs to implement init/erase/read_block/write_block
     OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_CUSTOM
     COMMON_VPATH += $(DRIVER_PATH)/eeprom
     SRC += eeprom_driver.c
   else ifeq ($(strip $(EEPROM_DRIVER)), i2c)
+    # External I2C EEPROM implementation
     OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_I2C
     COMMON_VPATH += $(DRIVER_PATH)/eeprom
     QUANTUM_LIB_SRC += i2c_master.c
     SRC += eeprom_driver.c eeprom_i2c.c
   else ifeq ($(strip $(EEPROM_DRIVER)), spi)
+    # External SPI EEPROM implementation
     OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_SPI
     COMMON_VPATH += $(DRIVER_PATH)/eeprom
     QUANTUM_LIB_SRC += spi_master.c
     SRC += eeprom_driver.c eeprom_spi.c
   else ifeq ($(strip $(EEPROM_DRIVER)), transient)
+    # Transient EEPROM implementation -- no data storage but provides runtime area for it
     OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_TRANSIENT
     COMMON_VPATH += $(DRIVER_PATH)/eeprom
     SRC += eeprom_driver.c eeprom_transient.c
   else ifeq ($(strip $(EEPROM_DRIVER)), vendor)
+    # Vendor-implemented EEPROM
     OPT_DEFS += -DEEPROM_VENDOR
     ifeq ($(PLATFORM),AVR)
       # Automatically provided by avr-libc, nothing required
     else ifeq ($(PLATFORM),CHIBIOS)
       ifneq ($(filter STM32F3xx_% STM32F1xx_% %_STM32F401xC %_STM32F401xE %_STM32F405xG %_STM32F411xE %_STM32F072xB %_STM32F042x6 %_GD32VF103xB %_GD32VF103x8, $(MCU_SERIES)_$(MCU_LDSCRIPT)),)
-        OPT_DEFS += -DEEPROM_DRIVER
+        # Emulated EEPROM
+        OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_STM32_FLASH_EMULATED
         COMMON_VPATH += $(DRIVER_PATH)/eeprom
         SRC += eeprom_driver.c
         SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c
         SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
       else ifneq ($(filter $(MCU_SERIES),STM32L0xx STM32L1xx),)
-        OPT_DEFS += -DEEPROM_DRIVER
+        # True EEPROM on STM32L0xx, L1xx
+        OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_STM32_L0_L1
         COMMON_VPATH += $(DRIVER_PATH)/eeprom
         COMMON_VPATH += $(PLATFORM_PATH)/$(PLATFORM_KEY)/$(DRIVER_DIR)/eeprom
         SRC += eeprom_driver.c
         SRC += eeprom_stm32_L0_L1.c
+      else ifneq ($(filter $(MCU_SERIES),KL2x K20x),)
+        # Teensy EEPROM implementations
+        OPT_DEFS += -DEEPROM_TEENSY
+        SRC += eeprom_teensy.c
       else
-        # This will effectively work the same as "transient" if not supported by the chip
-        SRC += $(PLATFORM_COMMON_DIR)/eeprom_teensy.c
+        # Fall back to transient, i.e. non-persistent
+        OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_TRANSIENT
+        COMMON_VPATH += $(DRIVER_PATH)/eeprom
+        SRC += eeprom_driver.c eeprom_transient.c
       endif
     else ifeq ($(PLATFORM),ARM_ATSAM)
-      SRC += $(PLATFORM_COMMON_DIR)/eeprom.c
+      # arm_atsam EEPROM
+      OPT_DEFS += -DEEPROM_SAMD
+      SRC += $(PLATFORM_COMMON_DIR)/eeprom_samd.c
     else ifeq ($(PLATFORM),TEST)
+      # Test harness "EEPROM"
+      OPT_DEFS += -DEEPROM_TEST_HARNESS
       SRC += $(PLATFORM_COMMON_DIR)/eeprom.c
     endif
   endif
 endif
 
+VALID_FLASH_DRIVER_TYPES := spi
+FLASH_DRIVER ?= no
+ifneq ($(strip $(FLASH_DRIVER)), no)
+    ifeq ($(filter $(FLASH_DRIVER),$(VALID_FLASH_DRIVER_TYPES)),)
+        $(error FLASH_DRIVER="$(FLASH_DRIVER)" is not a valid FLASH driver)
+    else
+        OPT_DEFS += -DFLASH_ENABLE
+        ifeq ($(strip $(FLASH_DRIVER)), spi)
+            OPT_DEFS += -DFLASH_DRIVER -DFLASH_SPI
+            COMMON_VPATH += $(DRIVER_PATH)/flash
+            SRC += flash_spi.c
+        endif
+    endif
+endif
+
 RGBLIGHT_ENABLE ?= no
 VALID_RGBLIGHT_TYPES := WS2812 APA102 custom
 
@@ -212,7 +245,7 @@ ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
     RGBLIGHT_DRIVER ?= WS2812
 
     ifeq ($(filter $(RGBLIGHT_DRIVER),$(VALID_RGBLIGHT_TYPES)),)
-        $(error RGBLIGHT_DRIVER="$(RGBLIGHT_DRIVER)" is not a valid RGB type)
+        $(call CATASTROPHIC_ERROR,Invalid RGBLIGHT_DRIVER,RGBLIGHT_DRIVER="$(RGBLIGHT_DRIVER)" is not a valid RGB type)
     else
         COMMON_VPATH += $(QUANTUM_DIR)/rgblight
         POST_CONFIG_H += $(QUANTUM_DIR)/rgblight/rgblight_post_config.h
@@ -237,12 +270,12 @@ ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
 endif
 
 LED_MATRIX_ENABLE ?= no
-VALID_LED_MATRIX_TYPES := IS31FL3731 custom
+VALID_LED_MATRIX_TYPES := IS31FL3731 IS31FL3742A IS31FL3743A IS31FL3745 IS31FL3746A custom
 # TODO: IS31FL3733 IS31FL3737 IS31FL3741
 
 ifeq ($(strip $(LED_MATRIX_ENABLE)), yes)
     ifeq ($(filter $(LED_MATRIX_DRIVER),$(VALID_LED_MATRIX_TYPES)),)
-        $(error "$(LED_MATRIX_DRIVER)" is not a valid matrix type)
+        $(call CATASTROPHIC_ERROR,Invalid LED_MATRIX_DRIVER,LED_MATRIX_DRIVER="$(LED_MATRIX_DRIVER)" is not a valid matrix type)
     endif
     OPT_DEFS += -DLED_MATRIX_ENABLE
 ifneq (,$(filter $(MCU), atmega16u2 atmega32u2 at90usb162))
@@ -264,14 +297,43 @@ endif
         SRC += is31fl3731-simple.c
         QUANTUM_LIB_SRC += i2c_master.c
     endif
+
+	ifeq ($(strip $(LED_MATRIX_DRIVER)), IS31FL3742A)
+        OPT_DEFS += -DIS31FLCOMMON -DIS31FL3742A -DSTM32_I2C -DHAL_USE_I2C=TRUE
+        COMMON_VPATH += $(DRIVER_PATH)/led/issi
+        SRC += is31flcommon.c
+        QUANTUM_LIB_SRC += i2c_master.c
+    endif
+
+	ifeq ($(strip $(LED_MATRIX_DRIVER)), IS31FL3743A)
+        OPT_DEFS += -DIS31FLCOMMON -DIS31FL3743A -DSTM32_I2C -DHAL_USE_I2C=TRUE
+        COMMON_VPATH += $(DRIVER_PATH)/led/issi
+        SRC += is31flcommon.c
+        QUANTUM_LIB_SRC += i2c_master.c
+    endif
+
+	ifeq ($(strip $(LED_MATRIX_DRIVER)), IS31FL3745)
+        OPT_DEFS += -DIS31FLCOMMON -DIS31FL3745 -DSTM32_I2C -DHAL_USE_I2C=TRUE
+        COMMON_VPATH += $(DRIVER_PATH)/led/issi
+        SRC += is31flcommon.c
+        QUANTUM_LIB_SRC += i2c_master.c
+    endif
+
+	ifeq ($(strip $(LED_MATRIX_DRIVER)), IS31FL3746A)
+        OPT_DEFS += -DIS31FLCOMMON -DIS31FL3746A -DSTM32_I2C -DHAL_USE_I2C=TRUE
+        COMMON_VPATH += $(DRIVER_PATH)/led/issi
+        SRC += is31flcommon.c
+        QUANTUM_LIB_SRC += i2c_master.c
+    endif
+
 endif
 
 RGB_MATRIX_ENABLE ?= no
-VALID_RGB_MATRIX_TYPES := AW20216 IS31FL3731 IS31FL3733 IS31FL3737 IS31FL3741 CKLED2001 WS2812 custom
 
+VALID_RGB_MATRIX_TYPES := AW20216 IS31FL3731 IS31FL3733 IS31FL3737 IS31FL3741 IS31FL3742A IS31FL3743A IS31FL3745 IS31FL3746A CKLED2001 WS2812 custom
 ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
     ifeq ($(filter $(RGB_MATRIX_DRIVER),$(VALID_RGB_MATRIX_TYPES)),)
-        $(error "$(RGB_MATRIX_DRIVER)" is not a valid matrix type)
+        $(call CATASTROPHIC_ERROR,Invalid RGB_MATRIX_DRIVER,RGB_MATRIX_DRIVER="$(RGB_MATRIX_DRIVER)" is not a valid matrix type)
     endif
     OPT_DEFS += -DRGB_MATRIX_ENABLE
 ifneq (,$(filter $(MCU), atmega16u2 atmega32u2 at90usb162))
@@ -323,6 +385,34 @@ endif
         QUANTUM_LIB_SRC += i2c_master.c
     endif
 
+	ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3742A)
+        OPT_DEFS += -DIS31FLCOMMON -DIS31FL3742A -DSTM32_I2C -DHAL_USE_I2C=TRUE
+        COMMON_VPATH += $(DRIVER_PATH)/led/issi
+        SRC += is31flcommon.c
+        QUANTUM_LIB_SRC += i2c_master.c
+    endif
+
+	ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3743A)
+        OPT_DEFS += -DIS31FLCOMMON -DIS31FL3743A -DSTM32_I2C -DHAL_USE_I2C=TRUE
+        COMMON_VPATH += $(DRIVER_PATH)/led/issi
+        SRC += is31flcommon.c
+        QUANTUM_LIB_SRC += i2c_master.c
+    endif
+
+	ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3745)
+        OPT_DEFS += -DIS31FLCOMMON -DIS31FL3745 -DSTM32_I2C -DHAL_USE_I2C=TRUE
+        COMMON_VPATH += $(DRIVER_PATH)/led/issi
+        SRC += is31flcommon.c
+        QUANTUM_LIB_SRC += i2c_master.c
+    endif
+
+	ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3746A)
+        OPT_DEFS += -DIS31FLCOMMON -DIS31FL3746A -DSTM32_I2C -DHAL_USE_I2C=TRUE
+        COMMON_VPATH += $(DRIVER_PATH)/led/issi
+        SRC += is31flcommon.c
+        QUANTUM_LIB_SRC += i2c_master.c
+    endif
+
     ifeq ($(strip $(RGB_MATRIX_DRIVER)), CKLED2001)
         OPT_DEFS += -DCKLED2001 -DSTM32_I2C -DHAL_USE_I2C=TRUE
         COMMON_VPATH += $(DRIVER_PATH)/led
@@ -356,7 +446,7 @@ endif
 ifeq ($(strip $(PRINTING_ENABLE)), yes)
     OPT_DEFS += -DPRINTING_ENABLE
     SRC += $(QUANTUM_DIR)/process_keycode/process_printer.c
-    SRC += $(TMK_DIR)/protocol/serial_uart.c
+    QUANTUM_LIB_SRC += uart.c
 endif
 
 VARIABLE_TRACE ?= no
@@ -385,7 +475,7 @@ else
 endif
 ifeq ($(strip $(BACKLIGHT_ENABLE)), yes)
     ifeq ($(filter $(BACKLIGHT_DRIVER),$(VALID_BACKLIGHT_TYPES)),)
-        $(error BACKLIGHT_DRIVER="$(BACKLIGHT_DRIVER)" is not a valid backlight type)
+        $(call CATASTROPHIC_ERROR,Invalid BACKLIGHT_DRIVER,BACKLIGHT_DRIVER="$(BACKLIGHT_DRIVER)" is not a valid backlight type)
     endif
 
     COMMON_VPATH += $(QUANTUM_DIR)/backlight
@@ -410,7 +500,7 @@ VALID_WS2812_DRIVER_TYPES := bitbang pwm spi i2c
 WS2812_DRIVER ?= bitbang
 ifeq ($(strip $(WS2812_DRIVER_REQUIRED)), yes)
     ifeq ($(filter $(WS2812_DRIVER),$(VALID_WS2812_DRIVER_TYPES)),)
-        $(error WS2812_DRIVER="$(WS2812_DRIVER)" is not a valid WS2812 driver)
+        $(call CATASTROPHIC_ERROR,Invalid WS2812_DRIVER,WS2812_DRIVER="$(WS2812_DRIVER)" is not a valid WS2812 driver)
     endif
 
     OPT_DEFS += -DWS2812_DRIVER_$(strip $(shell echo $(WS2812_DRIVER) | tr '[:lower:]' '[:upper:]'))
@@ -465,7 +555,7 @@ VALID_MAGIC_TYPES := yes
 BOOTMAGIC_ENABLE ?= no
 ifneq ($(strip $(BOOTMAGIC_ENABLE)), no)
   ifeq ($(filter $(BOOTMAGIC_ENABLE),$(VALID_MAGIC_TYPES)),)
-    $(error BOOTMAGIC_ENABLE="$(BOOTMAGIC_ENABLE)" is not a valid type of magic)
+    $(call CATASTROPHIC_ERROR,Invalid BOOTMAGIC_ENABLE,BOOTMAGIC_ENABLE="$(BOOTMAGIC_ENABLE)" is not a valid type of magic)
   endif
   ifneq ($(strip $(BOOTMAGIC_ENABLE)), no)
       OPT_DEFS += -DBOOTMAGIC_LITE
@@ -481,7 +571,7 @@ CUSTOM_MATRIX ?= no
 
 ifneq ($(strip $(CUSTOM_MATRIX)), yes)
     ifeq ($(filter $(CUSTOM_MATRIX),$(VALID_CUSTOM_MATRIX_TYPES)),)
-        $(error CUSTOM_MATRIX="$(CUSTOM_MATRIX)" is not a valid custom matrix type)
+        $(call CATASTROPHIC_ERROR,Invalid CUSTOM_MATRIX,CUSTOM_MATRIX="$(CUSTOM_MATRIX)" is not a valid custom matrix type)
     endif
 
     # Include common stuff for all non custom matrix users
@@ -564,7 +654,7 @@ VALID_OLED_DRIVER_TYPES := SSD1306 custom
 OLED_DRIVER ?= SSD1306
 ifeq ($(strip $(OLED_ENABLE)), yes)
     ifeq ($(filter $(OLED_DRIVER),$(VALID_OLED_DRIVER_TYPES)),)
-        $(error OLED_DRIVER="$(OLED_DRIVER)" is not a valid OLED driver)
+        $(call CATASTROPHIC_ERROR,Invalid OLED_DRIVER,OLED_DRIVER="$(OLED_DRIVER)" is not a valid OLED driver)
     else
         OPT_DEFS += -DOLED_ENABLE
         COMMON_VPATH += $(DRIVER_PATH)/oled
@@ -604,6 +694,7 @@ ifeq ($(strip $(UNICODE_ENABLE)), yes)
 endif
 
 ifeq ($(strip $(UNICODE_COMMON)), yes)
+    OPT_DEFS += -DUNICODE_COMMON_ENABLE
     SRC += $(QUANTUM_DIR)/process_keycode/process_unicode_common.c
 endif
 
@@ -631,7 +722,7 @@ endif
 ifeq ($(strip $(PS2_USE_BUSYWAIT)), yes)
     PS2_ENABLE := yes
     SRC += ps2_busywait.c
-    SRC += ps2_io_avr.c
+    SRC += ps2_io.c
     OPT_DEFS += -DPS2_USE_BUSYWAIT
 endif
 
@@ -660,7 +751,7 @@ VALID_JOYSTICK_TYPES := analog digital
 JOYSTICK_DRIVER ?= analog
 ifeq ($(strip $(JOYSTICK_ENABLE)), yes)
     ifeq ($(filter $(JOYSTICK_DRIVER),$(VALID_JOYSTICK_TYPES)),)
-        $(error "$(JOYSTICK_DRIVER)" is not a valid joystick driver)
+        $(call CATASTROPHIC_ERROR,Invalid JOYSTICK_DRIVER,JOYSTICK_DRIVER="$(JOYSTICK_DRIVER)" is not a valid joystick driver)
     endif
     OPT_DEFS += -DJOYSTICK_ENABLE
     SRC += $(QUANTUM_DIR)/process_keycode/process_joystick.c
@@ -680,7 +771,7 @@ VALID_USBPD_DRIVER_TYPES = custom vendor
 USBPD_DRIVER ?= vendor
 ifeq ($(strip $(USBPD_ENABLE)), yes)
     ifeq ($(filter $(strip $(USBPD_DRIVER)),$(VALID_USBPD_DRIVER_TYPES)),)
-        $(error USBPD_DRIVER="$(USBPD_DRIVER)" is not a valid USBPD driver)
+        $(call CATASTROPHIC_ERROR,Invalid USBPD_DRIVER,USBPD_DRIVER="$(USBPD_DRIVER)" is not a valid USBPD driver)
     else
         OPT_DEFS += -DUSBPD_ENABLE
         ifeq ($(strip $(USBPD_DRIVER)), vendor)
@@ -690,7 +781,7 @@ ifeq ($(strip $(USBPD_ENABLE)), yes)
                 OPT_DEFS += -DUSBPD_STM32G4
                 SRC += usbpd_stm32g4.c
             else
-                $(error There is no vendor-provided USBPD driver available)
+                $(call CATASTROPHIC_ERROR,Invalid USBPD_DRIVER,There is no vendor-provided USBPD driver available)
             endif
         else ifeq ($(strip $(USBPD_DRIVER)), custom)
             OPT_DEFS += -DUSBPD_CUSTOM
@@ -700,25 +791,26 @@ ifeq ($(strip $(USBPD_ENABLE)), yes)
 endif
 
 BLUETOOTH_ENABLE ?= no
-VALID_BLUETOOTH_DRIVER_TYPES := AdafruitBLE RN42 custom
+VALID_BLUETOOTH_DRIVER_TYPES := BluefruitLE RN42 custom
 ifeq ($(strip $(BLUETOOTH_ENABLE)), yes)
     ifeq ($(filter $(strip $(BLUETOOTH_DRIVER)),$(VALID_BLUETOOTH_DRIVER_TYPES)),)
-        $(error "$(BLUETOOTH_DRIVER)" is not a valid Bluetooth driver type)
+        $(call CATASTROPHIC_ERROR,Invalid BLUETOOTH_DRIVER,BLUETOOTH_DRIVER="$(BLUETOOTH_DRIVER)" is not a valid Bluetooth driver type)
     endif
     OPT_DEFS += -DBLUETOOTH_ENABLE
     NO_USB_STARTUP_CHECK := yes
     COMMON_VPATH += $(DRIVER_PATH)/bluetooth
     SRC += outputselect.c
 
-    ifeq ($(strip $(BLUETOOTH_DRIVER)), AdafruitBLE)
-        OPT_DEFS += -DMODULE_ADAFRUIT_BLE
+    ifeq ($(strip $(BLUETOOTH_DRIVER)), BluefruitLE)
+        OPT_DEFS += -DBLUETOOTH_BLUEFRUIT_LE
         SRC += analog.c
-        SRC += $(DRIVER_PATH)/bluetooth/adafruit_ble.cpp
+        SRC += $(DRIVER_PATH)/bluetooth/bluefruit_le.cpp
         QUANTUM_LIB_SRC += spi_master.c
     endif
 
     ifeq ($(strip $(BLUETOOTH_DRIVER)), RN42)
-        OPT_DEFS += -DMODULE_RN42
-        SRC += $(TMK_DIR)/protocol/serial_uart.c
+        OPT_DEFS += -DBLUETOOTH_RN42
+        SRC += $(DRIVER_PATH)/bluetooth/rn42.c
+        QUANTUM_LIB_SRC += uart.c
     endif
 endif

builddefs/common_rules.mk

@@ -234,6 +234,7 @@ endif
 
 # Define programs and commands.
 SHELL = sh
+SED = sed
 REMOVE = rm -f
 REMOVEDIR = rmdir
 COPY = cp
@@ -292,17 +293,15 @@ sym: $(BUILD_DIR)/$(TARGET).sym
 LIBNAME=lib$(TARGET).a
 lib: $(LIBNAME)
 
-# Display size of file.
-HEXSIZE = $(SIZE) --target=$(FORMAT) $(BUILD_DIR)/$(TARGET).hex
-#ELFSIZE = $(SIZE) --mcu=$(MCU) --format=avr $(TARGET).elf
-ELFSIZE = $(SIZE) $(BUILD_DIR)/$(TARGET).elf
+# Display size of file, modifying the output so people don't mistakenly grab the hex output
+BINARY_SIZE = $(SIZE) --target=$(FORMAT) $(BUILD_DIR)/$(TARGET).hex | $(SED) -e 's/\.build\/.*$$/$(TARGET).$(FIRMWARE_FORMAT)/g'
 
 sizebefore:
-	@if test -f $(BUILD_DIR)/$(TARGET).hex; then $(SECHO) $(MSG_SIZE_BEFORE); $(SILENT) || $(HEXSIZE); \
+	@if test -f $(BUILD_DIR)/$(TARGET).hex; then $(SECHO) $(MSG_SIZE_BEFORE); $(SILENT) || $(BINARY_SIZE); \
 	2>/dev/null; $(SECHO); fi
 
 sizeafter: $(BUILD_DIR)/$(TARGET).hex
-	@if test -f $(BUILD_DIR)/$(TARGET).hex; then $(SECHO); $(SECHO) $(MSG_SIZE_AFTER); $(SILENT) || $(HEXSIZE); \
+	@if test -f $(BUILD_DIR)/$(TARGET).hex; then $(SECHO); $(SECHO) $(MSG_SIZE_AFTER); $(SILENT) || $(BINARY_SIZE); \
 	2>/dev/null; $(SECHO); fi
 
 # Display compiler version information.
@@ -479,7 +478,7 @@ ifeq ($(findstring avr-gcc,$(CC)),avr-gcc)
 SIZE_MARGIN = 1024
 
 check-size:
-	$(eval MAX_SIZE=$(shell n=`$(CC) -E -mmcu=$(MCU) -D__ASSEMBLER__ $(CFLAGS) $(OPT_DEFS) platforms/avr/bootloader_size.c 2> /dev/null | sed -ne 's/\r//;/^#/n;/^AVR_SIZE:/,$${s/^AVR_SIZE: //;p;}'` && echo $$(($$n)) || echo 0))
+	$(eval MAX_SIZE=$(shell n=`$(CC) -E -mmcu=$(MCU) -D__ASSEMBLER__ $(CFLAGS) $(OPT_DEFS) platforms/avr/bootloader_size.c 2> /dev/null | $(SED) -ne 's/\r//;/^#/n;/^AVR_SIZE:/,$${s/^AVR_SIZE: //;p;}'` && echo $$(($$n)) || echo 0))
 	$(eval CURRENT_SIZE=$(shell if [ -f $(BUILD_DIR)/$(TARGET).hex ]; then $(SIZE) --target=$(FORMAT) $(BUILD_DIR)/$(TARGET).hex | $(AWK) 'NR==2 {print $$4}'; else printf 0; fi))
 	$(eval FREE_SIZE=$(shell expr $(MAX_SIZE) - $(CURRENT_SIZE)))
 	$(eval OVER_SIZE=$(shell expr $(CURRENT_SIZE) - $(MAX_SIZE)))

builddefs/mcu_selection.mk

@@ -143,6 +143,9 @@ ifneq ($(findstring STM32F042, $(MCU)),)
   # This ensures that the EEPROM page buffer fits into RAM
   USE_PROCESS_STACKSIZE = 0x600
   USE_EXCEPTIONS_STACKSIZE = 0x300
+
+  # Bootloader address for STM32 DFU
+  STM32_BOOTLOADER_ADDRESS ?= 0x1FFFC400
 endif
 
 ifneq ($(findstring STM32F072, $(MCU)),)
@@ -175,6 +178,9 @@ ifneq ($(findstring STM32F072, $(MCU)),)
 
   # UF2 settings
   UF2_FAMILY ?= STM32F0
+
+  # Bootloader address for STM32 DFU
+  STM32_BOOTLOADER_ADDRESS ?= 0x1FFFC800
 endif
 
 ifneq ($(findstring STM32F103, $(MCU)),)
@@ -239,6 +245,9 @@ ifneq ($(findstring STM32F303, $(MCU)),)
 
   # UF2 settings
   UF2_FAMILY ?= STM32F3
+
+  # Bootloader address for STM32 DFU
+  STM32_BOOTLOADER_ADDRESS ?= 0x1FFFD800
 endif
 
 ifneq ($(findstring STM32F401, $(MCU)),)
@@ -276,6 +285,9 @@ ifneq ($(findstring STM32F401, $(MCU)),)
 
   # UF2 settings
   UF2_FAMILY ?= STM32F4
+
+  # Bootloader address for STM32 DFU
+  STM32_BOOTLOADER_ADDRESS ?= 0x1FFF0000
 endif
 
 ifneq ($(findstring STM32F405, $(MCU)),)
@@ -308,6 +320,9 @@ ifneq ($(findstring STM32F405, $(MCU)),)
 
   # UF2 settings
   UF2_FAMILY ?= STM32F4
+
+  # Bootloader address for STM32 DFU
+  STM32_BOOTLOADER_ADDRESS ?= 0x1FFF0000
 endif
 
 ifneq ($(findstring STM32F407, $(MCU)),)
@@ -340,6 +355,9 @@ ifneq ($(findstring STM32F407, $(MCU)),)
 
   # UF2 settings
   UF2_FAMILY ?= STM32F4
+
+  # Bootloader address for STM32 DFU
+  STM32_BOOTLOADER_ADDRESS ?= 0x1FFF0000
 endif
 
 ifneq ($(findstring STM32F411, $(MCU)),)
@@ -377,6 +395,9 @@ ifneq ($(findstring STM32F411, $(MCU)),)
 
   # UF2 settings
   UF2_FAMILY ?= STM32F4
+
+  # Bootloader address for STM32 DFU
+  STM32_BOOTLOADER_ADDRESS ?= 0x1FFF0000
 endif
 
 ifneq ($(findstring STM32F446, $(MCU)),)
@@ -406,6 +427,9 @@ ifneq ($(findstring STM32F446, $(MCU)),)
   BOARD ?= GENERIC_STM32_F446XE
 
   USE_FPU ?= yes
+
+  # Bootloader address for STM32 DFU
+  STM32_BOOTLOADER_ADDRESS ?= 0x1FFF0000
 endif
 
 ifneq ($(findstring STM32G431, $(MCU)),)
@@ -438,6 +462,9 @@ ifneq ($(findstring STM32G431, $(MCU)),)
 
   # UF2 settings
   UF2_FAMILY ?= STM32G4
+
+  # Bootloader address for STM32 DFU
+  STM32_BOOTLOADER_ADDRESS ?= 0x1FFF0000
 endif
 
 ifneq ($(findstring STM32G474, $(MCU)),)
@@ -470,6 +497,46 @@ ifneq ($(findstring STM32G474, $(MCU)),)
 
   # UF2 settings
   UF2_FAMILY ?= STM32G4
+
+  # Bootloader address for STM32 DFU
+  STM32_BOOTLOADER_ADDRESS ?= 0x1FFF0000
+endif
+
+ifneq (,$(filter $(MCU),STM32L432 STM32L442))
+  # Cortex version
+  MCU = cortex-m4
+
+  # ARM version, CORTEX-M0/M1 are 6, CORTEX-M3/M4/M7 are 7
+  ARMV = 7
+
+  ## chip/board settings
+  # - the next two should match the directories in
+  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  MCU_FAMILY = STM32
+  MCU_SERIES = STM32L4xx
+
+  # Linker script to use
+  # - it should exist either in <chibios>/os/common/startup/ARMCMx/compilers/GCC/ld/
+  #   or <keyboard_dir>/ld/
+  MCU_LDSCRIPT ?= STM32L432xC
+
+  # Startup code to use
+  #  - it should exist in <chibios>/os/common/startup/ARMCMx/compilers/GCC/mk/
+  MCU_STARTUP ?= stm32l4xx
+
+  # Board: it should exist either in <chibios>/os/hal/boards/,
+  # <keyboard_dir>/boards/, or drivers/boards/
+  BOARD ?= GENERIC_STM32_L432XC
+
+  PLATFORM_NAME ?= platform_l432
+
+  USE_FPU ?= yes
+
+  # UF2 settings
+  UF2_FAMILY ?= STM32L4
+
+  # Bootloader address for STM32 DFU
+  STM32_BOOTLOADER_ADDRESS ?= 0x1FFF0000
 endif
 
 ifneq (,$(filter $(MCU),STM32L433 STM32L443))
@@ -504,6 +571,9 @@ ifneq (,$(filter $(MCU),STM32L433 STM32L443))
 
   # UF2 settings
   UF2_FAMILY ?= STM32L4
+
+  # Bootloader address for STM32 DFU
+  STM32_BOOTLOADER_ADDRESS ?= 0x1FFF0000
 endif
 
 ifneq (,$(filter $(MCU),STM32L412 STM32L422))
@@ -538,6 +608,9 @@ ifneq (,$(filter $(MCU),STM32L412 STM32L422))
 
   # UF2 settings
   UF2_FAMILY ?= STM32L4
+
+  # Bootloader address for STM32 DFU
+  STM32_BOOTLOADER_ADDRESS ?= 0x1FFF0000
 endif
 
 ifneq ($(findstring WB32F3G71, $(MCU)),)
@@ -567,6 +640,10 @@ ifneq ($(findstring WB32F3G71, $(MCU)),)
   BOARD ?= GENERIC_WB32_F3G71XX
 
   USE_FPU ?= no
+
+  # Bootloader address for WB32 DFU
+  STM32_BOOTLOADER_ADDRESS ?= 0x1FFFE000
+  WB32_BOOTLOADER_ADDRESS ?= 0x1FFFE000
 endif
 
 ifneq ($(findstring GD32VF103, $(MCU)),)

builddefs/message.mk

@@ -87,6 +87,7 @@ define GENERATE_MSG_AVAILABLE_KEYMAPS
 endef
 MSG_AVAILABLE_KEYMAPS = $(eval $(call GENERATE_MSG_AVAILABLE_KEYMAPS))$(MSG_AVAILABLE_KEYMAPS_ACTUAL)
 
+MSG_BOOTLOADER_NOT_FOUND_BASE = Bootloader not found. Make sure the board is in bootloader mode. See https://docs.qmk.fm/\#/newbs_flashing\n
 MSG_CHECK_FILESIZE = Checking file size of $(TARGET).$(FIRMWARE_FORMAT)
 MSG_CHECK_FILESIZE_SKIPPED = (Firmware size check does not yet support $(MCU_ORIG); skipping)
 MSG_FILE_TOO_BIG = $(ERROR_COLOR)The firmware is too large!$(NO_COLOR) $(CURRENT_SIZE)/$(MAX_SIZE) ($(OVER_SIZE) bytes over)\n
@@ -97,6 +98,11 @@ MSG_PYTHON_MISSING = $(ERROR_COLOR)ERROR:$(NO_COLOR) Cannot run \"qmk hello\"!\n
 	Please run $(BOLD)qmk setup$(NO_COLOR) to install all the dependencies QMK requires.\n\n
 MSG_FLASH_BOOTLOADER = $(WARN_COLOR)WARNING:$(NO_COLOR) This board's bootloader is not specified or is not supported by the \":flash\" target at this time.\n\n
 MSG_FLASH_ARCH = $(WARN_COLOR)WARNING:$(NO_COLOR) This board's architecture is not supported by the \":flash\" target at this time.\n\n
-MSG_BOOTLOADER_NOT_FOUND = $(ERROR_COLOR)ERROR:$(NO_COLOR) Bootloader not found. Trying again in 5s (Ctrl+C to cancel)\n
+MSG_BOOTLOADER_NOT_FOUND = $(ERROR_COLOR)ERROR:$(NO_COLOR) $(MSG_BOOTLOADER_NOT_FOUND_BASE) Trying again in 5s (Ctrl+C to cancel)\n
 BOOTLOADER_RETRY_TIME ?= 0.5
-MSG_BOOTLOADER_NOT_FOUND_QUICK_RETRY = Bootloader not found. Trying again every $(BOOTLOADER_RETRY_TIME)s (Ctrl+C to cancel)
+MSG_BOOTLOADER_NOT_FOUND_QUICK_RETRY = $(MSG_BOOTLOADER_NOT_FOUND_BASE) Trying again every $(BOOTLOADER_RETRY_TIME)s (Ctrl+C to cancel)
+
+define CATASTROPHIC_ERROR
+    $(shell printf "\n * %-99s $(ERROR_STRING)\n" "$2" >&2)
+    $(error $1)
+endef

builddefs/testlist.mk

@@ -8,7 +8,7 @@ include $(PLATFORM_PATH)/test/testlist.mk
 define VALIDATE_TEST_LIST
     ifneq ($1,)
         ifeq ($$(findstring -,$1),-)
-            $$(error Test names can't contain '-', but '$1' does)
+            $$(call CATASTROPHIC_ERROR,Invalid test name,Test names can't contain '-', but '$1' does.)
         else
             $$(eval $$(call VALIDATE_TEST_LIST,$$(firstword $2),$$(wordlist 2,9999,$2)))
         endif

data/mappings/info_config.json

@@ -15,6 +15,8 @@
     "COMBO_TERM": {"info_key": "combo.term", "value_type": "int"},
     "DEBOUNCE": {"info_key": "debounce", "value_type": "int"},
     "DEVICE_VER": {"info_key": "usb.device_ver", "value_type": "hex"},
+    # TODO: Replace ^^^ with vvv
+    #"DEVICE_VER": {"info_key": "usb.device_version", "value_type": "bcd_version"},
     "DESCRIPTION": {"info_key": "keyboard_folder", "to_json": false},
     "DIODE_DIRECTION": {"info_key": "diode_direction"},
     "FORCE_NKRO": {"info_key": "usb.force_nkro", "value_type": "bool"},

data/mappings/keyboard_aliases.json

@@ -41,8 +41,14 @@
     'atom47/rev3': {
           target: 'maartenwut/atom47/rev3'
     },
+    bakeneko60: {
+          target: 'kkatano/bakeneko60'
+    },
     bakeneko65: {
-          target: 'bakeneko65/rev2'
+          target: 'kkatano/bakeneko65/rev2'
+    },
+    bakeneko80: {
+          target: 'kkatano/bakeneko80'
     },
     bear_face: {
           target: 'bear_face/v1'
@@ -215,6 +221,9 @@
                   LAYOUT: 'LAYOUT_all'
           }
     },
+    idobo: {
+        target: 'idobao/id75'
+    },
     'jj40': {
           target: 'kprepublic/jj40'
     },
@@ -260,6 +269,9 @@
     'lfkeyboards/smk65': {
           target: 'lfkeyboards/smk65/revb'
     },
+    m3v3van: {
+          target: 'matthewdias/m3n3van'
+    },
     'maartenwut/atom47/rev2': {
           target: 'evyd13/atom47/rev2'
     },
@@ -344,15 +356,24 @@
     'mechlovin/hannah65/mechlovin9': {
           target: 'mechlovin/mechlovin9/rev1'
     },
+    'mechlovin/hex4b': {
+          target: 'mechlovin/hex4b/rev1'
+    },
     'melgeek/z70ultra': {
           target: 'melgeek/z70ultra/rev1'
     },
     'mechlovin/hannah65': {
           target: 'mechlovin/hannah65/rev1'
     },
+    minim: {
+          target: 'matthewdias/minim'
+    },
     model01: {
           target: 'keyboardio/model01'
     },
+    model_v: {
+          target: 'matthewdias/model_v'
+    },
     m0lly: {
           target: 'tkc/m0lly'
     },
@@ -495,6 +516,9 @@
     'tokyo60': {
           target: 'tokyokeyboard/tokyo60'
     },
+    'txuu': {
+          target: 'matthewdias/txuu'
+    },
     underscore33: {
           target: 'underscore33/rev1'
     },
@@ -547,7 +571,7 @@
           target: 'xelus/valor/rev1'
     },
     yd60mq: {
-          target: 'yd60mq/12led'
+          target: 'ymdk/yd60mq/12led'
     },
     ymd75: {
           target: 'ymd75/rev1'
@@ -560,5 +584,615 @@
     },
     zeal65: {
           target: 'wilba_tech/zeal65'
+    },
+    # Moved during 2022 Q1 cycle
+    6ball: {
+        target: 'maple_computing/6ball'
+    },
+    7skb: {
+        target: 'salicylic_acid3/7skb'
+    },
+    7splus: {
+        target: 'salicylic_acid3/7splus'
+    },
+    acr60: {
+        target: 'mechkeys/acr60'
+    },
+    adalyn: {
+        target: 'tominabox1/adalyn'
+    },
+    ajisai74: {
+        target: 'salicylic_acid3/ajisai74'
+    },
+    aleth42: {
+        target: '25keys/aleth42'
+    },
+    alicia_cook: {
+        target: 'ibnuda/alicia_cook'
+    },
+    allison: {
+        target: 'prototypist/allison'
+    },
+    allison_numpad: {
+        target: 'prototypist/allison_numpad'
+    },
+    alu84: {
+        target: 'mechkeys/alu84'
+    },
+    angel17: {
+        target: 'kakunpc/angel17'
+    },
+    angel64/alpha: {
+        target: 'kakunpc/angel64/alpha'
+    },
+    angel64/rev1: {
+        target: 'kakunpc/angel64/rev1'
+    },
+    arch_36: {
+        target: 'obosob/arch_36'
+    },
+    bakeneko60: {
+        target: 'kkatano/bakeneko60'
+    },
+    bakeneko65/rev2: {
+        target: 'kkatano/bakeneko65/rev2'
+    },
+    bakeneko65/rev3: {
+        target: 'kkatano/bakeneko65/rev3'
+    },
+    bakeneko80: {
+        target: 'kkatano/bakeneko80'
+    },
+    barleycorn: {
+        target: 'yiancardesigns/barleycorn'
+    },
+    bat43/rev1: {
+        target: 'dailycraft/bat43/rev1'
+    },
+    bat43/rev2: {
+        target: 'dailycraft/bat43/rev2'
+    },
+    bigseries/1key: {
+        target: 'woodkeys/bigseries/1key'
+    },
+    bigseries/2key: {
+        target: 'woodkeys/bigseries/2key'
+    },
+    bigseries/3key: {
+        target: 'woodkeys/bigseries/3key'
+    },
+    bigseries/4key: {
+        target: 'woodkeys/bigseries/4key'
+    },
+    bkf: {
+        target: 'drhigsby/bkf'
+    },
+    business_card/alpha: {
+        target: 'kakunpc/business_card/alpha'
+    },
+    business_card/beta: {
+        target: 'kakunpc/business_card/beta'
+    },
+    butterstick: {
+        target: 'gboards/butterstick'
+    },
+    c39: {
+        target: 'maple_computing/c39'
+    },
+    cassette42: {
+        target: '25keys/cassette42'
+    },
+    chidori: {
+        target: 'kagizaraya/chidori'
+    },
+    chili: {
+        target: 'ydkb/chili'
+    },
+    chimera_ergo: {
+        target: 'glenpickle/chimera_ergo'
+    },
+    chimera_ls: {
+        target: 'glenpickle/chimera_ls'
+    },
+    chimera_ortho: {
+        target: 'glenpickle/chimera_ortho'
+    },
+    chimera_ortho_plus: {
+        target: 'glenpickle/chimera_ortho_plus'
+    },
+    choc_taro: {
+        target: 'kakunpc/choc_taro'
+    },
+    choco60: {
+        target: 'recompile_keys/choco60'
+    },
+    christmas_tree: {
+        target: 'maple_computing/christmas_tree'
+    },
+    claw44/rev1: {
+        target: 'dailycraft/claw44/rev1'
+    },
+    cocoa40: {
+        target: 'recompile_keys/cocoa40'
+    },
+    comet46: {
+        target: 'satt/comet46'
+    },
+    cu24: {
+        target: 'capsunlocked/cu24'
+    },
+    cu75: {
+        target: 'capsunlocked/cu75'
+    },
+    cu80: {
+        target: 'capsunlocked/cu80/v1'
+    },
+    delilah: {
+        target: 'rainkeebs/delilah'
+    },
+    diverge3: {
+        target: 'unikeyboard/diverge3'
+    },
+    divergetm2: {
+        target: 'unikeyboard/divergetm2'
+    },
+    dozen0: {
+        target: 'yynmt/dozen0'
+    },
+    dubba175: {
+        target: 'drhigsby/dubba175'
+    },
+    eggman: {
+        target: 'qpockets/eggman'
+    },
+    ergo42: {
+        target: 'biacco42/ergo42'
+    },
+    ergoarrows: {
+        target: 'salicylic_acid3/ergoarrows'
+    },
+    ergodash/mini: {
+        target: 'omkbd/ergodash/mini'
+    },
+    ergodash/rev1: {
+        target: 'omkbd/ergodash/rev1'
+    },
+    ergodox_infinity: {
+        target: 'input_club/ergodox_infinity'
+    },
+    ergotaco: {
+        target: 'gboards/ergotaco'
+    },
+    espectro: {
+        target: 'mechkeys/espectro'
+    },
+    felix: {
+        target: 'unikeyboard/felix'
+    },
+    four_banger: {
+        target: 'bpiphany/four_banger'
+    },
+    freyr: {
+        target: 'hnahkb/freyr'
+    },
+    geminate60: {
+        target: 'weirdo/geminate60'
+    },
+    georgi: {
+        target: 'gboards/georgi'
+    },
+    gergo: {
+        target: 'gboards/gergo'
+    },
+    getta25: {
+        target: 'salicylic_acid3/getta25'
+    },
+    gingham: {
+        target: 'yiancardesigns/gingham'
+    },
+    gurindam: {
+        target: 'ibnuda/gurindam'
+    },
+    halberd: {
+        target: 'kagizaraya/halberd'
+    },
+    hecomi/alpha: {
+        target: 'takashiski/hecomi/alpha'
+    },
+    hid_liber: {
+        target: 'bpiphany/hid_liber'
+    },
+    id67/default_rgb: {
+        target: 'idobao/id67/default_rgb'
+    },
+    id67/rgb: {
+        target: 'idobao/id67/rgb'
+    },
+    id80: {
+        target: 'idobao/id80/v1'
+    },
+    id87: {
+        target: 'idobao/id87/v1'
+    },
+    idobo: {
+        target: 'idobao/id75/v1'
+    },
+    infinity60: {
+        target: 'input_club/infinity60'
+    },
+    ivy/rev1: {
+        target: 'maple_computing/ivy/rev1'
+    },
+    jisplit89: {
+        target: 'salicylic_acid3/jisplit89'
+    },
+    jnao: {
+        target: 'maple_computing/jnao'
+    },
+    just60: {
+        target: 'ydkb/just60'
+    },
+    k_type: {
+        target: 'input_club/k_type'
+    },
+    kagamidget: {
+        target: 'yynmt/kagamidget'
+    },
+    kelowna/rgb64: {
+        target: 'weirdo/kelowna/rgb64'
+    },
+    kprepublic/bm65hsrgb_iso: {
+        target: 'kprepublic/bm65hsrgb_iso/rev1'
+    },
+    kprepublic/bm68hsrgb: {
+        target: 'kprepublic/bm68hsrgb/rev1'
+    },
+    latin17rgb: {
+        target: 'latincompass/latin17rgb'
+    },
+    latin47ble: {
+        target: 'latincompass/latin47ble'
+    },
+    latin60rgb: {
+        target: 'latincompass/latin60rgb'
+    },
+    latin64ble: {
+        target: 'latincompass/latin64ble'
+    },
+    latin6rgb: {
+        target: 'latincompass/latin6rgb'
+    },
+    latinpad: {
+        target: 'latincompass/latinpad'
+    },
+    latinpadble: {
+        target: 'latincompass/latinpadble'
+    },
+    launchpad/rev1: {
+        target: 'maple_computing/launchpad/rev1'
+    },
+    lck75: {
+        target: 'lyso1/lck75'
+    },
+    le_chiffre: {
+        target: 'tominabox1/le_chiffre'
+    },
+    lefishe: {
+        target: 'lyso1/lefishe'
+    },
+    lets_split_eh/eh: {
+        target: 'maple_computing/lets_split_eh/eh'
+    },
+    ls_60: {
+        target: 'weirdo/ls_60'
+    },
+    m3n3van: {
+        target: 'matthewdias/m3n3van'
+    },
+    mechmini/v1: {
+        target: 'mechkeys/mechmini/v1'
+    },
+    mechmini/v2: {
+        target: 'mechkeys/mechmini/v2'
+    },
+    meira: {
+        target: 'woodkeys/meira'
+    },
+    meishi: {
+        target: 'biacco42/meishi'
+    },
+    meishi2: {
+        target: 'biacco42/meishi2'
+    },
+    minidox/rev1: {
+        target: 'maple_computing/minidox/rev1'
+    },
+    minim: {
+        target: 'matthewdias/minim'
+    },
+    mio: {
+        target: 'recompile_keys/mio'
+    },
+    model_v: {
+        target: 'matthewdias/model_v'
+    },
+    montex: {
+        target: 'idobao/montex/v1'
+    },
+    nafuda: {
+        target: 'salicylic_acid3/nafuda'
+    },
+    naiping/np64: {
+        target: 'weirdo/naiping/np64'
+    },
+    naiping/nphhkb: {
+        target: 'weirdo/naiping/nphhkb'
+    },
+    naiping/npminila: {
+        target: 'weirdo/naiping/npminila'
+    },
+    naked48: {
+        target: 'salicylic_acid3/naked48'
+    },
+    naked60: {
+        target: 'salicylic_acid3/naked60'
+    },
+    naked64: {
+        target: 'salicylic_acid3/naked64'
+    },
+    namecard2x4: {
+        target: 'takashiski/namecard2x4'
+    },
+    nebula12: {
+        target: 'spaceholdings/nebula12'
+    },
+    nebula68: {
+        target: 'spaceholdings/nebula68'
+    },
+    nebula68b: {
+        target: 'spaceholdings/nebula68b'
+    },
+    niu_mini: {
+        target: 'kbdfans/niu_mini'
+    },
+    nk1: {
+        target: 'novelkeys/nk1'
+    },
+    nk65: {
+        target: 'novelkeys/nk65'
+    },
+    nk87: {
+        target: 'novelkeys/nk87'
+    },
+    nknl7en: {
+        target: 'salicylic_acid3/nknl7en'
+    },
+    nknl7jp: {
+        target: 'salicylic_acid3/nknl7jp'
+    },
+    nomu30: {
+        target: 'recompile_keys/nomu30'
+    },
+    novelpad: {
+        target: 'novelkeys/novelpad'
+    },
+    ogurec: {
+        target: 'drhigsby/ogurec'
+    },
+    otaku_split/rev0: {
+        target: 'takashiski/otaku_split/rev0'
+    },
+    otaku_split/rev1: {
+        target: 'takashiski/otaku_split/rev1'
+    },
+    owl8: {
+        target: 'dailycraft/owl8'
+    },
+    packrat: {
+        target: 'drhigsby/packrat'
+    },
+    pistachio: {
+        target: 'rate/pistachio'
+    },
+    pistachio_mp: {
+        target: 'rate/pistachio_mp'
+    },
+    pistachio_pro: {
+        target: 'rate/pistachio_pro'
+    },
+    plexus75: {
+        target: 'checkerboards/plexus75'
+    },
+    pursuit40: {
+        target: 'checkerboards/pursuit40'
+    },
+    qaz: {
+        target: 'tominabox1/qaz'
+    },
+    quark: {
+        target: 'checkerboards/quark'
+    },
+    rabbit_capture_plan: {
+        target: 'kakunpc/rabbit_capture_plan'
+    },
+    rainkeeb: {
+        target: 'rainkeebs/rainkeeb'
+    },
+    reviung33: {
+        target: 'reviung/reviung33'
+    },
+    reviung34: {
+        target: 'reviung/reviung34'
+    },
+    reviung39: {
+        target: 'reviung/reviung39'
+    },
+    reviung41: {
+        target: 'reviung/reviung41'
+    },
+    reviung5: {
+        target: 'reviung/reviung5'
+    },
+    reviung53: {
+        target: 'reviung/reviung53'
+    },
+    reviung61: {
+        target: 'reviung/reviung61'
+    },
+    runner3680/3x6: {
+        target: 'omkbd/runner3680/3x6'
+    },
+    runner3680/3x7: {
+        target: 'omkbd/runner3680/3x7'
+    },
+    runner3680/3x8: {
+        target: 'omkbd/runner3680/3x8'
+    },
+    runner3680/4x6: {
+        target: 'omkbd/runner3680/4x6'
+    },
+    runner3680/4x7: {
+        target: 'omkbd/runner3680/4x7'
+    },
+    runner3680/4x8: {
+        target: 'omkbd/runner3680/4x8'
+    },
+    runner3680/5x6: {
+        target: 'omkbd/runner3680/5x6'
+    },
+    runner3680/5x6_5x8: {
+        target: 'omkbd/runner3680/5x6_5x8'
+    },
+    runner3680/5x7: {
+        target: 'omkbd/runner3680/5x7'
+    },
+    runner3680/5x8: {
+        target: 'omkbd/runner3680/5x8'
+    },
+    scarletbandana: {
+        target: 'woodkeys/scarletbandana'
+    },
+    scythe: {
+        target: 'kagizaraya/scythe'
+    },
+    seigaiha: {
+        target: 'yiancardesigns/seigaiha'
+    },
+    setta21: {
+        target: 'salicylic_acid3/setta21'
+    },
+    space_space/rev1: {
+        target: 'qpockets/space_space/rev1'
+    },
+    space_space/rev2: {
+        target: 'qpockets/space_space/rev2'
+    },
+    spiderisland/winry25tc: {
+        target: 'winry/winry25tc'
+    },
+    splitreus62: {
+        target: 'nacly/splitreus62'
+    },
+    squiggle/rev1: {
+        target: 'ibnuda/squiggle/rev1'
+    },
+    standaside: {
+        target: 'edi/standaside'
+    },
+    steal_this_keyboard: {
+        target: 'obosob/steal_this_keyboard'
+    },
+    stella: {
+        target: 'hnahkb/stella'
+    },
+    suihankey/alpha: {
+        target: 'kakunpc/suihankey/alpha'
+    },
+    suihankey/rev1: {
+        target: 'kakunpc/suihankey/rev1'
+    },
+    suihankey/split: {
+        target: 'kakunpc/suihankey/split'
+    },
+    the_ruler: {
+        target: 'maple_computing/the_ruler'
+    },
+    thedogkeyboard: {
+        target: 'kakunpc/thedogkeyboard'
+    },
+    tiger910: {
+        target: 'weirdo/tiger910'
+    },
+    treadstone32: {
+        target: 'marksard/treadstone32'
+    },
+    treadstone48/rev1: {
+        target: 'marksard/treadstone48/rev1'
+    },
+    treadstone48/rev2: {
+        target: 'marksard/treadstone48/rev2'
+    },
+    txuu: {
+        target: 'matthewdias/txuu'
+    },
+    ua62: {
+        target: 'nacly/ua62'
+    },
+    underscore33/rev1: {
+        target: 'tominabox1/underscore33/rev1'
+    },
+    underscore33/rev2: {
+        target: 'tominabox1/underscore33/rev2'
+    },
+    vn66: {
+        target: 'hnahkb/vn66'
+    },
+    wallaby: {
+        target: 'kkatano/wallaby'
+    },
+    wanten: {
+        target: 'qpockets/wanten'
+    },
+    whitefox: {
+        target: 'input_club/whitefox'
+    },
+    wings42/rev1: {
+        target: 'dailycraft/wings42/rev1'
+    },
+    wings42/rev1_extkeys: {
+        target: 'dailycraft/wings42/rev1_extkeys'
+    },
+    wings42/rev2: {
+        target: 'dailycraft/wings42/rev2'
+    },
+    yasui: {
+        target: 'rainkeebs/yasui'
+    },
+    yd60mq: {
+        target: 'ymdk/yd60mq'
+    },
+    yd68: {
+        target: 'ydkb/yd68'
+    },
+    ymd75: {
+        target: 'ymdk/ymd75'
+    },
+    ymd96: {
+        target: 'ymdk/ymd96'
+    },
+    ymdk_np21: {
+        target: 'ymdk/np21'
+    },
+    yurei: {
+        target: 'kkatano/yurei'
+    },
+    zinc: {
+        target: '25keys/zinc'
+    },
+    zinc/rev1: {
+        target: '25keys/zinc/rev1'
+    },
+    zinc/reva: {
+        target: '25keys/zinc/reva'
     }
 }

data/schemas/definitions.jsonschema

@@ -20,6 +20,10 @@
         "type": "string",
         "pattern": "^0x[0-9A-F]{4}$"
     },
+    "bcd_version": {
+        "type": "string",
+        "pattern": "^[0-9]{1,2}\\.[0-9]\\.[0-9]$"
+    },
     "text_identifier": {
         "type": "string",
         "minLength": 1,
@@ -47,6 +51,10 @@
     },
     "mcu_pin": {
         "oneOf": [
+            {
+                "type": "string",
+                "enum": ["NO_PIN"]
+            },
             {
                 "type": "string",
                 "pattern": "^[A-K]\\d{1,2}$"
@@ -70,13 +78,13 @@
     "signed_int": {
         "type": "number",
         "multipleOf": 1
-    }
+    },
     "signed_int_8": {
         "type": "number",
         "min": -127,
         "max": 127,
         "multipleOf": 1
-    }
+    },
     "string_array": {
         "type": "array",
         "items": {
@@ -97,7 +105,7 @@
         "type": "number",
         "min": 0,
         "multipleOf": 1
-    }
+    },
     "unsigned_int_8": {
         "type": "number",
         "min": 0,

data/schemas/keyboard.jsonschema

@@ -13,7 +13,7 @@
         },
         "processor": {
             "type": "string",
-            "enum": ["cortex-m0", "cortex-m0plus", "cortex-m3", "cortex-m4", "MKL26Z64", "MK20DX128", "MK20DX256", "MK66FX1M0", "STM32F042", "STM32F072", "STM32F103", "STM32F303", "STM32F401", "STM32F405", "STM32F407", "STM32F411", "STM32F446", "STM32G431", "STM32G474", "STM32L412", "STM32L422", "STM32L433", "STM32L443", "GD32VF103", "WB32F3G71", "atmega16u2", "atmega32u2", "atmega16u4", "atmega32u4", "at90usb162", "at90usb646", "at90usb647", "at90usb1286", "at90usb1287", "atmega32a", "atmega328p", "atmega328", "attiny85", "unknown"]
+            "enum": ["cortex-m0", "cortex-m0plus", "cortex-m3", "cortex-m4", "MKL26Z64", "MK20DX128", "MK20DX256", "MK66FX1M0", "STM32F042", "STM32F072", "STM32F103", "STM32F303", "STM32F401", "STM32F405", "STM32F407", "STM32F411", "STM32F446", "STM32G431", "STM32G474", "STM32L412", "STM32L422", "STM32L432", "STM32L433", "STM32L442", "STM32L443", "GD32VF103", "WB32F3G71", "atmega16u2", "atmega32u2", "atmega16u4", "atmega32u4", "at90usb162", "at90usb646", "at90usb647", "at90usb1286", "at90usb1287", "atmega32a", "atmega328p", "atmega328", "attiny85", "unknown"]
         },
         "audio": {
             "type": "object",
@@ -45,7 +45,7 @@
             "properties": {
                 "driver": {
                     "type": "string",
-                    "enum": ["AdafruitBLE", "RN42"]
+                    "enum": ["BluefruitLE", "RN42"]
                 },
                 "lto": {"type": "boolean"},
             }
@@ -57,7 +57,7 @@
         },
         "bootloader": {
             "type": "string",
-            "enum": ["atmel-dfu", "bootloadhid", "bootloadHID", "caterina", "halfkay", "kiibohd", "lufa-dfu", "lufa-ms", "micronucleus", "qmk-dfu", "qmk-hid", "stm32-dfu", "stm32duino", "gd32v-dfu", "wb32-dfu", "unknown", "usbasploader", "USBasp", "tinyuf2"],
+            "enum": ["atmel-dfu", "bootloadhid", "bootloadHID", "custom", "caterina", "halfkay", "kiibohd", "lufa-dfu", "lufa-ms", "md-boot", "qmk-dfu", "qmk-hid", "stm32-dfu", "stm32duino", "gd32v-dfu", "wb32-dfu", "unknown", "usbasploader", "USBasp", "tinyuf2"],
         },
         "bootloader_instructions": {
             "type": "string",
@@ -69,7 +69,7 @@
             "properties": {
                 "debounce_type": {
                     "type": "string",
-                    "enum": ["custom", "eager_pk", "eager_pr", "sym_defer_pk", "sym_eager_pk"]
+                    "enum": ["custom", "eager_pk", "eager_pr", "sym_defer_pk", "sym_defer_pr", "sym_eager_pk"]
                 },
                 "firmware_format": {
                     "type": "string",
@@ -320,7 +320,8 @@
             "type": "object",
             "additionalProperties": false,
             "properties": {
-                "device_ver": {"$ref": "qmk.definitions.v1#/hex_number_4d"},
+                "device_ver": {"$ref": "qmk.definitions.v1#/hex_number_4d"}, # Deprecated
+                "device_version": {"$ref": "qmk.definitions.v1#/bcd_version"},
                 "force_nkro": {"type": "boolean"},
                 "pid": {"$ref": "qmk.definitions.v1#/hex_number_4d"},
                 "vid": {"$ref": "qmk.definitions.v1#/hex_number_4d"},

data/templates/base/%(KEYBOARD)s.c

@@ -1,4 +0,0 @@
-// Copyright %(YEAR)s %(YOUR_NAME)s (@%(USER_NAME)s)
-// SPDX-License-Identifier: GPL-2.0-or-later
-
-#include "%(KEYBOARD)s.h"

data/templates/base/info.json

@@ -1,17 +0,0 @@
-{
-    "keyboard_name": "%(KEYBOARD)s",
-    "url": "",
-    "maintainer": "%(USER_NAME)s",
-    "layouts": {
-        "LAYOUT": {
-            "layout": [
-                {"label": "k00", "x": 0, "y": 0},
-                {"label": "k01", "x": 1, "y": 0},
-                {"label": "k02", "x": 2, "y": 0},
-
-                {"label": "k10", "x": 0, "y": 1, "w": 1.5},
-                {"label": "k12", "x": 1.5, "y": 1, "w": 1.5}
-            ]
-        }
-    }
-}

data/templates/base/keymaps/default/keymap.c

@@ -1,22 +0,0 @@
-// Copyright %(YEAR)s %(YOUR_NAME)s (@%(USER_NAME)s)
-// SPDX-License-Identifier: GPL-2.0-or-later
-
-#include QMK_KEYBOARD_H
-
-// Defines names for use in layer keycodes and the keymap
-enum layer_names {
-    _BASE,
-    _FN
-};
-
-const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
-    /* Base */
-    [_BASE] = LAYOUT(
-        KC_A,    KC_1,    MO(_FN),
-            KC_TAB,   KC_SPC
-    ),
-    [_FN] = LAYOUT(
-        _______, _______,  _______,
-            RESET,    XXXXXXX
-    )
-};

data/templates/base/keymaps/default/readme.md

@@ -1 +0,0 @@
-# The default keymap for %(KEYBOARD)s

data/templates/keyboard/config.h

@@ -0,0 +1,20 @@
+// Copyright %YEAR% %REAL_NAME% (@%USER_NAME%)
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+#pragma once
+
+/*
+ * 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

data/templates/keyboard/info.json

@@ -0,0 +1,25 @@
+{
+    "keyboard_name": "%KEYBOARD%",
+    "maintainer": "%USER_NAME%",
+    "manufacturer": "%REAL_NAME%",
+    "processor": "%MCU%",
+    "bootloader": "%BOOTLOADER%",
+    "diode_direction": "COL2ROW",
+    "matrix_pins": {
+        "cols": ["C2"],
+        "rows": ["D1"]
+    },
+    "usb": {
+        "vid": "0xFEED",
+        "pid": "0x0000",
+        "device_version": "1.0.0"
+    },
+    "features": {
+        "bootmagic_lite": true,
+        "command": false,
+        "console": false,
+        "extrakey": true,
+        "mousekey": true,
+        "nkro": true
+    }
+}

data/templates/keyboard/readme.md

@@ -1,20 +1,20 @@
-# %(KEYBOARD)s
+# %KEYBOARD%
 
-![%(KEYBOARD)s](imgur.com image replace me!)
+![%KEYBOARD%](imgur.com image replace me!)
 
 *A short description of the keyboard/project*
 
-* Keyboard Maintainer: [%(YOUR_NAME)s](https://github.com/%(USER_NAME)s)
+* Keyboard Maintainer: [%REAL_NAME%](https://github.com/%USER_NAME%)
 * Hardware Supported: *The PCBs, controllers supported*
 * Hardware Availability: *Links to where you can find this hardware*
 
 Make example for this keyboard (after setting up your build environment):
 
-    make %(KEYBOARD)s:default
+    make %KEYBOARD%:default
 
 Flashing example for this keyboard:
 
-    make %(KEYBOARD)s:default:flash
+    make %KEYBOARD%:default:flash
 
 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).
 

data/templates/keyboard/rules.mk

@@ -0,0 +1 @@
+# This file intentionally left blank

docs/ChangeLog/20220226.md

@@ -0,0 +1,489 @@
+# QMK Breaking Changes - 2022 February 26 Changelog
+
+## Notable Features :id=notable-features
+
+### Default USB Polling rate now 1kHz ([#15352](https://github.com/qmk/qmk_firmware/pull/15352))
+
+The default USB Polling rate has been aligned across supported platforms to now be 1ms/1kHz.
+
+Something something *Lets go gamers!*
+
+### Split support for pointing devices ([#15304](https://github.com/qmk/qmk_firmware/pull/15304))
+
+Pointing devices can now be shared across a split keyboard with support for a single pointing device or a pointing device on each side.
+
+See the [Pointing Device](feature_pointing_device.md) documentation for further configuration options.
+
+## Changes Requiring User Action :id=changes-requiring-user-action
+
+### Legacy macro and action_function system removed ([#16025](https://github.com/qmk/qmk_firmware/pull/16025))
+
+The long time deprecated `MACRO()` and `action_get_macro` methods have been removed. Where possible, existing usages have been migrated over to core [Macros](feature_macros.md).
+
+### Create a build error if no bootloader is specified ([#16181](https://github.com/qmk/qmk_firmware/pull/16181))
+
+Bootloader configuration is no longer assumed. Keyboards must now set either:
+
+* `BOOTLOADER` within `rules.mk`
+* `bootloader` within `info.json`
+
+### Rename `AdafruitBLE` to `BluefruitLE` ([#16127](https://github.com/qmk/qmk_firmware/pull/16127))
+
+In preparation of future bluetooth work, the `AdafruitBLE` integration has been renamed to allow potential for any other Adafruit BLE products. 
+
+### Updated Keyboard Codebases :id=updated-keyboard-codebases
+
+The following keyboards have had their source moved within QMK:
+
+| Old Keyboard Name          | New Keyboard Name                  |
+|----------------------------|------------------------------------|
+|  6ball                     |  maple_computing/6ball             |
+|  7skb                      |  salicylic_acid3/7skb              |
+|  7splus                    |  salicylic_acid3/7splus            |
+|  acr60                     |  mechkeys/acr60                    |
+|  adalyn                    |  tominabox1/adalyn                 |
+|  ajisai74                  |  salicylic_acid3/ajisai74          |
+|  aleth42                   |  25keys/aleth42                    |
+|  alicia_cook               |  ibnuda/alicia_cook                |
+|  allison_numpad            |  prototypist/allison_numpad        |
+|  allison                   |  prototypist/allison               |
+|  alu84                     |  mechkeys/alu84                    |
+|  angel17                   |  kakunpc/angel17                   |
+|  angel64/alpha             |  kakunpc/angel64/alpha             |
+|  angel64/rev1              |  kakunpc/angel64/rev1              |
+|  arch_36                   |  obosob/arch_36                    |
+|  bakeneko60                |  kkatano/bakeneko60                |
+|  bakeneko65/rev2           |  kkatano/bakeneko65/rev2           |
+|  bakeneko65/rev3           |  kkatano/bakeneko65/rev3           |
+|  bakeneko80                |  kkatano/bakeneko80                |
+|  barleycorn                |  yiancardesigns/barleycorn         |
+|  bat43/rev1                |  dailycraft/bat43/rev1             |
+|  bat43/rev2                |  dailycraft/bat43/rev2             |
+|  bigseries/1key            |  woodkeys/bigseries/1key           |
+|  bigseries/2key            |  woodkeys/bigseries/2key           |
+|  bigseries/3key            |  woodkeys/bigseries/3key           |
+|  bigseries/4key            |  woodkeys/bigseries/4key           |
+|  bkf                       |  drhigsby/bkf                      |
+|  business_card/alpha       |  kakunpc/business_card/alpha       |
+|  business_card/beta        |  kakunpc/business_card/beta        |
+|  butterstick               |  gboards/butterstick               |
+|  c39                       |  maple_computing/c39               |
+|  cassette42                |  25keys/cassette42                 |
+|  chidori                   |  kagizaraya/chidori                |
+|  chili                     |  ydkb/chili                        |
+|  chimera_ergo              |  glenpickle/chimera_ergo           |
+|  chimera_ls                |  glenpickle/chimera_ls             |
+|  chimera_ortho             |  glenpickle/chimera_ortho          |
+|  chimera_ortho_plus        |  glenpickle/chimera_ortho_plus     |
+|  choco60                   |  recompile_keys/choco60            |
+|  choc_taro                 |  kakunpc/choc_taro                 |
+|  christmas_tree            |  maple_computing/christmas_tree    |
+|  claw44/rev1               |  dailycraft/claw44/rev1            |
+|  cocoa40                   |  recompile_keys/cocoa40            |
+|  comet46                   |  satt/comet46                      |
+|  cu24                      |  capsunlocked/cu24                 |
+|  cu75                      |  capsunlocked/cu75                 |
+|  cu80                      |  capsunlocked/cu80/v1              |
+|  delilah                   |  rainkeebs/delilah                 |
+|  diverge3                  |  unikeyboard/diverge3              |
+|  divergetm2                |  unikeyboard/divergetm2            |
+|  dozen0                    |  yynmt/dozen0                      |
+|  dubba175                  |  drhigsby/dubba175                 |
+|  eggman                    |  qpockets/eggman                   |
+|  ergo42                    |  biacco42/ergo42                   |
+|  ergoarrows                |  salicylic_acid3/ergoarrows        |
+|  ergodash/mini             |  omkbd/ergodash/mini               |
+|  ergodash/rev1             |  omkbd/ergodash/rev1               |
+|  ergodox_infinity          |  input_club/ergodox_infinity       |
+|  ergotaco                  |  gboards/ergotaco                  |
+|  espectro                  |  mechkeys/espectro                 |
+|  felix                     |  unikeyboard/felix                 |
+|  four_banger               |  bpiphany/four_banger              |
+|  freyr                     |  hnahkb/freyr                      |
+|  geminate60                |  weirdo/geminate60                 |
+|  georgi                    |  gboards/georgi                    |
+|  gergo                     |  gboards/gergo                     |
+|  getta25                   |  salicylic_acid3/getta25           |
+|  gingham                   |  yiancardesigns/gingham            |
+|  gurindam                  |  ibnuda/gurindam                   |
+|  halberd                   |  kagizaraya/halberd                |
+|  hecomi/alpha              |  takashiski/hecomi/alpha           |
+|  hid_liber                 |  bpiphany/hid_liber                |
+|  id67/default_rgb          |  idobao/id67/default_rgb           |
+|  id67/rgb                  |  idobao/id67/rgb                   |
+|  id80                      |  idobao/id80/v1                    |
+|  id87                      |  idobao/id87/v1                    |
+|  idobo                     |  idobao/id75/v1                    |
+|  infinity60                |  input_club/infinity60             |
+|  ivy/rev1                  |  maple_computing/ivy/rev1          |
+|  jisplit89                 |  salicylic_acid3/jisplit89         |
+|  jnao                      |  maple_computing/jnao              |
+|  just60                    |  ydkb/just60                       |
+|  kagamidget                |  yynmt/kagamidget                  |
+|  kelowna/rgb64             |  weirdo/kelowna/rgb64              |
+|  kprepublic/bm65hsrgb_iso  |  kprepublic/bm65hsrgb_iso/rev1     |
+|  kprepublic/bm68hsrgb      |  kprepublic/bm68hsrgb/rev1         |
+|  k_type                    |  input_club/k_type                 |
+|  latin17rgb                |  latincompass/latin17rgb           |
+|  latin47ble                |  latincompass/latin47ble           |
+|  latin60rgb                |  latincompass/latin60rgb           |
+|  latin64ble                |  latincompass/latin64ble           |
+|  latin6rgb                 |  latincompass/latin6rgb            |
+|  latinpadble               |  latincompass/latinpadble          |
+|  latinpad                  |  latincompass/latinpad             |
+|  launchpad/rev1            |  maple_computing/launchpad/rev1    |
+|  lck75                     |  lyso1/lck75                       |
+|  le_chiffre                |  tominabox1/le_chiffre             |
+|  lefishe                   |  lyso1/lefishe                     |
+|  lets_split_eh/eh          |  maple_computing/lets_split_eh/eh  |
+|  ls_60                     |  weirdo/ls_60                      |
+|  m3n3van                   |  matthewdias/m3n3van               |
+|  mechmini/v1               |  mechkeys/mechmini/v1              |
+|  mechmini/v2               |  mechkeys/mechmini/v2              |
+|  meira                     |  woodkeys/meira                    |
+|  meishi2                   |  biacco42/meishi2                  |
+|  meishi                    |  biacco42/meishi                   |
+|  minidox/rev1              |  maple_computing/minidox/rev1      |
+|  minim                     |  matthewdias/minim                 |
+|  mio                       |  recompile_keys/mio                |
+|  model_v                   |  matthewdias/model_v               |
+|  montex                    |  idobao/montex/v1                  |
+|  nafuda                    |  salicylic_acid3/nafuda            |
+|  naiping/np64              |  weirdo/naiping/np64               |
+|  naiping/nphhkb            |  weirdo/naiping/nphhkb             |
+|  naiping/npminila          |  weirdo/naiping/npminila           |
+|  naked48                   |  salicylic_acid3/naked48           |
+|  naked60                   |  salicylic_acid3/naked60           |
+|  naked64                   |  salicylic_acid3/naked64           |
+|  namecard2x4               |  takashiski/namecard2x4            |
+|  nebula12                  |  spaceholdings/nebula12            |
+|  nebula68b                 |  spaceholdings/nebula68b           |
+|  nebula68                  |  spaceholdings/nebula68            |
+|  niu_mini                  |  kbdfans/niu_mini                  |
+|  nk1                       |  novelkeys/nk1                     |
+|  nk65                      |  novelkeys/nk65                    |
+|  nk87                      |  novelkeys/nk87                    |
+|  nknl7en                   |  salicylic_acid3/nknl7en           |
+|  nknl7jp                   |  salicylic_acid3/nknl7jp           |
+|  nomu30                    |  recompile_keys/nomu30             |
+|  novelpad                  |  novelkeys/novelpad                |
+|  ogurec                    |  drhigsby/ogurec                   |
+|  otaku_split/rev0          |  takashiski/otaku_split/rev0       |
+|  otaku_split/rev1          |  takashiski/otaku_split/rev1       |
+|  owl8                      |  dailycraft/owl8                   |
+|  packrat                   |  drhigsby/packrat                  |
+|  pistachio_mp              |  rate/pistachio_mp                 |
+|  pistachio_pro             |  rate/pistachio_pro                |
+|  pistachio                 |  rate/pistachio                    |
+|  plexus75                  |  checkerboards/plexus75            |
+|  pursuit40                 |  checkerboards/pursuit40           |
+|  qaz                       |  tominabox1/qaz                    |
+|  quark                     |  checkerboards/quark               |
+|  rabbit_capture_plan       |  kakunpc/rabbit_capture_plan       |
+|  rainkeeb                  |  rainkeebs/rainkeeb                |
+|  reviung33                 |  reviung/reviung33                 |
+|  reviung34                 |  reviung/reviung34                 |
+|  reviung39                 |  reviung/reviung39                 |
+|  reviung41                 |  reviung/reviung41                 |
+|  reviung53                 |  reviung/reviung53                 |
+|  reviung5                  |  reviung/reviung5                  |
+|  reviung61                 |  reviung/reviung61                 |
+|  runner3680/3x6            |  omkbd/runner3680/3x6              |
+|  runner3680/3x7            |  omkbd/runner3680/3x7              |
+|  runner3680/3x8            |  omkbd/runner3680/3x8              |
+|  runner3680/4x6            |  omkbd/runner3680/4x6              |
+|  runner3680/4x7            |  omkbd/runner3680/4x7              |
+|  runner3680/4x8            |  omkbd/runner3680/4x8              |
+|  runner3680/5x6_5x8        |  omkbd/runner3680/5x6_5x8          |
+|  runner3680/5x6            |  omkbd/runner3680/5x6              |
+|  runner3680/5x7            |  omkbd/runner3680/5x7              |
+|  runner3680/5x8            |  omkbd/runner3680/5x8              |
+|  scarletbandana            |  woodkeys/scarletbandana           |
+|  scythe                    |  kagizaraya/scythe                 |
+|  seigaiha                  |  yiancardesigns/seigaiha           |
+|  setta21                   |  salicylic_acid3/setta21           |
+|  space_space/rev1          |  qpockets/space_space/rev1         |
+|  space_space/rev2          |  qpockets/space_space/rev2         |
+|  spiderisland/winry25tc    |  winry/winry25tc                   |
+|  splitreus62               |  nacly/splitreus62                 |
+|  squiggle/rev1             |  ibnuda/squiggle/rev1              |
+|  standaside                |  edi/standaside                    |
+|  steal_this_keyboard       |  obosob/steal_this_keyboard        |
+|  stella                    |  hnahkb/stella                     |
+|  suihankey/alpha           |  kakunpc/suihankey/alpha           |
+|  suihankey/rev1            |  kakunpc/suihankey/rev1            |
+|  suihankey/split           |  kakunpc/suihankey/split           |
+|  thedogkeyboard            |  kakunpc/thedogkeyboard            |
+|  the_ruler                 |  maple_computing/the_ruler         |
+|  tiger910                  |  weirdo/tiger910                   |
+|  treadstone32              |  marksard/treadstone32             |
+|  treadstone48/rev1         |  marksard/treadstone48/rev1        |
+|  treadstone48/rev2         |  marksard/treadstone48/rev2        |
+|  txuu                      |  matthewdias/txuu                  |
+|  ua62                      |  nacly/ua62                        |
+|  underscore33/rev1         |  tominabox1/underscore33/rev1      |
+|  underscore33/rev2         |  tominabox1/underscore33/rev2      |
+|  vn66                      |  hnahkb/vn66                       |
+|  wallaby                   |  kkatano/wallaby                   |
+|  wanten                    |  qpockets/wanten                   |
+|  whitefox                  |  input_club/whitefox               |
+|  wings42/rev1              |  dailycraft/wings42/rev1           |
+|  wings42/rev1_extkeys      |  dailycraft/wings42/rev1_extkeys   |
+|  wings42/rev2              |  dailycraft/wings42/rev2           |
+|  yasui                     |  rainkeebs/yasui                   |
+|  yd60mq                    |  ymdk/yd60mq                       |
+|  yd68                      |  ydkb/yd68                         |
+|  ymd75                     |  ymdk/ymd75                        |
+|  ymd96                     |  ymdk/ymd96                        |
+|  ymdk_np21                 |  ymdk/np21                         |
+|  yurei                     |  kkatano/yurei                     |
+|  zinc                      |  25keys/zinc                       |
+|  zinc/rev1                 |  25keys/zinc/rev1                  |
+|  zinc/reva                 |  25keys/zinc/reva                  |
+
+## Notable core changes :id=notable-core
+
+### New MCU Support :id=new-mcu-support
+
+Building on previous cycles, QMK firmware picked up support for a couple extra MCU variants:
+
+* STM32L432
+* STM32L442
+
+### New Drivers
+
+QMK now has core-supplied support for the following device peripherals:
+
+#### LED
+
+* IS31FL3742A
+* IS31FL3743A
+* IS31FL3745
+* IS31FL3746A
+
+#### GPIO
+
+* SN74x138
+* mcp23018
+
+---
+
+## Full changelist
+
+Core:
+* Initial pass at data driven new-keyboard subcommand ([#12795](https://github.com/qmk/qmk_firmware/pull/12795))
+* Don't send keyboard reports that propagate no changes to the host ([#14065](https://github.com/qmk/qmk_firmware/pull/14065))
+* Custom matrix lite support for split keyboards ([#14674](https://github.com/qmk/qmk_firmware/pull/14674))
+* Add sym_defer_pr debouncer type ([#14948](https://github.com/qmk/qmk_firmware/pull/14948))
+* Add RGB matrix & LED Matrix support for IS31FL3742A, IS31FL3743A, IS31FL3745, IS31FL3746A ([#14989](https://github.com/qmk/qmk_firmware/pull/14989))
+* New combo configuration options ([#15083](https://github.com/qmk/qmk_firmware/pull/15083))
+* IS31FL3733 driver for LED Matrix ([#15088](https://github.com/qmk/qmk_firmware/pull/15088))
+* Add open-drain GPIO support. ([#15282](https://github.com/qmk/qmk_firmware/pull/15282))
+* Make (un)register code functions weak ([#15285](https://github.com/qmk/qmk_firmware/pull/15285))
+* Split support for pointing devices. ([#15304](https://github.com/qmk/qmk_firmware/pull/15304))
+* Added cancel_key_lock function ([#15321](https://github.com/qmk/qmk_firmware/pull/15321))
+* Remove matrix_is_modified() and debounce_is_active() ([#15349](https://github.com/qmk/qmk_firmware/pull/15349))
+* Change default USB Polling rate to 1kHz ([#15352](https://github.com/qmk/qmk_firmware/pull/15352))
+* Implement MAGIC_TOGGLE_CONTROL_CAPSLOCK ([#15368](https://github.com/qmk/qmk_firmware/pull/15368))
+* Tidy up existing i2c_master implementations ([#15376](https://github.com/qmk/qmk_firmware/pull/15376))
+* Generalize Unicode defines ([#15409](https://github.com/qmk/qmk_firmware/pull/15409))
+* Added external spi flash driver. ([#15419](https://github.com/qmk/qmk_firmware/pull/15419))
+* Remove Deprecated USB Polling comment from vusb.c ([#15420](https://github.com/qmk/qmk_firmware/pull/15420))
+* Expand rotational range for PMW3360 Optical Sensor ([#15431](https://github.com/qmk/qmk_firmware/pull/15431))
+* ChibiOS SVN mirror script update ([#15435](https://github.com/qmk/qmk_firmware/pull/15435))
+* Refactor `bootloader_jump()` implementations ([#15450](https://github.com/qmk/qmk_firmware/pull/15450))
+* added missing audio_off_user() callback ([#15457](https://github.com/qmk/qmk_firmware/pull/15457))
+* Migrate serial_uart usages to UART driver ([#15479](https://github.com/qmk/qmk_firmware/pull/15479))
+* Migrate RN42 to UART driver and refactor ([#15492](https://github.com/qmk/qmk_firmware/pull/15492))
+* pwm3360 driver cleanup and diff reduction to adns9800 ([#15559](https://github.com/qmk/qmk_firmware/pull/15559))
+* Advanced deferred_exec for core-side code. ([#15579](https://github.com/qmk/qmk_firmware/pull/15579))
+* Adjust tap_code16 to account for TAP_HOLD_CAPS_DELAY ([#15635](https://github.com/qmk/qmk_firmware/pull/15635))
+* Slight tidy up of keyboard task loop ([#15725](https://github.com/qmk/qmk_firmware/pull/15725))
+* Unify the key up/down behaviour of RGB keycodes ([#15730](https://github.com/qmk/qmk_firmware/pull/15730))
+* Add PMW3389 optical sensor Support (Updated) ([#15740](https://github.com/qmk/qmk_firmware/pull/15740))
+* ChibiOS: add support for HID Programmable Buttons ([#15787](https://github.com/qmk/qmk_firmware/pull/15787))
+* ChibiOS: shorten USB disconnect state on boot to 50ms ([#15805](https://github.com/qmk/qmk_firmware/pull/15805))
+* Add init function to clear previous matrix effect ([#15815](https://github.com/qmk/qmk_firmware/pull/15815))
+* Optimize initialization of PMW3360 Sensor ([#15821](https://github.com/qmk/qmk_firmware/pull/15821))
+* Add Pixel Flow RGB matrix effect ([#15829](https://github.com/qmk/qmk_firmware/pull/15829))
+* PMW3389 Revert Firmware load during Initilization ([#15859](https://github.com/qmk/qmk_firmware/pull/15859))
+* Combo `TAP_CODE_DELAY` and `clear_weak_mods` ([#15866](https://github.com/qmk/qmk_firmware/pull/15866))
+* Relocate matrix_scan_quantum tasks ([#15882](https://github.com/qmk/qmk_firmware/pull/15882))
+* Adjust mouse key defaults ([#15883](https://github.com/qmk/qmk_firmware/pull/15883))
+* RGB Matrix: Reload from EEPROM ([#15923](https://github.com/qmk/qmk_firmware/pull/15923))
+* Enable a default task throttle for split pointing. ([#15925](https://github.com/qmk/qmk_firmware/pull/15925))
+* Move mcp23018 driver to core ([#15944](https://github.com/qmk/qmk_firmware/pull/15944))
+* Relocate matrix_init_quantum content ([#15953](https://github.com/qmk/qmk_firmware/pull/15953))
+* Align location of some host led logic ([#15954](https://github.com/qmk/qmk_firmware/pull/15954))
+* Rename some Quantum keycodes ([#15968](https://github.com/qmk/qmk_firmware/pull/15968))
+* Migrate more makefile utilities to builddefs sub-directory ([#16002](https://github.com/qmk/qmk_firmware/pull/16002))
+* Various Makefile optimisations ([#16015](https://github.com/qmk/qmk_firmware/pull/16015))
+* Add support for STM32L432, STM32L442. ([#16016](https://github.com/qmk/qmk_firmware/pull/16016))
+* EEPROM refactor: remove `eeprom_teensy.c` by default, use transient instead ([#16020](https://github.com/qmk/qmk_firmware/pull/16020))
+* Deprecate Split Transaction status field ([#16023](https://github.com/qmk/qmk_firmware/pull/16023))
+* Rip out old macro and action_function system ([#16025](https://github.com/qmk/qmk_firmware/pull/16025))
+* Add a script that simplifies running commands under docker. ([#16028](https://github.com/qmk/qmk_firmware/pull/16028))
+* Add support for Q-series on the ckled2001 LED driver ([#16051](https://github.com/qmk/qmk_firmware/pull/16051))
+* Remove unused suspend_idle ([#16063](https://github.com/qmk/qmk_firmware/pull/16063))
+* Initial migration of suspend callbacks ([#16067](https://github.com/qmk/qmk_firmware/pull/16067))
+* Add layout change callbacks to VIA ([#16087](https://github.com/qmk/qmk_firmware/pull/16087))
+* Rename `AdafruitBLE` to `BluefruitLE` ([#16127](https://github.com/qmk/qmk_firmware/pull/16127))
+* Update outputselect to use platform connected state API ([#16185](https://github.com/qmk/qmk_firmware/pull/16185))
+* Remove default pointing device driver. ([#16190](https://github.com/qmk/qmk_firmware/pull/16190))
+* Add SN74x138 demultiplexer driver ([#16217](https://github.com/qmk/qmk_firmware/pull/16217))
+* Standardise error output. ([#16220](https://github.com/qmk/qmk_firmware/pull/16220))
+* Followup to #16220, more test error output. ([#16221](https://github.com/qmk/qmk_firmware/pull/16221))
+* Misc size regression script improvements. ([#16268](https://github.com/qmk/qmk_firmware/pull/16268))
+* Align existing pca9555 driver to better match mcp23018 API ([#16277](https://github.com/qmk/qmk_firmware/pull/16277))
+* Size checks print out target firmware file instead ([#16290](https://github.com/qmk/qmk_firmware/pull/16290))
+
+CLI:
+* `develop` changelog generator: use the PR title instead ([#15537](https://github.com/qmk/qmk_firmware/pull/15537))
+* `develop` changelog generator: skip code formatting in listing ([#16215](https://github.com/qmk/qmk_firmware/pull/16215))
+
+Keyboards:
+* Durgod: Increase scan rate by using wait_us timer ([#14091](https://github.com/qmk/qmk_firmware/pull/14091))
+* Add another GMMK Pro ANSI Keymap with custom RGB. ([#14243](https://github.com/qmk/qmk_firmware/pull/14243))
+* Parse USB device version BCD ([#14580](https://github.com/qmk/qmk_firmware/pull/14580))
+* Add vitoni keymap for GMMK Pro (ISO) ([#15006](https://github.com/qmk/qmk_firmware/pull/15006))
+* Move bm65hsrgb_iso and bm68hsrgb to rev1/ to prepare for updates to the boards ([#15132](https://github.com/qmk/qmk_firmware/pull/15132))
+* Convert ergoinu to SPLIT_KEYBOARD ([#15305](https://github.com/qmk/qmk_firmware/pull/15305))
+* Convert not_so_minidox to SPLIT_KEYBOARD ([#15306](https://github.com/qmk/qmk_firmware/pull/15306))
+* Added new handwired keyboard Wakizashi 40 ([#15336](https://github.com/qmk/qmk_firmware/pull/15336))
+* Convert ai03/orbit to SPLIT_KEYBOARD ([#15340](https://github.com/qmk/qmk_firmware/pull/15340))
+* Remove manual enable of LTO within user keymaps ([#15378](https://github.com/qmk/qmk_firmware/pull/15378))
+* Move to organization folder ([#15481](https://github.com/qmk/qmk_firmware/pull/15481))
+* Convert some more boards to Matrix Lite ([#15489](https://github.com/qmk/qmk_firmware/pull/15489))
+* Organize Reviung boards into a directory ([#15636](https://github.com/qmk/qmk_firmware/pull/15636))
+* move winry25tc to winry/ ([#15637](https://github.com/qmk/qmk_firmware/pull/15637))
+* Rename ymdk_np21 to np21 + move to ymdk vendor folder ([#15641](https://github.com/qmk/qmk_firmware/pull/15641))
+* move ymd96 to ymdk vendor folder ([#15643](https://github.com/qmk/qmk_firmware/pull/15643))
+* move ymd75 to ymdk vendor folder ([#15645](https://github.com/qmk/qmk_firmware/pull/15645))
+* move yd60mq to ymdk vendor folder ([#15647](https://github.com/qmk/qmk_firmware/pull/15647))
+* rename idobo to idobao/id75, move to vendor folder ([#15661](https://github.com/qmk/qmk_firmware/pull/15661))
+* move ID67 to IDOBAO vendor folder ([#15662](https://github.com/qmk/qmk_firmware/pull/15662))
+* move ID80 to IDOBAO vendor folder ([#15665](https://github.com/qmk/qmk_firmware/pull/15665))
+* move ID87 to IDOBAO vendor folder ([#15667](https://github.com/qmk/qmk_firmware/pull/15667))
+* move montex to IDOBAO vendor folder ([#15668](https://github.com/qmk/qmk_firmware/pull/15668))
+* move @yangdigi 's keyboards to a YDKB folder ([#15681](https://github.com/qmk/qmk_firmware/pull/15681))
+* move @kkatano 's keyboards to kkatano user folder ([#15684](https://github.com/qmk/qmk_firmware/pull/15684))
+* Sol 3 Keyboard from RGBKB ([#15687](https://github.com/qmk/qmk_firmware/pull/15687))
+* move cu24, cu75, cu80/v1 into capsunlocked folder ([#15758](https://github.com/qmk/qmk_firmware/pull/15758))
+* move mechkeys keyboards into the mechkeys/ vendor folder ([#15760](https://github.com/qmk/qmk_firmware/pull/15760))
+* move @lyso1 's boards into lyso1/ ([#15767](https://github.com/qmk/qmk_firmware/pull/15767))
+* move prototypist boards into vendor folder ([#15780](https://github.com/qmk/qmk_firmware/pull/15780))
+* move @yiancar 's boards into yiancardesigns/ ([#15781](https://github.com/qmk/qmk_firmware/pull/15781))
+* move novelkeys keyboards to vendor folder ([#15783](https://github.com/qmk/qmk_firmware/pull/15783))
+* move @weirdo-f 's keyboards into weirdo/ ([#15785](https://github.com/qmk/qmk_firmware/pull/15785))
+* move @marksard 's boards to marksard/ ([#15786](https://github.com/qmk/qmk_firmware/pull/15786))
+* move input club keyboards into vendor folder ([#15788](https://github.com/qmk/qmk_firmware/pull/15788))
+* move @monksoffunk 's boards into 25keys/ ([#15789](https://github.com/qmk/qmk_firmware/pull/15789))
+* move @Salicylic-acid3 's keyboards to salicylic-acid3/ ([#15791](https://github.com/qmk/qmk_firmware/pull/15791))
+* move @rainkeebs 's keyboards to rainkeebs/ ([#15797](https://github.com/qmk/qmk_firmware/pull/15797))
+* move standaside into edi/ ([#15798](https://github.com/qmk/qmk_firmware/pull/15798))
+* move @obosob 's boards into obosob/ ([#15799](https://github.com/qmk/qmk_firmware/pull/15799))
+* move @nacly 's boards to nacly/ ([#15801](https://github.com/qmk/qmk_firmware/pull/15801))
+* move @kakunpc 's keebs into kakunpc/ ([#15814](https://github.com/qmk/qmk_firmware/pull/15814))
+* move @qpocket 's keyboards to qpocket/ ([#15827](https://github.com/qmk/qmk_firmware/pull/15827))
+* BDN9 keymap ([#15924](https://github.com/qmk/qmk_firmware/pull/15924))
+* move @matthewdias 's keebs into matthewdias/ ([#15991](https://github.com/qmk/qmk_firmware/pull/15991))
+* move id80 and id75 to v1 to accommodate for id75 v2 and id80 v3 ([#15992](https://github.com/qmk/qmk_firmware/pull/15992))
+* Remove `action_function()` from LFKeyboards boards ([#15993](https://github.com/qmk/qmk_firmware/pull/15993))
+* move @latincompass (aka @18438880 , @haierwangwei2005)'s boards to /latincompass ([#16039](https://github.com/qmk/qmk_firmware/pull/16039))
+* move g heavy industry boards into /gboards ([#16040](https://github.com/qmk/qmk_firmware/pull/16040))
+* move @drhigsby 's boards into /drhigsby ([#16041](https://github.com/qmk/qmk_firmware/pull/16041))
+* More keyboard rules.mk cleanups ([#16044](https://github.com/qmk/qmk_firmware/pull/16044))
+* move @That-Canadian 's boards into /maple_computing ([#16050](https://github.com/qmk/qmk_firmware/pull/16050))
+* move @takai 's keyboards into /recompile_keys ([#16053](https://github.com/qmk/qmk_firmware/pull/16053))
+* move @satt99 's comet46 to satt/ ([#16059](https://github.com/qmk/qmk_firmware/pull/16059))
+* move @ka2hiro 's boards into /kagizaraya ([#16070](https://github.com/qmk/qmk_firmware/pull/16070))
+* move @GlenPickle 's chimera* boards into a folder ([#16072](https://github.com/qmk/qmk_firmware/pull/16072))
+* move @yynmt 's boards into /yynmt ([#16075](https://github.com/qmk/qmk_firmware/pull/16075))
+* move @Biacco42 's keebs into /biacco42 ([#16080](https://github.com/qmk/qmk_firmware/pull/16080))
+* move unikeyboard boards to /unikeyboard ([#16081](https://github.com/qmk/qmk_firmware/pull/16081))
+* move four_banger to bpiphany ([#16082](https://github.com/qmk/qmk_firmware/pull/16082))
+* move @takashiski 's keebs into /takashiski ([#16089](https://github.com/qmk/qmk_firmware/pull/16089))
+* move hid_liber to /bpiphany ([#16091](https://github.com/qmk/qmk_firmware/pull/16091))
+* move spaceholdings boards into /spaceholdings ([#16096](https://github.com/qmk/qmk_firmware/pull/16096))
+* move @7-rate 's keebs to /rate ([#16099](https://github.com/qmk/qmk_firmware/pull/16099))
+* move @npspears 's boards into /checkerboards ([#16100](https://github.com/qmk/qmk_firmware/pull/16100))
+* move @vuhopkep 's keebs into /hnahkb ([#16102](https://github.com/qmk/qmk_firmware/pull/16102))
+* move @ibnuda 's keebs into /ibnuda ([#16108](https://github.com/qmk/qmk_firmware/pull/16108))
+* move @tominabox1 's keebs into /tominabox1 ([#16109](https://github.com/qmk/qmk_firmware/pull/16109))
+* move niu_mini to /kbdfans ([#16112](https://github.com/qmk/qmk_firmware/pull/16112))
+* move woodkeys.click keyboards to /woodkeys ([#16113](https://github.com/qmk/qmk_firmware/pull/16113))
+* move @omkbd 's boards to /omkbd ([#16116](https://github.com/qmk/qmk_firmware/pull/16116))
+* Overhaul Tractyl Manuform ([#16134](https://github.com/qmk/qmk_firmware/pull/16134))
+* Reduce firmware size for dztech/dz60rgb_wkl/v2_1:via ([#16254](https://github.com/qmk/qmk_firmware/pull/16254))
+
+Keyboard fixes:
+* Fix build failure for UT47 ([#15483](https://github.com/qmk/qmk_firmware/pull/15483))
+* Update grs_70ec to use newer custom matrix ([#15609](https://github.com/qmk/qmk_firmware/pull/15609))
+* fix compiler issue with Tractyl Manuform 4x6 ([#15646](https://github.com/qmk/qmk_firmware/pull/15646))
+* Fix CI. ([#15828](https://github.com/qmk/qmk_firmware/pull/15828))
+* Yet another bad `DEFAULT_FOLDER` fix. ([#15904](https://github.com/qmk/qmk_firmware/pull/15904))
+* Fix build failures for `mschwingen/modelm` ([#15987](https://github.com/qmk/qmk_firmware/pull/15987))
+* `rocketboard_16`: Fix mismatched LUT sizes ([#15997](https://github.com/qmk/qmk_firmware/pull/15997))
+* Fix erroneous SRC for Clueboard 66 hotswap ([#16007](https://github.com/qmk/qmk_firmware/pull/16007))
+* Fix handwired/ms_sculpt_mobile default keymap ([#16032](https://github.com/qmk/qmk_firmware/pull/16032))
+* Re-org Hillside folders as new model prep. Fix default keymap. ([#16128](https://github.com/qmk/qmk_firmware/pull/16128))
+* Fix up default folder locations. Again. ([#16135](https://github.com/qmk/qmk_firmware/pull/16135))
+* Sol3 rgb fix ([#16157](https://github.com/qmk/qmk_firmware/pull/16157))
+* Add missing `BOOTLOADER` for a handful of boards ([#16225](https://github.com/qmk/qmk_firmware/pull/16225))
+* Remove half implemented micronucleus bootloader support ([#16252](https://github.com/qmk/qmk_firmware/pull/16252))
+* Fixup bootloaders. ([#16256](https://github.com/qmk/qmk_firmware/pull/16256))
+* Fix idobao/id80/v3 compilation errors ([#16280](https://github.com/qmk/qmk_firmware/pull/16280))
+* Remove parent-relative paths from keyboards. ([#16282](https://github.com/qmk/qmk_firmware/pull/16282))
+* Bodge for helix build failures ([#16376](https://github.com/qmk/qmk_firmware/pull/16376))
+
+Others:
+* Add a clarification to an error message ([#15207](https://github.com/qmk/qmk_firmware/pull/15207))
+* Clang-format tweaks ([#15906](https://github.com/qmk/qmk_firmware/pull/15906))
+* Add example implementations for compatible MCUs list ([#15935](https://github.com/qmk/qmk_firmware/pull/15935))
+* Add version.h to gitignore ([#16222](https://github.com/qmk/qmk_firmware/pull/16222))
+* Update keyboard mapping for all moved boards this cycle ([#16312](https://github.com/qmk/qmk_firmware/pull/16312))
+* Align docs to new-keyboard behaviour ([#16357](https://github.com/qmk/qmk_firmware/pull/16357))
+* Align new-keyboard with recent schema updates ([#16378](https://github.com/qmk/qmk_firmware/pull/16378))
+
+Bugs:
+* Fixes potential wpm sampling overflow, along with code comment fixes ([#15277](https://github.com/qmk/qmk_firmware/pull/15277))
+* Add missing define for unicode common ([#15416](https://github.com/qmk/qmk_firmware/pull/15416))
+* Fix for SPI write timing in PMW3360 driver ([#15519](https://github.com/qmk/qmk_firmware/pull/15519))
+* Documentation Typo fix ([#15538](https://github.com/qmk/qmk_firmware/pull/15538))
+* fix a typo ([#15557](https://github.com/qmk/qmk_firmware/pull/15557))
+* Fix avr serial compile ([#15589](https://github.com/qmk/qmk_firmware/pull/15589))
+* More AVR GPIO compilation fixes. ([#15592](https://github.com/qmk/qmk_firmware/pull/15592))
+* Fix bug and code regression for Split Common ([#15603](https://github.com/qmk/qmk_firmware/pull/15603))
+* Include missing string.h include in split ([#15606](https://github.com/qmk/qmk_firmware/pull/15606))
+* Fixes for bootloader refactor build failures ([#15638](https://github.com/qmk/qmk_firmware/pull/15638))
+* Update pmw3360 driver after reading the datasheet top to bottom. Fix some outdated refs. ([#15682](https://github.com/qmk/qmk_firmware/pull/15682))
+* Fix split pointing for analog joystick ([#15691](https://github.com/qmk/qmk_firmware/pull/15691))
+* Fix broken bootloader builds in develop. ([#15880](https://github.com/qmk/qmk_firmware/pull/15880))
+* Fix optical sensor firmware upload ([#15919](https://github.com/qmk/qmk_firmware/pull/15919))
+* Pass in the keyrecord_t of the dual-role/tapping key when calling per-key tap hold functions ([#15938](https://github.com/qmk/qmk_firmware/pull/15938))
+* fixed typo in orange HSV colors decalartion ([#15976](https://github.com/qmk/qmk_firmware/pull/15976))
+* Fix hack for chibiOS reset name ([#15984](https://github.com/qmk/qmk_firmware/pull/15984))
+* Fix right side ws2812 leds having two indices ([#15985](https://github.com/qmk/qmk_firmware/pull/15985))
+* Workaround in Makefile for recursive rule matching ([#15988](https://github.com/qmk/qmk_firmware/pull/15988))
+* Fix BACKLIGHT_CAPS_LOCK warning ([#15999](https://github.com/qmk/qmk_firmware/pull/15999))
+* Fix compilation issues for led indicators ([#16001](https://github.com/qmk/qmk_firmware/pull/16001))
+* ChibiOS timer fixes ([#16017](https://github.com/qmk/qmk_firmware/pull/16017))
+* Fix bootloader_jump for certain CTRL boards ([#16026](https://github.com/qmk/qmk_firmware/pull/16026))
+* Fix up issue with PROGMEM and hand_swap_config ([#16027](https://github.com/qmk/qmk_firmware/pull/16027))
+* Don't make EEPROM size assumptions with dynamic keymaps. ([#16054](https://github.com/qmk/qmk_firmware/pull/16054))
+* fix missed .noci in reviung move ([#16107](https://github.com/qmk/qmk_firmware/pull/16107))
+* Fix issues with Python Tests ([#16162](https://github.com/qmk/qmk_firmware/pull/16162))
+* Fixup multibuild filegen ([#16166](https://github.com/qmk/qmk_firmware/pull/16166))
+* Remove old .gitignore entry. Add more macOS junk exclusions. ([#16167](https://github.com/qmk/qmk_firmware/pull/16167))
+* Fixup builds so that teensy EEPROM knows which MCU it's targeting. ([#16168](https://github.com/qmk/qmk_firmware/pull/16168))
+* Create a build error if no bootloader is specified. ([#16181](https://github.com/qmk/qmk_firmware/pull/16181))
+* Ensure `version.h` is recreated each build. ([#16188](https://github.com/qmk/qmk_firmware/pull/16188))
+* Add `custom` to list of valid bootloader types in info.json ([#16228](https://github.com/qmk/qmk_firmware/pull/16228))
+* Fix `layer_state` restoration at end of dynamic macro feature #16208 ([#16230](https://github.com/qmk/qmk_firmware/pull/16230))
+* Minor additions #12795 ([#16276](https://github.com/qmk/qmk_firmware/pull/16276))
+* Various fixes for matrix _RIGHT handling ([#16292](https://github.com/qmk/qmk_firmware/pull/16292))
+* Fix slashes in build_full_test.mk ([#16300](https://github.com/qmk/qmk_firmware/pull/16300))
+* ps2/avr: use the correct file name ([#16316](https://github.com/qmk/qmk_firmware/pull/16316))
+* Fix compilation of ChibiOS UART driver ([#16348](https://github.com/qmk/qmk_firmware/pull/16348))
+* Various fixes for new-keyboard ([#16358](https://github.com/qmk/qmk_firmware/pull/16358))
+* Allow NO_PIN within data driven configuration ([#16359](https://github.com/qmk/qmk_firmware/pull/16359))

docs/_summary.md

@@ -37,7 +37,6 @@
   * Guides
     * [Customizing Functionality](custom_quantum_functions.md)
     * [Driver Installation with Zadig](driver_installation_zadig.md)
-    * [Easy Maker for One Offs](easy_maker.md)
     * [Keymap Overview](keymap.md)
     * Development Environments
       * [Docker Guide](getting_started_docker.md)
@@ -53,9 +52,6 @@
       * [Your Fork](newbs_git_using_your_master_branch.md)
       * [Merge Conflicts](newbs_git_resolving_merge_conflicts.md)
       * [Fixing Your Branch](newbs_git_resynchronize_a_branch.md)
-    * Keyboard Building
-      * [Hand Wiring Guide](hand_wire.md)
-      * [ISP Flashing Guide](isp_flashing_guide.md)
 
   * Simple Keycodes
     * [Full List](keycodes.md)
@@ -124,17 +120,22 @@
     * [Thermal Printer](feature_thermal_printer.md)
     * [Velocikey](feature_velocikey.md)
 
+  * Keyboard Building
+    * [Easy Maker for One Offs](easy_maker.md)
+    * [Porting Keyboards](porting_your_keyboard_to_qmk.md)
+    * [Hand Wiring Guide](hand_wire.md)
+    * [ISP Flashing Guide](isp_flashing_guide.md)
+
 * Developing QMK
   * [PR Checklist](pr_checklist.md)
   * Breaking Changes
     * [Overview](breaking_changes.md)
     * [My Pull Request Was Flagged](breaking_changes_instructions.md)
-    * [Most Recent ChangeLog](ChangeLog/20211127.md "QMK v0.15.0 - 2021 Nov 27")
+    * [Most Recent ChangeLog](ChangeLog/20220226.md "QMK v0.16.0 - 2022 Feb 26")
     * [Past Breaking Changes](breaking_changes_history.md)
 
   * C Development
     * [ARM Debugging Guide](arm_debugging.md)
-    * [AVR Processors](hardware_avr.md)
     * [Coding Conventions](coding_conventions_c.md)
     * [Compatible Microcontrollers](compatible_microcontrollers.md)
     * [Drivers](hardware_drivers.md)

docs/api_docs.md

@@ -62,7 +62,7 @@ This shows us that the job has made it through the queue and is currently runnin
 
 Once your compile job has finished you'll check the `result` key. The value of this key is a hash containing several key bits of information:
 
-* `firmware_binary_url`: A list of URLs for the the flashable firmware
-* `firmware_keymap_url`: A list of URLs for the the `keymap.c`
+* `firmware_binary_url`: A list of URLs for the flashable firmware
+* `firmware_keymap_url`: A list of URLs for the `keymap.c`
 * `firmware_source_url`: A list of URLs for the full firmware source code
 * `output`: The stdout and stderr for this compile job. Errors will be found here.

docs/breaking_changes.md

@@ -8,6 +8,7 @@ The breaking change period is when we will merge PR's that change QMK in dangero
 
 ## What has been included in past Breaking Changes?
 
+* [2022 Feb 26](ChangeLog/20220226.md)
 * [2021 Nov 27](ChangeLog/20211127.md)
 * [2021 Aug 28](ChangeLog/20210828.md)
 * [2021 May 29](ChangeLog/20210529.md)
@@ -20,17 +21,17 @@ The breaking change period is when we will merge PR's that change QMK in dangero
 
 ## When is the next Breaking Change?
 
-The next Breaking Change is scheduled for February 26, 2022.
+The next Breaking Change is scheduled for May 28, 2022.
 
 ### Important Dates
 
-* [x] 2021 Nov 27 - `develop` is tagged with a new release version. Each push to `master` is subsequently merged to `develop` by GitHub actions.
-* [ ] 2022 Jan 31 - `develop` closed to new PR's.
-* [ ] 2022 Jan 31 - Call for testers.
-* [ ] 2022 Feb 12 - Last day for merges -- after this point `develop` is locked for testing and accepts only bugfixes
-* [ ] 2022 Feb 24 - `master` is locked, no PR's merged.
-* [ ] 2022 Feb 26 - Merge `develop` to `master`.
-* [ ] 2022 Feb 26 - `master` is unlocked. PR's can be merged again.
+* [x] 2022 Feb 26 - `develop` is tagged with a new release version. Each push to `master` is subsequently merged to `develop` by GitHub actions.
+* [ ] 2022 Apr 31 - `develop` closed to new PR's.
+* [ ] 2022 Apr 31 - Call for testers.
+* [ ] 2022 May 14 - Last day for merges -- after this point `develop` is locked for testing and accepts only bugfixes
+* [ ] 2022 May 26 - `master` is locked, no PR's merged.
+* [ ] 2022 May 28 - Merge `develop` to `master`.
+* [ ] 2022 May 28 - `master` is unlocked. PR's can be merged again.
 
 ## What changes will be included?
 

docs/breaking_changes_history.md

@@ -2,6 +2,7 @@
 
 This page links to all previous changelogs from the QMK Breaking Changes process.
 
+* [2022 Feb 26](ChangeLog/20220226.md) - version 0.16.0
 * [2021 Nov 27](ChangeLog/20211127.md) - version 0.15.0
 * [2021 Aug 28](ChangeLog/20210828.md) - version 0.14.0
 * [2021 May 29](ChangeLog/20210529.md) - version 0.13.0

docs/cli_commands.md

@@ -54,7 +54,7 @@ or in keymap directory
 ```
 $ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
 $ qmk compile
-Ψ Compiling keymap with make make gh60/satan:colemak
+Ψ Compiling keymap with make gh60/satan:colemak
 ...
 ```
 
@@ -310,7 +310,7 @@ Any arguments that are not provided will prompt for input. If `-u` is not passed
 **Usage**:
 
 ```
-qmk new-keyboard [-kb KEYBOARD] [-t {avr,ps2avrgb}] -u USERNAME
+qmk new-keyboard [-kb KEYBOARD] [-t {atmega32u4,STM32F303,etc}] [-l {60_ansi,75_iso,etc}] -u USERNAME
 ```
 
 ## `qmk new-keymap`

docs/compatible_microcontrollers.md

@@ -1,6 +1,6 @@
 # Compatible Microcontrollers
 
-QMK runs on any USB-capable AVR or ARM microcontroller with enough flash space - generally 32kB or more, though it will *just* squeeze into 16kB with most features disabled.
+QMK runs on any USB-capable AVR or ARM microcontroller with enough flash space - generally 32kB+ for AVR, and 64kB+ for ARM. With significant disabling of features, QMK may *just* squeeze into 16kB AVR MCUs.
 
 ## Atmel AVR
 
@@ -8,7 +8,11 @@ The following use [LUFA](https://www.fourwalledcubicle.com/LUFA.php) as the USB
 
 * [ATmega16U2](https://www.microchip.com/wwwproducts/en/ATmega16U2) / [ATmega32U2](https://www.microchip.com/wwwproducts/en/ATmega32U2)
 * [ATmega16U4](https://www.microchip.com/wwwproducts/en/ATmega16U4) / [ATmega32U4](https://www.microchip.com/wwwproducts/en/ATmega32U4)
+  * SparkFun Pro Micro (and clones)
+  * PJRC Teensy 2.0
+  * Adafruit Feather 32U4
 * [AT90USB64](https://www.microchip.com/wwwproducts/en/AT90USB646) / [AT90USB128](https://www.microchip.com/wwwproducts/en/AT90USB1286)
+  * PJRC Teensy++ 2.0
 * [AT90USB162](https://www.microchip.com/wwwproducts/en/AT90USB162)
 
 Certain MCUs which do not have native USB will use [V-USB](https://www.obdev.at/products/vusb/index.html) instead:
@@ -25,17 +29,23 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s
 
  * [STM32F0x2](https://www.st.com/en/microcontrollers-microprocessors/stm32f0x2.html)
  * [STM32F103](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html)
+   * Bluepill (with STM32duino bootloader)
  * [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html)
+   * QMK Proton-C
  * [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html)
+   * WeAct Blackpill
  * [STM32F405](https://www.st.com/en/microcontrollers-microprocessors/stm32f405-415.html)
  * [STM32F407](https://www.st.com/en/microcontrollers-microprocessors/stm32f407-417.html)
  * [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html)
+   * WeAct Blackpill
  * [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html)
  * [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html)
  * [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html)
  * [STM32L412](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html)
  * [STM32L422](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html)
+ * [STM32L432](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html)
  * [STM32L433](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html)
+ * [STM32L442](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html)
  * [STM32L443](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html)
 
 ### WestBerryTech (WB32)
@@ -45,13 +55,16 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s
 ### NXP (Kinetis)
 
  * [MKL26Z64](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/kl-series-cortex-m0-plus/kinetis-kl2x-72-96-mhz-usb-ultra-low-power-microcontrollers-mcus-based-on-arm-cortex-m0-plus-core:KL2x)
+   * PJRC Teensy LC
  * [MK20DX128](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k2x-usb/kinetis-k20-50-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-based-on-arm-cortex-m4-core:K20_50)
  * [MK20DX256](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k2x-usb/kinetis-k20-72-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-mcus-based-on-arm-cortex-m4-core:K20_72)
+   * PJRC Teensy 3.2
  * [MK66FX1M0](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k6x-ethernet/kinetis-k66-180-mhz-dual-high-speed-full-speed-usbs-2mb-flash-microcontrollers-mcus-based-on-arm-cortex-m4-core:K66_180)
+   * PJRC Teensy 3.6
 
 ## Atmel ATSAM
 
-There is limited support for one of Atmel's ATSAM microcontrollers, that being the [ATSAMD51J18A](https://www.microchip.com/wwwproducts/en/ATSAMD51J18A) used by the [Massdrop keyboards](https://github.com/qmk/qmk_firmware/tree/master/keyboards/massdrop).
+There is limited support for one of Atmel's ATSAM microcontrollers, that being the [ATSAMD51J18A](https://www.microchip.com/wwwproducts/en/ATSAMD51J18A) used by the [Massdrop keyboards](https://github.com/qmk/qmk_firmware/tree/master/keyboards/massdrop). However, it is not recommended to design a board with this microcontroller as the support is quite specialized to Massdrop hardware.
 
 ## RISC-V
 

docs/config_options.md

@@ -61,6 +61,8 @@ This is a C header file that is one of the first things included, and will persi
   * pins unused by the keyboard for reference
 * `#define MATRIX_HAS_GHOST`
   * define is matrix has ghost (unlikely)
+* `#define MATRIX_UNSELECT_DRIVE_HIGH`
+  * On un-select of matrix pins, rather than setting pins to input-high, sets them to output-high.
 * `#define DIODE_DIRECTION COL2ROW`
   * COL2ROW or ROW2COL - how your matrix is configured. COL2ROW means the black mark on your diode is facing to the rows, and between the switch and the rows.
 * `#define DIRECT_PINS { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
@@ -124,10 +126,6 @@ If you define these options you will disable the associated feature, which can s
   * disable tap dance and other tapping features
 * `#define NO_ACTION_ONESHOT`
   * disable one-shot modifiers
-* `#define NO_ACTION_MACRO`
-  * disable old-style macro handling using `MACRO()`, `action_get_macro()` _(deprecated)_
-* `#define NO_ACTION_FUNCTION`
-  * disable old-style function handling using `fn_actions`, `action_function()` _(deprecated)_
 
 ## Features That Can Be Enabled
 
@@ -383,7 +381,6 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
   * A list of [layouts](feature_layouts.md) this keyboard supports.
 * `LTO_ENABLE`
   * Enables Link Time Optimization (LTO) when compiling the keyboard.  This makes the process take longer, but it can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable).
-However, this will automatically disable the legacy TMK Macros and Functions features, as these break when LTO is enabled.  It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION`.  (Note: This does not affect QMK [Macros](feature_macros.md) and [Layers](feature_layers.md).)
 
 ## AVR MCU Options
 * `MCU = atmega32u4`
@@ -434,8 +431,8 @@ Use these to enable or disable building certain features. The more you have enab
   * MIDI controls
 * `UNICODE_ENABLE`
   * Unicode
-* `BLUETOOTH`
-  * Current options are AdafruitBLE, RN42
+* `BLUETOOTH_ENABLE`
+  * Current options are BluefruitLE, RN42
 * `SPLIT_KEYBOARD`
   * Enables split keyboard support (dual MCU like the let's split and bakingpy's boards) and includes all necessary files located at quantum/split_common
 * `CUSTOM_MATRIX`

docs/configurator_step_by_step.md

@@ -43,7 +43,7 @@ Keycode Entry is accomplished in one of 3 ways:
 
 ## Step 5: Save Your Keymap for Future Changes
 
-When you're satisfied with your keymap or just want to work on it later, press the `Export Keymap` button. It will save your keymap to your computer. You can then load this .json file in the future by pressing the `Import Keymap` button.
+When you're satisfied with your keymap or just want to work on it later, press the `Download this QMK Keymap JSON File` button. It will save your keymap to your computer. You can then load this .json file in the future by pressing the `Upload a QMK Keymap JSON File` button.
 
 !> **CAUTION:** This is not the same type of .json file used for kbfirmware.com or any other tool. If you try to use this for those tools, or the .json from those tools with QMK Configurator, you will encounter problems.
 

docs/contributing.md

@@ -109,7 +109,7 @@ Before opening a pull request, you can preview your changes if you have set up t
 
 or if you only have Python 3 installed:
 
-    python3 -m http.server 8936
+    python3 -m http.server 8936 --directory docs
 
 and navigating to `http://localhost:8936/`.
 
@@ -165,4 +165,4 @@ To maintain a clear vision of how things are laid out in QMK we try to plan out
 
 # What Does the Code of Conduct Mean for Me?
 
-Our [Code of Conduct](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md) means that you are responsible for treating everyone on the project with respect and courtesy regardless of their identity. If you are the victim of any inappropriate behavior or comments as described in our Code of Conduct, we are here for you and will do the best to ensure that the abuser is reprimanded appropriately, per our code.
+Our [Code of Conduct](https://qmk.fm/coc/) means that you are responsible for treating everyone on the project with respect and courtesy regardless of their identity. If you are the victim of any inappropriate behavior or comments as described in our Code of Conduct, we are here for you and will do the best to ensure that the abuser is reprimanded appropriately, per our code.

docs/custom_quantum_functions.md

@@ -408,7 +408,7 @@ The `val` is the value of the data that you want to write to EEPROM.  And the `e
 
 ### Deferred Execution :id=deferred-execution
 
-QMK has the ability to execute a callback after a specified period of time, rather than having to manually manage timers.
+QMK has the ability to execute a callback after a specified period of time, rather than having to manually manage timers. To enable this functionality, set `DEFERRED_EXEC_ENABLE = yes` in rules.mk.
 
 #### Deferred executor callbacks
 

docs/data_driven_config.md

@@ -74,7 +74,7 @@ Whenever QMK generates a complete `info.json` it extracts information from `conf
 
 If you are not sure how to edit this file or are not comfortable with Python [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and someone can help you with this part.
 
-### Add code to generate it
+### Add code to generate it :id=add-code-to-generate-it
 
 The final piece of the puzzle is providing your new option to the build system. This is done by generating two files:
 

docs/easy_maker.md

@@ -7,7 +7,7 @@ There are different styles of Easy Maker available depending on your needs:
 * [Direct Pin](https://config.qmk.fm/#/?filter=ez_maker/direct) - Connect a single switch to a single pin
 * Direct Pin + Backlight (Coming Soon) - Like Direct Pin but dedicates a single pin to [Backlight](feature_backlight.md) control
 * Direct Pin + Numlock (Coming Soon) - Like Direct Pin but dedicates a single pin to the Numlock LED
-* Direct Pin + Capslock (Coming Soon) - Like Direct Pin but dedicates a single pin to the Numlock LED
+* Direct Pin + Capslock (Coming Soon) - Like Direct Pin but dedicates a single pin to the Capslock LED
 * Direct Pin + Encoder (Coming Soon) - Like Direct Pin but uses 2 pins to add a single rotary encoder
 
 ## Quickstart

docs/feature_bluetooth.md

@@ -7,7 +7,7 @@ Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1, QM
 |Board                                                           |Bluetooth Protocol  |Connection Type|rules.mk                        |Bluetooth Chip|
 |----------------------------------------------------------------|--------------------|---------------|--------------------------------|--------------|
 |Roving Networks RN-42 (Sparkfun Bluesmirf)                      |Bluetooth Classic   |UART           |`BLUETOOTH_DRIVER = RN42`       |RN-42         |
-|[Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633)|Bluetooth Low Energy|SPI            |`BLUETOOTH_DRIVER = AdafruitBLE`|nRF51822      |
+|[Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633)|Bluetooth Low Energy|SPI            |`BLUETOOTH_DRIVER = BluefruitLE`|nRF51822      |
 
 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)
@@ -17,9 +17,9 @@ Not Supported Yet but possible:
 
 ### Adafruit BLE SPI Friend
 Currently The only bluetooth chipset supported by QMK is the Adafruit Bluefruit SPI Friend. It's a Nordic nRF51822 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 ADAFRUIT_BLE_RST_PIN D4`
-* `#define ADAFRUIT_BLE_CS_PIN  B4`
-* `#define ADAFRUIT_BLE_IRQ_PIN E6`
+* `#define BLUEFRUIT_LE_RST_PIN D4`
+* `#define BLUEFRUIT_LE_CS_PIN  B4`
+* `#define BLUEFRUIT_LE_IRQ_PIN 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.
 
@@ -32,7 +32,7 @@ Add the following to your `rules.mk`:
 
 ```make
 BLUETOOTH_ENABLE = yes
-BLUETOOTH_DRIVER = AdafruitBLE # or RN42
+BLUETOOTH_DRIVER = BluefruitLE # or RN42
 ```
 
 ## Bluetooth Keycodes

docs/feature_combo.md

@@ -141,10 +141,13 @@ Processing combos has two buffers, one for the key presses, another for the comb
 ## Modifier Combos
 If a combo resolves to a Modifier, the window for processing the combo can be extended independently from normal combos. By default, this is disabled but can be enabled with `#define COMBO_MUST_HOLD_MODS`, and the time window can be configured with `#define COMBO_HOLD_TERM 150` (default: `TAPPING_TERM`). With `COMBO_MUST_HOLD_MODS`, you cannot tap the combo any more which makes the combo less prone to misfires.
 
-## Per Combo Timing, Holding and Tapping
-For each combo, it is possible to configure the time window it has to pressed in, if it needs to be held down, or if it needs to be tapped.
+## Strict key press order
+By defining `COMBO_MUST_PRESS_IN_ORDER` combos only activate when the keys are pressed in the same order as they are defined in the key array.
 
-For example, tap-only combos are useful if any (or all) of the underlying keys is a Mod-Tap or a Layer-Tap key. When you tap the combo, you get the combo result. When you press the combo and hold it down, the combo doesn't actually activate. Instead the keys are processed separately as if the combo wasn't even there.
+## Per Combo Timing, Holding, Tapping and Key Press Order
+For each combo, it is possible to configure the time window it has to pressed in, if it needs to be held down, if it needs to be tapped, or if its keys need to be pressed in order.
+
+For example, tap-only combos are useful if any (or all) of the underlying keys are mod-tap or layer-tap keys. When you tap the combo, you get the combo result. When you press the combo and hold it down, the combo doesn't activate. Instead the keys are processed separately as if the combo wasn't even there.
 
 In order to use these features, the following configuration options and functions need to be defined. Coming up with useful timings and configuration is left as an exercise for the reader.
 
@@ -153,6 +156,7 @@ In order to use these features, the following configuration options and function
 | `COMBO_TERM_PER_COMBO`      | uint16_t get_combo_term(uint16_t index, combo_t \*combo)  | Optional per-combo timeout window. (default: `COMBO_TERM`)                                             |
 | `COMBO_MUST_HOLD_PER_COMBO` | bool get_combo_must_hold(uint16_t index, combo_t \*combo) | Controls if a given combo should fire immediately on tap or if it needs to be held. (default: `false`) |
 | `COMBO_MUST_TAP_PER_COMBO`  | bool get_combo_must_tap(uint16_t index, combo_t \*combo)  | Controls if a given combo should fire only if tapped within `COMBO_HOLD_TERM`. (default: `false`)      |
+| `COMBO_MUST_PRESS_IN_ORDER_PER_COMBO` | bool get_combo_must_press_in_order(uint16_t index, combo_t \*combo) | Controls if a given combo should fire only if its keys are pressed in order. (default: `true`) |
 
 Examples:
 ```c
@@ -216,6 +220,38 @@ bool get_combo_must_tap(uint16_t index, combo_t *combo) {
     return false;
 
 }
+
+bool get_combo_must_press_in_order(uint16_t combo_index, combo_t *combo) {
+    switch (combo_index) {
+        /* List combos here that you want to only activate if their keys
+         * are pressed in the same order as they are defined in the combo's key
+         * array. */
+        case COMBO_NAME_HERE:
+            return true;
+        default:
+            return false;
+    }
+}
+```
+
+## Generic hook to (dis)allow a combo activation
+
+By defining `COMBO_SHOULD_TRIGGER` and its companying function `bool combo_should_trigger(uint16_t combo_index, combo_t *combo, uint16_t keycode, keyrecord_t *record)` you can block or allow combos to activate on the conditions of your choice.
+For example, you could disallow some combos on the base layer and allow them on another. Or disable combos on the home row when a timer is running.
+
+Examples:
+```c
+bool combo_should_trigger(uint16_t combo_index, combo_t *combo, uint16_t keycode, keyrecord_t *record) {
+    /* Disable combo `SOME_COMBO` on layer `_LAYER_A` */
+    switch (combo_index) {
+        case SOME_COMBO:
+            if (layer_state_is(_LAYER_A)) {
+                return false;
+            }
+    }
+
+    return true;
+}
 ```
 
 ## Variable Length Combos

docs/feature_debounce_type.md

@@ -116,6 +116,7 @@ Where name of algorithm is one of:
 For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be
 appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use.
 * ```sym_eager_pk``` - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key
+* ```sym_defer_pr``` - debouncing per row. On any state change, a per-row timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that row, the entire row is pushed. Can improve responsiveness over `sym_defer_g` while being less susceptible than per-key debouncers to noise.
 * ```sym_defer_pk``` - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key status change is pushed.
 * ```asym_eager_defer_pk``` - debouncing per key. On a key-down state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key. On a key-up state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key-up status change is pushed.
 

docs/feature_encoders.md

@@ -85,7 +85,7 @@ bool encoder_update_user(uint8_t index, bool clockwise) {
 }
 ```
 
-!> If you return `true`, this will allow the keyboard level code to run, as well.  Returning `false` will override the keyboard level code.  Depending on how the keyboard level function is set up. 
+!> If you return `true`, it will allow the keyboard level code to run as well. Returning `false` will override the keyboard level code, depending on how the keyboard function is set up. 
 
 Layer conditions can also be used with the callback function like the following:
 
@@ -132,7 +132,10 @@ The A an B lines of the encoders should be wired directly to the MCU, and the C/
 
 ## Multiple Encoders
 
-Multiple encoders may share pins so long as each encoder has a distinct pair of pins. 
+Multiple encoders may share pins so long as each encoder has a distinct pair of pins when the following conditions are met:
+- using detent encoders
+- pads must be high at the detent stability point which is called 'default position' in QMK
+- no more than two encoders sharing a pin can be turned at the same time 
 
 For example you can support two encoders using only 3 pins like this
 ```

docs/feature_grave_esc.md

@@ -4,17 +4,17 @@ If you're using a 60% keyboard, or any other layout with no F-row, you will have
 
 ## Usage
 
-Replace the `KC_GRV` key in your keymap (usually to the left of the `1` key) with `KC_GESC`. Most of the time this key will output `KC_ESC` when pressed. However, when Shift or GUI are held down it will output `KC_GRV` instead.
+Replace the `KC_GRV` key in your keymap (usually to the left of the `1` key) with `QK_GESC`. Most of the time this key will output `KC_ESC` when pressed. However, when Shift or GUI are held down it will output `KC_GRV` instead.
 
 ## What Your OS Sees
 
-If Mary presses GESC on her keyboard, the OS will see an KC_ESC character. Now if Mary holds Shift down and presses GESC it will output `~`, or a shifted backtick. Now if she holds GUI/CMD/WIN, it will output a simple <code>&#96;</code> character.
+If Mary presses `QK_GESC` on her keyboard, the OS will see an KC_ESC character. Now if Mary holds Shift down and presses `QK_GESC` it will output `~`, or a shifted backtick. Now if she holds GUI/CMD/WIN, it will output a simple <code>&#96;</code> character.
 
 ## Keycodes
 
-|Key      |Aliases    |Description                                                       |
-|---------|-----------|------------------------------------------------------------------|
-|`KC_GESC`|`GRAVE_ESC`|Escape when pressed, <code>&#96;</code> when Shift or GUI are held|
+|Key              |Aliases  |Description                                                       |
+|-----------------|---------|------------------------------------------------------------------|
+|`QK_GRAVE_ESCAPE`|`QK_GESC`|Escape when pressed, <code>&#96;</code> when Shift or GUI are held|
 
 ### Caveats
 

docs/feature_haptic_feedback.md

@@ -167,7 +167,7 @@ List of waveform sequences from the datasheet:
 ```
 #define DRV_GREETING *sequence name or number*
 ```
-If haptic feedback is enabled, the keyboard will vibrate to a specific sqeuence during startup. That can be selected using the following define:
+If haptic feedback is enabled, the keyboard will vibrate to a specific sequence during startup. That can be selected using the following define:
 
 ```
 #define DRV_MODE_DEFAULT *sequence name or number*
@@ -191,9 +191,6 @@ With the entry of `#define NO_HAPTIC_MOD` in config.h, the following keys will n
 * `TT()` layer tap toggle keys, when held to activate a layer. However when tapped `TAPPING_TOGGLE` times to permanently toggle the layer, on the last tap haptic feedback is still triggered.
 * `MT()` mod tap keys, when held to keep a usual modifier key pressed. However when tapped, and the key is quickly released, and sends a keycode, haptic feedback is still triggered. See also [Mod-Tap](mod_tap.md).
 
-### NO_HAPTIC_FN
-With the entry of `#define NO_HAPTIC_FN` in config.h, deprecated `fn_actions` type function keys will not trigger a feedback.
-
 ### NO_HAPTIC_ALPHA
 With the entry of `#define NO_HAPTIC_ALPHA` in config.h, none of the alpha keys (A ... Z) will trigger a feedback.
 
@@ -207,4 +204,4 @@ With the entry of `#define NO_HAPTIC_LOCKKEYS` in config.h, none of the followin
 With the entry of `#define NO_HAPTIC_NAV` in config.h, none of the following keys will trigger a feedback: Print Screen, Pause, Insert, Delete, Page Down, Page Up, Left Arrow, Up Arrow, Right Arrow, Down Arrow, End, Home.
 
 ### NO_HAPTIC_NUMERIC
-With the entry of `#define NO_HAPTIC_NUMERIC` in config.h, none of the following keys between 0 and 9 (KC_1 ... KC_0) will trigger a feedback.
+With the entry of `#define NO_HAPTIC_NUMERIC` in config.h, none of the following keys between 0 and 9 (KC_1 ... KC_0) will trigger a feedback.

docs/feature_key_lock.md

@@ -19,4 +19,5 @@ First, enable Key Lock by setting `KEY_LOCK_ENABLE = yes` in your `rules.mk`. Th
 Key Lock is only able to hold standard action keys and [One Shot modifier](one_shot_keys.md) 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.
+Switching layers will not cancel the Key Lock. The Key Lock can be cancelled by calling the `cancel_key_lock()` function.
+

docs/feature_leader_key.md

@@ -37,7 +37,7 @@ 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.
+As you can see, you have a few functions. 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.
 
@@ -74,9 +74,9 @@ SEQ_THREE_KEYS(KC_C, KC_C, KC_C) {
 
 ## Infinite Leader key timeout
 
-Sometimes your leader key is not on a comfortable places as the rest of keys on your sequence. Imagine that your leader key is one of your outer top right keys, you may need to reposition your hand just to reach your leader key.
+Sometimes your leader key is not on a comfortable place as the rest of keys on your sequence. Imagine that your leader key is one of your outer top right keys, you may need to reposition your hand just to reach your leader key.
 This can make typing the entire sequence on time hard even if you are able to type most of the sequence fast. For example, if your sequence is `Leader + asd` typing `asd` fast is very easy once you have your hands in your home row. However starting the sequence in time after moving your hand out of the home row to reach the leader key and back is not.
-To remove the stress this situation produces to your hands you can enable an infinite timeout just for the leader key. This mean that, after you hit the leader key you will have an infinite amount of time to start the rest of the sequence, allowing you to proper position your hands on the best position to type the rest of the sequence comfortably.
+To remove the stress this situation produces to your hands you can enable an infinite timeout just for the leader key. This means that after you hit the leader key you will have an infinite amount of time to start the rest of the sequence, allowing you to proper position your hands on the best position to type the rest of the sequence comfortably.
 This infinite timeout only affects the leader key, so in our previous example of `Leader + asd` you will have an infinite amount of time between `Leader` and `a`, but once you start the sequence the timeout you have configured (global or per key) will work normally.
 This way you can configure a very short `LEADER_TIMEOUT` but still have plenty of time to position your hands.
 
@@ -89,11 +89,11 @@ In order to enable this, place this in your `config.h`:
 
 By default, the Leader Key feature will filter the keycode out of [`Mod-Tap`](mod_tap.md) and [`Layer Tap`](feature_layers.md#switching-and-toggling-layers) functions when checking for the Leader sequences. That means if you're using `LT(3, KC_A)`, it will pick this up as `KC_A` for the sequence, rather than `LT(3, KC_A)`, giving a more expected behavior for newer users.
 
-While, this may be fine for most, if you want to specify the whole keycode (eg, `LT(3, KC_A)` from the example above) in the sequence, you can enable this by added `#define LEADER_KEY_STRICT_KEY_PROCESSING` to your `config.h` file.  This will then disable the filtering, and you'll need to specify the whole keycode.
+While, this may be fine for most, if you want to specify the whole keycode (eg, `LT(3, KC_A)` from the example above) in the sequence, you can enable this by adding `#define LEADER_KEY_STRICT_KEY_PROCESSING` to your `config.h` file.  This will then disable the filtering, and you'll need to specify the whole keycode.
 
 ## Customization 
 
-The Leader Key feature has some additional customization to how the Leader Key feature works.  It has two functions that can be called at certain parts of the process.  Namely `leader_start()` and `leader_end()`.
+The Leader Key feature has some additional customization to how the Leader Key feature works. It has two functions that can be called at certain parts of the process. Namely `leader_start()` and `leader_end()`.
 
 The `leader_start()` function is called when you tap the `KC_LEAD` key, and the `leader_end()` function is called when either the leader sequence is completed, or the leader timeout is hit. 
 

docs/feature_led_indicators.md

@@ -1,6 +1,6 @@
 # LED Indicators
 
-?> This feature requires additional configuration to work on both halves of a split keyboard see [Data sync options](feature_split_keyboard.md#data-sync-options)
+?> LED indicators on split keyboards will require state information synced to the slave half (e.g. `#define SPLIT_LED_STATE_ENABLE`). See [data sync options](feature_split_keyboard.md#data-sync-options) for more details.
 
 QMK provides methods to read 5 of the LEDs defined in the HID spec:
 

docs/feature_led_matrix.md

@@ -67,6 +67,109 @@ const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = {
 
 Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/led/issi/is31fl3731-simple.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` ).
 
+---
+### IS31FLCOMMON :id=is31flcommon
+
+There is basic support for addressable LED matrix lighting with a selection of I2C ISSI Lumissil LED controllers through a shared common driver. To enable it, add this to your `rules.mk`:
+
+```makefile
+LED_MATRIX_ENABLE = yes
+LED_MATRIX_DRIVER = <driver name>
+```
+
+Where `<driver name>` is the applicable LED driver chip as below
+
+| Driver Name | Data Sheet | Capability |
+|-------------|------------|------------|
+| `IS31FL3742A` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3742A_DS.pdf) | 180 LED, 30x6 Matrix |
+| `ISSIFL3743A` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3743A_DS.pdf) | 198 LED, 18x11 Matrix |
+| `IS31FL3745` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3745_DS.pdf) | 144 LED, 18x8 Matrix |
+| `IS31FL3746A` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3746A_DS.pdf) | 72 LED, 18x4 Matrix |
+
+You can use between 1 and 4 IC's. Do not specify `DRIVER_ADDR_<N>` define for IC's if not present on your keyboard. The `DRIVER_ADDR_1` default assumes that all Address pins on the controller have been connected to GND. Drivers that have SYNC functionality have the default settings to disable if 1 driver. If more than 1 drivers then `DRIVER_ADDR_1` will be set to Master and the remaiing ones set to Slave.
+
+Configure the hardware via your `config.h`:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 |
+| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 |
+| `DRIVER_COUNT` | (Required) How many LED driver IC's are present | |
+| `DRIVER_LED_TOTAL` | (Required) How many LED lights are present across all drivers | |
+| `DRIVER_ADDR_1` | (Optional) Address for the first LED driver | |
+| `DRIVER_ADDR_<N>` | (Required) Address for the additional LED drivers | |
+| `ISSI_SSR_<N>` | (Optional) Configuration for the Spread Spectrum Register | |
+| `ISSI_CONFIGURATION` | (Optional) Configuration for the Configuration Register | |
+| `ISSI_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF |
+| `ISSI_PULLDOWNUP` | (Optional) Configuration for the Pull Up & Pull Down Register | |
+| `ISSI_TEMP` | (Optional) Configuration for the Tempature Register | |
+| `ISSI_PWM_ENABLE` | (Optional) Configuration for the PWM Enable Register | |
+| `ISSI_PWM_SET` | (Optional) Configuration for the PWM Setting Register | |
+| `ISSI_SCAL_LED ` | (Optional) Configuration for the LEDs Scaling Registers | 0xFF |
+| `ISSI_MANUAL_SCALING` | (Optional) If you wish to configure the Scaling Registers manually | |
+
+
+Defaults
+
+| Variable | IS31FL3742A | IS31FL3743A | IS31FL3745 | IS31FL3746 |
+|----------|-------------|-------------|------------|------------|
+| `DRIVER_ADDR_1` | 0b0110000 | 0b0100000 | 0b0100000 | 0b1100000 |
+| `ISSI_SSR_1` | 0x00 | 0x00 / 0x60 | 0x00 / 0xC0 | 0x00 |
+| `ISSI_SSR_<2-4>` | 0x00 | 0x40 | 0x80 | 0x00 |
+| `ISSI_CONFIGURATION` | 0x31 | 0x01 | 0x31 | 0x01 |
+| `ISSI_PULLDOWNUP` | 0x55 | 0x33 | 0x33 | 0x33 |
+| `ISSI_TEMP` | N/A | 0x00 | 0x00 | 0x00 |
+| `ISSI_PWM_ENABLE` | N/A | N/A | N/A | 0x00 |
+| `ISSI_PWM_SET` | 0x00 | N/A | N/A | 0x00 |
+
+Here is an example using 2 drivers.
+
+```c
+#define DRIVER_ADDR_2 0b0100001
+
+#define DRIVER_COUNT 2
+#define DRIVER_1_LED_TOTAL 66
+#define DRIVER_2_LED_TOTAL 42
+#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)
+```
+!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`.
+
+Currently only 4 drivers are supported, but it would be trivial to support for more. Note that using a combination of different drivers is not supported. All drivers must be of the same model.
+
+Define these arrays listing all the LEDs in your `<keyboard>.c`:
+
+```c
+const is31_led __flash g_is31_leds[DRIVER_LED_TOTAL] = {
+/* Refer to IS31 manual for these locations
+ *    driver
+ *    |  LED address
+ *    |  | */
+    { 0, CS1_SW1 },
+    { 0, CS2_SW1 },
+    // ...
+}
+```
+
+Where `CSx_SWx` is the location of the LED in the matrix defined by the datasheet. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` for now).
+
+`ISSI_MANUAL_SCALING` is used to override the Scaling for individual LED's. By default they will be set as per `ISSI_SCAL_LED`. In `config.h` set how many LED's you want to manually set scaling for.
+Eg `#define ISSI_MANUAL_SCALING 3`
+
+Then Define the array listing all the LEDs you want to override in your `<keyboard>.c`:
+
+```c
+const is31_led __flash g_is31_scaling[ISSI_MANUAL_SCALING] = {
+ *   LED Index
+ *   |  Scaling
+ *   |  | */
+    {5, 120},
+    {9, 120},
+    ....
+}
+```
+
+Where LED Index is the position of the LED in the `g_is31_leds` array. The `scaling` value between 0 and 255 to be written to the Scaling Register.
+
 ---
 
 ## Common Configuration :id=common-configuration
@@ -333,7 +436,7 @@ Where `28` is an unused index from `eeconfig.h`.
 If you want to set custom indicators, such as an LED for Caps Lock, or layer indication, you can use the `led_matrix_indicators_kb` or `led_matrix_indicators_user` function for that: 
 ```c
 void led_matrix_indicators_kb(void) {
-    led_matrix_set_color(index, value);
+    led_matrix_set_value(index, value);
 }
 ```
 

docs/feature_macros.md

@@ -40,13 +40,13 @@ You can define up to 32 macros in a `keymap.json` file, as used by [Configurator
 
 ### Selecting Your Host Keyboard Layout
 
-If you type in a language other than English, or use a non-QWERTY layout like Colemak, Dvorak, or Workman, you may have set your computer's input language to match this layout. This presents a challenge when creating macros- you may need to type different keys to get the same letters! To address this you can add the `host_language` key to your keymap.json, like so:
+If you type in a language other than English, or use a non-QWERTY layout like Colemak, Dvorak, or Workman, you may have set your computer's input language to match this layout. This presents a challenge when creating macros - you may need to type different keys to get the same letters! To address this you can add the `host_language` key to your `keymap.json`, like so:
 
 ```json
 {
     "keyboard": "handwired/my_macropad",
     "keymap": "my_keymap",
-    "host_layout": "dvorak",
+    "host_language": "dvorak",
     "macros": [
         ["Hello, World!"]
     ],
@@ -75,7 +75,7 @@ The current list of available languages is:
 
 ### Macro Basics
 
-Each macro is an array consisting of strings and objects (dictionaries.) Strings are typed to your computer while objects allow you to control how your macro is typed out.
+Each macro is an array consisting of strings and objects (dictionaries). Strings are typed to your computer while objects allow you to control how your macro is typed out.
 
 #### Object Format
 

docs/feature_mouse_keys.md

@@ -59,13 +59,13 @@ This is the default mode. You can adjust the cursor and scrolling acceleration u
 
 |Define                      |Default|Description                                              |
 |----------------------------|-------|---------------------------------------------------------|
-|`MOUSEKEY_DELAY`            |300    |Delay between pressing a movement key and cursor movement|
-|`MOUSEKEY_INTERVAL`         |50     |Time between cursor movements in milliseconds            |
-|`MOUSEKEY_MOVE_DELTA`       |5      |Step size                                                |
+|`MOUSEKEY_DELAY`            |10     |Delay between pressing a movement key and cursor movement|
+|`MOUSEKEY_INTERVAL`         |20     |Time between cursor movements in milliseconds            |
+|`MOUSEKEY_MOVE_DELTA`       |8      |Step size                                                |
 |`MOUSEKEY_MAX_SPEED`        |10     |Maximum cursor speed at which acceleration stops         |
-|`MOUSEKEY_TIME_TO_MAX`      |20     |Time until maximum cursor speed is reached               |
-|`MOUSEKEY_WHEEL_DELAY`      |300    |Delay between pressing a wheel key and wheel movement    |
-|`MOUSEKEY_WHEEL_INTERVAL`   |100    |Time between wheel movements                             |
+|`MOUSEKEY_TIME_TO_MAX`      |30     |Time until maximum cursor speed is reached               |
+|`MOUSEKEY_WHEEL_DELAY`      |10     |Delay between pressing a wheel key and wheel movement    |
+|`MOUSEKEY_WHEEL_INTERVAL`   |80     |Time between wheel movements                             |
 |`MOUSEKEY_WHEEL_MAX_SPEED`  |8      |Maximum number of scroll steps per scroll action         |
 |`MOUSEKEY_WHEEL_TIME_TO_MAX`|40     |Time until maximum scroll speed is reached               |
 
@@ -85,9 +85,9 @@ This is an extension of the accelerated mode. The kinetic mode uses a quadratic
 |Define                                |Default  |Description                                                    |
 |--------------------------------------|---------|---------------------------------------------------------------|
 |`MK_KINETIC_SPEED`                    |undefined|Enable kinetic mode                                            |
-|`MOUSEKEY_DELAY`                      |8        |Delay between pressing a movement key and cursor movement      |
-|`MOUSEKEY_INTERVAL`                   |8        |Time between cursor movements in milliseconds                  |
-|`MOUSEKEY_MOVE_DELTA`                 |25       |Step size for accelerating from initial to base speed          |
+|`MOUSEKEY_DELAY`                      |5        |Delay between pressing a movement key and cursor movement      |
+|`MOUSEKEY_INTERVAL`                   |10       |Time between cursor movements in milliseconds                  |
+|`MOUSEKEY_MOVE_DELTA`                 |5        |Step size for accelerating from initial to base speed          |
 |`MOUSEKEY_INITIAL_SPEED`              |100      |Initial speed of the cursor in pixel per second                |
 |`MOUSEKEY_BASE_SPEED`                 |1000     |Maximum cursor speed at which acceleration stops               |
 |`MOUSEKEY_DECELERATED_SPEED`          |400      |Decelerated cursor speed                                       |
@@ -164,7 +164,7 @@ small and detailed movements of the cursor.
 * **KC_ACL2:** This acceleration sets your cursor to the maximum (computer defined) speed. This is
 useful for moving the cursor large distances without much accuracy.
 
-To use constant speed mode, you must at least define `MK_COMBINED` in your keymap’s `config.h` file:
+To use combined speed mode, you must at least define `MK_COMBINED` in your keymap’s `config.h` file:
 
 ```c
 #define MK_COMBINED

docs/feature_oled_driver.md

@@ -84,6 +84,8 @@ static void render_logo(void) {
 }
 ```
 
+?> The default font file is located at `drivers/oled/glcdfont.c` and its location can be overwritten with the `OLED_FONT_H` configuration option. Font file content can be edited with external tools such as [Helix Font Editor](https://helixfonteditor.netlify.app/) and [Logo Editor](https://joric.github.io/qle/).
+
 ## Buffer Read Example
 For some purposes, you may need to read the current state of the OLED display
 buffer. The `oled_read_raw` function can be used to safely read bytes from the
@@ -162,7 +164,7 @@ These configuration options should be placed in `config.h`. Example:
 |`OLED_FONT_END`            |`223`            |The ending character index for custom fonts                                                                               |
 |`OLED_FONT_WIDTH`          |`6`              |The font width                                                                                                            |
 |`OLED_FONT_HEIGHT`         |`8`              |The font height (untested)                                                                                                |
-|`OLED_TIMEOUT`             |`60000`          |Turns off the OLED screen after 60000ms of keyboard inactivity. Helps reduce OLED Burn-in. Set to 0 to disable.           |
+|`OLED_TIMEOUT`             |`60000`          |Turns off the OLED screen after 60000ms of screen update inactivity. Helps reduce OLED Burn-in. Set to 0 to disable.      |
 |`OLED_FADE_OUT`            |*Not defined*    |Enables fade out animation. Use together with `OLED_TIMEOUT`.                                                             |
 |`OLED_FADE_OUT_INTERVAL`   |`0`              |The speed of fade out animation, from 0 to 15. Larger values are slower.                                                  |
 |`OLED_SCROLL_TIMEOUT`      |`0`              |Scrolls the OLED screen after 0ms of OLED inactivity. Helps reduce OLED Burn-in. Set to 0 to disable.                     |

docs/feature_pointing_device.md

@@ -2,7 +2,7 @@
 
 Pointing Device is a generic name for a feature intended to be generic: moving the system pointer around.  There are certainly other options for it - like mousekeys - but this aims to be easily modifiable and hardware driven.  You can implement custom keys to control functionality, or you can gather information from other peripherals and insert it directly here - let QMK handle the processing for you.
 
-To enable Pointing Device, uncomment the following line in your rules.mk:
+To enable Pointing Device, add the following line in your rules.mk and specify one of the driver options below.
 
 ```make
 POINTING_DEVICE_ENABLE = yes
@@ -30,7 +30,7 @@ The ADNS 5050 sensor uses a serial type protocol for communication, and requires
 
 The CPI range is 125-1375, in increments of 125. Defaults to 500 CPI.
 
-### ADSN 9800 Sensor
+### ADNS 9800 Sensor
 
 To use the ADNS 9800 sensor, add this to your `rules.mk`
 
@@ -40,13 +40,13 @@ POINTING_DEVICE_DRIVER = adns9800
 
 The ADNS 9800 is an SPI driven optical sensor, that uses laser output for surface tracking. 
 
-| Setting                | Description                                                            | Default       |
-|------------------------|------------------------------------------------------------------------|---------------|
-|`ADNS9800_CLOCK_SPEED`  | (Optional) Sets the clock speed that the sensor runs at.               | `2000000`     |
-|`ADNS9800_SPI_LSBFIRST` | (Optional) Sets the Least/Most Significant Byte First setting for SPI. | `false`       |
-|`ADNS9800_SPI_MODE`     | (Optional) Sets the SPI Mode for the sensor.                           | `3`           |
-|`ADNS9800_SPI_DIVISOR`  | (Optional) Sets the SPI Divisor used for SPI communication.            | _varies_      |
-|`ADNS9800_CS_PIN`       | (Required) Sets the Cable Select pin connected to the sensor.          | _not defined_ |
+| Setting                        | Description                                                            | Default       |
+|--------------------------------|------------------------------------------------------------------------|---------------|
+|`ADNS9800_CLOCK_SPEED`          | (Optional) Sets the clock speed that the sensor runs at.               | `2000000`     |
+|`ADNS9800_SPI_LSBFIRST`         | (Optional) Sets the Least/Most Significant Byte First setting for SPI. | `false`       |
+|`ADNS9800_SPI_MODE`             | (Optional) Sets the SPI Mode for the sensor.                           | `3`           |
+|`ADNS9800_SPI_DIVISOR`          | (Optional) Sets the SPI Divisor used for SPI communication.            | _varies_      |
+|`ADNS9800_CS_PIN`               | (Required) Sets the Cable Select pin connected to the sensor.          | _not defined_ |
 
 
 The CPI range is 800-8200, in increments of 200. Defaults to 1800 CPI. 
@@ -69,7 +69,7 @@ The Analog Joystick is an analog (ADC) driven sensor.  There are a variety of jo
 |`ANALOG_JOYSTICK_AXIS_MAX`        | (Optional) Sets the upper range to be considered movement.                 | `1023`        |
 |`ANALOG_JOYSTICK_SPEED_REGULATOR` | (Optional) The divisor used to slow down movement. (lower makes it faster) | `20`          |
 |`ANALOG_JOYSTICK_READ_INTERVAL`   | (Optional) The interval in milliseconds between reads.                     | `10`          |
-|`ANALOG_JOYSTICK_SPEED_MAX`       | (Optional) The maxiumum value used for motion.                             | `2`           |
+|`ANALOG_JOYSTICK_SPEED_MAX`       | (Optional) The maximum value used for motion.                              | `2`           |
 |`ANALOG_JOYSTICK_CLICK_PIN`       | (Optional) The pin wired up to the press switch of the analog stick.       | _not defined_ |
 
 
@@ -127,11 +127,10 @@ The Pimoroni Trackball module is a I2C based breakout board with an RGB enable t
 | Setting                             | Description                                                                        | Default |
 |-------------------------------------|------------------------------------------------------------------------------------|---------|
 |`PIMORONI_TRACKBALL_ADDRESS`         | (Required) Sets the I2C Address for the Pimoroni Trackball.                        | `0x0A`  |
-|`PIMORONI_TRACKBALL_TIMEOUT`         | (Optional) The timeout for i2c communication with the trackpad in milliseconds.    | `100`   |
-|`PIMORONI_TRACKBALL_INTERVAL_MS`     | (Optional) The update/read interval for the sensor in milliseconds.                | `8`     |
+|`PIMORONI_TRACKBALL_TIMEOUT`         | (Optional) The timeout for i2c communication with the trackball in milliseconds.   | `100`   |
 |`PIMORONI_TRACKBALL_SCALE`           | (Optional) The multiplier used to generate reports from the sensor.                | `5`     |
 |`PIMORONI_TRACKBALL_DEBOUNCE_CYCLES` | (Optional) The number of scan cycles used for debouncing on the ball press.        | `20`    |
-|`PIMORONI_TRACKBALL_ERROR_COUNT`     | (Optional) Specifies the number of read/write errors until the sensor is disabled. | `10`  |
+|`PIMORONI_TRACKBALL_ERROR_COUNT`     | (Optional) Specifies the number of read/write errors until the sensor is disabled. | `10`    |
 
 ### PMW 3360 Sensor
 
@@ -145,20 +144,50 @@ The PMW 3360 is an SPI driven optical sensor, that uses a built in IR LED for su
 
 | Setting                     | Description                                                                                | Default       |
 |-----------------------------|--------------------------------------------------------------------------------------------|---------------|
-|`PMW3360_CS_PIN`             | (Required) Sets the Cable Select pin connected to the sensor.                              | _not defined_ |
-|`PMW3360_CLOCK_SPEED`        | (Optional) Sets the clock speed that the sensor runs at.                                   | `2000000`     |
-|`PMW3360_SPI_LSBFIRST`       | (Optional) Sets the Least/Most Significant Byte First setting for SPI.                     | `false`       |
-|`PMW3360_SPI_MODE`           | (Optional) Sets the SPI Mode for the sensor.                                               | `3`           |
-|`PMW3360_SPI_DIVISOR`        | (Optional) Sets the SPI Divisor used for SPI communication.                                | _varies_      |
-|`PMW3360_LIFTOFF_DISTANCE`   | (Optional) Sets the lift off distance at run time                                          | `0x02`        |
-|`ROTATIONAL_TRANSFORM_ANGLE` | (Optional) Allows for the sensor data to be rotated +/- 30 degrees directly in the sensor. | `0`           |
+|`PMW3360_CS_PIN`                 | (Required) Sets the Cable Select pin connected to the sensor.                              | _not defined_ |
+|`PMW3360_CLOCK_SPEED`            | (Optional) Sets the clock speed that the sensor runs at.                                   | `2000000`     |
+|`PMW3360_SPI_LSBFIRST`           | (Optional) Sets the Least/Most Significant Byte First setting for SPI.                     | `false`       |
+|`PMW3360_SPI_MODE`               | (Optional) Sets the SPI Mode for the sensor.                                               | `3`           |
+|`PMW3360_SPI_DIVISOR`            | (Optional) Sets the SPI Divisor used for SPI communication.                                | _varies_      |
+|`PMW3360_LIFTOFF_DISTANCE`       | (Optional) Sets the lift off distance at run time                                          | `0x02`        |
+|`ROTATIONAL_TRANSFORM_ANGLE`     | (Optional) Allows for the sensor data to be rotated +/- 127 degrees directly in the sensor.| `0`           |
+|`PMW3360_FIRMWARE_UPLOAD_FAST`   | (Optional) Skips the 15us wait between firmware blocks.                                    | _not defined_ |
 
 The CPI range is 100-12000, in increments of 100. Defaults to 1600 CPI.
 
+### PMW 3389 Sensor
+
+To use the PMW 3389 sensor, add this to your `rules.mk`
+
+```make
+POINTING_DEVICE_DRIVER = pmw3389
+```
+
+The PMW 3389 is an SPI driven optical sensor, that uses a built in IR LED for surface tracking.
+
+| Setting                         | Description                                                                                | Default       |
+|---------------------------------|--------------------------------------------------------------------------------------------|---------------|
+|`PMW3389_CS_PIN`                 | (Required) Sets the Cable Select pin connected to the sensor.                              | _not defined_ |
+|`PMW3389_CLOCK_SPEED`            | (Optional) Sets the clock speed that the sensor runs at.                                   | `2000000`     |
+|`PMW3389_SPI_LSBFIRST`           | (Optional) Sets the Least/Most Significant Byte First setting for SPI.                     | `false`       |
+|`PMW3389_SPI_MODE`               | (Optional) Sets the SPI Mode for the sensor.                                               | `3`           |
+|`PMW3389_SPI_DIVISOR`            | (Optional) Sets the SPI Divisor used for SPI communication.                                | _varies_      |
+|`PMW3389_LIFTOFF_DISTANCE`       | (Optional) Sets the lift off distance at run time                                          | `0x02`        |
+|`ROTATIONAL_TRANSFORM_ANGLE`     | (Optional) Allows for the sensor data to be rotated +/- 30 degrees directly in the sensor. | `0`           |
+|`PMW3389_FIRMWARE_UPLOAD_FAST`   | (Optional) Skips the 15us wait between firmware blocks.                                    | _not defined_ |
+
+The CPI range is 50-16000, in increments of 50. Defaults to 2000 CPI.
+
 
 ### Custom Driver
 
-If you have a sensor type that isn't supported here, you can manually implement it, by adding these functions (with the correct implementation for your device):
+If you have a sensor type that isn't supported above, a custom option is available by adding the following to your `rules.mk`
+
+```make
+POINTING_DEVICE_DRIVER = custom
+```
+
+Using the custom driver will require implementing the following functions:
 
 ```c
 void           pointing_device_driver_init(void) {}
@@ -171,14 +200,35 @@ void           pointing_device_driver_set_cpi(uint16_t cpi) {}
 
 ## Common Configuration
 
-| Setting                       | Description                                                           | Default       |
-|-------------------------------|-----------------------------------------------------------------------|---------------|
-|`POINTING_DEVICE_ROTATION_90`  | (Optional) Rotates the X and Y data by  90 degrees.                   | _not defined_ |
-|`POINTING_DEVICE_ROTATION_180` | (Optional) Rotates the X and Y data by 180 degrees.                   | _not defined_ |
-|`POINTING_DEVICE_ROTATION_270` | (Optional) Rotates the X and Y data by 270 degrees.                   | _not defined_ |
-|`POINTING_DEVICE_INVERT_X`     | (Optional) Inverts the X axis report.                                 | _not defined_ |
-|`POINTING_DEVICE_INVERT_Y`     | (Optional) Inverts the Y axis report.                                 | _not defined_ |
-|`POINTING_DEVICE_MOTION_PIN`   | (Optional) If supported, will only read from sensor if pin is active. | _not defined_ |
+| Setting                          | Description                                                           | Default           |
+|----------------------------------|-----------------------------------------------------------------------|-------------------|
+|`POINTING_DEVICE_ROTATION_90`     | (Optional) Rotates the X and Y data by  90 degrees.                   | _not defined_     |
+|`POINTING_DEVICE_ROTATION_180`    | (Optional) Rotates the X and Y data by 180 degrees.                   | _not defined_     |
+|`POINTING_DEVICE_ROTATION_270`    | (Optional) Rotates the X and Y data by 270 degrees.                   | _not defined_     |
+|`POINTING_DEVICE_INVERT_X`        | (Optional) Inverts the X axis report.                                 | _not defined_     |
+|`POINTING_DEVICE_INVERT_Y`        | (Optional) Inverts the Y axis report.                                 | _not defined_     |
+|`POINTING_DEVICE_MOTION_PIN`      | (Optional) If supported, will only read from sensor if pin is active. | _not defined_     |
+|`POINTING_DEVICE_TASK_THROTTLE_MS`      | (Optional) Limits the frequency that the sensor is polled for motion. | _not defined_     |
+
+!> When using `SPLIT_POINTING_ENABLE` the `POINTING_DEVICE_MOTION_PIN` functionality is not supported and `POINTING_DEVICE_TASK_THROTTLE_MS` will default to `1`. Increasing this value will increase transport performance at the cost of possible mouse responsiveness.
+
+
+## Split Keyboard Configuration
+
+The following configuration options are only available when using `SPLIT_POINTING_ENABLE` see [data sync options](feature_split_keyboard.md?id=data-sync-options). The rotation and invert `*_RIGHT` options are only used with `POINTING_DEVICE_COMBINED`. If using `POINTING_DEVICE_LEFT` or `POINTING_DEVICE_RIGHT` use the common configuration above to configure your pointing device.
+
+| Setting                                | Description                                                           | Default       |
+|----------------------------------------|-----------------------------------------------------------------------|---------------|
+|`POINTING_DEVICE_LEFT`                  | Pointing device on the left side (Required - pick one only)           | _not defined_ |
+|`POINTING_DEVICE_RIGHT`                 | Pointing device on the right side (Required - pick one only)          | _not defined_ |
+|`POINTING_DEVICE_COMBINED`              | Pointing device on both sides (Required - pick one only)              | _not defined_ |
+|`POINTING_DEVICE_ROTATION_90_RIGHT`     | (Optional) Rotates the X and Y data by  90 degrees.                   | _not defined_ |
+|`POINTING_DEVICE_ROTATION_180_RIGHT`    | (Optional) Rotates the X and Y data by 180 degrees.                   | _not defined_ |
+|`POINTING_DEVICE_ROTATION_270_RIGHT`    | (Optional) Rotates the X and Y data by 270 degrees.                   | _not defined_ |
+|`POINTING_DEVICE_INVERT_X_RIGHT`        | (Optional) Inverts the X axis report.                                 | _not defined_ |
+|`POINTING_DEVICE_INVERT_Y_RIGHT`        | (Optional) Inverts the Y axis report.                                 | _not defined_ |
+
+!> If there is a `_RIGHT` configuration option or callback, the [common configuration](feature_pointing_device.md?id=common-configuration) option will work for the left. For correct left/right detection you should setup a [handedness option](feature_split_keyboard?id=setting-handedness), `EE_HANDS` is usually a good option for an existing board that doesn't do handedness by hardware.
 
 
 ## Callbacks and Functions 
@@ -188,7 +238,7 @@ void           pointing_device_driver_set_cpi(uint16_t cpi) {}
 | `pointing_device_init_kb(void)`                            | Callback to allow for keyboard level initialization. Useful for additional hardware sensors.                  |
 | `pointing_device_init_user(void)`                          | Callback to allow for user level initialization. Useful for additional hardware sensors.                      |
 | `pointing_device_task_kb(mouse_report)`                    | Callback that sends sensor data, so keyboard code can intercept and modify the data.  Returns a mouse report. |
-| `pointing_device_task_user(mouse_report)`                  | Callback that sends sensor data, so user coe can intercept and modify the data.  Returns a mouse report.      |
+| `pointing_device_task_user(mouse_report)`                  | Callback that sends sensor data, so user code can intercept and modify the data.  Returns a mouse report.     |
 | `pointing_device_handle_buttons(buttons, pressed, button)` | Callback to handle hardware button presses. Returns a `uint8_t`.                                              |
 | `pointing_device_get_cpi(void)`                            | Gets the current CPI/DPI setting from the sensor, if supported.                                               |
 | `pointing_device_set_cpi(uint16_t)`                        | Sets the CPI/DPI, if supported.                                                                               |
@@ -196,6 +246,21 @@ void           pointing_device_driver_set_cpi(uint16_t cpi) {}
 | `pointing_device_set_report(mouse_report)`                 | Sets the mouse report to the assigned `mouse_report_t` data structured passed to the function.                | 
 | `pointing_device_send(void)`                               | Sends the current mouse report to the host system.  Function can be replaced.                                 | 
 | `has_mouse_report_changed(old, new)`                       | Compares the old and new `mouse_report_t` data and returns true only if it has changed.                       |
+| `pointing_device_adjust_by_defines(mouse_report)`          | Applies rotations and invert configurations to a raw mouse report.                                             |
+
+
+## Split Keyboard Callbacks and Functions
+
+The combined functions below are only available when using `SPLIT_POINTING_ENABLE` and `POINTING_DEVICE_COMBINED`. The 2 callbacks `pointing_device_task_combined_*` replace the single sided equivalents above. See the [combined pointing devices example](feature_pointing_device.md?id=combined-pointing-devices)
+
+| Function                                                        | Description                                                                                                              |
+|-----------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
+| `pointing_device_set_shared_report(mouse_report)`               | Sets the shared mouse report to the assigned `mouse_report_t` data structured passed to the function.                    |
+| `pointing_device_set_cpi_on_side(bool, uint16_t)`               | Sets the CPI/DPI of one side, if supported. Passing `true` will set the left and `false` the right`                      |
+| `pointing_device_combine_reports(left_report, right_report)`    | Returns a combined mouse_report of left_report and right_report (as a `mouse_report_t` data structure)                   |
+| `pointing_device_task_combined_kb(left_report, right_report)`   | Callback, so keyboard code can intercept and modify the data. Returns a combined mouse report.                           |
+| `pointing_device_task_combined_user(left_report, right_report)` | Callback, so user code can intercept and modify. Returns a combined mouse report using `pointing_device_combine_reports` |
+| `pointing_device_adjust_by_defines_right(mouse_report)`         | Applies right side rotations and invert configurations to a raw mouse report.                                            |
 
 
 # Manipulating Mouse Reports
@@ -274,3 +339,62 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
 ```
 
 This allows you to toggle between scrolling and cursor movement by pressing the DRAG_SCROLL key.  
+
+## Split Examples
+
+The following examples make use the `SPLIT_POINTING_ENABLE` functionality and show how to manipulate the mouse report for a scrolling mode.
+
+### Single Pointing Device
+
+The following example will work with either `POINTING_DEVICE_LEFT` or `POINTING_DEVICE_RIGHT` and enables scrolling mode while on a particular layer.
+
+```c
+
+static bool scrolling_mode = false;
+
+layer_state_t layer_state_set_user(layer_state_t state) {
+    switch (get_highest_layer(state)) {
+        case _RAISE:  // If we're on the _RAISE layer enable scrolling mode
+            scrolling_mode = true;
+            pointing_device_set_cpi(2000);
+            break;
+        default:
+            if (scrolling_mode) {  // check if we were scrolling before and set disable if so
+                scrolling_mode = false;
+                pointing_device_set_cpi(8000);
+            }
+            break;
+    }
+    return state;
+}
+
+report_mouse_t pointing_device_task_user(report_mouse_t mouse_report) {
+    if (scrolling_mode) {
+        mouse_report.h = mouse_report.x;
+        mouse_report.v = mouse_report.y;
+        mouse_report.x = 0;
+        mouse_report.y = 0;
+    }
+    return mouse_report;
+}
+```
+
+### Combined Pointing Devices
+
+The following example requires `POINTING_DEVICE_COMBINED` and sets the left side pointing device to scroll only.
+
+```c
+void keyboard_post_init_user(void) {
+    pointing_device_set_cpi_on_side(true, 1000); //Set cpi on left side to a low value for slower scrolling.
+    pointing_device_set_cpi_on_side(false, 8000); //Set cpi on right side to a reasonable value for mousing.
+}
+
+report_mouse_t pointing_device_task_combined_user(report_mouse_t left_report, report_mouse_t right_report) {
+    left_report.h = left_report.x;
+    left_report.v = left_report.y;
+    left_report.x = 0;
+    left_report.y = 0;
+    return pointing_device_combine_reports(left_report, right_report);
+}
+```
+=======

docs/feature_rgb_matrix.md

@@ -232,6 +232,115 @@ const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = {
 
 Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3737.pdf) and the header file `drivers/led/issi/is31fl3737.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0`, `1` for now).
 
+---
+### IS31FLCOMMON :id=is31flcommon
+
+There is basic support for addressable RGB matrix lighting with a selection of I2C ISSI Lumissil RGB controllers through a shared common driver. To enable it, add this to your `rules.mk`:
+
+```makefile
+RGB_MATRIX_ENABLE = yes
+RGB_MATRIX_DRIVER = <driver name>
+```
+
+Where `<driver name>` is the applicable LED driver chip as below
+
+| Driver Name | Data Sheet | Capability |
+|-------------|------------|------------|
+| `IS31FL3742A` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3742A_DS.pdf) | 60 RGB, 30x6 Matrix |
+| `ISSIFL3743A` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3743A_DS.pdf) | 66 RGB, 18x11 Matrix |
+| `IS31FL3745` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3745_DS.pdf) | 48 RGB, 18x8 Matrix |
+| `IS31FL3746A` | [datasheet](https://www.lumissil.com/assets/pdf/core/IS31FL3746A_DS.pdf) | 24 RGB, 18x4 Matrix |
+
+You can use between 1 and 4 IC's. Do not specify `DRIVER_ADDR_<N>` define for IC's if not present on your keyboard. The `DRIVER_ADDR_1` default assumes that all Address pins on the controller have been connected to GND. Drivers that have SYNC functionality have the default settings to disable if 1 driver. If more than 1 drivers then `DRIVER_ADDR_1` will be set to Master and the remaining ones set to Slave.
+
+Configure the hardware via your `config.h`:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 |
+| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 |
+| `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | |
+| `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | |
+| `DRIVER_ADDR_1` | (Optional) Address for the first RGB driver | |
+| `DRIVER_ADDR_<N>` | (Required) Address for the additional RGB drivers | |
+| `ISSI_SSR_<N>` | (Optional) Configuration for the Spread Spectrum Register | |
+| `ISSI_CONFIGURATION` | (Optional) Configuration for the Configuration Register | |
+| `ISSI_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF |
+| `ISSI_PULLDOWNUP` | (Optional) Configuration for the Pull Up & Pull Down Register | |
+| `ISSI_TEMP` | (Optional) Configuration for the Tempature Register | |
+| `ISSI_PWM_ENABLE` | (Optional) Configuration for the PWM Enable Register | |
+| `ISSI_PWM_SET` | (Optional) Configuration for the PWM Setting Register | |
+| `ISSI_SCAL_RED` | (Optional) Configuration for the RED LEDs in Scaling Registers | 0xFF |
+| `ISSI_SCAL_BLUE` | (Optional) Configuration for the BLUE LEDs in Scaling Registers | 0xFF |
+| `ISSI_SCAL_GREEN` | (Optional) Configuration for the GREEN LEDs in Scaling Registers | 0xFF |
+| `ISSI_MANUAL_SCALING` | (Optional) If you wish to configure the Scaling Registers manually | |
+
+
+Defaults
+
+| Variable | IS31FL3742A | IS31FL3743A | IS31FL3745 | IS31FL3746 |
+|----------|-------------|-------------|------------|------------|
+| `DRIVER_ADDR_1` | 0b0110000 | 0b0100000 | 0b0100000 | 0b1100000 |
+| `ISSI_SSR_1` | 0x00 | 0x00 / 0x60 | 0x00 / 0xC0 | 0x00 |
+| `ISSI_SSR_<2-4>` | 0x00 | 0x40 | 0x80 | 0x00 |
+| `ISSI_CONFIGURATION` | 0x31 | 0x01 | 0x31 | 0x01 |
+| `ISSI_PULLDOWNUP` | 0x55 | 0x33 | 0x33 | 0x33 |
+| `ISSI_TEMP` | N/A | 0x00 | 0x00 | 0x00 |
+| `ISSI_PWM_ENABLE` | N/A | N/A | N/A | 0x00 |
+| `ISSI_PWM_SET` | 0x00 | N/A | N/A | 0x00 |
+
+Here is an example using 2 drivers.
+
+```c
+#define DRIVER_ADDR_2 0b0100001
+
+#define DRIVER_COUNT 2
+#define DRIVER_1_LED_TOTAL 66
+#define DRIVER_2_LED_TOTAL 42
+#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)
+```
+
+!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`.
+
+Currently only 4 drivers are supported, but it would be trivial to support for more. Note that using a combination of different drivers is not supported. All drivers must be of the same model.
+
+Define these arrays listing all the LEDs in your `<keyboard>.c`:
+
+```c
+const is31_led __flash g_is31_leds[DRIVER_LED_TOTAL] = {
+/* Refer to IS31 manual for these locations
+ *   driver
+ *   |  R location
+ *   |  |        G location
+ *   |  |        |        B location
+ *   |  |        |        | */
+    {0, CS1_SW1, CS2_SW1, CS3_SW1},
+    ....
+}
+```
+
+Where `CSx_SWx` is the location of the LED in the matrix defined by the datasheet. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` for now).
+
+`ISSI_MANUAL_SCALING` is used to override the Scaling for individual LED's. By default they will be set as per `ISSI_SCAL_<colour>`. In `config.h` set how many LED's you want to manually set scaling for.
+Eg `#define ISSI_MANUAL_SCALING 3`
+
+Then Define the array listing all the LEDs you want to override in your `<keyboard>.c`:
+
+```c
+const is31_led __flash g_is31_scaling[ISSI_MANUAL_SCALING] = {
+ *   LED Index
+ *   |  R scaling
+ *   |  |    G scaling
+ *   |  |    |    B scaling
+ *   |  |    |    | */
+    {5, 120, 155, 167},
+    {9, 120, 155, 167},
+    ....
+}
+```
+
+Where LED Index is the position of the LED in the `g_is31_leds` array. The `scaling` value between 0 and 255 to be written to the Scaling Register.
+
 ---
 
 ### WS2812 :id=ws2812
@@ -417,6 +526,9 @@ All RGB keycodes are currently shared with the RGBLIGHT system:
 
 `RGB_MODE_PLAIN`, `RGB_MODE_BREATHE`, `RGB_MODE_RAINBOW`, and `RGB_MODE_SWIRL` are the only ones that are mapped properly. The rest don't have a direct equivalent, and are not mapped.
 
+?> `RGB_*` keycodes cannot be used with functions like `tap_code16(RGB_HUD)` as they're not USB HID keycodes. If you wish to replicate similar behaviour in custom code within your firmware (e.g. inside `encoder_update_user()` or `process_record_user()`), the equivalent [RGB functions](#functions-idfunctions) should be used instead.
+
+
 !> By default, if you have both the [RGB Light](feature_rgblight.md) and the RGB Matrix feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature.
 
 ## RGB Matrix Effects :id=rgb-matrix-effects
@@ -454,6 +566,7 @@ enum rgb_matrix_effects {
     RGB_MATRIX_HUE_PENDULUM,        // Hue shifts up a slight ammount in a wave to the right, then back to the left
     RGB_MATRIX_HUE_WAVE,            // Hue shifts up a slight ammount and then back down in a wave to the right
     RGB_MATRIX_PIXEL_FRACTAL,       // Single hue fractal filled keys pulsing horizontally out to edges
+    RGB_MATRIX_PIXEL_FLOW,          // Pulsing RGB flow along LED wiring with random hues
     RGB_MATRIX_PIXEL_RAIN,          // Randomly light keys with random hues
 #if define(RGB_MATRIX_FRAMEBUFFER_EFFECTS)
     RGB_MATRIX_TYPING_HEATMAP,      // How hot is your WPM!
@@ -509,6 +622,7 @@ You can enable a single effect by defining `ENABLE_[EFFECT_NAME]` in your `confi
 |`#define ENABLE_RGB_MATRIX_HUE_PENDULUM`              |Enables `RGB_MATRIX_HUE_PENDULUM`             |
 |`#define ENABLE_RGB_MATRIX_HUE_WAVE`                  |Enables `RGB_MATRIX_HUE_WAVE `                |
 |`#define ENABLE_RGB_MATRIX_PIXEL_FRACTAL`             |Enables `RGB_MATRIX_PIXEL_FRACTAL`            |
+|`#define ENABLE_RGB_MATRIX_PIXEL_FLOW`                |Enables `RGB_MATRIX_PIXEL_FLOW`               |
 |`#define ENABLE_RGB_MATRIX_PIXEL_RAIN`                |Enables `RGB_MATRIX_PIXEL_RAIN`               |
 
 ?> These modes don't require any additional defines.
@@ -554,9 +668,7 @@ In order to change the delay of temperature decrease define
 
 ## Custom RGB Matrix Effects :id=custom-rgb-matrix-effects
 
-By setting `RGB_MATRIX_CUSTOM_USER = yes` in `rules.mk`, new effects can be defined directly from your keymap or userspace, without having to edit any QMK core files.
-
-To declare new effects, create a `rgb_matrix_user.inc` file in the user keymap directory or userspace folder.
+By setting `RGB_MATRIX_CUSTOM_USER = yes` in `rules.mk`, new effects can be defined directly from your keymap or userspace, without having to edit any QMK core files. To declare new effects, create a `rgb_matrix_user.inc` file in the user keymap directory or userspace folder.
 
 ?> Hardware maintainers who want to limit custom effects to a specific keyboard can create a `rgb_matrix_kb.inc` file in the root of the keyboard directory, and add `RGB_MATRIX_CUSTOM_KB = yes` to the keyboard level `rules.mk`.
 
@@ -706,6 +818,7 @@ Where `28` is an unused index from `eeconfig.h`.
 |`rgb_matrix_decrease_speed_noeeprom()`      |Decrease the speed of the animations (not written to EEPROM) |
 |`rgb_matrix_set_speed(speed)`               |Set the speed of the animations to the given value where `speed` is between 0 and 255 |
 |`rgb_matrix_set_speed_noeeprom(speed)`      |Set the speed of the animations to the given value where `speed` is between 0 and 255 (not written to EEPROM) |
+|`rgb_matrix_reload_from_eeprom()`           |Reload the effect configuration (enabled, mode and color) from EEPROM |
 
 ### Change Color :id=change-color
 |Function                                    |Description  |
@@ -809,6 +922,8 @@ void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) {
 }
 ```
 
+?> Split keyboards will require layer state data syncing with `#define SPLIT_LAYER_STATE_ENABLE`. See [Data Sync Options](feature_split_keyboard?id=data-sync-options) for more details.
+
 #### Examples :id=indicator-examples
 
 This example sets the modifiers to be a specific color based on the layer state.  You can use a switch case here, instead, if you would like.  This uses HSV and then converts to RGB, because this allows the brightness to be limited (important when using the WS2812 driver).
@@ -848,6 +963,8 @@ void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) {
 }
 ```
 
+!> RGB indicators on split keyboards will require state information synced to the slave half (e.g. `#define SPLIT_LAYER_STATE_ENABLE`). See [data sync options](feature_split_keyboard.md#data-sync-options) for more details.
+
 #### Indicators without RGB Matrix Effect
 
 If you want to just use RGB indicators without RGB matrix effect, it is not possible to disable the latter because toggling RGB off will disable everything. You can workaround it with solid effect and colors off using this init function:

docs/feature_rgblight.md

@@ -76,9 +76,11 @@ Changing the **Value** sets the overall brightness.<br>
 |`RGB_MODE_RGBTEST` |`RGB_M_T` |Red, Green, Blue test animation mode                                |
 |`RGB_MODE_TWINKLE` |`RGB_M_TW`|Twinkle animation mode                                              |
 
-!> By default, if you have both the RGB Light and the [RGB Matrix](feature_rgb_matrix.md) feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature.
+?> `RGB_*` keycodes cannot be used with functions like `tap_code16(RGB_HUI)` as they're not USB HID keycodes. If you wish to replicate similar behaviour in custom code within your firmware (e.g. inside `encoder_update_user()` or `process_record_user()`), the equivalent [RGB functions](#functions) should be used instead.
 
 
+!> By default, if you have both the RGB Light and the [RGB Matrix](feature_rgb_matrix.md) feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature.
+
 ## Configuration
 
 Your RGB lighting can be configured by placing these `#define`s in your `config.h`:
@@ -202,7 +204,7 @@ const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64};
 
 ## Lighting Layers
 
-?> **Note:** Lighting Layers is an RGB Light feature, it will not work for RGB Matrix. See [RGB Matrix Indicators](feature_rgb_matrix.md?indicators) for details on how to do so.
+?> **Note:** Lighting Layers is an RGB Light feature, it will not work for RGB Matrix. See [RGB Matrix Indicators](feature_rgb_matrix.md#indicators) for details on how to do so.
 
 By including `#define RGBLIGHT_LAYERS` in your `config.h` file you can enable lighting layers. These make
 it easy to use your underglow LEDs as status indicators to show which keyboard layer is currently active, or the state of caps lock, all without disrupting any animations. [Here's a video](https://youtu.be/uLGE1epbmdY) showing an example of what you can do.
@@ -322,6 +324,8 @@ void post_process_record_user(uint16_t keycode, keyrecord_t *record) {
 ```
 would turn the layer 0 (or 1) on and off again three times when `DEBUG` is pressed.
 
+!> Lighting layers on split keyboards will require layer state synced to the slave half (e.g. `#define SPLIT_LAYER_STATE_ENABLE`). See [data sync options](feature_split_keyboard.md#data-sync-options) for more details.
+
 ### Overriding RGB Lighting on/off status
 
 Normally lighting layers are not shown when RGB Lighting is disabled (e.g. with `RGB_TOG` keycode). If you would like lighting layers to work even when the RGB Lighting is otherwise off, add `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF` to your `config.h`.
@@ -344,7 +348,7 @@ If you need to change your RGB lighting in code, for example in a macro to chang
 ### Low level Functions
 |Function                                    |Description                                |
 |--------------------------------------------|-------------------------------------------|
-|`rgblight_set()`                            |Flash out led buffers to LEDs              |
+|`rgblight_set()`                            |Flush out led buffers to LEDs              |
 |`rgblight_set_clipping_range(pos, num)`     |Set clipping Range. see [Clipping Range](#clipping-range) |
 
 Example:

docs/feature_split_keyboard.md

@@ -130,14 +130,17 @@ To enable this method, add the following to your `config.h` file:
 #define EE_HANDS
 ```
 
-However, you'll have to flash the EEPROM files for the correct hand to each controller.  You can do this manually, or there are targets for avrdude and dfu to do this, while flashing the firmware: 
+Next, you will have to flash the EEPROM files once for the correct hand to the controller on each halve. You can do this manually with the following bootloader targets while flashing the firmware:
 
-* `:avrdude-split-left`
-* `:avrdude-split-right`
-* `:dfu-split-left`
-* `:dfu-split-right`
-* `:dfu-util-split-left`
-* `:dfu-util-split-right`
+* AVR controllers with the Caterina bootloader (e.g. Pro Micro):
+  * `:avrdude-split-left`
+  * `:avrdude-split-right`
+* AVR controllers with the stock Amtel DFU or DFU compatible bootloader (e.g. Elite-C):
+  * `:dfu-split-left`
+  * `:dfu-split-right`
+* ARM controllers with a DFU compatible bootloader (e.g. Proton-C):
+  * `:dfu-util-split-left`
+  * `:dfu-util-split-right`
 
 Example:
 
@@ -145,9 +148,13 @@ Example:
 make crkbd:default:avrdude-split-left
 ```
 
+?> ARM controllers using `dfu-util` will require an EEPROM reset after setting handedness. This can be done using the `EEP_RST` keycode or [Bootmagic Lite](feature_bootmagic.md). Controllers using emulated EEPROM will always require handedness parameter when flashing the firmware.
+
+?> [QMK Toolbox]() can also be used to flash EEPROM handedness files. Place the controller in bootloader mode and select menu option Tools -> EEPROM -> Set Left/Right Hand
+
 This setting is not changed when re-initializing the EEPROM using the `EEP_RST` key, or using the `eeconfig_init()` function.  However, if you reset the EEPROM outside of the firmware's built in options (such as flashing a file that overwrites the `EEPROM`, like how the [QMK Toolbox]()'s "Reset EEPROM" button works), you'll need to re-flash the controller with the `EEPROM` files. 
 
-You can find the `EEPROM` files in the QMK firmware repo, [here](https://github.com/qmk/qmk_firmware/tree/master/quantum/split_common). 
+You can find the `EEPROM` files in the QMK firmware repo, [here](https://github.com/qmk/qmk_firmware/tree/master/quantum/split_common).
 
 #### Handedness by `#define`
 
@@ -266,6 +273,14 @@ This enables transmitting the current OLED on/off status to the slave side of th
 
 This enables transmitting the current ST7565 on/off status to the slave side of the split keyboard. The purpose of this feature is to support state (on/off state only) syncing.
 
+```c
+#define SPLIT_POINTING_ENABLE
+```
+
+This enables transmitting the pointing device status to the master side of the split keyboard. The purpose of this feature is to enable use pointing devices on the slave side. 
+
+!> There is additional required configuration for `SPLIT_POINTING_ENABLE` outlined in the [pointing device documentation](feature_pointing_device.md?id=split-keyboard-configuration).
+
 ### Custom data sync between sides :id=custom-data-sync
 
 QMK's split transport allows for arbitrary data transactions at both the keyboard and user levels. This is modelled on a remote procedure call, with the master invoking a function on the slave side, with the ability to send data from master to slave, process it slave side, and send data back from slave to master.

docs/feature_tap_dance.md

@@ -243,7 +243,7 @@ Now, at the bottom of your `keymap.c` file, you'll need to add the following:
  *
  * How to figure out tap dance state: interrupted and pressed.
  *
- * Interrupted: If the state of a dance dance is "interrupted", that means that another key has been hit
+ * Interrupted: If the state of a dance is "interrupted", that means that another key has been hit
  *  under the tapping term. This is typically indicitive that you are trying to "tap" the key.
  *
  * Pressed: Whether or not the key is still being pressed. If this value is true, that means the tapping term

docs/feature_wpm.md

@@ -16,7 +16,7 @@ For split keyboards using soft serial, the computed WPM score will be available
 | `WPM_ALLOW_COUNT_REGRESSION` | _Not defined_ | If defined allows the WPM to be decreased when hitting Delete or Backspace               |
 | `WPM_UNFILTERED`             | _Not defined_ | If undefined (the default), WPM values will be smoothed to avoid sudden changes in value |
 | `WPM_SAMPLE_SECONDS`         | `5`           | This defines how many seconds of typing to average, when calculating WPM                 |
-| `WPM_SAMPLE_PERIODS`         | `50`          | This defines how many sampling periods to use when calculating WPM                       |
+| `WPM_SAMPLE_PERIODS`         | `25`          | This defines how many sampling periods to use when calculating WPM                       |
 | `WPM_LAUNCH_CONTROL`         | _Not defined_ | If defined, WPM values will be calculated using partial buffers when typing begins       |
 
 'WPM_UNFILTERED' is potentially useful if you're filtering data in some other way (and also because it reduces the code required for the WPM feature), or if reducing measurement latency to a minimum is important for you.

docs/flash_driver.md

@@ -0,0 +1,24 @@
+# FLASH Driver Configuration :id=flash-driver-configuration
+
+The FLASH driver can be swapped out depending on the needs of the keyboard, or whether extra hardware is present.
+
+Driver                             | Description
+-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+`FLASH_DRIVER = spi`               | Supports writing to almost all NOR Flash chips. See the driver section below.
+
+
+## SPI FLASH Driver Configuration :id=spi-flash-driver-configuration
+
+Currently QMK supports almost all NOR Flash chips over SPI. As such, requires a working spi_master driver configuration. You can override the driver configuration via your config.h:
+
+`config.h` override                            | Description                                                                          | Default Value
+-----------------------------------------------|--------------------------------------------------------------------------------------|-----------------
+`#define EXTERNAL_FLASH_SPI_SLAVE_SELECT_PIN`  | SPI Slave select pin in order to inform that the FLASH is currently being addressed  | _none_
+`#define EXTERNAL_FLASH_SPI_CLOCK_DIVISOR`     | Clock divisor used to divide the peripheral clock to derive the SPI frequency        | `8`
+`#define EXTERNAL_FLASH_PAGE_SIZE`             | The Page size of the FLASH in bytes, as specified in the datasheet                   | `256`
+`#define EXTERNAL_FLASH_SECTOR_SIZE`           | The sector size of the FLASH in bytes, as specified in the datasheet                 | `(4 * 1024)`
+`#define EXTERNAL_FLASH_BLOCK_SIZE`            | The block size of the FLASH in bytes, as specified in the datasheet                  | `(64 * 1024)`
+`#define EXTERNAL_FLASH_SIZE`                  | The total size of the FLASH in bytes, as specified in the datasheet                  | `(512 * 1024)`
+`#define EXTERNAL_FLASH_ADDRESS_SIZE`          | The Flash address size in bytes, as specified in datasheet                           | `3`
+
+!> All the above default configurations are based on MX25L4006E NOR Flash.

docs/hardware_avr.md

@@ -1,182 +0,0 @@
-# Keyboards with AVR Processors
-
-This page describes the support for for AVR processors in QMK. AVR processors include the atmega32u4, atmega32u2, at90usb1286, and other processors from Atmel Corporation. AVR processors are 8-bit MCUs that are designed to be easy to work with. The most common AVR processors in keyboards have on-board USB and plenty of GPIO for supporting large keyboard matrices. They are the most popular MCU for use in keyboards today.
-
-If you have not yet you should read the [Keyboard Guidelines](hardware_keyboard_guidelines.md) to get a sense of how keyboards fit into QMK.
-
-## Adding Your AVR Keyboard to QMK
-
-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 `qmk new-keyboard`:
-
-```
-$ qmk new-keyboard
-Ψ Generating a new QMK keyboard directory
-
-Keyboard Name: mycoolkeeb
-Keyboard Type:
-        1. avr
-        2. ps2avrgb
-Please enter your choice:  [1]
-Your Name: [John Smith]
-Ψ Copying base template files...
-Ψ Copying avr template files...
-Ψ Renaming keyboard.[ch] to mycoolkeeb.[ch]...
-Ψ Replacing %YEAR% with 2021...
-Ψ Replacing %KEYBOARD% with mycoolkeeb...
-Ψ Replacing %YOUR_NAME% with John Smith...
-
-Ψ Created a new keyboard called mycoolkeeb.
-Ψ To start working on things, `cd` into keyboards/mycoolkeeb,
-Ψ or open the directory in your preferred text editor.
-```
-
-This will create all the files needed to support your new keyboard, and populate the settings with default values. Now you just need to customize it for your keyboard.
-
-## `readme.md`
-
-This is where you'll describe your keyboard. Please follow the [Keyboard Readme Template](documentation_templates.md#keyboard-readmemd-template) when writing your `readme.md`. You're encouraged to place an image at the top of your `readme.md`, please use an external service such as [Imgur](https://imgur.com) to host the images.
-
-## `<keyboard>.c`
-
-This is where all the custom logic for your keyboard goes. Many keyboards do not need to put anything at all in here. You can learn more about writing custom logic in [Custom Quantum Functions](custom_quantum_functions.md).
-
-## `<keyboard>.h`
-
-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         \
-) {                      \
-    { k00, k01,   k02 }, \
-    { k10, KC_NO, k11 }, \
-}
-```
-
-The first half of the `LAYOUT` pre-processor macro defines the physical arrangement of keys. The second half of the macro defines the matrix the switches are connected to. This allows you to have a physical arrangement of keys that differs from the wiring matrix.
-
-Each of the `k__` variables needs to be unique, and typically they follow the format `k<row><col>`.
-
-The physical matrix (the second half) must have a number of rows equaling `MATRIX_ROWS`, and each row must have exactly `MATRIX_COLS` elements in it. If you do not have this many physical keys you can use `KC_NO` to fill in the blank spots.
-
-## `config.h`
-
-The `config.h` file is where you configure the hardware and feature set for your keyboard. There are a lot of options that can be placed in that file, too many to list there. For a complete overview of available options see the [Config Options](config_options.md) page.
-
-### Hardware Configuration
-
-
-At the top of the `config.h` you'll find USB related settings. These control how your keyboard appears to the Operating System. If you don't have a good reason to change you should leave the `VENDOR_ID` as `0xFEED`. For the `PRODUCT_ID` you should pick a number that is not yet in use.
-
-Do change the `MANUFACTURER` and `PRODUCT` lines to accurately reflect your keyboard.
-
-```c
-#define VENDOR_ID       0xFEED
-#define PRODUCT_ID      0x6060
-#define DEVICE_VER      0x0001
-#define MANUFACTURER    You
-#define PRODUCT         my_awesome_keyboard
-```
-
-?> Windows and macOS will display the `MANUFACTURER` and `PRODUCT` in the list of USB devices. `lsusb` on Linux instead prefers the values in the list maintained by the [USB ID Repository](http://www.linux-usb.org/usb-ids.html). By default, it will only use `MANUFACTURER` and `PRODUCT` if the list does not contain that `VENDOR_ID` / `PRODUCT_ID`. `sudo lsusb -v` will show the values reported by the device, and they are also present in kernel logs after plugging it in.
-
-### 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
-```
-
-The number of `MATRIX_ROW_PINS` entries must be the same as the number you assigned to `MATRIX_ROWS`, and likewise for `MATRIX_COL_PINS` and `MATRIX_COLS`. You do not have to specify `UNUSED_PINS`, but you can if you want to document what pins are open.
-
-Finally, you can specify the direction your diodes point. This can be `COL2ROW` or `ROW2COL`.
-
-```c
-#define DIODE_DIRECTION COL2ROW
-```
-
-#### Direct Pin Matrix
-To configure a keyboard where each switch is connected to a separate pin and ground instead of sharing row and column pins, use `DIRECT_PINS`. The mapping defines the pins of each switch in rows and columns, from left to right. Must conform to the sizes within `MATRIX_ROWS` and `MATRIX_COLS`, use `NO_PIN` to fill in blank spaces. Overrides the behaviour of `DIODE_DIRECTION`, `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`.
-
-```c
-// #define MATRIX_ROW_PINS { D0, D5 }
-// #define MATRIX_COL_PINS { F1, F0, B0 }
-#define DIRECT_PINS { \
-    { F1, E6, B0, B2, B3 }, \
-    { F5, F0, B1, B7, D2 }, \
-    { F6, F7, C7, D5, D3 }, \
-    { B5, C6, B6, NO_PIN, NO_PIN } \
-}
-#define UNUSED_PINS
-
-/* COL2ROW, ROW2COL */
-//#define DIODE_DIRECTION
-```
-
-### Backlight Configuration
-
-QMK supports backlighting on most GPIO pins. A select few of these can be driven by the MCU in hardware. 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
-```
-
-### Other Configuration Options
-
-There are a lot of features that can be configured or tuned in `config.h`. You should see the [Config Options](config_options.md) page for more details.
-
-## `rules.mk`
-
-You use the `rules.mk` file to tell QMK what files to build and what features to enable. If you are building around an atmega32u4 you can largely leave these defaults alone. If you are using another MCU you may have to tweak some parameters.
-
-### MCU Options
-
-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
-F_USB = $(F_CPU)
-OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT
-```
-
-### 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. 
-
-#### Teensy Bootloader Example
-
-```make
-BOOTLOADER = halfkay
-```
-
-#### Atmel DFU Loader Example
-
-```make
-BOOTLOADER = atmel-dfu
-```
-
-#### Pro Micro Bootloader Example
-
-```make
-BOOTLOADER = caterina
-```
-
-### Build Options
-
-There are a number of features that can be turned on or off in `rules.mk`. See the [Config Options](config_options.md#feature-options) page for a detailed list and description.

docs/hardware_keyboard_guidelines.md

@@ -87,6 +87,7 @@ The `config.h` files can also be placed in sub-folders, and the order in which t
     * `keyboards/top_folder/sub_1/sub_2/config.h`
       * `keyboards/top_folder/sub_1/sub_2/sub_3/config.h`
         * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/config.h`
+          * [`.build/objs_<keyboard>/src/info_config.h`](data_driven_config.md#add-code-to-generate-it) see [Data Driven Configuration](data_driven_config.md)
           * `users/a_user_folder/config.h`
           * `keyboards/top_folder/keymaps/a_keymap/config.h`
         * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/post_config.h`

docs/index.html

@@ -39,7 +39,6 @@
         '/glossary': '/reference_glossary',
         '/key_lock': '/feature_key_lock',
         '/make_instructions': '/getting_started_make_guide',
-        '/porting_your_keyboard_to_qmk': '/hardware_avr',
         '/space_cadet_shift': '/feature_space_cadet_shift',
         '/getting_started_getting_help': '/support',
         '/tap_dance': '/feature_tap_dance',

docs/internals_gpio_control.md

@@ -6,17 +6,19 @@ QMK has a GPIO control abstraction layer which is microcontroller agnostic. This
 
 The following functions provide basic control of GPIOs and are found in `platforms/<platform>/gpio.h`.
 
-|Function                |Description                                       | Old AVR Examples                                | Old ChibiOS/ARM Examples                        |
-|------------------------|--------------------------------------------------|-------------------------------------------------|-------------------------------------------------|
-| `setPinInput(pin)`     | Set pin as input with high impedance (High-Z)    | `DDRB &= ~(1<<2)`                               | `palSetLineMode(pin, PAL_MODE_INPUT)`           |
-| `setPinInputHigh(pin)` | Set pin as input with builtin pull-up resistor   | `DDRB &= ~(1<<2); PORTB \|= (1<<2)`             | `palSetLineMode(pin, PAL_MODE_INPUT_PULLUP)`    |
-| `setPinInputLow(pin)`  | Set pin as input with builtin pull-down resistor | N/A (Not supported on AVR)                      | `palSetLineMode(pin, PAL_MODE_INPUT_PULLDOWN)`  |
-| `setPinOutput(pin)`    | Set pin as output                                | `DDRB \|= (1<<2)`                               | `palSetLineMode(pin, PAL_MODE_OUTPUT_PUSHPULL)` |
-| `writePinHigh(pin)`    | Set pin level as high, assuming it is an output  | `PORTB \|= (1<<2)`                              | `palSetLine(pin)`                               |
-| `writePinLow(pin)`     | Set pin level as low, assuming it is an output   | `PORTB &= ~(1<<2)`                              | `palClearLine(pin)`                             |
-| `writePin(pin, level)` | Set pin level, assuming it is an output          | `(level) ? PORTB \|= (1<<2) : PORTB &= ~(1<<2)` | `(level) ? palSetLine(pin) : palClearLine(pin)` |
-| `readPin(pin)`         | Returns the level of the pin                     | `_SFR_IO8(pin >> 4) & _BV(pin & 0xF)`           | `palReadLine(pin)`                              |
-| `togglePin(pin)`       | Invert pin level, assuming it is an output       | `PORTB ^= (1<<2)`                               | `palToggleLine(pin)`                            |
+| Function                     | Description                                         | Old AVR Examples                                | Old ChibiOS/ARM Examples                         |
+|------------------------------|-----------------------------------------------------|-------------------------------------------------|--------------------------------------------------|
+| `setPinInput(pin)`           | Set pin as input with high impedance (High-Z)       | `DDRB &= ~(1<<2)`                               | `palSetLineMode(pin, PAL_MODE_INPUT)`            |
+| `setPinInputHigh(pin)`       | Set pin as input with builtin pull-up resistor      | `DDRB &= ~(1<<2); PORTB \|= (1<<2)`             | `palSetLineMode(pin, PAL_MODE_INPUT_PULLUP)`     |
+| `setPinInputLow(pin)`        | Set pin as input with builtin pull-down resistor    | N/A (Not supported on AVR)                      | `palSetLineMode(pin, PAL_MODE_INPUT_PULLDOWN)`   |
+| `setPinOutput(pin)`          | Set pin as output (alias of `setPinOutputPushPull`) | `DDRB \|= (1<<2)`                               | `palSetLineMode(pin, PAL_MODE_OUTPUT_PUSHPULL)`  |
+| `setPinOutputPushPull(pin)`  | Set pin as output, push/pull mode                   | `DDRB \|= (1<<2)`                               | `palSetLineMode(pin, PAL_MODE_OUTPUT_PUSHPULL)`  |
+| `setPinOutputOpenDrain(pin)` | Set pin as output, open-drain mode                  | N/A (Not implemented on AVR)                    | `palSetLineMode(pin, PAL_MODE_OUTPUT_OPENDRAIN)` |
+| `writePinHigh(pin)`          | Set pin level as high, assuming it is an output     | `PORTB \|= (1<<2)`                              | `palSetLine(pin)`                                |
+| `writePinLow(pin)`           | Set pin level as low, assuming it is an output      | `PORTB &= ~(1<<2)`                              | `palClearLine(pin)`                              |
+| `writePin(pin, level)`       | Set pin level, assuming it is an output             | `(level) ? PORTB \|= (1<<2) : PORTB &= ~(1<<2)` | `(level) ? palSetLine(pin) : palClearLine(pin)`  |
+| `readPin(pin)`               | Returns the level of the pin                        | `_SFR_IO8(pin >> 4) & _BV(pin & 0xF)`           | `palReadLine(pin)`                               |
+| `togglePin(pin)`             | Invert pin level, assuming it is an output          | `PORTB ^= (1<<2)`                               | `palToggleLine(pin)`                             |
 
 ## Advanced Settings :id=advanced-settings
 

docs/isp_flashing_guide.md

@@ -57,13 +57,33 @@ To use a Teensy 2.0 as an ISP flashing tool, you will first need to load a [spec
 
 !> Note that the `B0` pin on the Teensy should be wired to the `RESET` pin on the keyboard's controller. ***DO NOT*** connect the `RESET` pin on the Teensy to the `RESET` on the keyboard.
 
-### SparkFun PocketAVR / USBtinyISP / USBasp
+### SparkFun PocketAVR / USBtinyISP
 
 [SparkFun PocketAVR](https://www.sparkfun.com/products/9825)  
 [Adafruit USBtinyISP](https://www.adafruit.com/product/46)  
+
+!> SparkFun PocketAVR and USBtinyISP **DO NOT support** AVR chips with more than 64 KiB of flash (e.g., the AT90USB128 series). This limitation is mentioned on the [shop page for SparkFun PocketAVR](https://www.sparkfun.com/products/9825) and in the [FAQ for USBtinyISP](https://learn.adafruit.com/usbtinyisp/f-a-q#faq-2270879). If you try to use one of these programmers with AT90USB128 chips, you will get verification errors from `avrdude`, and the bootloader won't be flashed properly (e.g., see the [issue #3286](https://github.com/qmk/qmk_firmware/issues/3286)).
+
+**AVRDUDE Programmer**: `usbtiny`  
+**AVRDUDE Port**: `usb`
+
+#### Wiring
+
+|ISP      |Keyboard|
+|---------|--------|
+|`VCC`    |`VCC`   |
+|`GND`    |`GND`   |
+|`RST`    |`RESET` |
+|`SCLK`   |`SCLK`  |
+|`MOSI`   |`MOSI`  |
+|`MISO`   |`MISO`  |
+
+
+### USBasp
+
 [Thomas Fischl's USBasp](https://www.fischl.de/usbasp/)
 
-**AVRDUDE Programmer**: `usbtiny` / `usbasp`  
+**AVRDUDE Programmer**: `usbasp`  
 **AVRDUDE Port**: `usb`
 
 #### Wiring

docs/ja/cli_commands.md

@@ -59,7 +59,7 @@ $ qmk compile -km 66_iso
 ```
 $ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
 $ qmk compile
-Ψ Compiling keymap with make make gh60/satan:colemak
+Ψ Compiling keymap with make gh60/satan:colemak
 ...
 ```
 

docs/keycodes.md

@@ -219,11 +219,11 @@ See also: [Basic Keycodes](keycodes_basic.md)
 
 See also: [Quantum Keycodes](quantum_keycodes.md#qmk-keycodes)
 
-|Key           |Aliases  |Description                                            |
-|--------------|---------|-------------------------------------------------------|
-|`RESET`       |         |Put the keyboard into bootloader mode for flashing     |
-|`DEBUG`       |         |Toggle debug mode                                      |
-|`EEPROM_RESET`|`EEP_RST`|Reinitializes the keyboard's EEPROM (persistent memory)|
+|Key              |Aliases  |Description                                            |
+|-----------------|---------|-------------------------------------------------------|
+|`QK_BOOTLOADER`  |`QK_BOOT`|Put the keyboard into bootloader mode for flashing     |
+|`QK_DEBUG_TOGGLE`|`DB_TOGG`|Toggle debug mode                                      |
+|`QK_CLEAR_EEPROM`|`EE_CLR` |Reinitializes the keyboard's EEPROM (persistent memory)|
 
 ## Audio Keys :id=audio-keys
 
@@ -283,9 +283,9 @@ See also: [Dynamic Macros](feature_dynamic_macros.md)
 
 See also: [Grave Escape](feature_grave_esc.md)
 
-|Key        |Aliases  |Description                                                       |
-|-----------|---------|------------------------------------------------------------------|
-|`GRAVE_ESC`|`KC_GESC`|Escape when pressed, <code>&#96;</code> when Shift or GUI are held|
+|Key              |Aliases  |Description                                                       |
+|-----------------|---------|------------------------------------------------------------------|
+|`QK_GRAVE_ESCAPE`|`QK_GESC`|Escape when pressed, <code>&#96;</code> when Shift or GUI are held|
 
 ## Key Lock :id=key-lock
 
@@ -326,6 +326,7 @@ See also: [Magic Keycodes](keycodes_magic.md)
 |----------------------------------|---------|--------------------------------------------------------------------------|
 |`MAGIC_SWAP_CONTROL_CAPSLOCK`     |`CL_SWAP`|Swap Caps Lock and Left Control                                           |
 |`MAGIC_UNSWAP_CONTROL_CAPSLOCK`   |`CL_NORM`|Unswap Caps Lock and Left Control                                         |
+|`MAGIC_TOGGLE_CONTROL_CAPSLOCK`   |`CL_TOGG`|Toggle Caps Lock and Left Control swap                                    |
 |`MAGIC_CAPSLOCK_TO_CONTROL`       |`CL_CTRL`|Treat Caps Lock as Control                                                |
 |`MAGIC_UNCAPSLOCK_TO_CONTROL`     |`CL_CAPS`|Stop treating Caps Lock as Control                                        |
 |`MAGIC_SWAP_LCTL_LGUI`            |`LCG_SWP`|Swap Left Control and GUI                                                 |
@@ -763,7 +764,7 @@ See also: [Unicode Support](feature_unicode.md)
 
 |Key                   |Aliases  |Description                                                     |
 |----------------------|---------|----------------------------------------------------------------|
-|`UC(c)`               |         |Send Unicode code point `c`                                     |
+|`UC(c)`               |         |Send Unicode code point `c`, up to `0x7FFF`                     |
 |`X(i)`                |         |Send Unicode code point at index `i` in `unicode_map`           |
 |`XP(i, j)`            |         |Send Unicode code point at index `i`, or `j` if Shift/Caps is on|
 |`UNICODE_MODE_FORWARD`|`UC_MOD` |Cycle through selected input modes                              |

docs/keycodes_magic.md

@@ -6,6 +6,7 @@
 |----------------------------------|---------|--------------------------------------------------------------------------|
 |`MAGIC_SWAP_CONTROL_CAPSLOCK`     |`CL_SWAP`|Swap Caps Lock and Left Control                                           |
 |`MAGIC_UNSWAP_CONTROL_CAPSLOCK`   |`CL_NORM`|Unswap Caps Lock and Left Control                                         |
+|`MAGIC_TOGGLE_CONTROL_CAPSLOCK`   |`CL_TOGG`|Toggle Caps Lock and Left Control swap                                    |
 |`MAGIC_CAPSLOCK_TO_CONTROL`       |`CL_CTRL`|Treat Caps Lock as Control                                                |
 |`MAGIC_UNCAPSLOCK_TO_CONTROL`     |`CL_CAPS`|Stop treating Caps Lock as Control                                        |
 |`MAGIC_SWAP_LCTL_LGUI`            |`LCG_SWP`|Swap Left Control and GUI                                                 |

docs/keycodes_us_ansi_shifted.md

@@ -8,7 +8,7 @@ Unfortunately, these keycodes cannot be used in Mod-Taps or Layer-Taps, since an
 
 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.
+To fix this, open Remote Desktop Connection, click on "Show Options", open 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
 

docs/keymap.md

@@ -136,7 +136,7 @@ After this you'll find a list of LAYOUT() macros. A LAYOUT() is simply a list of
 
 `keymaps[][MATRIX_ROWS][MATRIX_COLS]` in QMK holds the 16 bit action code (sometimes referred as the quantum keycode) in it.  For the keycode representing typical keys, its high byte is 0 and its low byte is the USB HID usage ID for keyboard.
 
-> TMK from which QMK was forked uses `const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]` instead and holds the 8 bit keycode.  Some keycode values are reserved to induce execution of certain action codes via the `fn_actions[]` array.
+> TMK from which QMK was forked uses `const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]` instead and holds the 8 bit keycode.
 
 #### Base Layer
 

docs/mod_tap.md

@@ -58,7 +58,7 @@ Currently, the `kc` argument of `MT()` is limited to the [Basic Keycode set](key
 Expanding this would be complicated, at best. Moving to a 32-bit keycode would solve a lot of this, but would double the amount of space that the keymap matrix uses. And it could potentially cause issues, too. If you need to apply modifiers to your tapped keycode, [Tap Dance](feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this.
 
 You may also run into issues when using Remote Desktop Connection on Windows. Because these keycodes send key events faster than a human, Remote Desktop could miss them.
-To fix this, open Remote Desktop Connection, click on "Show Options", open the the "Local Resources" tab, and in the keyboard section, change the drop down to "On this Computer". This will fix the issue, and allow the characters to work correctly.
+To fix this, open Remote Desktop Connection, click on "Show Options", open the "Local Resources" tab, and in the keyboard section, change the drop down to "On this Computer". This will fix the issue, and allow the characters to work correctly.
 It can also be mitigated by increasing [`TAP_CODE_DELAY`](config_options.md#behaviors-that-can-be-configured).
 
 ## Intercepting Mod-Taps

docs/newbs_building_firmware.md

@@ -1,6 +1,20 @@
 # Building Your First Firmware
 
-Now that you have setup your build environment you are ready to start building custom firmware. For this section of the guide we will bounce between 3 programs- your file manager, your text editor, and your terminal window. Keep all 3 open until you are done and happy with your keyboard firmware.
+Now that you have set up your build environment you are ready to start building custom firmware. For this section of the guide we will bounce between 3 programs- your file manager, your text editor, and your terminal window. Keep all 3 open until you are done and happy with your keyboard firmware.
+
+## Configure Your Build Environment Defaults (Optional)
+
+You can configure your build environment to set the defaults and make working with QMK less tedious. Let's do that now!
+
+Most people new to QMK only have 1 keyboard. You can set this keyboard as your default with the `qmk config` command. For example, to set your default keyboard to `clueboard/66/rev4`:
+
+    qmk config user.keyboard=clueboard/66/rev4
+
+?> The keyboard option is the path relative to the keyboard directory, the above example would be found in `qmk_firmware/keyboards/clueboard/66/rev4`. If you're unsure you can view a full list of supported keyboards with `qmk list-keyboards`.
+
+You can also set your default keymap name. Most people use their GitHub username like the keymap name from the previous steps:
+
+    qmk config user.keymap=<github_username>
 
 ## Create a New Keymap
 
@@ -45,7 +59,7 @@ When your changes to the keymap are complete you will need to build the firmware
 
     qmk compile
 
-If you did not configure your environment, or you have multiple keyboards, you can specify a keyboard and/or keymap:
+If you did not configure defaults for your environment, or you have multiple keyboards, you can specify a keyboard and/or keymap:
 
     qmk compile -kb <keyboard> -km <keymap>
 

docs/newbs_flashing.md

@@ -96,7 +96,7 @@ This has been made pretty simple compared to what it used to be. When you are re
 
     qmk flash
 
-If you have not configured your keyboard/keymap name in the CLI, or you have multiple keyboards, you can specify the keyboard and keymap:
+If you did not configure your keyboard/keymap name in the CLI according to the [Configure your build environment](newbs_getting_started.md) section, or you have multiple keyboards, you can specify the keyboard and keymap:
 
     qmk flash -kb <my_keyboard> -km <my_keymap>
 

docs/newbs_getting_started.md

@@ -182,22 +182,6 @@ Checking file size of clueboard_66_rev3_default.hex
  * The firmware size is fine - 26356/28672 (2316 bytes free)
 ```
 
-## 5. Configure Your Build Environment (Optional)
-
-You can configure your build environment to set the defaults and make working with QMK less tedious. Let's do that now!
-
-Most people new to QMK only have 1 keyboard. You can set this keyboard as your default with the `qmk config` command. For example, to set your default keyboard to `clueboard/66/rev4`:
-
-    qmk config user.keyboard=clueboard/66/rev4
-
-You can also set your default keymap name. Most people use their GitHub username here, and we recommend that you do too.
-
-    qmk config user.keymap=<github_username>
-
-The keyboard can now be compiled without arguments using the following command after creating your keymap in the next section:
-
-    qmk compile
-
 # Creating Your Keymap
 
 You are now ready to create your own personal keymap! Move on to [Building Your First Firmware](newbs_building_firmware.md) for that.

docs/newbs_learn_more_resources.md

@@ -20,6 +20,7 @@ Not sure which text editor to use?
 Editors specifically made for code:
 * [Sublime Text](https://www.sublimetext.com/)
 * [VS Code](https://code.visualstudio.com/)
+* [Atom](https://atom.io/)
 
 ### Git resources
 

docs/other_eclipse.md

@@ -11,7 +11,7 @@ Using an IDE such as Eclipse provides many advantages over a plain text editor,
 * static code analysis
 * many other tools such as debugging, code formatting, showing call hierarchies etc.
 
-The purpose of the is page is to document how to set-up Eclipse for developing AVR software, and working on the QMK code base.
+The purpose of this page is to document how to set-up Eclipse for developing AVR software, and working on the QMK code base.
 
 Note that this set-up has been tested on Ubuntu 16.04 only for the moment.
 
@@ -74,7 +74,7 @@ Once both plugins are installed, restart Eclipse as prompted.
 
 ## Build Your Keyboard
 
-We will now change the default make target of the the project from `all` to the
+We will now change the default make target of the project from `all` to the
 specific keyboard and keymap combination we are working on,
 e.g. `kinesis/kint36:stapelberg`. This way, project-wide actions like cleaning
 and building the project will complete quickly, instead of taking a long time or

docs/other_vscode.md

@@ -15,7 +15,7 @@ The purpose of this page is to document how to set up VS Code for developing QMK
 This guide covers how to configure everything needed on Windows and Ubuntu 18.04
 
 # Set up VS Code
-Before starting, you will want to make sure that you have all of the build tools set up, and QMK Firmware cloned. Head to the the [Newbs Getting Started Guide](newbs_getting_started.md) to get things set up, if you haven't already.
+Before starting, you will want to make sure that you have all of the build tools set up, and QMK Firmware cloned. Head to the [Newbs Getting Started Guide](newbs_getting_started.md) to get things set up, if you haven't already.
 
 ## Windows
 

docs/platformdev_chibios_earlyinit.md

@@ -17,7 +17,6 @@ As such, if you wish to override this API consider limiting use to writing to lo
 | `config.h` override                           | Description                                                                                                                                                                                                                                                                            | Default  |
 |-----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
 | `#define EARLY_INIT_PERFORM_BOOTLOADER_JUMP`  | Whether or not bootloader is to be executed during the early initialisation code of QMK.                                                                                                                                                                                               | `FALSE`  |
-| `#define STM32_BOOTLOADER_ADDRESS`            | Relevant for single-bank STM32 MCUs, signifies the memory address to jump to bootloader. Consult [AN2606](https://www.st.com/content/st_com/en/search.html#q=an2606-t=resources-page=1) for the _System Memory_ address for your MCU. This value should be of the format `0x11111111`. | `<none>` |
 | `#define STM32_BOOTLOADER_DUAL_BANK`          | Relevant for dual-bank STM32 MCUs, signifies that a GPIO is to be toggled in order to enter bootloader mode.                                                                                                                                                                           | `FALSE`  |
 | `#define STM32_BOOTLOADER_DUAL_BANK_GPIO`     | Relevant for dual-bank STM32 MCUs, the pin to toggle when attempting to enter bootloader mode, e.g. `B8`                                                                                                                                                                               | `<none>` |
 | `#define STM32_BOOTLOADER_DUAL_BANK_POLARITY` | Relevant for dual-bank STM32 MCUs, the value to set the pin to in order to trigger charging of the RC circuit. e.g. `0` or `1`.                                                                                                                                                        | `0`      |

docs/porting_your_keyboard_to_qmk.md

@@ -0,0 +1,163 @@
+# Adding Your Keyboard to QMK
+
+This page describes the support for [Compatible Microcontrollers](compatible_microcontrollers.md) in QMK.
+
+If you have not yet you should read the [Keyboard Guidelines](hardware_keyboard_guidelines.md) to get a sense of how keyboards fit into QMK.
+
+
+QMK has a number of features to simplify working with keyboards. For most, you don't have to write a single line of code. To get started, run `qmk new-keyboard`:
+
+```
+$ qmk new-keyboard
+Ψ Generating a new QMK keyboard directory
+
+Name Your Keyboard Project
+For more infomation, see:
+https://docs.qmk.fm/#/hardware_keyboard_guidelines?id=naming-your-keyboardproject
+
+keyboard Name? mycoolkeeb
+
+Attribution
+Used for maintainer, copyright, etc
+
+Your GitHub Username?  [jsmith] 
+
+More Attribution
+Used for maintainer, copyright, etc
+
+Your Real Name?  [John Smith] 
+
+Pick Base Layout
+As a starting point, one of the common layouts can be used to bootstrap the process
+
+Default Layout? 
+	1. 60_ansi
+...
+	50. tkl_iso
+	51. none of the above
+Please enter your choice:  [51] 
+
+What Powers Your Project
+For more infomation, see:
+https://docs.qmk.fm/#/compatible_microcontrollers
+
+MCU? 
+	1. atmega32u4
+...
+	22. STM32F303
+Please enter your choice:  [12]
+Ψ Created a new keyboard called mycoolkeeb.
+Ψ To start working on things, `cd` into keyboards/mycoolkeeb,
+Ψ or open the directory in your preferred text editor.
+Ψ And build with qmk compile -kb mycoolkeeb -km default.
+```
+
+This will create all the files needed to support your new keyboard, and populate the settings with default values. Now you just need to customize it for your keyboard.
+
+## `readme.md`
+
+This is where you'll describe your keyboard. Please follow the [Keyboard Readme Template](documentation_templates.md#keyboard-readmemd-template) when writing your `readme.md`. You're encouraged to place an image at the top of your `readme.md`, please use an external service such as [Imgur](https://imgur.com) to host the images.
+
+## `info.json`
+
+The `info.json` file is where you configure the hardware and feature set for your keyboard. There are a lot of options that can be placed in that file, too many to list here. For a complete overview of available options see the [Data Driven Configuration Options](reference_info_json.md) page.
+
+### Hardware Configuration
+
+At the top of the `info.json` you'll find USB related settings. These control how your keyboard appears to the Operating System. If you don't have a good reason to change you should leave the `usb.vid` as `0xFEED`. For the `usb.pid` you should pick a number that is not yet in use.
+
+Do change the `manufacturer` and `keyboard_name` lines to accurately reflect your keyboard.
+
+```json
+    "keyboard_name": "my_awesome_keyboard",
+    "maintainer": "You",
+    "usb": {
+        "vid": "0xFEED",
+        "pid": "0x0000",
+        "device_version": "1.0.0"
+    },
+```
+
+?> Windows and macOS will display the `manufacturer` and `keyboard_name` in the list of USB devices. `lsusb` on Linux instead prefers the values in the list maintained by the [USB ID Repository](http://www.linux-usb.org/usb-ids.html). By default, it will only use `manufacturer` and `keyboard_name` if the list does not contain that `usb.vid` / `usb.pid`. `sudo lsusb -v` will show the values reported by the device, and they are also present in kernel logs after plugging it in.
+
+
+### Matrix Configuration
+
+The next section of the `info` file deals with your keyboard's matrix. The first thing you should define is which pins on your MCU are connected to rows and columns. To do so simply specify the names of those pins:
+
+```json
+    "matrix_pins": {
+        "cols": ["C1", "C2", "C3", "C4"],
+        "rows": ["D1", "D2", "D3", "D4"]
+    },
+```
+
+The size of the `matrix_pins.cols` and `matrix_pins.rows` arrays infer the size of the matrix (previously `MATRIX_ROWS` and `MATRIX_COLS`). 
+
+Finally, you can specify the direction your diodes point. This can be `COL2ROW` or `ROW2COL`.
+
+```json
+    "diode_direction": "ROW2COL",
+```
+
+#### Direct Pin Matrix
+To configure a keyboard where each switch is connected to a separate pin and ground instead of sharing row and column pins, use `matrix_pins.direct`. The mapping defines the pins of each switch in rows and columns, from left to right. The size of the `matrix_pins.direct` array infers the size of the matrix. Use `NO_PIN` to fill in blank spaces. Overrides the behaviour of `diode_direction`, `matrix_pins.cols` and `matrix_pins.rows`.
+
+```json
+    "matrix_pins": {
+        "direct": [
+            ["F1", "E6", "B0", "B2", "B3" ],
+            ["F5", "F0", "B1", "B7", "D2" ],
+            ["F6", "F7", "C7", "D5", "D3" ],
+            ["B5", "C6", "B6", "NO_PIN", "NO_PIN"]
+        ]
+    },
+```
+
+### Layout macros
+
+Next is configuring Layout Macro(s). These define the physical arrangement of keys, and its position within the matrix that a switch are connected to. This allows you to have a physical arrangement of keys that differs from the wiring matrix.
+
+```json
+    "layouts": {
+        "LAYOUT_ortho_4x4": {
+            "layout": [
+                { "matrix": [0, 0], "x": 0, "y": 0 },
+                { "matrix": [0, 1], "x": 1, "y": 0 },
+                { "matrix": [0, 2], "x": 2, "y": 0 },
+                { "matrix": [0, 3], "x": 3, "y": 0 },
+                { "matrix": [1, 0], "x": 0, "y": 1 },
+                { "matrix": [1, 1], "x": 1, "y": 1 },
+                { "matrix": [1, 2], "x": 2, "y": 1 },
+                { "matrix": [1, 3], "x": 3, "y": 1 },
+                { "matrix": [2, 0], "x": 0, "y": 2 },
+                { "matrix": [2, 1], "x": 1, "y": 2 },
+                { "matrix": [2, 2], "x": 2, "y": 2 },
+                { "matrix": [2, 3], "x": 3, "y": 2 },
+                { "matrix": [3, 0], "x": 0, "y": 3 },
+                { "matrix": [3, 1], "x": 1, "y": 3 },
+                { "matrix": [3, 2], "x": 2, "y": 3 },
+                { "matrix": [3, 3], "x": 3, "y": 3 }
+            ]
+        }
+    }
+
+```
+
+In the above example, 
+
+* `LAYOUT_ortho_4x4` defines the name of the layout macro
+  * It must conform to [hardware_keyboard_guidelines.md#ltkeyboard_namehgt]
+* `"matrix": [0, 0]` defines the electrical position
+
+## Additional Configuration
+
+There are a lot of features that can be turned on or off, configured or tuned. Some of these have yet to be migrated over to [Data Driven Configuration](data_driven_config.md). The following sections cover the process for when an `info.json` option is unavailable.
+
+### Configuration Options
+
+For available options for `config.h`, you should see the [Config Options](config_options.md) page for more details.
+
+### Build Options
+
+For available options for `rules.mk`, see the [Config Options](config_options.md#feature-options) page for a detailed list and description.

docs/pr_checklist.md

@@ -8,7 +8,7 @@ If there are any inconsistencies with these recommendations, you're best off [cr
 
 - PR should be submitted using a non-`master` branch on the source repository
     - this does not mean you target a different branch for your PR, rather that you're not working out of your own master branch
-    - if submitter _does_ use their own `master` branch, they'll be given a link to the ["how to git"](https://docs.qmk.fm/#/newbs_git_using_your_master_branch) page after merging -- (end of this document will contain the contents of the message)
+    - if submitter _does_ use their own `master` branch, they'll be given a link to the ["how to git"](newbs_git_using_your_master_branch.md) page after merging -- (end of this document will contain the contents of the message)
 - newly-added directories and filenames must be lowercase
     - this rule may be relaxed if upstream sources originally had uppercase characters (e.g. LUFA, ChibiOS, or imported files from other repositories etc.)
     - if there is valid justification (i.e. consistency with existing core files etc.) this can be relaxed
@@ -76,9 +76,9 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
 - `<keyboard>.c`
     - empty `xxxx_xxxx_kb()` or other weak-defined default implemented functions removed
     - commented-out functions removed too
-    - `matrix_init_board()` etc. migrated to `keyboard_pre_init_kb()`, see: [keyboard_pre_init*](https://docs.qmk.fm/#/custom_quantum_functions?id=keyboard_pre_init_-function-documentation)
-    - prefer `CUSTOM_MATRIX = lite` if custom matrix used, allows for standard debounce, see [custom matrix 'lite'](https://docs.qmk.fm/#/custom_matrix?id=lite)
-    - prefer LED indicator [Configuration Options](https://docs.qmk.fm/#/feature_led_indicators?id=configuration-options) to custom `led_update_*()` implementations where possible
+    - `matrix_init_board()` etc. migrated to `keyboard_pre_init_kb()`, see: [keyboard_pre_init*](custom_quantum_functions.md?id=keyboard_pre_init_-function-documentation)
+    - prefer `CUSTOM_MATRIX = lite` if custom matrix used, allows for standard debounce, see [custom matrix 'lite'](custom_matrix.md?id=lite)
+    - prefer LED indicator [Configuration Options](feature_led_indicators.md?id=configuration-options) to custom `led_update_*()` implementations where possible
 - `<keyboard>.h`
     - `#include "quantum.h"` appears at the top
     - `LAYOUT` macros should use standard definitions if applicable
@@ -110,15 +110,17 @@ Also, specific to ChibiOS:
     - a lot of the time, an equivalent Nucleo board can be used with a different flash size or slightly different model in the same family
         - example: For an STM32L082KZ, given the similarity to an STM32L073RZ, you can use `BOARD = ST_NUCLEO64_L073RZ` in rules.mk
     - QMK is migrating to not having custom board definitions if at all possible, due to the ongoing maintenance burden when upgrading ChibiOS
+- New board definitions must not be embedded in a keyboard PR
+    - See [Core PRs](#core-pr) below for the procedure for adding a new board to QMK
 - if a board definition is unavoidable, `board.c` must have a standard `__early_init()` (as per normal ChibiOS board defs) and an empty `boardInit()`:
-    - see Arm/ChibiOS [early initialization](https://docs.qmk.fm/#/platformdev_chibios_earlyinit?id=board-init)
+    - see Arm/ChibiOS [early initialization](platformdev_chibios_earlyinit.md?id=board-init)
     - `__early_init()` should be replaced by either `early_hardware_init_pre()` or `early_hardware_init_post()` as appropriate
     - `boardInit()` should be migrated to `board_init()`
 
-## Core PRs
+## Core PRs :id=core-pr
 
 - must now target `develop` branch, which will subsequently be merged back to `master` on the breaking changes timeline
-- any support for new hardware now requires a corresponding test board under `keyboards/handwired/onekey`
+- any new boards adding support for new hardware now requires a corresponding test board under `keyboards/handwired/onekey`
     - for new MCUs, a new "child" keyboard should be added that targets your newly-added MCU, so that builds can be verified
     - for new hardware support such as display panels, core-side matrix implementations, or other peripherals, an associated keymap should be provided
     - if an existing keymap exists that can leverage this functionality this may not be required (e.g. a new RGB driver chip, supported by the `rgb` keymap) -- consult with the QMK Collaborators on Discord to determine if there is sufficient overlap already

docs/quantum_keycodes.md

@@ -8,8 +8,8 @@ On this page we have documented keycodes between `0x00FF` and `0xFFFF` which are
 
 ## QMK Keycodes :id=qmk-keycodes
 
-|Key           |Aliases  |Description                                            |
-|--------------|---------|-------------------------------------------------------|
-|`RESET`       |         |Put the keyboard into bootloader mode for flashing     |
-|`DEBUG`       |         |Toggle debug mode                                      |
-|`EEPROM_RESET`|`EEP_RST`|Reinitializes the keyboard's EEPROM (persistent memory)|
+|Key              |Aliases  |Description                                            |
+|-----------------|---------|-------------------------------------------------------|
+|`QK_BOOTLOADER`  |`QK_BOOT`|Put the keyboard into bootloader mode for flashing     |
+|`QK_DEBUG_TOGGLE`|`DB_TOGG`|Toggle debug mode                                      |
+|`QK_CLEAR_EEPROM`|`EE_CLR` |Reinitializes the keyboard's EEPROM (persistent memory)|

docs/reference_info_json.md

@@ -172,7 +172,7 @@ The following animations can be enabled:
 
 ### USB
 
-Every USB keyboard needs to have its USB parmaters defined. At a minimum you need to set vid, pid, and device version.
+Every USB keyboard needs to have its USB parameters defined. At a minimum you need to set the Vendor ID, Product ID, and device version.
 
 Example:
 
@@ -181,7 +181,9 @@ Example:
     "usb": {
         "vid": "0xC1ED",
         "pid": "0x23B0",
-        "device_ver": "0x0001"
+        "device_version": "1.0.0"
     }
 }
 ```
+
+The device version is a BCD (binary coded decimal) value, in the format `MMmr`, so the below value would look like `0x0100` in the generated code. This also means the maximum valid values for each part are `99.9.9`, despite it being a hexadecimal value under the hood.

docs/squeezing_avr.md

@@ -1,16 +1,16 @@
 # Squeezing the most out of AVR
 
-AVR is severely resource-constrained, and as QMK continues to grow, it is approaching a point where support for AVR may need to be moved to legacy status as newer development is unable to fit into those constraints.  
+AVR is severely resource-constrained, and as QMK continues to grow, it is approaching a point where support for AVR may need to be moved to legacy status as newer development is unable to fit into those constraints.
 
-However, if you need to reduce the compiled size of your firmware, there are a number of options to do so. 
+However, if you need to reduce the compiled size of your firmware, there are a number of options to do so.
 
 ## `rules.mk` Settings
-First and foremost is enabling link time optimization.  To do so, add this to your rules.mk: 
+First and foremost is enabling link time optimization. To do so, add this to your rules.mk: 
 ```make
 LTO_ENABLE = yes
 ```
-This will cause the final step to take longer, but should get you a smaller compiled size.  This also disables Action Functions, and Action Macros, both of which are deprecated.
-This will get you the most savings, in most situations. 
+This will cause the final step to take longer, but should get you a smaller compiled size. This also disables Action Functions, and Action Macros, both of which are deprecated.
+This will get you the most savings, in most situations.
 
 From there, disabling extraneous systems will help -- e.g.: 
 ```make
@@ -19,7 +19,7 @@ COMMAND_ENABLE = no
 MOUSEKEY_ENABLE = no
 EXTRAKEY_ENABLE = no
 ```
-This disables some of the functionality that you may not need.  But note that extrakeys disables stuff like the media keys and system volume control.
+This disables some of the functionality that you may not need. But note that extrakeys disables stuff like the media keys and system volume control.
 
 If that isn't enough to get your firmware down to size, then there are some additional features that you can disable: 
 ```make
@@ -27,19 +27,19 @@ SPACE_CADET_ENABLE = no
 GRAVE_ESC_ENABLE = no 
 MAGIC_ENABLE = no
 ```
-These features are enabled by default, but may not be needed.  Double check to make sure, though.  
-Largest in size is "magic" -- the QMK magic keycodes -- which control things like NKRO toggling, GUI and ALT/CTRL swapping, etc.  Disabling it will disable those functions. 
+These features are enabled by default, but may not be needed. Double check to make sure, though. 
+Largest in size is "magic" -- the QMK magic keycodes -- which control things like NKRO toggling, GUI and ALT/CTRL swapping, etc. Disabling it will disable those functions.
 
 ## `config.h` Settings
 
-If you've done all of that, and you don't want to disable features like RGB, Audio, OLEDs, etc, there are some additional options that you can add to your config.h that can help. 
+If you've done all of that, and you don't want to disable features like RGB, Audio, OLEDs, etc, there are some additional options that you can add to your config.h that can help.
 
-Starting with Lock Key support.  If you have an Cherry MX Lock switch (lucky you!), you don't want to do this.  But chances are, you don't.  In that case, add this to your `config.h`:
+Starting with Lock Key support. If you have an Cherry MX Lock switch (lucky you!), you don't want to do this. But chances are, you don't. In that case, add this to your `config.h`:
 ```c
 #undef LOCKING_SUPPORT_ENABLE
 #undef LOCKING_RESYNC_ENABLE
 ```
-Oneshots.  If you're not using these, you can disable the feature by adding this to your `config.h`: 
+Oneshots. If you're not using these, you can disable the feature by adding this to your `config.h`: 
 ```c
 #define NO_ACTION_ONESHOT
 ```
@@ -49,7 +49,7 @@ The same with tapping keys (mod tap, layer tap, etc)
 ```
 ## Audio Settings
 
-If you're using the Audio feature, by default that includes the music mode feature.  This tranlates matrix positions into notes.  It's neat for sure, but most likely, you're not using it.  You can disable it by adding this to your `config.h`:
+If you're using the Audio feature, by default that includes the music mode feature. This tranlates matrix positions into notes. It's neat for sure, but most likely, you're not using it. You can disable it by adding this to your `config.h`:
 ```c
 #define NO_MUSIC_MODE
 ```
@@ -60,7 +60,7 @@ MUSIC_ENABLE = no
 
 ## Layers
 
-There are also some options for layers, that can reduce the firmware size.  All of these settngs are for your `config.h`. 
+There are also some options for layers, that can reduce the firmware size. All of these settings are for your `config.h`.
 
 You can limit the number of layers that the firmware uses -- if you're using less than 8 layers in total:
 ```c
@@ -93,7 +93,7 @@ into this:
     oled_write_P(PSTR("WPM: "), false);
     oled_write(get_u8_str(get_current_wpm(), ' '), false);
 ```
-which outputs `WPM:   5`.  Or this: 
+which outputs `WPM:   5`. Or this: 
 ```c
     // NEW CODE
     oled_write_P(PSTR("WPM: "), false);
@@ -103,7 +103,7 @@ which outputs `WPM: 005`.
 
 ## RGB Settings
 
-If you're using RGB on your board, both RGB Light (Underglow) and RGB Matrix (per key RGB) now require defines to enable different animations -- some keyboards enable a lot of animations by default, so you can generally gain back some space by disabling specific animations if you don't use them..  For RGB Light you can disable these in your keymap's `config.h`: 
+If you're using RGB on your board, both RGB Light (Underglow) and RGB Matrix (per key RGB) now require defines to enable different animations -- some keyboards enable a lot of animations by default, so you can generally gain back some space by disabling specific animations if you don't use them. For RGB Light you can disable these in your keymap's `config.h`:
 ```c
 #undef RGBLIGHT_ANIMATIONS
 #undef RGBLIGHT_EFFECT_BREATHING
@@ -118,7 +118,7 @@ If you're using RGB on your board, both RGB Light (Underglow) and RGB Matrix (pe
 #undef RGBLIGHT_EFFECT_TWINKLE
 ```
 
-For RGB Matrix, these need to be explicitly enabled as well. To disable any that were enabled by the keyboard, add one or more of these to your keymap's `config.h`: 
+For RGB Matrix, these need to be explicitly enabled as well. To disable any that were enabled by the keyboard, add one or more of these to your keymap's `config.h`:
 ```c
 #undef ENABLE_RGB_MATRIX_ALPHAS_MODS
 #undef ENABLE_RGB_MATRIX_GRADIENT_UP_DOWN
@@ -147,6 +147,7 @@ For RGB Matrix, these need to be explicitly enabled as well. To disable any that
 #undef ENABLE_RGB_MATRIX_HUE_PENDULUM
 #undef ENABLE_RGB_MATRIX_HUE_WAVE
 #undef ENABLE_RGB_MATRIX_PIXEL_FRACTAL
+#undef ENABLE_RGB_MATRIX_PIXEL_FLOW
 #undef ENABLE_RGB_MATRIX_PIXEL_RAIN
 
 #undef ENABLE_RGB_MATRIX_TYPING_HEATMAP
@@ -168,7 +169,7 @@ For RGB Matrix, these need to be explicitly enabled as well. To disable any that
 
 # Final Thoughts
 
-If you've done all of this, and your firmware is still too large, then it's time.  It's time to consider making the switch to ARM.  Unfortunately, right now is the worst possible time for that, due to the silicon shortage, and supply chain issues. Getting an ARM chip is difficult, at best, and significantly overpriced, at worst. 
+If you've done all of this, and your firmware is still too large, then it's time. It's time to consider making the switch to ARM. Unfortunately, right now is the worst possible time for that, due to the silicon shortage, and supply chain issues. Getting an ARM chip is difficult, at best, and significantly overpriced, at worst.
  -- Drashna
 
 That said, there are a number of Pro Micro replacements with ARM controllers: 
@@ -176,5 +177,5 @@ That said, there are a number of Pro Micro replacements with ARM controllers:
 * [Bonsai C](https://github.com/customMK/Bonsai-C) (Open Source, DIY/PCBA)
 * [Raspberry Pi 2040](https://www.sparkfun.com/products/18288) (not currently supported, no ETA)
 
-There are other, non-Pro Micro compatible boards out there. The most popular being: 
+There are other, non-Pro Micro compatible boards out there. The most popular being:
 * [WeAct Blackpill F411](https://www.aliexpress.com/item/1005001456186625.html) (~$6 USD)

docs/zh-cn/README.md

@@ -1,31 +1,42 @@
-# QMK机械键盘固件
+# Quantum Mechanical Keyboard固件
 
-[![当前版本](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags)
-[![异议](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh)
-[![文档状态](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm)
-[![GitHub贡献者](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
-[![GitHub分支](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
+<!---
+  original document: 0.15.12:docs/README.md
+  git diff 0.15.12 HEAD -- docs/README.md | cat
+-->
 
 ## 什么是 QMK 固件?
 
-QMK (*Quantum Mechanical Keyboard*) 是一个社区维护的开源软件，包括 QMK 固件, QMK 工具箱, qmk.fm网站, 和这些文档。QMK 固件是一个基于[tmk\_keyboard](https://github.com/tmk/tmk_keyboard)的键盘固件，它在爱特梅尔AVR微控制器实现一些有用的功能,确切地说, 是在 [OLKB product line](https://olkb.com), 在 [ErgoDox EZ](https://www.ergodox-ez.com) 键盘, 和 [Clueboard product line](https://clueboard.co/). 上。它被移植到使用ChibiOS的ARM芯片上. 它可以在飞线键盘或定制PCB键盘中发挥功能.
+QMK (*Quantum Mechanical Keyboard*) 是一个社区维护的用于开发计算机输入设备的开源软件。社区专注像键盘，鼠标，MIDI设备的各种电子输入设备。社区内的核心小组成员维护[QMK固件](https://github.com/qmk/qmk_firmware)，[QMK配置器](https://config.qmk.fm)（QMK Configurator），[QMK工具箱](https://github.com/qmk/qmk_toolbox)（QMK Toolbox），[qmk.fm](https://qmk.fm)，并与各位社区成员维护这份文档。
 
-## 如何得到它
+## 如何入门
 
-如果你打算贡献布局, 键盘, 或者其他QMK特性, 一下是最简单的方法：[从GitHub获得repo分支](https://github.com/qmk/qmk_firmware#fork-destination-box), 并克隆你的repo到本地进行编辑，推送，然后从你的分支打开 [Pull Request](https://github.com/qmk/qmk_firmware/pulls).
+<div class="flex-container">
 
-此外, 你也可以直接下载 ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), 或者从git克隆 (`git@github.com:qmk/qmk_firmware.git`), 或 https (`https://github.com/qmk/qmk_firmware.git`).
+?> **基础方式** [QMK配置器](zh-cn/newbs_building_firmware_configurator.md) <br>
+用户友好的图形界面工具，无需具备编程知识基础。
 
-## 如何编译
+?> **进阶方式** [基于源代码](zh-cn/newbs.md) <br> 
+功能更强大，但门槛较高。
 
-在你能编译之前, 你需要[部署环境](zh-cn/getting_started_build_tools.md) 用于 AVR or/and ARM 开发。完成后, 你可以使用 `make` 命令来编译一个键盘和布局使用以下命令:
+</div>
 
-    make planck/rev4:default
+## 个性化定制
 
-这将建立 `planck`的`rev4` 修订版本并使用 `default`布局。并非所有键盘都有修订版本 (也叫做子项目或文件夹)，在此情况下，修订版本可以省略，如下:
+QMK提供了很多功能，对应着很多可供浏览的配套文档。大部分功能都是通过修改[键映射](zh-cn/keymap.md)及[键码](zh-cn/keycodes.md)实现的。
 
-    make preonic:default
+## 需要帮助？
 
-## 如何定制
+请查阅[寻求帮助页面](zh-cn/support.md)以了解如何获取QMK使用方法的帮助。
 
-QMK 有许多 [特性](zh-cn/features.md)来探索，也有很多 [参考文档](https://docs.qmk.fm) 供您发掘。你可以通过修改 [布局](zh-cn/keymap.md)和[键码](zh-cn/keycodes.md)来利用许多特性。
+## 回馈社区
+
+有多种回馈社区的方法，最简单的方法是开始使用QMK并向你的朋友们推荐它。
+
+* 可以在我们的论坛及聊天室进行互助：
+    * [/r/olkb](https://www.reddit.com/r/olkb/)
+    * [Discord服务器](https://discord.gg/Uq7gcHh)
+* 点击页面下方的“Edit This Page”，可以对文档提供贡献。
+* [将这份文档翻译为你的语言](zh-cn/translating.md)
+* [上报bug](https://github.com/qmk/qmk_firmware/issues/new/choose)
+* [发起Pull Request](zh-cn/contributing.md)

docs/zh-cn/_summary.md

@@ -1,133 +1,193 @@
-* [完全菜鸟指南](zh-cn/newbs.md)
+<!--for translators, see first: zh-cn/reference_glossary.md#terms-of-zh-cn-translate -->
+* 新手教程
+  * [介绍](zh-cn/newbs.md)
   * [入门](zh-cn/newbs_getting_started.md)
-  * [构建你的第一个固件](zh-cn/newbs_building_firmware.md)
-  * [刷新固件](zh-cn/newbs_flashing.md)
-  * [测试和调试](zh-cn/newbs_testing_debugging.md)
-  * [Git最佳实践](zh-cn/newbs_git_best_practices.md)
-    * [使用你分叉(fork)的主分支(master)](zh-cn/newbs_git_using_your_master_branch.md)
-    * [解决合并冲突](zh-cn/newbs_git_resolving_merge_conflicts.md)
-    * [重新同步一个分支](zh-cn/newbs_git_resynchronize_a_branch.md)
-  * [学习资源](zh-cn/newbs_learn_more_resources.md)
+  * [构建第一个固件](zh-cn/newbs_building_firmware.md)
+  * [刷写固件](zh-cn/newbs_flashing.md)
+  * [寻求帮助](zh-cn/support.md)
+  * [其它资源](zh-cn/newbs_learn_more_resources.md)
+  * [QMK大纲](zh-cn/syllabus.md)
 
-* [QMK基础](zh-cn/README.md)
-  * [QMK简介](zh-cn/getting_started_introduction.md)
-  * [QMK命令行工具](zh-cn/cli.md)
-  * [QMK命令行工具配置](zh-cn/cli_configuration.md)
-  * [向QMK贡献代码](zh-cn/contributing.md)
-  * [如何使用GitHub](zh-cn/getting_started_github.md)
-  * [获得帮助](zh-cn/getting_started_getting_help.md)
-
-* [非兼容性修改](zh-cn/breaking_changes.md)
-  * [我的PR已经被标记为非兼容性修改](zh-cn/breaking_changes_instructions.md)
-  * [2019年8月30日](zh-cn/ChangeLog/20190830.md)
-
-* [问题与解答](zh-cn/faq.md)
-  * [一般问题](zh-cn/faq_general.md)
-  * [构建/编译](zh-cn/faq_build.md)
-  * [调试/故障排除](zh-cn/faq_debug.md)
-  * [布局](zh-cn/faq_keymap.md)
-  * [Zadig驱动安装](zh-cn/driver_installation_zadig.md)
-
-* 详细指南
-  * [安装构建工具](zh-cn/getting_started_build_tools.md)
-  * [vagrant指南](zh-cn/getting_started_vagrant.md)
-  * [构建/编译指南](zh-cn/getting_started_make_guide.md)
-  * [刷新固件](zh-cn/flashing.md)
-  * [定制功能](zh-cn/custom_quantum_functions.md)
-  * [布局概述](zh-cn/keymap.md)
-
-* [硬件](zh-cn/hardware.md)
-  * [兼容的单片机](zh-cn/compatible_microcontrollers.md)
-  * [AVR处理器](zh-cn/hardware_avr.md)
-  * [驱动](zh-cn/hardware_drivers.md)
-
-* 参考
-  * [键盘指南](zh-cn/hardware_keyboard_guidelines.md)
-  * [配置选项](zh-cn/config_options.md)
-  * [键码](zh-cn/keycodes.md)
-  * [代码书写规范 - C](zh-cn/coding_conventions_c.md)
-  * [代码书写规范 - Python](zh-cn/coding_conventions_python.md)
-  * [文档书写规范](zh-cn/documentation_best_practices.md)
-  * [文档模板](zh-cn/documentation_templates.md)
+* FAQ
+  * [常规FAQ](zh-cn/faq_general.md)
+  * [构建/编译QMK](zh-cn/faq_build.md)
+  * [QMK问题排查](zh-cn/faq_misc.md)
+  * [调试QMK](zh-cn/faq_debug.md)
+  * [键映射FAQ](zh-cn/faq_keymap.md)
+  * [充分利用AVR的存储空间](zh-cn/squeezing_avr.md)
   * [术语表](zh-cn/reference_glossary.md)
-  * [单元测试](zh-cn/unit_testing.md)
-  * [实用函数](zh-cn/ref_functions.md)
-  * [配置器支持](zh-cn/reference_configurator_support.md)
-  * [info.json 格式](zh-cn/reference_info_json.md)
-  * [Python 命令行开发](zh-cn/cli_development.md)
 
-* [特性](zh-cn/features.md)
-  * [基本键码](zh-cn/keycodes_basic.md)
-  * [US ANSI控制码](zh-cn/keycodes_us_ansi_shifted.md)
-  * [量子键码](zh-cn/quantum_keycodes.md)
-  * [高级键码](zh-cn/feature_advanced_keycodes.md)
-  * [音频](zh-cn/feature_audio.md)
-  * [自动shift](zh-cn/feature_auto_shift.md)
-  * [背光](zh-cn/feature_backlight.md)
-  * [蓝牙](zh-cn/feature_bluetooth.md)
-  * [热改键](zh-cn/feature_bootmagic.md)
-  * [组合](zh-cn/feature_combo)
-  * [命令](zh-cn/feature_command.md)
-  * [消抖 API](zh-cn/feature_debounce_type.md)
-  * [拨动开关](zh-cn/feature_dip_switch.md)
-  * [动态宏指令](zh-cn/feature_dynamic_macros.md)
-  * [编码器](zh-cn/feature_encoders.md)
-  * [重音号Esc复合键](zh-cn/feature_grave_esc.md)
-  * [触摸反馈](zh-cn/feature_haptic_feedback.md)
-  * [HD44780 LCD控制器](zh-cn/feature_hd44780.md)
-  * [自锁键](zh-cn/feature_key_lock.md)
-  * [布局](zh-cn/feature_layouts.md)
-  * [前导键](zh-cn/feature_leader_key.md)
-  * [LED阵列](zh-cn/feature_led_matrix.md)
-  * [宏指令](zh-cn/feature_macros.md)
-  * [鼠标键](zh-cn/feature_mouse_keys.md)
-  * [OLED驱动](zh-cn/feature_oled_driver.md)
-  * [一键功能](zh-cn/one_shot_keys.md)
-  * [指针设备](zh-cn/feature_pointing_device.md)
-  * [PS/2鼠标](zh-cn/feature_ps2_mouse.md)
-  * [RGB灯光](zh-cn/feature_rgblight.md)
-  * [RGB矩阵](zh-cn/feature_rgb_matrix.md)
-  * [空格候补换挡](zh-cn/feature_space_cadet.md)
-  * [分体键盘](zh-cn/feature_split_keyboard.md)
-  * [速录机](zh-cn/feature_stenography.md)
-  * [换手](zh-cn/feature_swap_hands.md)
-  * [多击键](zh-cn/feature_tap_dance.md)
-  * [终端](zh-cn/feature_terminal.md)
-  * [热敏打印机](zh-cn/feature_thermal_printer.md)
-  * [Unicode](zh-cn/feature_unicode.md)
-  * [用户空间](zh-cn/feature_userspace.md)
-  * [速度键](zh-cn/feature_velocikey.md)
+* 配置器(Configurator)
+  * [总览](zh-cn/newbs_building_firmware_configurator.md)
+  * [入门](zh-cn/configurator_step_by_step.md)
+  * [问题排查](zh-cn/configurator_troubleshooting.md)
+  * [框架](zh-cn/configurator_architecture.md)
+  * QMK API
+    * [总览](zh-cn/api_overview.md)
+    * [API文档](zh-cn/api_docs.md)
+    * [键盘支持](zh-cn/reference_configurator_support.md)
+    * [添加默认键映射](zh-cn/configurator_default_keymaps.md)
 
-* 制造和定制者指南
-  * [手工连线指南](zh-cn/hand_wire.md)
-  * [ISP刷新指南](zh-cn/isp_flashing_guide.md)
-  * [ARM调试指南](zh-cn/arm_debugging.md)
-  * [ADC设备](zh-cn/adc_driver.md)
-  * [I2C设备](zh-cn/i2c_driver.md)
-  * [SPI设备](zh-cn/spi_driver.md)
-  * [WS2812设备](zh-cn/ws2812_driver.md)
-  * [EEPROM设备](zh-cn/eeprom_driver.md)
-  * [GPIO控制](zh-cn/internals_gpio_control.md)
-  * [自定义键盘矩阵](zh-cn/custom_matrix.md)
-  * [Proton C转换](zh-cn/proton_c_conversion.md)
+* CLI
+    * [总览](zh-cn/cli.md)
+    * [配置](zh-cn/cli_configuration.md)
+    * [命令](zh-cn/cli_commands.md)
+    * [Tab补全](zh-cn/cli_tab_complete.md)
 
-* 深入了解
-  * [键盘工作原理](zh-cn/how_keyboards_work.md)
-  * [深入了解QMK](zh-cn/understanding_qmk.md)
+* 使用QMK
+  * 导览
+    * [功能定制](zh-cn/custom_quantum_functions.md)
+    * [利用Zadig安装驱动](zh-cn/driver_installation_zadig.md)
+    * [极简式制作](zh-cn/easy_maker.md)
+    * [键映射总览](zh-cn/keymap.md)
+    * 开发环境
+      * [Docker指南](zh-cn/getting_started_docker.md)
+      * [Vagrant指南](zh-cn/getting_started_vagrant.md)
+    * 刷写(Flashing)
+      * [刷写](zh-cn/flashing.md)
+      * [刷写ATmega32A (ps2avrgb)](zh-cn/flashing_bootloadhid.md)
+    * IDE
+      * [在Eclipse中使用QMK](zh-cn/other_eclipse.md)
+      * [在VSCode中使用QMK](zh-cn/other_vscode.md)
+    * Git最佳实践
+      * [介绍](zh-cn/newbs_git_best_practices.md)
+      * [你自己的副本](zh-cn/newbs_git_using_your_master_branch.md)
+      * [冲突合并](zh-cn/newbs_git_resolving_merge_conflicts.md)
+      * [基于你的分支修复](zh-cn/newbs_git_resynchronize_a_branch.md)
+    * 键盘组装
+      * [飞线指南](zh-cn/hand_wire.md)
+      * [ISP刷写指南](zh-cn/isp_flashing_guide.md)
 
-* 其他话题
-  * [使用Eclipse开发QMK](zh-cn/other_eclipse.md)
-  * [使用VSCode开发QMK](zh-cn/other_vscode.md)
-  * [支持](zh-cn/getting_started_getting_help.md)
-  * [翻译QMK文档](zh-cn/translating.md)
+  * 键码入门
+    * [键码汇总](zh-cn/keycodes.md)
+    * [基础键码](zh-cn/keycodes_basic.md)
+    * [语言特定的键码](zh-cn/reference_keymap_extras.md)
+    * [修饰键](zh-cn/feature_advanced_keycodes.md)
+    * [原子键码](zh-cn/quantum_keycodes.md)
+    * [Magic键码](zh-cn/keycodes_magic.md)
 
-* QMK 内构 (正在编写)
-  * [定义](zh-cn/internals_defines.md)
-  * [输入回调寄存器](zh-cn/internals_input_callback_reg.md)
-  * [Midi设备](zh-cn/internals_midi_device.md)
-  * [Midi设备配置过程](zh-cn/internals_midi_device_setup_process.md)
-  * [Midi工具库](zh-cn/internals_midi_util.md)
-  * [发送函数](zh-cn/internals_send_functions.md)
-  * [Sysex工具](zh-cn/internals_sysex_tools.md)
-<!--fromen:20200126-6:03AM(GMT+8)-->
-<!--cn:20200211-11:04AM(GMT+8)-->
+  * 键码进阶
+    * [指令](zh-cn/feature_command.md)
+    * [动态宏](zh-cn/feature_dynamic_macros.md)
+    * [Grave Escape](zh-cn/feature_grave_esc.md)
+    * [前导键](zh-cn/feature_leader_key.md)
+    * [Mod-Tap](zh-cn/mod_tap.md)
+    * [宏](zh-cn/feature_macros.md)
+    * [鼠标键](zh-cn/feature_mouse_keys.md)
+    * [Space Cadet Shift](zh-cn/feature_space_cadet.md)
+    * [US ANSI上档键值](zh-cn/keycodes_us_ansi_shifted.md)
+
+  * 软件特性
+    * [自动Shift](zh-cn/feature_auto_shift.md)
+    * [组合键](zh-cn/feature_combo.md)
+    * [防抖API](zh-cn/feature_debounce_type.md)
+    * [按键锁定](zh-cn/feature_key_lock.md)
+    * [按键重定义](zh-cn/feature_key_overrides.md)
+    * [层](zh-cn/feature_layers.md)
+    * [粘滞键](zh-cn/one_shot_keys.md)
+    * [光标设备](zh-cn/feature_pointing_device.md)
+    * [原生HID](zh-cn/feature_rawhid.md)
+    * [Sequencer](zh-cn/feature_sequencer.md)
+    * [换手](zh-cn/feature_swap_hands.md)
+    * [一键多用](zh-cn/feature_tap_dance.md)
+    * [点按配置](zh-cn/tap_hold.md)
+    * [终端](zh-cn/feature_terminal.md)
+    * [Unicode](zh-cn/feature_unicode.md)
+    * [用户空间](zh-cn/feature_userspace.md)
+    * [WPM计算](zh-cn/feature_wpm.md)
+
+  * 硬件特性
+    * 显示
+      * [HD44780 LCD控制器](zh-cn/feature_hd44780.md)
+      * [ST7565 LCD驱动](zh-cn/feature_st7565.md)
+      * [OLED驱动](zh-cn/feature_oled_driver.md)
+    * 灯效
+      * [背光](zh-cn/feature_backlight.md)
+      * [LED矩阵](zh-cn/feature_led_matrix.md)
+      * [RGB灯光](zh-cn/feature_rgblight.md)
+      * [RGB矩阵](zh-cn/feature_rgb_matrix.md)
+    * [音频](zh-cn/feature_audio.md)
+    * [蓝牙](zh-cn/feature_bluetooth.md)
+    * [Bootmagic Lite](zh-cn/feature_bootmagic.md)
+    * [自定义矩阵](zh-cn/custom_matrix.md)
+    * [Digitizer](zh-cn/feature_digitizer.md)
+    * [拨动开关（DIP Switch）](zh-cn/feature_dip_switch.md)
+    * [编码器（旋钮）](zh-cn/feature_encoders.md)
+    * [触摸反馈](zh-cn/feature_haptic_feedback.md)
+    * [摇杆](zh-cn/feature_joystick.md)
+    * [LED指示](zh-cn/feature_led_indicators.md)
+    * [MIDI](zh-cn/feature_midi.md)
+    * [Proton C转换](zh-cn/proton_c_conversion.md)
+    * [PS/2鼠标](zh-cn/feature_ps2_mouse.md)
+    * [分体式键盘](zh-cn/feature_split_keyboard.md)
+    * [速记](zh-cn/feature_stenography.md)
+    * [热敏打印机](zh-cn/feature_thermal_printer.md)
+    * [Velocikey](zh-cn/feature_velocikey.md)
+
+* QMK开发
+  * [PR Checklist](zh-cn/pr_checklist.md)
+  * 打破兼容的改动
+    * [总览](zh-cn/breaking_changes.md)
+    * [我的PR已打上标记](zh-cn/breaking_changes_instructions.md)
+    * [近期的变更日志(Changelog)](zh-cn/ChangeLog/20210529.md "QMK v0.13.0 - 2021 May 29")
+    * [更早期的不兼容改动](zh-cn/breaking_changes_history.md)
+
+  * C语言开发
+    * [ARM调试指引](zh-cn/arm_debugging.md)
+    * [AVR处理器](zh-cn/hardware_avr.md)
+    * [C编码规范](zh-cn/coding_conventions_c.md)
+    * [兼容的微处理器](zh-cn/compatible_microcontrollers.md)
+    * [驱动](zh-cn/hardware_drivers.md)
+      * [ADC驱动](zh-cn/adc_driver.md)
+      * [Audio驱动](zh-cn/audio_driver.md)
+      * [I2C驱动](zh-cn/i2c_driver.md)
+      * [SPI驱动](zh-cn/spi_driver.md)
+      * [WS2812驱动](zh-cn/ws2812_driver.md)
+      * [EEPROM驱动](zh-cn/eeprom_driver.md)
+      * [串口驱动](zh-cn/serial_driver.md)
+      * [UART驱动](zh-cn/uart_driver.md)
+    * [操控GPIO](zh-cn/internals_gpio_control.md)
+    * [键盘开发指引](zh-cn/hardware_keyboard_guidelines.md)
+
+  * Python开发
+    * [编码规范](zh-cn/coding_conventions_python.md)
+    * [QMK CLI开发](zh-cn/cli_development.md)
+
+  * 配置器开发
+    * QMK API
+      * [开发环境](zh-cn/api_development_environment.md)
+      * [架构总览](zh-cn/api_development_overview.md)
+
+  * 硬件平台开发
+    * Arm/ChibiOS
+      * [选择MCU](zh-cn/platformdev_selecting_arm_mcu.md)
+      * [启动引导](zh-cn/platformdev_chibios_earlyinit.md)
+
+  * QMK参考信息
+    * [参与到QMK](zh-cn/contributing.md)
+    * [翻译QMK文档](zh-cn/translating.md)<!--but should we translate this? currently keep it fallback-->
+    * [配置](zh-cn/config_options.md)
+    * [数据驱动配置](zh-cn/data_driven_config.md)
+    * [Make指引](zh-cn/getting_started_make_guide.md)
+    * [编写文档的最佳实践](zh-cn/documentation_best_practices.md)
+    * [文档模板](zh-cn/documentation_templates.md)
+    * [贡献配列到社区](zh-cn/feature_layouts.md)
+    * [单元测试](zh-cn/unit_testing.md)
+    * [常用函数](zh-cn/ref_functions.md)
+    * [info.json参考资料](zh-cn/reference_info_json.md)
+
+  * 深入了解
+    * [键盘工作原理](zh-cn/how_keyboards_work.md)
+    * [键盘矩阵原理](zh-cn/how_a_matrix_works.md)
+    * [了解QMK](zh-cn/understanding_qmk.md)
+
+  * QMK内部细节 (编辑中)
+    * [定义](zh-cn/internals_defines.md)
+    * [输入回调的注册](zh-cn/internals_input_callback_reg.md)
+    * [Midi设备](zh-cn/internals_midi_device.md)
+    * [Midi设备驱动流程](zh-cn/internals_midi_device_setup_process.md)
+    * [Midi辅助功能](zh-cn/internals_midi_util.md)
+    * [发送函数](zh-cn/internals_send_functions.md)
+    * [Sysex工具](zh-cn/internals_sysex_tools.md)
+    
+<!--fromen:20211014-12:00(GMT+8) commit 04cf161aa01fd433b5dae69d9fd31569ed5dca59-->

docs/zh-cn/api_docs.md

@@ -0,0 +1,73 @@
+# QMK API
+
+<!---
+  original document: 0.15.12:docs/api_docs.md
+  git diff 0.15.12 HEAD -- docs/api_docs.md | cat
+-->
+
+本章节详述了QMK API的使用方法，若您是应用开发者，使用这套API可以实现[QMK](https://qmk.fm)键盘固件的编译支持。
+
+## 总览
+
+本服务提供了一套用于编译自定义键映射的异步API，通过POST方式发送JSON参数到API，定期检查执行状态，待固件编译完成后，即可下载生成的固件文件和固件的源文件（如果需要的话）。
+
+#### 荷载JSON参数示例：
+
+```json
+{
+  "keyboard": "clueboard/66/rev2",
+  "keymap": "my_awesome_keymap",
+  "layout": "LAYOUT_all",
+  "layers": [
+    ["KC_GRV","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_GRV","KC_BSPC","KC_PGUP","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","KC_PGDN","KC_CAPS","KC_A","KC_S","KC_D","KC_F","KC_G","KC_H","KC_J","KC_K","KC_L","KC_SCLN","KC_QUOT","KC_NUHS","KC_ENT","KC_LSFT","KC_NUBS","KC_Z","KC_X","KC_C","KC_V","KC_B","KC_N","KC_M","KC_COMM","KC_DOT","KC_SLSH","KC_RO","KC_RSFT","KC_UP","KC_LCTL","KC_LGUI","KC_LALT","KC_MHEN","KC_SPC","KC_SPC","KC_HENK","KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"],
+    ["KC_ESC","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_DEL","BL_STEP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","_______","KC_TRNS","KC_PSCR","KC_SLCK","KC_PAUS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","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_PGUP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_LEFT","KC_PGDN","KC_RGHT"],
+    ["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","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","MO(2)","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_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_TRNS","KC_TRNS","KC_TRNS"]
+  ]
+}
+```
+
+如上可见，荷载参数里有用于生成固件文件的所有键盘信息。每一个层定义都包含了与键盘 `LAYOUT` 宏定义一致的QMK键码列表数据，若该键盘有多个支持的 `LAYOUT` 宏定义，也可以指定使用的是哪一个。
+
+## 提交一个编译job
+
+若要将键映射配置编译成固件文件，仅需将JSON参数通过POST发送至 `/v1/compile` 节点。下面的示例中我们假设JSON荷载参数已存放在 `json_data` 文件中。
+
+```
+$ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" https://api.qmk.fm/v1/compile
+{
+  "enqueued": true,
+  "job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6"
+}
+```
+
+## 检查状态
+
+键映射配置提交后，可以简单地通过 HTTP GET 请求来查询job状态：
+
+```
+$ curl https://api.qmk.fm/v1/compile/ea1514b3-bdfc-4a7b-9b5c-08752684f7f6
+{
+  "created_at": "Sat, 19 Aug 2017 21:39:12 GMT",
+  "enqueued_at": "Sat, 19 Aug 2017 21:39:12 GMT",
+  "id": "f5f9b992-73b4-479b-8236-df1deb37c163",
+  "status": "running",
+  "result": null
+}
+```
+
+这份信息告诉我们编译job已经提交到队列中且正在执行。job的状态有5种：
+
+* **failed（失败）**: 编译服务出现问题。
+* **finished（完成）**: 编译已完成，`result` 字段中保存了编译结果。
+* **queued（排队中）**: 键映射job在等待可用的编译服务器。
+* **running（执行中）**: 编译进行中，应当很快就会结束。
+* **unknown（未知）**: 出现了较严重的错误，请给我们[提交一个bug](https://github.com/qmk/qmk_compiler/issues).
+
+## 确认编译产出
+
+编译job完成后请查看 `result` 字段，该字段下保存了如下信息项的哈希表数据：
+
+* `firmware_binary_url`: 用于刷写的固件文件URL列表
+* `firmware_keymap_url`: `keymap.c` 文件URL列表
+* `firmware_source_url`: 完整的固件源代码URL列表
+* `output`: 编译job的stdout及stderr输出信息，所有错误信息都会在这里。

docs/zh-cn/api_overview.md

@@ -0,0 +1,20 @@
+# QMK API
+
+<!---
+  original document: 0.15.12:docs/api_overview.md
+  git diff 0.15.12 HEAD -- docs/api_overview.md | cat
+-->
+
+QMK API提供了一套可用于Web及GUI工具可用的异步API，用于实现将任何[QMK](https://qmk.fm/)支持的键盘的键映射方案进行编译。已有的键映射模板支持所有的QMK键码并且不需要额外的C代码需求。键盘的维护团队可以提供新的模板来启用更多功能的支持。
+
+## App开发者
+
+若您是一位意愿将这套API引入您的程序中的移动端App开发者，请参阅[API使用指引](zh-cn/api_docs.md)。
+
+## 键盘维护团队
+
+若您希望强化您维护的键盘方案在QMK编译API中的支持，请参阅[键盘支持](zh-cn/reference_configurator_support.md)。
+
+## 后端开发者
+
+若您对这套API系统本身感兴趣，请参阅[开发环境](zh-cn/api_development_environment.md)搭建环境并继续深入探索[架构总览](zh-cn/api_development_overview.md)。

docs/zh-cn/cli.md

@@ -0,0 +1,43 @@
+# QMK CLI :id=qmk-cli
+
+<!---
+  original document: 0.15.12:docs/cli.md
+  git diff 0.15.12 HEAD -- docs/cli.md | cat
+-->
+
+## 总览 :id=overview
+
+QMK CLI可以让构建QMK键盘的过程更轻松一些，我们已提供的一批指令可用于简化及流式化地处理一些常见工作，如获取并编译QMK固件，创建新的键映射等。
+
+### 依赖项 :id=requirements
+
+QMK依赖Python 3.6或更高版本。我们已经尽力缩减依赖项，但在[`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt)中的依赖项是需安装的包。在安装QMK CLI时这些依赖项也会自动完成安装。
+
+### 通过 Homebrew 安装(macOS 及部分 Linux) :id=install-using-homebrew
+
+若已安装[Homebrew](https://brew.sh)，可以按如下方法安装QMK:
+
+```
+brew install qmk/qmk/qmk
+export QMK_HOME='~/qmk_firmware' # 可选，指定 `qmk_firmware` 的路径
+qmk setup  # 拉取 `qmk/qmk_firmware` 并选择性地配置构建环境
+```
+
+### 通过 pip 安装 :id=install-using-easy_install-or-pip
+
+未在以上列出的操作系统可以手动安装QMK。首先确认已安装Python 3.6（或更高版本）及 pip，然后通过如下指令安装QMK：
+
+```
+python3 -m pip install qmk
+export QMK_HOME='~/qmk_firmware' # 可选，指定 `qmk_firmware` 的路径
+qmk setup  # 拉取 `qmk/qmk_firmware` 并选择性地配置构建环境
+```
+
+### 其它操作系统的安装包 :id=packaging-for-other-operating-systems
+
+我们正在寻求可以制作维护更多操作系统下可用的 `qmk` 安装包的开发者，若您愿意为您的操作系统制作安装包，请遵循如下指引：
+
+* 当该系统下的最佳实践与本指引冲突时，请遵循系统的最佳实践方案
+    * 但请在注释中列明此处违反这份指引的原因
+* 在 virtualenv 下安装
+* 指引用户去设置 `QMK_HOME` 环境变量，使得固件源文件拉取路径不再是默认的 `~/qmk_firmware`

docs/zh-cn/cli_commands.md

@@ -0,0 +1,503 @@
+# QMK CLI 命令
+
+<!---
+  original document: 0.15.12:docs/cli_commands.md
+  git diff 0.15.12 HEAD -- docs/cli_commands.md | cat
+-->
+
+# 用户命令
+
+## `qmk compile`
+
+该命令用于在指定目录下编译固件，可用于构建<https://config.qmk.fm>导出的JSON数据，代码库中的键映射，或是当前目录下的键盘。
+
+该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。
+
+**用于配置器导出的数据时**：
+
+```
+qmk compile [-c] <configuratorExport.json>
+```
+
+**用于键映射时**：
+
+```
+qmk compile [-c] [-e <var>=<value>] [-j <num_jobs>] -kb <keyboard_name> -km <keymap_name>
+```
+
+**在键盘目录下时**：  
+
+须在存在默认键映射的键盘目录下执行，或是在键盘的键映射子目录下，否则须指定参数 `--keymap <keymap_name>`
+```
+qmk compile
+```
+
+**构建所有支持该键映射的键盘时**：
+
+```
+qmk compile -kb all -km <keymap_name>
+```
+
+**示例**：
+```
+$ qmk config compile.keymap=default
+$ cd ~/qmk_firmware/keyboards/planck/rev6
+$ qmk compile
+Ψ Compiling keymap with make planck/rev6:default
+...
+```
+指定键映射参数时
+
+```
+$ cd ~/qmk_firmware/keyboards/clueboard/66/rev4 
+$ qmk compile -km 66_iso
+Ψ Compiling keymap with make clueboard/66/rev4:66_iso
+...
+```
+位于键盘目录下时
+
+```
+$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
+$ qmk compile
+Ψ Compiling keymap with make gh60/satan:colemak
+...
+```
+
+**在配列目录下时**：  
+
+必须是在 `qmk_firmware/layouts/` 下的键映射目录下。
+```
+qmk compile -kb <keyboard_name>
+```
+
+**示例**：
+```
+$ cd ~/qmk_firmware/layouts/community/60_ansi/mechmerlin-ansi
+$ qmk compile -kb dz60
+Ψ Compiling keymap with make dz60:mechmerlin-ansi
+...
+```
+
+**并行编译**：
+
+在编译时添加 `-j`/`--parallel` 开关可能有助于加快编译速度。
+```
+qmk compile -j <num_jobs> -kb <keyboard_name>
+```
+`num_jobs` 用于指定并行的job上限，将其设置为0可以实现无限制的并行编译。
+```
+qmk compile -j 0 -kb <keyboard_name>
+```
+
+## `qmk flash` :id=qmk-flash
+
+该命令与 `qmk compile` 类似，但额外地可以指定bootloader。bootloader参数是可选的，默认会指定为 `:flash`。可通过 `-bl <bootloader>` 来指定bootloader。请查阅[刷写固件](zh-cn/flashing.md)指引以深入了解可用的bootloader信息。
+
+该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。
+
+**用于配置器导出的数据时**：
+
+```
+qmk flash [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>] <configuratorExport.json>
+```
+
+**用于键映射时**：
+
+```
+qmk flash -kb <keyboard_name> -km <keymap_name> [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>]
+```
+
+**列出所有bootloader**
+
+```
+qmk flash -b
+```
+
+## `qmk config`
+
+该命令用于配置QMK功能，完整的 `qmk config` 文档参见[CLI配置](zh-cn/cli_configuration.md)。
+
+**使用方法**：
+
+```
+qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
+```
+
+## `qmk cd`
+
+该命令会启动一个新的 shell 会话并定位到 `qmk_firmware` 所在目录。
+
+须留意如果你已经位于 `QMK_HOME` 下的某个位置（比如 `keyboards/` 目录中），该指令不会生效。
+
+若要退回到原来的 shell 会话，只需要执行 `exit`。
+
+**使用方法**:
+
+```
+qmk cd
+```
+
+## `qmk console`
+
+该命令用于连接键盘终端并展示调试信息。仅当键盘固件通过 `CONSOLE_ENABLE=yes` 编译时有效。
+
+**用法**：
+
+```
+qmk console [-d <pid>:<vid>[:<index>]] [-l] [-n] [-t] [-w <seconds>]
+```
+
+**示例**：
+
+连接到所有可用的键盘并输出终端信息：
+
+```
+qmk console
+```
+
+列出所有设备：
+
+```
+qmk console -l
+```
+
+仅输出 clueboard/66/rev3 键盘的信息:
+
+```
+qmk console -d C1ED:2370
+```
+
+仅输出第二把 clueboard/66/rev3 键盘的信息:
+
+```
+qmk console -d C1ED:2370:2
+```
+
+输出时间戳及VID:PID以替代键盘名：
+
+```
+qmk console -n -t
+```
+
+屏蔽bootloader的消息：
+
+```
+qmk console --no-bootloaders
+```
+
+## `qmk doctor`
+
+该命令用以检查你的开发环境并对发现的潜在的构建及刷写问题进行提醒，如果您乐意，它也可以修复其中大部分问题。
+
+**用法**：
+
+```
+qmk doctor [-y] [-n]
+```
+
+**示例**：
+
+检查开发环境中的问题并提示是否修复：
+
+    qmk doctor
+
+检查开发环境中的问题并自动进行修复：
+
+    qmk doctor -y
+
+检查开发环境中的问题，仅生成报告：
+
+    qmk doctor -n
+
+## `qmk format-json`
+
+将JSON文件格式化为（尽量）便于阅读的形式。会自动分辨JSON结构类型（info.json还是keymap.json），必要时也可以通过 `--format` 指定。
+
+**用法**：
+
+```
+qmk format-json [-f FORMAT] <json_file>
+```
+
+## `qmk info`
+
+展示QMK中的键盘及键映射信息，该命令用来获取键盘信息，输出配列，展示底层按键矩阵，及格式化地输出键映射JSON数据。
+
+**用法**：
+
+```
+qmk info [-f FORMAT] [-m] [-l] [-km KEYMAP] [-kb KEYBOARD]
+```
+
+该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。
+
+**示例**：
+
+输出键盘的基础信息：
+
+    qmk info -kb planck/rev5
+
+输出键盘的矩阵信息：
+
+    qmk info -kb ergodox_ez -m
+
+输出键盘的键映射JSON数据：
+
+    qmk info -kb clueboard/california -km default
+
+## `qmk json2c`
+
+从QMK配置器导出的数据中生成 keymap.c 文件
+Creates a keymap.c from a QMK Configurator export.
+
+**用法**：
+
+```
+qmk json2c [-o OUTPUT] filename
+```
+
+## `qmk c2json`
+
+从 keymap.c 文件中生成 keymap.json
+**注意：** 解析C代码文件并不容易，该命令有可能无法对你的键映射文件生效，不使用C预处理代码有时可以解决问题。
+
+**用法**：
+
+```
+qmk c2json -km KEYMAP -kb KEYBOARD [-q] [--no-cpp] [-o OUTPUT] filename
+```
+
+## `qmk lint`
+
+检查键盘及键映射数据并提示出常见错误与问题，以及不符合模板规范的地方。
+
+**用法**：
+
+```
+qmk lint [-km KEYMAP] [-kb KEYBOARD] [--strict]
+```
+
+该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。
+
+**示例**：
+
+基本的lint检查：
+
+    qmk lint -kb rominronin/katana60/rev2
+
+## `qmk list-keyboards`
+
+该命令可以列出 `qmk_firmware` 中所有的键盘
+
+**用法**：
+
+```
+qmk list-keyboards
+```
+
+## `qmk list-keymaps`
+
+该命令可以列出指定键盘（及指定版本）下的所有键映射。
+
+该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。
+
+**用法**：
+
+```
+qmk list-keymaps -kb planck/ez
+```
+
+## `qmk new-keyboard`
+
+该命令可基于现有模板创建出新的键盘定义。
+
+对于未给出的参数，会提示你输入，若未传入 `-u` 参数且 .gitconfig 中设置了 `user.name`，则会提示你使用该值作为默认用户名。
+
+**用法**：
+
+```
+qmk new-keyboard [-kb KEYBOARD] [-t {avr,ps2avrgb}] -u USERNAME
+```
+
+## `qmk new-keymap`
+
+该命令可基于键盘已有的默认键映射创建新的键映射。
+
+该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。
+
+**用法**：
+
+```
+qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
+```
+
+## `qmk clean`
+
+该命令会清理 `.build` 目录，若传入 `--all` 开关，在 `qmk_firmware` 下的所有.hex及.bin文件也会一并删除。
+
+**用法**：
+
+```
+qmk clean [-a]
+```
+
+---
+
+# 面向开发者的命令
+
+## `qmk format-text`
+
+该命令会重新格式化并统一文件的换行符。
+
+代码库下所有的文件须使用Unix换行符（LF）。
+若你在**Windows**下进行开发，必须确保文件中的换行符是正确的，才能让你的PR被允许合入。
+
+```
+qmk format-text
+```
+
+## `qmk format-c`
+
+该命令会使用clang-format来格式化C代码。
+
+不带参数地执行该命令以用来格式化核心代码相关的改动，默认会通过 `git diff` 来检查 `origin/master`， 可以通过 `-b <分支名>` 来改变检查的分支。
+
+带着 `-a` 开关执行命令会格式化所有的核心代码，也可以在命令行中传入文件名来指定格式化某个文件。
+
+**用以处理指定文件时**：
+
+```
+qmk format-c [file1] [file2] [...] [fileN]
+```
+
+**用以处理所有的核心代码时**：
+
+```
+qmk format-c -a
+```
+
+**用以处理 origin/master 下的所有改动时**：
+
+```
+qmk format-c
+```
+
+**用以处理指定分支下的所有改动时**：
+
+```
+qmk format-c -b branch_name
+```
+
+## `qmk generate-compilation-database`
+
+**用法**:
+
+```
+qmk generate-compilation-database [-kb KEYBOARD] [-km KEYMAP]
+```
+
+创建新 `compile_commands.json` 文件。
+
+你的IDE/编辑器是否使用了“编程语言本地服务器”（language server）且 _总是_ 无法找到全部的包含文件（include files）？是不是很讨厌红色的波浪线？想不想让你的编辑器看得懂 `#include QMK_KEYBOARD_H`？你需要的是一个[编译数据库](https://clang.llvm.org/docs/JSONCompilationDatabase.html)！而 QMK 可以帮助你构建出一个。
+
+该命令需要知道你在构建的是哪个键盘及键映射，它使用与 `qmk compile` 命令一样的选项：参数、当前目录以及配置文件。
+
+**示例：**
+
+```
+$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
+$ qmk generate-compilation-database
+Ψ Making clean
+Ψ Gathering build instructions from make -n gh60/satan:colemak
+Ψ Found 50 compile commands
+Ψ Writing build database to /Users/you/src/qmk_firmware/compile_commands.json
+```
+
+现在可以打开你的开发环境并享受没有波浪线的日子了。
+
+## `qmk docs`
+
+该命令会在本地启动一个HTTP服务，从而你可以浏览及改进文档，默认端口号为8936，使用 `-b`/`--browser` 开关可以让该命令自动通过默认浏览器打开链接地址。
+
+**用法**：
+
+```
+qmk docs [-b] [-p PORT]
+```
+
+## `qmk generate-docs`
+
+该命令可以在本地生成QMK文档，用以文档的常规浏览使用，或进行文档改进工作。可以使用类似[serve](https://www.npmjs.com/package/serve)这样的工具来浏览生成的文档文件。
+
+**用法**：
+
+```
+qmk generate-docs
+```
+
+## `qmk generate-rgb-breathe-table`
+
+该命令可以生成用于[RGB灯光](zh-cn/feature_rgblight.md)的呼吸效果的查询表（LUT）头文件。将该文件命名为 `rgblight_breathe_table.h` 并放入键盘或键映射目录下，可以覆盖替换 `quantum/rgblight/` 下的默认LUT。
+
+**用法**：
+
+```
+qmk generate-rgb-breathe-table [-q] [-o OUTPUT] [-m MAX] [-c CENTER]
+```
+
+## `qmk kle2json`
+
+该命令可以将KLE原始数据转换成QMK配置器的JSON数据，可接受的输入可以是文件绝对路径，或当前目录下的文件名。若 `info.json` 文件存在，默认不会进行覆盖，通过指定 `-f` 或 `--force` 开关可以允许覆盖。
+
+**用法**：
+
+```
+qmk kle2json [-f] <filename>
+```
+
+**示例**：
+
+```
+$ qmk kle2json kle.txt 
+☒ File info.json already exists, use -f or --force to overwrite.
+```
+
+```
+$ qmk kle2json -f kle.txt -f
+Ψ Wrote out to info.json
+```
+
+## `qmk format-python`
+
+该命令可以对 `qmk_firmware` 下的python代码进行格式化。
+
+**用法**：
+
+```
+qmk format-python
+```
+
+## `qmk pytest`
+
+该命令会执行python测试框架，在你更改了python代码后，应确保该命令可以成功执行。
+
+**用法**：
+
+```
+qmk pytest
+```
+
+**示例**:
+
+执行全部的测试套件：
+
+    qmk pytest
+
+执行指定的测试用例组：
+
+    qmk pytest -t qmk.tests.test_cli_commands
+
+执行单个测试用例：
+
+    qmk pytest -t qmk.tests.test_cli_commands.test_c2json
+    qmk pytest -t qmk.tests.test_qmk_path

docs/zh-cn/cli_configuration.md

@@ -0,0 +1,126 @@
+# QMK CLI 配置
+
+<!---
+  original document: 0.15.12:docs/cli_configuration.md
+  git diff 0.15.12 HEAD -- docs/cli_configuration.md | cat
+-->
+
+本文详述了 `qmk config` 功能及作用。
+
+# 介绍
+
+QMK CLI的配置系统是一套键/值（key/value）数据系统，每个键由一个子指令和一个参数名组成，通过点号（英文句号）分隔。这使得配置项可以简单直接地映射到命令行参数上。
+
+## 简单示例
+
+作为一个示例，对于指令 `qmk compile --keyboard clueboard/66/rev4 --keymap default`
+
+其存在两个命令行参数，可以通过如下方式从配置中读取：
+
+* `compile.keyboard`
+* `compile.keymap`
+
+可以这样设置：
+
+```
+$ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default
+compile.keyboard: None -> clueboard/66/rev4
+compile.keymap: None -> default
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+
+现在每次执行 `qmk compile` 时都不需要指定键盘及键映射参数了。
+
+## 设置用户级的默认配置
+
+当你需要在多个命令中使用一致的配置项时，比如很多命令都需要的 `--keyboard` 参数，相比于每次执行命令都去指定该参数值，你可以直接设置用户级的配置值，即可将该配置用于所有的命令。
+
+示例：
+
+```
+$ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default
+user.keyboard: None -> clueboard/66/rev4
+user.keymap: None -> default
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+
+# CLI文档 (`qmk config`)
+
+`qmk config` 命令可以管理配置数据。当不带额外参数执行时，会输出所有已有配置。存在参数时这些参数将被视为配置项参数，其格式须满足如下形式且无空格分隔：
+
+    <subcommand|general|default>[.<key>][=<value>]
+
+## 设置配置值
+
+在配置项的键后加 = 号进行值的设置，配置项的键必须是 `<section>.<key>` 的完整形式。
+
+举例：
+
+```
+$ qmk config default.keymap=default
+default.keymap: None -> default
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+
+## 读取配置值
+
+可以读取整个配置文件、单独配置键或是一整个配置系列，也可以同时指定读取多个配置项。
+
+### 全量配置读取示例
+
+    qmk config
+
+### 单系列配置读取示例
+
+    qmk config compile
+
+### 单配置项读取示例
+
+    qmk config compile.keyboard
+
+### 多配置项读取示例
+
+    qmk config user compile.keyboard compile.keymap
+
+## 删除配置值
+
+将配置值设置为 `None` 即可删除该配置值。
+
+示例：
+
+```
+$ qmk config default.keymap=None
+default.keymap: default -> None
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+
+## 批量操作
+
+一个指令中可以合并执行多个读写操作，将依序进行执行输出：
+
+```
+$ qmk config compile default.keymap=default compile.keymap=None
+compile.keymap=skully
+compile.keyboard=clueboard/66_hotswap/gen1
+default.keymap: None -> default
+compile.keymap: skully -> None
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+
+# 用户配置相关的配置项
+
+| 配置项 | 默认值 | 描述 |
+|-------|-------|------|
+| user.keyboard | None | 键盘路径（举例：`clueboard/66/rev4`） |
+| user.keymap | None | 键盘名称（举例：`default`） |
+| user.name | None | 用户的Github用户名 |
+
+# 所有配置项
+
+| 配置项 | 默认值 | 描述 |
+|-------|-------|------|
+| compile.keyboard | None | 键盘路径（举例：`clueboard/66/rev4`） |
+| compile.keymap | None | 键盘名称（举例：`default`） |
+| hello.name | None | 执行时展示的欢迎信息 |
+| new_keyboard.keyboard | None | 键盘路径（举例：`clueboard/66/rev4`） |
+| new_keyboard.keymap | None | 键盘名称（举例：`default`） |

docs/zh-cn/cli_tab_complete.md

@@ -0,0 +1,32 @@
+# QMK Tab补全
+
+<!---
+  original document: 0.15.12:docs/cli_tab_complete.md
+  git diff 0.15.12 HEAD -- docs/cli_tab_complete.md | cat
+-->
+
+在使用Bash 4.2及更高版本、Zsh或FiSH时，可以启用QMK CLI的Tab补全功能，可以实现对 `qmk` 参数中的开关、键盘、文件等参数的自动补全。
+
+## 设置
+
+有以下几种启用Tab补全的方法。
+
+### 仅当前用户生效
+
+将以下内容添加到文件 `.profile` 或 `.bashrc` 的末尾:
+
+    source ~/qmk_firmware/util/qmk_tab_complete.sh
+
+若你的 `qmk_firmware` 存放在其它路径，以上路径也需要调整。
+
+### 系统级的符号关联
+
+若想让所有本地用户都可以实现Tab补全，可以按如下方法添加符号连接到 `qmk_tab_complete.sh` 脚本：
+
+    `ln -s ~/qmk_firmware/util/qmk_tab_complete.sh /etc/profile.d/qmk_tab_complete.sh`
+
+### 系统级的脚本拷贝
+
+有时符号连接的方案无效，可以改用拷贝文件到指定位置的方案。但须留意该Tab补全脚本可能会不定时更新，你需要定期重新拷贝一次该脚本。
+
+    cp util/qmk_tab_complete.sh /etc/profile.d

docs/zh-cn/configurator_architecture.md

@@ -0,0 +1,66 @@
+# QMK配置器框架
+
+<!---
+  original document: 0.15.12:docs/configurator_architecture.md
+  git diff 0.15.12 HEAD -- docs/configurator_architecture.md | cat
+-->
+
+本章节提供了QMK配置器前端技术框架信息，若你对QMK配置器前端工程本身感兴趣，可以从[QMK配置器](https://github.com/qmk/qmk_configurator)代码库开始。
+
+# 总览
+
+![QMK配置器技术框架图](./../configurator_diagram.svg)
+
+# 详述
+
+QMK配置器基于[单页面框架](https://en.wikipedia.org/wiki/Single-page_application)实现，供使用者创建兼容QMK键盘的自定义键映射方案。键映射方案可以导出为JSON格式的数据，也可以编译出可通过[QMK工具箱](https://github.com/qmk/qmk_toolbox)刷写到键盘中的固件文件。
+
+配置器从“键盘元数据仓库（Keyboard Metadata store）”获取键盘元数据，编译请求通过QMK API提交，编译产出放在S3兼容的数据仓库[Digital Ocean空间](https://www.digitalocean.com/products/spaces/)中。
+
+## 配置器前端
+
+地址：<https://config.qmk.fm>
+
+[配置器前端](https://config.qmk.fm)会编译并产出一些静态文件并通过Github Pages托管，每当[QMK配置器 `master`](https://github.com/qmk/qmk_configurator)分支收到推送的提交时都会触发。可以通过[QMK配置器 actions页面](https://github.com/qmk/qmk_configurator/actions/workflows/build.yml)查看这些job的状态。
+
+## 键盘元数据
+
+地址：<https://keyboards.qmk.fm>
+
+每当[qmk_firmware](https://github.com/qmk/qmk_firmware)仓库中的键盘定义变化时，会生成JSON格式的键盘元数据，并上传到指定空间用于配置器生成每种键盘的UI展现。可以在[QMK固件 actions页面](https://github.com/qmk/qmk_firmware/actions/workflows/api.yml)查看相关job的状态。如果你是QMK开发团队成员（Collaborator），可以使用 `workflow_dispatch` 事件触发器来手动执行该job。
+
+## QMK API
+
+地址：<http://api.qmk.fm>
+
+QMK API接受 `keymap.json` 文件输入并进行编译，这和你在 `qmk compile` 和 `qmk flash` 中使用的文件一样。当 `keymap.json` 文件被提交后，浏览器中的页面将定时查看job状态（每2秒一次，有时更久一些）直到job完成。最终产出的JSON描述信息里包含了键映射方案的源文件，及编译出的二进制的可下载链接地址。
+
+为遵循GPL协议，QMK API会确保源文件及编译产出总是同时提供的。
+
+API有3种非异常的回应状态-
+
+1. 编译job排队中
+2. 编译job执行中
+3. 编译job已完成
+
+### 编译job排队中
+
+此状态表明[QMK编译器](#QMK编译器)节点还未选中该job，在配置器页面此时会显示“等待一个可用的烤炉（Waiting for an oven）”。
+
+### 编译job执行中
+
+此状态说明编译job已经在执行中，配置器页面会显示为“烤制中”(Baking)。
+
+### 编译job已完成
+
+此状态说明编译job已经执行完毕，输出的JSON格式的状态信息里有源文件及编译产出的二进制文件的下载链接项。
+
+## Redis/RQ
+
+QMK API通过Redis队列分发job到可用的[QMK编译器](#QMK编译器)节点。接收到的 `keymap.json` 文件先送到RQ队列，而 `qmk_compiler` 节点则从中拉取执行。
+
+## QMK编译器
+
+[QMK编译器](https://github.com/qmk/qmk_compiler)负责执行 `keymap.json` 文件的实际编译工作。它的工作逻辑是先拉取有请求的 `qmk_firmware` 分支代码，执行 `qmk compile keymap.json`，最后上传源文件及二进制产出到Digital Ocean空间中。
+
+当用户需要下载源代码/二进制文件时，API会给出重定向后的已鉴权地址链接。

docs/zh-cn/configurator_default_keymaps.md

@@ -0,0 +1,198 @@
+# 向QMK配置器中添加默认键映射 :id=adding-default-keymaps
+
+<!---
+  original document: 0.15.12:docs/configurator_default_keymaps.md
+  git diff 0.15.12 HEAD -- docs/configurator_default_keymaps.md | cat
+-->
+
+本章节描述了如何向QMK配置器中添加一款键盘的默认键映射
+
+
+## 技术信息 :id=technical-information
+
+QMK配置器使用JSON作为键映射的本地文件格式。我们尽力确保其行为与在 `qmk_firmware` 中 执行 `make <keyboard>:default` 时一致。
+
+该目录下的键映射需要定义四个键值对：
+
+* `keyboard` (字符串)
+  * 键盘名称，与执行 `make` 进行编译时使用的一致（如 `make 1upkeyboards/1up60rgb:default`）。
+* `keymap` (字符串)
+  * 应设置为 `default`.
+* `layout` (字符串)
+  * 默认键映射应使用的配列宏定义。
+* `layers` (数组)
+  * 键映射数据。此键下的每行元素对应一个层定义，层定义中包含该层的键码组成信息。
+
+额外地，大部分键映射中还有一个 `commit` 项，该项并不是QMK配置器后端服务API所需，而是用于告知配置器维护者这份JSON键映射数据来源于代码库中的哪个版本的键映射。该值为 `qmk_firmware` 代码库中最后一次修改键盘默认 `keymap.c` 文件提交的commit的SHA标记。该SHA值的获取方式是拉取[`qmk/qmk_firmware` 库的 `master`分支](https://github.com/qmk/qmk_firmware/tree/master/)后，执行 `git log -1 --pretty=oneline -- keyboards/<keyboard>/keymaps/default/keymap.c`（若键盘有什么问题且存在 `keymap.json` 文件，则用之作为替代），执行结果应类似于：
+
+```
+f14629ed1cd7c7ec9089604d64f29a99981558e8 Remove/migrate action_get_macro()s from default keymaps (#5625)
+```
+
+本例中，`f14629ed1cd7c7ec9089604d64f29a99981558e8` 即应为 `commit` 的值。
+
+
+## 示例 :id=example
+
+若某人想添加H87a Hineybush键盘的默认键映射方案，应到 `qmk_firmware` 下H87a的默认键映射下执行上述 `git log` 命令：
+
+```
+user ~/qmk_firmware (master)
+$ git log -1 --pretty=oneline master -- keyboards/hineybush/h87a/keymaps/default/keymap.c
+ef8878fba5d3786e3f9c66436da63a560cd36ac9 Hineybush h87a lock indicators (#8237)
+```
+
+在我们获取了commit哈希值后，还需要键映射定义（为加强可读性进行了编辑处理）：
+
+```c
+...
+#include QMK_KEYBOARD_H
+
+const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+
+  [0] = LAYOUT_all(
+    KC_ESC,           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_PSCR, KC_SLCK, KC_PAUS,
+    KC_GRV,  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_BSPC,    KC_INS,  KC_HOME, KC_PGUP,
+    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,             KC_DEL,  KC_END,  KC_PGDN,
+    KC_CAPS, KC_A,    KC_S,    KC_D,    KC_F,    KC_G,    KC_H,    KC_J,    KC_K,    KC_L,    KC_SCLN, KC_QUOT, KC_NUHS, KC_ENT,
+    KC_LSFT, KC_NUBS, KC_Z,    KC_X,    KC_C,    KC_V,    KC_B,    KC_N,    KC_M,    KC_COMM, KC_DOT,  KC_SLSH, KC_RSFT, KC_TRNS,                      KC_UP,
+    KC_LCTL, KC_LGUI, KC_LALT,                            KC_SPC,                             KC_RALT, MO(1),   KC_RGUI, KC_RCTL,             KC_LEFT, KC_DOWN, KC_RGHT),
+
+  [1] = LAYOUT_all(
+    KC_TRNS,          KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, RGB_TOG, RGB_MOD, RGB_HUD, RGB_HUI, RGB_SAD, RGB_SAI, RGB_VAD, RGB_VAI,             BL_TOGG, BL_DEC,  BL_INC,
+    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_VOLU,
+    KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, RESET,   KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,             KC_MPLY, KC_MNXT, KC_VOLD,
+    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_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),
+
+};
+```
+
+默认键映射使用了 `LAYOUT_all` 宏，最后其会成为 `layout` 项的值。编译为QMK配置器的JSON键映射数据后，输出文件应为：
+
+```json
+{
+  "keyboard": "hineybush/h87a",
+  "keymap": "default",
+  "commit": "ef8878fba5d3786e3f9c66436da63a560cd36ac9",
+  "layout": "LAYOUT_all",
+  "layers": [
+    [
+      "KC_ESC",             "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_PSCR", "KC_SLCK", "KC_PAUS",
+      "KC_GRV",  "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_BSPC",    "KC_INS",  "KC_HOME", "KC_PGUP",
+      "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",               "KC_DEL",  "KC_END",  "KC_PGDN",
+      "KC_CAPS", "KC_A",    "KC_S",    "KC_D",    "KC_F",    "KC_G",    "KC_H",    "KC_J",    "KC_K",    "KC_L",    "KC_SCLN", "KC_QUOT", "KC_NUHS", "KC_ENT",
+      "KC_LSFT", "KC_NUBS", "KC_Z",    "KC_X",    "KC_C",    "KC_V",    "KC_B",    "KC_N",    "KC_M",    "KC_COMM", "KC_DOT",  "KC_SLSH", "KC_RSFT", "KC_TRNS",                          "KC_UP",
+      "KC_LCTL", "KC_LGUI", "KC_LALT",                                  "KC_SPC",                                   "KC_RALT", "MO(1)",   "KC_RGUI", "KC_RCTL",               "KC_LEFT", "KC_DOWN", "KC_RGHT"
+    ],
+    [
+      "KC_TRNS",            "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "RGB_TOG", "RGB_MOD", "RGB_HUD", "RGB_HUI", "RGB_SAD", "RGB_SAI", "RGB_VAD", "RGB_VAI",               "BL_TOGG", "BL_DEC",  "BL_INC",
+      "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_VOLU",
+      "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "RESET",   "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS",               "KC_MPLY", "KC_MNXT", "KC_VOLD",
+      "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_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"
+    ]
+  ]
+}
+```
+
+`layers` 数组中的空白区域不影响键映射功能，仅为了方便阅读。
+
+
+## 附加说明 :id=caveats
+
+### 层定义只能通过序号进行引用 :id=layer-references
+
+QMK中常见的一种做法是通过一系列 `#define` 或 `enum` 类型声明来对层定义进行命名：
+
+```c
+enum layer_names {
+    _BASE,
+    _MEDIA,
+    _FN
+};
+```
+
+对于C代码来讲可行，但对于配置器来讲，你*必须*使用层序号 - 上例中的`MO(_FN)` 应使用 `MO(2)`。
+
+### 不支持任何形式的定制化代码 :id=custom-code
+
+需要在 keymap.c 文件中添加函数代码的功能，如Tap Dance或是Unicode，都*完全*无法在配置器中构建。即便是在 `qmk_firmware` 代码库中在键盘定义中设置了 `TAP_DANCE_ENABLE = yes`，也只会导致*任何*固件构建在配置器中行不通。这是由API及JSON格式的键映射数据同时造成的限制。
+
+### 对自定义键码的不完全支持 :id=custom-keycodes
+
+仅有一个方案可以支持自定义键码：若自定义键码的逻辑实现是在 qmk_firmware 下的键盘定义中完成的，而非在键映射中，那么这个键码*可以*在配置器中使用且*可以*编译运行。（因此，）相对于在 `keymap.c` 中使用如下代码段：
+
+```c
+enum custom_keycodes {
+    MACRO_1 = SAFE_RANGE,
+    MACRO_2,
+    MACRO_3
+};
+...
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+    switch(keycode) {
+        case MACRO_1:
+            if (record->event.pressed) {
+                SEND_STRING("This is macro #1.");
+            }
+            return false;
+        case MACRO_2:
+            if (record->event.pressed) {
+                SEND_STRING("This is macro #2.");
+            }
+            return false;
+        case MACRO_3:
+            if (record->event.pressed) {
+                SEND_STRING("This is macro #3.");
+            }
+            return false;
+    }
+    return true;
+};
+```
+
+... 请将键码的 `enum` 定义块添加到键盘的头文件（`<keyboard.h>`）中，例如（留意 `enum` 在这里命名为 `keyboard_keycodes`）：
+
+```c
+enum keyboard_keycodes {
+    MACRO_1 = SAFE_RANGE,
+    MACRO_2,
+    MACRO_3,
+    NEW_SAFE_RANGE  // 重要!
+};
+```
+
+... 之后在 `<keyboard>.c` 中的 `process_record_kb()` 代码逻辑应为：
+
+```c
+bool process_record_kb(uint16_t keycode, keyrecord_t *record) {
+    switch(keycode) {
+        case MACRO_1:
+            if (record->event.pressed) {
+                SEND_STRING("This is macro #1.");
+            }
+            return false;
+        case MACRO_2:
+            if (record->event.pressed) {
+                SEND_STRING("This is macro #2.");
+            }
+            return false;
+        case MACRO_3:
+            if (record->event.pressed) {
+                SEND_STRING("This is macro #3.");
+            }
+            return false;
+    }
+    return process_record_user(keycode, record);
+};
+```
+
+注意最后的 `process_record_user()` 调用，若用户需要添加自定义键码到键映射中，须使用 `NEW_SAFE_RANGE` 替代 `SAFE_RANGE`，而其定义来自于上面键盘层定义中。
+
+
+## 更多资料 :id=additional-reading
+
+为了让QMK配置器支持你的键盘，你的键盘定义必须存在于 `qmk_firmware` 代码库的 `master` 分支中。相关操作指引，请参见[在QMK配置器中支持你的键盘](zh-cn/reference_configurator_support.md).

docs/zh-cn/configurator_step_by_step.md

@@ -0,0 +1,63 @@
+# QMK 配置器: 入门
+
+<!---
+  original document: 0.15.12:docs/configurator_step_by_step.md
+  git diff 0.15.12 HEAD -- docs/configurator_step_by_step.md | cat
+-->
+
+本章节描述了如何使用QMK配置器构建出固件文件的过程。
+
+## 第一步：选择键盘
+
+从下拉列表中选择一款用于创建键映射的键盘。
+
+?> 当键盘有多个版本可选择时，请确保选择正确。
+
+因为很重要，这里我再次说一遍：
+
+!> **请选择正确的版本！**
+
+如果你的键盘声称是基于QMK的但未在列表中，可能是开发者还未提交给我们，或者提交还未被合并进来。若在[Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard)中没有找到请求支持该键盘的issue，请到[QMK固件](https://github.com/qmk/qmk_firmware/issues)提交一个issue。也有一些基于QMK的键盘是由制造商自己的GitHub账号在维护着，请也确认一下。  <!-- FIXME(skullydazed): This feels too wordy and I'm not sure we want to encourage these kinds of issues. Also, should we prompt them to bug the manufacutrer? -->
+
+## 第二部：选择键盘配列
+
+选择最适合你要创建的键映射的配列，一些键盘的配列不完整或有问题，后续会逐渐支持。
+
+!> 有时会遇到没有特别适合的配列的情况，请选择 `LAYOUT_all`。
+
+## 第三步：命名你的键映射
+
+如何起名完全取决于你。
+
+?> 如果编译时遇到了问题，可能是因为QMK固件代码库中已经有了同名项，可以尝试改一下名字。
+
+## 第四步：设计你的键映射
+
+以下三种方法可以添加键码：
+
+1. 拖拽
+2. 点击布局上的空白项，再点击所需的键码
+3. 点击布局上的空白项, 再点击你物理键盘上的按键
+
+?> 鼠标在键上悬停时会有一个键码值的提示出现，详细描述信息请参见:
+
+* [基础键码资料](zh-cn/keycodes_basic.md)
+* [进阶键码资料](zh-cn/feature_advanced_keycodes.md)
+
+!> 如果你选择的配列与物理实机有出入，请将不需要的按键留空。如果不清楚应该用哪个键，例如，你只需要一个退格键，但 `LAYOUT_all` 中有两个退格键，须将两个键都放上一样的键码。
+
+## 第五步：保存键映射留待后续修订
+
+当你调整完毕键映射方案，或打算以后继续编辑，点击 `导出Keymap JSON文件（Download this QMK Keymap JSON File）` 按钮，当前键映射方案将保存到你的计算机中，之后可以点击 `导入Keymap JSON文件(Upload a QMK Keymap JSON File)` 按钮导入后继续编辑。
+
+!> **注意：** 导出的.json文件与 kbfirmware.com 和其它工具软件生成的并不兼容，如果你将导出的数据放到那些工具中，或尝试导入那些工具生成的.json文件，是不可行的。
+
+## 第六步：编译固件
+
+点击绿色的 `编译（Compile）` 按钮。
+
+编译完成后，可以点击绿色的 `固件（Download Firmware）` 下载固件文件。
+
+## 下一步：刷写到键盘中
+
+参见[刷写固件](zh-cn/newbs_flashing.md).

docs/zh-cn/configurator_troubleshooting.md

@@ -0,0 +1,31 @@
+# 配置器问题排查
+
+<!---
+  original document: 0.15.12:docs/configurator_troubleshooting.md
+  git diff 0.15.12 HEAD -- docs/configurator_troubleshooting.md | cat
+-->
+
+## 我的 .json 文件不可用
+
+如果该 .json 文件确实是QMK配置器中导出的，恭喜你遇到bug了，请在[QMK配置器](https://github.com/qmk/qmk_configurator/issues)库中提交一个issue。
+
+如果不是……那么页面顶部加大加粗的提示让你不要使用其它 .json 文件，你是怎么错过的？
+
+## 我的配列中有好多空格键，我应该怎么处理？
+
+如果你是说有三个空格键栏，最好的做法是都放上空格键。这个处理方案也适用于退格键和Shift键。
+
+## 用于...的键码是什么？
+
+参见：
+
+* [基础键码资料](zh-cn/keycodes_basic.md)
+* [进阶键码资料](zh-cn/feature_advanced_keycodes.md)
+
+## 无法编译
+
+请检查键映射中所有的层，确保没有随机（random）键。
+
+## Bug及其它问题
+
+我们很乐意倾听你的需求及bug报告，请到[QMK配置器](https://github.com/qmk/qmk_configurator/issues)代码库中提交吧。

docs/zh-cn/contributing.md

@@ -1,123 +1,78 @@
 # 如何做贡献
 
+<!---
+  original document: 0.15.12:docs/contributing.md
+  git diff 0.15.12 HEAD -- docs/contributing.md | cat
+-->
+
 👍🎉 首先感谢各位百忙之中抽空阅读本文档，并为我们无私奉献。给您点赞啦！ 🎉👍
 
-第三方的帮助让Q酱成长了许多呢，Q酱也从你们那学到了不少新东西。Q酱希望每一个想帮助我的人都能很方便的做出有用的贡献。在这里我给摩拳擦掌的你们写了一点引导，让你们的代码在不对我做重大改动的情况下都能成功的被采纳哦。
+第三方的帮助让QMK获得了成长与进步。我们希望提供一套对贡献者和维护者都感到简便实用的PR（pull request）及贡献流程，因此我们整理出了一些准则，以免你的PR在被接纳前需要大改一番。
 
-* [项目概况](#项目概况)
-* [代码规范](#代码规范)
-* [一般教程](#一般教程)
-* [行为守则对于我来说有何意义?](#行为守则对于我来说有何意义?)
+* [项目概况](#project-overview)
+* [代码规范](#coding-conventions)
+* [一般教程](#general-guidelines)
+* [行为守则对于我来说有何意义？](#what-does-the-code-of-conduct-mean-for-me)
 
 ## 这文章巨长无比不想读啊! 我就想问个问题而已!
 
-您要是想问关于Q酱的问题的话可以在[OLKB Subreddit](https://reddit.com/r/olkb)或者是[Discord](https://discord.gg/Uq7gcHh)随意问。
+您要是有关于QMK的问题，请在[OLKB Subreddit](https://reddit.com/r/olkb)或者是[Discord](https://discord.gg/Uq7gcHh)上进行提问。
 
 请记住:
 
-* 维护Q酱的小可爱有的时候可能会有点忙，不能及时回答您的问题，耐心等等，他们都是很nice的人呀。
-* 维护Q酱的人都是很无私的善良的人。无论是贡献代码还是回答问题，都是义务的。有时见到他们努力回答各种问题，解决各种BUG，Q酱也是很心疼的。
+* 你的问题也许要过几个小时才会有人回复，请耐心一些。
+* 参与到QMK中的成员都是在无偿地贡献着自己的时间和精力，我们没有受雇于开发QMK或是专职回答你的疑问。
 * 您可以看看下面的教程，可以让您的问题浅显易懂，更容易回答：
   * https://opensource.com/life/16/10/how-ask-technical-questions
   * http://www.catb.org/esr/faqs/smart-questions.html
 
-# 项目概况
+# 项目概况 :id=project-overview
 
-Q酱很大一部分是用C语言组成的，不过有一小部分特性是C++的。怎么说呢，都是我的一部分，两个我都爱。Q酱一般是在键盘上的嵌入式处理器那里工作的，尤其与AVR([LUFA](https://www.fourwalledcubicle.com/LUFA.php))和ARM ([ChibiOS](https://www.chibios.org))两小哥哥搭配，干活不累，嘻嘻。如果您精通Arduino的话您会发现很多熟悉的概念，但也有点不爽，因为您以前的经验可能没法用来帮助Q酱。
+QMK很大一部分是C语言编写的，小部分特性是C++的。QMK的设计目标是在键盘上的嵌入式处理器中工作，如AVR([LUFA](https://www.fourwalledcubicle.com/LUFA.php))和ARM ([ChibiOS](https://www.chibios.org))。如果您对Arduino很熟悉的话，会发现优缺点也基本是相似的。但无论你之前是否有Arduino使用经验，都不会影响你参与到QMK贡献中来。
 
-<!-- 需要修正: 这里放些学习C语言的资源。另外感谢修正的小可爱。谢谢您了。-->
+<!-- FIXME: 这里应当放些C语言的学习资源。 -->
 
-# Q酱，我在哪能帮助你嘞?
+# 我到哪里寻求帮助？
 
 您要是有问题的话可以 [提出一个issue](https://github.com/qmk/qmk_firmware/issues) 或 [在Discord上交流一下](https://discord.gg/Uq7gcHh).
 
-# Q酱，我如何帮助你?
+# 我怎样才能做出贡献？
 
-您以前是否没为开源贡献过代码，而又想知道帮助Q酱是怎么一回事? 稍安勿躁，咱给您总结一下！
+您以前是否没有参与贡献过开源社区，而又想知道如何对QMK提供帮助？这里有一份快速指引！
+*译注：对于没有基本编程经验的人，请谨慎考虑这套操作流程，可参考，照着做很容易出问题，社区的语言障碍也会阻碍你对这些步骤的细节进行咨询*
 
 0. 先注册一个 [GitHub](https://github.com) 账户。
-1. 做好一个你要贡献的布局，那就要 [找一个你想解决的问题](https://github.com/qmk/qmk_firmware/issues)，或者 [找一个你想添加的特性](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature)。
-2. 把关联着问题的仓库分叉（fork）到你的仓库。这样你在`你的GitHub用户名/qmk_firmware`就有一个仓库备份啦。
-3. 使用 `git clone https://github.com/此处添GitHub用户名/此处添仓库名.git`这个命令把仓库同步到你的电脑中。
-4. 您要是想开发一个新特性的话可以先创建一个issue和Q酱的维护者讨论一下您要做什么。
-5. 使用`git checkout -b 此处写分支名字（别用汉字）`命令来创建一个分支（branch）用于开发。
+1. 完整整理出来你要贡献的键映射，或是 [找一个你想解决的问题](https://github.com/qmk/qmk_firmware/issues)，或者 [找一个你想添加的特性](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature)。
+2. 把关联着问题的仓库fork到你的仓库。这样在`你的GitHub用户名/qmk_firmware` 下就有一个副本啦。
+3. 使用 `git clone https://github.com/你的GitHub用户名/仓库名.git` 命令把仓库同步到你的电脑中。
+4. 您要是想开发一个新特性的话可以先创建一个issue和QMK的维护者讨论一下您要做什么。
+5. 使用 `git checkout -b 此处写分支名字（别用汉字）` 命令来创建一个新分支（branch）用于开发。
 6. 对要解决的问题或要添加的特性进行适当的更改。
 7. 使用 `git add 把改变的文件的目录写这里` 可以添加改变的文件内容到git用于管理工程状态的索引（快照）里。
 8. 使用 `git commit -m "这里写修改的相关信息"` 来描述你做出了什么修改。
 9. 使用 `git push origin 此处写分支名字`来把你的更改同步到GitHub库里（反正不是打篮球那个库里）。
 10. 提交一个[QMK 固件的pull request](https://github.com/qmk/qmk_firmware/pull/new/master)。
-11. 给你的pull request拟一个标题，包括简短的描述和问题或错误代码。比如, 你可以起一个这样的"Added more log outputting to resolve #4352"（最好用英语，毕竟Q酱的中文也不是那么的溜，有可能会看不懂中文）。
-12. 在描述（description）里面写你做了哪些更改，你的代码里还存在什么问题, 或者你想问维护的小可爱们的问题。你的your pull request有点小问题无伤大雅(本来也没有完美的代码嘛), 维护的小可爱们会竭尽全力帮您改进的！
+11. 给你的pull request拟一个标题，包括简短的描述和问题或错误代码。比如, 你可以起一个这样的"Added more log outputting to resolve #4352"（最好用英语，毕竟QMK的维护团队成员都是英语语系，有可能会看不懂中文）。
+12. 在描述（description）里面写你做了哪些更改，你的代码里还存在什么问题, 或者你想对QMK维护着询问的问题。你的pull request有点小问题无伤大雅（没有完美的pull request）, QMK维护团队会尽力帮您改进的！
 13. 维护人员审查代码可能需要一些时间。
 14. 维护人员会通知您要更改什么地方，然后您就按照建议改一改。
-15. 预祝您合并成功！
+15. 你的pull request合并成功了，恭喜！
 
-# 代码规范
+# 代码规范 :id=coding-conventions
 
-其实也没有什么特别严格的规范啦，但是俗话说的好：没有规矩，不成方圆。您可以看一下您的要改动的代码周围的画风，然后保持队形。如果你感觉周围都不知道是什么牛鬼蛇神的话就看看下面的建议：
+我们的编码风格很容易掌握，如果你有C语言或Python编码经验，跟随我们的编码风格不会有什么困难。
 
-* 我们用肆(4)个空格来缩进(软件中也可以设置到Tab键)
-* 我们使用改良的1TBS(允许单行样式)
-  * 左大括号: 在开放性语句块那行的末尾
-  * 右大括号: 和开放性语句块第一个字母对齐
-  * Else If: 将右大括号放在行的开头，下一个左大括号放在同一行的结尾
-  * 可选大括号: 可选大括号是必选的
-    * 应该这样: if (condition) { return false; }
-    * 不应该这样: if (condition) return false;
-* 建议使用C语言风格的注释: `/* */`
-  * 把注释想象成一个描述特征的故事
-  * 充分使用注释来描述你为何这样修改
-  * 有些公认的东西就不要写到注释里面了
-  * 如果你不知道注释是否多余,看下面
-* 一般不要主动换行，主动换行的话每行不要超过76列
-* 要把 `#pragma once` 放到头文件的开始哦，抛弃老土的(`#ifndef THIS_FILE_H`, `#define THIS_FILE_H`, ..., `#endif`)吧
-* 下面两种预处理命令都可以用: `#ifdef DEFINED` 还有 `#if defined(DEFINED)`
-  * 以上那句对处女座不是很友好哈，处女座的朋友们就别纠结了，直接 `#if defined(DEFINED)` 。
-  * 还有就是选好一种风格就一直用，一直用一直爽，不要朝三暮四, 除非你要变化到多重条件的 `#if`。
-  * `#` 和 `if`要挨在一起哦，再让本空格在中间冒充电灯泡本空格会生气的。
-  * 以下是缩进规则:
-    * 首先考虑可读性，强迫症的朋友们总想要保持代码的高一致性，这样可不好。
-    * 保证文件已有风格不变。如果代码本来就是杂糅风格，那就见机行事，让你的修改更有意义些。
-    * 其实你也可以在缩进的时候看看周围其他代码，然后范水模山，预处理命令可以有自己的缩进风格。
+* [编码规范 - C](zh-cn/coding_conventions_c.md)
+* [编码规范 - Python](zh-cn/coding_conventions_python.md)
 
-可以参照下面:
+# 基本准则 :id=general-guidelines
 
-```c
-/* foo 的 Enums*/
-enum foo_state {
-  FOO_BAR,
-  FOO_BAZ,
-};
-
-/* 有返回值的情况 */
-int foo(void) {
-  if (some_condition) {
-    return FOO_BAR;
-  } else {
-    return -1;
-  }
-}
-```
-
-# Clang-format的自动格式化
-[Clang-format](https://clang.llvm.org/docs/ClangFormat.html) 是LLVM的一部分，可以帮你自动格式化代码。我们给你准备好了一个适用于以上规范的配置文件，会帮你调整缩进和换行，你只需要写好括号就好。有了它，你再也不用担心调整代码格式太耗时，没有时间陪伴自己（虚构）的另一半了。
-
-使用[LLVM 完整安装](https://llvm.org/builds/)可以在Windows上安装clang-format, Ubuntu用户要用`sudo apt install clang-format`。
-
-命令行的朋友们, 加上 `-style=file`选项就会自动在QMK的根目录寻找.clang-format配置文件了。
-
-VSCode用户, 标准的 C/C++ 插件就支持clang-format, 或者可以用[独立扩展](https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.ClangFormat)也行。
-
-有些东西(比如LAYOUT宏) 会被clang-format打乱，所以那些文件就别用clang-format了,这里就教您一个小窍门，在`// clang-format off` 和 `//clang-format on`之间装上会被搞乱的代码就好了。
-
-# 一般教程
-
-你可以给Q酱的不同部分添砖加瓦，但也要用不同的方法严谨检查。不论你修改哪里最好还是看看下边。
+在QMK中存在多种类型的修改需求，因此也会有审查严格性上的差异。请在做出任何修改时留意，你的改动隶属于什么类型。
 
 * 将PR（pull request）分成一个个的逻辑单元。 比如，不要一次将两个新特性PR出去。要添加的特性排好队，一个一个来。
-* 提交之前看一眼，`git diff --check`的空格一定要写对了
+* 提交之前使用 `git diff --check` 做以下检查，不要提交多余的空格
 * 确定你的代码能通过编译
-  * 布局: 确定`make keyboard:your_new_keymap` 不返回错误
+  * 键映射: 确定`make keyboard:your_new_keymap` 不返回错误
   * 键盘: 确定 `make keyboard:all` 不返回错误
   * 核心代码: 确定 `make all` 不返回错误
 * 提交的信息尽量明确。第一行写点简短介绍(每行不多于70个英文字母), 第二行空着,第三行和后面就要写些必要的细节了。最好用英文写，比如:
@@ -130,13 +85,15 @@ The kerpleplork was intermittently failing with error code 23. The root cause wa
 Limited experimentation on the devices I have available shows that 7 is high enough to avoid confusing the kerpleplork, but I'd like to get some feedback from people with ARM devices to be sure.
 ```
 
+!> **特别留意：** 若你要对其它QMK使用者提交的代码进行功能修改或尝试修复bug，例如非默认的键映射、用户空间和配列部分，须在PR中标记出代码的原始提交者。很多QMK使用者都会对自己提交的代码在不知晓的情况下产生了改动感到困惑和沮丧，无论他的Git及Github经验丰富与否。
+
 ## 文档
 
-想帮助Q酱当然是先看文档最简单了。找到这个文档哪里错了然后改正它对于你来说超级简单! 我们也对有写文档能力的人求贤若渴，如果你是对的人[点这个](#Q酱，我在哪能帮助你嘞?)!
+对文档进行修正是最简单的参与贡献的一个办法，找到错误放置的文档或是修复不完备的部分很容易！我们也急需能修订文档的贡献者参与进来，所以如果你具备这样的能力但不清楚如何开始，请[看这里](#我怎样才能做出贡献？)！
 
-文档呢，都静静的放在`qmk_firmware/docs` 目录里, 也或者您想为网页做贡献的话也是可以的哦。
+文档位于 `qmk_firmware/docs` 目录下，如果你习惯于在web页面中完成工作目标，可以在 https://docs.qmk.fm/ 各文档页面下方点击“Edit this page”在线进行编辑。
 
-在文档中附代码案例时, 先观察文档其他地方的命名规范。比如, 把enums的名字都改成像`my_layers`或者`my_keycodes`来防止名字不一致的enums被当作特务枪毙:
+在文档中附代码案例时, 先观察文档其他地方的命名规范。比如, 将enum类型的定义命名为 `my_layers` 或 `my_keycodes` 的形式可以保持前后一致性：
 
 ```c
 enum my_layers {
@@ -150,56 +107,69 @@ enum my_keycodes {
 };
 ```
 
-## 布局
+### 预览文档 :id=previewing-the-documentation
 
-大多数QMK新手都从创建一个自己的布局开始。我们尽力保证布局规范宽松 (毕竟布局是个性的体现) 不过建议遵守以下准则，这样可以让别人更好理解你的代码
+在发起pull request前，请通过文档预览来检查你的本地更改。可以在 `qmk_firmware/` 目录下执行以下命令来配置文档开发环境：
 
-* 用 [模板](documentation_templates.md)写个`readme.md`。
-* 所有的布局PR都会被squash, 如果你想知道你的提交是怎么被squash的那你就自己来吧
-* 不要把新特性和布局一起PR。可以分别PR他们
-* 布局文件夹就不要放`Makefile`了，这个操作都过时啦
-* 更新文件头部的copyrights(看`%YOUR_NAME%`那)
+    qmk docs
+
+或者，如果你有安装Python 3，可以尝试：
+
+    python3 -m http.server 8936 --directory docs
+
+然后在本地浏览器打开 `http://localhost:8936/`.
+
+## 键映射
+
+大多数QMK新手都从创建一个自己的键映射
+开始。我们尽力保证键映射规范宽松 (毕竟键映射体现的是个人喜好) 不过我们仍要求须遵守以下准则，以便他人更好地发现并理解你的键映射代码。
+
+* 使用这份 [模板](zh-cn/documentation_templates.md) 写一份 `readme.md`。
+* 所有的键映射PR都会被压缩处理（squashed，参见[Github文档](https://docs.github.com/cn/github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges)），如果你对commit被压缩很介意，请自行处理
+* 不要把新特性和键映射放在一个PR中。先提交新特性，再通过PR提交键映射
+* 键映射文件夹中不要提交 `Makefile` 文件（已不再使用）
+* 更新头文件中的copyrights信息(看 `%YOUR_NAME%` 部分)
 
 ## 键盘
 
-QMK的最终归宿是键盘。有些键盘是社区维护的，有一些是制作这些键盘的人维护的。`readme.md`会告诉你是谁维护了这个键盘，如果你对某个键盘有疑问，可以 [创建一个Issue](https://github.com/qmk/qmk_firmware/issues) 来问一问维护者。
+QMK的最终归宿是键盘。有些键盘是社区维护的，有一些是制作这些键盘的人维护的。`readme.md` 会告诉你是谁维护了这个键盘，如果你对某个键盘有疑问，可以 [创建一个Issue](https://github.com/qmk/qmk_firmware/issues) 来问一问维护者。
 
 我们建议你按下面的来操作:
 
-* 用[模板](documentation_templates.md)写`readme.md`。
-* 提交数量尽量合理，不然我们可就要把你的PR给squash了。
-* 不要把新特性和新键盘一起PR。可以分别PR他们
-* 用父文件夹的名字命名 `.c`/`.h`文件, 比如`/keyboards/<kb1>/<kb2>/<kb2>.[ch]`
+* 基于[模板](zh-cn/documentation_templates.md)编写 `readme.md`。
+* commit数量尽量合理，否则你的PR可能会被我们压缩。
+* 不要把新特性和新键盘定义放在一个PR中。先提交新特性，再通过PR提交新键盘定义
+* 用最近一级的父文件夹的名字命名 `.c`/`.h` 文件, 比如 `/keyboards/<kb1>/<kb2>/<kb2>.[ch]`
 * 键盘文件夹就不要放`Makefile`了，这个操作都过时啦
 * 更新文件头部的copyrights(看`%YOUR_NAME%`那)
 
 ## Quantum/TMK 核心
 
-在您废寝忘食地开发Q酱新特性或者帮Q酱驱虫之前，一定要确保你的工作是有意义的。看看[了解QMK](understanding_qmk.md)你会对Q酱有更深的了解，这个文档将带你领略QMK的程序流程。现在你应该和维护团对谈谈来了解实现你想法的最佳方法了。一下渠道都可以：
+在你投入大量精力到新功能开发中之前，请先确保使用了最佳的实现方案。通过阅读[了解QMK](zh-cn/understanding_qmk.md)可以获得对QMK的基本认知，这个文档将带你领略QMK的程序流程，然后你可以和维护团队探讨一下实现你想法的最佳方法的思路，以下渠道都可以：
 
-* [在Discord交流](https://discord.gg/Uq7gcHh)
+* [在Discord中交流](https://discord.gg/Uq7gcHh)
 * [建立一个Issue](https://github.com/qmk/qmk_firmware/issues/new)
 
-新特性和BUG的修复影响所有键盘。开发组也在翻修QMK。所以，在实施重大返修之前一定要讨论一下。如果你在没有事先与维护团队沟通的情况下提交了一个PR，而且你的选择与维护团队的计划方向不符，那你可能要面临大改了。
+新特性和BUG的修复影响所有键盘，开发组也在翻修QMK。所以，在实施重大改动之前一定要讨论一下。如果你在没有事先与维护团队沟通的情况下提交了一个PR，而且你的选择与维护团队的计划方向不符，那你可能要面临大改了。
 
 修复BUG或者开发新特性之前看看这个：
 
-* **默认不启用** - QMK运行的芯片多数内存有限，所以首要考虑的还应该是布局不要被破坏，于是特性默认是不启用的。你喜欢什么特性的话就打开它，如果你觉得有些特性应该默认开启或者你能帮助缩减代码，那就联系维护组吧。
-* **提交之前在本地编译** - 这个简直就是家喻户晓了，但是也确实需要编译啊！ 我们的Travis系统会发现一切问题，但是自己编译一下可要比在线等快多了。
-* **注意版本和芯片平台** - 有那么几个键盘有支持不同配置甚至是不同芯片的版本。试着写一个能AVR和ARM两个平台运行的特性，或者在不支持的平台自动禁用。
+* **默认不启用** - QMK运行的芯片多数内存有限，首要考虑的应是已有的键映射不要被破坏，因此你的功能应当是“可以**启用**”的，而不是“可以禁用”的。如果你觉得该特性应该默认开启或者你能帮助缩减代码，请先和我们沟通一下。
+* **提交之前在本地编译** - 这个简直就是家喻户晓了，但是也确实需要编译啊！ 在你发起PR前，请确保任何改动都通过了编译验证。
+* **注意版本和芯片平台兼容性** - 有那么几个键盘有支持不同配置甚至是不同芯片的版本。请确保你开发的特性同时支持AVR和ARM两个平台，或者在不支持的平台自动禁用。
 * **解释你的新特性** - 在`docs/`写个文档, 你可以创建新文档或者写到现有文档中。如果你不把它记录下来，其他人就无法从你的努力中获益。
 
 也可以看看以下建议：
 
-* 提交数量尽量合理，不然我们可就要把你的PR给squash了。
-* 不要把新特性、布局和键盘一起PR。可以分别PR他们。
-* 给你的特性写[单元测试](unit_testing.md)。
-* 你编辑的文件风格要一致，如果风格不明确或者是混搭风的，你就要先看看[代码规范](#代码规范)确认情况。
+* commit数量尽量合理，否则你的PR可能会被我们压缩。
+* 不要把新键盘定义或新键映射与关键改动放在一个PR中。先提交关键改动。
+* 给你的特性编写[单元测试](zh-cn/unit_testing.md)。
+* 你编辑的文件风格要一致，如果风格不明确或者是混搭风的，请先阅读上方的[代码规范](#coding-conventions)。
 
 ## 重构
 
-为了保持QMK脉络清晰，Q酱打算深入规划重构一下自己，然后让合作者进行修改。如果你有重构的思路或建议[创建一个issue](https://github.com/qmk/qmk_firmware/issues), Q酱很乐意讨论一下怎么改进一下。
+为了保持QMK脉络清晰，QMK的深度重构工作已在规划中，并会通过合作者进行相应的修改。如果你有重构的思路或建议请[创建一个issue](https://github.com/qmk/qmk_firmware/issues), 我们很乐意讨论一下QMK可以如何改进。
 
-# 行为守则对于我来说有何意义?
+# 行为守则对于我来说有何意义？ :id=what-does-the-code-of-conduct-mean-for-me
 
-我们的[行为守则](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md) 是说明您有责任尊重和礼貌地对待项目中的每个人，无论他们的身份如何。 如果你是我们行为准则所描述的不当行为的受害者，我们将站在你这边，并按照行为准则对施暴者进行适当谴责。
+我们的[行为守则](https://qmk.fm/coc/) 指出您有责任尊重并礼貌地对待项目中的每个人，无论他们的身份如何。如果你是我们行为守则所描述的不当行为的受害者，我们将站在你这边，尽最大努力对施暴者进行谴责。

docs/zh-cn/custom_quantum_functions.md

@@ -1,31 +1,35 @@
-# 如何定制你键盘的功能
+# 如何定制化键盘功能
 
-对于很多人来说客制化键盘可不只是向你的电脑发送你按了那个件这么简单。你肯定想实现比简单按键和宏更复杂的功能。QMK有能让你注入代码的钩子, 覆盖功能, 另外，还可以自定义键盘在不同情况下的行为。
+<!---
+  original document: 0.15.12:docs/custom_quantum_functions.md
+  git diff 0.15.12 HEAD -- docs/custom_quantum_functions.md | cat
+-->
 
-本页不假定任何特殊的QMK知识，但阅读[理解QMK](understanding_qmk.md)将会在更基础的层面帮你理解发生了什么。
+对于很多人来说对客制化键盘的诉求不只是向电脑输入按下的键。你肯定想实现比简单按键和宏更复杂的功能。QMK支持基于注入点的代码注入，功能重写，另外还可以自定义键盘在不同情况下的行为。
 
-## A Word on Core vs 键盘 vs 布局
+本页不要求任何额外的QMK知识基础，但阅读[理解QMK](zh-cn/understanding_qmk.md)将会在更基础的层面帮你理解发生了什么。
 
-我们把qmk组织成一个层次结构：
+## 核心/键盘/键映射的概念 :id=a-word-on-core-vs-keyboards-vs-keymap
+
+QMK基于如下层级组成：
 
 * Core (`_quantum`)
   * Keyboard/Revision (`_kb`)
     * Keymap (`_user`)
 
-下面描述的每一个函数都可以在定义上加一个`_kb()`或 `_user()` 后缀。 建议在键盘/修订层使用`_kb()`后缀，在布局层使用`_user()`后缀。
+该文后续部分所提及的函数在定义时皆可添加 `_kb()` 或 `_user()` 后缀，我们建议在键盘及其子版本中使用 `_kb()` 后缀，而在键映射中使用 `_user()` 后缀。
 
-在键盘/修订层定义函数时，`_kb()`在执行任何代码前先调用`_user()`是必要的，不然布局层函数就不要被调用。
-<!-- 翻译问题：上面那句翻译的不太好-->
+在键盘及其子版本中定义函数时，一个重要的点是在 `_kb()` 函数执行任何逻辑前，应先调用 `_user()` 函数，否则这些键映射中的函数将没有机会被执行。
 # 自定义键码
 
 到目前为止，最常见的任务是更改现有键码的行为或创建新的键码。从代码角度来看这些操作都很相似。
 
 ## 定义一个新键码
 
-创建键码第一步，先枚举出它全部，也就是给键码起个名字并分配唯一数值。QMK没有直接限制最大键码值大小，而是提供了一个`SAFE_RANGE`宏。你可以在枚举时用`SAFE_RANGE`来保证你取得了唯一的键码值。
+创建键码的第一步，是先定义其枚举值，也就是给键码起个名字并分配一个唯一值。QMK没有直接限制最大可用的键码值，而是提供了一个 `SAFE_RANGE` 宏。你可以在定义枚举时用 `SAFE_RANGE` 来保证你取得了唯一的键码值。
 
 
-这有枚举两个键码的例子。把这块加到`keymap.c`的话你就在布局中能用`FOO`和`BAR`了。
+这有定义两个键码的枚举值的例子。添加以下代码块至 `keymap.c` 后你就可以在布局中使用 `FOO` 和 `BAR` 了。
 
 ```c
 enum my_keycodes {
@@ -34,15 +38,15 @@ enum my_keycodes {
 };
 ```
 
-## 为键码的行为编程
+## 编程设计你的键码的行为 :id=programming-the-behavior-of-any-keycode
 
-当你覆盖一个已存在按键的行为时，或将这个行为赋给新键时，你要用`process_record_kb()`和`process_record_user()`函数。这俩函数在键处理中真实键事件被处理前被QMK调用。如果这俩函数返回`true`，QMK将会用正常的方式处理键码。这样可以很方便的扩展键码的功能而不是替换它。如果函数返回`false` QMK会跳过正常键处理，然后发送键子抬起还是按下事件就由你决定了。
+当你覆盖一个已存在按键的行为时，或是给新按键设计功能时，请使用 `process_record_kb()` 和 `process_record_user()` 函数。QMK会在响应并处理按键事件前调用这些函数，如果这些函数返回值为 `true`，QMK将继续用常规的方式处理键码，这样可以很方便的扩展键码的功能而不需要替换代码实现。如果函数返回`false` QMK会跳过常规的键处理逻辑，需要发送的按键按下或抬起事件则需交由你负责完成。
 
-当某个键按下或释放时这俩函数会被调用。
+任意按键在按下或抬起时，每次都会调用这些函数。
 
-### process_record_user()`函数示例实现
+### process_record_user()` 实现示例
 
-这个例子做了两个事。自定义了一个叫做`FOO`的键码的行为，并补充了在按下回车时播放音符。
+这个例子做了两个事。自定义了一个叫做 `FOO` 的键码的行为，并提供了在按下回车时播放音符的功能。
 
 ```c
 bool process_record_user(uint16_t keycode, keyrecord_t *record) {
@@ -51,7 +55,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
       if (record->event.pressed) {
         // 按下时做些什么
       } else {
-        // 释放时做些什么
+        // 抬起时做些什么
       }
       return false; // 跳过此键的所有进一步处理
     case KC_ENTER:
@@ -59,21 +63,21 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
       if (record->event.pressed) {
         PLAY_SONG(tone_qwerty);
       }
-      return true; // 让QMK触发回车按下/释放事件
+      return true; // 让QMK响应回车按下/抬起事件
     default:
-      return true; // 正常处理其他键码
+      return true; // 正常响应其他键码
   }
 }
 ```
 
-### `process_record_*` 函数文档
+### `process_record_*` 实现示例
 
-* 键盘/修订: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
-* 布局: `bool process_record_user(uint16_t keycode, keyrecord_t *record)`
+* 键盘/各子版本：`bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
+* 键映射：`bool process_record_user(uint16_t keycode, keyrecord_t *record)`
 
-`keycode(键码)`参数是在布局上定义的，比如`MO(1)`, `KC_L`, 等等。 你要用 `switch...case` 块来处理这些事件。
+`keycode` 参数为键映射中形如 `MO(1)`，`KC_L` 等定义的键值项。 应使用 `switch...case` 代码块来处理这些事件。
 
-`record`参数含有实际按键的信息：
+`record` 参数含有按键的真实状态信息：
 
 ```c
 keyrecord_t record {
@@ -88,108 +92,31 @@ keyrecord_t record {
 }
 ```
 
-# LED控制
-
-qmk提供了读取HID规范包含的5个LED的方法。:
-
-* `USB_LED_NUM_LOCK`
-* `USB_LED_CAPS_LOCK`
-* `USB_LED_SCROLL_LOCK`
-* `USB_LED_COMPOSE`
-* `USB_LED_KANA`
-
-这五个常量对应于主机LED状态的位置位。
-有两种方法可以获得主机LED状态：
-
-* 通过执行 `led_set_user()`
-* 通过调用 `host_keyboard_leds()`
-
-## `led_set_user()`
-
-当5个LED中任何一个的状态需要改变时，此函数将被调用。此函数通过参数输入LED参数。
-使用`IS_LED_ON(usb_led, led_name)`和`IS_LED_OFF(usb_led, led_name)`这两个宏来检查LED状态。
-
-!> `host_keyboard_leds()`可能会在`led_set_user()`被调用前返回新值。
-
-### `led_set_user()`函数示例实现
-
-```c
-void led_set_user(uint8_t usb_led) {
-    if (IS_LED_ON(usb_led, USB_LED_NUM_LOCK)) {
-        writePinLow(B0);
-    } else {
-        writePinHigh(B0);
-    }
-    if (IS_LED_ON(usb_led, USB_LED_CAPS_LOCK)) {
-        writePinLow(B1);
-    } else {
-        writePinHigh(B1);
-    }
-    if (IS_LED_ON(usb_led, USB_LED_SCROLL_LOCK)) {
-        writePinLow(B2);
-    } else {
-        writePinHigh(B2);
-    }
-    if (IS_LED_ON(usb_led, USB_LED_COMPOSE)) {
-        writePinLow(B3);
-    } else {
-        writePinHigh(B3);
-    }
-    if (IS_LED_ON(usb_led, USB_LED_KANA)) {
-        writePinLow(B4);
-    } else {
-        writePinHigh(B4);
-    }
-}
-```
-
-### `led_set_*`函数文档
-
-* 键盘/修订: `void led_set_kb(uint8_t usb_led)`
-* 布局: `void led_set_user(uint8_t usb_led)`
-
-## `host_keyboard_leds()`
-
-调用这个函数会返回最后收到的LED状态。这个函数在`led_set_*`之外读取LED状态时很有用，比如在[`matrix_scan_user()`](#矩阵扫描代码).
-为了便捷，你可以用`IS_HOST_LED_ON(led_name)`和`IS_HOST_LED_OFF(led_name)` 宏，而不直接调用和检查`host_keyboard_leds()`。
-
-## 设置物理LED状态
-
-一些键盘实现了为设置物理LED的状态提供了方便的方法。
-
-### Ergodox Boards
-
-Ergodox实现了提供`ergodox_right_led_1`/`2`/`3_on`/`off()`来让每个LED开或关, 也可以用 `ergodox_right_led_on`/`off(uint8_t led)` 按索引打开或关闭他们。
-
-此外，还可以使用`ergodox_led_all_set(uint8_t n)`指定所有LED的亮度级别；针对每个LED用`ergodox_right_led_1`/`2`/`3_set(uint8_t n)`；使用索引的话用`ergodox_right_led_set(uint8_t led, uint8_t n)`。
-
-Ergodox boards 同时定义了最低亮度级别`LED_BRIGHTNESS_LO`和最高亮度级别`LED_BRIGHTNESS_HI`(默认最高).
-
 # 键盘初始化代码
 
-键盘初始化过程有几个步骤。你是用那个函数取决于你想要做什么。
+键盘初始化过程须经过几个步骤，而你的目的决定了你需要关注哪些函数。
 
 有三个主要初始化函数，按调用顺序列出。
 
-* `keyboard_pre_init_*` - 会在大多数其他东西运行前运行。适用于哪些需要提前运行的硬件初始化。
-* `matrix_init_*` - 在固件启动过程中间被调用。此时硬件已初始化，功能尚未初始化。
-* `keyboard_post_init_*` - 在固件启动过程最后被调用。大多数情况下，你的“客制化”代码都可以放在这里。
+* `keyboard_pre_init_*` - 会在大多数其他功能运行前执行。适用于那些需要尽早执行的硬件初始化工作。
+* `matrix_init_*` - 在固件启动过程中被调用。此时硬件已初始化，但部分功能还不可用。
+* `keyboard_post_init_*` - 在固件启动过程的最后被调用。大多数情况下，你的“客制化”代码都可以放在这里。
 
-!> 对于大多数人来说`keyboard_post_init_user`是你想要调用的函数。例如, 此时你可以设置RGB灯发光。
+!> 对于大多数人来说 `keyboard_post_init_user` 是你想要关注的函数。例如, 你可以在这里启动RGB背光灯。
 
 ## 键盘预初始化代码
 
-这代码极早运行，甚至都在USB初始化前运行。
+这部分代码执行的非常早，甚至是在USB通信功能启动之前。
 
-在这之后不久矩阵就被初始化了。
+在这之后不久即会完成矩阵的初始化。
 
-对于大多数用户来说,这用不到，因为它主要是用于面向硬件的初始化。
+对于大多数用户来说不应在此处进行修改，因为它主要用于硬件初始化。
 
-但如果你有硬件初始化的话放在这里再好不过了(比如初始化LED引脚一类的).
+但如果你有硬件须初始化的话放在这里再好不过了（比如初始化LED引脚）.
 
-### `keyboard_pre_init_user()`函数示例实现
+### `keyboard_pre_init_user()` 实现示例
 
-本例中在键盘级别，设定 B0, B1, B2, B3, 和 B4 是LED引脚。
+本例中，在键盘层将 B0, B1, B2, B3, 和 B4 引脚设置为LED引脚。
 
 ```c
 void keyboard_pre_init_user(void) {
@@ -206,95 +133,110 @@ void keyboard_pre_init_user(void) {
 
 ### `keyboard_pre_init_*` 函数文档
 
-* 键盘/修订: `void keyboard_pre_init_kb(void)`
-* 布局: `void keyboard_pre_init_user(void)`
+* 键盘/各子版本：`void keyboard_pre_init_kb(void)`
+* 键映射：`void keyboard_pre_init_user(void)`
 
 ## 矩阵初始化代码
 
-这将会在矩阵初始化时被调用，在某些硬件设置好后，但在一些功能被初始化前。 
+在矩阵初始化后被调用。此时一部分硬件已设置完成，但一些功能尚未完成初始化。 
 
-这在你设置其他地方会用到的东西的时候会很有用，但与硬件无关，也不依赖于它的启动位置。
+此处可以用来设置一些与硬件无关，且对初始化位置没有特殊要求的功能。
 
 
-### `matrix_init_*`函数文档
+### `matrix_init_*` 函数文档
 
-* 键盘/修订: `void matrix_init_kb(void)`
-* 布局: `void matrix_init_user(void)`
+* 键盘/各子版本：`void matrix_init_kb(void)`
+* 键映射：`void matrix_init_user(void)`
 
+### 低级矩阵函数的重写 :id=low-level-matrix-overrides
+
+* GPIO引脚初始化：`void matrix_init_pins(void)`
+  * 此处须完成低级行列引脚的初始化。默认实现中，这里会参考可选的键盘设置项 `ROW2COL`，`COL2ROW` 及 `DIRECT_PINS` 来初始化所有 `MATRIX_ROW_PINS` 及 `MATRIX_COL_PINS` 中定义的GPIO引脚的输入/输出状态。当键盘设计者重写该函数后，QMK本身不会进行任何引脚的初始化，只会听从重写的函数的实现逻辑。
+* `COL2ROW`-从行中读: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)`
+* `ROW2COL`-从列中读: `void matrix_read_rows_on_col(matrix_row_t current_matrix[], uint8_t current_col)`
+* `DIRECT_PINS`-直读: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)`
+  * 以上三个函数须参考矩阵类别，从底层矩阵的相关引脚状态中获取输入信息，并且应该只需要实现三者之一。默认情况下，在遍历 `MATRIX_ROW_PINS` and `MATRIX_COL_PINS` 时，会根据是否设置了 `ROW2COL`，`COL2ROW` 或 `DIRECT_PINS` 来配置输入输出方式。当键盘设计者重写该函数后，QMK本身不会进行任何矩阵GPIO引脚状态的变更，只会听从重写的函数的实现逻辑。
 
 ## 键盘后初始化代码
 
-这是键盘初始化过程中的最后一个任务。如果您想更改某些特性，这会很有用，因为此时应该对它们进行初始化。
+这是键盘初始化过程中的最后一个任务。此时您可以配置并调整某些特性，因为此时这些特性已初始化完毕。
 
+### `keyboard_post_init_user()` 实现示例
 
-### `keyboard_post_init_user()`示例实现
-
-本示例在所有初始化完成后运行，配置RGB灯。
+本示例在所有初始化完成后运行，配置RGB背光。
 
 ```c
 void keyboard_post_init_user(void) {
   // 调用后初始化代码
   rgblight_enable_noeeprom(); // 使能Rgb，不保存设置
-  rgblight_sethsv_noeeprom(180, 255, 255); // 将颜色设置到蓝绿色(青色)不保存
-  rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // 设置快速呼吸模式不保存
+  rgblight_sethsv_noeeprom(180, 255, 255); // 将颜色设置到蓝绿色(青色)，不保存设置
+  rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // 设置快速呼吸模式，不保存设置
 }
 ```
 
 ### `keyboard_post_init_*` 函数文档
 
-* 键盘/修订: `void keyboard_post_init_kb(void)`
+* 键盘/各子版本：`void keyboard_post_init_kb(void)`
 * 布局: `void keyboard_post_init_user(void)`
 
-# 矩阵扫描代码
+# 矩阵扫描码
 
-可能的话你要用`process_record_*()`自定义键盘，以这种方式连接到事件中，以确保代码不会对键盘产生负面的性能影响。然而，在极少数情况下，有必要进行矩阵扫描。在这些函数中要特别注意代码的性能，因为它每秒至少被调用10次。
+应尽量使用 `process_record_*()` 实现所需的键盘自定义以及事件监听，以确保这些代码不会对键盘性能产生负面的影响。然而，在极少数情况下需要在矩阵扫描中添加监听，此时需要极端留意这些函数代码的性能表现，因为这些函数每秒可能被执行十数次。
 
-### `matrix_scan_*`示例实现
+### `matrix_scan_*` 实现示例
 
-这个例子被故意省略了。在hook这样一个对性能及其敏感的区域之前，您应该足够了解qmk的内部结构，以便在没有示例的情况下编写。如果你需要帮助，请[建立一个issue](https://github.com/qmk/qmk_firmware/issues/new)或[在Discord上与我们交流](https://discord.gg/Uq7gcHh).
+这个例子被故意省略了。在监听处理这样一个对性能及其敏感的部分之前，您应该足够了解qmk的内部结构，才可以在没有示例的情况下编写。如果你需要帮助，请[新建一个issue](https://github.com/qmk/qmk_firmware/issues/new)或[在Discord上与我们交流](https://discord.gg/Uq7gcHh).
 
 ### `matrix_scan_*` 函数文档
 
-* 键盘/修订: `void matrix_scan_kb(void)`
+* 键盘/各子版本：`void matrix_scan_kb(void)`
 * 布局: `void matrix_scan_user(void)`
 
 该函数在每次矩阵扫描时被调用，这基本与MCU处理能力上限相同。在这里写代码要谨慎，因为它会运行很多次。
 
-你会在自定义矩阵扫描代码时用到这个函数。这也可以用作自定义状态输出(比如LED灯或者屏幕)或者其他即便用户不输入你也想定期运行的功能。
+在需要自定义矩阵扫描代码时可以使用该函数。这也可以用作自定义状态输出(比如LED灯或者屏幕)或者其他即便用户没有输入时你也想定期运行的功能。
 
+# Keyboard housekeeping
+
+* 键盘/各子版本：`void housekeeping_task_kb(void)`
+* 键映射：`void housekeeping_task_user(void)`
+
+该函数在所有QMK处理工作完毕后，下一轮开始执行前被执行。可以放心地假设此时QMK已对最新的矩阵扫描结果完成了所有的处理工作 -- 更新层状态，发送USB事件，更新LED状态，刷新显示屏。
+
+与 `matrix_scan_*` 类似，这些函数会频繁调用直至MCU处理能力上限。为了确保键盘的响应能力，建议在这些函数中尽量做最少的事情，在你确实需要在这里实现特别的功能时，可能会影响到其它功能的表现。
 
 # 键盘 空闲/唤醒 代码
 
-如果键盘支持就可以通过停止一大票功能来达到"空闲"。RGB灯和背光就是很好的例子。这可以节约能耗，也可能让你键盘风味更佳。
+在主控板支持情况下，暂停大部分功能可以实现“空闲”状态，例如RGB灯光和背光。既可以节省电量消耗，也可能增强键盘的表现。
 
-用两个函数控制: `suspend_power_down_*`和`suspend_wakeup_init_*`, 分别在系统板空闲和唤醒时调用。
+这由两个函数控制: `suspend_power_down_*` 和 `suspend_wakeup_init_*`，分别在主控板空闲和唤醒时被调用。
 
 
-### suspend_power_down_user()和suspend_wakeup_init_user()示例实现
+### suspend_power_down_user() 和 suspend_wakeup_init_user() 的实现示例
 
 
 ```c
 void suspend_power_down_user(void) {
-    // code will run multiple times while keyboard is suspended
+    // 当键盘挂起时会被多次调用的代码
 }
 
 void suspend_wakeup_init_user(void) {
-    // code will run on keyboard wakeup
+    // 键盘唤醒时被调用的代码
 }
 ```
 
 ### 键盘 挂起/唤醒 函数文档
 
-* 键盘/修订: `void suspend_power_down_kb(void)` 和`void suspend_wakeup_init_user(void)`
-* 布局: `void suspend_power_down_kb(void)` 和 `void suspend_wakeup_init_user(void)`
+* 键盘/各子版本：`void suspend_power_down_kb(void)` 和 `void suspend_wakeup_init_user(void)`
+* 键映射：`void suspend_power_down_kb(void)` 和 `void suspend_wakeup_init_user(void)`
 
-# 层改变代码
+# 层切换代码 :id=layer-change-code
 
-每当层改变这个就运行代码。这对于层指示或自定义层处理很有用。
+每当层发生切换时被执行，可用于感知层切换事件，或自定义层处理逻辑。
 
-### `layer_state_set_*` 示例实现
+### `layer_state_set_*` 实现示例
 
-本例使用了Planck键盘示范了如何设置 [RGB背光灯](feature_rgblight.md)使之与层对应
+本例中，通过Planck键盘示范了如何将[RGB背光灯](zh-cn/feature_rgblight.md)设置为与层同步。
 
 ```c
 layer_state_t layer_state_set_user(layer_state_t state) {
@@ -311,36 +253,41 @@ layer_state_t layer_state_set_user(layer_state_t state) {
     case _ADJUST:
         rgblight_setrgb (0x7A,  0x00, 0xFF);
         break;
-    default: //  for any other layers, or the default layer
+    default: // 默认层及其它层
         rgblight_setrgb (0x00,  0xFF, 0xFF);
         break;
     }
   return state;
 }
 ```
+
+可以通过 `IS_LAYER_ON_STATE(state, layer)` 和 `IS_LAYER_OFF_STATE(state, layer)` 宏来确认常规层的状态。
+
+如果不在 `layer_state_set_*` 函数中，可以通过 `IS_LAYER_ON(layer)` 和 `IS_LAYER_OFF(layer)` 宏来确认全局的层状态。
+
 ### `layer_state_set_*` 函数文档
 
-* 键盘/修订: `uint32_t layer_state_set_kb(uint32_t state)`
+* 键盘/各子版本：`uint32_t layer_state_set_kb(uint32_t state)`
 * 布局: `layer_state_t layer_state_set_user(layer_state_t state)`
 
 
-该`状态`是活动层的bitmask, 详见[布局概述](keymap.md#布局的层状态)
+此处的 `state` 为当前活跃层的位掩码, 详见[键映射概述](zh-cn/keymap.md#keymap-layer-status)
 
 
-# 掉电保存配置 (EEPROM)
+# 配置的持久存储（EEPROM）
 
-这会让你的配置长期的保存在键盘中。这些配置保存在你主控的EEPROM里，掉电不会消失。 设置可以用`eeconfig_read_kb`和`eeconfig_read_user`读取，可以用`eeconfig_update_kb`和`eeconfig_update_user`写入。这对于您希望能够切换的功能很有用(比如切换RGB层指示。此外，你可以用`eeconfig_init_kb`和`eeconfig_init_user`来设置EEPROM默认值。 
+该功能可以让键盘的配置持久存储下来。这些配置存储在控制器的EEPROM中，即便掉电后依旧可以留存下来。可以通过 `eeconfig_read_kb` 和 `eeconfig_read_user` 来读取，通过 `eeconfig_update_kb` and `eeconfig_update_user` 来进行保存。该功能常用于保存一些开关状态（比如rgb层指示灯）。此外，可以通过 `eeconfig_init_kb` 和 `eeconfig_init_user` 来设置EEPROM的默认配置值。
 
-最复杂的部分可能是，有很多方法可以通过EEPROM存储和访问数据，并且并没有用哪种方法是“政治正确”的。你每个功能只有一个双字(四字节)空间。
+复杂的地方是，有很多方法可以存储和访问EEPROM数据，并且没有哪种方法是“正确”的。但是，每个功能只有一个双字(四字节)空间可用。
 
-记住EEPROM是有写入寿命的。尽管写入寿命很高，但是并不是只有设置写道EEPROM中。如果你写入频繁，你的MCU寿命将会变短。
+记住EEPROM是有写入寿命的。尽管写入寿命很高，但是并不是只有这些配置信息会写到EEPROM中。如果你写入过于频繁，你的MCU寿命将会急速减少。
 
-* 如果您不理解这个例子，那么您可能希望避免使用这个特性，因为它相当复杂。
+* 如果您不理解这个例子，那么您可以不使用这个特性，因为它相当复杂。
 
-### 示例实现
-
-本例讲解了如何添加设置，并且读写。本里使用了用户布局。这是一个复杂的函数，有很多事情要做。实际上，它使用了很多上述函数来工作！
+### 实现示例
 
+本例讲解了如何添加并读写设置项。本例使用用户键映射来实现。这是一个复杂的函数，有很多事情要做。实际上，它使用了很多前述的函数来工作！
+（译注：该示例由于英文行文，可能会觉得看得稀里糊涂。实现的功能很简单，即开启了层指示功能（RGB_LYR）时，rgb背光灯会展示当前层的特定颜色用以指示层状态，而触发任何改变rgb背光颜色的键码时，rgb背光灯将回归普通的背光灯角色，不再作为层指示器）
 
 在你的keymap.c文件中，将以下代码添加至顶部:
 ```c
@@ -354,14 +301,14 @@ typedef union {
 user_config_t user_config;
 ```
 
-以上代码建立了一个结构体，该结构体可以存储设置并可用于写入EEPROM。如此这般将无需定义变量，因为在结构体中已然定义。要记住`bool` (布尔)值使用1位, `uint8_t`使用8位, `uint16_t`使用16位。你可以混合搭配使用，但是顺序记错可能会招致麻烦，因为那会改变写入写出的值。 
+以上代码建立了一个32位的结构体，用于在内存及EEPROM中存储配置项。此时不再需要再单独声明变量，因为都已经在该结构体中定义了。须记住 `bool`（布尔）值占用1位，`uint8_t` 占用8位，`uint16_t` 占用16位。你可以混合搭配使用，但改变这些顺序会因为错误的读写而招致问题。
 
- `layer_state_set_*`函数中使用了`rgb_layer_change`，使用了`keyboard_post_init_user`和`process_record_user`来配置一切。
+我们在 `layer_state_set_*` 函数中会使用 `rgb_layer_change`。通过 `keyboard_post_init_user` 和 `process_record_user` 来配置所需的一切。
 
-首先要使用`keyboard_post_init_user，你要加入`eeconfig_read_user()`来填充你刚刚创建的结构体。然后您可以立即使用这个结构来控制您的布局中的功能。就像这样： 
+在编写 `keyboard_post_init_user` 时，你需要使用 `eeconfig_read_user()` 来计算并填充你刚刚创建的结构体。然后即可以使用结构体数据来控制键映射中的功能。就像这样： 
 ```c
 void keyboard_post_init_user(void) {
-  // 调用布局级别的矩阵初始化
+  // 调用键映射级别的矩阵初始化
 
   // 从EEPROM读用户配置
   user_config.raw = eeconfig_read_user();
@@ -374,7 +321,7 @@ void keyboard_post_init_user(void) {
   }
 }
 ```
-以上函数会在读EEPROM配置后立即使用该设置来设置默认层RGB颜色。"raw"的值是从你上面基于"union"创建的结构体中转换来的。 
+以上函数会在读EEPROM配置后立即设置默认层的RGB颜色。"raw"值将被转换为上述创建的实际使用的"union"结构体。 
 
 ```c
 layer_state_t layer_state_set_user(layer_state_t state) {
@@ -398,7 +345,7 @@ layer_state_t layer_state_set_user(layer_state_t state) {
   return state;
 }
 ```
-这样仅在值使能时会改变RGB背光灯。现在配置这个值, 为`process_record_user`创建一个新键码叫做`RGB_LYR`。我们要确保，如果使用正常的RGB代码，使用上面的示例将其关闭，请将其设置为：
+这样仅在相关值使能时才会改变RGB背光灯。若要配置该值, 为 `process_record_user` 创建一个新键码 `RGB_LYR`。此时我们想实现的是，如果触发了常规的RGB码，以上示例中的逻辑都将不生效，形如：
 ```c
 
 bool process_record_user(uint16_t keycode, keyrecord_t *record) {
@@ -407,7 +354,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
       if (record->event.pressed) {
         // 按下时做点什么
       } else {
-        // 释放时做点什么
+        // 抬起时做点什么
       }
       return false; // 跳过此键的进一步处理
     case KC_ENTER:
@@ -415,76 +362,116 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
         if (record->event.pressed) {
             PLAY_SONG(tone_qwerty);
         }
-        return true; // 让QMK产生回车按下/释放事件
-    case RGB_LYR:  // 本句让underglow作为层指示，或正常使用。
+        return true; // 让QMK产生回车按下/抬起事件
+    case RGB_LYR:  // 这允许我们将背光灯作为层指示，或正常用途
         if (record->event.pressed) { 
             user_config.rgb_layer_change ^= 1; // 切换状态
             eeconfig_update_user(user_config.raw); // 向EEPROM写入新状态
-            if (user_config.rgb_layer_change) { // 如果层状态被使能
+            if (user_config.rgb_layer_change) { // 如果层指示功能被使能
                 layer_state_set(layer_state);   // 那么立刻更新层颜色
             }
         }
         return false;
-    case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // 对于所有的RGB代码 (see quantum_keycodes.h, L400 可以参考)
-        if (record->event.pressed) { //本句失能层指示，假设你改变了这个…你要把它禁用
+    case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // 对于所有的RGB代码 (参考 quantum_keycodes.h, 400 行处)
+        if (record->event.pressed) { // 本句失能层指示功能，假设你现在要调整该功能…你要把它禁用
             if (user_config.rgb_layer_change) {        // 仅当使能时
-                user_config.rgb_layer_change = false;  // 失能，然后 
+                user_config.rgb_layer_change = false;  // 失能，然后
                 eeconfig_update_user(user_config.raw); // 向EEPROM写入设置
             }
         }
         return true; break;
     default:
-      return true; // 按其他键正常
+      return true; // 其他键码正常处理
   }
 }
 ```
-最后你要加入`eeconfig_init_user`函数，所以当EEPROM重置时，可以指定默认值, 甚至自定义操作。想强制重置EEPROM，请用`EEP_RST`键码或[Bootmagic](feature_bootmagic.md)函数。比如，如果要在默认情况下设置RGB层指示，并保存默认值
+最后，须添加 `eeconfig_init_user` 函数，从而当EEPROM重置时，可以指定默认值, 甚至自定义操作。若想强制重置EEPROM，请用 `EEP_RST` 键码或[Bootmagic](zh-cn/feature_bootmagic.md) 功能。比如，在你想重置RGB层指示配置，并保存默认值时。
 
 ```c
-void eeconfig_init_user(void) {  // EEPROM正被重置
+void eeconfig_init_user(void) {  // EEPROM被重置
   user_config.raw = 0;
   user_config.rgb_layer_change = true; // 我们想要默认使能
   eeconfig_update_user(user_config.raw); // 向EEPROM写入默认值
 
-  // use the non noeeprom versions, 还要向EEPROM写入这些值
+  // 通过使用非'noeeprom'版本的函数，可以同时写入这些配置到EEPROM中。
   rgblight_enable(); // 默认使能RGB
   rgblight_sethsv_cyan();  // 默认设置青色
   rgblight_mode(1); // 默认设置长亮
 }
 ```
 
-然后就完事了。RGB层指示会在你想让它工作时工作。这个设置会一直保存，即便你拔下键盘。如果你使用其他RGB代码，层指示将失能，现在它可以做你所想了。 
+一切已就绪，RGB层指示将在需要时生效。这个设置会持久存储，即便是拔下键盘。如果你使用其他RGB码，层指示将失效，从而可以停留在期望的模式及颜色下。
 
 ### 'EECONFIG' 函数文档
 
-* 键盘/修订: `void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)`和`void eeconfig_update_kb(uint32_t val)`
-* 布局: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)`和`void eeconfig_update_user(uint32_t val)`
+* 键盘/各子版本：`void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)` 和 `void eeconfig_update_kb(uint32_t val)`
+* 键映射：`void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` 和 `void eeconfig_update_user(uint32_t val)`
 
 `val` 是你想写入EEPROM的值，`eeconfig_read_*`函数会从EEPROM返回一个32位(双字)的值。
 
-# 自定义击键-长按临界值(TAPPING_TERM)
-默认情况下,击键-长按临界值是全球统一的，并且不能通过键进行配置。对于大多数用户来说这很好。但是在有些情况下，对于`LT`键来说按键延时对双功能键的提升更大，可能是因为有些键比其他的键更容易按住。为了不给每个都自定义键码，本功能可以为每个键定义`TAPPING_TERM`。
+### 定时执行 :id=deferred-execution
 
-想使能这个功能的话, 要先在`config.h`加上`#define TAPPING_TERM_PER_KEY`。
+QMK支持在特定时间间隔后执行回调，以代替手动的计时器管理。
 
+#### 定时回调函数
 
-## `get_tapping_term`示例实现
-
-想要修改基于键码的`TAPPING TERM`,你要向`keymap.c`文件添加如下代码: 
+所有的 _定时回调函数_ 使用同样的函数签名，如下：
 
 ```c
-uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) {
-  switch (keycode) {
-    case SFT_T(KC_SPC):
-      return TAPPING_TERM + 1250;
-    case LT(1, KC_GRV):
-      return 130;
-    default:
-      return TAPPING_TERM;
-  }
+uint32_t my_callback(uint32_t trigger_time, void *cb_arg) {
+    /* 处理了一些工作 */
+    bool repeat = my_deferred_functionality();
+    return repeat ? 500 : 0;
 }
 ```
 
-### `get_tapping_term` 函数文档
+第一个参数 `trigger_time` 为预期的执行时间，如果因为其它事情造成了延迟未能在准确的时间点执行，可以利用这个参数“追赶”或者跳过这次间隔，取决于你的目的是什么。
+
+第二个参数 `cb_arg` 为下述的 `defer_exec()` 传入的参数，由此可以获取调用时的状态信息。
+
+返回值为该函数下一次期望被回调的时间间隔毫秒数 -- 若返回 `0` 则会自动被注销掉。上例中，通过执行假想的 `my_deferred_functionality()` 函数来决策回调是否继续下去 -- 若是，则给出一个 `500` 毫秒的延迟计划，否则，返回 `0` 来告知定时处理后台任务该计划已执行完毕。
+
+?> 须留意返回的延时时间是相对原定的触发时间点的，而不是回调执行完的时间点。这样可以防止偶发的执行延迟影响稳定的定时事件计划。
+
+#### 注册定时回调
+
+在定义好回调后，通过如下API进行定时回调注册：
+
+```c
+deferred_token my_token = defer_exec(1500, my_callback, NULL);
+```
+
+第一个参数为执行 `my_callback` 的毫秒时间延迟 -- 上例中为 `1500` 毫秒，即 1.5 秒。
+
+第三个参数为回调执行时传入的 `cb_arg` 参数。须确保该值在回调时依旧有效 -- 局部函数内的变量会在回调执行前就被释放掉因此不能用。如果并不需要这个参数，可以传入 `NULL`。
+
+返回值 `deferred_token` 可被用于在回调执行前取消该定时计划。如果该函数调用失败，会返回 `INVALID_DEFERRED_TOKEN`，一般错误原因是延时值被设置为 `0` 或回调函数参数为 `NULL`，还有一种可能是已有过量的回调在等待被处理 -- 可以按照下述方法修改这个阈值。
+
+#### 延长定时回调时间
+
+由 `defer_exec()` 返回的 `deferred_token` 可以用来修改回调执行所需等待的时延值：
+```c
+// 重新调整 my_token 后续的执行计划为当前时间起800ms后
+extend_deferred_exec(my_token, 800);
+```
+
+#### 取消定时回调
+
+由 `defer_exec()` 返回的 `deferred_token` 可以用来取消掉后续的执行计划：
+```c
+// 取消 my_token 的后续回调
+cancel_deferred_exec(my_token);
+```
+
+一旦 token 被取消了，即视为不再可用。重新使用该 token 是不支持的。
+
+#### 定时回调的限制
+
+可安排的定时回调计划数量是有限的，由 `MAX_DEFERRED_EXECUTORS` 定义的值确定。
+
+如果定时回调注册失败了，可以在对应的键盘或键映射下的 `config.h` 文件中修改该值，比如将默认的 8 改为 16：
+
+```c
+#define MAX_DEFERRED_EXECUTORS 16
+```
 
-不像这篇的其他功能,这个不需要quantum或者键盘级别的函数，只要用户级函数即可。

docs/zh-cn/driver_installation_zadig.md

@@ -0,0 +1,102 @@
+# 利用Zadig安装Bootloader驱动
+
+<!---
+  original document: 0.15.12:docs/driver_installation_zadig.md
+  git diff 0.15.12 HEAD -- docs/driver_installation_zadig.md | cat
+-->
+
+QMK在主机侧会展现为一台HID键盘设备，因此不需要额外的驱动。但若要在Windows下刷写键盘固件，重置主控板时出现的bootloader设备则通常需要一些驱动程序。
+
+已知的特例有两个：常见于Pro Micro的Caterina bootloader，以及PJRC Teensys上的HalfKay bootloader, 会同时提供一个串行端口设备及一个HID设备，因此不需要额外的驱动。
+
+这里我们推荐使用[Zadig](https://zadig.akeo.ie/)工具软件。若你在MSYS2中配置了开发环境，`qmk_install.sh` 脚本已经替你安装了相关驱动。
+
+## 安装
+
+将键盘重置为bootloader模式，点击 `RESET` 键码（可能在别的层中），或按一下通常在主控板背面上的重置开关，如果你的键盘上没有前两者，尝试在按住Esc键或空格+`B`键时插上键盘（更多信息参见[Bootmagic](zh-cn/feature_bootmagic.md)）。有些键盘使用[指令](zh-cn/feature_command.md)功能来代替Bootmagic，这种情况下，可以在键盘插入状态下点击 左Shift+右Shift+`B` 或 左Shift+右Shift+Esc组合键来进入bootloader模式。
+也有一些键盘需要特别的操作才能进入bootloader状态。例如，[Bootmagic](zh-cn/feature_bootmagic.md)键（默认为：Esc键）在其它键上，比如左Control；或是指令组合键（默认为：左Shift+右Shift）为其它组合，如左Control+右Control。当不确定的时候，可以查阅一下主控板的README文件。
+
+若要将USBaspLoader设备置为bootloader模式，请在按住 `BOOT` 按钮时点击 `RESET` 按钮，或是在按住 `BOOT` 按钮时插入USB线缆。
+
+Zadig可以自动检测到bootloader设备，但有时你需要在 **Options（选项） → List All Devices（列出所有设备）** 的下拉列表中选择正确的设备。
+
+!> 如果Zadig中列出的一个或多个设备为 `HidUsb` 驱动的，那么你的键盘应该没有进入bootloader模式，此时箭头会标记成橙色并会询问你确认是否要修改系统驱动，此时**不要**允许该操作。
+
+如果箭头呈现绿色，选择所需的驱动，点击**Install Driver（安装驱动）**。如何选择正确的驱动进行安装请参见[已知驱动列表](#list-of-known-bootloaders)。
+
+![在Zadig中安装了正确的bootloader驱动](https://i.imgur.com/b8VgXzx.png)
+
+最后，重新拔插一次键盘，确认驱动可以正常加载。如果你在使用QMK工具箱进行刷写，记得也重启一下，因为有时它不会检测到驱动的变化。
+
+## 从错误的驱动安装中恢复
+
+如果你发现键盘无法输入了，应当是因为错误地替换了键盘本身的驱动，而不是bootloader的驱动，你的键盘没有进入bootloader模式就进行安装时就会遇到这个问题。在Zadig中很容易看出这个问题 - 正常的键盘在其所有的接口上都应该有 `HidUsb` 驱动：
+
+![在Zadig中的一个正常的键盘](https://i.imgur.com/Hx0E5kC.png)
+
+打开Device Manager（设备管理器），选择**View（查看） → Devices by container（依类型排序设备）**，并定位到你键盘名所在的节点。
+
+![在设备管理器中安装了错误的驱动的主控板](https://i.imgur.com/o7WLvBl.png)
+
+在这些节点上右键，选择**Uninstall device（卸载）**。如果出现了**Delete the driver software for this device（同时卸载该设备驱动文件）**也请勾选上。
+
+![设备卸载确认对话框，选中了“删除驱动文件”](https://i.imgur.com/aEs2RuA.png)
+
+点击 **Action（操作） → Scan for hardware changes（扫描检测硬件改动）**。此时，键盘应该恢复可用状态了。再确认一下Zadig中键盘是否在使用 `HidUsb` 驱动，如果是，键盘即完全恢复可用状态了，如果不是，重复这一步直到Zadig中报告了正确的驱动。
+
+?> 在这一步有时需要重启电脑，以便Windows可以选用新驱动文件。
+
+## 卸载
+
+卸载bootloadeer设备要比安装过程复杂一些。
+
+打开设备管理器，选择**查看 → 依类型排序设备**，并找到bootloader设备，寻找USB VID和PID与Zadig的[该表格](#list-of-known-bootloaders)中一致的项。
+
+在设备属性的详细信息tab中，找到 `Inf name（INF名称）` 值，通常该值类似于 `oemXX.inf`：
+
+![设备属性中的INF名称值](https://i.imgur.com/Bu4mk9m.png)
+
+之后使用管理员权限打开一个命令行窗口（在开始菜单处输出 `cmd` 并点击Ctrl+Shift+回车）。执行 `pnputil /enum-drivers` 并找到 `INF名称` 与 `Published Name（发布名称）` 一致的项：
+
+![对pnputil输出中匹配驱动项进行高亮展示](https://i.imgur.com/3RrSjzW.png)
+
+执行 `pnputil /delete-driver oemXX.inf /uninstall`，之后该驱动会被删除，相关设备也不再使用该驱动，但设备是不会被移除的。
+
+与上一节相似，本流程也可能需要执行多次，因为一个设备可能会有多个可用的驱动。
+
+!> **警告：** 操作过程中*务必非常小心*！以免不小心卸载掉其它关键驱动。如果你对操作不是很确定，多次检查 `/enum-drivers`的输出信息，也可以考虑执行 `/delete-driver` 时不添加 `/uninstall` 开关\。
+
+## 已知驱动列表 :id=list-of-known-bootloaders
+
+该表列出了已知的bootloader设备及其USB VID（厂商ID）和PID（产品ID），以及可用于QMK刷写固件的驱动。留意usbser及HidUsb驱动是随Windows附带的，无法通过Zadig安装 - 如果你的设备驱动不符，请参照上节来卸载这些驱动。
+
+此处列出的设备名应与Zadig中的一致，但不一定与设备管理器及QMK工具箱展示的一致。
+
+|Bootloader    |设备名                         |VID/PID       |驱动   |
+|--------------|------------------------------|--------------|-------|
+|`atmel-dfu`   |ATmega16u2 DFU                |`03EB:2FEF`   |libusb0|
+|`atmel-dfu`   |ATmega32U2 DFU                |`03EB:2FF0`   |libusb0|
+|`atmel-dfu`   |ATm16U4 DFU V1.0.2            |`03EB:2FF3`   |libusb0|
+|`atmel-dfu`   |ATm32U4DFU                    |`03EB:2FF4`   |libusb0|
+|`atmel-dfu`   |*none* (AT90USB64)            |`03EB:2FF9`   |libusb0|
+|`atmel-dfu`   |AT90USB128 DFU                |`03EB:2FFB`   |libusb0|
+|`qmk-dfu`     |(键盘名) Bootloader            |同`atmel-dfu` |libusb0|
+|`halfkay`     |*none*                        |`16C0:0478`   |HidUsb |
+|`caterina`    |Pro Micro 3.3V                |`1B4F:9203`   |usbser |
+|`caterina`    |Pro Micro 5V                  |`1B4F:9205`   |usbser |
+|`caterina`    |LilyPadUSB                    |`1B4F:9207`   |usbser |
+|`caterina`    |Pololu A-Star 32U4 Bootloader |`1FFB:0101`   |usbser |
+|`caterina`    |Arduino Leonardo              |`2341:0036`   |usbser |
+|`caterina`    |Arduino Micro                 |`2341:0037`   |usbser |
+|`caterina`    |Adafruit Feather 32u4         |`239A:000C`   |usbser |
+|`caterina`    |Adafruit ItsyBitsy 32u4 3V    |`239A:000D`   |usbser |
+|`caterina`    |Adafruit ItsyBitsy 32u4 5V    |`239A:000E`   |usbser |
+|`caterina`    |Arduino Leonardo              |`2A03:0036`   |usbser |
+|`caterina`    |Arduino Micro                 |`2A03:0037`   |usbser |
+|`bootloadhid` |HIDBoot                       |`16C0:05DF`   |HidUsb |
+|`usbasploader`|USBasp                        |`16C0:05DC`   |libusbK|
+|`apm32-dfu`   |APM32 DFU ISP Mode            |`314B:0106`   |WinUSB |
+|`stm32-dfu`   |STM32 BOOTLOADER              |`0483:DF11`   |WinUSB |
+|`kiibohd`     |Kiibohd DFU Bootloader        |`1C11:B007`   |WinUSB |
+|`stm32duino`  |Maple 003                     |`1EAF:0003`   |WinUSB |
+|`qmk-hid`     |(键盘名) Bootloader            |`03EB:2067`   |HidUsb |