refactor doctor.py into a directory

* Update Japanese getting started documents.

* Update faq_build.md

* fix typo

.github/workflows/cli.yml

@@ -23,6 +23,6 @@ jobs:
       with:
         submodules: recursive
     - name: Install dependencies
-      run: pip3 install -r requirements.txt
+      run: pip3 install -r requirements-dev.txt
     - name: Run tests
       run: bin/qmk pytest

.github/workflows/format.yaml

@@ -34,7 +34,7 @@ jobs:
     - name: Run qmk cformat and qmk pyformat
       shell: 'bash {0}'
       run: |
-        qmk cformat -n $(< ~/files.txt)
+        qmk cformat --core-only -n $(< ~/files.txt)
         cformat_exit=$?
         qmk pyformat -n
         pyformat_exit=$?

.gitignore

@@ -5,6 +5,7 @@
 *.eep
 *.elf
 *.hex
+*.uf2
 *.qmk
 !util/bootloader.hex
 !quantum/tools/eeprom_reset.hex

.vscode/settings.json

@@ -22,5 +22,6 @@
     "[markdown]": {
         "editor.trimAutoWhitespace": false,
         "files.trimTrailingWhitespace": false
-    }
+    },
+    "python.formatting.provider": "yapf"
 }

Makefile

@@ -29,6 +29,13 @@ $(info QMK Firmware $(QMK_VERSION))
 endif
 endif
 
+# Determine which qmk cli to use
+ifeq (,$(shell which qmk))
+    QMK_BIN = bin/qmk
+else
+    QMK_BIN = qmk
+endif
+
 # avoid 'Entering|Leaving directory' messages
 MAKEFLAGS += --no-print-directory
 
@@ -86,8 +93,8 @@ clean:
 
 .PHONY: distclean
 distclean: clean
-	echo -n 'Deleting *.bin and *.hex ... '
-	rm -f *.bin *.hex
+	echo -n 'Deleting *.bin, *.hex, and *.uf2 ... '
+	rm -f *.bin *.hex *.uf2
 	echo 'done.'
 
 #Compatibility with the old make variables, anything you specify directly on the command line
@@ -384,7 +391,7 @@ define PARSE_KEYMAP
     # Format it in bold
     KB_SP := $(BOLD)$$(KB_SP)$(NO_COLOR)
     # Specify the variables that we are passing forward to submake
-    MAKE_VARS := KEYBOARD=$$(CURRENT_KB) KEYMAP=$$(CURRENT_KM) REQUIRE_PLATFORM_KEY=$$(REQUIRE_PLATFORM_KEY)
+    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)
     # The message to display
@@ -501,8 +508,8 @@ endef
 %:
 	# Check if we have the CMP tool installed
 	cmp $(ROOT_DIR)/Makefile $(ROOT_DIR)/Makefile >/dev/null 2>&1; if [ $$? -gt 0 ]; then printf "$(MSG_NO_CMP)"; exit 1; fi;
-	# Ensure that bin/qmk works.
-	if ! bin/qmk hello 1> /dev/null 2>&1; then printf "$(MSG_PYTHON_MISSING)"; exit 1; fi
+	# Ensure that $(QMK_BIN) works.
+	if ! $(QMK_BIN) hello 1> /dev/null 2>&1; then printf "$(MSG_PYTHON_MISSING)"; exit 1; fi
 	# Check if the submodules are dirty, and display a warning if they are
 ifndef SKIP_GIT
 	if [ ! -e lib/chibios ]; then git submodule sync lib/chibios && git submodule update --depth 50 --init lib/chibios; fi

Vagrantfile

@@ -6,7 +6,7 @@ Vagrant.configure(2) do |config|
   config.vm.define "qmk_firmware"
 
   # VMware/Virtualbox ( and also Hyperv/Parallels) 64 bit
-  config.vm.box = "generic/debian9"
+  config.vm.box = "generic/debian10"
   
   config.vm.synced_folder '.', '/vagrant'
 

bin/qmk

