Merge branch 'keyboards/trenctyl_manuform' into enc_master

Co-authored-by: swiftrax <swiftrax@github.com>
Co-authored-by: Drashna Jaelre <drashna@live.com>

.github/dependabot.yml

@@ -0,0 +1,9 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    labels: CI
+    reviewers:
+      - "qmk/collaborators"
+    schedule:
+      interval: "daily"

.github/stale.yml

@@ -1,58 +0,0 @@
-# Configuration for probot-stale - https://github.com/probot/stale
-
-# General configuration
-
-# Pull request specific configuration
-pulls:
-  staleLabel: awaiting changes
-  # Number of days of inactivity before an Issue or Pull Request becomes stale
-  daysUntilStale: 45
-  # Number of days of inactivity before a stale Issue or Pull Request is closed.
-  # Set to false to disable. If disabled, issues still need to be closed manually, but will remain marked as stale.
-  daysUntilClose: 30
-  # Comment to post when marking as stale. Set to `false` to disable
-  markComment: >
-    Thank you for your contribution!
-
-    This pull request has been automatically marked as stale because it has not had
-    activity in the last 45 days. It will be closed in 30 days if no further activity occurs.
-    Please feel free to give a status update now, or re-open when it's ready.
-    
-    For maintainers: Please label with `awaiting review`, `breaking_change`, `in progress`, or `on hold` to prevent 
-    the issue from being re-flagged.
-  # Comment to post when closing a stale Issue or Pull Request.
-  closeComment: >
-    Thank you for your contribution!
-
-    This pull request has been automatically closed because it has not had activity in the last 30 days.
-    Please feel free to give a status update now, ping for review, or re-open when it's ready.
-  # Limit the number of actions per hour, from 1-30. Default is 30
-  limitPerRun: 30
-  exemptLabels:
-    - awaiting review
-    - breaking_change
-    - in progress
-    - on hold
-
-# Issue specific configuration
-issues:
-  staleLabel: stale
-  limitPerRun: 10
-  daysUntilStale: 90
-  daysUntilClose: 30
-  markComment: >
-    This issue has been automatically marked as stale because it has not had activity in the
-    last 90 days. It will be closed in the next 30 days unless it is tagged properly or other activity
-    occurs.
-    
-    For maintainers: Please label with `bug`, `in progress`, `on hold`, `discussion` or `to do` to prevent 
-    the issue from being re-flagged.
-  closeComment: >
-    This issue has been automatically closed because it has not had activity in the last 30 days.
-    If this issue is still valid, re-open the issue and let us know.
-  exemptLabels:
-    - bug
-    - in progress
-    - on hold
-    - discussion
-    - to do

.github/workflows/api.yml

@@ -18,7 +18,7 @@ jobs:
     if: github.repository == 'qmk/qmk_firmware'
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
       with:
         fetch-depth: 1
         persist-credentials: false

.github/workflows/auto_approve.yml

@@ -0,0 +1,18 @@
+name: Automatic Approve
+
+on:
+  schedule:
+    - cron: "*/5 * * * *"
+
+jobs:
+  automatic_approve:
+    runs-on: ubuntu-latest
+
+    if: github.repository == 'qmk/qmk_firmware'
+
+    steps:
+    - uses: mheap/automatic-approve-action@v1
+      with:
+        token: ${{ secrets.QMK_BOT_TOKEN }}
+        workflows: "format.yml,lint.yml,unit_test.yml"
+        dangerous_files: "lib/python/,Makefile,paths.mk,builddefs/"

.github/workflows/auto_tag.yaml

@@ -1,33 +0,0 @@
-name: Essential files modified
-
-on:
-  push:
-    branches:
-    - master
-    paths:
-    - quantum/**/*
-    - tmk_core/**/*
-    - drivers/**/*
-    - tests/**/*
-    - util/**/*
-    - platforms/**/*
-    - Makefile
-    - '*.mk'
-
-jobs:
-  tag:
-    runs-on: ubuntu-latest
-
-    # protect against those who develop with their fork on master
-    if: github.repository == 'qmk/qmk_firmware'
-
-    steps:
-    - uses: actions/checkout@v2
-      with:
-        fetch-depth: 0
-
-    - name: Bump version and push tag
-      uses: anothrNick/github-tag-action@1.26.0
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        DEFAULT_BUMP: 'patch'

.github/workflows/auto_tag.yml

@@ -0,0 +1,33 @@
+name: Essential files modified
+
+on:
+  push:
+    branches:
+    - master
+    paths:
+    - quantum/**/*
+    - tmk_core/**/*
+    - drivers/**/*
+    - tests/**/*
+    - util/**/*
+    - platforms/**/*
+    - Makefile
+    - '*.mk'
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+
+    # protect against those who develop with their fork on master
+    if: github.repository == 'qmk/qmk_firmware'
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+
+    - name: Bump version and push tag
+      uses: anothrNick/github-tag-action@1.39.0
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        DEFAULT_BUMP: 'patch'

.github/workflows/cli.yml

@@ -18,7 +18,7 @@ jobs:
     container: qmkfm/qmk_cli
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
       with:
         submodules: recursive
     - name: Install dependencies

.github/workflows/develop_api.yml

@@ -18,13 +18,15 @@ jobs:
     if: github.repository == 'qmk/qmk_firmware'
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
       with:
         fetch-depth: 1
         persist-credentials: false
 
     - name: Generate API Data
-      run: qmk generate-api
+      run: |
+        python3 -m pip install -r requirements-dev.txt
+        qmk generate-api
 
     - name: Upload API Data
       uses: jakejarvis/s3-sync-action@master

.github/workflows/develop_update.yml

@@ -12,11 +12,15 @@ jobs:
     if: github.repository == 'qmk/qmk_firmware'
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
       with:
         token: ${{ secrets.QMK_BOT_TOKEN }}
         fetch-depth: 0
 
+    - name: Disable automatic eol conversion
+      run: |
+        echo "* -text" > .git/info/attributes
+
     - name: Checkout develop
       run: |
         git fetch origin master develop

.github/workflows/docs.yml

@@ -20,7 +20,7 @@ jobs:
     if: github.repository == 'qmk/qmk_firmware'
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
       with:
         fetch-depth: 1
 
@@ -34,7 +34,7 @@ jobs:
         qmk --verbose generate-docs
 
     - name: Deploy
-      uses: JamesIves/github-pages-deploy-action@3.7.1
+      uses: JamesIves/github-pages-deploy-action@v4.4.0
       with:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         BASE_BRANCH: master

.github/workflows/feature_branch_update.yml

@@ -17,11 +17,15 @@ jobs:
         - xap
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
       with:
         token: ${{ secrets.QMK_BOT_TOKEN }}
         fetch-depth: 0
 
+    - name: Disable automatic eol conversion
+      run: |
+        echo "* -text" > .git/info/attributes
+
     - name: Checkout branch
       run: |
         git fetch origin develop ${{ matrix.branch }}

.github/workflows/format.yaml

@@ -1,51 +0,0 @@
-name: PR Lint Format
-
-on:
-  pull_request:
-    paths:
-    - 'drivers/**'
-    - 'lib/arm_atsam/**'
-    - 'lib/lib8tion/**'
-    - 'lib/python/**'
-    - 'platforms/**'
-    - 'quantum/**'
-    - 'tests/**'
-    - 'tmk_core/**'
-
-jobs:
-  lint:
-    runs-on: ubuntu-latest
-
-    container: qmkfm/qmk_cli
-
-    steps:
-    - 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:
-        output: ' '
-        fileOutput: ' '
-
-    - name: Run qmk formatters
-      shell: 'bash {0}'
-      run: |
-        cat ~/files_added.txt ~/files_modified.txt > ~/files_changed.txt
-        qmk format-c --core-only $(< ~/files_changed.txt) || true
-        qmk format-python $(< ~/files_changed.txt) || true
-        qmk format-text $(< ~/files_changed.txt) || true
-
-    - name: Fail when formatting required
-      run: |
-        git diff
-        for file in $(git diff --name-only); do
-          echo "File '${file}' Requires Formatting"
-          echo "::error file=${file}::Requires Formatting"
-        done
-        test -z "$(git diff --name-only)"

.github/workflows/format.yml

@@ -0,0 +1,51 @@
+name: PR Lint Format
+
+on:
+  pull_request:
+    paths:
+    - 'drivers/**'
+    - 'lib/arm_atsam/**'
+    - 'lib/lib8tion/**'
+    - 'lib/python/**'
+    - 'platforms/**'
+    - 'quantum/**'
+    - 'tests/**'
+    - 'tmk_core/**'
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    container: qmkfm/qmk_cli
+
+    steps:
+    - uses: actions/checkout@v3
+      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:
+        output: ' '
+        fileOutput: ' '
+
+    - name: Run qmk formatters
+      shell: 'bash {0}'
+      run: |
+        cat ~/files_added.txt ~/files_modified.txt > ~/files_changed.txt
+        qmk format-c --core-only $(< ~/files_changed.txt) || true
+        qmk format-python $(< ~/files_changed.txt) || true
+        qmk format-text $(< ~/files_changed.txt) || true
+
+    - name: Fail when formatting required
+      run: |
+        git diff
+        for file in $(git diff --name-only); do
+          echo "File '${file}' Requires Formatting"
+          echo "::error file=${file}::Requires Formatting"
+        done
+        test -z "$(git diff --name-only)"

.github/workflows/format_push.yaml

@@ -1,49 +0,0 @@
-name: Lint Format
-
-on:
-  push:
-    branches:
-    - master
-    - develop
-
-jobs:
-  lint:
-    runs-on: ubuntu-latest
-
-    container: qmkfm/qmk_cli
-
-    steps:
-    - 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: |
-        qmk format-c -a
-        qmk format-python -a
-        qmk format-text -a
-        git diff
-
-    - uses: rlespinasse/github-slug-action@v3.x
-
-    - name: Become QMK Bot
-      run: |
-        git config user.name 'QMK Bot'
-        git config user.email 'hello@qmk.fm'
-
-    - name: Create Pull Request
-      uses: peter-evans/create-pull-request@v3
-      if: ${{ github.repository == 'qmk/qmk_firmware'}}
-      with:
-        token: ${{ secrets.QMK_BOT_TOKEN }}
-        delete-branch: true
-        branch: bugfix/format_${{ env.GITHUB_REF_SLUG }}
-        author: QMK Bot <hello@qmk.fm>
-        committer: QMK Bot <hello@qmk.fm>
-        commit-message: Format code according to conventions
-        title: '[CI] Format code according to conventions'

.github/workflows/format_push.yml

@@ -0,0 +1,53 @@
+name: Lint Format
+
+on:
+  push:
+    branches:
+    - master
+    - develop
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    container: qmkfm/qmk_cli
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+
+    - name: Disable automatic eol conversion
+      run: |
+        echo "* -text" > .git/info/attributes
+
+    - name: Install dependencies
+      run: |
+        pip3 install -r requirements-dev.txt
+
+    - name: Run qmk formatters
+      shell: 'bash {0}'
+      run: |
+        qmk format-c -a
+        qmk format-python -a
+        qmk format-text -a
+        git diff
+
+    - uses: rlespinasse/github-slug-action@v3.x
+
+    - name: Become QMK Bot
+      run: |
+        git config user.name 'QMK Bot'
+        git config user.email 'hello@qmk.fm'
+
+    - name: Create Pull Request
+      uses: peter-evans/create-pull-request@v4
+      if: ${{ github.repository == 'qmk/qmk_firmware'}}
+      with:
+        token: ${{ secrets.QMK_BOT_TOKEN }}
+        delete-branch: true
+        branch: bugfix/format_${{ env.GITHUB_REF_SLUG }}
+        author: QMK Bot <hello@qmk.fm>
+        committer: QMK Bot <hello@qmk.fm>
+        commit-message: Format code according to conventions
+        title: '[CI] Format code according to conventions'

.github/workflows/lint.yml

@@ -12,10 +12,13 @@ jobs:
     container: qmkfm/qmk_cli
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
       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/stale.yml

@@ -0,0 +1,64 @@
+name: 'Close stale issues and PRs'
+on:
+  schedule:
+    - cron: '30 1 * * *'
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v5
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+          remove-stale-when-updated: true
+          exempt-draft-pr: true
+          ascending: true
+          operations-per-run: 150
+
+          stale-issue-label: stale
+          days-before-issue-stale: 90
+          days-before-issue-close: 30
+          exempt-issue-labels: bug,in progress,on hold,discussion,to do
+
+          stale-issue-message: >
+            This issue has been automatically marked as stale because it has not had activity in the
+            last 90 days. It will be closed in the next 30 days unless it is tagged properly or other activity
+            occurs.
+
+            For maintainers: Please label with `bug`, `in progress`, `on hold`, `discussion` or `to do` to prevent
+            the issue from being re-flagged.
+
+          close-issue-message: >
+            This issue has been automatically closed because it has not had activity in the last 30 days.
+            If this issue is still valid, re-open the issue and let us know.
+
+            // [stale-action-closed]
+
+          stale-pr-label: stale
+          days-before-pr-stale: 45
+          days-before-pr-close: 30
+          exempt-pr-labels: bug,awaiting review,breaking_change,in progress,on hold
+
+          stale-pr-message: >
+            Thank you for your contribution!
+
+            This pull request has been automatically marked as stale because it has not had
+            activity in the last 45 days. It will be closed in 30 days if no further activity occurs.
+            Please feel free to give a status update now, or re-open when it's ready.
+
+            For maintainers: Please label with `bug`, `awaiting review`, `breaking_change`, `in progress`, or `on hold`
+            to prevent the issue from being re-flagged.
+
+          close-pr-message: >
+            Thank you for your contribution!
+
+            This pull request has been automatically closed because it has not had activity in the last 30 days.
+            Please feel free to give a status update now, ping for review, or re-open when it's ready.
+
+            // [stale-action-closed]

.github/workflows/unit_test.yml

@@ -20,11 +20,13 @@ jobs:
   test:
     runs-on: ubuntu-latest
 
-    container: qmkfm/base_container
+    container: qmkfm/qmk_cli
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
       with:
         submodules: recursive
+    - name: Install dependencies
+      run: pip3 install -r requirements-dev.txt
     - name: Run tests
       run: make test:all

.gitignore

@@ -5,6 +5,10 @@
 .DS_Store
 ._*
 
+# Merge files
+*.orig
+*.rej
+
 # Build artifacts
 .clang_complete
 .build/
@@ -27,16 +31,11 @@ quantum/version.h
 *.uf2
 
 # Old-style QMK Makefiles
-/keyboards/*/Makefile
-/keyboards/*/*/Makefile
-/keyboards/*/*/*/Makefile
-/keyboards/*/*/*/*/Makefile
-/keyboards/*/*/*/*/*/Makefile
-/keyboards/*/keymaps/Makefile
-/keyboards/*/*/keymaps/Makefile
-/keyboards/*/*/*/keymaps/Makefile
-/keyboards/*/*/*/*/keymaps/Makefile
-/keyboards/*/*/*/*/*/keymaps/Makefile
+/keyboards/**/Makefile
+
+# kbfirmware....
+/keyboards/**/kb.h
+/keyboards/**/kb.c
 
 # Eclipse/PyCharm/Other IDE Settings
 *.iml
@@ -67,10 +66,12 @@ CMakeLists.txt
 .vscode/temp.sql
 tags
 
-# Ignore image files
+# Ignore image/font files
 *.gif
 *.jpg
 *.png
+*.ttf
+*.otf
 
 # Things Travis sees
 /.vs
@@ -91,3 +92,6 @@ user_song_list.h
 compile_commands.json
 .clangd/
 .cache/
+
+# VIA(L) json files that don't belong in QMK repo
+via*.json

Makefile

@@ -428,9 +428,15 @@ lib/%:
 
 .PHONY: git-submodule
 git-submodule:
+	[ -e lib/ugfx ] && rm -rf lib/ugfx || true
+	[ -e lib/pico-sdk ] && rm -rf lib/pico-sdk || true
+	[ -e lib/chibios-contrib/ext/mcux-sdk ] && rm -rf lib/chibios-contrib/ext/mcux-sdk || true
 	git submodule sync --recursive
 	git submodule update --init --recursive --progress
 
+.PHONY: git-submodules
+git-submodules: git-submodule
+
 .PHONY: list-keyboards
 list-keyboards:
 	util/list_keyboards.sh | sort -u | tr '\n' ' '

builddefs/bootloader.mk

@@ -97,12 +97,18 @@ ifeq ($(strip $(BOOTLOADER)), halfkay)
     OPT_DEFS += -DBOOTLOADER_HALFKAY
     BOOTLOADER_TYPE = halfkay
 
+    # Teensy 2.0
     ifeq ($(strip $(MCU)), atmega32u4)
         BOOTLOADER_SIZE = 512
     endif
+    # Teensy 2.0++
     ifeq ($(strip $(MCU)), at90usb1286)
         BOOTLOADER_SIZE = 1024
     endif
+    # Teensy LC, 3.x
+    ifneq (,$(filter $(MCU_ORIG), MKL26Z64 MK20DX128 MK20DX256 MK66FX1M0))
+        FIRMWARE_FORMAT = hex
+    endif
 endif
 ifeq ($(strip $(BOOTLOADER)), caterina)
     OPT_DEFS += -DBOOTLOADER_CATERINA
@@ -202,6 +208,10 @@ ifeq ($(strip $(BOOTLOADER)), md-boot)
     OPT_DEFS += -DBOOTLOADER_MD_BOOT
     BOOTLOADER_TYPE = md_boot
 endif
+ifeq ($(strip $(BOOTLOADER)), wb32-dfu)
+    OPT_DEFS += -DBOOTLOADER_WB32_DFU
+    BOOTLOADER_TYPE = wb32_dfu
+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.)

builddefs/build_keyboard.mk

@@ -172,13 +172,7 @@ generated-files: $(KEYMAP_OUTPUT)/src/config.h $(KEYMAP_OUTPUT)/src/keymap.c
 
 endif
 
-ifeq ($(strip $(CTPC)), yes)
-    CONVERT_TO_PROTON_C=yes
-endif
-
-ifeq ($(strip $(CONVERT_TO_PROTON_C)), yes)
-    include platforms/chibios/boards/QMK_PROTON_C/convert_to_proton_c.mk
-endif
+include $(BUILDDEFS_PATH)/converters.mk
 
 include $(BUILDDEFS_PATH)/mcu_selection.mk
 
@@ -328,12 +322,18 @@ ifneq ("$(wildcard $(KEYBOARD_PATH_5)/info.json)","")
 endif
 
 CONFIG_H += $(KEYBOARD_OUTPUT)/src/info_config.h $(KEYBOARD_OUTPUT)/src/layouts.h
+KEYBOARD_SRC += $(KEYBOARD_OUTPUT)/src/default_keyboard.c
 
 $(KEYBOARD_OUTPUT)/src/info_config.h: $(INFO_JSON_FILES)
 	@$(SILENT) || printf "$(MSG_GENERATING) $@" | $(AWK_CMD)
 	$(eval CMD=$(QMK_BIN) generate-config-h --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/info_config.h)
 	@$(BUILD_CMD)
 
+$(KEYBOARD_OUTPUT)/src/default_keyboard.c: $(INFO_JSON_FILES)
+	@$(SILENT) || printf "$(MSG_GENERATING) $@" | $(AWK_CMD)
+	$(eval CMD=$(QMK_BIN) generate-keyboard-c --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/default_keyboard.c)
+	@$(BUILD_CMD)
+
 $(KEYBOARD_OUTPUT)/src/default_keyboard.h: $(INFO_JSON_FILES)
 	@$(SILENT) || printf "$(MSG_GENERATING) $@" | $(AWK_CMD)
 	$(eval CMD=$(QMK_BIN) generate-keyboard-h --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/default_keyboard.h)
@@ -344,7 +344,7 @@ $(KEYBOARD_OUTPUT)/src/layouts.h: $(INFO_JSON_FILES)
 	$(eval CMD=$(QMK_BIN) generate-layouts --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/layouts.h)
 	@$(BUILD_CMD)
 
-generated-files: $(KEYBOARD_OUTPUT)/src/info_config.h $(KEYBOARD_OUTPUT)/src/default_keyboard.h $(KEYBOARD_OUTPUT)/src/layouts.h
+generated-files: $(KEYBOARD_OUTPUT)/src/info_config.h $(KEYBOARD_OUTPUT)/src/default_keyboard.c $(KEYBOARD_OUTPUT)/src/default_keyboard.h $(KEYBOARD_OUTPUT)/src/layouts.h
 
 .INTERMEDIATE : generated-files
 

builddefs/common_features.mk

@@ -149,6 +149,11 @@ ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
     endif
 endif
 
+QUANTUM_PAINTER_ENABLE ?= no
+ifeq ($(strip $(QUANTUM_PAINTER_ENABLE)), yes)
+    include $(QUANTUM_DIR)/painter/rules.mk
+endif
+
 VALID_EEPROM_DRIVER_TYPES := vendor custom transient i2c spi
 EEPROM_DRIVER ?= vendor
 ifeq ($(filter $(EEPROM_DRIVER),$(VALID_EEPROM_DRIVER_TYPES)),)
@@ -551,6 +556,17 @@ ifeq ($(strip $(VIA_ENABLE)), yes)
     OPT_DEFS += -DVIA_ENABLE
 endif
 
+ifeq ($(strip $(ENC_ENABLE)), yes)
+	RAW_ENABLE := yes
+	COMMON_VPATH += $(QUANTUM_DIR)/enc
+	COMMON_VPATH += $(QUANTUM_DIR)/enc/enc_boards
+	include $(QUANTUM_DIR)/enc/enc_boards/enc_boards.mk
+	OPT_DEFS += -DENC_ENABLE
+	SRC += aes.c
+	SRC += pkcs7_padding.c
+	SRC += enc.c
+endif
+
 VALID_MAGIC_TYPES := yes
 BOOTMAGIC_ENABLE ?= no
 ifneq ($(strip $(BOOTMAGIC_ENABLE)), no)
@@ -696,7 +712,8 @@ endif
 
 ifeq ($(strip $(UNICODE_COMMON)), yes)
     OPT_DEFS += -DUNICODE_COMMON_ENABLE
-    SRC += $(QUANTUM_DIR)/process_keycode/process_unicode_common.c
+    SRC += $(QUANTUM_DIR)/process_keycode/process_unicode_common.c \
+           $(QUANTUM_DIR)/utf8.c
 endif
 
 MAGIC_ENABLE ?= yes

builddefs/common_rules.mk

@@ -82,8 +82,8 @@ endif
 #  -Wall...:     warning level
 #  -Wa,...:      tell GCC to pass this to the assembler.
 ifeq ($(strip $(LTO_ENABLE)), yes)
-    ifeq ($(PLATFORM),CHIBIOS)
-        $(info Enabling LTO on ChibiOS-targeting boards is known to have a high likelihood of failure.)
+    ifeq ($(PLATFORM),ARM_ATSAM)
+        $(info Enabling LTO on arm_atsam-targeting boards is known to have a high likelihood of failure.)
         $(info If unsure, set LTO_ENABLE = no.)
     endif
     CDEFS += -flto

builddefs/converters.mk