@@ -29,9 +29,13 @@ def main():
     """
     # Change to the root of our checkout
     os.environ['ORIG_CWD'] = os.getcwd()
+    os.environ['DEPRECATED_BIN_QMK'] = '1'
     os.chdir(qmk_dir)
 
+    print('Warning: The bin/qmk script is being deprecated. Please install the QMK CLI: python3 -m pip install qmk', file=sys.stderr)
+
     # Import the subcommands
+    import milc.subcommand.config  # noqa
     import qmk.cli  # noqa
 
     # Execute

bootloader.mk

@@ -89,11 +89,17 @@ ifeq ($(strip $(BOOTLOADER)), USBasp)
     BOOTLOADER_SIZE = 4096
 endif
 ifeq ($(strip $(BOOTLOADER)), lufa-ms)
-    # DO NOT USE THIS BOOTLOADER IN NEW PROJECTS!
-    # It is extremely prone to bricking, and is only included to support existing boards.
     OPT_DEFS += -DBOOTLOADER_MS
-    BOOTLOADER_SIZE = 6144
+    BOOTLOADER_SIZE ?= 8192
     FIRMWARE_FORMAT = bin
+cpfirmware: lufa_warning
+.INTERMEDIATE: lufa_warning
+lufa_warning: $(FIRMWARE_FORMAT)
+	$(info @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@)
+	$(info LUFA MASS STORAGE Bootloader selected)
+	$(info DO NOT USE THIS BOOTLOADER IN NEW PROJECTS!)
+	$(info It is extremely prone to bricking, and is only included to support existing boards.)
+	$(info @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@)
 endif
 ifdef BOOTLOADER_SIZE
     OPT_DEFS += -DBOOTLOADER_SIZE=$(strip $(BOOTLOADER_SIZE))
@@ -137,3 +143,6 @@ ifeq ($(strip $(BOOTLOADER)), stm32duino)
     DFU_ARGS = -d 1EAF:0003 -a 2 -R
     DFU_SUFFIX_ARGS = -v 1EAF -p 0003
 endif
+ifeq ($(strip $(BOOTLOADER)), tinyuf2)
+    OPT_DEFS += -DBOOTLOADER_TINYUF2
+endif

build_json.mk

@@ -1,22 +1,22 @@
 # Look for a json keymap file
 ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_5)/keymap.json)","")
-    KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
+    KEYMAP_C := $(KEYMAP_OUTPUT)/keymap.c
     KEYMAP_JSON := $(MAIN_KEYMAP_PATH_5)/keymap.json
     KEYMAP_PATH := $(MAIN_KEYMAP_PATH_5)
 else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_4)/keymap.json)","")
-    KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
+    KEYMAP_C := $(KEYMAP_OUTPUT)/keymap.c
     KEYMAP_JSON := $(MAIN_KEYMAP_PATH_4)/keymap.json
     KEYMAP_PATH := $(MAIN_KEYMAP_PATH_4)
 else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_3)/keymap.json)","")
-    KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
+    KEYMAP_C := $(KEYMAP_OUTPUT)/keymap.c
     KEYMAP_JSON := $(MAIN_KEYMAP_PATH_3)/keymap.json
     KEYMAP_PATH := $(MAIN_KEYMAP_PATH_3)
 else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_2)/keymap.json)","")
-    KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
+    KEYMAP_C := $(KEYMAP_OUTPUT)/keymap.c
     KEYMAP_JSON := $(MAIN_KEYMAP_PATH_2)/keymap.json
     KEYMAP_PATH := $(MAIN_KEYMAP_PATH_2)
 else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_1)/keymap.json)","")
-    KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
+    KEYMAP_C := $(KEYMAP_OUTPUT)/keymap.c
     KEYMAP_JSON := $(MAIN_KEYMAP_PATH_1)/keymap.json
     KEYMAP_PATH := $(MAIN_KEYMAP_PATH_1)
 endif
@@ -27,5 +27,5 @@ ifneq ("$(wildcard $(KEYMAP_PATH))", "")
 endif
 
 # Generate the keymap.c
-$(KEYBOARD_OUTPUT)/src/keymap.c: $(KEYMAP_JSON)
-	bin/qmk json2c --quiet --output $(KEYMAP_C) $(KEYMAP_JSON)
+$(KEYMAP_C): $(KEYMAP_JSON)
+	$(QMK_BIN) json2c --quiet --output $(KEYMAP_C) $(KEYMAP_JSON)

build_keyboard.mk

@@ -12,6 +12,9 @@ endif
 
 include common.mk
 
+# Set the qmk cli to use
+QMK_BIN ?= qmk
+
 # Set the filename for the final firmware binary
 KEYBOARD_FILESAFE := $(subst /,_,$(KEYBOARD))
 TARGET ?= $(KEYBOARD_FILESAFE)_$(KEYMAP)
@@ -97,9 +100,18 @@ MAIN_KEYMAP_PATH_4 := $(KEYBOARD_PATH_4)/keymaps/$(KEYMAP)
 MAIN_KEYMAP_PATH_5 := $(KEYBOARD_PATH_5)/keymaps/$(KEYMAP)
 
 # Pull in rules from info.json
-INFO_RULES_MK = $(shell bin/qmk generate-rules-mk --quiet --escape --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/rules.mk)
+INFO_RULES_MK = $(shell $(QMK_BIN) generate-rules-mk --quiet --escape --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/rules.mk)
 include $(INFO_RULES_MK)
 
+ifneq ($(FORCE_LAYOUT),)
+    TARGET := $(TARGET)_$(FORCE_LAYOUT)
+endif
+
+# Object files and generated keymap directory
+#     To put object files in current directory, use a dot (.), do NOT make
+#     this an empty or blank macro!
+KEYMAP_OUTPUT := $(BUILD_DIR)/obj_$(TARGET)
+
 # Check for keymap.json first, so we can regenerate keymap.c
 include build_json.mk
 
@@ -142,10 +154,6 @@ ifeq ($(strip $(CONVERT_TO_PROTON_C)), yes)
     include platforms/chibios/QMK_PROTON_C/convert_to_proton_c.mk
 endif
 
-ifneq ($(FORCE_LAYOUT),)
-    TARGET := $(TARGET)_$(FORCE_LAYOUT)
-endif
-
 include quantum/mcu_selection.mk
 
 # Find all the C source files to be compiled in subfolders.
@@ -295,13 +303,13 @@ endif
 CONFIG_H += $(KEYBOARD_OUTPUT)/src/info_config.h $(KEYBOARD_OUTPUT)/src/layouts.h
 
 $(KEYBOARD_OUTPUT)/src/info_config.h: $(INFO_JSON_FILES)
-	bin/qmk generate-config-h --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/info_config.h
+	$(QMK_BIN) generate-config-h --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/info_config.h
 
 $(KEYBOARD_OUTPUT)/src/default_keyboard.h: $(INFO_JSON_FILES)
-	bin/qmk generate-keyboard-h --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/default_keyboard.h
+	$(QMK_BIN) generate-keyboard-h --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/default_keyboard.h
 
 $(KEYBOARD_OUTPUT)/src/layouts.h: $(INFO_JSON_FILES)
-	bin/qmk generate-layouts --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/layouts.h
+	$(QMK_BIN) generate-layouts --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/layouts.h
 
 generated-files: $(KEYBOARD_OUTPUT)/src/info_config.h $(KEYBOARD_OUTPUT)/src/default_keyboard.h $(KEYBOARD_OUTPUT)/src/layouts.h
 
@@ -324,11 +332,6 @@ endif
 # Disable features that a keyboard doesn't support
 -include disable_features.mk
 
-# Object files directory
-#     To put object files in current directory, use a dot (.), do NOT make
-#     this an empty or blank macro!
-KEYMAP_OUTPUT := $(BUILD_DIR)/obj_$(TARGET)
-
 ifneq ("$(wildcard $(KEYMAP_PATH)/config.h)","")
     CONFIG_H += $(KEYMAP_PATH)/config.h
 endif

build_test.mk

@@ -49,6 +49,7 @@ endif
 
 include common_features.mk
 include $(TMK_PATH)/common.mk
+include $(QUANTUM_PATH)/debounce/tests/rules.mk
 include $(QUANTUM_PATH)/sequencer/tests/rules.mk
 include $(QUANTUM_PATH)/serial_link/tests/rules.mk
 ifneq ($(filter $(FULL_TESTS),$(TEST)),)

common_features.mk

@@ -223,14 +223,17 @@ VALID_LED_MATRIX_TYPES := IS31FL3731 custom
 
 ifeq ($(strip $(LED_MATRIX_ENABLE)), yes)
     ifeq ($(filter $(LED_MATRIX_DRIVER),$(VALID_LED_MATRIX_TYPES)),)
-        $(error LED_MATRIX_DRIVER="$(LED_MATRIX_DRIVER)" is not a valid matrix type)
-    else
-        BACKLIGHT_ENABLE = yes
-        BACKLIGHT_DRIVER = custom
-        OPT_DEFS += -DLED_MATRIX_ENABLE
-        SRC += $(QUANTUM_DIR)/led_matrix.c
-        SRC += $(QUANTUM_DIR)/led_matrix_drivers.c
+        $(error "$(LED_MATRIX_DRIVER)" is not a valid matrix type)
     endif
+    OPT_DEFS += -DLED_MATRIX_ENABLE
+ifneq (,$(filter $(MCU), atmega16u2 atmega32u2 at90usb162))
+    # ATmegaxxU2 does not have hardware MUL instruction - lib8tion must be told to use software multiplication routines
+    OPT_DEFS += -DLIB8_ATTINY
+endif
+    SRC += $(QUANTUM_DIR)/process_keycode/process_backlight.c
+    SRC += $(QUANTUM_DIR)/led_matrix.c
+    SRC += $(QUANTUM_DIR)/led_matrix_drivers.c
+    CIE1931_CURVE := yes
 
     ifeq ($(strip $(LED_MATRIX_DRIVER)), IS31FL3731)
         OPT_DEFS += -DIS31FL3731 -DSTM32_I2C -DHAL_USE_I2C=TRUE
@@ -241,7 +244,7 @@ ifeq ($(strip $(LED_MATRIX_ENABLE)), yes)
 endif
 
 RGB_MATRIX_ENABLE ?= no
-VALID_RGB_MATRIX_TYPES := IS31FL3731 IS31FL3733 IS31FL3737 IS31FL3741 WS2812 custom
+VALID_RGB_MATRIX_TYPES := AW20216 IS31FL3731 IS31FL3733 IS31FL3737 IS31FL3741 WS2812 custom
 
 ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
     ifeq ($(filter $(RGB_MATRIX_DRIVER),$(VALID_RGB_MATRIX_TYPES)),)
@@ -258,6 +261,13 @@ endif
     CIE1931_CURVE := yes
     RGB_KEYCODES_ENABLE := yes
 
+    ifeq ($(strip $(RGB_MATRIX_DRIVER)), AW20216)
+        OPT_DEFS += -DAW20216 -DSTM32_SPI -DHAL_USE_SPI=TRUE
+        COMMON_VPATH += $(DRIVER_PATH)/awinic
+        SRC += aw20216.c
+        QUANTUM_LIB_SRC += spi_master.c
+    endif
+
     ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3731)
         OPT_DEFS += -DIS31FL3731 -DSTM32_I2C -DHAL_USE_I2C=TRUE
         COMMON_VPATH += $(DRIVER_PATH)/issi
@@ -347,7 +357,11 @@ endif
 VALID_BACKLIGHT_TYPES := pwm timer software custom
 
 BACKLIGHT_ENABLE ?= no
-BACKLIGHT_DRIVER ?= pwm
+ifeq ($(strip $(CONVERT_TO_PROTON_C)), yes)
+    BACKLIGHT_DRIVER ?= software
+else
+    BACKLIGHT_DRIVER ?= pwm
+endif
 ifeq ($(strip $(BACKLIGHT_ENABLE)), yes)
     ifeq ($(filter $(BACKLIGHT_DRIVER),$(VALID_BACKLIGHT_TYPES)),)
         $(error BACKLIGHT_DRIVER="$(BACKLIGHT_DRIVER)" is not a valid backlight type)
@@ -422,10 +436,6 @@ ifeq ($(strip $(TERMINAL_ENABLE)), yes)
     OPT_DEFS += -DUSER_PRINT
 endif
 
-ifeq ($(strip $(USB_HID_ENABLE)), yes)
-    include $(TMK_DIR)/protocol/usb_hid.mk
-endif
-
 ifeq ($(strip $(WPM_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/wpm.c
     OPT_DEFS += -DWPM_ENABLE
@@ -459,6 +469,23 @@ ifeq ($(strip $(DIP_SWITCH_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/dip_switch.c
 endif
 
+VALID_MAGIC_TYPES := yes full lite
+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)
+  endif
+  ifneq ($(strip $(BOOTMAGIC_ENABLE)), full)
+      OPT_DEFS += -DBOOTMAGIC_LITE
+      QUANTUM_SRC += $(QUANTUM_DIR)/bootmagic/bootmagic_lite.c
+  else
+    OPT_DEFS += -DBOOTMAGIC_ENABLE
+    QUANTUM_SRC += $(QUANTUM_DIR)/bootmagic/bootmagic_full.c
+  endif
+endif
+COMMON_VPATH += $(QUANTUM_DIR)/bootmagic
+QUANTUM_SRC += $(QUANTUM_DIR)/bootmagic/magic.c
+
 VALID_CUSTOM_MATRIX_TYPES:= yes lite no
 
 CUSTOM_MATRIX ?= no
@@ -509,7 +536,11 @@ ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
 
     # Determine which (if any) transport files are required
     ifneq ($(strip $(SPLIT_TRANSPORT)), custom)
-        QUANTUM_LIB_SRC += $(QUANTUM_DIR)/split_common/transport.c
+        QUANTUM_SRC += $(QUANTUM_DIR)/split_common/transport.c \
+                       $(QUANTUM_DIR)/split_common/transactions.c
+
+        OPT_DEFS += -DSPLIT_COMMON_TRANSACTIONS
+
         # Functions added via QUANTUM_LIB_SRC are only included in the final binary if they're called.
         # Unused functions are pruned away, which is why we can add multiple drivers here without bloat.
         ifeq ($(PLATFORM),AVR)
@@ -530,6 +561,11 @@ ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
     COMMON_VPATH += $(QUANTUM_PATH)/split_common
 endif
 
+ifeq ($(strip $(CRC_ENABLE)), yes)
+    OPT_DEFS += -DCRC_ENABLE
+    QUANTUM_LIB_SRC += crc.c
+endif
+
 HAPTIC_ENABLE ?= no
 ifneq ($(strip $(HAPTIC_ENABLE)),no)
     COMMON_VPATH += $(DRIVER_PATH)/haptic
@@ -560,6 +596,14 @@ ifeq ($(strip $(OLED_DRIVER_ENABLE)), yes)
     SRC += oled_driver.c
 endif
 
+ifeq ($(strip $(ST7565_ENABLE)), yes)
+    OPT_DEFS += -DST7565_ENABLE
+    COMMON_VPATH += $(DRIVER_PATH)/oled # For glcdfont.h
+    COMMON_VPATH += $(DRIVER_PATH)/lcd
+    QUANTUM_LIB_SRC += spi_master.c
+    SRC += st7565.c
+endif
+
 include $(DRIVER_PATH)/qwiic/qwiic.mk
 
 ifeq ($(strip $(UCIS_ENABLE)), yes)
@@ -673,4 +717,4 @@ ifeq ($(strip $(USBPD_ENABLE)), yes)
             # Board designers can add their own driver to $(SRC)
         endif
     endif
-endif
+endif

data/mappings/keyboard_aliases.json

@@ -59,8 +59,11 @@
     'cmm_studio/saka68': {
           target: 'cmm_studio/saka68/solder'
     },
-    'crkbd/rev1': {
-          target: 'crkbd/rev1/legacy'
+    'crkbd/rev1/legacy': {
+          target: 'crkbd/rev1'
+    },
+    'crkbd/rev1/common': {
+          target: 'crkbd/rev1'
     },
     'doro67/multi': {
           layouts: {

data/schemas/api_keyboard.jsonschema

@@ -1,34 +1,22 @@
 {
+    "$id": "qmk.api.keyboard.v1",
     "allOf": [
-        { "$ref": "qmk.keyboard.v1" },
+        {"$ref": "qmk.keyboard.v1"},
         {
-            "$id": "qmk.api.keyboard.v1",
-            "keymaps": {
-                "type": "string"
-            },
-            "parse_errors": {
-                "type": "array",
-                "items": {
-                    "type": "string"
-                }
-            },
-            "parse_warnings": {
-                "type": "array",
-                "items": {
-                    "type": "string"
-                }
-            },
-            "processor_type": {
-                "type": "string"
-            },
-            "protocol": {
-                "type": "string"
-            },
-            "keyboard_folder": {
-                "type": "string"
-            },
-            "platform": {
-                "type": "string"
+            "properties": {
+                "keymaps": {
+                    "type": "object",
+                    "properties": {
+                        "url": {"type": "string"}
+                    }
+
+                },
+                "parse_errors": {"$ref": "qmk.definitions.v1#/string_array"},
+                "parse_warnings": {"$ref": "qmk.definitions.v1#/string_array"},
+                "processor_type": {"type": "string"},
+                "protocol": {"type": "string"},
+                "keyboard_folder": {"type": "string"},
+                "platform": {"type": "string"}
             }
         }
     ]

data/schemas/definitions.jsonschema

@@ -0,0 +1,107 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "qmk.definitions.v1",
+    "title": "Common definitions used across QMK's jsonschemas.",
+    "type": "object",
+    "boolean_array": {
+        "type": "object",
+        "additionalProperties": {"type": "boolean"}
+    },
+    "filename": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^[0-9a-z_]*$"
+    },
+    "hex_number_2d": {
+        "type": "string",
+        "pattern": "^0x[0-9A-F]{2}$"
+    },
+    "hex_number_4d": {
+        "type": "string",
+        "pattern": "^0x[0-9A-F]{4}$"
+    },
+    "text_identifier": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 250
+    },
+    "layout_macro": {
+        "oneOf": [
+            {
+                "type": "string",
+                "enum": ["LAYOUT", "LAYOUT_planck_1x2uC"]
+            },
+            {
+                "type": "string",
+                "pattern": "^LAYOUT_[0-9a-z_]*$"
+            }
+        ]
+    },
+    "key_unit": {
+        "type": "number",
+        "min": 0.25
+    },
+    "mcu_pin_array": {
+        "type": "array",
+        "items": {"$ref": "#/mcu_pin"}
+    },
+    "mcu_pin": {
+        "oneOf": [
+            {
+                "type": "string",
+                "pattern": "^[A-K]\\d{1,2}$"
+            },
+            {
+                "type": "string",
+                "pattern": "^LINE_PIN\\d{1,2}$"
+            },
+            {
+                "type": "number",
+                "multipleOf": 1
+            },
+            {
+                "type": "null"
+            }
+        ]
+    },
+    "signed_decimal": {
+        "type": "number"
+    },
+    "signed_int": {
+        "type": "number",
+        "multipleOf": 1
+    }
+    "signed_int_8": {
+        "type": "number",
+        "min": -127,
+        "max": 127,
+        "multipleOf": 1
+    }
+    "string_array": {
+        "type": "array",
+        "items": {
+            "type": "string"
+        }
+    },
+    "string_object": {
+        "type": "object",
+        "additionalProperties": {
+            "type": "string"
+        }
+    },
+    "unsigned_decimal": {
+        "type": "number",
+        "min": 0
+    },
+    "unsigned_int": {
+        "type": "number",
+        "min": 0,
+        "multipleOf": 1
+    }
+    "unsigned_int_8": {
+        "type": "number",
+        "min": 0,
+        "max": 255,
+        "multipleOf": 1
+    }
+}

docs/ChangeLog/20200829.md

@@ -5,7 +5,7 @@ Four times a year QMK runs a process for merging Breaking Changes. A Breaking Ch
 
 ## Changes Requiring User Action :id=changes-requiring-user-action
 
-### Relocated Keyboards :id-relocated-keyboards
+### Relocated Keyboards :id=relocated-keyboards
 
 #### The Key Company project consolidation ([#9547](https://github.com/qmk/qmk_firmware/pull/9547))
 #### relocating boards by flehrad to flehrad/ folder ([#9635](https://github.com/qmk/qmk_firmware/pull/9635))

docs/ChangeLog/20201128.md

@@ -5,7 +5,7 @@ Four times a year QMK runs a process for merging Breaking Changes. A Breaking Ch
 
 ## Changes Requiring User Action :id=changes-requiring-user-action
 
-### Relocated Keyboards :id-relocated-keyboards
+### Relocated Keyboards :id=relocated-keyboards
 
 #### Reduce Helix keyboard build variation ([#8669](https://github.com/qmk/qmk_firmware/pull/8669))
 

docs/ChangeLog/20210529.md

@@ -0,0 +1,192 @@
+# QMK Breaking Changes - 2021 May 29 Changelog
+
+## Notable Changes :id=notable-changes
+
+### RGB Matrix support for split common ([#11055](https://github.com/qmk/qmk_firmware/pull/11055)) :id=rgb-matrix-split-common
+
+Split boards can now use RGB Matrix without defining a custom matrix.
+
+### Teensy 3.6 support ([#12258](https://github.com/qmk/qmk_firmware/pull/12258)) :id=teensy-3-6-support
+
+Added support for MK66F18 (Teensy 3.6) microcontroller.
+
+### New command: qmk console ([#12828](https://github.com/qmk/qmk_firmware/pull/12828)) :id=new-command-qmk-console
+
+A new `qmk console` command has been added for attaching to your keyboard's console. It operates similiarly to QMK Toolbox by allowing you to connect to one or more keyboard consoles to display debugging messages.
+
+### Improved command: qmk config :id=improve-command-qmk-config
+
+We've updated the `qmk config` command to show only the configuration items you have actually set. You can now display (almost) all of the available configuration options, along with their default values, using `qmk config -a`.
+
+### LED Matrix Improvements ([#12509](https://github.com/qmk/qmk_firmware/pull/12509), [#12580](https://github.com/qmk/qmk_firmware/pull/12580), [#12588](https://github.com/qmk/qmk_firmware/pull/12588), [#12633](https://github.com/qmk/qmk_firmware/pull/12633), [#12651](https://github.com/qmk/qmk_firmware/pull/12651), [#12685](https://github.com/qmk/qmk_firmware/pull/12685)) :id=led-matrix-improvements
+
+LED Matrix has been improved with effects, CIE1931 curves, and a task system.
+
+## Changes Requiring User Action :id=changes-requiring-user-action
+
+### Updated Keyboard Codebases :id=updated-keyboard-codebases
+
+* Durgod keyboard refactor in preparation for adding additional durgod keyboards ([#11978](https://github.com/qmk/qmk_firmware/pull/11978))
+* Updated Function96 with V2 files and removed chconf.h and halconf.h ([#12613](https://github.com/qmk/qmk_firmware/pull/12613))
+* [Keyboard] updated a vendor name / fixed minor keymap issues ([#12881](https://github.com/qmk/qmk_firmware/pull/12881))
+* [Keyboard] Corne - Remove legacy revision support ([#12226](https://github.com/qmk/qmk_firmware/pull/12226))
+
+The following keyboards have had their source moved within QMK:
+
+Old Keyboard Name | New Keyboard Name
+:---------------- | :----------------
+crkbd/rev1/common | crkbd/rev1
+function96 | function96/v1
+nckiibs/flatbread60 | delikeeb/flatbread60
+nckiibs/vaguettelite | delikeeb/vaguettelite
+nckiibs/vanana/rev1 | delikeeb/vanana/rev1
+nckiibs/vanana/rev2 | delikeeb/vanana/rev2
+nckiibs/vaneela | delikeeb/vaneela
+nckiibs/vaneelaex | delikeeb/vaneelaex
+nckiibs/waaffle/rev3/elite_c | delikeeb/waaffle/rev3/elite_c
+nckiibs/waaffle/rev3/pro_micro | delikeeb/waaffle/rev3/pro_micro
+
+The [Function96 V2](https://github.com/qmk/qmk_firmware/tree/0.13.0/keyboards/function96/v2) has also been added as part of these changes.
+
+The codebase for the [Durgod K320](https://github.com/qmk/qmk_firmware/tree/0.13.0/keyboards/durgod/k320) has been reworked in anticipation of additional Durgod keyboards gaining QMK support.
+
+Additionally, the `crkbd/rev1/legacy` keyboard has been removed.
+
+### Bootmagic Deprecation and Refactor ([#12172](https://github.com/qmk/qmk_firmware/pull/12172)) :id=bootmagic-deprecation-and-refactor
+
+QMK has decided to deprecate the full Bootmagic feature and leave Bootmagic Lite as the only remaining option.
+
+This pull request changes the behavior of `BOOTMAGIC_ENABLE` such that specifying `BOOTMAGIC_ENABLE = yes` enables Bootmagic Lite instead of full Bootmagic.
+
+If attempts to use Bootmagic functionality result in unexpected behavior, check your `rules.mk` file and change the `BOOTMAGIC_ENABLE` setting to specify either `lite` or `full`.
+
+#### Tentative Deprecation Schedule
+
+This is the current planned roadmap for the behavior of `BOOTMAGIC_ENABLE`:
+
+- From 2021 May 29, setting `BOOTMAGIC_ENABLE = yes` will enable Bootmagic Lite instead of full Bootmagic.
+- From 2021 Aug 28, `BOOTMAGIC_ENABLE` must be either `yes`, `lite`, or `no` – setting `BOOTMAGIC_ENABLE = full` will cause compilation to fail.
+- From 2021 Nov 27, `BOOTMAGIC_ENABLE` must be either `yes` or `no` – setting `BOOTMAGIC_ENABLE = lite` will cause compilation to fail.
+
+### Removal of LAYOUT_kc ([#12160](https://github.com/qmk/qmk_firmware/pull/12160)) :id=removal-of-layout-kc
+
+We've removed support for `LAYOUT_kc` macros, if your keymap uses one you will need to update it use a regular `LAYOUT` macro.
+
+### Encoder callbacks are now boolean ([#12805](https://github.com/qmk/qmk_firmware/pull/12805), [#12985](https://github.com/qmk/qmk_firmware/pull/12985)) :id=encoder-callback-boolean
+
+To allow for keyboards to override (or not) keymap level code the `encoder_update_kb` function has been changed from `void` to `bool`. You will need to update your function definition to reflect this and ensure that you return a `true` or `false` value.
+
+Example code before change:
+
+```c
+void encoder_update_kb(uint8_t index, bool clockwise) {
+    encoder_update_user(index, clockwise);
+}
+```
+
+Example code after change:
+
+```c
+bool encoder_update_kb(uint8_t index, bool clockwise) {
+    return encoder_update_user(index, clockwise);
+}
+```
+
+## Core Changes :id=core-changes
+
+### Fixes :id=core-fixes
+
+* Fix connection issue in split keyboards when slave and OLED display are connected via I2C (fixes #9335) ([#11487](https://github.com/qmk/qmk_firmware/pull/11487))
+* Terrazzo: Fix wrong LED Matrix function names ([#12561](https://github.com/qmk/qmk_firmware/pull/12561))
+* Apply the "NO_LIMITED_CONTROLLER_CONNECT" fix to atmega16u2 ([#12482](https://github.com/qmk/qmk_firmware/pull/12482))
+* Fix comment parsing ([#12750](https://github.com/qmk/qmk_firmware/pull/12750))
+* Turn OLED off on suspend in soundmonster Corne keymap ([#10419](https://github.com/qmk/qmk_firmware/pull/10419))
+* Fixup build errors on `develop` branch. ([#12723](https://github.com/qmk/qmk_firmware/pull/12723))
+* Fix syntax error when compiling for ARM ([#12866](https://github.com/qmk/qmk_firmware/pull/12866))
+* Add missing LED Matrix suspend code to suspend.c ([#12878](https://github.com/qmk/qmk_firmware/pull/12878))
+* Fix spelling mistake regarding LED Matrix in split_common. ([#12888](https://github.com/qmk/qmk_firmware/pull/12888))
+* [Keymap] Fix QWERTY/DVORAK status output for kzar keymap ([#12895](https://github.com/qmk/qmk_firmware/pull/12895))
+* Fixup housekeeping from being invoked twice per loop. ([#12933](https://github.com/qmk/qmk_firmware/pull/12933))
+* wait for matrix row signal to go HIGH for every row ([#12945](https://github.com/qmk/qmk_firmware/pull/12945))
+* ensure we do not conflict with existing keymap aliases ([#12976](https://github.com/qmk/qmk_firmware/pull/12976))
+* [Keyboard] Fix Terrazzo build failure ([#12977](https://github.com/qmk/qmk_firmware/pull/12977))
+* Do not hard set config in CPTC files ([#11864](https://github.com/qmk/qmk_firmware/pull/11864))
+
+### Additions and Enhancements :id=core-additions
+
+* ARM - Refactor SLEEP_LED to support more platforms ([#8403](https://github.com/qmk/qmk_firmware/pull/8403))
+* Add ability to toggle One Shot functionality ([#4198](https://github.com/qmk/qmk_firmware/pull/4198))
+* Add RGB Matrix support to Split Common ([#11055](https://github.com/qmk/qmk_firmware/pull/11055))
+* Add support for complementary outputs to the ChibiOS WS2812 PWM driver ([#11988](https://github.com/qmk/qmk_firmware/pull/11988))
+* Enable RGB Matrix for Corne ([#12091](https://github.com/qmk/qmk_firmware/pull/12091))
+* Set default OLED Update Interval for Split Keyboards to improve matrix scan performance ([#12107](https://github.com/qmk/qmk_firmware/pull/12107))
+* Add support for MK66F18 (Teensy 3.6) micro controller ([#12258](https://github.com/qmk/qmk_firmware/pull/12258))
+* Split RGB Matrix support for RGBKB Zygomorph ([#11083](https://github.com/qmk/qmk_firmware/pull/11083))
+* Add baudrate and circular buffer to ARM WS2812 SPI config ([#12216](https://github.com/qmk/qmk_firmware/pull/12216))
+* Add keyboard level weak function for slave matrix scan ([#12317](https://github.com/qmk/qmk_firmware/pull/12317))
+* Add link to schematic on EasyEDA for XD60 ([#12018](https://github.com/qmk/qmk_firmware/pull/12018))
+* Add Config functions for LED Matrix ([#12361](https://github.com/qmk/qmk_firmware/pull/12361))
+* Add pin definitions for MK66F18 ([#12419](https://github.com/qmk/qmk_firmware/pull/12419))
+* add kinesis/kint36 keyboard ([#10171](https://github.com/qmk/qmk_firmware/pull/10171))
+* Add support for producing UF2-format binaries. ([#12435](https://github.com/qmk/qmk_firmware/pull/12435))
+* Implement CIE1931 curve for LED Matrix ([#12417](https://github.com/qmk/qmk_firmware/pull/12417))
+* Change `BOOTMAGIC_ENABLE=yes` to use Bootmagic Lite ([#12172](https://github.com/qmk/qmk_firmware/pull/12172))
+* Add kzar keymap for Kinesis Advantage ([#12444](https://github.com/qmk/qmk_firmware/pull/12444))
+* LED Matrix: suspend code ([#12509](https://github.com/qmk/qmk_firmware/pull/12509))
+* LED Matrix: Task system ([#12580](https://github.com/qmk/qmk_firmware/pull/12580))
+* Add missing RGB_MODE_TWINKLE / RGB_M_TW keycodes ([#11935](https://github.com/qmk/qmk_firmware/pull/11935))
+* Enhancement of WPM feature ([#11727](https://github.com/qmk/qmk_firmware/pull/11727))
+* Add Per Key functionality for AutoShift ([#11536](https://github.com/qmk/qmk_firmware/pull/11536))
+* LED Matrix: Reactive effect buffers & advanced indicators ([#12588](https://github.com/qmk/qmk_firmware/pull/12588))
+* LED Matrix: support for Split keyboards ([#12633](https://github.com/qmk/qmk_firmware/pull/12633))
+* add setting to enable infinite timeout for leader key ([#6580](https://github.com/qmk/qmk_firmware/pull/6580), [#12721](https://github.com/qmk/qmk_firmware/pull/12721 "Fix bad PR merge for #6580"))
+* Update ADC driver for STM32F1xx, STM32F3xx, STM32F4xx ([#12403](https://github.com/qmk/qmk_firmware/pull/12403))
+* Add initial support for tinyuf2 bootloader (when hosted on F411 blackpill) ([#12600](https://github.com/qmk/qmk_firmware/pull/12600))
+* Add support for STM32F446 MCU ([#12619](https://github.com/qmk/qmk_firmware/pull/12619))
+* Add STM32L433 and L443 support ([#12063](https://github.com/qmk/qmk_firmware/pull/12063))
+* Added OLED fade out support ([#12086](https://github.com/qmk/qmk_firmware/pull/12086))
+* New command: `qmk console` ([#12828](https://github.com/qmk/qmk_firmware/pull/12828))
+* LED Matrix: Effects! ([#12651](https://github.com/qmk/qmk_firmware/pull/12651))
+* Add setup, clone, and env to the list of commands we allow even with broken modules ([#12868](https://github.com/qmk/qmk_firmware/pull/12868))
+* LED Matrix: Documentation ([#12685](https://github.com/qmk/qmk_firmware/pull/12685))
+* Add function to allow repeated blinking of one layer ([#12237](https://github.com/qmk/qmk_firmware/pull/12237))
+* Add support for up to 4 IS31FL3733 drivers ([#12342](https://github.com/qmk/qmk_firmware/pull/12342))
+* Convert Encoder callbacks to be boolean functions ([#12805](https://github.com/qmk/qmk_firmware/pull/12805), [#12985](https://github.com/qmk/qmk_firmware/pull/12985))
+* [Keymap] Update to Drashna keymap and user code (based on develop) ([#12936](https://github.com/qmk/qmk_firmware/pull/12936))
+* Add Full-duplex serial driver for ARM boards ([#9842](https://github.com/qmk/qmk_firmware/pull/9842))
+* Document LED_MATRIX_FRAMEBUFFER_EFFECTS ([#12987](https://github.com/qmk/qmk_firmware/pull/12987))
+* Backlight: add defines for default level and breathing state ([#12560](https://github.com/qmk/qmk_firmware/pull/12560), [#13024](https://github.com/qmk/qmk_firmware/pull/13024))
+* Add dire message about LUFA mass storage bootloader ([#13014](https://github.com/qmk/qmk_firmware/pull/13014))
+
+### Clean-ups and Optimizations :id=core-optimizations
+
+* Overhaul bootmagic logic to have single entrypoint ([#8532](https://github.com/qmk/qmk_firmware/pull/8532))
+* Refactor of USB code within split_common ([#11890](https://github.com/qmk/qmk_firmware/pull/11890))
+* Begin the process of deprecating `bin/qmk` in favor of the global CLI ([#12109](https://github.com/qmk/qmk_firmware/pull/12109))
+* LED Matrix: decouple from Backlight ([#12054](https://github.com/qmk/qmk_firmware/pull/12054))
+* Remove `FUNC()` ([#12161](https://github.com/qmk/qmk_firmware/pull/12161))
+* Move gpio wait logic to wait.h ([#12067](https://github.com/qmk/qmk_firmware/pull/12067))
+* LED Matrix: Clean up includes ([#12197](https://github.com/qmk/qmk_firmware/pull/12197))
+* Consistently use bin/qmk when that script is called ([#12286](https://github.com/qmk/qmk_firmware/pull/12286))
+* LED Matrix: Additional common_features.mk tweaks ([#12187](https://github.com/qmk/qmk_firmware/pull/12187))
+* LED Matrix: Fix up eeconfig code ([#12327](https://github.com/qmk/qmk_firmware/pull/12327))
+* Big quantum_keycodes cleanup ([#12249](https://github.com/qmk/qmk_firmware/pull/12249))
+* Fix up builds that are now too big for `develop` branch. ([#12495](https://github.com/qmk/qmk_firmware/pull/12495))
+* [Keyboard] kint36: switch to sym_eager_pk debouncing ([#12626](https://github.com/qmk/qmk_firmware/pull/12626))
+* [Keyboard] kint2pp: reduce input latency by ≈10ms ([#12625](https://github.com/qmk/qmk_firmware/pull/12625))
+* eeprom driver: Refactor where eeprom driver initialisation (and EEPROM emulation initialisation) occurs to make it non-target-specific. ([#12671](https://github.com/qmk/qmk_firmware/pull/12671))
+* Change RGB/LED Matrix to use a simple define for USB suspend ([#12697](https://github.com/qmk/qmk_firmware/pull/12697), [#12770](https://github.com/qmk/qmk_firmware/pull/12770 "Fixing transport's led/rgb matrix suspend state logic"))
+* Remove pointless SERIAL_LINK_ENABLE rules ([#12846](https://github.com/qmk/qmk_firmware/pull/12846))
+* Make Swap Hands use PROGMEM ([#12284](https://github.com/qmk/qmk_firmware/pull/12284))
+* Remove KEYMAP and LAYOUT_kc ([#12160](https://github.com/qmk/qmk_firmware/pull/12160))
+* Rename `point_t` -> `led_point_t` ([#12864](https://github.com/qmk/qmk_firmware/pull/12864))
+* Deprecate `send_unicode_hex_string()` ([#12602](https://github.com/qmk/qmk_firmware/pull/12602))
+* [Keyboard] Remove redundant legacy and common headers for crkbd ([#13023](https://github.com/qmk/qmk_firmware/pull/13023))
+
+### QMK Infrastructure and Internals :id=qmk-internals
+
+* trivial change to trigger api update ([`b15288fb87`](https://github.com/qmk/qmk_firmware/commit/b15288fb87))
+* fix some references to bin/qmk that slipped in ([#12832](https://github.com/qmk/qmk_firmware/pull/12832))
+* Resolve a number of warnings in `qmk generate-api` ([#12833](https://github.com/qmk/qmk_firmware/pull/12833))
+* Fix another bin/qmk reference ([#12856](https://github.com/qmk/qmk_firmware/pull/12856))
+* Use milc.subcommand.config instead of qmk.cli.config ([#12915](https://github.com/qmk/qmk_firmware/pull/12915))

docs/_summary.md

@@ -93,6 +93,7 @@
   * Hardware Features
     * Displays
       * [HD44780 LCD Controller](feature_hd44780.md)
+      * [ST7565 LCD Driver](feature_st7565.md)
       * [OLED Driver](feature_oled_driver.md)
     * Lighting
       * [Backlight](feature_backlight.md)
@@ -108,6 +109,7 @@
     * [Haptic Feedback](feature_haptic_feedback.md)
     * [Joystick](feature_joystick.md)
     * [LED Indicators](feature_led_indicators.md)
+    * [MIDI](feature_midi.md)
     * [Proton C Conversion](proton_c_conversion.md)
     * [PS/2 Mouse](feature_ps2_mouse.md)
     * [Split Keyboard](feature_split_keyboard.md)
@@ -120,7 +122,7 @@
   * Breaking Changes
     * [Overview](breaking_changes.md)
     * [My Pull Request Was Flagged](breaking_changes_instructions.md)
-    * [Most Recent ChangeLog](ChangeLog/20210227.md "QMK v0.12.0 - 2021 Feb 27")
+    * [Most Recent ChangeLog](ChangeLog/20210529.md "QMK v0.13.0 - 2021 May 29")
     * [Past Breaking Changes](breaking_changes_history.md)
 
   * C Development

docs/adc_driver.md

@@ -47,73 +47,79 @@ Note that some of these pins are doubled-up on ADCs with the same channel. This
 
 Also note that the F0 and F3 use different numbering schemes. The F0 has a single ADC and the channels are 0-indexed, whereas the F3 has 4 ADCs and the channels are 1-indexed. This is because the F0 uses the `ADCv1` implementation of the ADC, whereas the F3 uses the `ADCv3` implementation.
 
-|ADC|Channel|STM32F0xx|STM32F3xx|
-|---|-------|---------|---------|
-|1  |0      |`A0`     |         |
-|1  |1      |`A1`     |`A0`     |
-|1  |2      |`A2`     |`A1`     |
-|1  |3      |`A3`     |`A2`     |
-|1  |4      |`A4`     |`A3`     |
-|1  |5      |`A5`     |`F4`     |
-|1  |6      |`A6`     |`C0`     |
-|1  |7      |`A7`     |`C1`     |
-|1  |8      |`B0`     |`C2`     |
-|1  |9      |`B1`     |`C3`     |
-|1  |10     |`C0`     |`F2`     |
-|1  |11     |`C1`     |         |
-|1  |12     |`C2`     |         |
-|1  |13     |`C3`     |         |
-|1  |14     |`C4`     |         |
-|1  |15     |`C5`     |         |
-|1  |16     |         |         |
-|2  |1      |         |`A4`     |
-|2  |2      |         |`A5`     |
-|2  |3      |         |`A6`     |
-|2  |4      |         |`A7`     |
-|2  |5      |         |`C4`     |
-|2  |6      |         |`C0`     |
-|2  |7      |         |`C1`     |
-|2  |8      |         |`C2`     |
-|2  |9      |         |`C3`     |
-|2  |10     |         |`F2`     |
-|2  |11     |         |`C5`     |
-|2  |12     |         |`B2`     |
-|2  |13     |         |         |
-|2  |14     |         |         |
-|2  |15     |         |         |
-|2  |16     |         |         |
-|3  |1      |         |`B1`     |
-|3  |2      |         |`E9`     |
-|3  |3      |         |`E13`    |
-|3  |4      |         |         |
-|3  |5      |         |         |
-|3  |6      |         |`E8`     |
-|3  |7      |         |`D10`    |
-|3  |8      |         |`D11`    |
-|3  |9      |         |`D12`    |
-|3  |10     |         |`D13`    |
-|3  |11     |         |`D14`    |
-|3  |12     |         |`B0`     |
-|3  |13     |         |`E7`     |
-|3  |14     |         |`E10`    |
-|3  |15     |         |`E11`    |
-|3  |16     |         |`E12`    |
-|4  |1      |         |`E14`    |
-|4  |2      |         |`B12`    |
-|4  |3      |         |`B13`    |
-|4  |4      |         |`B14`    |
-|4  |5      |         |`B15`    |
-|4  |6      |         |`E8`     |
-|4  |7      |         |`D10`    |
-|4  |8      |         |`D11`    |
-|4  |9      |         |`D12`    |
-|4  |10     |         |`D13`    |
-|4  |11     |         |`D14`    |
-|4  |12     |         |`D8`     |
-|4  |13     |         |`D9`     |
-|4  |14     |         |         |
-|4  |15     |         |         |
-|4  |16     |         |         |
+|ADC|Channel|STM32F0xx|STM32F1xx|STM32F3xx|STM32F4xx|
+|---|-------|---------|---------|---------|---------|
+|1  |0      |`A0`     |`A0`     |         |`A0`     |
+|1  |1      |`A1`     |`A1`     |`A0`     |`A1`     |
+|1  |2      |`A2`     |`A2`     |`A1`     |`A2`     |
+|1  |3      |`A3`     |`A3`     |`A2`     |`A3`     |
+|1  |4      |`A4`     |`A4`     |`A3`     |`A4`     |
+|1  |5      |`A5`     |`A5`     |`F4`     |`A5`     |
+|1  |6      |`A6`     |`A6`     |`C0`     |`A6`     |
+|1  |7      |`A7`     |`A7`     |`C1`     |`A7`     |
+|1  |8      |`B0`     |`B0`     |`C2`     |`B0`     |
+|1  |9      |`B1`     |`B1`     |`C3`     |`B1`     |
+|1  |10     |`C0`     |`C0`     |`F2`     |`C0`     |
+|1  |11     |`C1`     |`C1`     |         |`C1`     |
+|1  |12     |`C2`     |`C2`     |         |`C2`     |
+|1  |13     |`C3`     |`C3`     |         |`C3`     |
+|1  |14     |`C4`     |`C4`     |         |`C4`     |
+|1  |15     |`C5`     |`C5`     |         |`C5`     |
+|1  |16     |         |         |         |         |
+|2  |0      |         |`A0`¹    |         |`A0`²    |
+|2  |1      |         |`A1`¹    |`A4`     |`A1`²    |
+|2  |2      |         |`A2`¹    |`A5`     |`A2`²    |
+|2  |3      |         |`A3`¹    |`A6`     |`A3`²    |
+|2  |4      |         |`A4`¹    |`A7`     |`A4`²    |
+|2  |5      |         |`A5`¹    |`C4`     |`A5`²    |
+|2  |6      |         |`A6`¹    |`C0`     |`A6`²    |
+|2  |7      |         |`A7`¹    |`C1`     |`A7`²    |
+|2  |8      |         |`B0`¹    |`C2`     |`B0`²    |
+|2  |9      |         |`B1`¹    |`C3`     |`B1`²    |
+|2  |10     |         |`C0`¹    |`F2`     |`C0`²    |
+|2  |11     |         |`C1`¹    |`C5`     |`C1`²    |
+|2  |12     |         |`C2`¹    |`B2`     |`C2`²    |
+|2  |13     |         |`C3`¹    |         |`C3`²    |
+|2  |14     |         |`C4`¹    |         |`C4`²    |
+|2  |15     |         |`C5`¹    |         |`C5`²    |
+|2  |16     |         |         |         |         |
+|3  |0      |         |`A0`¹    |         |`A0`²    |
+|3  |1      |         |`A1`¹    |`B1`     |`A1`²    |
+|3  |2      |         |`A2`¹    |`E9`     |`A2`²    |
+|3  |3      |         |`A3`¹    |`E13`    |`A3`²    |
+|3  |4      |         |`F6`¹    |         |`F6`²    |
+|3  |5      |         |`F7`¹    |`B13`    |`F7`²    |
+|3  |6      |         |`F8`¹    |`E8`     |`F8`²    |
+|3  |7      |         |`F9`¹    |`D10`    |`F9`²    |
+|3  |8      |         |`F10`¹   |`D11`    |`F10`²   |
+|3  |9      |         |         |`D12`    |`F3`²    |
+|3  |10     |         |`C0`¹    |`D13`    |`C0`²    |
+|3  |11     |         |`C1`¹    |`D14`    |`C1`²    |
+|3  |12     |         |`C2`¹    |`B0`     |`C2`²    |
+|3  |13     |         |`C3`¹    |`E7`     |`C3`²    |
+|3  |14     |         |         |`E10`    |`F4`²    |
+|3  |15     |         |         |`E11`    |`F5`²    |
+|3  |16     |         |         |`E12`    |         |
+|4  |1      |         |         |`E14`    |         |
+|4  |2      |         |         |`E15`    |         |
+|4  |3      |         |         |`B12`    |         |
+|4  |4      |         |         |`B14`    |         |
+|4  |5      |         |         |`B15`    |         |
+|4  |6      |         |         |`E8`     |         |
+|4  |7      |         |         |`D10`    |         |
+|4  |8      |         |         |`D11`    |         |
+|4  |9      |         |         |`D12`    |         |
+|4  |10     |         |         |`D13`    |         |
+|4  |11     |         |         |`D14`    |         |
+|4  |12     |         |         |`D8`     |         |
+|4  |13     |         |         |`D9`     |         |
+|4  |14     |         |         |         |         |
+|4  |15     |         |         |         |         |
+|4  |16     |         |         |         |         |
+
+<sup>¹ As of ChibiOS 20.3.4, the ADC driver for STM32F1xx devices supports only ADC1, therefore any configurations involving ADC2 or ADC3 cannot actually be used. In particular, pins `F6`…`F10`, which are present at least on some STM32F103x[C-G] devices, cannot be used as ADC inputs because of this driver limitation.</sup>
+
+<sup>² Not all STM32F4xx devices have ADC2 and/or ADC3, therefore some configurations shown in this table may be unavailable; in particular, pins `F4`…`F10` cannot be used as ADC inputs on devices which do not have ADC3. Check the device datasheet to confirm which pin functions are supported.</sup>
 
 ## Functions
 
@@ -141,10 +147,10 @@ Also note that the F0 and F3 use different numbering schemes. The F0 has a singl
 
 The ARM implementation of the ADC has a few additional options that you can override in your own keyboards and keymaps to change how it operates. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.
 
-|`#define`            |Type  |Default              |Description                                                                                                                                                                                                 |
-|---------------------|------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-|`ADC_CIRCULAR_BUFFER`|`bool`|`false`              |If `true`, then the implementation will use a circular buffer.                                                                                                                                              |
-|`ADC_NUM_CHANNELS`   |`int` |`1`                  |Sets the number of channels that will be scanned as part of an ADC operation. The current implementation only supports `1`.                                                                                 |
-|`ADC_BUFFER_DEPTH`   |`int` |`2`                  |Sets the depth of each result. Since we are only getting a 12-bit result by default, we set this to 2 bytes so we can contain our one value. This could be set to 1 if you opt for an 8-bit or lower result.|
-|`ADC_SAMPLING_RATE`  |`int` |`ADC_SMPR_SMP_1P5`   |Sets the sampling rate of the ADC. By default, it is set to the fastest setting.                                                                                                                            |
-|`ADC_RESOLUTION`     |`int` |`ADC_CFGR1_RES_12BIT`|The resolution of your result. We choose 12 bit by default, but you can opt for 12, 10, 8, or 6 bit.                                                                                                        |
+|`#define`            |Type  |Default                                       |Description                                                                                                                                                                                                 |
+|---------------------|------|----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+|`ADC_CIRCULAR_BUFFER`|`bool`|`false`                                       |If `true`, then the implementation will use a circular buffer.                                                                                                                                              |
+|`ADC_NUM_CHANNELS`   |`int` |`1`                                           |Sets the number of channels that will be scanned as part of an ADC operation. The current implementation only supports `1`.                                                                                 |
+|`ADC_BUFFER_DEPTH`   |`int` |`2`                                           |Sets the depth of each result. Since we are only getting a 10-bit result by default, we set this to 2 bytes so we can contain our one value. This could be set to 1 if you opt for an 8-bit or lower result.|
+|`ADC_SAMPLING_RATE`  |`int` |`ADC_SMPR_SMP_1P5`                            |Sets the sampling rate of the ADC. By default, it is set to the fastest setting.                                                                                                                            |
+|`ADC_RESOLUTION`     |`int` |`ADC_CFGR1_RES_10BIT` or `ADC_CFGR_RES_10BITS`|The resolution of your result. We choose 10 bit by default, but you can opt for 12, 10, 8, or 6 bit. Different MCUs use slightly different names for the resolution constants.                              |

docs/breaking_changes.md

@@ -6,6 +6,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?
 
+* [2021 May 29](ChangeLog/20210529.md)
 * [2021 Feb 27](ChangeLog/20210227.md)
 * [2020 Nov 28](ChangeLog/20201128.md)
 * [2020 Aug 29](ChangeLog/20200829.md)
@@ -15,16 +16,16 @@ 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 May 29, 2021.
+The next Breaking Change is scheduled for August 28, 2021.
 
 ### Important Dates
 
-* [x] 2021 Feb 27 - `develop` is created. Each push to `master` is subsequently merged to `develop`
-* [ ] 2021 May 01 - `develop` closed to new PR's.
-* [ ] 2021 May 01 - Call for testers.
-* [ ] 2021 May 27 - `master` is locked, no PR's merged.
-* [ ] 2021 May 29 - Merge `develop` to `master`.
-* [ ] 2021 May 29 - `master` is unlocked. PR's can be merged again.
+* [x] 2021 May 29 - `develop` is created. Each push to `master` is subsequently merged to `develop`
+* [ ] 2021 Jul 31 - `develop` closed to new PR's.
+* [ ] 2021 Jul 31 - Call for testers.
+* [ ] 2021 Aug 26 - `master` is locked, no PR's merged.
+* [ ] 2021 Aug 28 - Merge `develop` to `master`.
+* [ ] 2021 Aug 28 - `master` is unlocked. PR's can be merged again.
 
 ## What changes will be included?
 
@@ -55,7 +56,7 @@ This happens immediately after the previous `develop` branch is merged.
     * [ ] `git commit -m 'Branch point for <DATE> Breaking Change'`
     * [ ] `git tag breakpoint_<YYYY>_<MM>_<DD>`
     * [ ] `git tag <next_version>` # Prevent the breakpoint tag from confusing version incrementing
-    * [ ] `git push origin develop`
+    * [ ] `git push upstream develop`
     * [ ] `git push --tags`
 
 ## 4 Weeks Before Merge
@@ -85,13 +86,21 @@ This happens immediately after the previous `develop` branch is merged.
 * `qmk_firmware` git commands
     * [ ] `git checkout develop`
     * [ ] `git pull --ff-only`
-    * [ ] `git rebase origin/master`
     * [ ] Edit `readme.md`
         * [ ] Remove the notes about `develop`
     * [ ] Roll up the ChangeLog into one file.
     * [ ] `git commit -m 'Merge point for <DATE> Breaking Change'`
-    * [ ] `git push origin develop`
+    * [ ] `git push upstream develop`
 * GitHub Actions
     * [ ] Create a PR for `develop`
     * [ ] Make sure travis comes back clean
-    * [ ] Merge `develop` PR
+    * [ ] **Turn off 'Automatically delete head branches' for the repository** -- confirm with @qmk/directors that it is done before continuing
+* `qmk_firmware` git commands
+    * [ ] `git checkout master`
+    * [ ] `git pull --ff-only`
+    * [ ] `git merge --no-ff develop`
+    * [ ] `git push upstream master`
+
+## Post-merge operations
+
+* (Optional) [update ChibiOS + ChibiOS-Contrib on `develop`](chibios_upgrade_instructions.md)

docs/breaking_changes_history.md

@@ -2,6 +2,7 @@
 
 This page links to all previous changelogs from the QMK Breaking Changes process.
 
+* [2021 May 29](ChangeLog/20210529.md) - version 0.13.0
 * [2021 Feb 27](ChangeLog/20210227.md) - version 0.12.0
 * [2020 Nov 28](ChangeLog/20201128.md) - version 0.11.0
 * [2020 Aug 29](ChangeLog/20200829.md) - version 0.10.0

docs/chibios_upgrade_instructions.md

@@ -0,0 +1,56 @@
+# ChibiOS Upgrade Procedure
+
+ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a branch tied to the ChibiOS version in use and should not be mixed with different versions.
+
+## Getting ChibiOS
+
+* `svn` Initialisation:
+    * Only needed to be done once
+    * You might need to separately install `git-svn` package in your OS's package manager
+    * `git svn init --stdlayout --prefix='svn/' http://svn.osdn.net/svnroot/chibios/`
+    * `git remote add qmk git@github.com:qmk/ChibiOS.git`
+* Updating:
+    * `git svn fetch`
+    * First time around this will take several hours
+    * Subsequent updates will be incremental only
+* Tagging example (work out which version first!):
+    * `git tag -a ver20.3.3 -m ver20.3.3 svn/tags/ver20.3.3`
+    * `git push qmk ver20.3.3`
+    * `git tag -a breaking_YYYY_qN -m breaking_YYYY_qN svn/tags/ver20.3.3`
+    * `git push qmk breaking_YYYY_qN`
+
+## Getting ChibiOS-Contrib
+
+* `git` Initialisation:
+    * `git clone git@github.com:qmk/ChibiOS-Contrib`
+    * `git remote add upstream https://github.com/ChibiOS/ChibiOS-Contrib`
+    * `git checkout -b chibios-20.3.x upstream/chibios-20.3.x`
+* Updating:
+    * `git fetch --all --tags --prune`
+    * `git checkout chibios-20.3.x`
+    * `git pull --ff-only`
+    * `git push origin chibios-20.3.x`
+    * `git tag -a breaking_YYYY_qN -m breaking_YYYY_qN chibios-20.3.x`
+    * `git push origin breaking_YYYY_qN`
+
+## Updating submodules
+
+* Update the submodules
+    * `cd $QMK_FIRMWARE`
+    * `git checkout develop`
+    * `git pull --ff-only`
+    * `git checkout -b chibios-version-bump`
+    * `cd lib/chibios`
+    * `git fetch --all --tags --prune`
+    * `git checkout breaking_YYYY_qN`
+    * `cd ../chibios-contrib`
+    * `git fetch --all --tags --prune`
+    * `git checkout breaking_YYYY_qN`
+* Build everything
+    * `cd $QMK_FIRMWARE`
+    * `qmk multibuild -j4`
+    * Make sure there are no errors
+* Push to the repo
+    * `git commit -am 'Update ChibiOS to XXXXXXXXX'`
+    * `git push --set-upstream origin chibios-version-bump`
+* Make a PR to qmk_firmware with the new branch

docs/cli_commands.md

@@ -107,6 +107,54 @@ This command lets you configure the behavior of QMK. For the full `qmk config` d
 qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
 ```
 
+## `qmk console`
+
+This command lets you connect to keyboard consoles to get debugging messages. It only works if your keyboard firmware has been compiled with `CONSOLE_ENABLED=yes`.
+
+**Usage**:
+
+```
+qmk console [-d <pid>:<vid>[:<index>]] [-l] [-n] [-t] [-w <seconds>]
+```
+
+**Examples**:
+
+Connect to all available keyboards and show their console messages:
+
+```
+qmk console
+```
+
+List all devices:
+
+```
+qmk console -l
+```
+
+Show only messages from clueboard/66/rev3 keyboards:
+
+```
+qmk console -d C1ED:2370
+```
+
+Show only messages from the second clueboard/66/rev3:
+
+```
+qmk console -d C1ED:2370:2
+```
+
+Show timestamps and VID:PID instead of names:
+
+```
+qmk console -n -t
+```
+
+Disable bootloader messages:
+
+```
+qmk console --no-bootloaders
+```
+
 ## `qmk doctor`
 
 This command examines your environment and alerts you to potential build or flash problems. It can fix many of them if you want it to.

docs/compatible_microcontrollers.md

@@ -28,8 +28,11 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s
  * [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html)
  * [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html)
  * [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html)
+ * [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)
+ * [STM32L433](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html)
+ * [STM32L443](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html)
 
 ### NXP (Kinetis)
 

docs/config_options.md

@@ -51,8 +51,10 @@ This is a C header file that is one of the first things included, and will persi
   * the number of columns in your keyboard's matrix
 * `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }`
   * pins of the rows, from top to bottom
+  * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information.
 * `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }`
   * pins of the columns, from left to right
+  * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information.
 * `#define MATRIX_IO_DELAY 30`
   * the delay in microseconds when between changing matrix pin state and reading values
 * `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }`
@@ -78,10 +80,10 @@ This is a C header file that is one of the first things included, and will persi
   * enables audio on pin B5 (duophony is enabled if one of B pins is enabled along with one of C pins)
   * Deprecated. Use `#define AUDIO_PIN B5`, or use `#define AUDIO_PIN_ALT B5` if a `C` pin is enabled with `AUDIO_PIN`
 * `#define B6_AUDIO`
-  * enables audio on pin B5 (duophony is enabled if one of B pins is enabled along with one of C pins)
+  * enables audio on pin B6 (duophony is enabled if one of B pins is enabled along with one of C pins)
   * Deprecated. Use `#define AUDIO_PIN B6`, or use `#define AUDIO_PIN_ALT B6` if a `C` pin is enabled with `AUDIO_PIN`
 * `#define B7_AUDIO`
-  * enables audio on pin B5 (duophony is enabled if one of B pins is enabled along with one of C pins)
+  * enables audio on pin B7 (duophony is enabled if one of B pins is enabled along with one of C pins)
   * Deprecated. Use `#define AUDIO_PIN B7`, or use `#define AUDIO_PIN_ALT B7` if a `C` pin is enabled with `AUDIO_PIN`
 * `#define BACKLIGHT_PIN B7`
   * pin of the backlight
@@ -272,7 +274,7 @@ There are a few different ways to set handedness for split keyboards (listed in
 ### Other Options
 
 * `#define USE_I2C`
-  * For using I2C instead of Serial (defaults to serial)
+  * For using I2C instead of Serial (default is serial; serial transport is supported on ARM -- I2C is AVR-only)
 
 * `#define SOFT_SERIAL_PIN D0`
   * When using serial, define this. `D0` or `D1`,`D2`,`D3`,`E6`.
@@ -280,6 +282,7 @@ There are a few different ways to set handedness for split keyboards (listed in
 * `#define MATRIX_ROW_PINS_RIGHT { <row pins> }`
 * `#define MATRIX_COL_PINS_RIGHT { <col pins> }`
   * If you want to specify a different pinout for the right half than the left half, you can define `MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT`. Currently, the size of `MATRIX_ROW_PINS` must be the same as `MATRIX_ROW_PINS_RIGHT` and likewise for the definition of columns.
+  * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information.
 
 * `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
   * If you want to specify a different direct pinout for the right half than the left half, you can define `DIRECT_PINS_RIGHT`. Currently, the size of `DIRECT_PINS` must be the same as `DIRECT_PINS_RIGHT`.
@@ -300,7 +303,7 @@ There are a few different ways to set handedness for split keyboards (listed in
 * `#define SPLIT_USB_DETECT`
   * Detect (with timeout) USB connection when delegating master/slave
   * Default behavior for ARM
-  * Required for AVR Teensy
+  * Required for AVR Teensy (without hardware mods)
 
 * `#define SPLIT_USB_TIMEOUT 2000`
   * Maximum timeout when detecting master/slave when using `SPLIT_USB_DETECT`
@@ -308,6 +311,28 @@ There are a few different ways to set handedness for split keyboards (listed in
 * `#define SPLIT_USB_TIMEOUT_POLL 10`
   * Poll frequency when detecting master/slave when using `SPLIT_USB_DETECT`
 
+* `#define FORCED_SYNC_THROTTLE_MS 100`
+  * Deadline for synchronizing data from master to slave when using the QMK-provided split transport.
+
+* `#define SPLIT_TRANSPORT_MIRROR`
+  * Mirrors the master-side matrix on the slave when using the QMK-provided split transport.
+
+* `#define SPLIT_LAYER_STATE_ENABLE`
+  * Ensures the current layer state is available on the slave when using the QMK-provided split transport.
+
+* `#define SPLIT_LED_STATE_ENABLE`
+  * Ensures the current host indicator state (caps/num/scroll) is available on the slave when using the QMK-provided split transport.
+
+* `#define SPLIT_MODS_ENABLE`
+  * Ensures the current modifier state (normal, weak, and oneshot) is available on the slave when using the QMK-provided split transport.
+
+* `#define SPLIT_WPM_ENABLE`
+  * Ensures the current WPM is available on the slave when using the QMK-provided split transport.
+
+* `#define SPLIT_TRANSACTION_IDS_KB .....`
+* `#define SPLIT_TRANSACTION_IDS_USER .....`
+  * Allows for custom data sync with the slave when using the QMK-provided split transport. See [custom data sync between sides](feature_split_keyboard.md#custom-data-sync) for more information.
+
 # The `rules.mk` File
 
 This is a [make](https://www.gnu.org/software/make/manual/make.html) file that is included by the top-level `Makefile`. It is used to set some information about the MCU that we will be compiling for as well as enabling and disabling certain features.

docs/custom_quantum_functions.md

@@ -144,6 +144,14 @@ This is useful for setting up stuff that you may need elsewhere, but isn't hardw
 * Keyboard/Revision: `void matrix_init_kb(void)`
 * Keymap: `void matrix_init_user(void)`
 
+### Low-level Matrix Overrides Function Documentation :id=low-level-matrix-overrides
+
+* GPIO pin initialisation: `void matrix_init_pins(void)`
+  * This needs to perform the low-level initialisation of all row and column pins. By default this will initialise the input/output state of each of the GPIO pins listed in `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`, based on whether or not the keyboard is set up for `ROW2COL`, `COL2ROW`, or `DIRECT_PINS`. Should the keyboard designer override this function, no initialisation of pin state will occur within QMK itself, instead deferring to the keyboard's override.
+* `COL2ROW`-based row reads: `void matrix_read_rows_on_col(matrix_row_t current_matrix[], uint8_t current_col)`
+* `ROW2COL`-based column reads: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)`
+* `DIRECT_PINS`-based reads: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)`
+  * These three functions need to perform the low-level retrieval of matrix state of relevant input pins, based on the matrix type. Only one of the functions should be implemented, if needed. By default this will iterate through `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`, configuring the inputs and outputs based on whether or not the keyboard is set up for `ROW2COL`, `COL2ROW`, or `DIRECT_PINS`. Should the keyboard designer override this function, no manipulation of matrix GPIO pin state will occur within QMK itself, instead deferring to the keyboard's override.
 
 ## Keyboard Post Initialization code
 

docs/feature_audio.md

@@ -131,12 +131,14 @@ You can override the default songs by doing something like this in your `config.
 
 ```c
 #ifdef AUDIO_ENABLE
-  #define STARTUP_SONG SONG(STARTUP_SOUND)
+#    define STARTUP_SONG SONG(STARTUP_SOUND)
 #endif
 ```
 
 A full list of sounds can be found in [quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) - feel free to add your own to this list! All available notes can be seen in [quantum/audio/musical_notes.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/musical_notes.h).
 
+Additionally, if you with to maintain your own list of songs (such as ones that may be copyrighted) and not have them added to the repo, you can create a `user_song_list.h` file and place it in your keymap (or userspace) folder.  This file will be automatically included, it just needs to exist.
+
 To play a custom sound at a particular time, you can define a song like this (near the top of the file):
 
 ```c
@@ -301,8 +303,7 @@ You can configure the default, min and max frequencies, the stepping and built i
 
 ## MIDI Functionality
 
-This is still a WIP, but check out `quantum/process_keycode/process_midi.c` to see what's happening. Enable from the Makefile.
-
+See [MIDI](feature_midi.md)
 
 ## Audio Keycodes
 
@@ -319,114 +320,3 @@ This is still a WIP, but check out `quantum/process_keycode/process_midi.c` to s
 |`MU_OFF`        |         |Turns off Music Mode              |
 |`MU_TOG`        |         |Toggles Music Mode                |
 |`MU_MOD`        |         |Cycles through the music modes    |
-
-<!-- FIXME: this formatting needs work
-
-## Audio
-
-```c
-#ifdef AUDIO_ENABLE
-    AU_ON,
-    AU_OFF,
-    AU_TOG,
-
-    // Music mode on/off/toggle
-    MU_ON,
-    MU_OFF,
-    MU_TOG,
-
-    // Music voice iterate
-    MUV_IN,
-    MUV_DE,
-#endif
-```
-
-### Midi
-
-#if !MIDI_ENABLE_STRICT || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))
-    MI_ON,  // send midi notes when music mode is enabled
-    MI_OFF, // don't send midi notes when music mode is enabled
-#endif
-
-MIDI_TONE_MIN,
-MIDI_TONE_MAX
-
-MI_C = MIDI_TONE_MIN,
-MI_Cs,
-MI_Db = MI_Cs,
-MI_D,
-MI_Ds,
-MI_Eb = MI_Ds,
-MI_E,
-MI_F,
-MI_Fs,
-MI_Gb = MI_Fs,
-MI_G,
-MI_Gs,
-MI_Ab = MI_Gs,
-MI_A,
-MI_As,
-MI_Bb = MI_As,
-MI_B,
-
-MIDI_TONE_KEYCODE_OCTAVES > 1
-
-where x = 1-5:
-MI_C_x,
-MI_Cs_x,
-MI_Db_x = MI_Cs_x,
-MI_D_x,
-MI_Ds_x,
-MI_Eb_x = MI_Ds_x,
-MI_E_x,
-MI_F_x,
-MI_Fs_x,
-MI_Gb_x = MI_Fs_x,
-MI_G_x,
-MI_Gs_x,
-MI_Ab_x = MI_Gs_x,
-MI_A_x,
-MI_As_x,
-MI_Bb_x = MI_As_x,
-MI_B_x,
-
-MI_OCT_Nx 1-2
-MI_OCT_x 0-7
-MIDI_OCTAVE_MIN = MI_OCT_N2,
-MIDI_OCTAVE_MAX = MI_OCT_7,
-MI_OCTD, // octave down
-MI_OCTU, // octave up
-
-MI_TRNS_Nx 1-6
-MI_TRNS_x 0-6
-MIDI_TRANSPOSE_MIN = MI_TRNS_N6,
-MIDI_TRANSPOSE_MAX = MI_TRNS_6,
-MI_TRNSD, // transpose down
-MI_TRNSU, // transpose up
-
-MI_VEL_x 1-10
-MIDI_VELOCITY_MIN = MI_VEL_1,
-MIDI_VELOCITY_MAX = MI_VEL_9,
-MI_VELD, // velocity down
-MI_VELU, // velocity up
-
-MI_CHx 1-16
-MIDI_CHANNEL_MIN = MI_CH1
-MIDI_CHANNEL_MAX = MI_CH16,
-MI_CHD, // previous channel
-MI_CHU, // next channel
-
-MI_ALLOFF, // all notes off
-
-MI_SUS, // sustain
-MI_PORT, // portamento
-MI_SOST, // sostenuto
-MI_SOFT, // soft pedal
-MI_LEG,  // legato
-
-MI_MOD, // modulation
-MI_MODSD, // decrease modulation speed
-MI_MODSU, // increase modulation speed
-#endif // MIDI_ADVANCED
-
--->

docs/feature_auto_shift.md

@@ -109,6 +109,33 @@ Do not Auto Shift numeric keys, zero through nine.
 
 Do not Auto Shift alpha characters, which include A through Z.
 
+### Auto Shift Per Key 
+
+This is a function that allows you to determine which keys shold be autoshifted, much like the tap-hold keys. 
+
+The default function looks like this: 
+
+```c
+bool get_auto_shifted_key(uint16_t keycode, keyrecord_t *record) {
+    switch (keycode) {
+#    ifndef NO_AUTO_SHIFT_ALPHA
+        case KC_A ... KC_Z:
+#    endif
+#    ifndef NO_AUTO_SHIFT_NUMERIC
+        case KC_1 ... KC_0:
+#    endif
+#    ifndef NO_AUTO_SHIFT_SPECIAL
+        case KC_TAB:
+        case KC_MINUS ... KC_SLASH:
+        case KC_NONUS_BSLASH:
+#    endif
+            return true;
+    }
+    return false;
+}
+```
+This functionality is enabled by default, and does not need a define.
+
 ### AUTO_SHIFT_REPEAT (simple define)
 
 Enables keyrepeat.