@@ -0,0 +1,37 @@
+# Note for new boards -- CTPC and CONVERT_TO_PROTON_C are deprecated terms
+# and should not be replicated for new boards. These will be removed from
+# documentation as well as existing keymaps in due course.
+ifeq ($(strip $(CTPC)), yes)
+    CONVERT_TO_PROTON_C=yes
+endif
+ifeq ($(strip $(CONVERT_TO_PROTON_C)), yes)
+    CONVERT_TO=proton_c
+
+cpfirmware: ctpc_warning
+.INTERMEDIATE: ctpc_warning
+ctpc_warning: elf
+	$(info @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@)
+	$(info The `CONVERT_TO_PROTON_C` and `CTPC` options are soon to be deprecated.)
+	$(info Boards should be changed to use `CONVERT_TO=proton_c` instead.)
+	$(info @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@)
+endif
+
+# TODO: opt in rather than assume everything uses a pro micro
+PIN_COMPATIBLE ?= promicro
+ifneq ($(CONVERT_TO),)
+    # glob to search each platfrorm and/or check for valid converter
+    CONVERTER := $(wildcard $(PLATFORM_PATH)/*/converters/$(PIN_COMPATIBLE)_to_$(CONVERT_TO)/)
+    ifeq ($(CONVERTER),)
+        $(call CATASTROPHIC_ERROR,Converting from '$(PIN_COMPATIBLE)' to '$(CONVERT_TO)' not possible!)
+    endif
+
+    TARGET := $(TARGET)_$(CONVERT_TO)
+
+    # Configure any defaults
+    OPT_DEFS += -DCONVERT_TO_$(strip $(shell echo $(CONVERT_TO) | tr '[:lower:]' '[:upper:]'))
+    OPT_DEFS += -DCONVERTER_ENABLED
+    VPATH += $(CONVERTER)
+
+    # Finally run any converter specific logic
+    include $(CONVERTER)/converter.mk
+endif

builddefs/generic_features.mk

@@ -17,6 +17,7 @@ SPACE_CADET_ENABLE ?= yes
 GRAVE_ESC_ENABLE ?= yes
 
 GENERIC_FEATURES = \
+    CAPS_WORD \
     COMBO \
     COMMAND \
     DEFERRED_EXEC \
@@ -32,6 +33,7 @@ GENERIC_FEATURES = \
     KEY_OVERRIDE \
     LEADER \
     PROGRAMMABLE_BUTTON \
+    SECURE \
     SPACE_CADET \
     SWAP_HANDS \
     TAP_DANCE \

builddefs/mcu_selection.mk

@@ -680,7 +680,40 @@ ifneq ($(findstring WB32F3G71, $(MCU)),)
   USE_FPU ?= no
 
   # Bootloader address for WB32 DFU
-  STM32_BOOTLOADER_ADDRESS ?= 0x1FFFE000
+  WB32_BOOTLOADER_ADDRESS ?= 0x1FFFE000
+endif
+
+ifneq ($(findstring WB32FQ95, $(MCU)),)
+  # Cortex version
+  MCU = cortex-m3
+
+  # 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[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  MCU_FAMILY = WB32
+  MCU_SERIES = WB32FQ95xx
+
+  # Linker script to use
+  # - it should exist either in <chibios>/os/common/ports/ARMCMx/compilers/GCC/ld/
+  #   or <keyboard_dir>/ld/
+  MCU_LDSCRIPT ?= WB32FQ95xB
+
+  # Startup code to use
+  #  - it should exist in <chibios>/os/common/startup/ARMCMx/compilers/GCC/mk/
+  MCU_STARTUP ?= wb32fq95xx
+
+  # Board: it should exist either in <chibios>/os/hal/boards/,
+  # <keyboard_dir>/boards/, or drivers/boards/
+  BOARD ?= GENERIC_WB32_FQ95XX
+
+  USE_FPU ?= no
+
+  # Bootloader address for WB32 DFU
   WB32_BOOTLOADER_ADDRESS ?= 0x1FFFE000
 endif
 

builddefs/show_options.mk

@@ -11,7 +11,8 @@ BUILD_OPTION_NAMES = \
   SPLIT_KEYBOARD \
   DYNAMIC_KEYMAP_ENABLE \
   USB_HID_ENABLE \
-  VIA_ENABLE
+  VIA_ENABLE \
+  ENC_ENABLE
 
 HARDWARE_OPTION_NAMES = \
   SLEEP_LED_ENABLE \
@@ -80,7 +81,9 @@ OTHER_OPTION_NAMES = \
   LED_MIRRORED \
   RGBLIGHT_FULL_POWER \
   LTO_ENABLE \
-  PROGRAMMABLE_BUTTON_ENABLE
+  PROGRAMMABLE_BUTTON_ENABLE \
+  SECURE_ENABLE \
+  CAPS_WORD_ENABLE
 
 define NAME_ECHO
        @printf "  %-30s = %-16s # %s\\n" "$1" "$($1)" "$(origin $1)"

data/mappings/defaults.json

@@ -0,0 +1,35 @@
+{
+    "development_board": {
+        "promicro": {
+            "processor": "atmega32u4",
+            "bootloader": "caterina",
+            "pin_compatible": "promicro"
+        },
+        "elite_c": {
+            "processor": "atmega32u4",
+            "bootloader": "atmel-dfu",
+            "pin_compatible": "promicro"
+        },
+        "proton_c": {
+            "processor": "STM32F303",
+            "bootloader": "stm32-dfu",
+            "board": "QMK_PROTON_C",
+            "pin_compatible": "promicro"
+        },
+        "bluepill": {
+            "processor": "STM32F103",
+            "bootloader": "stm32duino",
+            "board": "STM32_F103_STM32DUINO"
+        },
+        "blackpill_f401": {
+            "processor": "STM32F401",
+            "bootloader": "stm32-dfu",
+            "board": "BLACKPILL_STM32_F401"
+        },
+        "blackpill_f411": {
+            "processor": "STM32F411",
+            "bootloader": "stm32-dfu",
+            "board": "BLACKPILL_STM32_F411"
+        }
+    }
+}

data/mappings/info_config.json

@@ -7,18 +7,23 @@
     # to_json: Default `true`. Set to `false` to exclude this mapping from info.json
     # to_c: Default `true`. Set to `false` to exclude this mapping from config.h
     # warn_duplicate: Default `true`. Set to `false` to turn off warning when a value exists in both places
+    # deprecated: Default `false`. Set to `true` to turn on warning when a value exists
+    # invalid: Default `false`. Set to `true` to generate errors when a value exists
+    # replace_with: use with a key marked deprecated or invalid to designate a replacement
     "AUDIO_VOICES": {"info_key": "audio.voices", "value_type": "bool"},
     "BACKLIGHT_BREATHING": {"info_key": "backlight.breathing", "value_type": "bool"},
     "BREATHING_PERIOD": {"info_key": "backlight.breathing_period", "value_type": "int"},
     "BACKLIGHT_PIN": {"info_key": "backlight.pin"},
+    "BOTH_SHIFTS_TURNS_ON_CAPS_WORD": {"info_key": "caps_word.both_shifts_turns_on", "value_type": "bool"},
+    "CAPS_WORD_IDLE_TIMEOUT": {"info_key": "caps_word.idle_timeout", "value_type": "int"},
     "COMBO_COUNT": {"info_key": "combo.count", "value_type": "int"},
     "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", "value_type": "str", "to_json": false},
     "DIODE_DIRECTION": {"info_key": "diode_direction"},
+    "DOUBLE_TAP_SHIFT_TURNS_ON_CAPS_WORD": {"info_key": "caps_word.double_tap_shift_turns_on", "value_type": "bool"},
     "FORCE_NKRO": {"info_key": "usb.force_nkro", "value_type": "bool"},
     "DYNAMIC_KEYMAP_EEPROM_MAX_ADDR": {"info_key": "dynamic_keymap.eeprom_max_addr", "value_type": "int"},
     "DYNAMIC_KEYMAP_LAYER_COUNT": {"info_key": "dynamic_keymap.layer_count", "value_type": "int"},
@@ -78,6 +83,9 @@
     "QMK_KEYS_PER_SCAN": {"info_key": "qmk.keys_per_scan", "value_type": "int"},
     "QMK_LED": {"info_key": "qmk_lufa_bootloader.led"},
     "QMK_SPEAKER": {"info_key": "qmk_lufa_bootloader.speaker"},
+    "SECURE_UNLOCK_SEQUENCE": {"info_key": "secure.unlock_sequence", "value_type": "array.array.int", "to_json": false},
+    "SECURE_UNLOCK_TIMEOUT": {"info_key": "secure.unlock_timeout", "value_type": "int"},
+    "SECURE_IDLE_TIMEOUT": {"info_key": "secure.idle_timeout", "value_type": "int"},
     "SENDSTRING_BELL": {"info_key": "audio.macro_beep", "value_type": "bool"},
     "SPLIT_MODS_ENABLE": {"info_key": "split.transport.sync_modifiers", "value_type": "bool"},
     "SPLIT_TRANSPORT_MIRROR": {"info_key": "split.transport.sync_matrix_state", "value_type": "bool"},
@@ -96,4 +104,11 @@
     "USB_MAX_POWER_CONSUMPTION": {"info_key": "usb.max_power", "value_type": "int"},
     "USB_POLLING_INTERVAL_MS": {"info_key": "usb.polling_interval", "value_type": "int"},
     "USB_SUSPEND_WAKEUP_DELAY": {"info_key": "usb.suspend_wakeup_delay", "value_type": "int"},
+
+    # Items we want flagged in lint
+    "NO_ACTION_MACRO": {"info_key": "_invalid.no_action_macro", "invalid": true},
+    "NO_ACTION_FUNCTION": {"info_key": "_invalid.no_action_function", "invalid": true},
+    "DESCRIPTION": {"info_key": "_invalid.usb_description", "invalid": true},
+    "DEBOUNCING_DELAY": {"info_key": "_invalid.debouncing_delay", "invalid": true, replace_with: "DEBOUNCE"},
+    "PREVENT_STUCK_MODIFIERS": {"info_key": "_invalid.prevent_stuck_mods", "invalid": true},
 }

data/mappings/info_rules.json

@@ -7,9 +7,13 @@
     # to_json: Default `true`. Set to `false` to exclude this mapping from info.json
     # to_c: Default `true`. Set to `false` to exclude this mapping from rules.mk
     # warn_duplicate: Default `true`. Set to `false` to turn off warning when a value exists in both places
+    # deprecated: Default `false`. Set to `true` to turn on warning when a value exists
+    # invalid: Default `false`. Set to `true` to generate errors when a value exists
+    # replace_with: use with a key marked deprecated or invalid to designate a replacement
     "BOARD": {"info_key": "board"},
     "BOOTLOADER": {"info_key": "bootloader", "warn_duplicate": false},
     "BLUETOOTH": {"info_key": "bluetooth.driver"},
+    "CAPS_WORD_ENABLE": {"info_key": "caps_word.enabled", "value_type": "bool"},
     "FIRMWARE_FORMAT": {"info_key": "build.firmware_format"},
     "KEYBOARD_SHARED_EP": {"info_key": "usb.shared_endpoint.keyboard", "value_type": "bool"},
     "MOUSE_SHARED_EP": {"info_key": "usb.shared_endpoint.mouse", "value_type": "bool"},
@@ -19,7 +23,14 @@
     "MCU": {"info_key": "processor", "warn_duplicate": false},
     "MOUSEKEY_ENABLE": {"info_key": "mouse_key.enabled", "value_type": "bool"},
     "NO_USB_STARTUP_CHECK": {"info_key": "usb.no_startup_check", "value_type": "bool"},
+    "PIN_COMPATIBLE": {"info_key": "pin_compatible"},
+    "SECURE_ENABLE": {"info_key": "secure.enabled", "value_type": "bool"},
     "SPLIT_KEYBOARD": {"info_key": "split.enabled", "value_type": "bool"},
     "SPLIT_TRANSPORT": {"info_key": "split.transport.protocol", "to_c": false},
-    "WAIT_FOR_USB": {"info_key": "usb.wait_for", "value_type": "bool"}
+    "WAIT_FOR_USB": {"info_key": "usb.wait_for", "value_type": "bool"},
+
+    # Items we want flagged in lint
+    "CTPC": {"info_key": "_deprecated.ctpc", "deprecated": true, "replace_with": "CONVERT_TO=proton_c"},
+    "CONVERT_TO_PROTON_C": {"info_key": "_deprecated.ctpc", "deprecated": true, "replace_with": "CONVERT_TO=proton_c"},
+    "VIAL_ENABLE": {"info_key": "_invalid.vial", "invalid": true},
 }

data/mappings/keyboard_aliases.json

@@ -11,6 +11,9 @@
     '2_milk': {
           target: 'spaceman/2_milk'
     },
+    'absinthe': {
+        target: 'keyhive/absinthe'
+    },
     'aeboards/constellation': {
           target: 'aeboards/constellation/rev1'
     },
@@ -26,6 +29,18 @@
     alice: {
           target: 'tgr/alice'
     },
+    amj40: {
+        target: 'amjkeyboard/amj40'
+    },
+    amj60: {
+        target: 'amjkeyboard/amj60'
+    },
+    amj96: {
+        target: 'amjkeyboard/amj96'
+    },
+    amjpad: {
+        target: 'amjkeyboard/amjpad'
+    },
     angel17: {
           target: 'angel17/alpha'
     },
@@ -33,7 +48,10 @@
           target: 'angel64/alpha'
     },
     at101_blackheart: {
-          target: 'at101_bh'
+          target: 'viktus/at101_bh'
+    },
+    at101_bh: {
+        target: 'viktus/at101_bh'
     },
     'atom47/rev2': {
           target: 'maartenwut/atom47/rev2'
@@ -158,6 +176,9 @@
     ergoinu: {
           target: 'dm9records/ergoinu'
     },
+    ergosaurus: {
+        target: 'keyhive/ergosaurus'
+    },
     'exclusive/e85': {
           target: 'exclusive/e85/hotswap'
     },
@@ -165,7 +186,13 @@
           target: 'gh60/revc'
     },
     'gmmk/pro': {
-          target: 'gmmk/pro/ansi'
+          target: 'gmmk/pro/rev1/ansi'
+    },
+    'gmmk/pro/ansi': {
+        target: 'gmmk/pro/rev1/ansi'
+    },
+    'gmmk/pro/iso': {
+        target: 'gmmk/pro/rev1/iso'
     },
     'handwired/ferris': {
           target: 'ferris/0_1'
@@ -212,6 +239,9 @@
     'helix/rev2/under/oled': {
           target: 'helix/rev2/under'
     },
+    honeycomb: {
+        target: 'keyhive/honeycomb'
+    },
     id80: {
           target: 'id80/ansi'
     },
@@ -260,6 +290,9 @@
     'kyria': {
           target: 'splitkb/kyria'
     },
+    lattice60: {
+        target: 'keyhive/lattice60'
+    },
     'lazydesigners/the60': {
           target: 'lazydesigners/the60/rev1'
     },
@@ -392,7 +425,13 @@
           target: 'oddball/v1'
     },
     omnikey_blackheart: {
-          target: 'omnikey_bh'
+          target: 'viktus/omnikey_bh'
+    },
+    omnikey_bh: {
+        target: 'viktus/omnikey_bh'
+    },
+    opus: {
+        target: 'keyhive/opus'
     },
     'pabile/p20': {
           target: 'pabile/p20/ver1'
@@ -489,6 +528,12 @@
     skog: {
           target: 'percent/skog'
     },
+    smallice: {
+        target: 'keyhive/smallice'
+    },
+    southpole: {
+        target: 'keyhive/southpole'
+    },
     speedo: {
           target: 'cozykeys/speedo/v2'
     },
@@ -577,7 +622,10 @@
           target: 'ymd75/rev1'
     },
     z150_blackheart: {
-          target: 'z150_bh'
+          target: 'viktus/z150_bh'
+    },
+    z150_bh:{
+        target: 'viktus/z150_bh'
     },
     zeal60: {
           target: 'wilba_tech/zeal60'
@@ -904,6 +952,9 @@
     meishi2: {
         target: 'biacco42/meishi2'
     },
+    melody96: {
+        target: 'ymdk/melody96'
+    },
     minidox/rev1: {
         target: 'maple_computing/minidox/rev1'
     },
@@ -919,6 +970,18 @@
     montex: {
         target: 'idobao/montex/v1'
     },
+    mt40: {
+        target: 'mt/mt40'
+    },
+    mt64rgb: {
+        target: 'mt/mt64rgb'
+    },
+    mt84: {
+        target: 'mt/mt84'
+    },
+    mt980: {
+        target: 'mt/mt980'
+    },
     nafuda: {
         target: 'salicylic_acid3/nafuda'
     },
@@ -943,6 +1006,9 @@
     namecard2x4: {
         target: 'takashiski/namecard2x4'
     },
+    navi10: {
+        target: 'keyhive/navi10'
+    },
     nebula12: {
         target: 'spaceholdings/nebula12'
     },
@@ -1144,6 +1210,12 @@
     underscore33/rev2: {
         target: 'tominabox1/underscore33/rev2'
     },
+    uno: {
+        target: 'keyhive/uno'
+    },
+    ut472: {
+        target: 'keyhive/ut472'
+    },
     vn66: {
         target: 'hnahkb/vn66'
     },
@@ -1153,6 +1225,12 @@
     wanten: {
         target: 'qpockets/wanten'
     },
+    'wheatfield/blocked65': {
+        target: 'mt/blocked65'
+    },
+    'wheatfield/split75': {
+        target: 'mt/split75'
+    },
     whitefox: {
         target: 'input_club/whitefox'
     },

data/schemas/definitions.jsonschema

@@ -41,8 +41,6 @@
                     "LAYOUT_2x2uC",
                     "LAYOUT_2x3uC",
                     "LAYOUT_625uC",
-                    "LAYOUT_ANSI_DEFAULT",
-                    "LAYOUT_JP",
                     "LAYOUT_ortho_3x12_1x2uC",
                     "LAYOUT_ortho_4x12_1x2uC",
                     "LAYOUT_ortho_4x12_1x2uL",
@@ -57,8 +55,7 @@
                     "LAYOUT_planck_1x2uR",
                     "LAYOUT_preonic_1x2uC",
                     "LAYOUT_preonic_1x2uL",
-                    "LAYOUT_preonic_1x2uR",
-                    "LAYOUT_reviung34_2uL"
+                    "LAYOUT_preonic_1x2uR"
                 ]
             },
             {
@@ -71,6 +68,22 @@
         "type": "number",
         "min": 0.25
     },
+    "keyboard": {
+        "oneOf": [
+            {
+                "type": "string",
+                "enum": [
+                    "converter/numeric_keypad_IIe",
+                    "emptystring/NQG",
+                    "maple_computing/christmas_tree/V2017"
+                ]
+            },
+            {
+                "type": "string",
+                "pattern": "^[0-9a-z][0-9a-z_/]*$"
+            }
+        ]
+    },
     "mcu_pin_array": {
         "type": "array",
         "items": {"$ref": "#/mcu_pin"}

data/schemas/keyboard.jsonschema

@@ -5,15 +5,24 @@
     "type": "object",
     "properties": {
         "keyboard_name": {"$ref": "qmk.definitions.v1#/text_identifier"},
+        "keyboard_folder": {"$ref": "qmk.definitions.v1#/keyboard"},
         "maintainer": {"$ref": "qmk.definitions.v1#/text_identifier"},
         "manufacturer": {"$ref": "qmk.definitions.v1#/text_identifier"},
         "url": {
             "type": "string",
             "format": "uri"
         },
+        "development_board": {
+            "type": "string",
+            "enum": ["promicro", "elite_c", "proton_c", "bluepill", "blackpill_f401", "blackpill_f411"]
+        },
+        "pin_compatible": {
+            "type": "string",
+            "enum": ["promicro"]
+        },
         "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", "STM32L432", "STM32L433", "STM32L442", "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", "WB32FQ95", "atmega16u2", "atmega32u2", "atmega16u4", "atmega32u4", "at90usb162", "at90usb646", "at90usb647", "at90usb1286", "at90usb1287", "atmega32a", "atmega328p", "atmega328", "attiny85", "unknown"]
         },
         "audio": {
             "type": "object",
@@ -83,6 +92,16 @@
             "enum": ["COL2ROW", "ROW2COL"]
         },
         "debounce": {"$ref": "qmk.definitions.v1#/unsigned_int"},
+        "caps_word": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "enabled": {"type": "boolean"},
+                "both_shifts_turns_on": {"type": "boolean"},
+                "double_tap_shift_turns_on": {"type": "boolean"},
+                "idle_timeout": {"$ref": "qmk.definitions.v1#/unsigned_int"},
+            },
+        },
         "combo": {
             "type": "object",
             "properties": {
@@ -126,7 +145,10 @@
                             "type": "object",
                             "additionalProperties": false,
                             "properties": {
-                                "label": {"type": "string"},
+                                "label": {
+                                    "type": "string",
+                                    "pattern": "^[^\\n]*$"
+                                },
                                 "matrix": {
                                     "type": "array",
                                     "minItems": 2,
@@ -193,6 +215,62 @@
                 "timeout": {"$ref": "qmk.definitions.v1#/unsigned_int"}
             }
         },
+        "led_matrix": {
+            "type": "object",
+            "properties": {
+                "driver": {"type": "string"},
+                "layout": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "properties": {
+                            "matrix": {
+                                "type": "array",
+                                "minItems": 2,
+                                "maxItems": 2,
+                                "items": {
+                                    "type": "number",
+                                    "min": 0,
+                                    "multipleOf": 1
+                                }
+                            },
+                            "x": {"$ref": "qmk.definitions.v1#/key_unit"},
+                            "y": {"$ref": "qmk.definitions.v1#/key_unit"},
+                            "flags": {"$ref": "qmk.definitions.v1#/unsigned_decimal"}
+                        }
+                    }
+                }
+            }
+        },
+        "rgb_matrix": {
+            "type": "object",
+            "properties": {
+                "driver": {"type": "string"},
+                "layout": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "properties": {
+                            "matrix": {
+                                "type": "array",
+                                "minItems": 2,
+                                "maxItems": 2,
+                                "items": {
+                                    "type": "number",
+                                    "min": 0,
+                                    "multipleOf": 1
+                                }
+                            },
+                            "x": {"$ref": "qmk.definitions.v1#/key_unit"},
+                            "y": {"$ref": "qmk.definitions.v1#/key_unit"},
+                            "flags": {"$ref": "qmk.definitions.v1#/unsigned_decimal"}
+                        }
+                    }
+                }
+            }
+        },
         "rgblight": {
             "type": "object",
             "additionalProperties": false,
@@ -235,6 +313,30 @@
                 }
             }
         },
+        "secure": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "enabled": {"type": "boolean"},
+                "unlock_timeout": {"$ref": "qmk.definitions.v1#/unsigned_int"},
+                "idle_timeout": {"$ref": "qmk.definitions.v1#/unsigned_int"},
+                "unlock_sequence": {
+                    "type": "array",
+                    "minLength": 1,
+                    "maxLength": 5,
+                    "items": {
+                        "type": "array",
+                        "minItems": 2,
+                        "maxItems": 2,
+                        "items": {
+                            "type": "number",
+                            "min": 0,
+                            "multipleOf": 1
+                        }
+                    }
+                }
+            }
+        },
         "split": {
             "type": "object",
             "additionalProperties": false,

data/templates/keyboard/readme.md

@@ -24,4 +24,4 @@ Enter the bootloader in 3 ways:
 
 * **Bootmagic reset**: Hold down the key at (0,0) in the matrix (usually the top left key or Escape) and plug in the keyboard
 * **Physical reset button**: Briefly press the button on the back of the PCB - some may have pads you must short instead
-* **Keycode in layout**: Press the key mapped to `RESET` if it is available
+* **Keycode in layout**: Press the key mapped to `QK_BOOT` if it is available

docs/ChangeLog/20220528.md

@@ -0,0 +1,216 @@
+# QMK Breaking Changes - 2022 May 28 Changelog
+
+## Notable Features :id=notable-features
+
+### Caps Word ([#16588](https://github.com/qmk/qmk_firmware/pull/16588)) :id=caps-word
+
+This is a new feature that allows for capslock-like functionality that turns itself off at the end of the word.
+
+For instance, if you wish to type "QMK" without holding shift the entire time, you can either tap both left and right shift, or double-tap shift, to turn on _Caps Word_ -- then type `qmk` (lowercase) without holding shift. Once you hit any key other than `a`--`z`, `0`--`9`, `-`, `_`, delete, or backspace, this will go back to normal typing!
+
+There are other activation mechanisms as well as configurable options like timeout and the like -- see the [Caps Word documentation](feature_caps_word.md) for more information.
+
+### Quantum Painter ([#10174](https://github.com/qmk/qmk_firmware/pull/10174)) :id=quantum-painter
+
+QMK has had support for small OLED displays for some time now, but hasn't really gained too much ability to draw to panels other than the SSD1306 or SH1106 panels.
+
+Quantum Painter is a new drawing subsystem available to suitable ARM and RISC-V boards that is capable of drawing to large panel RGB LCDs and RGB OLEDs. It also allows for a lot more flexibility with a larger set of drawing APIs -- lines, rectangles, circles, ellipses, text, images, and even animations.
+
+The QMK CLI has new commands added to be able to generate images and fonts for Quantum Painter to digest -- it's even capable of converting animated gifs for display on screen.
+
+See the [Quantum Painter documentation](quantum_painter.md) for more information on how to set up the displays as well as how to convert images and fonts.
+
+!> Quantum Painter is not supported on AVR due to complexity and size constraints. Boards based on AVR such as ProMicro or Elite-C builds will not be able to leverage Quantum Painter.
+
+### Encoder Mapping ([#13286](https://github.com/qmk/qmk_firmware/pull/13286)) :id=encoder-mapping
+
+One of the long-standing complaints with Encoders is that there has been no easy way to configure them in user keymaps. [#13286](https://github.com/qmk/qmk_firmware/pull/13286) added support for [Encoder Mapping](feature_encoders.md#encoder-map), which allows users to define encoder functionality in a similar way to their normal keymap.
+
+!> This is not yet supported by QMK Configurator. It is also unlikely to ever be supported by VIA.
+
+## Changes Requiring User Action :id=changes-requiring-user-action
+
+### `RESET` => `QK_BOOT` ([#17037](https://github.com/qmk/qmk_firmware/pull/17037)) :id=reset-2-qk_boot
+
+QMK is always in the process of picking up support for new hardware platforms. One of the side-effects for future integrations has shown that QMK's usage of `RESET` as a keycode is causing naming collisions. As a result, [#17037](https://github.com/qmk/qmk_firmware/pull/17037) changed usages of `RESET` to the new keycode `QK_BOOT` in the majority of default-like keymaps. At this stage the old keycode is still usable but will likely be removed in the next breaking changes cycle. Users with keymaps containing `RESET` should also move to `QK_BOOT`.
+
+### Sendstring keycode overhaul ([#16941](https://github.com/qmk/qmk_firmware/pull/16941)) :id=sendstring-keycodes
+
+Some keycodes used with `SEND_STRING` and its relatives have been deprecated and may have their old keycode usages removed at a later date. The list of [deprecated keycodes](https://github.com/qmk/qmk_firmware/blob/ebd402788346aa6e88bde1486b2a835684d40d39/quantum/send_string_keycodes.h#L456-L505) should be consulted to determine if you're using one of the older names (the first identifier after `#define`) -- you should swap to the newer variant (the second identifier on the same line).
+
+### Pillow Installation ([#17133](https://github.com/qmk/qmk_firmware/pull/17133)) :id=pillow-install
+
+The merge of Quantum Painter added some new dependencies in the QMK CLI, most notably _Pillow_, which requires some installation in order for the CLI to function. If you've got an existing installation, you'll need to run some commands in order to get things working:
+
+On Windows, if using _QMK MSYS_ or _msys2_, you'll need to run the following command:
+
+```sh
+pacman --needed --noconfirm --disable-download-timeout -S mingw-w64-x86_64-python-pillow
+python3 -m pip install --upgrade qmk
+```
+
+On macOS:
+
+```sh
+brew update
+brew upgrade qmk/qmk/qmk
+```
+
+On Linux or WSL:
+
+```sh
+python3 -m pip install --user --upgrade qmk
+```
+
+### Updated Keyboard Codebases :id=updated-keyboard-codebases
+
+The following keyboards have had their source moved within QMK:
+
+| Old Keyboard Name    | New Keyboard Name  |
+|----------------------|--------------------|
+| absinthe             | keyhive/absinthe   |
+| amj40                | amjkeyboard/amj40  |
+| amj60                | amjkeyboard/amj60  |
+| amj96                | amjkeyboard/amj96  |
+| amjpad               | amjkeyboard/amjpad |
+| at101_bh             | viktus/at101_bh    |
+| ergosaurus           | keyhive/ergosaurus |
+| gmmk/pro/ansi        | gmmk/pro/rev1/ansi |
+| gmmk/pro/iso         | gmmk/pro/rev1/iso  |
+| honeycomb            | keyhive/honeycomb  |
+| lattice60            | keyhive/lattice60  |
+| melody96             | ymdk/melody96      |
+| mt40                 | mt/mt40            |
+| mt64rgb              | mt/mt64rgb         |
+| mt84                 | mt/mt84            |
+| mt980                | mt/mt980           |
+| navi10               | keyhive/navi10     |
+| omnikey_bh           | viktus/omnikey_bh  |
+| opus                 | keyhive/opus       |
+| smallice             | keyhive/smallice   |
+| southpole            | keyhive/southpole  |
+| uno                  | keyhive/uno        |
+| ut472                | keyhive/ut472      |
+| wheatfield/blocked65 | mt/blocked65       |
+| wheatfield/split75   | mt/split75         |
+| z150_bh              | viktus/z150_bh     |
+
+---
+
+## Full changelist :id=full-changelist
+
+Core:
+* Quantum Painter ([#10174](https://github.com/qmk/qmk_firmware/pull/10174))
+* Add support for encoder mapping. ([#13286](https://github.com/qmk/qmk_firmware/pull/13286))
+* Add support for multiple switchs/solenoids to Haptic Feedback engine ([#15657](https://github.com/qmk/qmk_firmware/pull/15657))
+* Add compile/make macro to core ([#15959](https://github.com/qmk/qmk_firmware/pull/15959))
+* Add Reboot keycode to core ([#15990](https://github.com/qmk/qmk_firmware/pull/15990))
+* Add support for multiple sensors to pmw3360 ([#15996](https://github.com/qmk/qmk_firmware/pull/15996))
+* Asymmetric encoders, encoder tests. ([#16068](https://github.com/qmk/qmk_firmware/pull/16068))
+* Add hacky via support for RGB Matrix ([#16086](https://github.com/qmk/qmk_firmware/pull/16086))
+* Allow usage of AVRs minimal printf library ([#16266](https://github.com/qmk/qmk_firmware/pull/16266))
+* Squeeze AVR some more with `-mrelax` and `-mcall-prologues` ([#16269](https://github.com/qmk/qmk_firmware/pull/16269))
+* Heatmap incorrect matrix effect workaround ([#16315](https://github.com/qmk/qmk_firmware/pull/16315))
+* Add SN74x154 driver and convert AL1 custom matrix ([#16331](https://github.com/qmk/qmk_firmware/pull/16331))
+* Add customizable snake and knight animation increments ([#16337](https://github.com/qmk/qmk_firmware/pull/16337))
+* Chibios USB protocol: allow overriding RAW Capacity ([#16339](https://github.com/qmk/qmk_firmware/pull/16339))
+* HD44780 driver rework ([#16370](https://github.com/qmk/qmk_firmware/pull/16370))
+* Update wb32-dfu ([#16438](https://github.com/qmk/qmk_firmware/pull/16438))
+* Remove `send_unicode_hex_string()` ([#16518](https://github.com/qmk/qmk_firmware/pull/16518))
+* Add :flash target for UF2 bootloaders ([#16525](https://github.com/qmk/qmk_firmware/pull/16525))
+* Move `has_mouse_report_changed` function to `report.c` ([#16543](https://github.com/qmk/qmk_firmware/pull/16543))
+* Move Doxygen docs to subdirectory ([#16561](https://github.com/qmk/qmk_firmware/pull/16561))
+* Add Caps Word feature to core ([#16588](https://github.com/qmk/qmk_firmware/pull/16588))
+* Add non blackpill F4x1 config files ([#16600](https://github.com/qmk/qmk_firmware/pull/16600))
+* Force platform pin defs to be included ([#16611](https://github.com/qmk/qmk_firmware/pull/16611))
+* Refactor CTPC logic to allow future converters ([#16621](https://github.com/qmk/qmk_firmware/pull/16621))
+* Use a mutex guard for split shared memory ([#16647](https://github.com/qmk/qmk_firmware/pull/16647))
+* Rename TICK to TICK_EVENT ([#16649](https://github.com/qmk/qmk_firmware/pull/16649))
+* Add GET_TAPPING_TERM macro to reduce duplicate code ([#16681](https://github.com/qmk/qmk_firmware/pull/16681))
+* add the ability to change the pwm frequency for the IS31FL3737B ([#16718](https://github.com/qmk/qmk_firmware/pull/16718))
+* Joystick feature updates ([#16732](https://github.com/qmk/qmk_firmware/pull/16732))
+* Add emulated eeprom support for STM32F303xE ([#16737](https://github.com/qmk/qmk_firmware/pull/16737))
+* Refactor writePin to work with statements ([#16738](https://github.com/qmk/qmk_firmware/pull/16738))
+* Add mechanism to limit available converters ([#16783](https://github.com/qmk/qmk_firmware/pull/16783))
+* Implement XAP 'secure' core requirements ([#16843](https://github.com/qmk/qmk_firmware/pull/16843))
+* rgblight: Add functions to stop blinking one or all but one layer ([#16859](https://github.com/qmk/qmk_firmware/pull/16859))
+* Expose API for hardware unique ID ([#16869](https://github.com/qmk/qmk_firmware/pull/16869))
+* Added support for Wb32fq95 ([#16871](https://github.com/qmk/qmk_firmware/pull/16871))
+* Provide better config defaults for bluepill boards ([#16909](https://github.com/qmk/qmk_firmware/pull/16909))
+* Joystick: Simplify report descriptor and clean up error messages ([#16926](https://github.com/qmk/qmk_firmware/pull/16926))
+* Rename keymap_extras headers for consistency ([#16939](https://github.com/qmk/qmk_firmware/pull/16939))
+* Sendstring keycode overhaul ([#16941](https://github.com/qmk/qmk_firmware/pull/16941))
+* Move disable_jtag to platforms ([#16960](https://github.com/qmk/qmk_firmware/pull/16960))
+* Remove ARM pgm_read_word workaround in rgblight ([#16961](https://github.com/qmk/qmk_firmware/pull/16961))
+* Warn about LTO with arm_atsam, not ChibiOS. ([#17106](https://github.com/qmk/qmk_firmware/pull/17106))
+
+CLI:
+* Rework generate-api CLI command to use .build directory ([#16441](https://github.com/qmk/qmk_firmware/pull/16441))
+* Change data driven "str" type to represent a quoted string literal ([#16516](https://github.com/qmk/qmk_firmware/pull/16516))
+* Bump the 'jsonschema' version ([#16635](https://github.com/qmk/qmk_firmware/pull/16635))
+* Add frameworking for development board presets ([#16637](https://github.com/qmk/qmk_firmware/pull/16637))
+* Extend 'qmk info' to handle keymap level overrides ([#16702](https://github.com/qmk/qmk_firmware/pull/16702))
+* Data driven `g_led_config` ([#16728](https://github.com/qmk/qmk_firmware/pull/16728))
+* Allow new-keyboard to use development_board presets ([#16785](https://github.com/qmk/qmk_firmware/pull/16785))
+* Also format *.hpp files. ([#16997](https://github.com/qmk/qmk_firmware/pull/16997))
+
+Submodule updates:
+* ChibiOS 21.11.1 update. ([#16251](https://github.com/qmk/qmk_firmware/pull/16251))
+* Update ChibiOS-Contrib ([#16915](https://github.com/qmk/qmk_firmware/pull/16915))
+
+Keyboards:
+* chore: Add personal GMMK Pro keymap ([#15320](https://github.com/qmk/qmk_firmware/pull/15320))
+* move melody96 to ymdk vendor folder ([#15680](https://github.com/qmk/qmk_firmware/pull/15680))
+* move amj keyboards into amjkeyboard vendor folder ([#15733](https://github.com/qmk/qmk_firmware/pull/15733))
+* move z150_bh at101_bh omnikey_bh to viktus/ ([#16004](https://github.com/qmk/qmk_firmware/pull/16004))
+* MS Sculpt Mobile refactor ([#16038](https://github.com/qmk/qmk_firmware/pull/16038))
+* move keyhive exclusive boards into /keyhive ([#16084](https://github.com/qmk/qmk_firmware/pull/16084))
+* move 麦田 boards into /mt ([#16095](https://github.com/qmk/qmk_firmware/pull/16095))
+* Convert Wasdat Code custom matrix to SN74x138 driver ([#16257](https://github.com/qmk/qmk_firmware/pull/16257))
+* Move GMMK Pro to allow for multiple revisions ([#16423](https://github.com/qmk/qmk_firmware/pull/16423))
+* Updated pin mapping and readme. ([#16505](https://github.com/qmk/qmk_firmware/pull/16505))
+* Map data driven `DESCRIPTION` as string literal ([#16523](https://github.com/qmk/qmk_firmware/pull/16523))
+* remove unecessary layers ([#16559](https://github.com/qmk/qmk_firmware/pull/16559))
+* Helix/rev2 move to split common ([#16723](https://github.com/qmk/qmk_firmware/pull/16723))
+* Remove some layout exceptions ([#16957](https://github.com/qmk/qmk_firmware/pull/16957))
+* Refactor legacy quantum keycodes in default-ish keymaps ([#17037](https://github.com/qmk/qmk_firmware/pull/17037))
+* Refactor legacy quantum keycodes in default-ish keymaps ([#17150](https://github.com/qmk/qmk_firmware/pull/17150))
+
+Keyboard fixes:
+* gboards/gergoplex: move `COMBO_ENABLE` to keymap level ([#16667](https://github.com/qmk/qmk_firmware/pull/16667))
+* usb-usb converter: community layout support ([#16773](https://github.com/qmk/qmk_firmware/pull/16773))
+* Fix build of `keyhive/uno`. ([#16891](https://github.com/qmk/qmk_firmware/pull/16891))
+* Fix uno ([#16892](https://github.com/qmk/qmk_firmware/pull/16892))
+* converter/usb_usb: remove surplus commas ([#17024](https://github.com/qmk/qmk_firmware/pull/17024))
+* Various fixes for g_led_config lint warnings ([#17104](https://github.com/qmk/qmk_firmware/pull/17104))
+
+Others:
+* Add warning for CTPC/CONVERT_TO_PROTON_C. ([#16782](https://github.com/qmk/qmk_firmware/pull/16782))
+* Add bluepill/blackpill development board presets ([#16806](https://github.com/qmk/qmk_firmware/pull/16806))
+* Recommend pillow as part of manual MSYS install ([#17133](https://github.com/qmk/qmk_firmware/pull/17133))
+
+Bugs:
+* Fix one-shot locked modifiers ([#16114](https://github.com/qmk/qmk_firmware/pull/16114))
+* Fix missing definition for non-encoder case. ([#16593](https://github.com/qmk/qmk_firmware/pull/16593))
+* Fixup builds. ([#16596](https://github.com/qmk/qmk_firmware/pull/16596))
+* Missed some erroneous prints. ([#16597](https://github.com/qmk/qmk_firmware/pull/16597))
+* Workaround for pin_def errors on KINETIS based builds ([#16614](https://github.com/qmk/qmk_firmware/pull/16614))
+* Fix flipped logic bug with One Shot `OS_ON` / `OS_OFF` keys ([#16617](https://github.com/qmk/qmk_firmware/pull/16617))
+* Redo workaround for pin_def errors on KINETIS ([#16620](https://github.com/qmk/qmk_firmware/pull/16620))
+* Fix oneshot toggle logic ([#16630](https://github.com/qmk/qmk_firmware/pull/16630))
+* Mousekeys fix ([#16640](https://github.com/qmk/qmk_firmware/pull/16640))
+* Ignore transport defaults if SPLIT_KEYBOARD is unset ([#16706](https://github.com/qmk/qmk_firmware/pull/16706))
+* Fixes #16705 : digital rain follows val ([#16716](https://github.com/qmk/qmk_firmware/pull/16716))
+* Fix AVR backlight breathing: low brightness limit & exceeding breathing table max index ([#16770](https://github.com/qmk/qmk_firmware/pull/16770))
+* Fixed usb read loops not reading until timeout ([#16827](https://github.com/qmk/qmk_firmware/pull/16827))
+* [QP] Check BPP capabilities before loading the palette ([#16863](https://github.com/qmk/qmk_firmware/pull/16863))
+* Fix #16859. ([#16865](https://github.com/qmk/qmk_firmware/pull/16865))
+* Preinstall python dependencies before executing `qmk`. ([#16874](https://github.com/qmk/qmk_firmware/pull/16874))
+* Fixup AVR builds. ([#16875](https://github.com/qmk/qmk_firmware/pull/16875))
+* Fix kinetic mouse mode ([#16951](https://github.com/qmk/qmk_firmware/pull/16951))
+* Enhancement and fixes of "Secure" feature ([#16958](https://github.com/qmk/qmk_firmware/pull/16958))
+* Check for ongoing transfers on the OUT endpoint ([#16974](https://github.com/qmk/qmk_firmware/pull/16974))
+* MSYS2 install: add some Python dependencies through Pacman ([#17025](https://github.com/qmk/qmk_firmware/pull/17025))
+* Revert "Fix kinetic mouse mode (#16951)" ([#17095](https://github.com/qmk/qmk_firmware/pull/17095))
+* Workaround for recent -Werror=array-bounds AVR issues ([#17136](https://github.com/qmk/qmk_firmware/pull/17136))
+* Bug fix: Continue Caps Word when AltGr (right Alt) is held. ([#17156](https://github.com/qmk/qmk_firmware/pull/17156))

docs/_summary.md

@@ -4,6 +4,7 @@
   * [Building Your First Firmware](newbs_building_firmware.md)
   * [Flashing Firmware](newbs_flashing.md)
   * [Getting Help/Support](support.md)
+  * [Building With GitHub Userspace](newbs_building_firmware_workflow.md)
   * [Other Resources](newbs_learn_more_resources.md)
   * [Syllabus](syllabus.md)
 
@@ -75,6 +76,7 @@
 
   * Software Features
     * [Auto Shift](feature_auto_shift.md)
+    * [Caps Word](feature_caps_word.md)
     * [Combos](feature_combo.md)
     * [Debounce API](feature_debounce_type.md)
     * [Key Lock](feature_key_lock.md)
@@ -83,6 +85,7 @@
     * [One Shot Keys](one_shot_keys.md)
     * [Pointing Device](feature_pointing_device.md)
     * [Raw HID](feature_rawhid.md)
+    * [Secure](feature_secure.md)
     * [Sequencer](feature_sequencer.md)
     * [Swap Hands](feature_swap_hands.md)
     * [Tap Dance](feature_tap_dance.md)
@@ -94,6 +97,7 @@
 
   * Hardware Features
     * Displays
+      * [Quantum Painter](quantum_painter.md)
       * [HD44780 LCD Driver](feature_hd44780.md)
       * [ST7565 LCD Driver](feature_st7565.md)
       * [OLED Driver](feature_oled_driver.md)
@@ -131,7 +135,7 @@
   * Breaking Changes
     * [Overview](breaking_changes.md)
     * [My Pull Request Was Flagged](breaking_changes_instructions.md)
-    * [Most Recent ChangeLog](ChangeLog/20220226.md "QMK v0.16.0 - 2022 Feb 26")
+    * [Most Recent ChangeLog](ChangeLog/20220528.md "QMK v0.17.0 - 2022 May 28")
     * [Past Breaking Changes](breaking_changes_history.md)
 
   * C Development
@@ -163,6 +167,7 @@
     * Arm/ChibiOS
       * [Selecting an MCU](platformdev_selecting_arm_mcu.md)
       * [Early initialization](platformdev_chibios_earlyinit.md)
+      * [WeAct Blackpill F411](platformdev_blackpill_f411.md)
 
   * QMK Reference
     * [Contributing to QMK](contributing.md)

docs/audio_driver.md

@@ -113,15 +113,17 @@ Additionally, in the board config, you'll want to make changes to enable the DAC
 
 ### DAC Config
 
-| Define                           | Defaults                   | Description                                                --------------------------------------------------------------------------------------------- |
+| Define                           | Defaults                   | Description                                                                                                                                                           |
+| -------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `AUDIO_DAC_SAMPLE_MAX`           | `4095U`                    | Highest value allowed. Lower value means lower volume. And 4095U is the upper limit, since this is limited to a 12 bit value. Only effects non-pregenerated samples.  |
-| `AUDIO_DAC_OFF_VALUE`            | `AUDIO_DAC_SAMPLE_MAX / 2` | The value of the DAC when notplaying anything. Some setups may require a high (`AUDIO_DAC_SAMPLE_MAX`) or low (`0`) value here.                                        |
+| `AUDIO_DAC_OFF_VALUE`            | `AUDIO_DAC_SAMPLE_MAX / 2` | The value of the DAC when notplaying anything. Some setups may require a high (`AUDIO_DAC_SAMPLE_MAX`) or low (`0`) value here.                                       |
 | `AUDIO_MAX_SIMULTANEOUS_TONES`   | __see next table__         | The number of tones that can be played simultaneously.  A value that is too high may freeze the controller or glitch out when too many tones are being played.        |
-| `AUDIO_DAC_SAMPLE_RATE`          | __see next table__         | Effective bit rate of the DAC (in hertz), higher limits simultaneous tones, and lower sacrifices quality.                                                          |
+| `AUDIO_DAC_SAMPLE_RATE`          | __see next table__         | Effective bit rate of the DAC (in hertz), higher limits simultaneous tones, and lower sacrifices quality.                                                             |
 
 There are a number of predefined quality settings that you can use, with "sane minimum" being the default.  You can use custom values by simply defining the sample rate and number of simultaneous tones, instead of using one of the listed presets. 
 
 | Define                            | Sample Rate | Simultaneous tones  |
+| --------------------------------- | ----------- | ------------------- |
 | `AUDIO_DAC_QUALITY_VERY_LOW`      | `11025U`    | `8`                 |
 | `AUDIO_DAC_QUALITY_LOW`           | `22040U`    | `4`                 |
 | `AUDIO_DAC_QUALITY_HIGH`          | `44100U`    | `2`                 |

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 May 28](ChangeLog/20220528.md)
 * [2022 Feb 26](ChangeLog/20220226.md)
 * [2021 Nov 27](ChangeLog/20211127.md)
 * [2021 Aug 28](ChangeLog/20210828.md)
@@ -21,17 +22,18 @@ 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 28, 2022.
+The next Breaking Change is scheduled for August 27, 2022.
 
 ### Important Dates
 
-* [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.
+* 2022 May 28 - `develop` is tagged with a new release version. Each push to `master` is subsequently merged to `develop` by GitHub actions.
+* 2022 Jul 31 - `develop` closed to new PR's.
+* 2022 Jul 31 - Call for testers.
+* 2022 Aug 13 - Last day for merges -- after this point `develop` is locked for testing and accepts only bugfixes
+* 2022 Aug 20 - `develop` is locked, only critical bugfix PR's merged.
+* 2022 Aug 25 - `master` is locked, no PR's merged.
+* 2022 Aug 27 - Merge `develop` to `master`.
+* 2022 Aug 27 - `master` is unlocked. PR's can be merged again.
 
 ## What changes will be included?
 
@@ -42,80 +44,128 @@ If you want your breaking change to be included in this round you need to create
 Criteria for acceptance:
 
 * The PR is complete and ready to merge
-* The PR has a ChangeLog file describing the changes under `<qmk_firmware>/docs/Changelog/20220226`.
+* The PR has a ChangeLog file describing the changes under `<qmk_firmware>/docs/Changelog/20220827`.
     * This should be in Markdown format, with a name in the format `PR12345.md`, substituting the digits for your PR's ID.
     * One strong recommendation that the ChangeLog document matches the PR description on GitHub, so as to ensure traceability.
 
-# Checklists
+## Checklists
 
 This section documents various processes we use when running the Breaking Changes process.
 
-## Creating the `develop` branch
-
-This happens immediately after the previous `develop` branch is merged.
-
-* `qmk_firmware` git commands
-    * [ ] `git checkout master`
-    * [ ] `git pull --ff-only`
-    * [ ] `git checkout -b develop`
-    * [ ] Edit `readme.md`
-        * [ ] Add a big notice at the top that this is a testing branch.
-        * [ ] Include a link to this document
-    * [ ] `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 upstream develop`
-    * [ ] `git push --tags`
-
-## 4 Weeks Before Merge
+### 4 Weeks Before Merge
 
 * `develop` is now closed to new PR's, only fixes for current PR's may be merged
-* Post call for testers
-    * [ ] Discord
-    * [ ] GitHub PR
-    * [ ] https://reddit.com/r/olkb
+* Post call for testers: message `@Breaking Changes Updates` on `#qmk_firmware` in Discord:
+    * `@Breaking Changes Updates -- Hey folks, last day for functional PRs to be raised against qmk_firmware for this breaking changes cycle is today.`
 
-## 2 Weeks Before Merge
+### 2 Weeks Before Merge
 
 * `develop` is now closed to existing PR merges, only bugfixes for previous merges may be included
-* Post call for testers
-    * [ ] Discord
-    * [ ] GitHub PR
-    * [ ] https://reddit.com/r/olkb
+* Post call for testers: message `@Breaking Changes Updates` on `#qmk_firmware` in Discord.
+    * `@Breaking Changes Updates -- Hey folks, last day for functional PRs to be merged into qmk_firmware for this breaking changes cycle is today. After that, we're handling bugfixes only.`
 
-## 1 Week Before Merge
+### 1 Week Before Merge
 
-* Announce that master will be closed from <2 Days Before> to <Day of Merge>
-    * [ ] Discord
-    * [ ] GitHub PR
-    * [ ] https://reddit.com/r/olkb
+* `develop` is now closed to PR merges, only critical bugfixes may be included
+* Announce that master will be closed from <2 Days Before> to <Day of Merge> -- message `@Breaking Changes Updates` on `#qmk_firmware` in Discord:
+    * `@Breaking Changes Updates -- Hey folks, last day for functional PRs to be merged into qmk_firmware for this breaking changes cycle is today. After that, we're handling bugfixes only.`
 
-## 2 Days Before Merge
+### 2 Days Before Merge
 
+* `master` is now closed to PR merges
 * Announce that master is closed for 2 days
-    * [ ] Discord
-    * [ ] GitHub PR
-    * [ ] https://reddit.com/r/olkb
+    * `@Breaking Changes Updates -- Hey folks, the master branch of qmk_firmware is now locked for the next couple of days while we prepare to merge the newest batch of changes from develop.`
 
-## Day Of Merge
+### Day Of Merge
 
 * `qmk_firmware` git commands
-    * [ ] `git checkout develop`
-    * [ ] `git pull --ff-only`
-    * [ ] 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 upstream develop`
+    * `git checkout develop`
+    * `git pull --ff-only`
+    * 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 upstream develop`
 * GitHub Actions
-    * [ ] Create a PR for `develop`
-    * [ ] **Turn off 'Automatically delete head branches' for the repository** -- confirm with @qmk/directors that it is done before continuing
+    * Create a PR for `develop`
+    * **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`
+    * `git checkout master`
+    * `git pull --ff-only`
+    * `git merge --no-ff develop`
+    * `git tag <next_version>` # Prevent the breakpoint tag from confusing version incrementing
+    * `git push upstream <next_version>`
+    * `git push upstream master`
 
 ## Post-merge operations
 
+### Updating the `develop` branch
+
+This happens immediately after the previous `develop` branch is merged to `master`.
+
+* `qmk_firmware` git commands
+    * `git checkout master`
+    * `git pull --ff-only`
+    * `git checkout develop`
+    * `git pull --ff-only`
+    * `git merge --no-ff master`
+    * Edit `readme.md`
+        * Add a big notice at the top that this is a testing branch.
+        * Include a link to this document
+    * `git commit -m 'Branch point for <DATE> Breaking Change'`
+    * `git tag breakpoint_<YYYY>_<MM>_<DD>`
+    * `git push upstream breakpoint_<YYYY>_<MM>_<DD>`
+
+* All submodules under `lib` now need to be checked against their QMK-based forks:
+    * `git submodule foreach git log -n1`
+    * Validate each submodule SHA1 matches the qmk fork, e.g. for ChibiOS:
+        * Go to [qmk/ChibiOS](https://github.com/qmk/ChibiOS)
+        * Compare the commit hash in the above output to the commit hash in the repository
+        * If there's a mismatch:
+            * `cd lib/chibios`
+            * `git fetch --all`
+            * `git checkout master`
+            * `git reset --hard <commit hash>`
+            * `git push origin master --force-with-lease`
+
 * (Optional) [update ChibiOS + ChibiOS-Contrib on `develop`](chibios_upgrade_instructions.md)
+
+### Set up Discord events for the next cycle
+
+* Update this file with the new dates: `docs/breaking_changes.md`
+* Create Events on the QMK Discord - "Somewhere Else" => "GitHub":
+    * Event #1:
+        | Field       | Value                                                                                                                                                                                                                 |
+        |-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+        | Topic       | Last `develop` functionality PRs to be raised                                                                                                                                                                         |
+        | Start Date  | ((5 weeks before merge)), 12:00am                                                                                                                                                                                     |
+        | End Date    | ((4 weeks before merge)), 12:00am                                                                                                                                                                                     |
+        | Description | This is the last window for functional PRs to be raised against `develop` for the current breaking changes cycle. After ((4 weeks before merge)), any new PRs targeting `develop` will be deferred to the next cycle. |
+    * Event #2:
+        | Field       | Value                                                                                                                                                                                                            |
+        |-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+        | Topic       | Last `develop` functionality PRs to be merged                                                                                                                                                                    |
+        | Start Date  | ((4 weeks before merge)), 12:00am                                                                                                                                                                                |
+        | End Date    | ((2 weeks before merge)), 12:00am                                                                                                                                                                                |
+        | Description | This is the last window for functional PRs to be merged into `develop` for the current breaking changes cycle. After ((2 weeks before merge)), only bugfix PRs targeting `develop` will be considered for merge. |
+    * Event #3:
+        | Field       | Value                                                                                                                                                                                                                           |
+        |-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+        | Topic       | `develop` closed for merges                                                                                                                                                                                                     |
+        | Start Date  | ((2 weeks before merge)), 12:00am                                                                                                                                                                                               |
+        | End Date    | ((day of merge)), 12:00am                                                                                                                                                                                                       |
+        | Description | This is the deadline for functionality bugfix PRs to be merged into `develop` for the current breaking changes cycle. After ((1 week before merge)), only critical bugfix PRs targeting `develop` will be considered for merge. |
+    * Event #4:
+        | Field       | Value                                                                                                                |
+        |-------------|----------------------------------------------------------------------------------------------------------------------|
+        | Topic       | `master` closed for merges                                                                                           |
+        | Start Date  | ((2 days before merge)), 12:00am                                                                                     |
+        | End Date    | ((day of merge)), 12:00am                                                                                            |
+        | Description | This is the period that no PRs are to be merged to `master`, so that the merge of `develop` into `master` is stable. |
+    * Event #5:
+        | Field       | Value                                                                                                                                      |
+        |-------------|--------------------------------------------------------------------------------------------------------------------------------------------|
+        | Topic       | `develop` merges to `master`                                                                                                               |
+        | Start Date  | ((day of merge)), 12:00am                                                                                                                  |
+        | End Date    | ((day of merge)), 11:45pm                                                                                                                  |
+        | Description | At some point, QMK will merge `develop` into `master` and everyone will be able to reap the benefits of the newest batch of functionality. |

docs/breaking_changes_history.md

@@ -2,6 +2,7 @@
 
 This page links to all previous changelogs from the QMK Breaking Changes process.
 
+* [2022 May 28](ChangeLog/20220528.md) - version 0.17.0
 * [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

docs/cli_commands.md

@@ -515,3 +515,15 @@ Run single test:
 
     qmk pytest -t qmk.tests.test_cli_commands.test_c2json
     qmk pytest -t qmk.tests.test_qmk_path
+
+## `qmk painter-convert-graphics`
+
+This command converts images to a format usable by QMK, i.e. the QGF File Format. See the [Quantum Painter](quantum_painter.md?id=quantum-painter-cli) documentation for more information on this command.
+
+## `qmk painter-make-font-image`
+
+This command converts a TTF font to an intermediate format for editing, before converting to the QFF File Format. See the [Quantum Painter](quantum_painter.md?id=quantum-painter-cli) documentation for more information on this command.
+
+## `qmk painter-convert-font-image`
+
+This command converts an intermediate font image to the QFF File Format. See the [Quantum Painter](quantum_painter.md?id=quantum-painter-cli) documentation for more information on this command.

docs/cli_tab_complete.md

@@ -14,6 +14,10 @@ Add this to the end of your `.profile` or `.bashrc`:
 
 If you put `qmk_firmware` into another location you will need to adjust this path.
 
+Zsh users will need to load `bashcompinit`. The following can be added to `~/.zshrc` file:
+
+    autoload -Uz bashcompinit && bashcompinit
+
 ### System Wide Symlink
 
 If you want the tab completion available to all users of the system you can add a symlink to the `qmk_tab_complete.sh` script:

docs/compatible_microcontrollers.md

@@ -2,6 +2,8 @@
 
 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.
 
+Features within QMK may or may not be compatible with every microcontroller.
+
 ## Atmel AVR
 
 The following use [LUFA](https://www.fourwalledcubicle.com/LUFA.php) as the USB stack:
@@ -51,6 +53,7 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s
 ### WestBerryTech (WB32)
 
  * [WB32F3G71xx](http://www.westberrytech.com)
+ * [WB32FQ95xx](http://www.westberrytech.com)
 
 ### NXP (Kinetis)
 

docs/custom_quantum_functions.md

@@ -406,11 +406,11 @@ And you're done.  The RGB layer indication will only work if you want it to. And
 
 The `val` is the value of the data that you want to write to EEPROM.  And the `eeconfig_read_*` function return a 32 bit (DWORD) value from the EEPROM. 
 
-### Deferred Execution :id=deferred-execution
+# 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. To enable this functionality, set `DEFERRED_EXEC_ENABLE = yes` in rules.mk.
 
-#### Deferred executor callbacks
+## Deferred executor callbacks
 
 All _deferred executor callbacks_ have a common function signature and look like:
 
@@ -430,7 +430,7 @@ The return value is the number of milliseconds to use if the function should be
 
 ?> Note that the returned delay will be applied to the intended trigger time, not the time of callback invocation. This allows for generally consistent timing even in the face of occasional late execution.
 
-#### Deferred executor registration
+## Deferred executor registration
 
 Once a callback has been defined, it can be scheduled using the following API:
 
@@ -444,7 +444,7 @@ The third parameter is the `cb_arg` that gets passed to the callback at the poin
 
 The return value is a `deferred_token` that can consequently be used to cancel the deferred executor callback before it's invoked. If a failure occurs, the returned value will be `INVALID_DEFERRED_TOKEN`. Usually this will be as a result of supplying `0` to the delay, or a `NULL` for the callback. The other failure case is if there are too many deferred executions "in flight" -- this can be increased by changing the limit, described below.
 
-#### Extending a deferred execution
+## Extending a deferred execution
 
 The `deferred_token` returned by `defer_exec()` can be used to extend a the duration a pending execution waits before it gets invoked:
 ```c
@@ -452,7 +452,7 @@ The `deferred_token` returned by `defer_exec()` can be used to extend a the dura
 extend_deferred_exec(my_token, 800);
 ```
 
-#### Cancelling a deferred execution
+## Cancelling a deferred execution
 
 The `deferred_token` returned by `defer_exec()` can be used to cancel a pending execution before it gets invoked:
 ```c
@@ -462,7 +462,7 @@ cancel_deferred_exec(my_token);
 
 Once a token has been canceled, it should be considered invalid. Reusing the same token is not supported.
 
-#### Deferred callback limits
+## Deferred callback limits
 
 There are a maximum number of deferred callbacks that can be scheduled, controlled by the value of the define `MAX_DEFERRED_EXECUTORS`.
 

docs/data_driven_config.md

@@ -22,7 +22,7 @@ You will then need to add support for your new configuration to `info.json`. The
 
 1. Add it to the schema in `data/schemas/keyboards.jsonschema`
 1. Add a mapping in `data/maps`
-1. (optional and discoraged) Add code to extract/generate it to:
+1. (optional and discouraged) Add code to extract/generate it to:
   * `lib/python/qmk/info.py`
   * `lib/python/qmk/cli/generate/config_h.py`
   * `lib/python/qmk/cli/generate/rules_mk.py`

docs/faq_keymap.md

@@ -3,6 +3,7 @@
 This page covers questions people often have about keymaps. If you haven't you should read [Keymap Overview](keymap.md) first.
 
 ## What Keycodes Can I Use?
+
 See [Keycodes](keycodes.md) for an index of keycodes available to you. These link to more extensive documentation when available.
 
 Keycodes are actually defined in [quantum/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/keycode.h).
@@ -25,25 +26,30 @@ Sometimes, for readability's sake, it's useful to define custom names for some k
 
 This will allow you to use `FN_CAPS` and `ALT_TAB` in your keymap, keeping it more readable.
 
+## My Keymap Doesn't Update When I Flash It
+
+This is usually due to VIA, and has to do with how it deals with keymaps.
+
+On first run, the VIA code in the firmware will copy the keymap from flash memory into EEPROM so that it can be rewritten at runtime by the VIA app. From this point QMK will use the keymap stored in EEPROM instead of flash, and so updates to your `keymap.c` will not be reflected.
+
+The simple fix for this is to clear the EEPROM. You can do this in several ways:
+
+* Hold the Bootmagic Lite key (usually top left/Escape) while plugging the board in, which will also place the board into bootloader mode; then unplug and replug the board.
+* Press the `QK_CLEAR_EEPROM`/`EE_CLR` keycode if it is accessible on your keymap.
+* Place the board into bootloader mode and hit the "Clear EEPROM" button. This may not be available for all bootloaders, and you may need to reflash the board afterwards.
+
 ## Some Of My Keys Are Swapped Or Not Working
 
-QMK has two features, Bootmagic and Command, which allow you to change the behavior of your keyboard on the fly. This includes, but is not limited to, swapping Ctrl/Caps, disabling Gui, swapping Alt/Gui, swapping Backspace/Backslash, disabling all keys, and other behavioral modifications. 
+QMK has a couple of features which allow you to change the behavior of your keyboard on the fly. This includes, but is not limited to, swapping Ctrl/Caps, disabling GUI, swapping Alt/GUI, swapping Backspace/Backslash, disabling all keys, and other behavioral modifications.
 
-As a quick fix try holding down `Space`+`Backspace` while you plug in your keyboard. This will reset the stored settings on your keyboard, returning those keys to normal operation. If that doesn't work look here:
+Refer to the EEPROM clearing methods above, which should return those keys to normal operation. If that doesn't work, look here:
 
-* [Bootmagic Lite](feature_bootmagic.md)
-* [Command](feature_command.md) 
+* [Magic Keycodes](keycodes_magic.md)
+* [Command](feature_command.md)
 
 ## The Menu Key Isn't Working
 
-The key found on most modern keyboards that is located between `KC_RGUI` and `KC_RCTL` is actually called `KC_APP`. This is because when that key was invented there was already a key named `MENU` in the relevant standards, so MS chose to call that the `APP` key.
-
-## `KC_SYSTEM_REQUEST` Isn't Working
-Use keycode for Print Screen (`KC_PRINT_SCREEN`/`KC_PSCR`) instead of `KC_SYSTEM_REQUEST`. Key combination of 'Alt + Print Screen' is recognized as 'System request'.
-
-See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and
-* https://en.wikipedia.org/wiki/Magic_SysRq_key
-* https://en.wikipedia.org/wiki/System_request
+The key found on most modern keyboards that is located between `KC_RGUI` and `KC_RCTL` is actually called `KC_APP`. This is because when the key was invented, there was already a key named "Menu" in the HID specification, so for whatever reason, Microsoft chose to create a new key and call it "Application".
 
 ## Power Keys Aren't Working
 
@@ -52,10 +58,12 @@ Somewhat confusingly, there are two "Power" keycodes in QMK: `KC_KB_POWER` in th
 The former is only recognized on macOS, while the latter, `KC_SLEP` and `KC_WAKE` are supported by all three major operating systems, so it is recommended to use those instead. Under Windows, these keys take effect immediately, however on macOS they must be held down until a dialog appears.
 
 ## One Shot Modifier
+
 Solves my personal 'the' problem. I often got 'the' or 'THe' wrongly instead of 'The'.  One Shot Shift mitigates this for me.
 https://github.com/tmk/tmk_keyboard/issues/67
 
 ## Modifier/Layer Stuck
+
 Modifier keys or layers can be stuck unless layer switching is configured properly.
 For Modifier keys and layer actions you have to place `KC_TRNS` on same position of destination layer to  unregister the modifier key or return to previous layer on release event.
 
@@ -63,12 +71,11 @@ For Modifier keys and layer actions you have to place `KC_TRNS` on same position
 * https://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
 * https://github.com/tmk/tmk_keyboard/issues/248
 
-
 ## Mechanical Lock Switch Support
 
 This feature is for *mechanical lock switch* like [this Alps one](https://deskthority.net/wiki/Alps_SKCL_Lock). You can enable it by adding this to your `config.h`:
 
-```
+```c
 #define LOCKING_SUPPORT_ENABLE
 #define LOCKING_RESYNC_ENABLE
 ```
@@ -91,6 +98,7 @@ Even worse, it is not recognized unless the keyboard's VID and PID match that of
 See [this issue](https://github.com/qmk/qmk_firmware/issues/2179) for detailed information.
 
 ## Keys Supported in Mac OSX?
+
 You can know which keycodes are supported in OSX from this source code.
 
 `usb_2_adb_keymap` array maps Keyboard/Keypad Page usages to ADB scancodes(OSX internal keycodes).
@@ -101,8 +109,8 @@ And `IOHIDConsumer::dispatchConsumerEvent` handles Consumer page usages.
 
 https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp
 
-
 ## JIS Keys in Mac OSX
+
 Japanese JIS keyboard specific keys like `無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)` are not recognized on OSX. You can use **Seil** to enable those keys, try following options.
 
 * Enable NFER Key on PC keyboard
@@ -111,8 +119,8 @@ Japanese JIS keyboard specific keys like `無変換(Muhenkan)`, `変換(Henkan)`
 
 https://pqrs.org/osx/karabiner/seil.html
 
-
 ## RN-42 Bluetooth Doesn't Work with Karabiner
+
 Karabiner - Keymapping tool on Mac OSX - ignores inputs from RN-42 module by default. You have to enable this option to make Karabiner working with your keyboard.
 https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237
 
@@ -120,37 +128,24 @@ See these for the detail of this problem.
 https://github.com/tmk/tmk_keyboard/issues/213
 https://github.com/tekezo/Karabiner/issues/403
 
-
 ## Esc and <code>&#96;</code> on a Single Key
 
 See the [Grave Escape](feature_grave_esc.md) feature.
 
 ## Eject on Mac OSX
+
 `KC_EJCT` keycode works on OSX. https://github.com/tmk/tmk_keyboard/issues/250
 It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default.
 
-Not sure what keycode Eject is on genuine Apple keyboard actually. HHKB uses `F20` for Eject key(`Fn+f`) on Mac mode but this is not same as Apple Eject keycode probably.
+Not sure what keycode Eject is on genuine Apple keyboard actually. HHKB uses `F20` for Eject key(`Fn+F`) on Mac mode but this is not same as Apple Eject keycode probably.
 
+## What are "Real" and "Weak" modifiers?
 
-## What's `weak_mods` and `real_mods` in `action_util.c`
-___TO BE IMPROVED___
+Real modifiers refer to the state of the real/physical modifier keys, while weak modifiers are the state of "virtual" or temporary modifiers which should not interfere with the internal state of the real modifier keys.
 
-real_mods is intended to retains state of real/physical modifier key state, while
-weak_mods retains state of virtual or temporary modifiers which should not affect state real modifier key.
+The real and weak modifier states are ORed together when the keyboard report is sent, so if you release a weak modifier while the same real modifier is still held, the report does not change:
 
-Let's say you hold down physical left shift key and type ACTION_MODS_KEY(LSHIFT, KC_A),
-
-with weak_mods,
-* (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
-* (2) press ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT)
-* (3) release ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods &= ~MOD_BIT(LSHIFT)
-real_mods still keeps modifier state.
-
-without weak mods,
-* (1) hold down left shift: real_mods |= MOD_BIT(LSHIFT)
-* (2) press ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT)
-* (3) release ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT)
-here real_mods lost state for 'physical left shift'.
-
-weak_mods is ORed with real_mods when keyboard report is sent.
-https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57
+ 1. **Hold down physical Left Shift:** Real mods now contains Left Shift, final state is Left Shift
+ 2. **Add weak Left Shift:** Weak mods now contains Left Shift, final state is Left Shift
+ 3. **Remove weak Left Shift:** Weak mods now contains nothing, final state is Left Shift
+ 4. **Release physical Left Shift:** Real mods now contains nothing, final state is nothing

docs/feature_advanced_keycodes.md

@@ -39,7 +39,7 @@ In practice, this means that you can check whether a given modifier is active wi
 
 To check that *only* a specific set of mods is active at a time, AND the modifier state and your desired mod mask as explained above and compare the result to the mod mask itself: `get_mods() & <mod mask> == <mod mask>`.
 
-For example, let's say you want to trigger a piece of custom code if one-shot left control and one-shot left shift are on but every other one-shot mods are off. To do so, you can compose the desired mod mask by combining the mod bits for left control and shift with `(MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT))` and then plug it in: `get_oneshot_mods & (MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT)) == (MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT))`. Using `MOD_MASK_CS` instead for the mod bitmask would have forced you to press four modifier keys (both versions of control and shift) to fulfill the condition.
+For example, let's say you want to trigger a piece of custom code if one-shot left control and one-shot left shift are on but every other one-shot mods are off. To do so, you can compose the desired mod mask by combining the mod bits for left control and shift with `(MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT))` and then plug it in: `get_oneshot_mods() & (MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT)) == (MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT))`. Using `MOD_MASK_CS` instead for the mod bitmask would have forced you to press four modifier keys (both versions of control and shift) to fulfill the condition.
 
 The full list of mod masks is as follows:
 

docs/feature_caps_word.md

@@ -0,0 +1,156 @@
+# Caps Word
+
+It is often useful to type a single word in all capitals, for instance
+abbreviations like "QMK", or in code, identifiers like `KC_SPC`. "Caps Word" is
+a modern alternative to Caps Lock:
+
+* Letters are capitalized while active, and Caps Word automatically disables
+  itself at the end of the word. That is, it stops by default once a space or
+  any key other than `a`--`z`, `0`--`9`, `-`, `_`, delete, or backspace is
+  pressed. Caps Word also disables itself if the keyboard is idle for 5 seconds.
+  This is configurable, see below.
+
+* To avoid requiring a dedicated key for Caps Word, there is an option
+  (`BOTH_SHIFTS_TURNS_ON_CAPS_WORD`) to activate Caps Word by simultaneously
+  pressing both shift keys. See below for other options.
+
+* The implementation does not use the Caps Lock (`KC_CAPS`) keycode. Caps Word
+  works even if you're remapping Caps Lock at the OS level to Ctrl or something
+  else, as Emacs and Vim users often do.
+
+
+## How do I enable Caps Word :id=how-do-i-enable-caps-word
+
+In your `rules.mk`, add:
+
+```make
+CAPS_WORD_ENABLE = yes
+```
+
+Next, use one the following methods to activate Caps Word:
+
+* **Activate by pressing a key**: Use the `CAPS_WORD` keycode (short
+  alias `CAPSWRD`) in your keymap.
+
+* **Activate by pressing Left Shift + Right Shift**: Add `#define
+  BOTH_SHIFTS_TURNS_ON_CAPS_WORD` to config.h. You may also need to disable or
+  reconfigure Command, details below. Then, simultaneously pressing both left
+  and right shifts turns on Caps Word. This method works with the plain
+  `KC_LSFT` and `KC_RSFT` keycodes as well as one-shot shifts and Space Cadet
+  shifts. If your shift keys are mod-taps, hold both shift mod-tap keys until
+  the tapping term, then release them.
+
+* **Activate by double tapping Left Shift**: Add `#define
+  DOUBLE_TAP_SHIFT_TURNS_ON_CAPS_WORD` config.h. Then, double tapping Left Shift
+  turns on Caps Word. This method works with `KC_LSFT` or one-shot Left Shift
+  `OSM(MOD_LSFT)`. To count as a double tap, the maximum time in milliseconds
+  between taps is `TAPPING_TERM`, or if using `TAPPING_TERM_PER_KEY`, the time
+  returned by `get_tapping_term()` for the shift keycode being tapped.
+
+* **Custom activation**: You can activate Caps Word from code by calling
+  `caps_word_on()`. This may be used to activate Caps Word through [a
+  combo](feature_combo.md) or [tap dance](feature_tap_dance.md) or any means
+  you like.
+
+### Troubleshooting: Command :id=troubleshooting-command
+
+When using `BOTH_SHIFTS_TURNS_ON_CAPS_WORD`, you might see a compile message
+**"BOTH_SHIFTS_TURNS_ON_CAPS_WORD and Command should not be enabled at the same
+time, since both use the Left Shift + Right Shift key combination."**
+
+Many keyboards enable the [Command feature](feature_command.md), which by
+default is also activated using the Left Shift + Right Shift key combination. To
+fix this conflict, please disable Command by adding in rules.mk: 
+
+```make
+COMMAND_ENABLE = no
+```
+
+Or configure Command to use another key combination like Left Ctrl + Right Ctrl
+by defining `IS_COMMAND()` in config.h:
+
+```c
+// Activate Command with Left Ctrl + Right Ctrl.
+#define IS_COMMAND() (get_mods() == MOD_MASK_CTRL)
+```
+
+
+## Customizing Caps Word :id=customizing-caps-word
+
+### Idle timeout :id=idle-timeout
+
+Caps Word turns off automatically if no keys are pressed for
+`CAPS_WORD_IDLE_TIMEOUT` milliseconds. The default is 5000 (5 seconds).
+Configure the timeout duration in config.h, for instance 
+
+```c
+#define CAPS_WORD_IDLE_TIMEOUT 3000  // 3 seconds.
+```
+
+Setting `CAPS_WORD_IDLE_TIMEOUT` to 0 configures Caps Word to never time out.
+Caps Word then remains active indefinitely until a word breaking key is pressed.
+
+
+### Functions :id=functions
+
+Functions to manipulate Caps Word:
+
+| Function                | Description                                    |
+|-------------------------|------------------------------------------------|
+| `caps_word_on()`        | Turns Caps Word on.                            |
+| `caps_word_off()`       | Turns Caps Word off.                           |
+| `caps_word_toggle()`    | Toggles Caps Word.                             |
+| `is_caps_word_on()`     | Returns true if Caps Word is currently on.     |
+
+
+### Configure which keys are "word breaking" :id=configure-which-keys-are-word-breaking
+
+You can define the `caps_word_press_user(uint16_t keycode)` callback to
+configure which keys should be shifted and which keys are considered "word
+breaking" and stop Caps Word.
+
+The callback is called on every key press while Caps Word is active. When the
+key should be shifted (that is, a letter key), the callback should call
+`add_weak_mods(MOD_BIT(KC_LSFT))` to shift the key. Returning true continues the
+current "word," while returning false is "word breaking" and deactivates Caps
+Word. The default callback is
+
+```c
+bool caps_word_press_user(uint16_t keycode) {
+    switch (keycode) {
+        // Keycodes that continue Caps Word, with shift applied.
+        case KC_A ... KC_Z:
+        case KC_MINS:
+            add_weak_mods(MOD_BIT(KC_LSFT));  // Apply shift to next key.
+            return true;
+
+        // Keycodes that continue Caps Word, without shifting.
+        case KC_1 ... KC_0:
+        case KC_BSPC:
+        case KC_DEL:
+        case KC_UNDS:
+            return true;
+
+        default:
+            return false;  // Deactivate Caps Word.
+    }
+}
+```
+
+
+### Representing Caps Word state :id=representing-caps-word-state
+
+Define `caps_word_set_user(bool active)` to get callbacks when Caps Word turns
+on or off. This is useful to represent the current Caps Word state, e.g. by
+setting an LED or playing a sound. In your keymap, define
+
+```c
+void caps_word_set_user(bool active) {
+    if (active) {
+        // Do something when Caps Word activates.
+    } else {
+        // Do something when Caps Word deactivates.
+    }
+}
+```
+

docs/feature_combo.md

@@ -326,7 +326,7 @@ bool process_combo_key_release(uint16_t combo_index, combo_t *combo, uint8_t key
 
 If you, for example, use multiple base layers for different key layouts, one for QWERTY, and another one for Colemak, you might want your combos to work from the same key positions on all layers. Defining the same combos again for another layout is redundant and takes more memory. The solution is to just check the keycodes from one layer.
 
-With `#define COMBO_ONLY_FROM_LAYER _LAYER_A` the combos' keys are always checked from layer `_LAYER_A` even though the active layer would be `_LAYER_B`.
+With `#define COMBO_ONLY_FROM_LAYER 0` in config.h, the combos' keys are always checked from layer `0`, even if other layers are active.
 
 ## User callbacks
 

docs/feature_encoders.md

@@ -67,7 +67,7 @@ Additionally, if one side does not have an encoder, you can specify `{}` for the
 #define ENCODER_RESOLUTIONS_RIGHT { 4 }
 ```
 
-## Encoder map
+## Encoder map :id=encoder-map
 
 Encoder mapping may be added to your `keymap.c`, which replicates the normal keyswitch layer handling functionality, but with encoders. Add this to your `rules.mk`:
 
@@ -125,34 +125,37 @@ Layer conditions can also be used with the callback function like the following:
 
 ```c
 bool encoder_update_user(uint8_t index, bool clockwise) {
-    if (get_highest_layer(layer_state|default_layer_state) > 0) {
-        if (index == 0) {
-            if (clockwise) {
-                tap_code(KC_WH_D);
-            } else {
-                tap_code(KC_WH_U);
+    switch(get_highest_layer(layer_state|default_layer_state)) {
+        case 0:
+            if (index == 0) {
+                if (clockwise) {
+                    tap_code(KC_PGDN);
+                } else {
+                    tap_code(KC_PGUP);
+                }
+            } else if (index == 1) {
+                if (clockwise) {
+                    rgb_matrix_increase_speed();
+                } else {
+                    rgb_matrix_decrease_speed();
+                }
             }
-        } else if (index == 1) {
-            if (clockwise) {
-                tap_code_delay(KC_VOLU, 10);
-            } else {
-                tap_code_delay(KC_VOLD, 10);
+            break;
+        case 1:
+            if (index == 0) {
+                if (clockwise) {
+                    tap_code(KC_WH_D);
+                } else {
+                    tap_code(KC_WH_U);
+                }
+            } else if (index == 1) {
+                if (clockwise) {
+                    tap_code_delay(KC_VOLU, 10);
+                } else {
+                    tap_code_delay(KC_VOLD, 10);
+                }
             }
-        }
-    } else {  /* Layer 0 */
-        if (index == 0) {
-            if (clockwise) {
-                tap_code(KC_PGDN);
-            } else {
-                tap_code(KC_PGUP);
-            }
-        } else if (index == 1) {
-            if (clockwise) {
-                rgb_matrix_increase_speed();
-            } else {
-                rgb_matrix_decrease_speed();
-            }
-        }
+            break;
     }
     return false;
 }

docs/feature_haptic_feedback.md

@@ -50,22 +50,28 @@ Not all keycodes below will work depending on which haptic mechanism you have ch
 
 ### Solenoids
 
-First you will need a build a circuit to drive the solenoid through a mosfet as most MCU will not be able to provide the current needed to drive the coil in the solenoid.
+The solenoid code supports relay switches, and similar hardware, as well as solenoids. 
+
+For a regular solenoid,  you will need a build a circuit to drive the solenoid through a mosfet as most MCU will not be able to provide the current needed to drive the coil in the solenoid.
 
 [Wiring diagram provided by Adafruit](https://cdn-shop.adafruit.com/product-files/412/solenoid_driver.pdf)
 
+For relay switches, the hardware may already contain all of that ciruitry, and just require VCC, GND and a data pin.
 
-| Settings                   | Default              | Description                                           |
-|----------------------------|----------------------|-------------------------------------------------------|
-|`SOLENOID_PIN`              | *Not defined*        |Configures the pin that the Solenoid is connected to.  |
-|`SOLENOID_PIN_ACTIVE_LOW`   | *Not defined*        |If defined then the solenoid trigger pin is active low.|
-|`SOLENOID_DEFAULT_DWELL`    | `12` ms              |Configures the default dwell time for the solenoid.    |
-|`SOLENOID_MIN_DWELL`        | `4` ms               |Sets the lower limit for the dwell.                    |
-|`SOLENOID_MAX_DWELL`        | `100` ms             |Sets the upper limit for the dwell.                    |
-|`SOLENOID_DWELL_STEP_SIZE`  | `1` ms               |The step size to use when `HPT_DWL*` keycodes are sent |
-|`SOLENOID_DEFAULT_BUZZ`     | `0` (disabled)       |On HPT_RST buzz is set "on" if this is "1"             |
-|`SOLENOID_BUZZ_ACTUATED`    | `SOLENOID_MIN_DWELL` |Actuated-time when the solenoid is in buzz mode        |
-|`SOLENOID_BUZZ_NONACTUATED` | `SOLENOID_MIN_DWELL` |Non-Actuated-time when the solenoid is in buzz mode    |
+| Settings                   | Default              | Description                                                  |
+|----------------------------|----------------------|--------------------------------------------------------------|
+|`SOLENOID_PIN`              | *Not defined*        |Configures the pin that the switch  is connected to.          |
+|`SOLENOID_PIN_ACTIVE_LOW`   | *Not defined*        |If defined then the switch trigger pin is active low.         |
+|`SOLENOID_PINS`             | *Not defined*        |Configures an array of pins to be used for switch activation. |
+|`SOLENOID_PINS_ACTIVE_LOW`  | *Not defined*        |Allows you to specify how each pin is pulled for activation.  |
+|`SOLENOID_RANDOM_FIRE`      | *Not defined*        |When there are multiple solenoids, will select a random one to fire.|
+|`SOLENOID_DEFAULT_DWELL`    | `12` ms              |Configures the default dwell time for the switch.             |
+|`SOLENOID_MIN_DWELL`        | `4` ms               |Sets the lower limit for the dwell.                           |
+|`SOLENOID_MAX_DWELL`        | `100` ms             |Sets the upper limit for the dwell.                           |
+|`SOLENOID_DWELL_STEP_SIZE`  | `1` ms               |The step size to use when `HPT_DWL*` keycodes are sent.       |
+|`SOLENOID_DEFAULT_BUZZ`     | `0` (disabled)       |On HPT_RST buzz is set "on" if this is "1"                    |
+|`SOLENOID_BUZZ_ACTUATED`    | `SOLENOID_MIN_DWELL` |Actuated-time when the switch is in buzz mode.                |
+|`SOLENOID_BUZZ_NONACTUATED` | `SOLENOID_MIN_DWELL` |Non-Actuated-time when the switch is in buzz mode.            |
 
 * If solenoid buzz is off, then dwell time is how long the "plunger" stays activated. The dwell time changes how the solenoid sounds.
 * If solenoid buzz is on, then dwell time sets the length of the buzz, while `SOLENOID_BUZZ_ACTUATED` and `SOLENOID_BUZZ_NONACTUATED` set the (non-)actuation times withing the buzz period.

docs/feature_joystick.md

@@ -150,3 +150,5 @@ Note that the supported AVR MCUs have a 10-bit ADC, and 12-bit for most STM32 MC
 
 Joystick buttons are normal Quantum keycodes, defined as `JS_BUTTON0` to `JS_BUTTON31`, depending on the number of buttons you have configured.
 To trigger a joystick button, just add the corresponding keycode to your keymap.
+
+You can also trigger joystick buttons in code with `register_joystick_button(button)` and `unregister_joystick_button(button)`, where `button` is the 0-based button index (0 = button 1).

docs/feature_led_indicators.md

@@ -11,13 +11,13 @@ QMK provides methods to read 5 of the LEDs defined in the HID spec:
 * Kana
 
 There are three ways to get the lock LED state:
-* by specifying configuration options within `config.h`
-* by implementing `bool led_update_kb(led_t led_state)` or `_user(led_t led_state)`; or
-* by calling `led_t host_keyboard_led_state()`
+* Configuration options in `config.h`
+* Implement `led_update_*` function
+* Call `led_t host_keyboard_led_state()`
 
-!> `host_keyboard_led_state()` may already reflect a new value before `led_update_user()` is called.
+!> The `host_keyboard_led_state()` may reflect an updated state before `led_update_user()` is called.
 
-Two more deprecated functions exist that provide the LED state as a `uint8_t`:
+Two deprecated functions that provide the LED state as `uint8_t`:
 
 * `uint8_t led_set_kb(uint8_t usb_led)` and `_user(uint8_t usb_led)`
 * `uint8_t host_keyboard_leds()`
@@ -37,23 +37,20 @@ To configure the indicators, `#define` these in your `config.h`:
 
 Unless you are designing your own keyboard, you generally should not need to change the above config options.
 
-## `led_update_*()`
+## LED update function
 
-When the configuration options do not provide enough flexibility, the API hooks provided allow custom control of the LED behavior. These functions will be called when the state of one of those 5 LEDs changes. It receives the LED state as a struct parameter.
+When the configuration options do not provide enough flexibility, the following callbacks allow custom control of the LED behavior. These functions will be called when one of those 5 LEDs changes state: 
 
-By convention, return `true` from `led_update_user()` to get the `led_update_kb()` hook to run its code, and
-return `false` when you would prefer not to run the code in `led_update_kb()`.
+* Keyboard/revision: `bool led_update_kb(led_t led_state)`
+* Keymap: `bool led_update_user(led_t led_state)`
 
-Some examples include:
+Both receives LED state as a struct parameter. Returning `true` in `led_update_user()` will allow the keyboard level code in `led_update_kb()` to run as well. Returning `false` will override the keyboard level code, depending on how the keyboard level function is set up.
 
-  - overriding the LEDs to use them for something else like layer indication
-    - return `false` because you do not want the `_kb()` function to run, as it would override your layer behavior.
-  - play a sound when an LED turns on or off.
-    - return `true` because you want the `_kb` function to run, and this is in addition to the default LED behavior.
+?> This boolean return type of `led_update_user` allows for overriding keyboard LED controls, and is thus recommended over the void `led_set_user` function.
 
-?> Because the `led_set_*` functions return `void` instead of `bool`, they do not allow for overriding the keyboard LED control, and thus it's recommended to use `led_update_*` instead.
+### Example of keyboard LED update implementation
 
-### Example `led_update_kb()` Implementation
+This is a template indicator function that can be implemented on keyboard level code:
 
 ```c
 bool led_update_kb(led_t led_state) {
@@ -74,9 +71,9 @@ bool led_update_kb(led_t led_state) {
 }
 ```
 
-### Example `led_update_user()` Implementation
+### Example of user LED update implementation
 
-This incomplete example would play a sound if Caps Lock is turned on or off. It returns `true`, because you also want the LEDs to maintain their state.
+This is an incomplete example will play a sound if Caps Lock is turned on or off. It returns `true` to allow keyboard LED function to maintain their state.
 
 ```c
 #ifdef AUDIO_ENABLE
@@ -96,18 +93,17 @@ bool led_update_user(led_t led_state) {
 }
 ```
 
-### `led_update_*` Function Documentation
+## Host keyboard LED state 
 
-* Keyboard/Revision: `bool led_update_kb(led_t led_state)`
-* Keymap: `bool led_update_user(led_t led_state)`
+The `host_keyboard_led_state()` function will report the LED state returned from the host computer as `led_t`. This is useful for reading the LED state outside `led_update_*`. For example, you can get the boolean state of Caps Lock from the host with:
 
-## `host_keyboard_led_state()`
-
-Call this function to get the last received LED state as a `led_t`. This is useful for reading the LED state outside `led_update_*`, e.g. in [`matrix_scan_user()`](#matrix-scanning-code).
+```c
+bool caps = host_keyboard_led_state().caps_lock;
+```
 
 ## Setting Physical LED State
 
-Some keyboard implementations provide convenience methods for setting the state of the physical LEDs.
+Some keyboard implementations provide convenient methods for setting the state of the physical LEDs.
 
 ### Ergodox Boards
 

docs/feature_led_matrix.md

@@ -264,11 +264,11 @@ enum led_matrix_effects {
 };
 ```
 
-You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `config.h`:
+You can enable a single effect by defining `ENABLE_[EFFECT_NAME]` in your `config.h`:
 
 
-|Define                                                 |Description                                    |
-|-------------------------------------------------------|-----------------------------------------------|
+|Define                                                 |Description                                   |
+|-------------------------------------------------------|----------------------------------------------|
 |`#define ENABLE_LED_MATRIX_ALPHAS_MODS`                |Enables `LED_MATRIX_ALPHAS_MODS`              |
 |`#define ENABLE_LED_MATRIX_BREATHING`                  |Enables `LED_MATRIX_BREATHING`                |
 |`#define ENABLE_LED_MATRIX_BAND`                       |Enables `LED_MATRIX_BAND`                     |
@@ -278,6 +278,13 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con
 |`#define ENABLE_LED_MATRIX_CYCLE_UP_DOWN`              |Enables `LED_MATRIX_CYCLE_UP_DOWN`            |
 |`#define ENABLE_LED_MATRIX_CYCLE_OUT_IN`               |Enables `LED_MATRIX_CYCLE_OUT_IN`             |
 |`#define ENABLE_LED_MATRIX_DUAL_BEACON`                |Enables `LED_MATRIX_DUAL_BEACON`              |
+|`#define ENABLE_LED_MATRIX_WAVE_LEFT_RIGHT`            |Enables `LED_MATRIX_WAVE_LEFT_RIGHT`          |
+|`#define ENABLE_LED_MATRIX_WAVE_UP_DOWN`               |Enables `LED_MATRIX_WAVE_UP_DOWN`             |
+
+?> These modes don't require any additional defines.
+
+|Reactive Defines                                       |Description                                   |
+|-------------------------------------------------------|----------------------------------------------|
 |`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_SIMPLE`      |Enables `LED_MATRIX_SOLID_REACTIVE_SIMPLE`    |
 |`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_WIDE`        |Enables `LED_MATRIX_SOLID_REACTIVE_WIDE`      |
 |`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_MULTIWIDE`   |Enables `LED_MATRIX_SOLID_REACTIVE_MULTIWIDE` |
@@ -287,8 +294,8 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con
 |`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_MULTINEXUS`  |Enables `LED_MATRIX_SOLID_REACTIVE_MULTINEXUS`|
 |`#define ENABLE_LED_MATRIX_SOLID_SPLASH`               |Enables `LED_MATRIX_SOLID_SPLASH`             |
 |`#define ENABLE_LED_MATRIX_SOLID_MULTISPLASH`          |Enables `LED_MATRIX_SOLID_MULTISPLASH`        |
-|`#define ENABLE_LED_MATRIX_WAVE_LEFT_RIGHT`            |Enables `LED_MATRIX_WAVE_LEFT_RIGHT`          |
-|`#define ENABLE_LED_MATRIX_WAVE_UP_DOWN`               |Enables `LED_MATRIX_WAVE_UP_DOWN`             |
+
+?> These modes also require the `LED_MATRIX_KEYPRESSES` or `LED_MATRIX_KEYRELEASES` define to be available.
 
 ## Custom LED Matrix Effects :id=custom-led-matrix-effects
 

docs/feature_midi.md

@@ -10,6 +10,10 @@ MIDI_ENABLE = yes
 
 There are two MIDI systems in QMK: basic and advanced. With basic MIDI you will only be able to send Note On and Note Off messages using the note keycodes, meaning that keycodes like `MI_OCTU` and `MI_OCTD` will not work. Advanced MIDI allows you to do things like octave shifts, channel changes, velocity changes, modulation, and more.
 
+### Caveats
+
+MIDI requires 2 USB endpoints and as such may not work on some hardware such as V-USB controllers.
+
 ### Basic MIDI
 
 To enable basic MIDI, add the following to your `config.h`:

docs/feature_pointing_device.md

@@ -134,6 +134,7 @@ The Pimoroni Trackball module is a I2C based breakout board with an RGB enable t
 
 ### PMW 3360 Sensor
 
+This drivers supports multiple sensors _per_ controller, so 2 can be attached at the same side for split keyboards (or unsplit keyboards).
 To use the PMW 3360 sensor, add this to your `rules.mk`
 
 ```make
@@ -145,6 +146,7 @@ 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_CS_PINS`                | (Alternative) Sets the Cable Select pins connected to multiple sensors.                    | _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`           |
@@ -155,6 +157,36 @@ The PMW 3360 is an SPI driven optical sensor, that uses a built in IR LED for su
 
 The CPI range is 100-12000, in increments of 100. Defaults to 1600 CPI.
 
+To use multiple sensors, instead of setting `PMW3360_CS_PIN` you need to set `PMW3360_CS_PINS` and also handle and merge the read from this sensor in user code.
+Note that different (per sensor) values of CPI, speed liftoff, rotational angle or flipping of X/Y is not currently supported.
+
+```c
+// in config.h:
+#define PMW3360_CS_PINS { B5, B6 }
+
+// in keyboard.c:
+#ifdef POINTING_DEVICE_ENABLE
+void pointing_device_init_kb(void) {
+    pmw3360_init(1);  // index 1 is the second device.
+    pointing_device_set_cpi(800);  // applies to both sensors
+    pointing_device_init_user();
+}
+
+// Contains report from sensor #0 already, need to merge in from sensor #1
+report_mouse_t pointing_device_task_kb(report_mouse_t mouse_report) {
+    report_pmw3360_t data = pmw3360_read_burst(1);
+    if (data.isOnSurface && data.isMotion) {
+// From quantum/pointing_device_drivers.c
+#define constrain_hid(amt) ((amt) < -127 ? -127 : ((amt) > 127 ? 127 : (amt)))
+        mouse_report.x = constrain_hid(mouse_report.x + data.dx);
+        mouse_report.y = constrain_hid(mouse_report.y + data.dy);
+    }
+    return pointing_device_task_user(mouse_report);
+}
+#endif
+
+```
+
 ### PMW 3389 Sensor
 
 To use the PMW 3389 sensor, add this to your `rules.mk`

docs/feature_rgb_matrix.md

@@ -520,7 +520,7 @@ All RGB keycodes are currently shared with the RGBLIGHT system:
 |`RGB_VAD`          |          |Decrease value (brightness), increase value when Shift is held                        |
 |`RGB_SPI`          |          |Increase effect speed (does not support eeprom yet), decrease speed when Shift is held|
 |`RGB_SPD`          |          |Decrease effect speed (does not support eeprom yet), increase speed when Shift is held|
-|`RGB_MODE_PLAIN`   |`RGB_M_P `|Static (no animation) mode                                                            |
+|`RGB_MODE_PLAIN`   |`RGB_M_P` |Static (no animation) mode                                                            |
 |`RGB_MODE_BREATHE` |`RGB_M_B` |Breathing animation mode                                                              |
 |`RGB_MODE_RAINBOW` |`RGB_M_R` |Full gradient scrolling left to right (uses the `RGB_MATRIX_CYCLE_LEFT_RIGHT` mode)   |
 |`RGB_MODE_SWIRL`   |`RGB_M_SW`|Full gradient spinning pinwheel around center of keyboard (uses `RGB_MATRIX_CYCLE_PINWHEEL` mode) |
@@ -657,18 +657,19 @@ You can enable a single effect by defining `ENABLE_[EFFECT_NAME]` in your `confi
 
 ### RGB Matrix Effect Typing Heatmap :id=rgb-matrix-effect-typing-heatmap
 
-This effect will color the RGB matrix according to a heatmap of recently pressed
-keys. Whenever a key is pressed its "temperature" increases as well as that of
-its neighboring keys. The temperature of each key is then decreased
-automatically every 25 milliseconds by default.
+This effect will color the RGB matrix according to a heatmap of recently pressed keys. Whenever a key is pressed its "temperature" increases as well as that of its neighboring keys. The temperature of each key is then decreased automatically every 25 milliseconds by default.
 
-In order to change the delay of temperature decrease define
-`RGB_MATRIX_TYPING_HEATMAP_DECREASE_DELAY_MS`:
+In order to change the delay of temperature decrease define `RGB_MATRIX_TYPING_HEATMAP_DECREASE_DELAY_MS`:
 
 ```c
 #define RGB_MATRIX_TYPING_HEATMAP_DECREASE_DELAY_MS 50
 ```
 
+Heatmap effect may not light up the correct adjacent LEDs for certain key matrix layout such as split keyboards. The following define will limit the effect to pressed keys only:
+```c
+#define RGB_MATRIX_TYPING_HEATMAP_SLIM
+```
+
 ## 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.
@@ -776,6 +777,7 @@ These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master
 #define RGB_MATRIX_DISABLE_KEYCODES // disables control of rgb matrix by keycodes (must use code functions to control the feature)
 #define RGB_MATRIX_SPLIT { X, Y } 	// (Optional) For split keyboards, the number of LEDs connected on each half. X = left, Y = Right.
                               		// If RGB_MATRIX_KEYPRESSES or RGB_MATRIX_KEYRELEASES is enabled, you also will want to enable SPLIT_TRANSPORT_MIRROR
+#define RGB_TRIGGER_ON_KEYDOWN      // Triggers RGB keypress events on key down. This makes RGB control feel more responsive. This may cause RGB to not function properly on some boards
 ```
 
 ## EEPROM storage :id=eeprom-storage
@@ -887,15 +889,15 @@ void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) {
 }
 ```
 
-Layer indicator on all flagged keys:
+Layer indicator on all keys:
 ```c
 void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) {
     for (uint8_t i = led_min; i <= led_max; i++) {
         switch(get_highest_layer(layer_state|default_layer_state)) {
-            case RAISE:
+            case 2:
                 rgb_matrix_set_color(i, RGB_BLUE);
                 break;
-            case LOWER:
+            case 1:
                 rgb_matrix_set_color(i, RGB_YELLOW);
                 break;
             default:
@@ -905,7 +907,7 @@ void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) {
 }
 ```
 
-Layer indicator with only configured keys:
+Layer indicator only on keys with configured keycodes:
 ```c
 void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) {
     if (get_highest_layer(layer_state) > 0) {

docs/feature_rgblight.md

@@ -326,6 +326,19 @@ 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.
 
+Blinking accumulates layers so if multiple layers are set blinking at the same time they will all blink for the duration and repeat times of the last layer to be blinked.
+To stop these other layers from blinking use `rgblight_unblink_layer` or `rgblight_unblink_all_but_layer`:
+
+```c
+rgblight_blink_layer(1, 500);
+rgblight_unblink_all_but_layer(1);
+```
+
+```c
+rgblight_unblink_layer(3);
+rgblight_blink_layer(2, 500);
+```
+
 !> 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

docs/feature_secure.md

@@ -0,0 +1,54 @@
+# Secure
+
+The secure feature aims to prevent unwanted interaction without user intervention.
+
+?> Secure does **not** currently implement encryption/decryption/etc and should not be a replacement where a strong hardware/software based solution is required.
+
+### Unlock sequence
+
+To unlock, the user must perform a set of actions. This can optionally be configured to be multiple keys.
+
+* While unlocking all keyboard input is ignored
+* Incorrect attempts will revert back to the previously locked state
+
+### Automatic Locking
+
+Once unlocked, the keyboard will revert back to a locked state after the configured timeout.
+The timeout can be refreshed by using the `secure_activity_event` function, for example from one of the various [hooks](custom_quantum_functions.md).
+
+## Usage
+
+Add the following to your `rules.mk`:
+
+```make
+SECURE_ENABLE = yes
+```
+
+## Keycodes
+
+| Key              | Description                                                                    |
+|------------------|--------------------------------------------------------------------------------|
+| `SECURE_LOCK`    | Revert back to a locked state                                                  |
+| `SECURE_UNLOCK`  | Forces unlock without performing a unlock sequence                             |
+| `SECURE_TOGGLE`  | Toggle directly between locked and unlock without performing a unlock sequence |
+| `SECURE_REQUEST` | Request that user perform the unlock sequence                                  |
+
+## Configuration
+
+| Define                  | Default        | Description                                                                     |
+|-------------------------|----------------|---------------------------------------------------------------------------------|
+|`SECURE_UNLOCK_TIMEOUT`  | `5000`         | Timeout for the user to perform the configured unlock sequence - `0` to disable |
+|`SECURE_IDLE_TIMEOUT`    | `60000`        | Timeout while unlocked before returning to locked - `0` to disable              |
+|`SECURE_UNLOCK_SEQUENCE` | `{ { 0, 0 } }` | Array of matrix locations describing a sequential sequence of keypresses        |
+
+## Functions
+
+| Function                  | Description                                                                |
+|---------------------------|----------------------------------------------------------------------------|
+| `secure_is_locked()`      | Check if the device is currently locked                                    |
+| `secure_is_unlocking()`   | Check if an unlock sequence is currently in progress                       |
+| `secure_is_unlocked()`    | Check if the device is currently unlocked                                  |
+| `secure_lock()`           | Lock down the device                                                       |
+| `secure_unlock()`         | Force unlock the device - bypasses user unlock sequence                    |
+| `secure_request_unlock()` | Begin listening for an unlock sequence                                     |
+| `secure_activity_event()` | Flag that user activity has happened and the device should remain unlocked |

docs/feature_split_keyboard.md

@@ -10,6 +10,8 @@ For this, we will mostly be talking about the generic implementation used by the
 
 !> ARM split supports most QMK subsystems when using the 'serial' and 'serial_usart' drivers. I2C slave is currently unsupported.
 
+!> Both sides must use the same MCU family, for eg two Pro Micro-compatible controllers or two Blackpills. Currently, mixing AVR and ARM is not possible as ARM vs AVR uses different method for serial communication, and are not compatible. Moreover Blackpill's uses 3.3v logic, and atmega32u4 uses 5v logic.
+
 ## Compatibility Overview
 
 | Transport                    | AVR                | ARM                |

docs/feature_stenography.md

@@ -115,8 +115,8 @@ As defined in `keymap_steno.h`.
 |`STN_E`|`STN_E`| `E` vowel|
 |`STN_U`|`STN_U`| `U` vowel|
 |`STN_FR`|`STN_FR`| `-F`|
-|`STN_PR`|`STN_PR`| `-P`|
 |`STN_RR`|`STN_RR`| `-R`|
+|`STN_PR`|`STN_PR`| `-P`|
 |`STN_BR`|`STN_BR`| `-B`|
 |`STN_LR`|`STN_LR`| `-L`|
 |`STN_GR`|`STN_GR`| `-G`|

docs/feature_tap_dance.md

@@ -305,7 +305,8 @@ void x_finished(qk_tap_dance_state_t *state, void *user_data) {
         // Last case is for fast typing. Assuming your key is `f`:
         // For example, when typing the word `buffer`, and you want to make sure that you send `ff` and not `Esc`.
         // In order to type `ff` when typing fast, the next character will have to be hit within the `TAPPING_TERM`, which by default is 200ms.
-        case TD_DOUBLE_SINGLE_TAP: tap_code(KC_X); register_code(KC_X);
+        case TD_DOUBLE_SINGLE_TAP: tap_code(KC_X); register_code(KC_X); break;
+        default: break;
     }
 }
 
@@ -314,8 +315,9 @@ void x_reset(qk_tap_dance_state_t *state, void *user_data) {
         case TD_SINGLE_TAP: unregister_code(KC_X); break;
         case TD_SINGLE_HOLD: unregister_code(KC_LCTL); break;
         case TD_DOUBLE_TAP: unregister_code(KC_ESC); break;
-        case TD_DOUBLE_HOLD: unregister_code(KC_LALT);
-        case TD_DOUBLE_SINGLE_TAP: unregister_code(KC_X);
+        case TD_DOUBLE_HOLD: unregister_code(KC_LALT); break;
+        case TD_DOUBLE_SINGLE_TAP: unregister_code(KC_X); break;
+        default: break;
     }
     xtap_state.state = TD_NONE;
 }

docs/flashing.md

@@ -266,7 +266,7 @@ Flashing sequence:
 ### `make` Targets
 
 * `:dfu-util`: Waits until an STM32 bootloader device is available, and then flashes the firmware.
-* `:dfu-util-split-left` and `:dfu-util-split-right`: Flashes the firmware as with `:avrdude`, but also sets the handedness setting in EEPROM. This is ideal for Proton-C-based split keyboards.
+* `:dfu-util-split-left` and `:dfu-util-split-right`: Flashes the firmware as with `:dfu-util`, but also sets the handedness setting in EEPROM. This is ideal for Proton-C-based split keyboards.
 * `:st-link-cli`: Allows you to flash the firmware via the ST-Link CLI utility, rather than dfu-util. Requires an ST-Link dongle.
 * `:st-flash`: Allows you to flash the firmware via the `st-flash` utility from [STLink Tools](https://github.com/stlink-org/stlink), rather than dfu-util. Requires an ST-Link dongle.
 

docs/how_keyboards_work.md

@@ -35,7 +35,7 @@ USB for a given key.
 
 ## 3. What the Event Input/Kernel Does
 
-The *scancode* is mapped to a *keycode* dependent on the keyboard [60-keyboard.hwdb at Master](https://github.com/systemd/systemd/blob/master/hwdb.d/60-keyboard.hwdb). Without this mapping, the operating system will not receive a valid keycode and will be unable to do anything useful with that key press.
+The *scancode* is mapped to a *keycode* dependent on the keyboard [60-keyboard.hwdb at Main](https://github.com/systemd/systemd/blob/main/hwdb.d/60-keyboard.hwdb). Without this mapping, the operating system will not receive a valid keycode and will be unable to do anything useful with that key press.
 
 ## 4. What the Operating System Does
 

docs/i2c_driver.md

@@ -166,7 +166,7 @@ Send multiple bytes to the selected I2C device.
 
 ### `i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout)`
 
-Receive multiple bytes from the selected SPI device.
+Receive multiple bytes from the selected I2C device.
 
 #### Arguments
 

docs/index.html

@@ -15,7 +15,7 @@
   <meta name="twitter:card" content="summary_large_image">
   <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/buble.css" title="light">
   <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/dark.css" media="(prefers-color-scheme: dark)">
-  <link rel="stylesheet" href="//unpkg.com/docsify-toc@1.0.0/dist/toc.css">
+  <link rel="stylesheet" href="//unpkg.com/docsify-toc@1.1.0/dist/toc.css">
   <link rel="stylesheet" href="qmk_custom_light.css">
   <link rel="stylesheet" href="qmk_custom_dark.css" media="(prefers-color-scheme: dark)">
 </head>
@@ -130,7 +130,7 @@
   <script src="//unpkg.com/docsify/lib/plugins/emoji.min.js"></script>
   <script src="//unpkg.com/docsify-tabs@1"></script>
   <script src="//unpkg.com/docsify-copy-code@2"></script>
-  <script src="//unpkg.com/docsify-toc@1.0.0/dist/toc.js"></script>
+  <script src="//unpkg.com/docsify-toc@1.1.0/dist/toc.js"></script>
   <script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
   <script src="//unpkg.com/prismjs/components/prism-c.min.js"></script>
   <script src="//unpkg.com/prismjs/components/prism-cpp.min.js"></script>

docs/keycodes.md

@@ -225,6 +225,7 @@ See also: [Quantum Keycodes](quantum_keycodes.md#qmk-keycodes)
 |`QK_DEBUG_TOGGLE`|`DB_TOGG`|Toggle debug mode                                                                |
 |`QK_CLEAR_EEPROM`|`EE_CLR` |Reinitializes the keyboard's EEPROM (persistent memory)                          |
 |`QK_MAKE`        |         |Sends `qmk compile -kb (keyboard) -km (keymap)`, or `qmk flash` if shift is held |
+|`QK_REBOOT`      |`QK_RBT` |Resets the keyboard. Does not load the bootloader                                |
 
 ## Audio Keys :id=audio-keys
 
@@ -268,6 +269,14 @@ See also: [Bluetooth](feature_bluetooth.md)
 |`OUT_USB` |USB only                                      |
 |`OUT_BT`  |Bluetooth only                                |
 
+## Caps Word :id=caps-word
+
+See also: [Caps Word](feature_caps_word.md)
+
+|Key        |Aliases  |Description                   |
+|-----------|---------|------------------------------|
+|`CAPS_WORD`|`CAPSWRD`|Toggles Caps Word             |
+
 ## Dynamic Macros :id=dynamic-macros
 
 See also: [Dynamic Macros](feature_dynamic_macros.md)

docs/newbs_building_firmware_workflow.md

@@ -0,0 +1,189 @@
+# Building QMK with GitHub Userspace
+
+This is an intermediate QMK tutorial to setup an out-of-tree build environment with a personal GitHub repository. It avoids using a fork of the QMK firmware to store and build your keymap within its source tree. Keymap files will instead be stored in your own personal GitHub repository, in [Userspace](https://docs.qmk.fm/#/feature_userspace) format, and built with an action workflow. Unlike the [default tutorial](https://docs.qmk.fm/#/newbs), this guide requires some familiarity with using Git.
+
+?> **Is This Guide For Me?**<br>
+This is a lean setup to avoid space-consuming local build environment in your computer. Troubleshooting compile-time errors will be slower with commit uploads to GitHub for the compiler workflow.
+
+
+## Prerequisites
+
+The following are required to get started:
+
+* [GitHub Account](https://github.com/new)
+  * A working account is required to setup and host your repository for GitHub Actions to build QMK firmware.
+* [Text editor](newbs_learn_more_resources.md#text-editor-resources)
+  * You’ll need a program that can edit and save plain text files. The default editor that comes with many OS's does not save plain text files, so you'll need to make sure that whatever editor you chose does.
+* [Toolbox](https://github.com/qmk/qmk_toolbox)
+  * A graphical program for Windows and macOS that allows you to both program and debug your custom keyboard.
+
+
+## Environment Setup
+
+?> If you are familiar with using [github.dev](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor), you can skip to [step 2](#_2-create-github-repository) and commit the code files that follows directly on GitHub using the web-based VSCode editor.
+
+### 1. Install Git
+
+A working Git client is required for your local operating system to commit and push changes to GitHub.
+
+<!-- tabs:start -->
+
+### ** Windows **
+
+QMK maintains a bundle of MSYS2, the CLI and all necessary dependencies including Git. Install [QMK MSYS](https://msys.qmk.fm/) with the latest release [here](https://github.com/qmk/qmk_distro_msys/releases/latest). Git will be part of the bundle.
+
+### ** macOS **
+
+Install Homebrew following the instructions on https://brew.sh. Git will be part of the bundle.
+
+### ** Linux/WSL **
+
+It's very likely that you already have Git installed. If not, use one of the following commands:
+
+* Debian / Ubuntu / Devuan: `sudo apt install -y git`
+* Fedora / Red Hat / CentOS: `sudo yum -y install git`
+* Arch / Manjaro: `sudo pacman --needed --noconfirm -S git`
+* Void: `sudo xbps-install -y git`
+* Solus: `sudo eopkg -y install git`
+* Sabayon: `sudo equo install dev-vcs/git`
+* Gentoo: `sudo emerge dev-vcs/git`
+
+<!-- tabs:end -->
+
+### 2. GitHub authentication
+
+If your GitHub account is not configured for [authenticated Git operations](https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/), you will need to setup at least one of the following:
+* [Personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
+* [Connecting with SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh)
+
+### 3. Create a repository
+
+You will need a personal GitHub repository to host your QMK code. Follow [this guide](https://docs.github.com/en/get-started/quickstart/create-a-repo#create-a-repository) to create one named `qmk_keymap`. Do not proceed to commit any files just yet.
+
+
+## Initial Code Commit
+
+### Create template files
+
+Run the following commands in your computer to create a folder with a few template files:
+```
+mkdir -p ~/qmk_keymap/.github/workflows
+touch ~/qmk_keymap/.github/workflows/build.yml
+touch ~/qmk_keymap/config.h
+echo "SRC += source.c" > ~/qmk_keymap/rules.mk
+echo "#include QMK_KEYBOARD_H" > ~/qmk_keymap/source.c
+```
+
+?> For Windows user running MSYS, those commands will create the folder `qmk_keymap/` and its content in the `C:\Users\<windows_username>\qmk_keymap\` path location.
+
+### Add a JSON keymap
+
+Visit the [QMK Configurator](https://config.qmk.fm/#/) to create a keymap file:
+
+1. Select your keyboard from the drop-down list (and choose a layout if required).
+2. Use your GitHub username for the **Keymap Name** field.
+3. Customise the key layout according to your preference.
+4. Select download next to **KEYMAP.JSON** and save the JSON file into the `~/qmk_keymap/` folder.
+
+### Add a GitHub Action workflow
+
+Open the file `~/qmk_keymap/.github/workflows/build.yml` with your favorite [text editor](newbs_learn_more_resources.md#text-editor-resources), paste the following workflow content, and save it:
+```yml
+name: Build QMK firmware
+on: [push, workflow_dispatch]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container: qmkfm/qmk_cli
+    strategy:
+      fail-fast: false
+      matrix:
+# List of keymap json files to build
+        file:
+        - username.json
+# End of json file list
+
+    steps:
+
+    - name: Checkout QMK
+      uses: actions/checkout@v3
+      with:
+        repository: qmk/qmk_firmware
+        submodules: recursive
+
+    - name: Checkout userspace
+      uses: actions/checkout@v3
+      with:
+        path: users/${{ github.actor }}
+
+    - name: Build firmware
+      run: qmk compile "users/${{ github.actor }}/${{ matrix.file }}"
+
+    - name: Archive firmware
+      uses: actions/upload-artifact@v3
+      continue-on-error: true
+      with:
+        name: ${{ matrix.file }}_${{ github.actor }}
+        path: |
+          *.hex
+          *.bin
+          *.uf2
+```
+Replace `username.json` with the JSON file name that was downloaded from [QMK Configurator](https://config.qmk.fm/#/) in the previous step.
+
+!> Do note that the `build.yml` file requires ***proper indentation*** for every line. Incorrect spacing will trigger workflow syntax errors.
+
+### Commit files to GitHub
+
+If you have completed all steps correctly, the folder `qmk_keymap/` will contain the following files:
+```
+|-- .github
+|   `-- workflows
+|       `-- build.yml
+|-- rules.mk
+|-- config.h
+|-- source.c
+|-- username.json
+```
+
+To commit and push them into GitHub, run the following commands (replacing `gh-username` with your GitHub user name):
+```
+cd ~/qmk_keymap
+git init
+git add -A
+git commit -m "Initial QMK keymap commit"
+git branch -M main
+git remote add origin https://github.com/gh-username/qmk_keymap.git
+git push -u origin main
+```
+?> Use your GitHub personal access token at the password prompt. If you have setup SSH access, replace `https://github.com/gh-username/qmk_keymap.git` with `git@github.com:gh-username/qmk_keymap.git` in the remote origin command above.
+
+### Review workflow output
+
+Files committed to GitHub in the previous step will automatically trigger the workflow to build the JSON file listed in `build.yml`. To review its output:
+1. Visit your "**qmk_keymap**" repository page on [GitHub](https://github.com/).
+2. Select **Actions** tab to display the "**Build QMK Firmware**" workflow.
+3. Select that workflow to display its run from the last commit.
+4. Successfully compiled firmware will be under the "**Artifacts**" section.
+5. If there are build errors, review the job log for details.
+
+Download and flash the firmware file into your keyboard using [QMK Toolbox](https://docs.qmk.fm/#/newbs_flashing?id=flashing-your-keyboard-with-qmk-toolbox).
+
+
+## Customising your keymap
+
+This setup and workflow relies on the QMK [Userspace](https://docs.qmk.fm/#/feature_userspace) feature. The build process will copy the QMK source codes and clone your repository into its `users/` folder in a container. You must adhere to the following guidelines when customising your keymaps:
+
+* Keymap layout files must be retained in JSON format and cannot be converted to `keymap.c`.
+* User callback and functions (e.g. `process_record_user()`) can be placed in the `source.c` file.
+* Multiple keymap JSON files can be built in the same workflow. List them under `matrix.file:`, e.g.:
+```yml
+        file:
+        - planck.json
+        - crkbd.json
+```
+* Code changes will require Git commit into GitHub to trigger the build workflow.
+
+
+?> See [GitHub Actions guide](https://docs.github.com/en/actions/learn-github-actions) to learn more about development workflow.

docs/newbs_flashing.md

@@ -108,6 +108,8 @@ However, this does rely on the bootloader being set by the keyboard. If this inf
 
 In this case, you'll have to fall back on specifying the bootloader. See the [Flashing Firmware](flashing.md) Guide for more details.
 
+!> If your bootloader is not detected by `qmk flash`, try running `qmk doctor` for suggestions on how to fix common problems.
+
 ## Test It Out!
 
 Congrats! Your custom firmware has been programmed to your keyboard and you're ready to test it out!

docs/newbs_getting_started.md

@@ -27,30 +27,24 @@ QMK maintains a Bundle of MSYS2, the CLI and all necessary dependencies. It also
 
 You will need to install [QMK MSYS](https://msys.qmk.fm/). The latest release is available [here](https://github.com/qmk/qmk_distro_msys/releases/latest).
 
-Alternatively, if you'd like to manually install MSYS2, the following section will walk you through the process.
-
 <details>
-  <summary>Manual Install</summary>
+  <summary>Advanced Users</summary>
 
-?> Ignore the following steps if you use `QMK MSYS`.
+!> <b style="font-size:150%">This process is not recommended for new users.</b>
+
+If you'd like to manually install MSYS2, the following sections will walk you through the process.
 
 #### Prerequisites
 
-You will need to install MSYS2, Git and Python. Follow the installation instructions on https://www.msys2.org.
-
-Once MSYS2 is installed, close any open MSYS terminals and open a new MinGW 64-bit terminal.
+You will need to install [MSYS2](https://www.msys2.org). Once installed, close any open MSYS terminals (purple icon) and open a new MinGW 64-bit terminal (blue icon) from the Start Menu.
 
 !> **NOTE:** The MinGW 64-bit terminal is *not* the same as the MSYS terminal that opens when installation is completed. Your prompt should say "MINGW64" in purple text, rather than "MSYS". See [this page](https://www.msys2.org/wiki/MSYS2-introduction/#subsystems) for more information on the differences.
 
-Then run the following command:
-
-    pacman --needed --noconfirm --disable-download-timeout -S git mingw-w64-x86_64-toolchain mingw-w64-x86_64-python3-pip
-
 #### Installation
 
 Install the QMK CLI by running:
 
-    python3 -m pip install qmk
+    pacman --needed --noconfirm --disable-download-timeout -S git mingw-w64-x86_64-python-qmk
 
 </details>
 

docs/newbs_learn_more_resources.md

@@ -20,7 +20,6 @@ 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_vscode.md

@@ -104,10 +104,8 @@ There are a number of extensions that you may want to install:
 * [Git Extension Pack](https://marketplace.visualstudio.com/items?itemName=donjayamanne.git-extension-pack) - 
 This installs a bunch of Git related tools that may make using Git with QMK Firmware easier.
 * [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) - _[Optional]_ -  Helps to keep the code to the QMK Coding Conventions.
-* [Bracket Pair Colorizer 2](https://marketplace.visualstudio.com/items?itemName=CoenraadS.bracket-pair-colorizer-2) - _[Optional]_ - This color codes the brackets in your code, to make it easier to reference nested code.
 * [GitHub Markdown Preview](https://marketplace.visualstudio.com/items?itemName=bierner.github-markdown-preview) - _[Optional]_ - Makes the markdown preview in VS Code more like GitHub's.
 * [VS Live Share Extension Pack](https://marketplace.visualstudio.com/items?itemName=MS-vsliveshare.vsliveshare-pack) - _[Optional]_ - This extension allows somebody else to access your workspace (or you to access somebody else's workspace) and help out.  This is great if you're having issues and need some help from somebody.
-* [VIM Keymap](https://marketplace.visualstudio.com/items?itemName=GiuseppeCesarano.vim-keymap) - _[Optional]_ - For those that prefer VIM style keybindings. There are other options for this, too. 
 
 Restart once you've installed any extensions
 

docs/platformdev_blackpill_f411.md

@@ -0,0 +1,48 @@
+# WeAct Blackpill (STM32F411)
+
+The WeAct Blackpill is a popular choice for handwired boards, as it offers a powerful micro controller, USB Type C, a good number of pins to use, and a large amount of firmware space.  All for a ~$6 USD price tag. 
+
+* [WeAct GitHub for F411 Blackpill](https://github.com/WeActTC/MiniSTM32F4x1)
+  * Unfortunately, due to supply issues official WeAct F411 based blackpills may not be available.
+
+![Blackpill F411](https://i.imgur.com/nCgeolTh.png)
+
+
+## Pin Usage Limitations
+
+While the Blackpill is a great choice to use in your keyboard, there are a number of caveats in regards to using them.  The first is that a number of exposed pins cannot be used, or have special considerations/hardware tweaks that are required for proper opertion. 
+
+### Unusable pins
+* Pins `A11` and `A12` are not useable because they're used for USB connection, and cannot be shared.
+  * In theory, these pins can be used.  However, doing so may disable USB connectivity, outright, if used for anything other than a USB port
+* Pin `B2` is used by `BOOT1` and cannot be used, without causing problems. 
+* `VBAT` is not a usable pin.
+* `NRST` is not a usable pin.
+
+### Pins to be avoided
+* Pin `A9` is meant for VBUS Sense and should not be used, if it can be avoided.  It has an internal pull-down resesitor, which may cause issues with usage.  However, a pull-up resistor can work (~5.1k), but should be avoided.
+* Pin `A10` can be used, but should be avoided.  Any connection on this pin can prevent the bootloader from entering the proper mode for DFU flashing.  A pull-up resistor (~22k) on this pin fixes the bootloader issue. 
+
+### Shared Usage
+* Pin `A0` is shared with the User Key (button) on the controller.  It can be used. 
+* Pin `C13` is shared with the onboard LED indicator, and is connected to +3.3V.  This can be used, but may cause the LED to blink intermittently, depending on activity on the pin. 
+  * 
+* Pins `A4`, `A5`, `A6` and `A7` are used by the SOI8 footprint on the back of the controller, that can be used for either an SPI Flash chip, or an SPI EEPROM chip.  `A4` is the Chip Select pin, and cannot be shared.  However, `A5`, `A6`, and `A7` are the `SCK`, `MISO`, and `MOSI` pins, respectively, and can be shared with other SPI devices. 
+
+### Limited Usage
+* Pins `C13`, `C14`, and `C15` have limits on output current. They should be used only as input.   Eg, they should not be used for row pins in COL2ROW matrix configurations, but can be used as column pins.
+  * This is because the column pins (in COL2ROW) are pulled up (the pullup strength is independant of the current sourcing limitation) and the ROW is driven low and sinks current, then we check the state of the COLs to look for keypresses.
+
+* Pins `A0` and `B5` are not 5V tolerant, and should only be used with 3.3V compatible functionality. 
+
+## Additional Information
+
+### Bootloader issuse
+
+Due to the use of a 25MHz crystal, the controller may have issues entering the bootloader.  Heating up the controller can help with this issue. 
+
+Also, if pin `A10` is connected to anything at all, it needs to have a pullup resistor (see [Pins to be avoided](#pins-to-be-avoided), above)
+
+### Tiny UF2 Support
+
+There is [tinyuf2 support for the WeAct Blackpill](https://github.com/adafruit/tinyuf2/tree/master/ports/stm32f4/boards/stm32f411ce_blackpill).  Instructions on how to compile the bootloadr can be found [here](https://github.com/adafruit/tinyuf2#build-and-flash).  Setting `BOOTLOADER = tinyuf2` will enable support for this user bootloader, and the correct configuration to prevent it from being overwritten when flashing firmware. 

docs/pr_checklist.md

@@ -46,9 +46,12 @@ Closed PRs (for inspiration, previous sets of review comments will help you elim
 https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
 
 - `info.json`
-    - valid URL
-    - valid maintainer
-    - displays correctly in Configurator (press Ctrl+Shift+I to preview local file, turn on fast input to verify ordering)
+    - With the move to [data driven](https://docs.qmk.fm/#/data_driven_config) keyboard configuration, we encourage contributors to utilise as many features as possible of the info.json [schema](https://github.com/qmk/qmk_firmware/blob/master/data/schemas/keyboard.jsonschema).
+    - the mandatory elements for a minimally complete `info.json` at present are:
+        - valid URL
+        - valid maintainer
+        - valid USB VID/PID and device version
+        - displays correctly in Configurator (press Ctrl+Shift+I to preview local file, turn on fast input to verify ordering)
 - `readme.md`
     - standard template should be present -- [link to template](https://github.com/qmk/qmk_firmware/blob/master/data/templates/keyboard/readme.md)
     - flash command is present, and has `:flash` at end
@@ -57,12 +60,13 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
     - a picture about the keyboard and preferably about the PCB, too
         - images are not to be placed in the `qmk_firmware` repository
         - images should be uploaded to an external image hosting service, such as [imgur](https://imgur.com/).
+        - if imgur is used, images should be resized appropriately: append "h" to the image url i.e. `https://i.imgur.com/vqgE7Ok.jpg` becomes `https://i.imgur.com/vqgE7Okh.jpg`
 - `rules.mk`
     - removed `MIDI_ENABLE`, `FAUXCLICKY_ENABLE` and `HD44780_ENABLE`
     - modified `# Enable Bluetooth with the Adafruit EZ-Key HID` -> `# Enable Bluetooth`
     - no `(-/+size)` comments related to enabling features
     - remove the list of alternate bootloaders if one has been specified
-    - no re-definitions of the default MCU parameters if same value, when compared to the equivalent MCU in [mcu_selection.mk](https://github.com/qmk/qmk_firmware/blob/master/quantum/mcu_selection.mk)
+    - no re-definitions of the default MCU parameters if same value, when compared to the equivalent MCU in [mcu_selection.mk](https://github.com/qmk/qmk_firmware/blob/master/builddefs/mcu_selection.mk)
 - keyboard `config.h`
     - don't repeat `MANUFACTURER` in the `PRODUCT` value
     - no `#define DESCRIPTION`
@@ -79,6 +83,9 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
     - `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
+    - Encoder support should not be hacked into the keymap here -- no `tap_code(dynamic_keymap_get_keycode())` or `action_exec()` hacks.  The [Encoder Map](feature_encoders.md?id=encoder-map) feature already supports the dynamic keymap feature (what power's VIA's "live keymap updates" capability).
+      - If support is absolutely necessary, it should be implemented exclusively at the keymap level, with none of the implementation bleeding into the keyboard level (no empty rows/columns, no encoder specific layouts, etc.), as those configurations can be redefined at the keymap level. Keymaps can then choose to use the `action_exec` hack. <!-- because people will complain, give them a way to implement it, in the meanwhile.  To be removed. -->
+      - [Request for official proper VIA support](https://github.com/the-via/app/issues/26)
 - `<keyboard>.h`
     - `#include "quantum.h"` appears at the top
     - `LAYOUT` macros should use standard definitions if applicable

docs/quantum_keycodes.md

@@ -14,3 +14,4 @@ On this page we have documented keycodes between `0x00FF` and `0xFFFF` which are
 |`QK_DEBUG_TOGGLE`|`DB_TOGG`|Toggle debug mode                                                                |
 |`QK_CLEAR_EEPROM`|`EE_CLR` |Reinitializes the keyboard's EEPROM (persistent memory)                          |
 |`QK_MAKE`        |         |Sends `qmk compile -kb (keyboard) -km (keymap)`, or `qmk flash` if shift is held |
+|`QK_REBOOT`      |`QK_RBT` |Resets the keyboard. Does not load the bootloader                                |

docs/quantum_painter.md

@@ -0,0 +1,705 @@
+# Quantum Painter :id=quantum-painter
+
+Quantum Painter is the standardised API for graphical displays. It currently includes support for basic drawing primitives, as well as custom images, animations, and fonts.
+
+Due to the complexity, there is no support for Quantum Painter on AVR-based boards.
+
+To enable overall Quantum Painter to be built into your firmware, add the following to `rules.mk`:
+
+```make
+QUANTUM_PAINTER_ENABLE = yes
+QUANTUM_PAINTER_DRIVERS = ......
+```
+
+You will also likely need to select an appropriate driver in `rules.mk`, which is listed below.
+
+!> Quantum Painter is not currently integrated with system-level operations such as disabling displays after a configurable timeout, or when the keyboard goes into suspend. Users will need to handle this manually at the current time.
+
+The QMK CLI can be used to convert from normal images such as PNG files or animated GIFs, as well as fonts from TTF files.
+
+Hardware supported:
+
+| Display Panel | Panel Type         | Size             | Comms Transport | Driver                                  |
+|---------------|--------------------|------------------|-----------------|-----------------------------------------|
+| GC9A01        | RGB LCD (circular) | 240x240          | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS = gc9a01_spi`  |
+| ILI9163       | RGB LCD            | 128x128          | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS = ili9163_spi` |
+| ILI9341       | RGB LCD            | 240x320          | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS = ili9341_spi` |
+| SSD1351       | RGB OLED           | 128x128          | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS = ssd1351_spi` |
+| ST7789        | RGB LCD            | 240x320, 240x240 | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS = st7789_spi`  |
+
+## Quantum Painter Configuration :id=quantum-painter-config
+
+| Option                                  | Default | Purpose                                                                                                                                     |
+|-----------------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------|
+| `QUANTUM_PAINTER_NUM_IMAGES`            | `8`     | The maximum number of images/animations that can be loaded at any one time.                                                                 |
+| `QUANTUM_PAINTER_NUM_FONTS`             | `4`     | The maximum number of fonts that can be loaded at any one time.                                                                             |
+| `QUANTUM_PAINTER_CONCURRENT_ANIMATIONS` | `4`     | The maximum number of animations that can be executed at the same time.                                                                     |
+| `QUANTUM_PAINTER_LOAD_FONTS_TO_RAM`     | `FALSE` | Whether or not fonts should be loaded to RAM. Relevant for fonts stored in off-chip persistent storage, such as external flash.             |
+| `QUANTUM_PAINTER_PIXDATA_BUFFER_SIZE`   | `32`    | The limit of the amount of pixel data that can be transmitted in one transaction to the display. Higher values require more RAM on the MCU. |
+| `QUANTUM_PAINTER_SUPPORTS_256_PALETTE`  | `FALSE` | If 256-color palettes are supported. Requires significantly more RAM on the MCU.                                                            |
+| `QUANTUM_PAINTER_DEBUG`                 | _unset_ | Prints out significant amounts of debugging information to CONSOLE output. Significant performance degradation, use only for debugging.     |
+
+Drivers have their own set of configurable options, and are described in their respective sections.
+
+## Quantum Painter CLI Commands :id=quantum-painter-cli
+
+### `qmk painter-convert-graphics`
+
+This command converts images to a format usable by QMK, i.e. the QGF File Format.
+
+**Usage**:
+
+```
+usage: qmk painter-convert-graphics [-h] [-d] [-r] -f FORMAT [-o OUTPUT] -i INPUT [-v]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -d, --no-deltas       Disables the use of delta frames when encoding animations.
+  -r, --no-rle          Disables the use of RLE when encoding images.
+  -f FORMAT, --format FORMAT
+                        Output format, valid types: pal256, pal16, pal4, pal2, mono256, mono16, mono4, mono2
+  -o OUTPUT, --output OUTPUT
+                        Specify output directory. Defaults to same directory as input.
+  -i INPUT, --input INPUT
+                        Specify input graphic file.
+  -v, --verbose         Turns on verbose output.
+```
+
+The `INPUT` argument can be any image file loadable by Python's Pillow module. Common formats include PNG, or Animated GIF.
+
+The `OUTPUT` argument needs to be a directory, and will default to the same directory as the input argument.
+
+The `FORMAT` argument can be any of the following:
+
+| Format    | Meaning                                                               |
+|-----------|-----------------------------------------------------------------------|
+| `pal256`  | 256-color palette (requires `QUANTUM_PAINTER_SUPPORTS_256_PALETTE`)   |
+| `pal16`   | 16-color palette                                                      |
+| `pal4`    | 4-color palette                                                       |
+| `pal2`    | 2-color palette                                                       |
+| `mono256` | 256-shade grayscale (requires `QUANTUM_PAINTER_SUPPORTS_256_PALETTE`) |
+| `mono16`  | 16-shade grayscale                                                    |
+| `mono4`   | 4-shade grayscale                                                     |
+| `mono2`   | 2-shade grayscale                                                     |
+
+**Examples**:
+
+```
+$ cd /home/qmk/qmk_firmware/keyboards/my_keeb
+$ qmk painter-convert-graphics -f mono16 -i my_image.gif -o ./generated/
+Writing /home/qmk/qmk_firmware/keyboards/my_keeb/generated/my_image.qgf.h...
+Writing /home/qmk/qmk_firmware/keyboards/my_keeb/generated/my_image.qgf.c...
+```
+
+### `qmk painter-make-font-image`
+
+This command converts a TTF font to an intermediate format for editing, before converting to the QFF File Format.
+
+**Usage**:
+
+```
+usage: qmk painter-make-font-image [-h] [-a] [-u UNICODE_GLYPHS] [-n] [-s SIZE] -o OUTPUT -f FONT
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -a, --no-aa           Disable anti-aliasing on fonts.
+  -u UNICODE_GLYPHS, --unicode-glyphs UNICODE_GLYPHS
+                        Also generate the specified unicode glyphs.
+  -n, --no-ascii        Disables output of the full ASCII character set (0x20..0x7E), exporting only the glyphs specified.
+  -s SIZE, --size SIZE  Specify font size. Default 12.
+  -o OUTPUT, --output OUTPUT
+                        Specify output image path.
+  -f FONT, --font FONT  Specify input font file.
+```
+
+The `FONT` argument is generally a TrueType Font file (TTF).
+
+The `OUTPUT` argument is the output image to generate, generally something like `my_font.png`.
+
+The `UNICODE_GLYPHS` argument allows for specifying extra unicode glyphs to generate, and accepts a string.
+
+**Examples**:
+
+```
+$ qmk painter-make-font-image --font NotoSans-ExtraCondensedBold.ttf --size 11 -o noto11.png --unicode-glyphs "ĄȽɂɻɣɈʣ"
+```
+
+### `qmk painter-convert-font-image`
+
+This command converts an intermediate font image to the QFF File Format.
+
+This command expects an image that conforms to the following format:
+
+* Top-left pixel (at `0,0`) is the "delimiter" color:
+    * Each glyph in the font starts when a pixel of this color is found on the first row
+    * The first row is discarded when converting to the QFF format
+* The number of delimited glyphs must match the supplied arguments to the command:
+    * The full ASCII set `0x20..0x7E` (if `--no-ascii` was not specified)
+    * The corresponding number of unicode glyphs if any were specified with `--unicode-glyphs`
+* The order of the glyphs matches the ASCII set, if any, followed by the Unicode glyph set, if any.
+
+**Usage**:
+
+```
+usage: qmk painter-convert-font-image [-h] [-r] -f FORMAT [-u UNICODE_GLYPHS] [-n] [-o OUTPUT] [-i INPUT]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -r, --no-rle          Disable the use of RLE to minimise converted image size.
+  -f FORMAT, --format FORMAT
+                        Output format, valid types: pal256, pal16, pal4, pal2, mono256, mono16, mono4, mono2
+  -u UNICODE_GLYPHS, --unicode-glyphs UNICODE_GLYPHS
+                        Also generate the specified unicode glyphs.
+  -n, --no-ascii        Disables output of the full ASCII character set (0x20..0x7E), exporting only the glyphs specified.
+  -o OUTPUT, --output OUTPUT
+                        Specify output directory. Defaults to same directory as input.
+  -i INPUT, --input INPUT
+                        Specify input graphic file.
+```
+
+The same arguments for `--no-ascii` and `--unicode-glyphs` need to be specified, as per `qmk painter-make-font-image`.
+
+**Examples**:
+
+```
+$ cd /home/qmk/qmk_firmware/keyboards/my_keeb
+$ qmk painter-convert-font-image --input noto11.png -f mono4 --unicode-glyphs "ĄȽɂɻɣɈʣ"
+Writing /home/qmk/qmk_firmware/keyboards/my_keeb/generated/noto11.qff.h...
+Writing /home/qmk/qmk_firmware/keyboards/my_keeb/generated/noto11.qff.c...
+```
+
+## Quantum Painter Drawing API :id=quantum-painter-api
+
+All APIs require a `painter_device_t` object as their first parameter -- this object comes from the specific device initialisation, and instructions on creating it can be found in each driver's respective section.
+
+To use any of the APIs, you need to include `qp.h`:
+```c
+#include <qp.h>
+```
+
+### General Notes :id=quantum-painter-api-general
+
+The coordinate system used in Quantum Painter generally accepts `left`, `top`, `right`, and `bottom` instead of x/y/width/height, and each coordinate is inclusive of where pixels should be drawn. This is required as some datatypes used by display panels have a maximum value of `255` -- for any value or geometry extent that matches `256`, this would be represented as a `0`, instead.
+
+?> Drawing a horizontal line 8 pixels long, starting from 4 pixels inside the left side of the display, will need `left=4`, `right=11`.
+
+All color data matches the standard QMK HSV triplet definitions:
+
+* Hue is of the range `0...255` and is internally mapped to 0...360 degrees.
+* Saturation is of the range `0...255` and is internally mapped to 0...100% saturation.
+* Value is of the range `0...255` and is internally mapped to 0...100% brightness.
+
+?> Colors used in Quantum Painter are not subject to the RGB lighting CIE curve, if it is enabled.
+
+### Device Control :id=quantum-painter-api-device-control
+
+#### Display Initialisation :id=quantum-painter-api-init
+
+```c
+bool qp_init(painter_device_t device, painter_rotation_t rotation);
+```
+
+The `qp_init` function is used to initialise a display device after it has been created. This accepts a rotation parameter (`QP_ROTATION_0`, `QP_ROTATION_90`, `QP_ROTATION_180`, `QP_ROTATION_270`), which makes sure that the orientation of what's drawn on the display is correct.
+
+```c
+static painter_device_t display;
+void keyboard_post_init_kb(void) {
+    display = qp_make_.......;         // Create the display
+    qp_init(display, QP_ROTATION_0);   // Initialise the display
+}
+```
+
+#### Display Power :id=quantum-painter-api-power
+
+```c
+bool qp_power(painter_device_t device, bool power_on);
+```
+
+The `qp_power` function instructs the display whether or not the display panel should be on or off.
+
+!> If there is a separate backlight controlled through the normal QMK backlight API, this is not controlled by the `qp_power` function and needs to be manually handled elsewhere.
+
+```c
+static uint8_t last_backlight = 255;
+void suspend_power_down_user(void) {
+    if (last_backlight == 255) {
+        last_backlight = get_backlight_level();
+    }
+    backlight_set(0);
+    rgb_matrix_set_suspend_state(true);
+    qp_power(display, false);
+}
+
+void suspend_wakeup_init_user(void) {
+    qp_power(display, true);
+    rgb_matrix_set_suspend_state(false);
+    if (last_backlight != 255) {
+        backlight_set(last_backlight);
+    }
+    last_backlight = 255;
+}
+```
+
+#### Display Clear :id=quantum-painter-api-clear
+
+```c
+bool qp_clear(painter_device_t device);
+```
+
+The `qp_clear` function clears the display's screen.
+
+#### Display Flush :id=quantum-painter-api-flush
+
+```c
+bool qp_flush(painter_device_t device);
+```
+
+The `qp_flush` function ensures that all drawing operations are "pushed" to the display. This should be done as the last operation whenever a sequence of draws occur, and guarantees that any changes are applied.
+
+!> Some display panels may seem to work even without a call to `qp_flush` -- this may be because the driver cannot queue drawing operations and needs to display them immediately when invoked. In general, calling `qp_flush` at the end is still considered "best practice".
+
+```c
+void housekeeping_task_user(void) {
+    static uint32_t last_draw = 0;
+    if (timer_elapsed32(last_draw) > 33) { // Throttle to 30fps
+        last_draw = timer_read32();
+        // Draw a rect based off the current RGB color
+        qp_rect(display, 0, 7, 0, 239, rgb_matrix_get_hue(), 255, 255);
+        qp_flush(display);
+    }
+}
+```
+
+### Drawing Primitives :id=quantum-painter-api-primitives
+
+#### Set Pixel :id=quantum-painter-api-setpixel
+
+```c
+bool qp_setpixel(painter_device_t device, uint16_t x, uint16_t y, uint8_t hue, uint8_t sat, uint8_t val);
+```
+
+The `qp_setpixel` can be used to set a specific pixel on the screen to the supplied color.
+
+?> Using `qp_setpixel` for large amounts of drawing operations is inefficient and should be avoided unless they cannot be achieved with other drawing APIs.
+
+```c
+void housekeeping_task_user(void) {
+    static uint32_t last_draw = 0;
+    if (timer_elapsed32(last_draw) > 33) { // Throttle to 30fps
+        last_draw = timer_read32();
+        // Draw a 240px high vertical rainbow line on X=0:
+        for (int i = 0; i < 239; ++i) {
+            qp_setpixel(display, 0, i, i, 255, 255);
+        }
+        qp_flush(display);
+    }
+}
+```
+
+#### Draw Line :id=quantum-painter-api-line
+
+```c
+bool qp_line(painter_device_t device, uint16_t x0, uint16_t y0, uint16_t x1, uint16_t y1, uint8_t hue, uint8_t sat, uint8_t val);
+```
+
+The `qp_line` can be used to draw lines on the screen with the supplied color.
+
+```c
+void housekeeping_task_user(void) {
+    static uint32_t last_draw = 0;
+    if (timer_elapsed32(last_draw) > 33) { // Throttle to 30fps
+        last_draw = timer_read32();
+        // Draw 8px-wide rainbow down the left side of the display
+        for (int i = 0; i < 239; ++i) {
+            qp_line(display, 0, i, 7, i, i, 255, 255);
+        }
+        qp_flush(display);
+    }
+}
+```
+
+#### Draw Rect :id=quantum-painter-api-rect
+
+```c
+bool qp_rect(painter_device_t device, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint8_t hue, uint8_t sat, uint8_t val, bool filled);
+```
+
+The `qp_rect` can be used to draw rectangles on the screen with the supplied color, with or without a background fill. If not filled, any pixels inside the rectangle will be left as-is.
+
+```c
+void housekeeping_task_user(void) {
+    static uint32_t last_draw = 0;
+    if (timer_elapsed32(last_draw) > 33) { // Throttle to 30fps
+        last_draw = timer_read32();
+        // Draw 8px-wide rainbow filled rectangles down the left side of the display
+        for (int i = 0; i < 239; i+=8) {
+            qp_rect(display, 0, i, 7, i+7, i, 255, 255, true);
+        }
+        qp_flush(display);
+    }
+}
+```
+
+#### Draw Circle :id=quantum-painter-api-circle
+
+```c
+bool qp_circle(painter_device_t device, uint16_t x, uint16_t y, uint16_t radius, uint8_t hue, uint8_t sat, uint8_t val, bool filled);
+```
+
+The `qp_circle` can be used to draw circles on the screen with the supplied color, with or without a background fill. If not filled, any pixels inside the circle will be left as-is.
+
+```c
+void housekeeping_task_user(void) {
+    static uint32_t last_draw = 0;
+    if (timer_elapsed32(last_draw) > 33) { // Throttle to 30fps
+        last_draw = timer_read32();
+        // Draw r=4 filled circles down the left side of the display
+        for (int i = 0; i < 239; i+=8) {
+            qp_circle(display, 4, 4+i, 4, i, 255, 255, true);
+        }
+        qp_flush(display);
+    }
+}
+```
+
+#### Draw Ellipse :id=quantum-painter-api-ellipse
+
+```c
+bool qp_ellipse(painter_device_t device, uint16_t x, uint16_t y, uint16_t sizex, uint16_t sizey, uint8_t hue, uint8_t sat, uint8_t val, bool filled);
+```
+
+The `qp_ellipse` can be used to draw ellipses on the screen with the supplied color, with or without a background fill. If not filled, any pixels inside the ellipses will be left as-is.
+
+```c
+void housekeeping_task_user(void) {
+    static uint32_t last_draw = 0;
+    if (timer_elapsed32(last_draw) > 33) { // Throttle to 30fps
+        last_draw = timer_read32();
+        // Draw 16x8 filled ellipses down the left side of the display
+        for (int i = 0; i < 239; i+=8) {
+            qp_ellipse(display, 8, 4+i, 16, 8, i, 255, 255, true);
+        }
+        qp_flush(display);
+    }
+}
+```
+
+### Image Functions :id=quantum-painter-api-images
+
+#### Load Image :id=quantum-painter-api-load-image
+
+```c
+painter_image_handle_t qp_load_image_mem(const void *buffer);
+```
+
+The `qp_load_image_mem` function loads a QGF image from memory or flash.
+
+`qp_load_image_mem` returns a handle to the loaded image, which can then be used to draw to the screen using `qp_drawimage`, `qp_drawimage_recolor`, `qp_animate`, or `qp_animate_recolor`. If an image is no longer required, it can be unloaded by calling `qp_close_image` below. 
+
+See the [CLI Commands](quantum_painter.md?id=quantum-painter-cli) for instructions on how to convert images to [QGF](quantum_painter_qgf.md).
+
+?> The total number of images available to load at any one time is controlled by the configurable option `QUANTUM_PAINTER_NUM_IMAGES` in the table above. If more images are required, the number should be increased in `config.h`.
+
+Image information is available through accessing the handle:
+
+| Property    | Accessor             |
+|-------------|----------------------|
+| Width       | `image->width`       |
+| Height      | `image->height`      |
+| Frame Count | `image->frame_count` |
+
+#### Unload Image :id=quantum-painter-api-close-image
+
+```c
+bool qp_close_image(painter_image_handle_t image);
+```
+
+The `qp_close_image` function releases resources related to the loading of the supplied image.
+
+#### Draw image :id=quantum-painter-api-draw-image
+
+```c
+bool qp_drawimage(painter_device_t device, uint16_t x, uint16_t y, painter_image_handle_t image);
+bool qp_drawimage_recolor(painter_device_t device, uint16_t x, uint16_t y, painter_image_handle_t image, uint8_t hue_fg, uint8_t sat_fg, uint8_t val_fg, uint8_t hue_bg, uint8_t sat_bg, uint8_t val_bg);
+```
+
+The `qp_drawimage` and `qp_drawimage_recolor` functions draw the supplied image to the screen at the supplied location, with the latter function allowing for monochrome-based images to be recolored.
+
+```c
+// Draw an image on the bottom-right of the 240x320 display on initialisation
+static painter_image_handle_t my_image;
+void keyboard_post_init_kb(void) {
+    my_image = qp_load_image_mem(gfx_my_image);
+    if (my_image != NULL) {
+        qp_drawimage(display, (239 - my_image->width), (319 - my_image->height), my_image);
+    }
+}
+```
+
+#### Animate Image :id=quantum-painter-api-animate-image
+
+```c
+deferred_token qp_animate(painter_device_t device, uint16_t x, uint16_t y, painter_image_handle_t image);
+deferred_token qp_animate_recolor(painter_device_t device, uint16_t x, uint16_t y, painter_image_handle_t image, uint8_t hue_fg, uint8_t sat_fg, uint8_t val_fg, uint8_t hue_bg, uint8_t sat_bg, uint8_t val_bg);
+```
+
+The `qp_animate` and `qp_animate_recolor` functions draw the supplied image to the screen at the supplied location, with the latter function allowing for monochrome-based animations to be recolored. They also set up internal timing such that each frame is rendered at the correct time as per the animated image.
+
+Once an image has been set to animate, it will loop indefinitely until stopped, with no user intervention required.
+
+Both functions return a `deferred_token`, which can then be used to stop the animation, using `qp_stop_animation` below.
+
+```c
+// Animate an image on the bottom-right of the 240x320 display on initialisation
+static painter_image_handle_t my_image;
+static deferred_token my_anim;
+void keyboard_post_init_kb(void) {
+    my_image = qp_load_image_mem(gfx_my_image);
+    if (my_image != NULL) {
+        my_anim = qp_animate(display, (239 - my_image->width), (319 - my_image->height), my_image);
+    }
+}
+```
+
+#### Stop Animation :id=quantum-painter-api-stop-animation
+
+```c
+void qp_stop_animation(deferred_token anim_token);
+```
+
+The `qp_stop_animation` function stops the previously-started animation.
+```c
+void housekeeping_task_user(void) {
+    if (some_random_stop_reason) {
+        qp_stop_animation(my_anim);
+    }
+}
+```
+
+### Font Functions :id=quantum-painter-api-fonts
+
+#### Load Font :id=quantum-painter-api-load-font
+
+```c
+painter_font_handle_t qp_load_font_mem(const void *buffer);
+```
+
+The `qp_load_font_mem` function loads a QFF font from memory or flash.
+
+`qp_load_font_mem` returns a handle to the loaded font, which can then be measured using `qp_textwidth`, or drawn to the screen using `qp_drawtext`, or `qp_drawtext_recolor`. If a font is no longer required, it can be unloaded by calling `qp_close_font` below. 
+
+See the [CLI Commands](quantum_painter.md?id=quantum-painter-cli) for instructions on how to convert TTF fonts to [QFF](quantum_painter_qff.md).
+
+?> The total number of fonts available to load at any one time is controlled by the configurable option `QUANTUM_PAINTER_NUM_FONTS` in the table above. If more fonts are required, the number should be increased in `config.h`.
+
+Font information is available through accessing the handle:
+
+| Property    | Accessor             |
+|-------------|----------------------|
+| Line Height | `image->line_height` |
+
+#### Unload Font :id=quantum-painter-api-close-font
+
+```c
+bool qp_close_font(painter_font_handle_t font);
+```
+
+The `qp_close_font` function releases resources related to the loading of the supplied font.
+
+#### Measure Text :id=quantum-painter-api-textwidth
+
+```c
+int16_t qp_textwidth(painter_font_handle_t font, const char *str);
+```
+
+The `qp_textwidth` function allows measurement of how many pixels wide the supplied string would result in, for the given font.
+
+#### Draw Text :id=quantum-painter-api-drawtext
+
+```c
+int16_t qp_drawtext(painter_device_t device, uint16_t x, uint16_t y, painter_font_handle_t font, const char *str);
+int16_t qp_drawtext_recolor(painter_device_t device, uint16_t x, uint16_t y, painter_font_handle_t font, const char *str, uint8_t hue_fg, uint8_t sat_fg, uint8_t val_fg, uint8_t hue_bg, uint8_t sat_bg, uint8_t val_bg);
+```
+
+The `qp_drawtext` and `qp_drawtext_recolor` functions draw the supplied string to the screen at the given location using the font supplied, with the latter function allowing for monochrome-based fonts to be recolored.
+
+```c
+// Draw a text message on the bottom-right of the 240x320 display on initialisation
+static painter_font_handle_t my_font;
+void keyboard_post_init_kb(void) {
+    my_font = qp_load_font_mem(font_opensans);
+    if (my_font != NULL) {
+        static const char *text = "Hello from QMK!";
+        int16_t width = qp_textwidth(my_font, text);
+        qp_drawtext(display, (239 - width), (319 - my_font->line_height), my_font, text);
+    }
+}
+```
+
+### Advanced Functions :id=quantum-painter-api-advanced
+
+#### Get Geometry :id=quantum-painter-api-get-geometry
+
+```c
+void qp_get_geometry(painter_device_t device, uint16_t *width, uint16_t *height, painter_rotation_t *rotation, uint16_t *offset_x, uint16_t *offset_y);
+```
+
+The `qp_get_geometry` function allows external code to retrieve the current width, height, rotation, and drawing offsets.
+
+#### Set Viewport Offsets :id=quantum-painter-api-set-viewport
+
+```c
+void qp_set_viewport_offsets(painter_device_t device, uint16_t offset_x, uint16_t offset_y);
+```
+
+The `qp_set_viewport_offsets` function can be used to offset all subsequent drawing operations. For example, if a display controller is internally 240x320, but the display panel is 240x240 and has a Y offset of 80 pixels, you could invoke `qp_set_viewport_offsets(display, 0, 80);` and the drawing positioning would be corrected.
+
+#### Set Viewport :id=quantum-painter-api-viewport
+
+```c
+bool qp_viewport(painter_device_t device, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom);
+```
+
+The `qp_viewport` function controls where raw pixel data is written to.
+
+#### Stream Pixel Data :id=quantum-painter-api-pixdata
+
+```c
+bool qp_pixdata(painter_device_t device, const void *pixel_data, uint32_t native_pixel_count);
+```
+
+The `qp_pixdata` function allows raw pixel data to be streamed to the display. It requires a native pixel count rather than the number of bytes to transfer, to ensure display panel data alignment is respected. E.g. for display panels using RGB565 internal format, sending 10 pixels will result in 20 bytes of transfer.
+
+!> Under normal circumstances, users will not need to manually call either `qp_viewport` or `qp_pixdata`. These allow for writing of raw pixel information, in the display panel's native format, to the area defined by the viewport.
+
+## Quantum Painter Display Drivers :id=quantum-painter-drivers
+
+### Common: Standard TFT (SPI + D/C + RST)
+
+Most TFT display panels use a 5-pin interface -- SPI SCK, SPI MOSI, SPI CS, D/C, and RST pins.
+
+For these displays, QMK's `spi_master` must already be correctly configured for the platform you're building for.
+
+The pin assignments for SPI CS, D/C, and RST are specified during device construction.
+
+### GC9A01 :id=qp-driver-gc9a01
+
+Enabling support for the GC9A01 in Quantum Painter is done by adding the following to `rules.mk`:
+
+```make
+QUANTUM_PAINTER_ENABLE = yes
+QUANTUM_PAINTER_DRIVERS = gc9a01_spi
+```
+
+Creating a GC9A01 device in firmware can then be done with the following API:
+
+```c
+painter_device_t qp_gc9a01_make_spi_device(uint16_t panel_width, uint16_t panel_height, pin_t chip_select_pin, pin_t dc_pin, pin_t reset_pin, uint16_t spi_divisor, int spi_mode);
+```
+
+The device handle returned from the `qp_gc9a01_make_spi_device` function can be used to perform all other drawing operations.
+
+The maximum number of displays can be configured by changing the following in your `config.h` (default is 1):
+
+```c
+// 3 displays:
+#define GC9A01_NUM_DEVICES 3
+```
+
+### ILI9163 :id=qp-driver-ili9163
+
+Enabling support for the ILI9163 in Quantum Painter is done by adding the following to `rules.mk`:
+
+```make
+QUANTUM_PAINTER_ENABLE = yes
+QUANTUM_PAINTER_DRIVERS = ili9163_spi
+```
+
+Creating a ILI9163 device in firmware can then be done with the following API:
+
+```c
+painter_device_t qp_ili9163_make_spi_device(uint16_t panel_width, uint16_t panel_height, pin_t chip_select_pin, pin_t dc_pin, pin_t reset_pin, uint16_t spi_divisor, int spi_mode);
+```
+
+The device handle returned from the `qp_ili9163_make_spi_device` function can be used to perform all other drawing operations.
+
+The maximum number of displays can be configured by changing the following in your `config.h` (default is 1):
+
+```c
+// 3 displays:
+#define ILI9163_NUM_DEVICES 3
+```
+
+### ILI9341 :id=qp-driver-ili9341
+
+Enabling support for the ILI9341 in Quantum Painter is done by adding the following to `rules.mk`:
+
+```make
+QUANTUM_PAINTER_ENABLE = yes
+QUANTUM_PAINTER_DRIVERS = ili9341_spi
+```
+
+Creating a ILI9341 device in firmware can then be done with the following API:
+
+```c
+painter_device_t qp_ili9341_make_spi_device(uint16_t panel_width, uint16_t panel_height, pin_t chip_select_pin, pin_t dc_pin, pin_t reset_pin, uint16_t spi_divisor, int spi_mode);
+```
+
+The device handle returned from the `qp_ili9341_make_spi_device` function can be used to perform all other drawing operations.
+
+The maximum number of displays can be configured by changing the following in your `config.h` (default is 1):
+
+```c
+// 3 displays:
+#define ILI9341_NUM_DEVICES 3
+```
+
+### SSD1351 :id=qp-driver-ssd1351
+
+Enabling support for the SSD1351 in Quantum Painter is done by adding the following to `rules.mk`:
+
+```make
+QUANTUM_PAINTER_ENABLE = yes
+QUANTUM_PAINTER_DRIVERS = ssd1351_spi
+```
+
+Creating a SSD1351 device in firmware can then be done with the following API:
+
+```c
+painter_device_t qp_ssd1351_make_spi_device(uint16_t panel_width, uint16_t panel_height, pin_t chip_select_pin, pin_t dc_pin, pin_t reset_pin, uint16_t spi_divisor, int spi_mode);
+```
+
+The device handle returned from the `qp_ssd1351_make_spi_device` function can be used to perform all other drawing operations.
+
+The maximum number of displays can be configured by changing the following in your `config.h` (default is 1):
+
+```c
+// 3 displays:
+#define SSD1351_NUM_DEVICES 3
+```
+
+### ST7789 :id=qp-driver-st7789
+
+Enabling support for the ST7789 in Quantum Painter is done by adding the following to `rules.mk`:
+
+```make
+QUANTUM_PAINTER_ENABLE = yes
+QUANTUM_PAINTER_DRIVERS = st7789_spi
+```
+
+Creating a ST7789 device in firmware can then be done with the following API:
+
+```c
+painter_device_t qp_st7789_make_spi_device(uint16_t panel_width, uint16_t panel_height, pin_t chip_select_pin, pin_t dc_pin, pin_t reset_pin, uint16_t spi_divisor, int spi_mode);
+```
+
+The device handle returned from the `qp_st7789_make_spi_device` function can be used to perform all other drawing operations.
+
+The maximum number of displays can be configured by changing the following in your `config.h` (default is 1):
+
+```c
+// 3 displays:
+#define ST7789_NUM_DEVICES 3
+```
+
+!> Some ST7789 devices are known to have different drawing offsets -- despite being a 240x320 pixel display controller internally, some display panels are only 240x240, or smaller. These may require an offset to be applied; see `qp_set_viewport_offsets` above for information on how to override the offsets if they aren't correctly rendered.

docs/quantum_painter_qff.md

@@ -0,0 +1,103 @@
+# QMK Font Format :id=qmk-font-format
+
+QMK uses a font format _("Quantum Font Format" - QFF)_ specifically for resource-constrained systems.
+
+This format is capable of encoding 1-, 2-, 4-, and 8-bit-per-pixel greyscale- and palette-based images into a font. It also includes RLE for pixel data for some basic compression.
+
+All integer values are in little-endian format.
+
+The QFF is defined in terms of _blocks_ -- each _block_ contains a _header_ and an optional _blob_ of data. The _header_ contains the block's _typeid_, and the length of the _blob_ that follows. Each block type is denoted by a different _typeid_ has its own block definition below. All blocks are defined as packed structs, containing zero padding between fields.
+
+The general structure of the file is:
+
+* _Font descriptor block_
+* _ASCII glyph block_ (optional, only if ASCII glyphs are included)
+* _Unicode glyph block_ (optional, only if Unicode glyphs are included)
+* _Font palette block_ (optional, depending on frame format)
+* _Font data block_
+
+## Block Header :id=qff-block-header
+
+The block header is identical to [QGF's block header](quantum_painter_qgf.md#qgf-block-header), and is present for all blocks, including the font descriptor.
+
+## Font descriptor block :id=qff-font-descriptor
+
+* _typeid_ = 0x00
+* _length_ = 20
+
+This block must be located at the start of the file contents, and can exist a maximum of once in an entire QGF file. It is always followed by either the _ASCII glyph table_ or the _Unicode glyph table_, depending on which glyphs are included in the font.
+
+_Block_ format:
+
+```c
+typedef struct __attribute__((packed)) qff_font_descriptor_v1_t {
+    qgf_block_header_v1_t header;               // = { .type_id = 0x00, .neg_type_id = (~0x00), .length = 20 }
+    uint24_t              magic;                // constant, equal to 0x464651 ("QFF")
+    uint8_t               qff_version;          // constant, equal to 0x01
+    uint32_t              total_file_size;      // total size of the entire file, starting at offset zero
+    uint32_t              neg_total_file_size;  // negated value of total_file_size, used for detecting parsing errors
+    uint8_t               line_height;          // glyph height in pixels
+    bool                  has_ascii_table;      // whether the font has an ascii table of glyphs (0x20...0x7E)
+    uint16_t              num_unicode_glyphs;   // the number of glyphs in the unicode table -- no table specified if zero
+    uint8_t               format;               // frame format, see below.
+    uint8_t               flags;                // frame flags, see below.
+    uint8_t               compression_scheme;   // compression scheme, see below.
+    uint8_t               transparency_index;   // palette index used for transparent pixels (not yet implemented)
+} qff_font_descriptor_v1_t;
+// _Static_assert(sizeof(qff_font_descriptor_v1_t) == (sizeof(qgf_block_header_v1_t) + 20), "qff_font_descriptor_v1_t must be 25 bytes in v1 of QFF");
+```
+
+The values for `format`, `flags`, `compression_scheme`, and `transparency_index` match [QGF's frame descriptor block](quantum_painter_qgf.md#qgf-frame-descriptor), with the exception that the `delta` flag is ignored by QFF.
+
+## ASCII glyph table :id=qff-ascii-table
+
+* _typeid_ = 0x01
+* _length_ = 290
+
+If the font contains ascii characters, the _ASCII glyph block_ must be located directly after the _font descriptor block_.
+
+```c
+#define QFF_GLYPH_WIDTH_BITS 6
+#define QFF_GLYPH_WIDTH_MASK ((1<<QFF_GLYPH_WIDTH_BITS)-1)
+#define QFF_GLYPH_OFFSET_BITS 18
+#define QFF_GLYPH_OFFSET_MASK (((1<<QFF_GLYPH_OFFSET_BITS)-1) << QFF_GLYPH_WIDTH_BITS)
+
+typedef struct __attribute__((packed)) qff_ascii_glyph_table_v1_t {
+    qgf_block_header_v1_t header;  // = { .type_id = 0x01, .neg_type_id = (~0x01), .length = 285 }
+    uint24_t glyph[95];            // 95 glyphs, 0x20..0x7E, see bits/masks above for values
+} qff_ascii_glyph_table_v1_t;
+// _Static_assert(sizeof(qff_ascii_glyph_table_v1_t) == (sizeof(qgf_block_header_v1_t) + 285), "qff_ascii_glyph_table_v1_t must be 290 bytes in v1 of QFF");
+```
+
+## Unicode glyph table :id=qff-unicode-table
+
+* _typeid_ = 0x02
+* _length_ = variable
+
+If this font contains unicode characters, the _unicode glyph block_ must be located directly after the _ASCII glyph table block_, or the _font descriptor block_ if the font does not contain ASCII characters.
+
+```c
+typedef struct __attribute__((packed)) qff_unicode_glyph_table_v1_t {
+    qgf_block_header_v1_t header;     // = { .type_id = 0x02, .neg_type_id = (~0x02), .length = (N * 6) }
+    struct __attribute__((packed)) {  // container for a single unicode glyph
+        uint24_t code_point;          // the unicode code point
+        uint24_t glyph;               // the glyph information, as per ASCII glyphs above
+    } glyph[N];                       // N glyphs worth of data
+} qff_unicode_glyph_table_v1_t;
+```
+
+## Font palette block :id=qff-palette-descriptor
+
+* _typeid_ = 0x03
+* _length_ = variable
+
+The _font palette block_ is identical to [QGF's frame palette block](quantum_painter_qgf.md#qgf-frame-palette-descriptor), retaining the same _typeid_ of 0x03.
+
+It is only specified in the QFF if the font is palette-based, and follows the _unicode glyph block_ if the font contains any Unicode glyphs, or the _ASCII glyph block_ if the font contains only ASCII glyphs.
+
+## Font data block :id=qff-data-descriptor
+
+* _typeid_ = 0x04
+* _length_ = variable
+
+The _font data block_ is the last block in the file and is identical to [QGF's frame data block](quantum_painter_qgf.md#qgf-frame-data-descriptor), however has a different _typeid_ of 0x04 in QFF.

docs/quantum_painter_qgf.md

@@ -0,0 +1,178 @@
+# QMK Graphics Format :id=qmk-graphics-format
+
+QMK uses a graphics format _("Quantum Graphics Format" - QGF)_ specifically for resource-constrained systems.
+
+This format is capable of encoding 1-, 2-, 4-, and 8-bit-per-pixel greyscale- and palette-based images. It also includes RLE for pixel data for some basic compression.
+
+All integer values are in little-endian format.
+
+The QGF is defined in terms of _blocks_ -- each _block_ contains a _header_ and an optional _blob_ of data. The _header_ contains the block's _typeid_, and the length of the _blob_ that follows. Each block type is denoted by a different _typeid_ has its own block definition below. All blocks are defined as packed structs, containing zero padding between fields.
+
+The general structure of the file is:
+
+* _Graphics descriptor block_
+* _Frame offset block_
+* Repeating list of frames:
+    * _Frame descriptor block_
+    * _Frame palette block_ (optional, depending on frame format)
+    * _Frame delta block_ (optional, depending on delta flag)
+    * _Frame data block_
+
+Different frames within the file should be considered "isolated" and may have their own image format and/or palette.
+
+## Block Header :id=qgf-block-header
+
+This block header is present for all blocks, including the graphics descriptor.
+
+_Block header_ format:
+
+```c
+typedef struct __attribute__((packed)) qgf_block_header_v1_t {
+    uint8_t type_id;      // See each respective block type
+    uint8_t neg_type_id;  // Negated type ID, used for detecting parsing errors
+    uint24_t length;      // 24-bit blob length, allowing for block sizes of a maximum of 16MB
+} qgf_block_header_v1_t;
+// _Static_assert(sizeof(qgf_block_header_v1_t) == 5, "qgf_block_header_v1_t must be 5 bytes in v1 of QGF");
+```
+The _length_ describes the number of octets in the data following the block header -- a block header may specify a _length_ of `0` if no blob is specified.
+
+## Graphics descriptor block :id=qgf-graphics-descriptor
+
+* _typeid_ = 0x00
+* _length_ = 18
+
+This block must be located at the start of the file contents, and can exist a maximum of once in an entire QGF file. It is always followed by the _frame offset block_.
+
+_Block_ format:
+
+```c
+typedef struct __attribute__((packed)) qgf_graphics_descriptor_v1_t {
+    qgf_block_header_v1_t header;               // = { .type_id = 0x00, .neg_type_id = (~0x00), .length = 18 }
+    uint24_t              magic;                // constant, equal to 0x464751 ("QGF")
+    uint8_t               qgf_version;          // constant, equal to 0x01
+    uint32_t              total_file_size;      // total size of the entire file, starting at offset zero
+    uint32_t              neg_total_file_size;  // negated value of total_file_size, used for detecting parsing errors
+    uint16_t              image_width;          // in pixels
+    uint16_t              image_height;         // in pixels
+    uint16_t              frame_count;          // minimum of 1
+} qgf_graphics_descriptor_v1_t;
+// _Static_assert(sizeof(qgf_graphics_descriptor_v1_t) == (sizeof(qgf_block_header_v1_t) + 18), "qgf_graphics_descriptor_v1_t must be 23 bytes in v1 of QGF");
+```
+
+## Frame offset block :id=qgf-frame-offset-descriptor
+
+* _typeid_ = 0x01
+* _length_ = variable
+
+This block denotes the offsets within the file to each frame's _frame descriptor block_, relative to the start of the file. The _frame offset block_ always immediately follows the _graphics descriptor block_. The contents of this block are an array of U32's, with one entry for each frame.
+
+Duplicate frame offsets in this block are allowed, if a certain frame is to be shown multiple times during animation.
+
+_Block_ format:
+
+```c
+typedef struct __attribute__((packed)) qgf_frame_offsets_v1_t {
+    qgf_block_header_v1_t header;    // = { .type_id = 0x01, .neg_type_id = (~0x01), .length = (N * sizeof(uint32_t)) }
+    uint32_t              offset[N]; // where 'N' is the number of frames in the file
+} qgf_frame_offsets_v1_t;
+```
+
+## Frame descriptor block :id=qgf-frame-descriptor
+
+* _typeid_ = 0x02
+* _length_ = 5
+
+This block denotes the start of a frame.
+
+_Block_ format:
+
+```c
+typedef struct __attribute__((packed)) qgf_frame_v1_t {
+    qgf_block_header_v1_t header;              // = { .type_id = 0x02, .neg_type_id = (~0x02), .length = 5 }
+    uint8_t               format;              // Frame format, see below.
+    uint8_t               flags;               // Frame flags, see below.
+    uint8_t               compression_scheme;  // Compression scheme, see below.
+    uint8_t               transparency_index;  // palette index used for transparent pixels (not yet implemented)
+    uint16_t              delay;               // frame delay time for animations (in units of milliseconds)
+} qgf_frame_v1_t;
+// _Static_assert(sizeof(qgf_frame_v1_t) == (sizeof(qgf_block_header_v1_t) + 6), "qgf_frame_v1_t must be 11 bytes in v1 of QGF");
+```
+
+If this frame is grayscale, the _frame descriptor block_ (or _frame delta block_ if flags denote a delta frame) is immediately followed by this frame's corresponding _frame data block_.
+
+If the frame uses an indexed palette, the _frame descriptor block_ (or _frame delta block_ if flags denote a delta frame) is immediately followed by this frame's corresponding _frame palette block_.
+
+Frame format possible values:
+
+* `0x00`: 1bpp grayscale, no palette, `0` = black, `1` = white, LSb first pixel
+* `0x01`: 2bpp grayscale, no palette, `0` = black, `3` = white, linear interpolation of brightness, LSb first pixel
+* `0x02`: 4bpp grayscale, no palette, `0` = black, `15` = white, linear interpolation of brightness, LSb first pixel
+* `0x03`: 8bpp grayscale, no palette, `0` = black, `255` = white, linear interpolation of brightness, LSb first pixel
+* `0x04`: 1bpp indexed palette, 2 colors, LSb first pixel
+* `0x05`: 2bpp indexed palette, 4 colors, LSb first pixel
+* `0x06`: 4bpp indexed palette, 16 colors, LSb first pixel
+* `0x07`: 8bpp indexed palette, 256 colors, LSb first pixel
+
+Frame flags is a bitmask with the following format:
+
+| `bit 7` | `bit 6` | `bit 5` | `bit 4` | `bit 3` | `bit 2` | `bit 1` | `bit 0`      |
+|---------|---------|---------|---------|---------|---------|---------|--------------|
+| -       | -       | -       | -       | -       | -       | Delta   | Transparency |
+
+* `[1]` -- Delta: Signifies that the current frame is a delta frame, which specifies only a sub-image. The _frame delta block_ follows the _frame palette block_ if the image format specifies a palette, otherwise it directly follows the _frame descriptor block_.
+* `[0]` -- Transparency: The transparent palette index in the _blob_ is considered valid and should be used when considering which pixels should be transparent during rendering this frame, if possible.
+
+Compression scheme possible values:
+
+* `0x00`: No compression
+* `0x01`: [QMK RLE](quantum_painter_rle.md)
+
+## Frame palette block :id=qgf-frame-palette-descriptor
+
+* _typeid_ = 0x03
+* _length_ = variable
+
+This block describes the palette used for the frame. The _blob_ contains an array of palette entries -- one palette entry is present for each color used -- each palette entry is in QMK HSV888 format:
+
+```c
+typedef struct __attribute__((packed)) qgf_palette_v1_t {
+    qgf_block_header_v1_t header;     // = { .type_id = 0x03, .neg_type_id = (~0x03), .length = (N * 3 * sizeof(uint8_t)) }
+    struct {  // container for a single HSV palette entry
+        uint8_t h;                    // hue component: `[0,360)` degrees is mapped to `[0,255]` uint8_t.
+        uint8_t s;                    // saturation component: `[0,1]` is mapped to `[0,255]` uint8_t.
+        uint8_t v;                    // value component: `[0,1]` is mapped to `[0,255]` uint8_t.
+    } hsv[N];                         // N * hsv, where N is the number of palette entries depending on the frame format in the descriptor
+} qgf_palette_v1_t;
+```
+
+## Frame delta block :id=qgf-frame-delta-descriptor
+
+* _typeid_ = 0x04
+* _length_ = 8
+
+This block describes where the delta frame should be drawn, with respect to the top left location of the image.
+
+```c
+typedef struct __attribute__((packed)) qgf_delta_v1_t {
+    qgf_block_header_v1_t header;  // = { .type_id = 0x04, .neg_type_id = (~0x04), .length = 8 }
+    uint16_t left;                 // The left pixel location to draw the delta image
+    uint16_t top;                  // The top pixel location to draw the delta image
+    uint16_t right;                // The right pixel location to to draw the delta image
+    uint16_t bottom;               // The bottom pixel location to to draw the delta image
+} qgf_delta_v1_t;
+// _Static_assert(sizeof(qgf_delta_v1_t) == 13, "qgf_delta_v1_t must be 13 bytes in v1 of QGF");
+```
+
+## Frame data block :id=qgf-frame-data-descriptor
+
+* _typeid_ = 0x05
+* _length_ = variable
+
+This block describes the data associated with the frame. The _blob_ contains an array of bytes containing the data corresponding to the frame's image format:
+
+```c
+typedef struct __attribute__((packed)) qgf_data_v1_t {
+    qgf_block_header_v1_t header;   // = { .type_id = 0x05, .neg_type_id = (~0x05), .length = N }
+    uint8_t               data[N];  // N data octets
+} qgf_data_v1_t;
+```

docs/quantum_painter_rle.md

@@ -0,0 +1,29 @@
+# QMK QGF/QFF RLE data schema :id=qmk-qp-rle-schema
+
+There are two "modes" to the RLE algorithm used in both [QGF](quantum_painter_qgf.md)/[QFF](quantum_painter_qff.md):
+
+* Non-repeating sections of octets, with associated length of up to `128` octets
+    * `length` = `marker - 128`
+    * A corresponding `length` number of octets follow directly after the marker octet
+* Repeated octet with associated length, with associated length of up to `128`
+    * `length` = `marker`
+    * A single octet follows the marker that should be repeated `length` times.
+
+Decoder pseudocode:
+```
+while !EOF
+    marker = READ_OCTET()
+
+    if marker >= 128
+        length = marker - 128
+        for i = 0 ... length-1
+            c = READ_OCTET()
+            WRITE_OCTET(c)
+
+    else
+        length = marker
+        c = READ_OCTET()
+        for i = 0 ... length-1
+            WRITE_OCTET(c)
+
+```

docs/ref_functions.md

@@ -87,9 +87,13 @@ To configure the default layer sounds, you would want to define this in your `co
 
 ## Resetting the keyboard
 
-There is the `RESET` quantum keycode that you can use. But if you want to reset the board as part of a macro, rather than hitting a key separately, you can do that.
+There is the `QK_REBOOT` or `QK_RBT` quantum keycode that you can use. But if you want to reset the board as part of a macro, rather than hitting a key separately, you can do that.
 
-And to do so, add `reset_keyboard()` to your function or macro, and this will reset to bootloader.
+And to do so, add `soft_reset_keyboard()` to your function or macro.
+
+## Reset to bootloader
+
+To reset to the bootloader use `QK_BOOTLOADER` or `QK_BOOT` keycode or `reset_keyboard()` function.
 
 ## Wiping the EEPROM (Persistent Storage)
 

docs/reference_info_json.md

@@ -89,7 +89,7 @@ Example:
 
 Direct pins are when you connect one side of the switch to GND and the other side to a GPIO pin on your MCU. No diode is required, but there is a 1:1 mapping between switches and pins.
 
-When specifying direct pins you need to arrange them in nested arrays. The outer array consists of rows, while the inner array is a text string corresponding to a pin. You can use `null` to indicate an empty spot in the matrix.
+When specifying direct pins you need to arrange them in nested arrays. The outer array consists of rows, while the inner array uses text strings to identify the pins used in each row. You can use `null` to indicate an empty spot in the matrix.
 
 Example:
 
@@ -108,7 +108,58 @@ Example:
 }
 ```
 
-### RGB Lighting
+## Non-RGB LED Lighting
+
+This section controls basic 2-pin LEDs, which typically pass through keyswitches and are soldered into the PCB, or are placed in PCB sockets.
+### Backlight
+
+* `breathing`
+    * Enable backlight breathing, if supported
+* `breathing_period`
+    * The length of one backlight “breath” in seconds
+* `levels`
+    * The number of brightness levels (maximum 31, excluding off)
+* `pin`
+    * The pin that controls the backlight LED(s)
+
+Example:
+
+```json
+{
+    "backlight": {
+        "breathing": true,
+        "breathing_period": 5,
+        "levels": 15,
+        "pin": "B7"
+    }
+}
+```
+
+### LED Indicators
+
+Used for indicating Num Lock, Caps Lock, and Scroll Lock. May be soldered in-switch or in a dedicated area.
+
+* `num_lock`
+    * The pin that controls the `Num Lock` LED
+* `caps_lock`
+    * The pin that controls the `Caps Lock` LED
+* `scroll_lock`
+    * The pin that controls the `Scroll Lock` LED
+
+Example:
+
+```json
+{
+    "indicators": {
+        "num_lock": "B6",
+        "caps_lock": "D2",
+        "scroll_lock": "A3"
+    }
+}
+
+```
+
+## RGB Lighting
 
 This section controls the legacy WS2812 support in QMK. This should not be confused with the RGB Matrix feature, which can be used to control both WS2812 and ISSI RGB LEDs.
 
@@ -152,7 +203,7 @@ Example:
 }
 ```
 
-#### RGBLight Animations
+### RGBLight Animations
 
 The following animations can be enabled:
 
@@ -187,3 +238,25 @@ Example:
 ```
 
 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.
+
+### Secure
+
+The following options can be configured:
+
+|Key               |Description                                                                      |
+|------------------|---------------------------------------------------------------------------------|
+|`unlock_sequence` | Timeout for the user to perform the configured unlock sequence - `0` to disable |
+|`unlock_timeout`  | Timeout while unlocked before returning to locked - `0` to disable              |
+|`idle_timeout`    | Array of matrix locations describing a sequential sequence of keypresses        |
+
+Example:
+
+```json
+{
+    "secure": {
+        "unlock_sequence": [ [0,0], [0,1] ],
+        "unlock_timeout": 5000,
+        "idle_timeout": 60000
+    }
+}
+```

docs/reference_keymap_extras.md

@@ -36,20 +36,20 @@ These headers are located in [`quantum/keymap_extras/`](https://github.com/qmk/q
 |French (AFNOR)                   |`keymap_french_afnor.h`          |`sendstring_french_afnor.h`         |
 |French (BÉPO)                    |`keymap_bepo.h`                  |`sendstring_bepo.h`                 |
 |French (Belgium)                 |`keymap_belgian.h`               |`sendstring_belgian.h`              |
-|French (Switzerland)             |`keymap_fr_ch.h`                 |`sendstring_fr_ch.h`                |
-|French (macOS, ISO)              |`keymap_french_osx.h`            |`sendstring_french_osx.h`           |
+|French (Switzerland)             |`keymap_swiss_fr.h`              |`sendstring_swiss_fr.h`             |
+|French (macOS, ISO)              |`keymap_french_mac_iso.h`        |`sendstring_french_mac_iso.h`       |
 |German                           |`keymap_german.h`                |`sendstring_german.h`               |
-|German (Switzerland)             |`keymap_german_ch.h`             |`sendstring_german_ch.h`            |
-|German (macOS)                   |`keymap_german_osx.h`            |`sendstring_german_osx.h`           |
+|German (Switzerland)             |`keymap_swiss_de.h`              |`sendstring_swiss_de.h`             |
+|German (macOS)                   |`keymap_german_mac_iso.h`        |`sendstring_german_mac_iso.h`       |
 |German (Neo2)                    |`keymap_neo2.h`                  |                                    |
 |Greek                            |`keymap_greek.h`                 |                                    |
 |Hebrew                           |`keymap_hebrew.h`                |                                    |
 |Hungarian                        |`keymap_hungarian.h`             |`sendstring_hungarian.h`            |
 |Icelandic                        |`keymap_icelandic.h`             |`sendstring_icelandic.h`            |
 |Italian                          |`keymap_italian.h`               |`sendstring_italian.h`              |
-|Italian (macOS, ANSI)            |`keymap_italian_osx_ansi.h`      |`sendstring_italian_osx_ansi.h`     |
-|Italian (macOS, ISO)             |`keymap_italian_osx_iso.h`       |`sendstring_italian_osx_iso.h`      |
-|Japanese                         |`keymap_jp.h`                    |`sendstring_jis.h`                  |
+|Italian (macOS, ANSI)            |`keymap_italian_mac_ansi.h`      |`sendstring_italian_mac_ansi.h`     |
+|Italian (macOS, ISO)             |`keymap_italian_mac_iso.h`       |`sendstring_italian_mac_iso.h`      |
+|Japanese                         |`keymap_japanese.h`              |`sendstring_japanese.h`             |
 |Korean                           |`keymap_korean.h`                |                                    |
 |Latvian                          |`keymap_latvian.h`               |`sendstring_latvian.h`              |
 |Lithuanian (ĄŽERTY)              |`keymap_lithuanian_azerty.h`     |`sendstring_lithuanian_azerty.h`    |
@@ -57,8 +57,8 @@ These headers are located in [`quantum/keymap_extras/`](https://github.com/qmk/q
 |Norwegian                        |`keymap_norwegian.h`             |`sendstring_norwegian.h`            |
 |Polish                           |`keymap_polish.h`                |                                    |
 |Portuguese                       |`keymap_portuguese.h`            |`sendstring_portuguese.h`           |
-|Portuguese (macOS, ISO)          |`keymap_portuguese_osx_iso.h`    |`sendstring_portuguese_osx_iso.h`   |
-|Portuguese (Brazil)              |`keymap_br_abnt2.h`              |`sendstring_br_abnt2.h`             |
+|Portuguese (macOS, ISO)          |`keymap_portuguese_mac_iso.h`    |`sendstring_portuguese_mac_iso.h`   |
+|Portuguese (Brazil)              |`keymap_brazilian_abnt2.h`       |`sendstring_brazilian_abnt2.h`      |
 |Romanian                         |`keymap_romanian.h`              |`sendstring_romanian.h`             |
 |Russian                          |`keymap_russian.h`               |                                    |
 |Serbian                          |`keymap_serbian.h`               |                                    |
@@ -68,24 +68,25 @@ These headers are located in [`quantum/keymap_extras/`](https://github.com/qmk/q
 |Spanish                          |`keymap_spanish.h`               |`sendstring_spanish.h`              |
 |Spanish (Dvorak)                 |`keymap_spanish_dvorak.h`        |`sendstring_spanish_dvorak.h`       |
 |Swedish                          |`keymap_swedish.h`               |`sendstring_swedish.h`              |
-|Swedish (macOS, ANSI)            |`keymap_swedish_osx_ansi.h`      |                                    |
-|Swedish (macOS, ISO)             |`keymap_swedish_osx_iso.h`       |                                    |
-|Swedish Pro (macOS, ANSI)        |`keymap_swedish_pro_osx_ansi.h`  |                                    |
-|Swedish Pro (macOS, ISO)         |`keymap_swedish_pro_osx_iso.h`   |                                    |
+|Swedish (macOS, ANSI)            |`keymap_swedish_mac_ansi.h`      |                                    |
+|Swedish (macOS, ISO)             |`keymap_swedish_mac_iso.h`       |                                    |
+|Swedish Pro (macOS, ANSI)        |`keymap_swedish_pro_mac_ansi.h`  |                                    |
+|Swedish Pro (macOS, ISO)         |`keymap_swedish_pro_mac_iso.h`   |                                    |
 |Turkish (F)                      |`keymap_turkish_f.h`             |`sendstring_turkish_f.h`            |
 |Turkish (Q)                      |`keymap_turkish_q.h`             |`sendstring_turkish_q.h`            |
+|Ukrainian                        |`keymap_ukrainian.h`             |                                    |
 
 There are also a few which are not quite language-specific, but useful if you are not using a QWERTY layout:
 
-|Layout             |Keycodes Header         |Sendstring LUT Header       |
-|-------------------|------------------------|----------------------------|
-|Colemak            |`keymap_colemak.h`      |`sendstring_colemak.h`      |
-|Dvorak             |`keymap_dvorak.h`       |`sendstring_dvorak.h`       |
-|Dvorak (French)    |`keymap_dvorak_fr.h`    |`sendstring_dvorak_fr.h`    |
-|Dvorak (Programmer)|`keymap_dvp.h`          |`sendstring_dvp.h`          |
-|Norman             |`keymap_norman.h`       |`sendstring_norman.h`       |
-|Plover             |`keymap_plover.h`       |                            |
-|Plover (Dvorak)    |`keymap_plover_dvorak.h`|                            |
-|Steno              |`keymap_steno.h`        |                            |
-|Workman            |`keymap_workman.h`      |`sendstring_workman.h`      |
-|Workman (ZXCVM)    |`keymap_workman_zxcvm.h`|`sendstring_workman_zxcvm.h`|
+|Layout             |Keycodes Header             |Sendstring LUT Header           |
+|-------------------|----------------------------|--------------------------------|
+|Colemak            |`keymap_colemak.h`          |`sendstring_colemak.h`          |
+|Dvorak             |`keymap_dvorak.h`           |`sendstring_dvorak.h`           |
+|Dvorak (French)    |`keymap_dvorak_fr.h`        |`sendstring_dvorak_fr.h`        |
+|Dvorak (Programmer)|`keymap_dvorak_programmer.h`|`sendstring_dvorak_programmer.h`|
+|Norman             |`keymap_norman.h`           |`sendstring_norman.h`           |
+|Plover             |`keymap_plover.h`           |                                |
+|Plover (Dvorak)    |`keymap_plover_dvorak.h`    |                                |
+|Steno              |`keymap_steno.h`            |                                |
+|Workman            |`keymap_workman.h`          |`sendstring_workman.h`          |
+|Workman (ZXCVM)    |`keymap_workman_zxcvm.h`    |`sendstring_workman_zxcvm.h`    |

docs/squeezing_avr.md

@@ -30,6 +30,19 @@ 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.
 
+If you use `sprintf` or `snprintf` functions you can save around ~400 Bytes by enabling this option.
+```make
+AVR_USE_MINIMAL_PRINTF = yes
+```
+
+This will include smaller implementations from AVRs libc into your Firmware. They are [not fully featured](https://www.nongnu.org/avr-libc/user-manual/group__avr__stdio.html#gaa3b98c0d17b35642c0f3e4649092b9f1), for instance zero padding and field width specifiers are not supported. So if you use `sprintf` or `snprintf` like this:
+```c
+sprintf(wpm_str, "%03d", get_current_wpm());
+snprintf(keylog_str, sizeof(keylog_str), "%dx%d, k%2d : %c");
+```
+
+you will still need the standard implementation.
+
 ## `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.
@@ -175,7 +188,10 @@ If you've done all of this, and your firmware is still too large, then it's time
 That said, there are a number of Pro Micro replacements with ARM controllers: 
 * [Proton C](https://qmk.fm/proton-c/) (out of stock)
 * [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)
+* [STeMCell](https://github.com/megamind4089/STeMCell) (Open Source, DIY/PCBA)
+* [Adafruit KB2040](https://learn.adafruit.com/adafruit-kb2040)
+* [SparkFun Pro Micro - RP2040](https://www.sparkfun.com/products/18288)
+* [Blok](https://boardsource.xyz/store/628b95b494dfa308a6581622)
 
 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/tap_hold.md

@@ -112,7 +112,7 @@ uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) {
 }
 ```
 
-The reason being that `TAPPING_TERM` is a macro that expands to a constant integer and thus cannot be changed at runtime whereas `g_tapping_term` is a variable whose value can be changed at runtime. If you want, you can temporarily enable `DYNAMIC_TAPPING_TERM_ENABLE` to find a suitable tapping term value and then disable that feature and revert back to using the classic syntax for per-key tapping term settings.
+The reason being that `TAPPING_TERM` is a macro that expands to a constant integer and thus cannot be changed at runtime whereas `g_tapping_term` is a variable whose value can be changed at runtime. If you want, you can temporarily enable `DYNAMIC_TAPPING_TERM_ENABLE` to find a suitable tapping term value and then disable that feature and revert back to using the classic syntax for per-key tapping term settings. In case you need to access the tapping term from elsewhere in your code, you can use the `GET_TAPPING_TERM(keycode, record)` macro. This macro will expand to whatever is the appropriate access pattern given the current configuration.
 
 ## Tap-Or-Hold Decision Modes
 

docs/zh-cn/flashing.md

@@ -252,7 +252,7 @@ BOOTLOADER = stm32-dfu
 ### `make` 构建目标
 
 * `:dfu-util`: 每5秒检测一次直到发现可用的STM32 bootloader设备，然后进行固件刷写。
-* `:dfu-util-split-left` 和 `:dfu-util-split-right`: 同 `:avrdude` 一样会刷写固件，但额外地会设置手性设置到EEPROM中，对于基于Proton-C的分体式键盘这是理想的方法。
+* `:dfu-util-split-left` 和 `:dfu-util-split-right`: 同 `:dfu-util` 一样会刷写固件，但额外地会设置手性设置到EEPROM中，对于基于Proton-C的分体式键盘这是理想的方法。
 * `:st-link-cli`: 通过ST-Link CLI工具集而非dfu-util进行刷写，需要有ST-Link电子狗。
 * `:st-flash`: 通过[STLink工具](https://github.com/stlink-org/stlink)内的 `st-flash` 工具而非dfu-util进行刷写，需要有ST-Link电子狗。
 

docs/zh-cn/newbs_git_best_practices.md

@@ -0,0 +1,23 @@
+# QMK所采用的Git最佳实践
+
+<!---
+  original document: 0.15.17:docs/newbs_git_best_practices.md 
+  git diff 0.15.17 HEAD -- docs/newbs_git_best_practices.md  | cat
+-->
+
+*译者注：对于git相关的部分，除广为接受的名词外，会尽量保留git命令及各种术语的英文版本，部分名词及关键部分会附带中文翻译*
+
+## 或者讲，"怎么才能不害怕并喜欢上Git"
+
+本节旨在以最佳方式指导新手在为QMK做贡献时获得流畅的体验。我们将进行一次完整的QMK贡献操作流程，并在部分环节中详细讲述几种便捷的方法，之后我们会故意搞砸一些东西，并教导你如何回到正轨。
+
+该章节做了如下假设：
+
+1. 你已有Github账号且已[fork了qmk_firmware仓库](zh-cn/getting_started_github.md)到你的账号下。
+2. 已完成了[构建环境](zh-cn/newbs_getting_started.md#set-up-your-environment)及[QMK](zh-cn/newbs_getting_started.md#set-up-qmk)配置。
+
+---
+
+- 第一节：[在你Fork的主干上：频繁更新，不要提交](zh-cn/newbs_git_using_your_master_branch.md)
+- 第二节：[解决合并冲突](zh-cn/newbs_git_resolving_merge_conflicts.md)
+- 第三节：[重新同步一个脱离同步状态的Git分支](zh-cn/newbs_git_resynchronize_a_branch.md)

docs/zh-cn/newbs_git_resolving_merge_conflicts.md

@@ -0,0 +1,86 @@
+# 解决合并冲突
+
+<!---
+  original document: 0.15.17:docs/newbs_git_resolving_merge_conflicts.md 
+  git diff 0.15.17 HEAD -- docs/newbs_git_resolving_merge_conflicts.md  | cat
+-->
+
+有时在你致力于一个较长周期才能完成的分支时，其它人提交的变更会与你提交的pull request中的变更发生冲突。我们将这种多个人编辑同一个模块同一个文件时产生的场景叫做 *合并冲突*
+
+?> 本文中的场景基于[在你Fork的主干上：频繁更新，不要提交](zh-cn/newbs_git_using_your_master_branch.md)一文。如果你对那篇文章不熟悉，请先阅读它，再回来继续。
+
+## 变基/衍合（rebase）
+
+
+Git的*变基*操作会将提交历史中的提交节点摘除并回滚，然后统一提交到一个新节点上。在解决合并冲突时，可以通过对当前分支进行变基，来获取从分支拉取到当前时刻的所有变更。
+
+从执行如下命令开始：
+
+```
+git fetch upstream
+git rev-list --left-right --count HEAD...upstram/master
+```
+
+此处输入的 `git rev-list` 命令可以得到当前分支与QMK主干分支间的提交数量差。而先执行 `git fetch` 是为了确保我们有上游仓库（upstream repo）的最新状态。`git rev-list` 命令会返回两个数字：
+
+```
+$ git rev-list --left-right --count HEAD...upstream/master
+7       35
+```
+
+第一个数字为当前分支自创建后新增的提交数量。第二个数字为当前分支创建后在 `upstream/master` 上的提交数量，而这部分就是我们当前分支上缺失的提交记录。
+
+在我们了解了当前分支以及上游仓库的状态后，可以发起变基操作了：
+
+```
+git rebase upstream/master
+```
+
+这样可以让Git回滚该分支的提交，然后基于QMK的主干版本重新应用这些提交。
+
+*译注：以下内容在中文Git下大同小异，且仅作为示例，不进行翻译*
+```
+$ git rebase upstream/master
+First, rewinding head to replay your work on top of it...
+Applying: Commit #1
+Using index info to reconstruct a base tree...
+M       conflicting_file_1.txt
+Falling back to patching base and 3-way merge...
+Auto-merging conflicting_file_1.txt
+CONFLICT (content): Merge conflict in conflicting_file_1.txt
+error: Failed to merge in the changes.
+hint: Use 'git am --show-current-patch' to see the failed patch
+Patch failed at 0001 Commit #1
+
+Resolve all conflicts manually, mark them as resolved with
+"git add/rm <conflicted_files>", then run "git rebase --continue".
+You can instead skip this commit: run "git rebase --skip".
+To abort and get back to the state before "git rebase", run "git rebase --abort".
+```
+
+以上内容是在告诉我们有合并冲突存在，并给出了冲突所在的文件名。在编辑器中打开该文件，可以在某处发现类似如下形式的内容：
+
+```
+<<<<<<< HEAD
+<p>For help with any issues, email us at support@webhost.us.</p>
+=======
+<p>Need help? Email support@webhost.us.</p>
+>>>>>>> Commit #1
+```
+
+`<<<<<<< HEAD` 标记了合并冲突的起始行，直至 `>>>>>>> Commit #1` 标记的结束行，中间通过 `=======` 分隔开冲突双方。其中 `HEAD` 部分为QMK主干上的版本，标记了提交日志的部分为当前分支的本地提交。
+
+由于Git存储的是*文件差异部分*而非整个文件，所以当Git无法在文件中找到一个变更发生前的内容时，就无法知道如何去进行文件变更，重新编辑一下可以解决问题。在更改完成后，保存文件。
+
+```
+<p>Need help? Email support@webhost.us.</p>
+```
+
+之后，执行：
+
+```
+git add conflicting_file_1.txt
+git rebase --continue
+```
+
+Git即会记录对文件冲突做出的变更，并继续处理剩余的提交，直至全部完成。

docs/zh-cn/newbs_git_resynchronize_a_branch.md

@@ -0,0 +1,76 @@
+# 重新同步已失去同步状态的Git分支
+
+<!---
+  original document: 0.15.17:docs/newbs_git_resynchronize_a_branch.md 
+  git diff 0.15.17 HEAD -- docs/newbs_git_resynchronize_a_branch.md  | cat
+-->
+
+假设你在自己的 `master` 分支之上有提交，并且想和QMK仓库进行同步，可以通过 `git pull` 拉取QMK的 `master` 分支到你的库，但同时Github也会提醒你当前分支相比 `qmk:master` 有几个领先的提交，会在你向QMK发起pr时造成麻烦。
+
+?> 本文中的场景基于[在你Fork的主干上：频繁更新，不要提交](zh-cn/newbs_git_using_your_master_branch.md)一文。如果你对那篇文章不熟悉，请先阅读它，再回来继续。
+
+## 备份你在自己的主干分支上的所有变更（可选）
+
+不会有人想把有用的成果弄丢的。如果你想将你的 `master` 分支上的变更另存一份，简便的方法是直接创建一个当前“脏” `master` 分支的副本：
+
+```
+git branch old_master master
+```
+
+现在 `master` 分支拥有了一个副本分支 `old_master`。
+
+## 重新同步分支
+
+现在可以重新同步 `master` 分支了，这里，我们将QMK仓库设置为Git的远程仓库。通过执行 `git remote -v` 可以确认远程仓库配置，输出信息应类似于：
+
+```
+QMKuser ~/qmk_firmware (master)
+$ git remote -v
+origin  https://github.com/<your_username>/qmk_firmware.git (fetch)
+origin  https://github.com/<your_username>/qmk_firmware.git (push)
+upstream        https://github.com/qmk/qmk_firmware.git (fetch)
+upstream        https://github.com/qmk/qmk_firmware.git (push)
+```
+
+如果你只能看到一个仓库：
+
+```
+QMKuser ~/qmk_firmware (master)
+$ git remote -v
+origin  https://github.com/qmk/qmk_firmware.git (fetch)
+origin  https://github.com/qmk/qmk_firmware.git (push)
+```
+
+通过如下命令添加新的远程仓库：
+
+```
+git remote add upstream https://github.com/qmk/qmk_firmware.git
+```
+
+然后，重新将 `origin` 远程仓库设置为自己的fork：
+
+```
+git remote set-url origin https://github.com/<your_username>/qmk_firmware.git
+```
+
+在两个远程仓库配置完毕后，需要从QMK的 upstream 仓库中获取到更新，执行：
+
+```
+git fetch upstream
+```
+
+此时，重新同步你的分支到QMK的版本：
+
+```
+git reset --hard upstream/master
+```
+
+以上操作会更新你的本地仓库，而你的Github远程仓库仍然处于未同步状态，通过推送，可以让其进入已同步状态。可以通过如下命令来指引Git强行覆盖掉那些仅在你远程仓库中存在的提交：
+
+```
+git push --force-with-lease
+```
+
+!> **不要**在其它使用者也会提交的分支上执行 `git push --force-with-lease`，否则会覆盖掉他人的提交。
+
+此时你的Github fork，本地文件副本，以及QMK仓库就是一致的了。之后再进行变更（[在分支上！](zh-cn/newbs_git_using_your_master_branch.md#making-changes)）和提交。

docs/zh-cn/newbs_git_using_your_master_branch.md

@@ -0,0 +1,79 @@
+# 在你Fork的主干上：频繁更新，不要提交
+
+<!---
+  original document: 0.15.17:docs/newbs_git_using_your_master_branch.md 
+  git diff 0.15.17 HEAD -- docs/newbs_git_using_your_master_branch.md  | cat
+-->
+
+我们强烈推荐所有QMK开发者，无论在哪里做什么改动，频繁更新你的 `master` 分支，但***不要***在其上提交。相对地，将你所有的改动提交到开发分支上并提交一个pull request。
+
+为了减少冲突 &mdash; 多人同时编辑同一个文件 &mdash; 保持你的 `master` 分支更新到最新，并在新创建的分支上进行开发。
+
+## 更新master分支
+
+为了保持 `master` 更新到最新，推荐将QMK固件仓库（"repo"）设置为git远程仓库。打开Git命令行界面并键入：
+
+```
+git remote add upstream https://github.com/qmk/qmk_firmware.git
+```
+
+?> 名称 `upstream` 部分可以任意，这里给的是常用的；你可以将QMK远程仓库名称改成你想要的。Git的 `remote` 命令语法为 `git remote add <name> <url>`, `<name>` 是远程仓库的简写名称，这个名称可以在很多Git命令中使用，包括但不限于 `fetch`，`pull` 及 `push`，以指定目标远程仓库。
+
+要验证是否添加成功，可以执行 `git remote -v`，输出应该类似于：
+
+```
+$ git remote -v
+origin  https://github.com/<your_username>/qmk_firmware.git (fetch)
+origin  https://github.com/<your_username>/qmk_firmware.git (push)
+upstream        https://github.com/qmk/qmk_firmware.git (fetch)
+upstream        https://github.com/qmk/qmk_firmware.git (push)
+```
+
+在以上操作完成后，可以通过执行 `git fetch upstream` 来检查仓库是否有更新。该命令从QMK仓库拉取的分支（branches）及标签（tags） &mdash; 统称为“refs（引用）” &mdash;现在也被称作 `upstream`（上游）。此时我们可以比对自己fork版本的 `origin` 与QMK维护的分支的差异了。
+
+要更新你的fork的master分支，执行以下指令，每一行结束都需要按回车：
+
+```
+git checkout master
+git fetch upstream
+git pull upstream master
+git push origin master
+```
+
+以上操作会切换到 `master` 分支，从QMK仓库拉取refs，下载QMK `master` 分支的当前版本，并上传至你的fork中。
+
+## 进行编辑 :id=making-changes
+
+要进行编辑，通过如下命令创建一个新分支：
+
+```
+git checkout -b dev_branch
+git push --set-upstream origin dev_branch
+```
+
+以上操作会创建 `dev_branch` 新分支，检出（check out）并保存到你的fork中。`--set-upstream` 参数用于告知git使用你的fork仓库来处理 `dev_branch` 分支下的 `git push` 及 `git pull` 命令，且仅需要在第一次执行push命令时指定，之后再次执行 `git push` 或是 `git pull` 都无需加入该参数了。
+
+?> 在 `git push` 时，可以使用 `-u` 替代 `--set-upstram` &mdash; `-u` 为 `--set-upsream` 参数的别名。
+
+你可以任意命名该分支，但仍建议对分支起一个可以描述将在该分支下要做的工作的名称。
+
+默认情况下 `git checkout -b` 会基于你当前检出的分支作为新分支的基准。可以在后面追加已存在但未检出的分支名来指定新分支的基准：
+
+```
+git checkout -b dev_branch master
+```
+
+此时你便有了一个开发用分支，可以打开编辑器并进行你期望的变更了。通常推荐提交大量的小规模提交（commit），这样在需要时会更容易地定位并回滚造成问题的提交。若要提交更改，编辑并保存要更新的文件，并将其添加到*暂存区（staged area）*，然后提交到分支中：
+
+```
+git add path/to/updated_file
+git commit -m "My commit message."
+```
+
+`git add` 会将更改后的文件放到Git的*暂存区*，也称作Git的“装载区”。这里留存着即将通过 `git commit` 所提交并保存到仓库中的变更。请使用确切的描述来填写提交日志，以便于快速了解改动内容。
+
+?> 如果更改了多个文件，可以通过 `git add -- path/to/file1 path/to/file2 ...` 来添加所有项目。
+
+## 发布变更
+
+最后一步为上传你的变更到你的fork中。通过执行 `git push`，Git将发布 `dev_branch` 分支的所有变更至你的fork中。

drivers/flash/flash_spi.c

@@ -57,7 +57,7 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 /* Mode setting comands */
 #define FLASH_CMD_DP 0xB9  /* DP (Deep Power Down) */
-#define FLASH_CMD_RDP 0xAB /* RDP (Release form Deep Power Down) */
+#define FLASH_CMD_RDP 0xAB /* RDP (Release from Deep Power Down) */
 
 /* Status register */
 #define FLASH_FLAG_WIP 0x01 /* Write in progress bit */

drivers/flash/flash_spi.h

@@ -74,21 +74,21 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
     The sector size of the FLASH in bytes, as specified in the datasheet.
 */
 #ifndef EXTERNAL_FLASH_SECTOR_SIZE
-#    define EXTERNAL_FLASH_SECTOR_SIZE (4 * 1024)
+#    define EXTERNAL_FLASH_SECTOR_SIZE (4 * 1024L)
 #endif
 
 /*
     The block size of the FLASH in bytes, as specified in the datasheet.
 */
 #ifndef EXTERNAL_FLASH_BLOCK_SIZE
-#    define EXTERNAL_FLASH_BLOCK_SIZE (64 * 1024)
+#    define EXTERNAL_FLASH_BLOCK_SIZE (64 * 1024L)
 #endif
 
 /*
     The total size of the FLASH in bytes, as specified in the datasheet.
 */
 #ifndef EXTERNAL_FLASH_SIZE
-#    define EXTERNAL_FLASH_SIZE (512 * 1024)
+#    define EXTERNAL_FLASH_SIZE (512 * 1024L)
 #endif
 
 /*

drivers/haptic/solenoid.c

@@ -20,11 +20,22 @@
 #include "haptic.h"
 #include "gpio.h"
 #include "usb_device_state.h"
+#include <stdlib.h>
 
-bool     solenoid_on      = false;
-bool     solenoid_buzzing = false;
-uint16_t solenoid_start   = 0;
-uint8_t  solenoid_dwell   = SOLENOID_DEFAULT_DWELL;
+uint8_t      solenoid_dwell  = SOLENOID_DEFAULT_DWELL;
+static pin_t solenoid_pads[] = SOLENOID_PINS;
+#define NUMBER_OF_SOLENOIDS (sizeof(solenoid_pads) / sizeof(pin_t))
+bool     solenoid_on[NUMBER_OF_SOLENOIDS]      = {false};
+bool     solenoid_buzzing[NUMBER_OF_SOLENOIDS] = {false};
+uint16_t solenoid_start[NUMBER_OF_SOLENOIDS]   = {0};
+#ifdef SOLENOID_PIN_ACTIVE_LOW
+#    define low true
+#    define high false
+#else
+#    define low false
+#    define high true
+#endif
+static bool solenoid_active_state[NUMBER_OF_SOLENOIDS];
 
 extern haptic_config_t haptic_config;
 
@@ -36,7 +47,7 @@ void solenoid_buzz_off(void) {
     haptic_set_buzz(0);
 }
 
-void solenoid_set_buzz(int buzz) {
+void solenoid_set_buzz(uint8_t buzz) {
     haptic_set_buzz(buzz);
 }
 
@@ -44,59 +55,121 @@ void solenoid_set_dwell(uint8_t dwell) {
     solenoid_dwell = dwell;
 }
 
-void solenoid_stop(void) {
-    SOLENOID_PIN_WRITE_INACTIVE();
-    solenoid_on      = false;
-    solenoid_buzzing = false;
+/**
+ * @brief Stops a specific solenoid
+ *
+ * @param index select which solenoid to check/stop
+ */
+void solenoid_stop(uint8_t index) {
+    writePin(solenoid_pads[index], !solenoid_active_state[index]);
+    solenoid_on[index]      = false;
+    solenoid_buzzing[index] = false;
 }
 
-void solenoid_fire(void) {
-    if (!haptic_config.buzz && solenoid_on) return;
-    if (haptic_config.buzz && solenoid_buzzing) return;
+/**
+ * @brief Fires off a specific solenoid
+ *
+ * @param index Selects which solenoid to fire
+ */
+void solenoid_fire(uint8_t index) {
+    if (!haptic_config.buzz && solenoid_on[index]) return;
+    if (haptic_config.buzz && solenoid_buzzing[index]) return;
 
-    solenoid_on      = true;
-    solenoid_buzzing = true;
-    solenoid_start   = timer_read();
-    SOLENOID_PIN_WRITE_ACTIVE();
+    solenoid_on[index]      = true;
+    solenoid_buzzing[index] = true;
+    solenoid_start[index]   = timer_read();
+    writePin(solenoid_pads[index], solenoid_active_state[index]);
 }
 
-void solenoid_check(void) {
-    uint16_t elapsed = 0;
-
-    if (!solenoid_on) return;
-
-    elapsed = timer_elapsed(solenoid_start);
-
-    // Check if it's time to finish this solenoid click cycle
-    if (elapsed > solenoid_dwell) {
-        solenoid_stop();
-        return;
+/**
+ * @brief Handles selecting a non-active solenoid, and firing it.
+ *
+ */
+void solenoid_fire_handler(void) {
+#ifndef SOLENOID_RANDOM_FIRE
+    if (NUMBER_OF_SOLENOIDS > 1) {
+        uint8_t i = rand() % NUMBER_OF_SOLENOIDS;
+        if (!solenoid_on[i]) {
+            solenoid_fire(i);
+        }
+    } else {
+        solenoid_fire(0);
     }
+#else
+    for (uint8_t i = 0; i < NUMBER_OF_SOLENOIDS; i++) {
+        if (!solenoid_on[i]) {
+            solenoid_fire(i);
+            break;
+        }
+    }
+#endif
+}
 
-    // Check whether to buzz the solenoid on and off
-    if (haptic_config.buzz) {
-        if ((elapsed % (SOLENOID_BUZZ_ACTUATED + SOLENOID_BUZZ_NONACTUATED)) < SOLENOID_BUZZ_ACTUATED) {
-            if (!solenoid_buzzing) {
-                solenoid_buzzing = true;
-                SOLENOID_PIN_WRITE_ACTIVE();
-            }
-        } else {
-            if (solenoid_buzzing) {
-                solenoid_buzzing = false;
-                SOLENOID_PIN_WRITE_INACTIVE();
+/**
+ * @brief Checks active solenoid to stop them, and to handle buzz mode
+ *
+ */
+void solenoid_check(void) {
+    uint16_t elapsed[NUMBER_OF_SOLENOIDS] = {0};
+
+    for (uint8_t i = 0; i < NUMBER_OF_SOLENOIDS; i++) {
+        if (!solenoid_on[i]) continue;
+
+        elapsed[i] = timer_elapsed(solenoid_start[i]);
+
+        // Check if it's time to finish this solenoid click cycle
+        if (elapsed[i] > solenoid_dwell) {
+            solenoid_stop(i);
+            continue;
+        }
+
+        // Check whether to buzz the solenoid on and off
+        if (haptic_config.buzz) {
+            if ((elapsed[i] % (SOLENOID_BUZZ_ACTUATED + SOLENOID_BUZZ_NONACTUATED)) < SOLENOID_BUZZ_ACTUATED) {
+                if (!solenoid_buzzing[i]) {
+                    solenoid_buzzing[i] = true;
+                    writePin(solenoid_pads[i], solenoid_active_state[i]);
+                }
+            } else {
+                if (solenoid_buzzing[i]) {
+                    solenoid_buzzing[i] = false;
+                    writePin(solenoid_pads[i], !solenoid_active_state[i]);
+                }
             }
         }
     }
 }
 
+/**
+ * @brief Initial configuration for solenoids
+ *
+ */
 void solenoid_setup(void) {
-    SOLENOID_PIN_WRITE_INACTIVE();
-    setPinOutput(SOLENOID_PIN);
-    if ((!HAPTIC_OFF_IN_LOW_POWER) || (usb_device_state == USB_DEVICE_STATE_CONFIGURED)) {
-        solenoid_fire();
+#ifdef SOLENOID_PINS_ACTIVE_STATE
+    bool    state_temp[] = SOLENOID_PINS_ACTIVE_STATE;
+    uint8_t bound_check  = (sizeof(state_temp) / sizeof(bool));
+#endif
+
+    for (uint8_t i = 0; i < NUMBER_OF_SOLENOIDS; i++) {
+#ifdef SOLENOID_PINS_ACTIVE_STATE
+        solenoid_active_state[i] = (bound_check - i) ? state_temp[i] : high;
+#else
+        solenoid_active_state[i] = high;
+#endif
+        writePin(solenoid_pads[i], !solenoid_active_state[i]);
+        setPinOutput(solenoid_pads[i]);
+        if ((!HAPTIC_OFF_IN_LOW_POWER) || (usb_device_state == USB_DEVICE_STATE_CONFIGURED)) {
+            solenoid_fire(i);
+        }
     }
 }
 
+/**
+ * @brief stops solenoids prior to device reboot, to prevent them from being locked on
+ *
+ */
 void solenoid_shutdown(void) {
-    SOLENOID_PIN_WRITE_INACTIVE();
+    for (uint8_t i = 0; i < NUMBER_OF_SOLENOIDS; i++) {
+        writePin(solenoid_pads[i], !solenoid_active_state[i]);
+    }
 }

drivers/haptic/solenoid.h

@@ -45,26 +45,24 @@
 #    define SOLENOID_BUZZ_NONACTUATED SOLENOID_MIN_DWELL
 #endif
 
-#ifndef SOLENOID_PIN
-#    error SOLENOID_PIN not defined
+#ifndef SOLENOID_PINS
+#    ifdef SOLENOID_PIN
+#        define SOLENOID_PINS \
+            { SOLENOID_PIN }
+#    else
+#        error SOLENOID_PINS array not defined
+#    endif
 #endif
 
-#ifdef SOLENOID_PIN_ACTIVE_LOW
-#    define SOLENOID_PIN_WRITE_ACTIVE() writePinLow(SOLENOID_PIN)
-#    define SOLENOID_PIN_WRITE_INACTIVE() writePinHigh(SOLENOID_PIN)
-#else
-#    define SOLENOID_PIN_WRITE_ACTIVE() writePinHigh(SOLENOID_PIN)
-#    define SOLENOID_PIN_WRITE_INACTIVE() writePinLow(SOLENOID_PIN)
-#endif
-
-void solenoid_buzz_on(void);
+void solenoidbuzz_on(void);
 void solenoid_buzz_off(void);
-void solenoid_set_buzz(int buzz);
+void solenoid_set_buzz(uint8_t buzz);
 
 void solenoid_set_dwell(uint8_t dwell);
 
-void solenoid_stop(void);
-void solenoid_fire(void);
+void solenoid_stop(uint8_t index);
+void solenoid_fire(uint8_t index);
+void solenoid_fire_handler(void);
 
 void solenoid_check(void);
 

drivers/led/aw20216.c

@@ -63,7 +63,7 @@ bool    g_pwm_buffer_update_required[DRIVER_COUNT] = {false};
 bool AW20216_write(pin_t cs_pin, uint8_t page, uint8_t reg, uint8_t* data, uint8_t len) {
     static uint8_t s_spi_transfer_buffer[2] = {0};
 
-    if (!spi_start(cs_pin, false, 0, AW_SPI_DIVISOR)) {
+    if (!spi_start(cs_pin, false, 3, AW_SPI_DIVISOR)) {
         spi_stop();
         return false;
     }

drivers/painter/comms/qp_comms_spi.c

@@ -0,0 +1,137 @@
+// Copyright 2021 Nick Brassel (@tzarc)
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+#ifdef QUANTUM_PAINTER_SPI_ENABLE
+
+#    include "spi_master.h"
+#    include "qp_comms_spi.h"
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// Base SPI support
+
+bool qp_comms_spi_init(painter_device_t device) {
+    struct painter_driver_t *     driver       = (struct painter_driver_t *)device;
+    struct qp_comms_spi_config_t *comms_config = (struct qp_comms_spi_config_t *)driver->comms_config;
+
+    // Initialize the SPI peripheral
+    spi_init();
+
+    // Set up CS as output high
+    setPinOutput(comms_config->chip_select_pin);
+    writePinHigh(comms_config->chip_select_pin);
+
+    return true;
+}
+
+bool qp_comms_spi_start(painter_device_t device) {
+    struct painter_driver_t *     driver       = (struct painter_driver_t *)device;
+    struct qp_comms_spi_config_t *comms_config = (struct qp_comms_spi_config_t *)driver->comms_config;
+
+    return spi_start(comms_config->chip_select_pin, comms_config->lsb_first, comms_config->mode, comms_config->divisor);
+}
+
+uint32_t qp_comms_spi_send_data(painter_device_t device, const void *data, uint32_t byte_count) {
+    uint32_t       bytes_remaining = byte_count;
+    const uint8_t *p               = (const uint8_t *)data;
+    while (bytes_remaining > 0) {
+        uint32_t bytes_this_loop = bytes_remaining < 1024 ? bytes_remaining : 1024;
+        spi_transmit(p, bytes_this_loop);
+        p += bytes_this_loop;
+        bytes_remaining -= bytes_this_loop;
+    }
+
+    return byte_count - bytes_remaining;
+}
+
+void qp_comms_spi_stop(painter_device_t device) {
+    struct painter_driver_t *     driver       = (struct painter_driver_t *)device;
+    struct qp_comms_spi_config_t *comms_config = (struct qp_comms_spi_config_t *)driver->comms_config;
+    spi_stop();
+    writePinHigh(comms_config->chip_select_pin);
+}
+
+const struct painter_comms_vtable_t spi_comms_vtable = {
+    .comms_init  = qp_comms_spi_init,
+    .comms_start = qp_comms_spi_start,
+    .comms_send  = qp_comms_spi_send_data,
+    .comms_stop  = qp_comms_spi_stop,
+};
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// SPI with D/C and RST pins
+
+#    ifdef QUANTUM_PAINTER_SPI_DC_RESET_ENABLE
+
+bool qp_comms_spi_dc_reset_init(painter_device_t device) {
+    if (!qp_comms_spi_init(device)) {
+        return false;
+    }
+
+    struct painter_driver_t *              driver       = (struct painter_driver_t *)device;
+    struct qp_comms_spi_dc_reset_config_t *comms_config = (struct qp_comms_spi_dc_reset_config_t *)driver->comms_config;
+
+    // Set up D/C as output low, if specified
+    if (comms_config->dc_pin != NO_PIN) {
+        setPinOutput(comms_config->dc_pin);
+        writePinLow(comms_config->dc_pin);
+    }
+
+    // Set up RST as output, if specified, performing a reset in the process
+    if (comms_config->reset_pin != NO_PIN) {
+        setPinOutput(comms_config->reset_pin);
+        writePinLow(comms_config->reset_pin);
+        wait_ms(20);
+        writePinHigh(comms_config->reset_pin);
+        wait_ms(20);
+    }
+
+    return true;
+}
+
+uint32_t qp_comms_spi_dc_reset_send_data(painter_device_t device, const void *data, uint32_t byte_count) {
+    struct painter_driver_t *              driver       = (struct painter_driver_t *)device;
+    struct qp_comms_spi_dc_reset_config_t *comms_config = (struct qp_comms_spi_dc_reset_config_t *)driver->comms_config;
+    writePinHigh(comms_config->dc_pin);
+    return qp_comms_spi_send_data(device, data, byte_count);
+}
+
+void qp_comms_spi_dc_reset_send_command(painter_device_t device, uint8_t cmd) {
+    struct painter_driver_t *              driver       = (struct painter_driver_t *)device;
+    struct qp_comms_spi_dc_reset_config_t *comms_config = (struct qp_comms_spi_dc_reset_config_t *)driver->comms_config;
+    writePinLow(comms_config->dc_pin);
+    spi_write(cmd);
+}
+
+void qp_comms_spi_dc_reset_bulk_command_sequence(painter_device_t device, const uint8_t *sequence, size_t sequence_len) {
+    for (size_t i = 0; i < sequence_len;) {
+        uint8_t command   = sequence[i];
+        uint8_t delay     = sequence[i + 1];
+        uint8_t num_bytes = sequence[i + 2];
+        qp_comms_spi_dc_reset_send_command(device, command);
+        if (num_bytes > 0) {
+            qp_comms_spi_dc_reset_send_data(device, &sequence[i + 3], num_bytes);
+        }
+        if (delay > 0) {
+            wait_ms(delay);
+        }
+        i += (3 + num_bytes);
+    }
+}
+
+const struct painter_comms_with_command_vtable_t spi_comms_with_dc_vtable = {
+    .base =
+        {
+            .comms_init  = qp_comms_spi_dc_reset_init,
+            .comms_start = qp_comms_spi_start,
+            .comms_send  = qp_comms_spi_dc_reset_send_data,
+            .comms_stop  = qp_comms_spi_stop,
+        },
+    .send_command          = qp_comms_spi_dc_reset_send_command,
+    .bulk_command_sequence = qp_comms_spi_dc_reset_bulk_command_sequence,
+};
+
+#    endif // QUANTUM_PAINTER_SPI_DC_RESET_ENABLE
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+#endif // QUANTUM_PAINTER_SPI_ENABLE

drivers/painter/comms/qp_comms_spi.h

@@ -0,0 +1,51 @@
+// Copyright 2021 Nick Brassel (@tzarc)
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+#pragma once
+
+#ifdef QUANTUM_PAINTER_SPI_ENABLE
+
+#    include <stdint.h>
+
+#    include "gpio.h"
+#    include "qp_internal.h"
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// Base SPI support
+
+struct qp_comms_spi_config_t {
+    pin_t    chip_select_pin;
+    uint16_t divisor;
+    bool     lsb_first;
+    int8_t   mode;
+};
+
+bool     qp_comms_spi_init(painter_device_t device);
+bool     qp_comms_spi_start(painter_device_t device);
+uint32_t qp_comms_spi_send_data(painter_device_t device, const void* data, uint32_t byte_count);
+void     qp_comms_spi_stop(painter_device_t device);
+
+extern const struct painter_comms_vtable_t spi_comms_vtable;
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// SPI with D/C and RST pins
+
+#    ifdef QUANTUM_PAINTER_SPI_DC_RESET_ENABLE
+
+struct qp_comms_spi_dc_reset_config_t {
+    struct qp_comms_spi_config_t spi_config;
+    pin_t                        dc_pin;
+    pin_t                        reset_pin;
+};
+
+void     qp_comms_spi_dc_reset_send_command(painter_device_t device, uint8_t cmd);
+uint32_t qp_comms_spi_dc_reset_send_data(painter_device_t device, const void* data, uint32_t byte_count);
+void     qp_comms_spi_dc_reset_bulk_command_sequence(painter_device_t device, const uint8_t* sequence, size_t sequence_len);
+
+extern const struct painter_comms_with_command_vtable_t spi_comms_with_dc_vtable;
+
+#    endif // QUANTUM_PAINTER_SPI_DC_RESET_ENABLE
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+#endif // QUANTUM_PAINTER_SPI_ENABLE

drivers/painter/gc9a01/qp_gc9a01.c

@@ -0,0 +1,150 @@
+// Copyright 2021 Paul Cotter (@gr1mr3aver)
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+#include <wait.h>
+#include "qp_internal.h"
+#include "qp_comms.h"
+#include "qp_gc9a01.h"
+#include "qp_gc9a01_opcodes.h"
+#include "qp_tft_panel.h"
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// Driver storage
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+tft_panel_dc_reset_painter_device_t gc9a01_drivers[GC9A01_NUM_DEVICES] = {0};
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// Initialization
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+bool qp_gc9a01_init(painter_device_t device, painter_rotation_t rotation) {
+    // A lot of these "unknown" opcodes are sourced from other OSS projects and are seemingly required for this display to function.
+    // clang-format off
+    const uint8_t gc9a01_init_sequence[] = {
+        // Command,                 Delay,  N, Data[N]
+        GC9A01_SET_INTER_REG_ENABLE2,   0,  0,
+        0xEB,                           0,  1, 0x14,
+        GC9A01_SET_INTER_REG_ENABLE1,   0,  0,
+        GC9A01_SET_INTER_REG_ENABLE2,   0,  0,
+        0xEB,                           0,  1, 0x14,
+        0x84,                           0,  1, 0x40,
+        0x85,                           0,  1, 0xFF,
+        0x86,                           0,  1, 0xFF,
+        0x87,                           0,  1, 0xFF,
+        0x88,                           0,  1, 0x0A,
+        0x89,                           0,  1, 0x21,
+        0x8a,                           0,  1, 0x00,
+        0x8b,                           0,  1, 0x80,
+        0x8c,                           0,  1, 0x01,
+        0x8d,                           0,  1, 0x01,
+        0x8e,                           0,  1, 0xFF,
+        0x8f,                           0,  1, 0xFF,
+        GC9A01_SET_FUNCTION_CTL,        0,  2, 0x00, 0x20,
+        GC9A01_SET_PIX_FMT,             0,  1, 0x55,
+        0x90,                           0,  4, 0x08, 0x08, 0x08, 0x08,
+        0xBD,                           0,  1, 0x06,
+        0xBC,                           0,  1, 0x00,
+        0xFF,                           0,  3, 0x60, 0x01, 0x04,
+        GC9A01_SET_POWER_CTL_2,         0,  1, 0x13,
+        GC9A01_SET_POWER_CTL_3,         0,  1, 0x13,
+        GC9A01_SET_POWER_CTL_4,         0,  1, 0x22,
+        0xBE,                           0,  1, 0x11,
+        0xE1,                           0,  2, 0x10, 0x0E,
+        0xDF,                           0,  3, 0x21, 0x0C, 0x02,
+        GC9A01_SET_GAMMA1,              0,  6, 0x45, 0x09, 0x08, 0x08, 0x26, 0x2A,
+        GC9A01_SET_GAMMA2,              0,  6, 0x43, 0x70, 0x72, 0x36, 0x37, 0x6F,
+        GC9A01_SET_GAMMA3,              0,  6, 0x45, 0x09, 0x08, 0x08, 0x26, 0x2A,
+        GC9A01_SET_GAMMA4,              0,  6, 0x43, 0x70, 0x72, 0x36, 0x37, 0x6F,
+        0xED,                           0,  2, 0x1B, 0x0B,
+        0xAE,                           0,  1, 0x77,
+        0xCD,                           0,  1, 0x63,
+        0x70,                           0,  9, 0x07, 0x07, 0x04, 0x0E, 0x0F, 0x09, 0x07, 0x08, 0x03,
+        GC9A01_SET_FRAME_RATE,          0,  1, 0x34,
+        0x62,                           0, 12, 0x18, 0x0D, 0x71, 0xED, 0x70, 0x70, 0x18, 0x0F, 0x71, 0xEF, 0x70, 0x70,
+        0x63,                           0, 12, 0x18, 0x11, 0x71, 0xF1, 0x70, 0x70, 0x18, 0x13, 0x71, 0xF3, 0x70, 0x70,
+        0x64,                           0,  7, 0x28, 0x29, 0xF1, 0x01, 0xF1, 0x00, 0x07,
+        0x66,                           0, 10, 0x3C, 0x00, 0xCD, 0x67, 0x45, 0x45, 0x10, 0x00, 0x00, 0x00,
+        0x67,                           0, 10, 0x00, 0x3C, 0x00, 0x00, 0x00, 0x01, 0x54, 0x10, 0x32, 0x98,
+        0x74,                           0,  7, 0x10, 0x85, 0x80, 0x00, 0x00, 0x4E, 0x00,
+        0x98,                           0,  2, 0x3E, 0x07,
+        GC9A01_CMD_TEARING_OFF,         0,  0,
+        GC9A01_CMD_INVERT_OFF,          0,  0,
+        GC9A01_CMD_SLEEP_OFF,         120,  0,
+        GC9A01_CMD_DISPLAY_ON,         20,  0
+    };
+    // clang-format on
+
+    // clang-format on
+    qp_comms_bulk_command_sequence(device, gc9a01_init_sequence, sizeof(gc9a01_init_sequence));
+
+    // Configure the rotation (i.e. the ordering and direction of memory writes in GRAM)
+    const uint8_t madctl[] = {
+        [QP_ROTATION_0]   = GC9A01_MADCTL_BGR,
+        [QP_ROTATION_90]  = GC9A01_MADCTL_BGR | GC9A01_MADCTL_MX | GC9A01_MADCTL_MV,
+        [QP_ROTATION_180] = GC9A01_MADCTL_BGR | GC9A01_MADCTL_MX | GC9A01_MADCTL_MY,
+        [QP_ROTATION_270] = GC9A01_MADCTL_BGR | GC9A01_MADCTL_MV | GC9A01_MADCTL_MY,
+    };
+    qp_comms_command_databyte(device, GC9A01_SET_MEM_ACS_CTL, madctl[rotation]);
+
+    return true;
+}
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// Driver vtable
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+const struct tft_panel_dc_reset_painter_driver_vtable_t gc9a01_driver_vtable = {
+    .base =
+        {
+            .init            = qp_gc9a01_init,
+            .power           = qp_tft_panel_power,
+            .clear           = qp_tft_panel_clear,
+            .flush           = qp_tft_panel_flush,
+            .pixdata         = qp_tft_panel_pixdata,
+            .viewport        = qp_tft_panel_viewport,
+            .palette_convert = qp_tft_panel_palette_convert,
+            .append_pixels   = qp_tft_panel_append_pixels,
+        },
+    .rgb888_to_native16bit = qp_rgb888_to_rgb565_swapped,
+    .num_window_bytes      = 2,
+    .swap_window_coords    = false,
+    .opcodes =
+        {
+            .display_on         = GC9A01_CMD_DISPLAY_ON,
+            .display_off        = GC9A01_CMD_DISPLAY_OFF,
+            .set_column_address = GC9A01_SET_COL_ADDR,
+            .set_row_address    = GC9A01_SET_PAGE_ADDR,
+            .enable_writes      = GC9A01_SET_MEM,
+        },
+};
+
+#ifdef QUANTUM_PAINTER_GC9A01_SPI_ENABLE
+// Factory function for creating a handle to the ILI9341 device
+painter_device_t qp_gc9a01_make_spi_device(uint16_t panel_width, uint16_t panel_height, pin_t chip_select_pin, pin_t dc_pin, pin_t reset_pin, uint16_t spi_divisor, int spi_mode) {
+    for (uint32_t i = 0; i < GC9A01_NUM_DEVICES; ++i) {
+        tft_panel_dc_reset_painter_device_t *driver = &gc9a01_drivers[i];
+        if (!driver->base.driver_vtable) {
+            driver->base.driver_vtable         = (const struct painter_driver_vtable_t *)&gc9a01_driver_vtable;
+            driver->base.comms_vtable          = (const struct painter_comms_vtable_t *)&spi_comms_with_dc_vtable;
+            driver->base.native_bits_per_pixel = 16; // RGB565
+            driver->base.panel_width           = panel_width;
+            driver->base.panel_height          = panel_height;
+            driver->base.rotation              = QP_ROTATION_0;
+            driver->base.offset_x              = 0;
+            driver->base.offset_y              = 0;
+
+            // SPI and other pin configuration
+            driver->base.comms_config                              = &driver->spi_dc_reset_config;
+            driver->spi_dc_reset_config.spi_config.chip_select_pin = chip_select_pin;
+            driver->spi_dc_reset_config.spi_config.divisor         = spi_divisor;
+            driver->spi_dc_reset_config.spi_config.lsb_first       = false;
+            driver->spi_dc_reset_config.spi_config.mode            = spi_mode;
+            driver->spi_dc_reset_config.dc_pin                     = dc_pin;
+            driver->spi_dc_reset_config.reset_pin                  = reset_pin;
+            return (painter_device_t)driver;
+        }
+    }
+    return NULL;
+}
+
+#endif // QUANTUM_PAINTER_GC9A01_SPI_ENABLE

drivers/painter/gc9a01/qp_gc9a01.h

@@ -0,0 +1,37 @@
+// Copyright 2021 Paul Cotter (@gr1mr3aver)
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+#pragma once
+
+#include "gpio.h"
+#include "qp_internal.h"
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// Quantum Painter GC9A01 configurables (add to your keyboard's config.h)
+
+#ifndef GC9A01_NUM_DEVICES
+/**
+ * @def This controls the maximum number of GC9A01 devices that Quantum Painter can communicate with at any one time.
+ *      Increasing this number allows for multiple displays to be used.
+ */
+#    define GC9A01_NUM_DEVICES 1
+#endif
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// Quantum Painter GC9A01 device factories
+
+#ifdef QUANTUM_PAINTER_GC9A01_SPI_ENABLE
+/**
+ * Factory method for an GC9A01 SPI LCD device.
+ *
+ * @param panel_width[in] the width of the display panel
+ * @param panel_height[in] the height of the display panel
+ * @param chip_select_pin[in] the GPIO pin used for SPI chip select
+ * @param dc_pin[in] the GPIO pin used for D/C control
+ * @param reset_pin[in] the GPIO pin used for RST
+ * @param spi_divisor[in] the SPI divisor to use when communicating with the display
+ * @param spi_mode[in] the SPI mode to use when communicating with the display
+ * @return the device handle used with all drawing routines in Quantum Painter
+ */
+painter_device_t qp_gc9a01_make_spi_device(uint16_t panel_width, uint16_t panel_height, pin_t chip_select_pin, pin_t dc_pin, pin_t reset_pin, uint16_t spi_divisor, int spi_mode);
+#endif // QUANTUM_PAINTER_GC9A01_SPI_ENABLE

drivers/painter/gc9a01/qp_gc9a01_opcodes.h

@@ -0,0 +1,78 @@
+// Copyright 2021 Paul Cotter (@gr1mr3aver)
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+#pragma once
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// Quantum Painter GC9A01 command opcodes
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// Level 1 command opcodes
+
+#define GC9A01_GET_ID_INFO 0x04       // Get ID information
+#define GC9A01_GET_STATUS 0x09        // Get status
+#define GC9A01_CMD_SLEEP_ON 0x10      // Enter sleep mode
+#define GC9A01_CMD_SLEEP_OFF 0x11     // Exit sleep mode
+#define GC9A01_CMD_PARTIAL_ON 0x12    // Enter partial mode
+#define GC9A01_CMD_PARTIAL_OFF 0x13   // Exit partial mode
+#define GC9A01_CMD_INVERT_ON 0x20     // Enter inverted mode
+#define GC9A01_CMD_INVERT_OFF 0x21    // Exit inverted mode
+#define GC9A01_CMD_DISPLAY_OFF 0x28   // Disable display
+#define GC9A01_CMD_DISPLAY_ON 0x29    // Enable display
+#define GC9A01_SET_COL_ADDR 0x2A      // Set column address
+#define GC9A01_SET_PAGE_ADDR 0x2B     // Set page address
+#define GC9A01_SET_MEM 0x2C           // Set memory
+#define GC9A01_SET_PARTIAL_AREA 0x30  // Set partial area
+#define GC9A01_SET_VSCROLL 0x33       // Set vertical scroll def
+#define GC9A01_CMD_TEARING_ON 0x34    // Tearing line enabled
+#define GC9A01_CMD_TEARING_OFF 0x35   // Tearing line disabled
+#define GC9A01_SET_MEM_ACS_CTL 0x36   // Set mem access ctl
+#define GC9A01_SET_VSCROLL_ADDR 0x37  // Set vscroll start addr
+#define GC9A01_CMD_IDLE_OFF 0x38      // Exit idle mode
+#define GC9A01_CMD_IDLE_ON 0x39       // Enter idle mode
+#define GC9A01_SET_PIX_FMT 0x3A       // Set pixel format
+#define GC9A01_SET_MEM_CONT 0x3C      // Set memory continue
+#define GC9A01_SET_TEAR_SCANLINE 0x44 // Set tearing scanline
+#define GC9A01_GET_TEAR_SCANLINE 0x45 // Get tearing scanline
+#define GC9A01_SET_BRIGHTNESS 0x51    // Set brightness
+#define GC9A01_SET_DISPLAY_CTL 0x53   // Set display ctl
+#define GC9A01_GET_ID1 0xDA           // Get ID1
+#define GC9A01_GET_ID2 0xDB           // Get ID2
+#define GC9A01_GET_ID3 0xDC           // Get ID3
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// Level 2 command opcodes
+
+#define GC9A01_SET_RGB_IF_SIG_CTL 0xB0     // RGB IF signal ctl
+#define GC9A01_SET_BLANKING_PORCH_CTL 0xB5 // Set blanking porch ctl
+#define GC9A01_SET_FUNCTION_CTL 0xB6       // Set function ctl
+#define GC9A01_SET_TEARING_EFFECT 0xBA     // Set backlight ctl 3
+#define GC9A01_SET_IF_CTL 0xF6             // Set interface control
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// Level 3 command opcodes
+
+#define GC9A01_SET_FRAME_RATE 0xE8        // Set frame rate
+#define GC9A01_SET_SPI_2DATA 0xE9         // Set frame rate
+#define GC9A01_SET_POWER_CTL_1 0xC1       // Set power ctl 1
+#define GC9A01_SET_POWER_CTL_2 0xC3       // Set power ctl 2
+#define GC9A01_SET_POWER_CTL_3 0xC4       // Set power ctl 3
+#define GC9A01_SET_POWER_CTL_4 0xC9       // Set power ctl 4
+#define GC9A01_SET_POWER_CTL_7 0xA7       // Set power ctl 7
+#define GC9A01_SET_INTER_REG_ENABLE1 0xFE // Enable Inter Register 1
+#define GC9A01_SET_INTER_REG_ENABLE2 0xEF // Enable Inter Register 2
+#define GC9A01_SET_GAMMA1 0xF0            //
+#define GC9A01_SET_GAMMA2 0xF1
+#define GC9A01_SET_GAMMA3 0xF2
+#define GC9A01_SET_GAMMA4 0xF3
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// MADCTL Flags
+#define GC9A01_MADCTL_MY 0b10000000
+#define GC9A01_MADCTL_MX 0b01000000
+#define GC9A01_MADCTL_MV 0b00100000
+#define GC9A01_MADCTL_ML 0b00010000
+#define GC9A01_MADCTL_RGB 0b00000000
+#define GC9A01_MADCTL_BGR 0b00001000
+#define GC9A01_MADCTL_MH 0b00000100

drivers/painter/ili9xxx/qp_ili9163.c

@@ -0,0 +1,121 @@
+// Copyright 2021 Nick Brassel (@tzarc)
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+#include "qp_internal.h"
+#include "qp_comms.h"
+#include "qp_ili9163.h"
+#include "qp_ili9xxx_opcodes.h"
+#include "qp_tft_panel.h"
+
+#ifdef QUANTUM_PAINTER_ILI9163_SPI_ENABLE
+#    include "qp_comms_spi.h"
+#endif // QUANTUM_PAINTER_ILI9163_SPI_ENABLE
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// Common
+
+// Driver storage
+tft_panel_dc_reset_painter_device_t ili9163_drivers[ILI9163_NUM_DEVICES] = {0};
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// Initialization
+
+bool qp_ili9163_init(painter_device_t device, painter_rotation_t rotation) {
+    // clang-format off
+    const uint8_t ili9163_init_sequence[] = {
+        // Command,                 Delay,  N, Data[N]
+        ILI9XXX_CMD_RESET,            120,  0,
+        ILI9XXX_CMD_SLEEP_OFF,          5,  0,
+        ILI9XXX_SET_PIX_FMT,            0,  1, 0x55,
+        ILI9XXX_SET_GAMMA,              0,  1, 0x04,
+        ILI9XXX_ENABLE_3_GAMMA,         0,  1, 0x01,
+        ILI9XXX_SET_FUNCTION_CTL,       0,  2, 0xFF, 0x06,
+        ILI9XXX_SET_PGAMMA,             0, 15, 0x36, 0x29, 0x12, 0x22, 0x1C, 0x15, 0x42, 0xB7, 0x2F, 0x13, 0x12, 0x0A, 0x11, 0x0B, 0x06,
+        ILI9XXX_SET_NGAMMA,             0, 15, 0x09, 0x16, 0x2D, 0x0D, 0x13, 0x15, 0x40, 0x48, 0x53, 0x0C, 0x1D, 0x25, 0x2E, 0x34, 0x39,
+        ILI9XXX_SET_FRAME_CTL_NORMAL,   0,  2, 0x08, 0x02,
+        ILI9XXX_SET_POWER_CTL_1,        0,  2, 0x0A, 0x02,
+        ILI9XXX_SET_POWER_CTL_2,        0,  1, 0x02,
+        ILI9XXX_SET_VCOM_CTL_1,         0,  2, 0x50, 0x63,
+        ILI9XXX_SET_VCOM_CTL_2,         0,  1, 0x00,
+        ILI9XXX_CMD_PARTIAL_OFF,        0,  0,
+        ILI9XXX_CMD_DISPLAY_ON,        20,  0
+    };
+    // clang-format on
+    qp_comms_bulk_command_sequence(device, ili9163_init_sequence, sizeof(ili9163_init_sequence));
+
+    // Configure the rotation (i.e. the ordering and direction of memory writes in GRAM)
+    const uint8_t madctl[] = {
+        [QP_ROTATION_0]   = ILI9XXX_MADCTL_BGR,
+        [QP_ROTATION_90]  = ILI9XXX_MADCTL_BGR | ILI9XXX_MADCTL_MX | ILI9XXX_MADCTL_MV,
+        [QP_ROTATION_180] = ILI9XXX_MADCTL_BGR | ILI9XXX_MADCTL_MX | ILI9XXX_MADCTL_MY,
+        [QP_ROTATION_270] = ILI9XXX_MADCTL_BGR | ILI9XXX_MADCTL_MV | ILI9XXX_MADCTL_MY,
+    };
+    qp_comms_command_databyte(device, ILI9XXX_SET_MEM_ACS_CTL, madctl[rotation]);
+
+    return true;
+}
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// Driver vtable
+
+const struct tft_panel_dc_reset_painter_driver_vtable_t ili9163_driver_vtable = {
+    .base =
+        {
+            .init            = qp_ili9163_init,
+            .power           = qp_tft_panel_power,
+            .clear           = qp_tft_panel_clear,
+            .flush           = qp_tft_panel_flush,
+            .pixdata         = qp_tft_panel_pixdata,
+            .viewport        = qp_tft_panel_viewport,
+            .palette_convert = qp_tft_panel_palette_convert,
+            .append_pixels   = qp_tft_panel_append_pixels,
+        },
+    .rgb888_to_native16bit = qp_rgb888_to_rgb565_swapped,
+    .num_window_bytes      = 2,
+    .swap_window_coords    = false,
+    .opcodes =
+        {
+            .display_on         = ILI9XXX_CMD_DISPLAY_ON,
+            .display_off        = ILI9XXX_CMD_DISPLAY_OFF,
+            .set_column_address = ILI9XXX_SET_COL_ADDR,
+            .set_row_address    = ILI9XXX_SET_PAGE_ADDR,
+            .enable_writes      = ILI9XXX_SET_MEM,
+        },
+};
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// SPI
+
+#ifdef QUANTUM_PAINTER_ILI9163_SPI_ENABLE
+
+// Factory function for creating a handle to the ILI9163 device
+painter_device_t qp_ili9163_make_spi_device(uint16_t panel_width, uint16_t panel_height, pin_t chip_select_pin, pin_t dc_pin, pin_t reset_pin, uint16_t spi_divisor, int spi_mode) {
+    for (uint32_t i = 0; i < ILI9163_NUM_DEVICES; ++i) {
+        tft_panel_dc_reset_painter_device_t *driver = &ili9163_drivers[i];
+        if (!driver->base.driver_vtable) {
+            driver->base.driver_vtable         = (const struct painter_driver_vtable_t *)&ili9163_driver_vtable;
+            driver->base.comms_vtable          = (const struct painter_comms_vtable_t *)&spi_comms_with_dc_vtable;
+            driver->base.panel_width           = panel_width;
+            driver->base.panel_height          = panel_height;
+            driver->base.rotation              = QP_ROTATION_0;
+            driver->base.offset_x              = 0;
+            driver->base.offset_y              = 0;
+            driver->base.native_bits_per_pixel = 16; // RGB565
+
+            // SPI and other pin configuration
+            driver->base.comms_config                              = &driver->spi_dc_reset_config;
+            driver->spi_dc_reset_config.spi_config.chip_select_pin = chip_select_pin;
+            driver->spi_dc_reset_config.spi_config.divisor         = spi_divisor;
+            driver->spi_dc_reset_config.spi_config.lsb_first       = false;
+            driver->spi_dc_reset_config.spi_config.mode            = spi_mode;
+            driver->spi_dc_reset_config.dc_pin                     = dc_pin;
+            driver->spi_dc_reset_config.reset_pin                  = reset_pin;
+            return (painter_device_t)driver;
+        }
+    }
+    return NULL;
+}
+
+#endif // QUANTUM_PAINTER_ILI9163_SPI_ENABLE
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////