Merge remote-tracking branch 'origin/develop' into xap

* Added autoclicker, better mouse, vim like FN layer and more.

* Updated docs to comply with guidelines

* Fixed Imgur links

* increased step sizes

* updated readme to reflect step size

* Added second delay array for autoclicker to compensate for RGB animation CPU loads

* better RGB effects and updated docs

* better README.md formatting

* added DEBONCE libinput workaround for Linux

* fixed formatting

* fixed typos and clarified

* fixed layer picture order

* Update keyboards/dztech/dz65rgb/keymaps/yuannan/keymap.c

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

* Update keyboards/dztech/dz65rgb/keymaps/yuannan/README.md

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

* Updated Docs and rules

* Updated with the new deferred exec API to ensure more consistant CPS

* renamed README.md to be lower case to comply with fauxpark's request

* Remapped alt to be left instead of right for compatibility reasons

* Update keyboards/dztech/dz65rgb/keymaps/yuannan/config.h

Co-authored-by: Drashna Jaelre <drashna@live.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
@@ -35,4 +35,4 @@ jobs:
         AWS_ACCESS_KEY_ID: ${{ secrets.SPACES_ACCESS_KEY }}
         AWS_SECRET_ACCESS_KEY: ${{ secrets.SPACES_SECRET_KEY }}
         AWS_S3_ENDPOINT: https://nyc3.digitaloceanspaces.com
-        SOURCE_DIR: 'api_data'
+        SOURCE_DIR: '.build/api_data'

.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
@@ -35,4 +37,4 @@ jobs:
         AWS_ACCESS_KEY_ID: ${{ secrets.SPACES_ACCESS_KEY }}
         AWS_SECRET_ACCESS_KEY: ${{ secrets.SPACES_SECRET_KEY }}
         AWS_S3_ENDPOINT: https://nyc3.digitaloceanspaces.com
-        SOURCE_DIR: 'api_data'
+        SOURCE_DIR: '.build/api_data'

.github/workflows/develop_update.yml

@@ -5,7 +5,6 @@ on:
     branches:
     - master
 
-
 jobs:
   develop_update:
     runs-on: ubuntu-latest
@@ -13,8 +12,9 @@ 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: Checkout develop
@@ -22,14 +22,7 @@ jobs:
         git fetch origin master develop
         git checkout develop
 
-    - name: Check if branch locked
-      id: check_locked
-      uses: andstor/file-existence-action@v1
-      with:
-        files: ".locked"
-
     - name: Update develop from master
-      if: steps.check_locked.outputs.files_exists == 'false'
       run: |
         git config --global user.name "QMK Bot"
         git config --global user.email "hello@qmk.fm"

.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

@@ -0,0 +1,35 @@
+name: Update feature branches after develop merge
+
+on:
+  push:
+    branches:
+    - develop
+
+jobs:
+  feature_branch_update:
+    runs-on: ubuntu-latest
+
+    if: github.repository == 'qmk/qmk_firmware'
+
+    strategy:
+      matrix:
+        branch:
+        - xap
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        token: ${{ secrets.QMK_BOT_TOKEN }}
+        fetch-depth: 0
+
+    - name: Checkout branch
+      run: |
+        git fetch origin develop ${{ matrix.branch }}
+        git checkout ${{ matrix.branch }}
+
+    - name: Update branch from develop
+      run: |
+        git config --global user.name "QMK Bot"
+        git config --global user.email "hello@qmk.fm"
+        git merge origin/develop
+        git push origin ${{ 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,49 @@
+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: 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

.gitmodules

@@ -18,3 +18,6 @@
 [submodule "lib/printf"]
 	path = lib/printf
 	url = https://github.com/qmk/printf
+[submodule "lib/pico-sdk"]
+	path = lib/pico-sdk
+	url = https://github.com/qmk/pico-sdk.git

Makefile

@@ -401,6 +401,7 @@ ifndef SKIP_GIT
 	if [ ! -e lib/lufa ]; then git submodule sync lib/lufa && git submodule update --depth 50 --init lib/lufa; fi
 	if [ ! -e lib/vusb ]; then git submodule sync lib/vusb && git submodule update --depth 50 --init lib/vusb; fi
 	if [ ! -e lib/printf ]; then git submodule sync lib/printf && git submodule update --depth 50 --init lib/printf; fi
+	if [ ! -e lib/pico-sdk ]; then git submodule sync lib/pico-sdk && git submodule update --depth 50 --init lib/pico-sdk; fi
 	git submodule status --recursive 2>/dev/null | \
 	while IFS= read -r x; do \
 		case "$$x" in \

api_data/_config.yml

@@ -1 +0,0 @@
-theme: jekyll-theme-cayman

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.0, 3.1/2, 3.5, 3.6
+    ifneq (,$(filter $(MCU_ORIG), MKL26Z64 MK20DX128 MK20DX256 MK64FX512 MK66FX1M0))
+        FIRMWARE_FORMAT = hex
+    endif
 endif
 ifeq ($(strip $(BOOTLOADER)), caterina)
     OPT_DEFS += -DBOOTLOADER_CATERINA
@@ -194,6 +200,10 @@ ifeq ($(strip $(BOOTLOADER)), tinyuf2)
     OPT_DEFS += -DBOOTLOADER_TINYUF2
     BOOTLOADER_TYPE = tinyuf2
 endif
+ifeq ($(strip $(BOOTLOADER)), rp2040)
+    OPT_DEFS += -DBOOTLOADER_RP2040
+    BOOTLOADER_TYPE = rp2040
+endif
 ifeq ($(strip $(BOOTLOADER)), halfkay)
     OPT_DEFS += -DBOOTLOADER_HALFKAY
     BOOTLOADER_TYPE = halfkay
@@ -202,6 +212,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

@@ -1,4 +1,4 @@
-# Determine what keyboard we are building and setup the build environment.
+    # Determine what keyboard we are building and setup the build environment.
 #
 # We support folders up to 5 levels deep below `keyboards/`. This file is
 # responsible for determining which folder is being used and doing the
@@ -13,6 +13,14 @@ endif
 include paths.mk
 include $(BUILDDEFS_PATH)/message.mk
 
+# Helper to add defines with a 'QMK_' prefix
+define add_qmk_prefix_defs
+    ifdef $1
+        # Need to cater for 'STM32L4xx+'
+        OPT_DEFS += -DQMK_$(2)="$($1)" -DQMK_$(2)_$(shell echo $($1) | sed -e 's@+@Plus@g' -e 's@[^a-zA-Z0-9]@_@g' | tr '[:lower:]' '[:upper:]')
+    endif
+endef
+
 # Set the qmk cli to use
 QMK_BIN ?= qmk
 
@@ -159,22 +167,20 @@ ifneq ("$(wildcard $(KEYMAP_JSON))", "")
 
 # Add rules to generate the keymap files - indentation here is important
 $(KEYMAP_OUTPUT)/src/keymap.c: $(KEYMAP_JSON)
-	$(QMK_BIN) json2c --quiet --output $(KEYMAP_C) $(KEYMAP_JSON)
+	@$(SILENT) || printf "$(MSG_GENERATING) $@" | $(AWK_CMD)
+	$(eval CMD=$(QMK_BIN) json2c --quiet --output $(KEYMAP_C) $(KEYMAP_JSON))
+	@$(BUILD_CMD)
 
 $(KEYMAP_OUTPUT)/src/config.h: $(KEYMAP_JSON)
-	$(QMK_BIN) generate-config-h --quiet --keyboard $(KEYBOARD) --keymap $(KEYMAP) --output $(KEYMAP_H)
+	@$(SILENT) || printf "$(MSG_GENERATING) $@" | $(AWK_CMD)
+	$(eval CMD=$(QMK_BIN) generate-config-h --quiet --keyboard $(KEYBOARD) --keymap $(KEYMAP) --output $(KEYMAP_H))
+	@$(BUILD_CMD)
 
 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
 
@@ -324,17 +330,29 @@ 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)
-	$(QMK_BIN) generate-config-h --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/info_config.h
+	@$(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)
-	$(QMK_BIN) generate-keyboard-h --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/default_keyboard.h
+	@$(SILENT) || printf "$(MSG_GENERATING) $@" | $(AWK_CMD)
+	$(eval CMD=$(QMK_BIN) generate-keyboard-h --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/default_keyboard.h)
+	@$(BUILD_CMD)
 
 $(KEYBOARD_OUTPUT)/src/layouts.h: $(INFO_JSON_FILES)
-	$(QMK_BIN) generate-layouts --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/layouts.h
+	@$(SILENT) || printf "$(MSG_GENERATING) $@" | $(AWK_CMD)
+	$(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
 
@@ -380,10 +398,18 @@ ifneq ("$(KEYMAP_H)","")
     CONFIG_H += $(KEYMAP_H)
 endif
 
+OPT_DEFS += -DKEYMAP_C=\"$(KEYMAP_C)\"
+
+# If a keymap or userspace places their keymap array in another file instead, allow for it to be included
+# !!NOTE!! -- For this to work, the source file cannot be part of $(SRC), so users should not add it via `SRC += <file>`
+ifneq ($(strip $(INTROSPECTION_KEYMAP_C)),)
+OPT_DEFS += -DINTROSPECTION_KEYMAP_C=\"$(strip $(INTROSPECTION_KEYMAP_C))\"
+endif
+
 # project specific files
 SRC += \
     $(KEYBOARD_SRC) \
-    $(KEYMAP_C) \
+    $(QUANTUM_DIR)/keymap_introspection.c \
     $(QUANTUM_SRC) \
     $(QUANTUM_DIR)/main.c \
 
@@ -426,6 +452,14 @@ else
     include $(TMK_PATH)/protocol/$(PLATFORM_KEY).mk
 endif
 
+# Setup definitions based on the selected MCU
+$(eval $(call add_qmk_prefix_defs,MCU_ORIG,MCU))
+$(eval $(call add_qmk_prefix_defs,MCU_ARCH,MCU_ARCH))
+$(eval $(call add_qmk_prefix_defs,MCU_PORT_NAME,MCU_PORT_NAME))
+$(eval $(call add_qmk_prefix_defs,MCU_FAMILY,MCU_FAMILY))
+$(eval $(call add_qmk_prefix_defs,MCU_SERIES,MCU_SERIES))
+$(eval $(call add_qmk_prefix_defs,BOARD,BOARD))
+
 # TODO: remove this bodge?
 PROJECT_DEFS := $(OPT_DEFS)
 PROJECT_INC := $(VPATH) $(EXTRAINCDIRS) $(KEYBOARD_PATHS)
@@ -459,6 +493,19 @@ check-size: build
 check-md5: build
 objs-size: build
 
+ifeq ($(strip $(TOP_SYMBOLS)),yes)
+all: top-symbols
+check-size: top-symbols
+top-symbols: build
+	echo "###########################################"
+	echo "# Highest flash usage:"
+	$(NM) -Crtd --size-sort $(BUILD_DIR)/$(TARGET).elf | grep -i ' [t] ' | head -n10 | sed -e 's#^0000000#       #g' -e 's#^000000#      #g' -e 's#^00000#     #g' -e 's#^0000#    #g' -e 's#^000#   #g' -e 's#^00#  #g' -e 's#^0# #g'
+	echo "###########################################"
+	echo "# Highest RAM usage:"
+	$(NM) -Crtd --size-sort $(BUILD_DIR)/$(TARGET).elf | grep -i ' [dbv] ' | head -n10 | sed -e 's#^0000000#       #g' -e 's#^000000#      #g' -e 's#^00000#     #g' -e 's#^0000#    #g' -e 's#^000#   #g' -e 's#^00#  #g' -e 's#^0# #g'
+	echo "###########################################"
+endif
+
 include $(BUILDDEFS_PATH)/show_options.mk
 include $(BUILDDEFS_PATH)/common_rules.mk
 

builddefs/build_test.mk

@@ -4,6 +4,8 @@ endif
 
 .DEFAULT_GOAL := all
 
+OPT = g
+
 include paths.mk
 include $(BUILDDEFS_PATH)/message.mk
 
@@ -36,11 +38,11 @@ CREATE_MAP := no
 VPATH += \
 	$(LIB_PATH)/googletest \
 	$(LIB_PATH)/googlemock \
-	$(LIB_PATH)/printf
+	$(COMMON_VPATH) \
+	$(TEST_PATH)
 
 all: elf
 
-VPATH += $(COMMON_VPATH)
 PLATFORM:=TEST
 PLATFORM_KEY:=test
 BOOTLOADER_TYPE:=none
@@ -61,6 +63,8 @@ include $(TMK_PATH)/protocol.mk
 include $(QUANTUM_PATH)/debounce/tests/rules.mk
 include $(QUANTUM_PATH)/encoder/tests/rules.mk
 include $(QUANTUM_PATH)/sequencer/tests/rules.mk
+include $(QUANTUM_PATH)/wear_leveling/tests/rules.mk
+include $(QUANTUM_PATH)/logging/print.mk
 include $(PLATFORM_PATH)/test/rules.mk
 ifneq ($(filter $(FULL_TESTS),$(TEST)),)
 include $(BUILDDEFS_PATH)/build_full_test.mk
@@ -68,7 +72,6 @@ endif
 
 $(TEST)_SRC += \
 	tests/test_common/main.c \
-	$(LIB_PATH)/printf/printf.c \
 	$(QUANTUM_PATH)/logging/print.c
 
 $(TEST_OBJ)/$(TEST)_SRC := $($(TEST)_SRC)

builddefs/common_features.mk

@@ -15,7 +15,6 @@
 
 QUANTUM_SRC += \
     $(QUANTUM_DIR)/quantum.c \
-    $(QUANTUM_DIR)/send_string.c \
     $(QUANTUM_DIR)/bitwise.c \
     $(QUANTUM_DIR)/led.c \
     $(QUANTUM_DIR)/action.c \
@@ -45,6 +44,10 @@ else ifeq ($(strip $(DEBUG_MATRIX_SCAN_RATE_ENABLE)), api)
     OPT_DEFS += -DDEBUG_MATRIX_SCAN_RATE
 endif
 
+ifeq ($(strip $(XAP_ENABLE)), yes)
+    include $(BUILDDEFS_PATH)/xap.mk
+endif
+
 AUDIO_ENABLE ?= no
 ifeq ($(strip $(AUDIO_ENABLE)), yes)
     ifeq ($(PLATFORM),CHIBIOS)
@@ -92,10 +95,29 @@ ifeq ($(MUSIC_ENABLE), yes)
     SRC += $(QUANTUM_DIR)/process_keycode/process_music.c
 endif
 
+VALID_STENO_PROTOCOL_TYPES := geminipr txbolt all
+STENO_PROTOCOL ?= all
 ifeq ($(strip $(STENO_ENABLE)), yes)
+    ifeq ($(filter $(STENO_PROTOCOL),$(VALID_STENO_PROTOCOL_TYPES)),)
+        $(call CATASTROPHIC_ERROR,Invalid STENO_PROTOCOL,STENO_PROTOCOL="$(STENO_PROTOCOL)" is not a valid stenography protocol)
+    else
         OPT_DEFS += -DSTENO_ENABLE
         VIRTSER_ENABLE ?= yes
+
+        ifeq ($(strip $(STENO_PROTOCOL)), geminipr)
+            OPT_DEFS += -DSTENO_ENABLE_GEMINI
+        endif
+        ifeq ($(strip $(STENO_PROTOCOL)), txbolt)
+            OPT_DEFS += -DSTENO_ENABLE_BOLT
+        endif
+        ifeq ($(strip $(STENO_PROTOCOL)), all)
+            OPT_DEFS += -DSTENO_ENABLE_ALL
+            OPT_DEFS += -DSTENO_ENABLE_GEMINI
+            OPT_DEFS += -DSTENO_ENABLE_BOLT
+        endif
+
         SRC += $(QUANTUM_DIR)/process_keycode/process_steno.c
+    endif
 endif
 
 ifeq ($(strip $(VIRTSER_ENABLE)), yes)
@@ -108,15 +130,16 @@ ifeq ($(strip $(MOUSEKEY_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/mousekey.c
 endif
 
-VALID_POINTING_DEVICE_DRIVER_TYPES := adns5050 adns9800 analog_joystick cirque_pinnacle_i2c cirque_pinnacle_spi pmw3360 pmw3389 pimoroni_trackball custom
+VALID_POINTING_DEVICE_DRIVER_TYPES := adns5050 adns9800 analog_joystick cirque_pinnacle_i2c cirque_pinnacle_spi paw3204 pmw3360 pmw3389 pimoroni_trackball custom
 ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
     ifeq ($(filter $(POINTING_DEVICE_DRIVER),$(VALID_POINTING_DEVICE_DRIVER_TYPES)),)
         $(call CATASTROPHIC_ERROR,Invalid POINTING_DEVICE_DRIVER,POINTING_DEVICE_DRIVER="$(POINTING_DEVICE_DRIVER)" is not a valid pointing device type)
     else
         OPT_DEFS += -DPOINTING_DEVICE_ENABLE
         MOUSE_ENABLE := yes
-        SRC += $(QUANTUM_DIR)/pointing_device.c
-        SRC += $(QUANTUM_DIR)/pointing_device_drivers.c
+        VPATH += $(QUANTUM_DIR)/pointing_device
+        SRC += $(QUANTUM_DIR)/pointing_device/pointing_device.c
+        SRC += $(QUANTUM_DIR)/pointing_device/pointing_device_drivers.c
         ifneq ($(strip $(POINTING_DEVICE_DRIVER)), custom)
             SRC += drivers/sensors/$(strip $(POINTING_DEVICE_DRIVER)).c
             OPT_DEFS += -DPOINTING_DEVICE_DRIVER_$(strip $(shell echo $(POINTING_DEVICE_DRIVER) | tr '[:lower:]' '[:upper:]'))
@@ -131,51 +154,61 @@ ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
         else ifeq ($(strip $(POINTING_DEVICE_DRIVER)), cirque_pinnacle_i2c)
             OPT_DEFS += -DSTM32_I2C -DHAL_USE_I2C=TRUE
             SRC += drivers/sensors/cirque_pinnacle.c
+            SRC += drivers/sensors/cirque_pinnacle_gestures.c
+            SRC += $(QUANTUM_DIR)/pointing_device/pointing_device_gestures.c
             QUANTUM_LIB_SRC += i2c_master.c
         else ifeq ($(strip $(POINTING_DEVICE_DRIVER)), cirque_pinnacle_spi)
             OPT_DEFS += -DSTM32_SPI -DHAL_USE_SPI=TRUE
             SRC += drivers/sensors/cirque_pinnacle.c
+            SRC += drivers/sensors/cirque_pinnacle_gestures.c
+            SRC += $(QUANTUM_DIR)/pointing_device/pointing_device_gestures.c
             QUANTUM_LIB_SRC += spi_master.c
         else ifeq ($(strip $(POINTING_DEVICE_DRIVER)), pimoroni_trackball)
             OPT_DEFS += -DSTM32_SPI -DHAL_USE_I2C=TRUE
             QUANTUM_LIB_SRC += i2c_master.c
-        else ifeq ($(strip $(POINTING_DEVICE_DRIVER)), pmw3360)
-            OPT_DEFS += -DSTM32_SPI -DHAL_USE_SPI=TRUE
-            QUANTUM_LIB_SRC += spi_master.c
-        else ifeq ($(strip $(POINTING_DEVICE_DRIVER)), pmw3389)
+        else ifneq ($(filter $(strip $(POINTING_DEVICE_DRIVER)),pmw3360 pmw3389),)
             OPT_DEFS += -DSTM32_SPI -DHAL_USE_SPI=TRUE
+            SRC += drivers/sensors/pmw33xx_common.c
             QUANTUM_LIB_SRC += spi_master.c
         endif
     endif
 endif
 
-VALID_EEPROM_DRIVER_TYPES := vendor custom transient i2c spi
+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 wear_leveling
 EEPROM_DRIVER ?= vendor
 ifeq ($(filter $(EEPROM_DRIVER),$(VALID_EEPROM_DRIVER_TYPES)),)
   $(call CATASTROPHIC_ERROR,Invalid EEPROM_DRIVER,EEPROM_DRIVER="$(EEPROM_DRIVER)" is not a valid EEPROM driver)
 else
   OPT_DEFS += -DEEPROM_ENABLE
+  COMMON_VPATH += $(PLATFORM_PATH)/$(PLATFORM_KEY)/$(DRIVER_DIR)/eeprom
+  COMMON_VPATH += $(DRIVER_PATH)/eeprom
+  COMMON_VPATH += $(PLATFORM_COMMON_DIR)
   ifeq ($(strip $(EEPROM_DRIVER)), custom)
     # Custom EEPROM implementation -- only needs to implement init/erase/read_block/write_block
     OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_CUSTOM
-    COMMON_VPATH += $(DRIVER_PATH)/eeprom
     SRC += eeprom_driver.c
+  else ifeq ($(strip $(EEPROM_DRIVER)), wear_leveling)
+    # Wear-leveling EEPROM implementation
+    OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_WEAR_LEVELING
+    SRC += eeprom_driver.c eeprom_wear_leveling.c
   else ifeq ($(strip $(EEPROM_DRIVER)), i2c)
     # External I2C EEPROM implementation
     OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_I2C
-    COMMON_VPATH += $(DRIVER_PATH)/eeprom
     QUANTUM_LIB_SRC += i2c_master.c
     SRC += eeprom_driver.c eeprom_i2c.c
   else ifeq ($(strip $(EEPROM_DRIVER)), spi)
     # External SPI EEPROM implementation
     OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_SPI
-    COMMON_VPATH += $(DRIVER_PATH)/eeprom
     QUANTUM_LIB_SRC += spi_master.c
     SRC += eeprom_driver.c eeprom_spi.c
   else ifeq ($(strip $(EEPROM_DRIVER)), transient)
     # Transient EEPROM implementation -- no data storage but provides runtime area for it
     OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_TRANSIENT
-    COMMON_VPATH += $(DRIVER_PATH)/eeprom
     SRC += eeprom_driver.c eeprom_transient.c
   else ifeq ($(strip $(EEPROM_DRIVER)), vendor)
     # Vendor-implemented EEPROM
@@ -186,17 +219,18 @@ else
       ifneq ($(filter STM32F3xx_% STM32F1xx_% %_STM32F401xC %_STM32F401xE %_STM32F405xG %_STM32F411xE %_STM32F072xB %_STM32F042x6 %_GD32VF103xB %_GD32VF103x8, $(MCU_SERIES)_$(MCU_LDSCRIPT)),)
         # Emulated EEPROM
         OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_STM32_FLASH_EMULATED
-        COMMON_VPATH += $(DRIVER_PATH)/eeprom
-        SRC += eeprom_driver.c
-        SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c
-        SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
+        COMMON_VPATH += $(PLATFORM_PATH)/$(PLATFORM_KEY)/$(DRIVER_DIR)/flash
+        COMMON_VPATH += $(DRIVER_PATH)/flash
+        SRC += eeprom_driver.c eeprom_stm32.c flash_stm32.c
       else ifneq ($(filter $(MCU_SERIES),STM32L0xx STM32L1xx),)
         # True EEPROM on STM32L0xx, L1xx
         OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_STM32_L0_L1
-        COMMON_VPATH += $(DRIVER_PATH)/eeprom
-        COMMON_VPATH += $(PLATFORM_PATH)/$(PLATFORM_KEY)/$(DRIVER_DIR)/eeprom
-        SRC += eeprom_driver.c
-        SRC += eeprom_stm32_L0_L1.c
+        SRC += eeprom_driver.c eeprom_stm32_L0_L1.c
+      else ifneq ($(filter $(MCU_SERIES),RP2040),)
+		# Wear-leveling EEPROM implementation, backed by RP2040 flash
+		OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_WEAR_LEVELING
+		SRC += eeprom_driver.c eeprom_wear_leveling.c
+        WEAR_LEVELING_DRIVER = rp2040_flash
       else ifneq ($(filter $(MCU_SERIES),KL2x K20x),)
         # Teensy EEPROM implementations
         OPT_DEFS += -DEEPROM_TEENSY
@@ -204,32 +238,64 @@ else
       else
         # Fall back to transient, i.e. non-persistent
         OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_TRANSIENT
-        COMMON_VPATH += $(DRIVER_PATH)/eeprom
         SRC += eeprom_driver.c eeprom_transient.c
       endif
     else ifeq ($(PLATFORM),ARM_ATSAM)
       # arm_atsam EEPROM
       OPT_DEFS += -DEEPROM_SAMD
-      SRC += $(PLATFORM_COMMON_DIR)/eeprom_samd.c
+      SRC += eeprom_samd.c
     else ifeq ($(PLATFORM),TEST)
       # Test harness "EEPROM"
       OPT_DEFS += -DEEPROM_TEST_HARNESS
-      SRC += $(PLATFORM_COMMON_DIR)/eeprom.c
+      SRC += eeprom.c
+    endif
+  endif
+endif
+
+VALID_WEAR_LEVELING_DRIVER_TYPES := custom embedded_flash spi_flash rp2040_flash legacy
+WEAR_LEVELING_DRIVER ?= none
+ifneq ($(strip $(WEAR_LEVELING_DRIVER)),none)
+  ifeq ($(filter $(WEAR_LEVELING_DRIVER),$(VALID_WEAR_LEVELING_DRIVER_TYPES)),)
+    $(call CATASTROPHIC_ERROR,Invalid WEAR_LEVELING_DRIVER,WEAR_LEVELING_DRIVER="$(WEAR_LEVELING_DRIVER)" is not a valid wear leveling driver)
+  else
+    FNV_ENABLE := yes
+    OPT_DEFS += -DWEAR_LEVELING_ENABLE
+    OPT_DEFS += -DWEAR_LEVELING_$(strip $(shell echo $(WEAR_LEVELING_DRIVER) | tr '[:lower:]' '[:upper:]'))
+    COMMON_VPATH += $(PLATFORM_PATH)/$(PLATFORM_KEY)/$(DRIVER_DIR)/wear_leveling
+    COMMON_VPATH += $(DRIVER_PATH)/wear_leveling
+    COMMON_VPATH += $(QUANTUM_DIR)/wear_leveling
+    SRC += wear_leveling.c
+    ifeq ($(strip $(WEAR_LEVELING_DRIVER)), embedded_flash)
+      OPT_DEFS += -DHAL_USE_EFL
+      SRC += wear_leveling_efl.c
+      POST_CONFIG_H += $(PLATFORM_PATH)/$(PLATFORM_KEY)/$(DRIVER_DIR)/wear_leveling/wear_leveling_efl_config.h
+    else ifeq ($(strip $(WEAR_LEVELING_DRIVER)), spi_flash)
+      FLASH_DRIVER := spi
+      SRC += wear_leveling_flash_spi.c
+      POST_CONFIG_H += $(DRIVER_PATH)/wear_leveling/wear_leveling_flash_spi_config.h
+    else ifeq ($(strip $(WEAR_LEVELING_DRIVER)), rp2040_flash)
+      SRC += wear_leveling_rp2040_flash.c
+      POST_CONFIG_H += $(DRIVER_PATH)/wear_leveling/wear_leveling_rp2040_flash_config.h
+    else ifeq ($(strip $(WEAR_LEVELING_DRIVER)), legacy)
+      COMMON_VPATH += $(PLATFORM_PATH)/$(PLATFORM_KEY)/$(DRIVER_DIR)/flash
+      SRC += flash_stm32.c wear_leveling_legacy.c
+      POST_CONFIG_H += $(PLATFORM_PATH)/$(PLATFORM_KEY)/$(DRIVER_DIR)/wear_leveling/wear_leveling_legacy_config.h
     endif
   endif
 endif
 
 VALID_FLASH_DRIVER_TYPES := spi
-FLASH_DRIVER ?= no
-ifneq ($(strip $(FLASH_DRIVER)), no)
+FLASH_DRIVER ?= none
+ifneq ($(strip $(FLASH_DRIVER)), none)
     ifeq ($(filter $(FLASH_DRIVER),$(VALID_FLASH_DRIVER_TYPES)),)
-        $(error FLASH_DRIVER="$(FLASH_DRIVER)" is not a valid FLASH driver)
+        $(call CATASTROPHIC_ERROR,Invalid FLASH_DRIVER,FLASH_DRIVER="$(FLASH_DRIVER)" is not a valid flash driver)
     else
         OPT_DEFS += -DFLASH_ENABLE
-        ifeq ($(strip $(FLASH_DRIVER)), spi)
+        ifeq ($(strip $(FLASH_DRIVER)),spi)
             OPT_DEFS += -DFLASH_DRIVER -DFLASH_SPI
             COMMON_VPATH += $(DRIVER_PATH)/flash
             SRC += flash_spi.c
+            QUANTUM_LIB_SRC += spi_master.c
         endif
     endif
 endif
@@ -495,7 +561,7 @@ ifeq ($(strip $(BACKLIGHT_ENABLE)), yes)
     endif
 endif
 
-VALID_WS2812_DRIVER_TYPES := bitbang pwm spi i2c
+VALID_WS2812_DRIVER_TYPES := bitbang pwm spi i2c vendor
 
 WS2812_DRIVER ?= bitbang
 ifeq ($(strip $(WS2812_DRIVER_REQUIRED)), yes)
@@ -537,12 +603,6 @@ ifeq ($(strip $(LED_TABLES)), yes)
     SRC += $(QUANTUM_DIR)/led_tables.c
 endif
 
-ifeq ($(strip $(TERMINAL_ENABLE)), yes)
-    SRC += $(QUANTUM_DIR)/process_keycode/process_terminal.c
-    OPT_DEFS += -DTERMINAL_ENABLE
-    OPT_DEFS += -DUSER_PRINT
-endif
-
 ifeq ($(strip $(VIA_ENABLE)), yes)
     DYNAMIC_KEYMAP_ENABLE := yes
     RAW_ENABLE := yes
@@ -551,6 +611,22 @@ ifeq ($(strip $(VIA_ENABLE)), yes)
     OPT_DEFS += -DVIA_ENABLE
 endif
 
+ifeq ($(strip $(XAP_ENABLE)), yes)
+    ifeq ($(strip $(VIA_ENABLE)), yes)
+        $(error 'XAP_ENABLE = $(XAP_ENABLE)' deprecates 'VIA_ENABLE = $(VIA_ENABLE)'. Please set 'VIA_ENABLE = no')
+    endif
+
+    DYNAMIC_KEYMAP_ENABLE := yes
+    FNV_ENABLE := yes
+    SECURE_ENABLE := yes
+    BOOTMAGIC_ENABLE := yes
+
+    OPT_DEFS += -DXAP_ENABLE
+    OPT_DEFS += -DBOOTLOADER_JUMP_SUPPORTED
+    VPATH += $(QUANTUM_DIR)/xap
+    SRC += $(QUANTUM_DIR)/xap/xap.c $(QUANTUM_DIR)/xap/xap_handlers.c
+endif
+
 VALID_MAGIC_TYPES := yes
 BOOTMAGIC_ENABLE ?= no
 ifneq ($(strip $(BOOTMAGIC_ENABLE)), no)
@@ -590,6 +666,14 @@ ifneq ($(strip $(DEBOUNCE_TYPE)), custom)
     QUANTUM_SRC += $(QUANTUM_DIR)/debounce/$(strip $(DEBOUNCE_TYPE)).c
 endif
 
+
+VALID_SERIAL_DRIVER_TYPES := bitbang usart vendor
+
+SERIAL_DRIVER ?= bitbang
+ifeq ($(filter $(SERIAL_DRIVER),$(VALID_SERIAL_DRIVER_TYPES)),)
+    $(call CATASTROPHIC_ERROR,Invalid SERIAL_DRIVER,SERIAL_DRIVER="$(SERIAL_DRIVER)" is not a valid SERIAL driver)
+endif
+
 ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
     POST_CONFIG_H += $(QUANTUM_DIR)/split_common/post_config.h
     OPT_DEFS += -DSPLIT_KEYBOARD
@@ -614,11 +698,11 @@ ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
             endif
         endif
 
-        SERIAL_DRIVER ?= bitbang
         OPT_DEFS += -DSERIAL_DRIVER_$(strip $(shell echo $(SERIAL_DRIVER) | tr '[:lower:]' '[:upper:]'))
         ifeq ($(strip $(SERIAL_DRIVER)), bitbang)
             QUANTUM_LIB_SRC += serial.c
         else
+            QUANTUM_LIB_SRC += serial_protocol.c
             QUANTUM_LIB_SRC += serial_$(strip $(SERIAL_DRIVER)).c
         endif
     endif
@@ -630,6 +714,12 @@ ifeq ($(strip $(CRC_ENABLE)), yes)
     SRC += crc.c
 endif
 
+ifeq ($(strip $(FNV_ENABLE)), yes)
+    OPT_DEFS += -DFNV_ENABLE
+    VPATH += $(LIB_PATH)/fnv
+    SRC += qmk_fnv_type_validation.c hash_32a.c hash_64a.c
+endif
+
 ifeq ($(strip $(HAPTIC_ENABLE)),yes)
     COMMON_VPATH += $(DRIVER_PATH)/haptic
 
@@ -646,8 +736,9 @@ ifeq ($(strip $(HAPTIC_ENABLE)),yes)
 endif
 
 ifeq ($(strip $(HD44780_ENABLE)), yes)
-    SRC += platforms/avr/drivers/hd44780.c
     OPT_DEFS += -DHD44780_ENABLE
+    COMMON_VPATH += $(DRIVER_PATH)/lcd
+    SRC += hd44780.c
 endif
 
 VALID_OLED_DRIVER_TYPES := SSD1306 custom
@@ -695,7 +786,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
@@ -704,6 +796,13 @@ ifeq ($(strip $(MAGIC_ENABLE)), yes)
     OPT_DEFS += -DMAGIC_KEYCODE_ENABLE
 endif
 
+SEND_STRING_ENABLE ?= yes
+ifeq ($(strip $(SEND_STRING_ENABLE)), yes)
+    OPT_DEFS += -DSEND_STRING_ENABLE
+    COMMON_VPATH += $(QUANTUM_DIR)/send_string
+    SRC += $(QUANTUM_DIR)/send_string/send_string.c
+endif
+
 ifeq ($(strip $(AUTO_SHIFT_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/process_keycode/process_auto_shift.c
     OPT_DEFS += -DAUTO_SHIFT_ENABLE

builddefs/common_rules.mk

@@ -1,19 +1,5 @@
 # Hey Emacs, this is a -*- makefile -*-
 #----------------------------------------------------------------------------
-# WinAVR Makefile Template written by Eric B. Weddington, Jg Wunsch, et al.
-#
-# Released to the Public Domain
-#
-# Additional material for this makefile was written by:
-# Peter Fleury
-# Tim Henigan
-# Colin O'Flynn
-# Reiner Patommel
-# Markus Pfaff
-# Sander Pool
-# Frederik Rouleau
-# Carlos Lamas
-#
 
 # Enable vpath seraching for source files only
 # Without this, output files, could be read from the wrong .build directories
@@ -38,36 +24,15 @@ NO_LTO_OBJ := $(filter %.a,$(OBJ))
 
 MASTER_OUTPUT := $(firstword $(OUTPUTS))
 
-
-
 # Output format. (can be srec, ihex, binary)
 FORMAT = ihex
 
 # Optimization level, can be [0, 1, 2, 3, s].
-#     0 = turn off optimization. s = optimize for size.
-#     (Note: 3 is not always the best optimization level. See avr-libc FAQ.)
 OPT ?= s
 
-# Compiler flag to set the C Standard level.
-#     c89   = "ANSI" C
-#     gnu89 = c89 plus GCC extensions
-#     c99   = ISO C99 standard (not yet fully implemented)
-#     gnu99 = c99 plus GCC extensions
-CSTANDARD = -std=gnu99
-
-
-# Place -D or -U options here for C sources
-#CDEFS +=
-
-
-# Place -D or -U options here for ASM sources
-#ADEFS +=
-
-
-# Place -D or -U options here for C++ sources
-#CXXDEFS += -D__STDC_LIMIT_MACROS
-#CXXDEFS += -D__STDC_CONSTANT_MACROS
-#CXXDEFS +=
+# Compiler flag to set the C and C++ language standard level
+CSTANDARD = -std=gnu11
+CXXSTANDARD = -std=gnu++14
 
 # Speed up recompilations by opt-in usage of ccache
 USE_CCACHE ?= no
@@ -75,15 +40,11 @@ ifneq ($(USE_CCACHE),no)
     CC_PREFIX ?= ccache
 endif
 
-#---------------- Compiler Options C ----------------
-#  -g*:          generate debugging information
-#  -O*:          optimization level
-#  -f...:        tuning, see GCC manual and avr-libc documentation
-#  -Wall...:     warning level
-#  -Wa,...:      tell GCC to pass this to the assembler.
+#---------------- C Compiler Options ----------------
+
 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
@@ -111,23 +72,14 @@ CFLAGS += -Wstrict-prototypes
 ifneq ($(strip $(ALLOW_WARNINGS)), yes)
     CFLAGS += -Werror
 endif
-#CFLAGS += -mshort-calls
-#CFLAGS += -fno-unit-at-a-time
-#CFLAGS += -Wundef
-#CFLAGS += -Wunreachable-code
-#CFLAGS += -Wsign-compare
 CFLAGS += $(CSTANDARD)
 
 # This fixes lots of keyboards linking errors but SHOULDN'T BE A FINAL SOLUTION
 # Fixing of multiple variable definitions must be made.
 CFLAGS += -fcommon
 
-#---------------- Compiler Options C++ ----------------
-#  -g*:          generate debugging information
-#  -O*:          optimization level
-#  -f...:        tuning, see GCC manual and avr-libc documentation
-#  -Wall...:     warning level
-#  -Wa,...:      tell GCC to pass this to the assembler.
+#---------------- C++ Compiler Options ----------------
+
 ifeq ($(strip $(DEBUG_ENABLE)),yes)
   CXXFLAGS += -g$(DEBUG)
 endif
@@ -141,57 +93,17 @@ CXXFLAGS += -Wundef
 ifneq ($(strip $(ALLOW_WARNINGS)), yes)
     CXXFLAGS += -Werror
 endif
-#CXXFLAGS += -mshort-calls
-#CXXFLAGS += -fno-unit-at-a-time
-#CXXFLAGS += -Wstrict-prototypes
-#CXXFLAGS += -Wunreachable-code
-#CXXFLAGS += -Wsign-compare
-#CXXFLAGS += $(CSTANDARD)
 
 #---------------- Assembler Options ----------------
+
 ASFLAGS += $(ADEFS)
 ifeq ($(VERBOSE_AS_CMD),yes)
 	ASFLAGS += -v
 endif
 
-#---------------- Library Options ----------------
-# Minimalistic printf version
-PRINTF_LIB_MIN = -Wl,-u,vfprintf -lprintf_min
-
-# Floating point printf version (requires MATH_LIB = -lm below)
-PRINTF_LIB_FLOAT = -Wl,-u,vfprintf -lprintf_flt
-
-# If this is left blank, then it will use the Standard printf version.
-PRINTF_LIB =
-#PRINTF_LIB = $(PRINTF_LIB_MIN)
-#PRINTF_LIB = $(PRINTF_LIB_FLOAT)
-
-
-# Minimalistic scanf version
-SCANF_LIB_MIN = -Wl,-u,vfscanf -lscanf_min
-
-# Floating point + %[ scanf version (requires MATH_LIB = -lm below)
-SCANF_LIB_FLOAT = -Wl,-u,vfscanf -lscanf_flt
-
-# If this is left blank, then it will use the Standard scanf version.
-SCANF_LIB =
-#SCANF_LIB = $(SCANF_LIB_MIN)
-#SCANF_LIB = $(SCANF_LIB_FLOAT)
-
-
-MATH_LIB = -lm
-CREATE_MAP ?= yes
-
-
 #---------------- Linker Options ----------------
-#  -Wl,...:     tell GCC to pass this to linker.
-#    -Map:      create map file
-#    --cref:    add cross reference to  map file
-#
-# Comennt out "--relax" option to avoid a error such:
-# 	(.vectors+0x30): relocation truncated to fit: R_AVR_13_PCREL against symbol `__vector_12'
-#
 
+CREATE_MAP ?= yes
 ifeq ($(CREATE_MAP),yes)
 	LDFLAGS += -Wl,-Map=$(BUILD_DIR)/$(TARGET).map,--cref
 endif
@@ -201,20 +113,11 @@ endif
 #LDFLAGS += -Wl,--relax
 LDFLAGS += $(EXTMEMOPTS)
 LDFLAGS += $(patsubst %,-L%,$(EXTRALIBDIRS))
-LDFLAGS += $(PRINTF_LIB) $(SCANF_LIB) $(MATH_LIB)
-#LDFLAGS += -T linker_script.x
+LDFLAGS += -lm
 # You can give EXTRALDFLAGS at 'make' command line.
 LDFLAGS += $(EXTRALDFLAGS)
 
 #---------------- Assembler Listings ----------------
-#  -Wa,...:   tell GCC to pass this to the assembler.
-#  -adhlns:   create listing
-#  -gstabs:   have the assembler create line number information; note that
-#             for use in COFF files, additional information about filenames
-#             and function names needs to be present in the assembler source
-#             files -- see avr-libc docs [FIXME: not yet described there]
-#  -listing-cont-lines: Sets the maximum number of continuation lines of hex
-#       dump that will be displayed for a given single line of source input.
 
 ADHLNS_ENABLE ?= no
 ifeq ($(ADHLNS_ENABLE),yes)
@@ -316,7 +219,7 @@ gccversion :
 	@$(BUILD_CMD)
 
 %.uf2: %.hex
-	$(eval CMD=$(UF2CONV) $(BUILD_DIR)/$(TARGET).hex -o $(BUILD_DIR)/$(TARGET).uf2 -c -f $(UF2_FAMILY) >/dev/null 2>&1)
+	$(eval CMD=$(UF2CONV) $(BUILD_DIR)/$(TARGET).hex --output $(BUILD_DIR)/$(TARGET).uf2 --convert --family $(UF2_FAMILY) >/dev/null 2>&1)
 	#@$(SILENT) || printf "$(MSG_EXECUTING) '$(CMD)':\n"
 	@$(SILENT) || printf "$(MSG_UF2) $@" | $(AWK_CMD)
 	@$(BUILD_CMD)

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 \
@@ -25,12 +26,14 @@ GENERIC_FEATURES = \
     DYNAMIC_KEYMAP \
     DYNAMIC_MACRO \
     ENCODER \
+    ENCODER_MAP \
     GRAVE_ESC \
     HAPTIC \
     KEY_LOCK \
     KEY_OVERRIDE \
     LEADER \
     PROGRAMMABLE_BUTTON \
+    SECURE \
     SPACE_CADET \
     SWAP_HANDS \
     TAP_DANCE \

builddefs/mcu_selection.mk

@@ -9,7 +9,9 @@ ifneq ($(findstring MKL26Z64, $(MCU)),)
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
   MCU_FAMILY = KINETIS
   MCU_SERIES = KL2x
 
@@ -36,7 +38,9 @@ ifneq ($(findstring MK20DX128, $(MCU)),)
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
   MCU_FAMILY = KINETIS
   MCU_SERIES = K20x
 
@@ -63,7 +67,9 @@ ifneq ($(findstring MK20DX256, $(MCU)),)
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
   MCU_FAMILY = KINETIS
   MCU_SERIES = K20x
 
@@ -81,7 +87,7 @@ ifneq ($(findstring MK20DX256, $(MCU)),)
   BOARD ?= PJRC_TEENSY_3_1
 endif
 
-ifneq ($(findstring MK66FX1M0, $(MCU)),)
+ifneq ($(findstring MK64FX512, $(MCU)),)
   # Cortex version
   MCU = cortex-m4
 
@@ -92,6 +98,35 @@ ifneq ($(findstring MK66FX1M0, $(MCU)),)
   # - the next two should match the directories in
   #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
   MCU_FAMILY = KINETIS
+  MCU_SERIES = K60x
+
+  # Linker script to use
+  # - it should exist either in <chibios>/os/common/ports/ARMCMx/compilers/GCC/ld/
+  #   or <keyboard_dir>/ld/
+  MCU_LDSCRIPT ?= MK64FX512
+
+  # Startup code to use
+  #  - it should exist in <chibios>/os/common/startup/ARMCMx/compilers/GCC/mk/
+  MCU_STARTUP ?= k60x
+
+  # Board: it should exist either in <chibios>/os/hal/boards/,
+  # <keyboard_dir>/boards/, or drivers/boards/
+  BOARD ?= PJRC_TEENSY_3_5
+endif
+
+ifneq ($(findstring MK66FX1M0, $(MCU)),)
+  # Cortex version
+  MCU = cortex-m4
+
+  # ARM version, CORTEX-M0/M1 are 6, CORTEX-M3/M4/M7 are 7
+  ARMV = 7
+
+  ## chip/board settings
+  # - the next two should match the directories in
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  MCU_FAMILY = KINETIS
   MCU_SERIES = MK66F18
 
   # Linker script to use
@@ -108,6 +143,41 @@ ifneq ($(findstring MK66FX1M0, $(MCU)),)
   BOARD ?= PJRC_TEENSY_3_6
 endif
 
+ifneq ($(findstring RP2040, $(MCU)),)
+  # Cortex version
+  MCU = cortex-m0plus
+
+  # ARM version, CORTEX-M0/M1 are 6, CORTEX-M3/M4/M7 are 7
+  CHIBIOS_PORT = ARMv6-M-RP2
+
+  ## 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 = RP
+  MCU_SERIES = RP2040
+
+  # Linker script to use
+  # - it should exist either in <chibios>/os/common/ports/ARMCMx/compilers/GCC/ld/
+  #   or <keyboard_dir>/ld/
+  STARTUPLD_CONTRIB = $(CHIBIOS_CONTRIB)/os/common/startup/ARMCMx/compilers/GCC/ld
+  MCU_LDSCRIPT ?= RP2040_FLASH_TIMECRIT
+  LDFLAGS += -L $(STARTUPLD_CONTRIB)
+
+  # Startup code to use
+  #  - it should exist in <chibios>/os/common/startup/ARMCMx/compilers/GCC/mk/
+  MCU_STARTUP ?= rp2040
+
+  # Board: it should exist either in <chibios>/os/hal/boards/,
+  # <keyboard_dir>/boards/, or drivers/boards/
+  BOARD ?= GENERIC_PROMICRO_RP2040
+
+  # Default UF2 Bootloader settings
+  UF2_FAMILY ?= RP2040
+  FIRMWARE_FORMAT ?= uf2
+endif
+
 ifneq ($(findstring STM32F042, $(MCU)),)
   # Cortex version
   MCU = cortex-m0
@@ -117,7 +187,9 @@ ifneq ($(findstring STM32F042, $(MCU)),)
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
   MCU_FAMILY = STM32
   MCU_SERIES = STM32F0xx
 
@@ -157,7 +229,9 @@ ifneq ($(findstring STM32F072, $(MCU)),)
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
   MCU_FAMILY = STM32
   MCU_SERIES = STM32F0xx
 
@@ -192,7 +266,9 @@ ifneq ($(findstring STM32F103, $(MCU)),)
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
   MCU_FAMILY = STM32
   MCU_SERIES = STM32F1xx
 
@@ -224,7 +300,9 @@ ifneq ($(findstring STM32F303, $(MCU)),)
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
   MCU_FAMILY = STM32
   MCU_SERIES = STM32F3xx
 
@@ -259,7 +337,9 @@ ifneq ($(findstring STM32F401, $(MCU)),)
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
   MCU_FAMILY = STM32
   MCU_SERIES = STM32F4xx
 
@@ -299,7 +379,9 @@ ifneq ($(findstring STM32F405, $(MCU)),)
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
   MCU_FAMILY = STM32
   MCU_SERIES = STM32F4xx
 
@@ -334,7 +416,9 @@ ifneq ($(findstring STM32F407, $(MCU)),)
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
   MCU_FAMILY = STM32
   MCU_SERIES = STM32F4xx
 
@@ -369,7 +453,9 @@ ifneq ($(findstring STM32F411, $(MCU)),)
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
   MCU_FAMILY = STM32
   MCU_SERIES = STM32F4xx
 
@@ -409,7 +495,9 @@ ifneq ($(findstring STM32F446, $(MCU)),)
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
   MCU_FAMILY = STM32
   MCU_SERIES = STM32F4xx
 
@@ -441,7 +529,9 @@ ifneq ($(findstring STM32G431, $(MCU)),)
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
   MCU_FAMILY = STM32
   MCU_SERIES = STM32G4xx
 
@@ -476,7 +566,9 @@ ifneq ($(findstring STM32G474, $(MCU)),)
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
   MCU_FAMILY = STM32
   MCU_SERIES = STM32G4xx
 
@@ -511,7 +603,9 @@ ifneq (,$(filter $(MCU),STM32L432 STM32L442))
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
   MCU_FAMILY = STM32
   MCU_SERIES = STM32L4xx
 
@@ -548,7 +642,9 @@ ifneq (,$(filter $(MCU),STM32L433 STM32L443))
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
   MCU_FAMILY = STM32
   MCU_SERIES = STM32L4xx
 
@@ -585,7 +681,9 @@ ifneq (,$(filter $(MCU),STM32L412 STM32L422))
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
   MCU_FAMILY = STM32
   MCU_SERIES = STM32L4xx
 
@@ -602,7 +700,7 @@ ifneq (,$(filter $(MCU),STM32L412 STM32L422))
   # <keyboard_dir>/boards/, or drivers/boards/
   BOARD ?= GENERIC_STM32_L412XB
 
-  PLATFORM_NAME ?= platform_l432
+  PLATFORM_NAME ?= platform_l412_l422
 
   USE_FPU ?= yes
 
@@ -622,7 +720,9 @@ ifneq ($(findstring WB32F3G71, $(MCU)),)
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <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 = WB32F3G71xx
 
@@ -642,7 +742,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
 
@@ -657,7 +790,10 @@ ifneq ($(findstring GD32VF103, $(MCU)),)
 
   ## chip/board settings
   # - the next two should match the directories in
-  #   <chibios>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_PORT_NAME)/$(MCU_SERIES)
+  #   OR
+  #   <chibios[-contrib]>/os/hal/ports/$(MCU_FAMILY)/$(MCU_SERIES)
+  MCU_PORT_NAME = GD
   MCU_FAMILY = GD32V
   MCU_SERIES = GD32VF103
 

builddefs/message.mk

@@ -63,6 +63,7 @@ MSG_COMPILING_CXX = Compiling:
 MSG_ASSEMBLING = Assembling:
 MSG_CLEANING = Cleaning project:
 MSG_CREATING_LIBRARY = Creating library:
+MSG_GENERATING = Generating:
 MSG_SUBMODULE_DIRTY = $(WARN_COLOR)WARNING:$(NO_COLOR) Some git submodules are out of date or modified.\n\
 Please consider running $(BOLD)make git-submodule$(NO_COLOR).\n\n
 MSG_NO_CMP = $(ERROR_COLOR)Error:$(NO_COLOR)$(BOLD) cmp command not found, please install diffutils\n$(NO_COLOR)

builddefs/show_options.mk

@@ -5,7 +5,6 @@ BUILD_OPTION_NAMES = \
   CONSOLE_ENABLE \
   COMMAND_ENABLE \
   NKRO_ENABLE \
-  TERMINAL_ENABLE \
   CUSTOM_MATRIX \
   DEBOUNCE_TYPE \
   SPLIT_KEYBOARD \
@@ -46,6 +45,7 @@ OTHER_OPTION_NAMES = \
   LEADER_ENABLE \
   PRINTING_ENABLE \
   STENO_ENABLE \
+  STENO_PROTOCOL \
   TAP_DANCE_ENABLE \
   VIRTSER_ENABLE \
   OLED_ENABLE \
@@ -57,6 +57,7 @@ OTHER_OPTION_NAMES = \
   HELIX ZINC \
   AUTOLOG_ENABLE \
   DEBUG_ENABLE \
+  ENCODER_MAP_ENABLE \
   ENCODER_ENABLE_CUSTOM \
   GERMAN_ENABLE \
   HAPTIC_ENABLE \
@@ -79,7 +80,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)"

builddefs/testlist.mk

@@ -2,7 +2,9 @@ TEST_LIST = $(sort $(patsubst %/test.mk,%, $(shell find $(ROOT_DIR)tests -type f
 FULL_TESTS := $(notdir $(TEST_LIST))
 
 include $(QUANTUM_PATH)/debounce/tests/testlist.mk
+include $(QUANTUM_PATH)/encoder/tests/testlist.mk
 include $(QUANTUM_PATH)/sequencer/tests/testlist.mk
+include $(QUANTUM_PATH)/wear_leveling/tests/testlist.mk
 include $(PLATFORM_PATH)/test/testlist.mk
 
 define VALIDATE_TEST_LIST

builddefs/xap.mk

@@ -0,0 +1,41 @@
+# Copyright 2022 Nick Brassel (@tzarc)
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+XAP_FILES := $(shell ls -1 data/xap/* | sort | xargs echo)
+ifneq ("$(wildcard $(KEYBOARD_PATH_1)/xap.hjson)","")
+	XAP_FILES += $(KEYBOARD_PATH_1)/xap.hjson
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_2)/xap.hjson)","")
+	XAP_FILES += $(KEYBOARD_PATH_2)/xap.hjson
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_3)/xap.hjson)","")
+	XAP_FILES += $(KEYBOARD_PATH_3)/xap.hjson
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_4)/xap.hjson)","")
+	XAP_FILES += $(KEYBOARD_PATH_4)/xap.hjson
+endif
+ifneq ("$(wildcard $(KEYBOARD_PATH_5)/xap.hjson)","")
+	XAP_FILES += $(KEYBOARD_PATH_5)/xap.hjson
+endif
+ifneq ("$(wildcard $(KEYMAP_PATH)/xap.hjson)","")
+	XAP_FILES += $(KEYMAP_PATH)/xap.hjson
+endif
+
+$(KEYMAP_OUTPUT)/src/config_blob_gz.h: $(INFO_JSON_FILES)
+	@$(SILENT) || printf "$(MSG_GENERATING) $@" | $(AWK_CMD)
+	$(eval CMD=$(QMK_BIN) xap-generate-qmk-blob-h -o "$(KEYMAP_OUTPUT)/src/config_blob_gz.h" -kb $(KEYBOARD) -km $(KEYMAP))
+	@$(BUILD_CMD)
+
+$(KEYMAP_OUTPUT)/src/xap_generated.inl: $(XAP_FILES)
+	@$(SILENT) || printf "$(MSG_GENERATING) $@" | $(AWK_CMD)
+	$(eval CMD=$(QMK_BIN) xap-generate-qmk-inc -o "$(KEYMAP_OUTPUT)/src/xap_generated.inl" -kb $(KEYBOARD) -km $(KEYMAP))
+	@$(BUILD_CMD)
+
+$(KEYMAP_OUTPUT)/src/xap_generated.h: $(XAP_FILES)
+	@$(SILENT) || printf "$(MSG_GENERATING) $@" | $(AWK_CMD)
+	$(eval CMD=$(QMK_BIN) xap-generate-qmk-h -o "$(KEYMAP_OUTPUT)/src/xap_generated.h" -kb $(KEYBOARD) -km $(KEYMAP))
+	@$(BUILD_CMD)
+
+generated-files: $(KEYMAP_OUTPUT)/src/config_blob_gz.h $(KEYMAP_OUTPUT)/src/xap_generated.inl $(KEYMAP_OUTPUT)/src/xap_generated.h
+
+VPATH += $(KEYMAP_OUTPUT)/src

data/mappings/defaults.json

@@ -0,0 +1,53 @@
+{
+    "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"
+        },
+        "kb2040": {
+            "processor": "RP2040",
+            "bootloader": "rp2040",
+            "board": "QMK_PM2040",
+            "pin_compatible": "promicro"
+        },
+        "promicro_rp2040": {
+            "processor": "RP2040",
+            "bootloader": "rp2040",
+            "board": "QMK_PM2040",
+            "pin_compatible": "promicro"
+        },
+        "blok": {
+            "processor": "RP2040",
+            "bootloader": "rp2040",
+            "board": "QMK_PM2040",
+            "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

@@ -3,22 +3,27 @@
 {
     # Format:
     # <config.h key>: {"info_key": <info.json key>, ["value_type": <value_type>], ["to_json": <true/false>], ["to_c": <true/false>]}
-    # value_type: one of "array", "array.int", "bool", "int", "hex", "list", "mapping"
+    # value_type: one of "array", "array.int", "bool", "int", "hex", "list", "mapping", "str", "raw"
     # 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
     "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_ON_STATE": {"info_key": "backlight.on_state", "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", "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"},
@@ -31,6 +36,9 @@
     "LED_CAPS_LOCK_PIN": {"info_key": "indicators.caps_lock"},
     "LED_NUM_LOCK_PIN": {"info_key": "indicators.num_lock"},
     "LED_SCROLL_LOCK_PIN": {"info_key": "indicators.scroll_lock"},
+    "LED_COMPOSE_PIN": {"info_key": "indicators.compose"},
+    "LED_KANA_PIN": {"info_key": "indicators.kana"},
+    "LED_PIN_ON_STATE": {"info_key": "indicators.on_state", "value_type": "int"},
     "MANUFACTURER": {"info_key": "manufacturer"},
     "MATRIX_HAS_GHOST": {"info_key": "matrix_pins.ghost", "value_type": "bool"},
     "MATRIX_IO_DELAY": {"info_key": "matrix_pins.io_delay", "value_type": "int"},
@@ -78,6 +86,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 +107,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},
+    "PREVENT_STUCK_MODIFIERS": {"info_key": "_invalid.prevent_stuck_mods", "invalid": true},
 }

data/mappings/info_rules.json

@@ -3,13 +3,17 @@
 {
     # Format:
     # <rules.mk key>: {"info_key": <info.json key>, ["value_type": <value_type>], ["to_json": <true/false>], ["to_c": <true/false>]}
-    # value_type: one of "array", "array.int", "bool", "int", "list", "hex", "mapping"
+    # value_type: one of "array", "array.int", "bool", "int", "list", "hex", "mapping", "str", "raw"
     # 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
     "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"},
+    "ENCODER_ENABLE": {"info_key": "encoder.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,16 @@
     "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", "value_type": "str", "to_c": false},
-    "WAIT_FOR_USB": {"info_key": "usb.wait_for", "value_type": "bool"}
+    "SPLIT_TRANSPORT": {"info_key": "split.transport.protocol", "to_c": false},
+    "WAIT_FOR_USB": {"info_key": "usb.wait_for", "value_type": "bool"},
+    "STENO_ENABLE": {"info_key": "stenography.enabled", "value_type": "bool"},
+    "STENO_PROTOCOL": {"info_key": "stenography.protocol"},
+
+    # Items we want flagged in lint
+    "CTPC": {"info_key": "_deprecated.ctpc", "deprecated": true},
+    "CONVERT_TO_PROTON_C": {"info_key": "_deprecated.ctpc", "deprecated": true},
+    "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/mappings/xap_defaults.json

@@ -0,0 +1,7 @@
+{
+    "secure": {
+        "unlock_sequence": [ [0,0] ],
+        "unlock_timeout": 5000,
+        "idle_timeout": 60000
+    }
+}

data/schemas/definitions.jsonschema

@@ -1,5 +1,5 @@
 {
-    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$schema": "https://json-schema.org/draft/2020-12/schema#",
     "$id": "qmk.definitions.v1",
     "title": "Common definitions used across QMK's jsonschemas.",
     "type": "object",
@@ -12,6 +12,12 @@
         "minLength": 1,
         "pattern": "^[0-9a-z_]*$"
     },
+    "define": {
+        "type": "string",
+        "minLength": 2,
+        "maxLength": 50,
+        "pattern": "^[A-Z_]*$"
+    },
     "hex_number_2d": {
         "type": "string",
         "pattern": "^0x[0-9A-F]{2}$"
@@ -24,6 +30,10 @@
         "type": "string",
         "pattern": "^[0-9]{1,2}\\.[0-9]\\.[0-9]$"
     },
+    "text_unsigned_int": {
+        "type": "string",
+        "pattern": "^[0-8]+$"
+    },
     "text_identifier": {
         "type": "string",
         "minLength": 1,
@@ -41,8 +51,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 +65,7 @@
                     "LAYOUT_planck_1x2uR",
                     "LAYOUT_preonic_1x2uC",
                     "LAYOUT_preonic_1x2uL",
-                    "LAYOUT_preonic_1x2uR",
-                    "LAYOUT_reviung34_2uL"
+                    "LAYOUT_preonic_1x2uR"
                 ]
             },
             {
@@ -68,8 +75,23 @@
         ]
     },
     "key_unit": {
-        "type": "number",
-        "min": 0.25
+        "type": "number"
+    },
+    "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",
@@ -90,8 +112,11 @@
                 "pattern": "^LINE_PIN\\d{1,2}$"
             },
             {
-                "type": "number",
-                "multipleOf": 1
+                "type": "string",
+                "pattern": "^GP\\d{1,2}$"
+            },
+            {
+                "type": "integer"
             },
             {
                 "type": "null"
@@ -102,14 +127,12 @@
         "type": "number"
     },
     "signed_int": {
-        "type": "number",
-        "multipleOf": 1
+        "type": "integer"
     },
     "signed_int_8": {
-        "type": "number",
-        "min": -127,
-        "max": 127,
-        "multipleOf": 1
+        "type": "integer",
+        "minimum": -127,
+        "maximum": 127
     },
     "string_array": {
         "type": "array",
@@ -125,17 +148,20 @@
     },
     "unsigned_decimal": {
         "type": "number",
-        "min": 0
+        "minimum": 0
     },
     "unsigned_int": {
-        "type": "number",
-        "min": 0,
-        "multipleOf": 1
+        "type": "integer",
+        "minimum": 0
     },
     "unsigned_int_8": {
-        "type": "number",
-        "min": 0,
-        "max": 255,
-        "multipleOf": 1
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 255
+    },
+    "bit": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 1
     }
 }

data/schemas/keyboard.jsonschema

@@ -1,19 +1,48 @@
 {
-    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$schema": "https://json-schema.org/draft/2020-12/schema#",
     "$id": "qmk.keyboard.v1",
     "title": "Keyboard Information",
+    "definitions": {
+        "encoder_config": {
+            "type": "object",
+            "properties": {
+                "rotary": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "required": ["pin_a", "pin_b"],
+                        "properties": {
+                            "pin_a": {"$ref": "qmk.definitions.v1#/mcu_pin"},
+                            "pin_b": {"$ref": "qmk.definitions.v1#/mcu_pin"},
+                            "resolution": {"$ref": "qmk.definitions.v1#/unsigned_int"} 
+                        }
+                    }
+                }
+            }
+        }
+    },
     "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", "kb2040", "promicro_rp2040", "blok", "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", "MK64FX512", "MK66FX1M0", "RP2040", "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",
@@ -31,12 +60,12 @@
                 "breathing": {"type": "boolean"},
                 "breathing_period": {"$ref": "qmk.definitions.v1#/unsigned_int_8"},
                 "levels": {
-                    "type": "number",
-                    "min": 1,
-                    "max": 31,
-                    "multipleOf": 1
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 31
                 },
-                "pin": {"$ref": "qmk.definitions.v1#/mcu_pin"}
+                "pin": {"$ref": "qmk.definitions.v1#/mcu_pin"},
+                "on_state": {"$ref": "qmk.definitions.v1#/bit"}
             }
         },
         "bluetooth": {
@@ -57,7 +86,7 @@
         },
         "bootloader": {
             "type": "string",
-            "enum": ["atmel-dfu", "bootloadhid", "bootloadHID", "custom", "caterina", "halfkay", "kiibohd", "lufa-dfu", "lufa-ms", "md-boot", "qmk-dfu", "qmk-hid", "stm32-dfu", "stm32duino", "gd32v-dfu", "wb32-dfu", "unknown", "usbasploader", "USBasp", "tinyuf2"],
+            "enum": ["atmel-dfu", "bootloadhid", "bootloadHID", "custom", "caterina", "halfkay", "kiibohd", "lufa-dfu", "lufa-ms", "md-boot", "qmk-dfu", "qmk-hid", "stm32-dfu", "stm32duino", "gd32v-dfu", "wb32-dfu", "unknown", "usbasploader", "USBasp", "tinyuf2", "rp2040"],
         },
         "bootloader_instructions": {
             "type": "string",
@@ -83,6 +112,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": {
@@ -94,13 +133,22 @@
             "type": "array",
             "items": {"$ref": "qmk.definitions.v1#/filename"}
         },
+        "encoder": {
+            "$ref": "#/definitions/encoder_config",
+            "properties": {
+                "enabled": {"type": "boolean"}
+            }
+        },
         "features": {"$ref": "qmk.definitions.v1#/boolean_array"},
         "indicators": {
             "type": "object",
             "properties": {
                 "caps_lock": {"$ref": "qmk.definitions.v1#/mcu_pin"},
                 "num_lock": {"$ref": "qmk.definitions.v1#/mcu_pin"},
-                "scroll_lock": {"$ref": "qmk.definitions.v1#/mcu_pin"}
+                "scroll_lock": {"$ref": "qmk.definitions.v1#/mcu_pin"},
+                "compose": {"$ref": "qmk.definitions.v1#/mcu_pin"},
+                "kana": {"$ref": "qmk.definitions.v1#/mcu_pin"},
+                "on_state": {"$ref": "qmk.definitions.v1#/bit"}
             }
         },
         "layout_aliases": {
@@ -126,18 +174,20 @@
                             "type": "object",
                             "additionalProperties": false,
                             "properties": {
-                                "label": {"type": "string"},
+                                "label": {
+                                    "type": "string",
+                                    "pattern": "^[^\\n]*$"
+                                },
                                 "matrix": {
                                     "type": "array",
                                     "minItems": 2,
                                     "maxItems": 2,
                                     "items": {
-                                        "type": "number",
-                                        "min": 0,
-                                        "multipleOf": 1
+                                        "type": "integer",
+                                        "minimum": 0
                                     }
                                 },
-                                "r": {"$ref": "qmk.definitions.v1#/unsigned_decimal"},
+                                "r": {"$ref": "qmk.definitions.v1#/signed_decimal"},
                                 "rx": {"$ref": "qmk.definitions.v1#/unsigned_decimal"},
                                 "ry": {"$ref": "qmk.definitions.v1#/unsigned_decimal"},
                                 "h": {"$ref": "qmk.definitions.v1#/key_unit"},
@@ -193,6 +243,60 @@
                 "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": "integer",
+                                    "minimum": 0
+                                }
+                            },
+                            "x": {"$ref": "qmk.definitions.v1#/key_unit"},
+                            "y": {"$ref": "qmk.definitions.v1#/key_unit"},
+                            "flags": {"$ref": "qmk.definitions.v1#/unsigned_int_8"}
+                        }
+                    }
+                }
+            }
+        },
+        "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": "integer",
+                                    "minimum": 0
+                                }
+                            },
+                            "x": {"$ref": "qmk.definitions.v1#/key_unit"},
+                            "y": {"$ref": "qmk.definitions.v1#/key_unit"},
+                            "flags": {"$ref": "qmk.definitions.v1#/unsigned_int_8"}
+                        }
+                    }
+                }
+            }
+        },
         "rgblight": {
             "type": "object",
             "additionalProperties": false,
@@ -212,10 +316,9 @@
                         "blink": {"type": "boolean"},
                         "enabled": {"type": "boolean"},
                         "max": {
-                            "type": "number",
-                            "min": 1,
-                            "max": 32,
-                            "multipleOf": 1
+                            "type": "integer",
+                            "minimum": 1,
+                            "maximum": 32
                         },
                         "override_rgb": {"type": "boolean"}
                     }
@@ -229,12 +332,46 @@
                 "split": {"type": "boolean"},
                 "split_count": {
                     "type": "array",
-                    "minLength": 2,
-                    "maxLength": 2,
+                    "minItems": 2,
+                    "maxItems": 2,
                     "items": {"$ref": "qmk.definitions.v1#/unsigned_int"}
                 }
             }
         },
+        "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",
+                    "minItems": 1,
+                    "maxItems": 5,
+                    "items": {
+                        "type": "array",
+                        "minItems": 2,
+                        "maxItems": 2,
+                        "items": {
+                            "type": "integer",
+                            "minimum": 0
+                        }
+                    }
+                }
+            }
+        },
+        "stenography": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "enabled": {"type": "boolean"},
+                "protocol": {
+                    "type": "string",
+                    "enum": ["all", "geminipr", "txbolt"]
+                }
+            }
+        },
         "split": {
             "type": "object",
             "additionalProperties": false,
@@ -263,16 +400,24 @@
                         }
                     }
                 },
+                "encoder": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "right": {
+                            "$ref": "#/definitions/encoder_config"
+                        }
+                    }
+                },
                 "main": {
                     "type": "string",
                     "enum": ["eeprom", "left", "matrix_grid", "pin", "right"]
                 },
                 "soft_serial_pin": {"$ref": "qmk.definitions.v1#/mcu_pin"},
                 "soft_serial_speed": {
-                    "type": "number",
-                    "min": 0,
-                    "max": 5,
-                    "multipleOf": 1
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 5
                 },
                 "transport": {
                     "type": "object",
@@ -326,7 +471,7 @@
                 "force_nkro": {"type": "boolean"},
                 "pid": {"$ref": "qmk.definitions.v1#/hex_number_4d"},
                 "vid": {"$ref": "qmk.definitions.v1#/hex_number_4d"},
-                "max_power": {"$ref": "qmk.definitions.v1#/unsigned_int_8"},
+                "max_power": {"$ref": "qmk.definitions.v1#/unsigned_int"},
                 "no_startup_check": {"type": "boolean"},
                 "polling_interval": {"$ref": "qmk.definitions.v1#/unsigned_int_8"},
                 "shared_endpoint": {
@@ -337,7 +482,7 @@
                         "mouse": {"type": "boolean"}
                     }
                 },
-                "suspend_wakeup_delay": {"$ref": "qmk.definitions.v1#/unsigned_int_8"},
+                "suspend_wakeup_delay": {"$ref": "qmk.definitions.v1#/unsigned_int"},
                 "wait_for": {"type": "boolean"},
             }
         },
@@ -346,8 +491,8 @@
             "additionalProperties": false,
             "properties": {
                 "keys_per_scan": {"$ref": "qmk.definitions.v1#/unsigned_int_8"},
-                "tap_keycode_delay": {"$ref": "qmk.definitions.v1#/unsigned_int_8"},
-                "tap_capslock_delay": {"$ref": "qmk.definitions.v1#/unsigned_int_8"},
+                "tap_keycode_delay": {"$ref": "qmk.definitions.v1#/unsigned_int"},
+                "tap_capslock_delay": {"$ref": "qmk.definitions.v1#/unsigned_int"},
             }
         },
         "qmk_lufa_bootloader": {

data/schemas/keymap.jsonschema

@@ -1,5 +1,5 @@
 {
-    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$schema": "https://json-schema.org/draft/2020-12/schema#",
     "$id": "qmk.keymap.v1",
     "title": "Keymap Information",
     "type": "object",
@@ -50,8 +50,7 @@
         },
         "config": {"$ref": "qmk.keyboard.v1"},
         "notes": {
-            "type": "string",
-            "description": "asdf"
+            "type": "string"
         }
     },
     "required": [

data/schemas/xap.jsonschema

@@ -0,0 +1,261 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "qmk.xap.v1",
+    "title": "XAP Spec",
+    "definitions": {
+        "data_type": {
+            "oneOf": [
+                {
+                    "enum": [
+                        "bool",
+                        "u8",
+                        "u16",
+                        "u32",
+                        "u64",
+                        "struct",
+                        "string"
+                    ]
+                },
+                {
+                    "type": "string",
+                    "pattern": "^u\\d{1,2}\\[\\d{1,2}\\]*$"
+                }
+            ]
+        },
+        "router_type": {
+            "enum": [
+                "command",
+                "router"
+            ]
+        },
+        "permission": {
+            "enum": [
+                "secure"
+            ]
+        },
+        "struct": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                    "name",
+                    "type"
+                ],
+                "properties": {
+                    "name": {
+                        "type": "string"
+                    },
+                    "type": {
+                        "type": "string"
+                    }
+                }
+            }
+        },
+        "route": {
+            "type": "object",
+            "propertyNames": {
+                "$ref": "qmk.definitions.v1#/hex_number_2d"
+            },
+            "additionalProperties": {
+                "type": "object",
+                "required": [
+                    "type",
+                    "define"
+                ],
+                "additionalProperties": false,
+                "properties": {
+                    "type": {
+                        "$ref": "#/definitions/router_type"
+                    },
+                    "name": {
+                        "type": "string"
+                    },
+                    "description": {
+                        "type": "string"
+                    },
+                    "define": {
+                        "$ref": "qmk.definitions.v1#/define"
+                    },
+                    "permissions": {
+                        "$ref": "#/definitions/permission"
+                    },
+                    "enable_if_preprocessor": {
+                        "type": "string"
+                    },
+                    "request_type": {
+                        "$ref": "#/definitions/data_type"
+                    },
+                    "request_struct_length": {
+                        "type": "number"
+                    },
+                    "request_purpose": {
+                        "type": "string"
+                    },
+                    "return_type": {
+                        "$ref": "#/definitions/data_type"
+                    },
+                    "request_struct_members": {
+                        "$ref": "#definitions/struct"
+                    },
+                    "return_struct_length": {
+                        "type": "number"
+                    },
+                    "return_constant": {
+                        "type": [
+                            "array",
+                            "string"
+                        ]
+                    },
+                    "return_struct_members": {
+                        "$ref": "#definitions/struct"
+                    },
+                    "return_purpose": {
+                        "type": "string"
+                    },
+                    "return_execute": {
+                        "type": "string"
+                    },
+                    "routes": {
+                        "$ref": "#/definitions/route"
+                    }
+                }
+            }
+        }
+    },
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+        "version"
+    ],
+    "properties": {
+        "version": {
+            "$ref": "qmk.definitions.v1#/bcd_version"
+        },
+        "define": {
+            "$ref": "qmk.definitions.v1#/define"
+        },
+        "uses": {
+            "type": "object",
+            "additionalProperties": {
+                "$ref": "qmk.definitions.v1#/bcd_version"
+            }
+        },
+        "documentation": {
+            "type": "object",
+            "properties": {
+                "order": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                }
+            },
+            "additionalProperties": {
+                "type": "string"
+            }
+        },
+        "term_definitions": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "string"
+            }
+        },
+        "type_docs": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "string"
+            }
+        },
+        "type_definitions": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                    "name": {
+                        "type": "string"
+                    },
+                    "description": {
+                        "type": "string"
+                    },
+                    "type": {
+                        "$ref": "#/definitions/data_type"
+                    },
+                    "struct_length": {
+                        "type": "number"
+                    },
+                    "struct_members": {
+                        "$ref": "#definitions/struct"
+                    }
+                }
+            }
+        },
+        "response_flags": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "define_prefix": {
+                    "$ref": "qmk.definitions.v1#/define"
+                },
+                "bits": {
+                    "type": "object",
+                    "propertyNames": {
+                        "$ref": "qmk.definitions.v1#/text_unsigned_int"
+                    },
+                    "additionalProperties": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "properties": {
+                            "name": {
+                                "type": "string"
+                            },
+                            "define": {
+                                "$ref": "qmk.definitions.v1#/define"
+                            },
+                            "description": {
+                                "type": "string"
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "broadcast_messages": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "define_prefix": {
+                    "$ref": "qmk.definitions.v1#/define"
+                },
+                "messages": {
+                    "type": "object",
+                    "propertyNames": {
+                        "$ref": "qmk.definitions.v1#/hex_number_2d"
+                    },
+                    "additionalProperties": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "properties": {
+                            "name": {
+                                "type": "string"
+                            },
+                            "define": {
+                                "$ref": "qmk.definitions.v1#/define"
+                            },
+                            "description": {
+                                "type": "string"
+                            },
+                            "return_type": {
+                                "$ref": "#/definitions/data_type"
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "routes": {
+            "$ref": "#/definitions/route"
+        }
+    }
+}

data/templates/xap/client/python/routes.py.j2

@@ -0,0 +1,14 @@
+
+class XAPRouteError(Exception):
+    pass
+
+
+class XAPRoutes():
+{%- for id, route in xap.routes | dictsort %}
+{%- if route.routes %}
+    # {{route.define}}
+{%- for subid, subroute in route.routes | dictsort %}
+    {{route.define}}_{{subroute.define}} = b'\x{{ '%02d' % id|int(base=16) }}\x{{ '%02d' % subid|int(base=16) }}'
+{%- endfor %}
+{%- endif %}
+{%- endfor %}

data/templates/xap/client/python/types.py.j2

@@ -0,0 +1,39 @@
+from collections import namedtuple
+from enum import IntFlag, IntEnum
+from struct import Struct
+
+{% set type_definitions = [{'name':'XAPRequest', 'members': 'token length data', 'fmt':'<HB61s'}, {'name':'XAPResponse', 'members': 'token flags length data', 'fmt':'<HBB60s'}] %}
+{% for item in type_definitions -%}
+class {{ item.name }}(namedtuple('{{ item.name }}', '{{ item.members }}')):
+    fmt = Struct('{{ item.fmt }}')
+
+    def __new__(cls, *args):
+        return super().__new__(cls, *args)
+
+    @classmethod
+    def from_bytes(cls, data):
+        return cls._make(cls.fmt.unpack(data))
+
+    def to_bytes(self):
+        return self.fmt.pack(*list(self))
+
+
+{% endfor -%}
+class XAPSecureStatus(IntEnum):
+    LOCKED = 0x00
+    UNLOCKING = 0x01
+    UNLOCKED = 0x02
+
+
+class XAPEventType(IntEnum):
+{%- for id, message in xap.broadcast_messages.messages | dictsort %}
+    {{ message.define }} = {{ id }}
+{%- endfor %}
+
+
+class XAPFlags(IntFlag):
+{%- for bitnum, bitinfo in xap.response_flags.bits | dictsort %}
+{%- if bitinfo.define != "-" %}
+    {{ bitinfo.define }} = 1 << {{ bitnum }}
+{%- endif %}
+{%- endfor %}

data/templates/xap/docs/broadcast_messages.md.j2

@@ -0,0 +1,4 @@
+{%- for id, message in xap.broadcast_messages.messages | dictsort %}
+### {{ message.name }} - `{{ id }}`
+{{ message.description }}
+{%- endfor %}

data/templates/xap/docs/docs.md.j2

@@ -0,0 +1,7 @@
+{%- for item in xap.documentation.order -%}
+{%- if not item[0:1] == '!' -%}
+{{ xap.documentation.get(item) }}
+{% else %}
+{%- include item[1:] %}
+{% endif %}
+{% endfor %}

data/templates/xap/docs/response_flags.md.j2

@@ -0,0 +1,9 @@
+|{% for bitnum, bitinfo in xap.response_flags.bits | dictsort | reverse %} Bit {{ bitnum }} |{% endfor %}
+|{% for bitnum, bitinfo in xap.response_flags.bits | dictsort | reverse %} -- |{% endfor %}
+|{% for bitnum, bitinfo in xap.response_flags.bits | dictsort | reverse %} `{{ bitinfo.define }}` |{%- endfor %}
+
+{% for bitnum, bitinfo in xap.response_flags.bits | dictsort | reverse %}
+{%- if bitinfo.define != "-" -%}
+* Bit {{ bitnum }} (`{{ bitinfo.define }}`): {{ bitinfo.description }}
+{% endif %}
+{%- endfor %}

data/templates/xap/docs/route_request.md.j2

@@ -0,0 +1,8 @@
+{%- if subroute.request_type == 'struct' -%}
+__Request:__
+{%- for member in subroute.request_struct_members -%}
+<br>{{ "&nbsp;"|safe*4 }}* {{ member.name }}: `{{ member.type }}`
+{%- endfor -%}
+{%- elif subroute.request_type -%}
+__Request:__ `{{ subroute.request_type }}`
+{%- endif -%}

data/templates/xap/docs/route_response.md.j2

@@ -0,0 +1,8 @@
+{%- if subroute.return_type == 'struct' -%}
+__Response:__
+{%- for member in subroute.return_struct_members -%}
+<br>{{ "&nbsp;"|safe*4 }}* {{ member.name }}: `{{ member.type }}`
+{%- endfor -%}
+{%- elif subroute.return_type -%}
+__Response:__ `{{ subroute.return_type }}`
+{%- endif -%}

data/templates/xap/docs/routes.md.j2

@@ -0,0 +1,12 @@
+{%- for id, route in xap.routes | dictsort %}
+### {{ route.name }} - `{{ id }}`
+{{ route.description }}
+
+{% if route.routes %}
+| Name | Route | Tags | Payloads | Description |
+| -- | -- | -- | -- | -- |
+{%- for subid, subroute in route.routes | dictsort %}
+| {{ subroute.name }} | `{{ id }} {{ subid }}` | {% if 'secure' == subroute.permissions %}__Secure__{% endif %} | {%- include 'route_request.md.j2' -%}{%- if subroute.return_type and subroute.request_type -%}<br><br>{% endif %}{%- include 'route_response.md.j2' -%} | {{ subroute.description.replace('\n', '<br>') }}|
+{%- endfor %}
+{% endif %}
+{%- endfor %}

data/templates/xap/docs/term_definitions.md.j2

@@ -0,0 +1,8 @@
+| Name | Definition |
+| -- | -- |
+{%- for type, definition in xap.term_definitions | dictsort %}
+| _{{ type }}_ | {{ definition }} |
+{%- endfor %}
+{%- for type, definition in xap.type_definitions | dictsort %}
+| _{{ definition.name }}_ | {{ definition.description }}{% if 'struct' == definition.type %} Takes the format:{% for item in definition.struct_members %}<br>`{{ item.type }}` - {{ item.name }}{%- endfor %}{% endif %} |
+{%- endfor %}

data/templates/xap/docs/type_docs.md.j2

@@ -0,0 +1,5 @@
+| Name | Definition |
+| -- | -- |
+{%- for type, definition in xap.type_docs | dictsort %}
+| _{{ type }}_ | {{ definition }} |
+{%- endfor %}

data/xap/xap_0.0.1.hjson

@@ -0,0 +1,237 @@
+{
+    version: 0.0.1
+
+    // Needed for table generation
+    define: XAP_ROUTE
+
+    // Documentation section is used purely for `qmk xap-generate-docs`.
+    documentation: {
+        order: [
+            page_header
+            type_docs
+            !type_docs.md.j2
+            term_definitions
+            !term_definitions.md.j2
+            request_response
+            reserved_tokens
+            response_flags
+            !response_flags.md.j2
+            example_conversation
+            routes
+            !routes.md.j2
+        ]
+
+        page_header:
+            '''
+            # QMK Firmware XAP Specs
+
+            This document describes the requirements of the QMK XAP ("extensible application protocol") API.
+            '''
+
+        type_docs:
+            '''
+            ## Types
+
+            **All integral types are little-endian.**
+            '''
+
+        term_definitions:
+            '''
+            ## Definitions
+
+            This list defines the terms used across the entire set of XAP protocol documentation.
+            '''
+
+        request_response:
+            '''
+            ## Requests and Responses
+
+            Communication generally follows a request/response pattern.
+
+            Each request needs to include a _token_ -- this `u16` value prefixes each outbound request from the host application and its corresponding response.
+            This allows response messages to be correlated with their request, even if multiple host applications are communicating with the firmware simultaneously.
+            Host applications should randomly generate a token ID for **every** outbound request, unless using a reserved token defined below.
+            To ensure host interoperability, valid token values are within the range `0x0100`-`0xFFFF`.
+
+            This token is followed by a `u8` signifying the length of data in the request.
+            '''
+
+        // This documentation section reserved for next version
+        reserved_tokens: ''
+
+        response_flags:
+            '''
+            Response messages will always be prefixed by the originating request _token_, directly followed by that request's _response flags_, then the response payload length:
+            '''
+
+        example_conversation:
+            '''
+            ### Example "conversation":
+
+            **Request** -- version query:
+
+            | Byte | 0 | 1 | 2 | 3 | 4 |
+            | --- | --- | --- | --- | --- | --- |
+            | **Purpose** | Token | Token | Payload Length | Route | Route |
+            | **Value** | `0x43` | `0x2B` | `0x02` | `0x00` | `0x00` |
+
+            **Response** -- matching token, successful flag, payload of `0x03170192` = 3.17.192:
+            
+            | Byte | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
+            | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+            | **Purpose** | Token | Token | Response Flags | Payload Length | Payload | Payload | Payload | Payload |
+            | **Value** | `0x43` | `0x2B` | `0x01` | `0x04` | `0x92` | `0x01` | `0x17` | `0x03` |
+            '''
+
+        routes:
+            '''
+            ## Routes
+
+            Subsystem validity should be queried through the “Enabled-in-firmware subsystem query” under the QMK subsystem (route=0x00,0x01).
+            This is the primary method for determining if a subsystem has been enabled in the running firmware.
+            '''
+    }
+
+    type_docs: {
+        u8:
+            '''
+            An unsigned 8-bit integral (octet, or byte), commonly seen as `uint8_t` from _stdint.h_.
+            '''
+        u16:
+            '''
+            An unsigned 16-bit integral, commonly seen as `uint16_t` from _stdint.h_.
+            '''
+        u32:
+            '''
+            An unsigned 32-bit integral, commonly seen as `uint32_t` from _stdint.h_.
+            '''
+        "type[n]":
+            '''
+            An array of `type`, with array extent of `N` -- e.g. `u8[2]` signifies two consecutive octets.
+            '''
+    }
+
+    term_definitions: {
+        Subsystem:
+            '''
+            A high-level area of functionality within XAP.
+            '''
+        Route:
+            '''
+            A sequence of _IDs_ describing the route to invoke a _handler_.
+            '''
+        Handler:
+            '''
+            A piece of code that is executed when a specific _route_ is received.
+            '''
+        Response:
+            '''
+            The data sent back to the host during execution of a _handler_.
+            '''
+        Payload:
+            '''
+            Any received data appended to the _route_, which gets delivered to the _handler_ when received.
+            '''
+    }
+
+    type_definitions: {
+        identifier: {
+            name: ID
+            description: A single octet / 8-bit byte, representing Subsystem or Route index.
+            type: u8
+        }
+
+        response_flags: {
+            name: Response Flags
+            description: An `u8` containing the status of the request.
+            type: u8
+        }
+
+        token: {
+            name: Token
+            description: A `u16` associated with a specific request as well as its corresponding response. Valid token values are within the range `0x0100`-`0xFFFF`.
+            type: u16
+        }
+
+        request_header: {
+            name: Request Header
+            description: Packet format for inbound data.
+            type: struct
+            struct_length: 3
+            struct_members: [
+                {
+                    type: token
+                    name: token
+                },
+                {
+                    type: u8
+                    name: length
+                }
+            ]
+        }
+
+        response_header: {
+            name: Response Header
+            description: Packet format for outbound data.
+            type: struct
+            struct_length: 4
+            struct_members: [
+                {
+                    type: token
+                    name: token
+                },
+                {
+                    type: response_flags
+                    name: flags
+                },
+                {
+                    type: u8
+                    name: length
+                }
+            ]
+        }
+    }
+
+    response_flags: {
+        define_prefix: XAP_RESPONSE_FLAG
+        bits: {
+            0: {
+                name: Success
+                define: SUCCESS
+                description:
+                    '''
+                    When this bit is set, the request was successfully handled. If not set, all payload data should be disregarded, and the request retried if appropriate (with a new token).
+                    '''
+            }
+        }
+    }
+
+    routes: {
+        0x00: {
+            type: router
+            name: XAP
+            define: XAP
+            description:
+                '''
+                This subsystem is always present, and provides the ability to query information about the XAP protocol of the connected device.
+                '''
+            routes: {
+                0x00: {
+                    type: command
+                    name: Version Query
+                    define: VERSION_QUERY
+                    description:
+                        '''
+                        XAP protocol version query.
+
+                        * Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`
+                            * e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.
+                        '''
+                    return_type: u32
+                    return_purpose: bcd-version
+                    return_constant: XAP_BCD_VERSION
+                }
+            }
+        }
+    }
+}

data/xap/xap_0.1.0.hjson

@@ -0,0 +1,367 @@
+{
+    version: 0.1.0
+
+    uses: {
+        keycodes: 0.0.1
+    }
+
+    documentation: {
+        order: [
+            broadcast_messages
+            !broadcast_messages.md.j2
+        ]
+
+        reserved_tokens:
+            '''
+            Two token values are reserved: `0xFFFE` and `0xFFFF`:
+            * `0xFFFE`: A message sent by a host application may use this token if no response is to be sent -- a "fire and forget" message.
+            * `0xFFFF`: Signifies a "broadcast" message sent by the firmware without prompting from the host application. Broadcast messages are defined later in this document.
+
+            Any request will generate at least one corresponding response, with the exception of messages using reserved tokens. Maximum total message length is 128 bytes due to RAM constraints.
+            '''
+
+        broadcast_messages:
+            '''
+            ## Broadcast messages
+
+            Broadcast messages may be sent by the firmware to the host, without a corresponding inbound request. Each broadcast message uses the token `0xFFFF`, and does not expect a response from the host. Tokens are followed by an _ID_ signifying the type of broadcast, with corresponding _payload_.
+            '''
+    }
+
+    response_flags: {
+        bits: {
+            1: {
+                name: Secure Failure
+                define: SECURE_FAILURE
+                description:
+                    '''
+                    When this bit is set, the requested _route_ was marked _secure_ but an _unlock sequence_ has not completed.
+                    '''
+            }
+        }
+    }
+
+    type_docs: {
+        u64:
+            '''
+            An unsigned 64-bit integral, commonly seen as `uint64_t` from _stdint.h_.
+            '''
+        "struct{}":
+            '''
+            A structure of data, packing different objects together. Data is "compacted" -- there are no padding bytes between fields. Equivalent to a packed C-style `struct`. The order in which they're defined matches the order of the data in the response packet.
+            '''
+    }
+
+    term_definitions: {
+        Capability:
+            '''
+            A way to determine if certain functionality is enabled in the firmware. Any _subsystem_ that provides build-time restriction of functionality must provide a _route_ for a _capabilities query_.
+            '''
+        "Secure Route":
+            '''
+            A _route_ which has potentially destructive consequences, necessitating prior approval by the user before executing.
+            '''
+        "Unlock sequence":
+            '''
+            A physical sequence initiated by the user to enable execution of  _secure routes_.
+            '''
+    }
+
+    type_definitions: {
+        broadcast_header: {
+            name: Broadcast Header
+            description: Packet format for broadcast messages.
+            type: struct
+            struct_length: 4
+            struct_members: [
+                {
+                    type: token
+                    name: token
+                },
+                {
+                    type: u8
+                    name: type
+                },
+                {
+                    type: u8
+                    name: length
+                }
+            ]
+        }
+    }
+
+    broadcast_messages: {
+        define_prefix: XAP_BROADCAST
+        messages: {
+            0x00: {
+                name: Log message
+                define: LOG_MESSAGE
+                description:
+                    '''
+                    Replicates and replaces the same functionality as if using the standard QMK `CONSOLE_ENABLE = yes` in `rules.mk`. Normal prints within the firmware will manifest as log messages broadcast to the host. `hid_listen` will not be functional with XAP enabled.
+
+                    Log message payloads include a `u8` signifying the length of the text, followed by the `u8[Length]` containing the text itself.
+
+                    **Example Log Broadcast** -- log message "Hello QMK!"
+
+                    | Byte | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
+                    | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+                    | **Purpose** | Token | Token | Broadcast Type | Length | Payload | Payload | Payload | Payload | Payload | Payload | Payload | Payload | Payload | Payload |
+                    | **Value** | `0xFF` | `0xFF` | `0x00` | `0x0A`(10) | `0x48`(H) | `0x65`(e) | `0x6C`(l) | `0x6C`(l) | `0x6F`(o) | `0x20`( ) | `0x51`(Q) | `0x4D`(M) | `0x4B`(K) | `0x21`(!) |
+                    '''
+            }
+            0x01: {
+                name: Secure Status
+                define: SECURE_STATUS
+                description:
+                    '''
+                    Secure status has changed. Payloads include a `u8` matching a 'Secure Status' request.
+
+                    **Example Secure Status Broadcast** -- secure "Unlocking"
+
+                    | Byte | 0 | 1 | 2 | 3 |
+                    | --- | --- | --- | --- | --- |
+                    | **Purpose** | Token | Token | Broadcast Type | Secure Status |
+                    | **Value** | `0xFF` | `0xFF` | `0x01` | `0x01` |
+                    '''
+                return_type: u8
+            }
+            0x02: {
+                name: Keyboard
+                define: KB
+                description:
+                    '''
+                    Reserved for vendor-specific functionality. No messages are defined by XAP.
+                    '''
+            },
+
+            0x03: {
+                name: User
+                define: USER
+                description:
+                    '''
+                    Reserved for user-specific functionality. No messages are defined by XAP.
+                    '''
+            }
+        }
+    }
+
+    routes: {
+        0x00: {
+            routes: {
+                0x01: {
+                    type: command
+                    name: Capabilities Query
+                    define: CAPABILITIES_QUERY
+                    description:
+                        '''
+                        XAP subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.
+                        '''
+                    return_type: u32
+                    return_purpose: capabilities
+                    return_constant: XAP_ROUTE_XAP_CAPABILITIES
+                }
+                0x02: {
+                    type: command
+                    name: Enabled subsystem query
+                    define: SUBSYSTEM_QUERY
+                    description:
+                        '''
+                        XAP protocol subsystem query. Each bit should be considered as a "usable" subsystem. For example, checking `(value & (1 << XAP_ROUTE_QMK) != 0)` means the QMK subsystem is enabled and available for querying.
+                        '''
+                    return_type: u32
+                    return_purpose: capabilities
+                    return_constant: XAP_ROUTE_CAPABILITIES
+                }
+                0x03: {
+                    type: command
+                    name: Secure Status
+                    define: SECURE_STATUS
+                    description:
+                        '''
+                        Query secure route status
+
+                        * 0 means secure routes are disabled
+                        * 1 means unlock sequence initiated but incomplete
+                        * 2 means secure routes are allowed
+                        * any other value should be interpreted as disabled
+                        '''
+                    return_type: u8
+                    return_execute: secure_status
+                }
+                0x04: {
+                    type: command
+                    name: Secure Unlock
+                    define: SECURE_UNLOCK
+                    description: Initiate secure route unlock sequence
+                    return_execute: secure_unlock
+                }
+                0x05: {
+                    type: command
+                    name: Secure Lock
+                    define: SECURE_LOCK
+                    description: Disable secure routes
+                    return_execute: secure_lock
+                }
+            }
+        },
+
+        0x01: {
+            type: router
+            name: QMK
+            define: QMK
+            description:
+                '''
+                This subsystem is always present, and provides the ability to address QMK-specific functionality.
+                '''
+            routes: {
+                0x00: {
+                    type: command
+                    name: Version Query
+                    define: VERSION_QUERY
+                    description:
+                        '''
+                        QMK protocol version query.
+
+                        * Returns the BCD-encoded version in the format of XX.YY.ZZZZ => `0xXXYYZZZZ`
+                            * e.g. 3.2.115 will match `0x03020115`, or bytes {0x15,0x01,0x02,0x03}.
+                        '''
+                    return_type: u32
+                    return_purpose: bcd-version
+                    return_constant: QMK_BCD_VERSION
+                }
+                0x01: {
+                    type: command
+                    name: Capabilities Query
+                    define: CAPABILITIES_QUERY
+                    description:
+                        '''
+                        QMK subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.
+                        '''
+                    return_type: u32
+                    return_purpose: capabilities
+                    return_constant: XAP_ROUTE_QMK_CAPABILITIES
+                }
+                0x02: {
+                    type: command
+                    name: Board identifiers
+                    define: BOARD_IDENTIFIERS
+                    description:
+                        '''
+                        Retrieves the set of identifying information for the board.
+                        '''
+                    return_type: struct
+                    return_struct_length: 10
+                    return_struct_members: [
+                        {
+                            type: u16
+                            name: Vendor ID
+                        },
+                        {
+                            type: u16
+                            name: Product ID
+                        },
+                        {
+                            type: u16
+                            name: Product Version
+                        },
+                        {
+                            type: u32
+                            name: QMK Unique Identifier
+                        }
+                    ]
+                    return_constant: [
+                        VENDOR_ID
+                        PRODUCT_ID
+                        DEVICE_VER
+                        XAP_KEYBOARD_IDENTIFIER
+                    ]
+                }
+                0x03: {
+                    type: command
+                    name: Board Manufacturer
+                    define: BOARD_MANUFACTURER
+                    description: Retrieves the name of the manufacturer
+                    return_type: string
+                    return_constant: QSTR(MANUFACTURER)
+                }
+                0x04: {
+                    type: command
+                    name: Product Name
+                    define: PRODUCT_NAME
+                    description: Retrieves the product name
+                    return_type: string
+                    return_constant: QSTR(PRODUCT)
+                }
+                0x05: {
+                    type: command
+                    name: Config Blob Length
+                    define: CONFIG_BLOB_LEN
+                    description: Retrieves the length of the configuration data bundled within the firmware
+                    return_type: u16
+                    return_constant: CONFIG_BLOB_GZ_LEN
+                }
+                0x06: {
+                    type: command
+                    name: Config Blob Chunk
+                    define: CONFIG_BLOB_CHUNK
+                    description: Retrieves a chunk of the configuration data bundled within the firmware
+                    request_type: u16
+                    request_purpose: offset
+                    return_type: u8[32]
+                    return_execute: get_config_blob_chunk
+                }
+                0x07: {
+                    type: command
+                    name: Jump to bootloader
+                    define: BOOTLOADER_JUMP
+                    permissions: secure
+                    enable_if_preprocessor: defined(BOOTLOADER_JUMP_SUPPORTED)
+                    description:
+                        '''
+                        Jump to bootloader
+
+                        May not be present – if QMK capabilities query returns “true”, then jump to bootloader is supported
+
+                        * 0 means secure routes are disabled, and should be considered as a failure
+                        * 1 means successful, board will jump to bootloader
+                        '''
+                    return_type: u8
+                    return_execute: request_bootloader_jump
+                }
+                0x08: {
+                    type: command
+                    name: Hardware Identifier
+                    define: HARDWARE_ID
+                    description: Retrieves a unique identifier for the board.
+                    return_type: u32[4]
+                    return_execute: get_hardware_id
+                }
+            }
+        },
+
+        0x02: {
+            type: router
+            name: Keyboard
+            define: KB
+            description:
+                '''
+                This subsystem is always present, and reserved for vendor-specific functionality. No routes are defined by XAP.
+                '''
+            routes: {
+            }
+        },
+
+        0x03: {
+            type: router
+            name: User
+            define: USER
+            description:
+                '''
+                This subsystem is always present, and reserved for user-specific functionality. No routes are defined by XAP.
+                '''
+            routes: {
+            }
+        }
+    }
+}

data/xap/xap_0.2.0.hjson

@@ -0,0 +1,201 @@
+{
+    version: 0.2.0
+
+    routes: {
+        0x04: {
+            type: router
+            name: Keymap
+            define: KEYMAP
+            description:
+                '''
+                This subsystem allows for query of currently configured keycodes.
+                '''
+            routes: {
+                0x01: {
+                    type: command
+                    name: Capabilities Query
+                    define: CAPABILITIES_QUERY
+                    description:
+                        '''
+                        Keymap subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.
+                        '''
+                    return_type: u32
+                    return_purpose: capabilities
+                    return_constant: XAP_ROUTE_KEYMAP_CAPABILITIES
+                }
+                0x02: {
+                    type: command
+                    name: Get Layer Count
+                    define: GET_LAYER_COUNT
+                    description: Query maximum number of layers that can be addressed within the keymap.
+                    return_type: u8
+                    return_execute: keymap_get_layer_count
+                }
+                0x03: {
+                    type: command
+                    name: Get Keycode
+                    define: GET_KEYMAP_KEYCODE
+                    description: Query the Keycode at the requested location.
+                    request_type: struct
+                    request_struct_length: 3
+                    request_struct_members: [
+                        {
+                            type: u8
+                            name: Layer
+                        },
+                        {
+                            type: u8
+                            name: Row
+                        },
+                        {
+                            type: u8
+                            name: Column
+                        }
+                    ]
+                    return_type: u16
+                    return_execute: get_keymap_keycode
+                }
+                0x04: {
+                    type: command
+                    name: Get Encoder Keycode
+                    define: GET_ENCODER_KEYCODE
+                    description: Query the Keycode at the requested location.
+                    enable_if_preprocessor: defined(ENCODER_MAP_ENABLE)
+                    request_type: struct
+                    request_struct_length: 3
+                    request_struct_members: [
+                        {
+                            type: u8
+                            name: Layer
+                        },
+                        {
+                            type: u8
+                            name: Encoder
+                        },
+                        {
+                            type: u8
+                            name: Clockwise
+                        }
+                    ]
+                    return_type: u16
+                    return_execute: get_encoder_keycode
+                }
+            }
+        }
+
+        0x05: {
+            type: router
+            name: Remapping
+            define: REMAPPING
+            description:
+                '''
+                This subsystem allows for live reassignment of keycodes without rebuilding the firmware.
+                '''
+            enable_if_preprocessor: defined(DYNAMIC_KEYMAP_ENABLE)
+            routes: {
+                0x01: {
+                    type: command
+                    name: Capabilities Query
+                    define: CAPABILITIES_QUERY
+                    description:
+                        '''
+                        Remapping subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.
+                        '''
+                    return_type: u32
+                    return_purpose: capabilities
+                    return_constant: XAP_ROUTE_REMAPPING_CAPABILITIES
+                }
+                0x02: {
+                    type: command
+                    name: Get Layer Count
+                    define: GET_DYNAMIC_LAYER_COUNT
+                    description: Query maximum number of layers that can be addressed within the keymap.
+                    return_type: u8
+                    return_constant: DYNAMIC_KEYMAP_LAYER_COUNT
+                }
+                0x03: {
+                    type: command
+                    name: Set Keycode
+                    define: SET_KEYMAP_KEYCODE
+                    description: Modify the Keycode at the requested location.
+                    permissions: secure
+                    request_type: struct
+                    request_struct_length: 5
+                    request_struct_members: [
+                        {
+                            type: u8
+                            name: Layer
+                        },
+                        {
+                            type: u8
+                            name: Row
+                        },
+                        {
+                            type: u8
+                            name: Column
+                        },
+                        {
+                            type: u16
+                            name: Keycode
+                        }
+                    ]
+                    return_execute: dynamic_keymap_set_keycode
+                }
+                0x04: {
+                    type: command
+                    name: Set Encoder Keycode
+                    define: SET_ENCODER_KEYCODE
+                    permissions: secure
+                    description: Modify the Keycode at the requested location.
+                    enable_if_preprocessor: defined(ENCODER_MAP_ENABLE)
+                    request_type: struct
+                    request_struct_length: 5
+                    request_struct_members: [
+                        {
+                            type: u8
+                            name: Layer
+                        },
+                        {
+                            type: u8
+                            name: Encoder
+                        },
+                        {
+                            type: u8
+                            name: Clockwise
+                        },
+                        {
+                            type: u16
+                            name: Keycode
+                        }
+                    ]
+                    return_execute: dynamic_encoder_set_keycode
+                }
+            }
+        }
+
+        0x06: {
+            type: router
+            name: Lighting
+            define: LIGHTING
+            description:
+                '''
+                This subsystem allows for control over the lighting subsystem.
+                '''
+            enable_if_preprocessor: defined(RGBLIGHT_ENABLE) || defined(RGB_MATRIX_ENABLE)
+            routes: {
+                0x01: {
+                    type: command
+                    name: Capabilities Query
+                    define: CAPABILITIES_QUERY
+                    description:
+                        '''
+                        Lighting subsystem capabilities query. Each bit should be considered as a "usable" route within this subsystem.
+                        '''
+                    return_type: u32
+                    return_purpose: capabilities
+                    return_constant: XAP_ROUTE_LIGHTING_CAPABILITIES
+                }
+            }
+        }
+    }
+}

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

@@ -75,6 +75,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,18 +84,21 @@
     * [One Shot Keys](one_shot_keys.md)
     * [Pointing Device](feature_pointing_device.md)
     * [Raw HID](feature_rawhid.md)
+    * [Secure](feature_secure.md)
+    * [Send String](feature_send_string.md)
     * [Sequencer](feature_sequencer.md)
     * [Swap Hands](feature_swap_hands.md)
     * [Tap Dance](feature_tap_dance.md)
     * [Tap-Hold Configuration](tap_hold.md)
-    * [Terminal](feature_terminal.md)
     * [Unicode](feature_unicode.md)
     * [Userspace](feature_userspace.md)
     * [WPM Calculation](feature_wpm.md)
+    * [XAP](xap.md)
 
   * Hardware Features
     * Displays
-      * [HD44780 LCD Controller](feature_hd44780.md)
+      * [Quantum Painter](quantum_painter.md)
+      * [HD44780 LCD Driver](feature_hd44780.md)
       * [ST7565 LCD Driver](feature_st7565.md)
       * [OLED Driver](feature_oled_driver.md)
     * Lighting
@@ -105,6 +109,7 @@
     * [Audio](feature_audio.md)
     * [Bluetooth](feature_bluetooth.md)
     * [Bootmagic Lite](feature_bootmagic.md)
+    * [Converters](feature_converters.md)
     * [Custom Matrix](custom_matrix.md)
     * [Digitizer](feature_digitizer.md)
     * [DIP Switch](feature_dip_switch.md)
@@ -113,7 +118,6 @@
     * [Joystick](feature_joystick.md)
     * [LED Indicators](feature_led_indicators.md)
     * [MIDI](feature_midi.md)
-    * [Proton C Conversion](proton_c_conversion.md)
     * [PS/2 Mouse](feature_ps2_mouse.md)
     * [Split Keyboard](feature_split_keyboard.md)
     * [Stenography](feature_stenography.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
@@ -145,9 +149,10 @@
       * [SPI Driver](spi_driver.md)
       * [WS2812 Driver](ws2812_driver.md)
       * [EEPROM Driver](eeprom_driver.md)
+      * [Flash Driver](flash_driver.md)
       * ['serial' Driver](serial_driver.md)
       * [UART Driver](uart_driver.md)
-    * [GPIO Controls](internals_gpio_control.md)
+    * [GPIO Controls](gpio_control.md)
     * [Keyboard Guidelines](hardware_keyboard_guidelines.md)
 
   * Python Development
@@ -163,6 +168,8 @@
     * Arm/ChibiOS
       * [Selecting an MCU](platformdev_selecting_arm_mcu.md)
       * [Early initialization](platformdev_chibios_earlyinit.md)
+      * [Raspberry Pi RP2040](platformdev_rp2040.md)
+      * [Proton C](platformdev_proton_c.md)
 
   * QMK Reference
     * [Contributing to QMK](contributing.md)
@@ -183,10 +190,10 @@
     * [Understanding QMK](understanding_qmk.md)
 
   * QMK Internals (In Progress)
-    * [Defines](internals_defines.md)
-    * [Input Callback Reg](internals_input_callback_reg.md)
-    * [Midi Device](internals_midi_device.md)
-    * [Midi Device Setup Process](internals_midi_device_setup_process.md)
-    * [Midi Util](internals_midi_util.md)
-    * [Send Functions](internals_send_functions.md)
-    * [Sysex Tools](internals_sysex_tools.md)
+    * [Defines](internals/defines.md)
+    * [Input Callback Reg](internals/input_callback_reg.md)
+    * [Midi Device](internals/midi_device.md)
+    * [Midi Device Setup Process](internals/midi_device_setup_process.md)
+    * [Midi Util](internals/midi_util.md)
+    * [Send Functions](internals/send_functions.md)
+    * [Sysex Tools](internals/sysex_tools.md)

docs/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,17 @@ The breaking change period is when we will merge PR's that change QMK in dangero
 
 ## When is the next Breaking Change?
 
-The next Breaking Change is scheduled for 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.
+* [x] 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 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,32 +43,15 @@ 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
@@ -75,7 +59,7 @@ This happens immediately after the previous `develop` branch is merged.
     * [ ] GitHub PR
     * [ ] https://reddit.com/r/olkb
 
-## 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
@@ -83,21 +67,21 @@ This happens immediately after the previous `develop` branch is merged.
     * [ ] GitHub PR
     * [ ] https://reddit.com/r/olkb
 
-## 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
 
-## 2 Days Before Merge
+### 2 Days Before Merge
 
 * Announce that master is closed for 2 days
     * [ ] Discord
     * [ ] GitHub PR
     * [ ] https://reddit.com/r/olkb
 
-## Day Of Merge
+### Day Of Merge
 
 * `qmk_firmware` git commands
     * [ ] `git checkout develop`
@@ -114,8 +98,39 @@ This happens immediately after the previous `develop` branch is merged.
     * [ ] `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)

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

@@ -335,6 +335,90 @@ This command cleans up the `.build` folder. If `--all` is passed, any .hex or .b
 qmk clean [-a]
 ```
 
+## `qmk via2json`
+
+This command an generate a keymap.json from a VIA keymap backup. Both the layers and the macros are converted, enabling users to easily move away from a VIA-enabled firmware without writing any code or reimplementing their keymaps in QMK Configurator.
+
+**Usage**:
+
+```
+qmk via2json -kb KEYBOARD [-l LAYOUT] [-km KEYMAP] [-o OUTPUT] filename
+```
+
+**Example:**
+
+```
+$ qmk via2json -kb ai03/polaris -o polaris_keymap.json polaris_via_backup.json
+Ψ Wrote keymap to /home/you/qmk_firmware/polaris_keymap.json
+```
+
+## `qmk import-keyboard`
+
+This command imports a data-driven `info.json` keyboard into the repo.
+
+**Usage**:
+
+```
+usage: qmk import-keyboard [-h] filename
+```
+
+**Example:**
+
+```
+$ qmk import-keyboard ~/Downloads/forever60.json
+Ψ Importing forever60.json.
+
+Ψ Imported a new keyboard named forever60.
+Ψ To start working on things, `cd` into keyboards/forever60,
+Ψ or open the directory in your preferred text editor.
+Ψ And build with qmk compile -kb forever60 -km default.
+```
+
+## `qmk import-keymap`
+
+This command imports a data-driven `keymap.json` keymap into the repo.
+
+**Usage**:
+
+```
+usage: qmk import-keymap [-h] filename
+```
+
+**Example:**
+
+```
+qmk import-keymap ~/Downloads/asdf2.json
+Ψ Importing asdf2.json.
+
+Ψ Imported a new keymap named asdf2.
+Ψ To start working on things, `cd` into keyboards/takashicompany/dogtag/keymaps/asdf2,
+Ψ or open the directory in your preferred text editor.
+Ψ And build with qmk compile -kb takashicompany/dogtag -km asdf2.
+```
+
+## `qmk import-kbfirmware`
+
+This command creates a new keyboard based on a [Keyboard Firmware Builder](https://kbfirmware.com/) export.
+
+**Usage**:
+
+```
+usage: qmk import-kbfirmware [-h] filename
+```
+
+**Example:**
+
+```
+$ qmk import-kbfirmware ~/Downloads/gh62.json
+Ψ Importing gh62.json.
+
+⚠ Support here is basic - Consider using 'qmk new-keyboard' instead
+Ψ Imported a new keyboard named gh62.
+Ψ To start working on things, `cd` into keyboards/gh62,
+Ψ or open the directory in your preferred text editor.
+Ψ And build with qmk compile -kb gh62 -km default.
+```
+
 ---
 
 # Developer Commands
@@ -498,3 +582,16 @@ 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)
 
@@ -59,9 +62,17 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s
  * [MK20DX128](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k2x-usb/kinetis-k20-50-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-based-on-arm-cortex-m4-core:K20_50)
  * [MK20DX256](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k2x-usb/kinetis-k20-72-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-mcus-based-on-arm-cortex-m4-core:K20_72)
    * PJRC Teensy 3.2
+ * [MK64FX512](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k6x-ethernet/kinetis-k64-120-mhz-256-kb-sram-microcontrollers-mcus-based-on-arm-cortex-m4-core:K64_120)
+   * PJRC Teensy 3.5
  * [MK66FX1M0](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k6x-ethernet/kinetis-k66-180-mhz-dual-high-speed-full-speed-usbs-2mb-flash-microcontrollers-mcus-based-on-arm-cortex-m4-core:K66_180)
    * PJRC Teensy 3.6
 
+### Raspberry Pi
+
+* [RP2040](https://www.raspberrypi.com/documentation/microcontrollers/rp2040.html)
+
+For a detailed overview about the RP2040 support by QMK see the [dedicated RP2040 page](platformdev_rp2040.md).
+
 ## Atmel ATSAM
 
 There is limited support for one of Atmel's ATSAM microcontrollers, that being the [ATSAMD51J18A](https://www.microchip.com/wwwproducts/en/ATSAMD51J18A) used by the [Massdrop keyboards](https://github.com/qmk/qmk_firmware/tree/master/keyboards/massdrop). However, it is not recommended to design a board with this microcontroller as the support is quite specialized to Massdrop hardware.

docs/config_options.md

@@ -107,8 +107,10 @@ This is a C header file that is one of the first things included, and will persi
   * sets the maximum power (in mA) over USB for the device (default: 500)
 * `#define USB_POLLING_INTERVAL_MS 10`
   * sets the USB polling rate in milliseconds for the keyboard, mouse, and shared (NKRO/media keys) interfaces
-* `#define USB_SUSPEND_WAKEUP_DELAY 200`
-  * set the number of milliseconde to pause after sending a wakeup packet
+* `#define USB_SUSPEND_WAKEUP_DELAY 0`
+  * sets the number of milliseconds to pause after sending a wakeup packet.
+    Disabled by default, you might want to set this to 200 (or higher) if the
+    keyboard does not wake up properly after suspending.
 * `#define F_SCL 100000L`
   * sets the I2C clock rate speed for keyboards using I2C. The default is `400000L`, except for keyboards using `split_common`, where the default is `100000L`.
 
@@ -131,6 +133,8 @@ If you define these options you will disable the associated feature, which can s
 
 If you define these options you will enable the associated feature, which may increase your code size.
 
+* `#define ENABLE_COMPILE_KEYCODE`
+  * Enables the `QK_MAKE` keycode
 * `#define FORCE_NKRO`
   * NKRO by default requires to be turned on, this forces it on during keyboard startup regardless of EEPROM setting. NKRO can still be turned off but will be turned on again if the keyboard reboots.
 * `#define STRICT_LAYER_RELEASE`
@@ -139,7 +143,7 @@ If you define these options you will enable the associated feature, which may in
 ## Behaviors That Can Be Configured
 
 * `#define TAPPING_TERM 200`
-  * how long before a tap becomes a hold, if set above 500, a key tapped during the tapping term will turn it into a hold too
+  * how long before a key press becomes a hold
 * `#define TAPPING_TERM_PER_KEY`
   * enables handling for per key `TAPPING_TERM` settings
 * `#define RETRO_TAPPING`
@@ -172,6 +176,8 @@ If you define these options you will enable the associated feature, which may in
   * sets the timer for leader key chords to run on each key press rather than overall
 * `#define LEADER_KEY_STRICT_KEY_PROCESSING`
   * Disables keycode filtering for Mod-Tap and Layer-Tap keycodes. Eg, if you enable this, you would need to specify `MT(MOD_CTL, KC_A)` if you want to use `KC_A`.
+* `#define MOUSE_EXTENDED_REPORT`
+  * Enables support for extended reports (-32767 to 32767, instead of -127 to 127), which may allow for smoother reporting, and prevent maxing out of the reports. Applies to both Pointing Device and Mousekeys.
 * `#define ONESHOT_TIMEOUT 300`
   * how long before oneshot times out
 * `#define ONESHOT_TAP_TOGGLE 2`

docs/custom_matrix.md

@@ -81,17 +81,17 @@ void matrix_init(void) {
 }
 
 uint8_t matrix_scan(void) {
-    bool matrix_has_changed = false;
+    bool changed = false;
 
     // TODO: add matrix scanning routine here
 
     // Unless hardware debouncing - use the configured debounce routine
-    debounce(raw_matrix, matrix, MATRIX_ROWS, changed);
+    changed = debounce(raw_matrix, matrix, MATRIX_ROWS, changed);
 
     // This *must* be called for correct keyboard behavior
     matrix_scan_quantum();
 
-    return matrix_has_changed;
+    return changed;
 }
 ```
 

docs/data_driven_config.md

@@ -44,7 +44,7 @@ In other cases you should group like options together in an `object`. This is pa
 In most cases you can add a simple mapping. These are maintained as JSON files in `data/mappings/info_config.json` and `data/mappings/info_rules.json`, and control mapping for `config.h` and `rules.mk`, respectively. Each mapping is keyed by the `config.h` or `rules.mk` variable, and the value is a hash with the following keys:
 
 * `info_key`: (required) The location within `info.json` for this value. See below.
-* `value_type`: (optional) Default `str`. The format for this variable's value. See below.
+* `value_type`: (optional) Default `raw`. The format for this variable's value. See below.
 * `to_json`: (optional) Default `true`. Set to `false` to exclude this mapping from info.json
 * `to_c`: (optional) Default `true`. Set to `false` to exclude this mapping from config.h
 * `warn_duplicate`: (optional) Default `true`. Set to `false` to turn off warning when a value exists in both places
@@ -57,7 +57,7 @@ Under the hood we use [Dotty Dict](https://dotty-dict.readthedocs.io/en/latest/)
 
 #### Value Types
 
-By default we treat all values as simple strings. If your value is more complex you can use one of these types to intelligently parse the data:
+By default we treat all values as unquoted "raw" data. If your value is more complex you can use one of these types to intelligently parse the data:
 
 * `array`: A comma separated array of strings
 * `array.int`: A comma separated array of integers
@@ -65,6 +65,7 @@ By default we treat all values as simple strings. If your value is more complex
 * `hex`: A number formatted as hex
 * `list`: A space separate array of strings
 * `mapping`: A hash of key/value pairs
+* `str`: A quoted string literal
 
 ### Add code to extract it
 

docs/eeprom_driver.md

@@ -2,12 +2,15 @@
 
 The EEPROM driver can be swapped out depending on the needs of the keyboard, or whether extra hardware is present.
 
+Selecting the EEPROM driver is done in your keyboard's `rules.mk`:
+
 Driver                             | Description
 -----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 `EEPROM_DRIVER = vendor` (default) | Uses the on-chip driver provided by the chip manufacturer. For AVR, this is provided by avr-libc. This is supported on ARM for a subset of chips -- STM32F3xx, STM32F1xx, and STM32F072xB will be emulated by writing to flash. STM32L0xx and STM32L1xx will use the onboard dedicated true EEPROM. Other chips will generally act as "transient" below.
 `EEPROM_DRIVER = i2c`              | Supports writing to I2C-based 24xx EEPROM chips. See the driver section below.
 `EEPROM_DRIVER = spi`              | Supports writing to SPI-based 25xx EEPROM chips. See the driver section below.
 `EEPROM_DRIVER = transient`        | Fake EEPROM driver -- supports reading/writing to RAM, and will be discarded when power is lost.
+`EEPROM_DRIVER = wear_leveling`    | Frontend driver for the wear_leveling system, allowing for EEPROM emulation on top of flash -- both in-MCU and external SPI NOR flash.
 
 ## Vendor Driver Configuration :id=vendor-eeprom-driver-configuration
 
@@ -43,8 +46,9 @@ Module           | Equivalent `#define`            | Source
 -----------------|---------------------------------|------------------------------------------
 CAT24C512 EEPROM | `#define EEPROM_I2C_CAT24C512`  | <https://www.sparkfun.com/products/14764>
 RM24C512C EEPROM | `#define EEPROM_I2C_RM24C512C`  | <https://www.sparkfun.com/products/14764>
-24LC64 EEPROM    | `#define EEPROM_I2C_24LC64`     | <https://www.microchip.com/wwwproducts/en/24LC64>
-24LC128 EEPROM   | `#define EEPROM_I2C_24LC128`    | <https://www.microchip.com/wwwproducts/en/24LC128>
+24LC32A EEPROM   | `#define EEPROM_I2C_24LC32A`    | <https://www.microchip.com/en-us/product/24LC32A>
+24LC64 EEPROM    | `#define EEPROM_I2C_24LC64`     | <https://www.microchip.com/en-us/product/24LC64>
+24LC128 EEPROM   | `#define EEPROM_I2C_24LC128`    | <https://www.microchip.com/en-us/product/24LC128>
 24LC256 EEPROM   | `#define EEPROM_I2C_24LC256`    | <https://www.sparkfun.com/products/525>
 MB85RC256V FRAM  | `#define EEPROM_I2C_MB85RC256V` | <https://www.adafruit.com/product/1895>
 
@@ -54,13 +58,13 @@ MB85RC256V FRAM  | `#define EEPROM_I2C_MB85RC256V` | <https://www.adafruit.com/p
 
 Currently QMK supports 25xx-series chips over SPI. As such, requires a working spi_master driver configuration. You can override the driver configuration via your config.h:
 
-`config.h` override                            | Description                                                                          | Default Value
------------------------------------------------|--------------------------------------------------------------------------------------|--------------
-`#define EXTERNAL_EEPROM_SPI_SLAVE_SELECT_PIN` | SPI Slave select pin in order to inform that the EEPROM is currently being addressed | _none_
-`#define EXTERNAL_EEPROM_SPI_CLOCK_DIVISOR`    | Clock divisor used to divide the peripheral clock to derive the SPI frequency        | `64`
-`#define EXTERNAL_EEPROM_BYTE_COUNT`           | Total size of the EEPROM in bytes                                                    | 8192
-`#define EXTERNAL_EEPROM_PAGE_SIZE`            | Page size of the EEPROM in bytes, as specified in the datasheet                      | 32
-`#define EXTERNAL_EEPROM_ADDRESS_SIZE`         | The number of bytes to transmit for the memory location within the EEPROM            | 2
+`config.h` override                            | Default Value | Description
+-----------------------------------------------|---------------|-------------------------------------------------------------------------------------
+`#define EXTERNAL_EEPROM_SPI_SLAVE_SELECT_PIN` | _none_        | SPI Slave select pin in order to inform that the EEPROM is currently being addressed
+`#define EXTERNAL_EEPROM_SPI_CLOCK_DIVISOR`    | `64`          | Clock divisor used to divide the peripheral clock to derive the SPI frequency
+`#define EXTERNAL_EEPROM_BYTE_COUNT`           | `8192`        | Total size of the EEPROM in bytes
+`#define EXTERNAL_EEPROM_PAGE_SIZE`            | `32`          | Page size of the EEPROM in bytes, as specified in the datasheet
+`#define EXTERNAL_EEPROM_ADDRESS_SIZE`         | `2`           | The number of bytes to transmit for the memory location within the EEPROM
 
 !> There's no way to determine if there is an SPI EEPROM actually responding. Generally, this will result in reads of nothing but zero.
 
@@ -73,3 +77,84 @@ The only configurable item for the transient EEPROM driver is its size:
 `#define TRANSIENT_EEPROM_SIZE` | Total size of the EEPROM storage in bytes | 64
 
 Default values and extended descriptions can be found in `drivers/eeprom/eeprom_transient.h`.
+
+## Wear-leveling Driver Configuration :id=wear_leveling-eeprom-driver-configuration
+
+The wear-leveling driver uses an algorithm to minimise the number of erase cycles on the underlying MCU flash memory.
+
+There is no specific configuration for this driver, but the wear-leveling system used by this driver may need configuration. See the [wear-leveling configuration](#wear_leveling-configuration) section for more information.
+
+# Wear-leveling Configuration :id=wear_leveling-configuration
+
+The wear-leveling driver has a few possible _backing stores_ that may be used by adding to your keyboard's `rules.mk` file:
+
+Driver                                  | Description
+----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+`WEAR_LEVELING_DRIVER = embedded_flash` | This driver is used for emulating EEPROM by writing to embedded flash on the MCU.
+`WEAR_LEVELING_DRIVER = spi_flash`      | This driver is used to address external SPI NOR Flash peripherals.
+`WEAR_LEVELING_DRIVER = rp2040_flash`   | This driver is used to write to the same storage the RP2040 executes code from.
+`WEAR_LEVELING_DRIVER = legacy`         | This driver is the "legacy" emulated EEPROM provided in historical revisions of QMK. Currently used for STM32F0xx and STM32F4x1, but slated for deprecation and removal once `embedded_flash` support for those MCU families is complete.
+
+!> All wear-leveling drivers require an amount of RAM equivalent to the selected logical EEPROM size. Increasing the size to 32kB of EEPROM requires 32kB of RAM, which a significant number of MCUs simply do not have.
+
+## Wear-leveling Embedded Flash Driver Configuration :id=wear_leveling-efl-driver-configuration
+
+This driver performs writes to the embedded flash storage embedded in the MCU. In most circumstances, the last few of sectors of flash are used in order to minimise the likelihood of collision with program code.
+
+Configurable options in your keyboard's `config.h`:
+
+`config.h` override                      | Default     | Description
+-----------------------------------------|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+`#define WEAR_LEVELING_EFL_FIRST_SECTOR` | _unset_     | The first sector on the MCU to use. By default this is not defined and calculated at runtime based on the MCU. However, different flash sizes on MCUs may require custom configuration.
+`#define WEAR_LEVELING_EFL_FLASH_SIZE`   | _unset_     | Allows overriding the flash size available for use for wear-leveling. Under normal circumstances this is automatically calculated and should not need to be overridden. Specifying a size larger than the amount actually available in flash will usually prevent the MCU from booting.
+`#define WEAR_LEVELING_LOGICAL_SIZE`     | `1024`      | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM.
+`#define WEAR_LEVELING_BACKING_SIZE`     | `2048`      | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size.
+`#define BACKING_STORE_WRITE_SIZE`       | _automatic_ | The byte width of the underlying write used on the MCU, and is usually automatically determined from the selected MCU family. If an error occurs in the auto-detection, you'll need to consult the MCU's datasheet and determine this value, specifying it directly.
+
+!> If your MCU does not boot after swapping to the EFL wear-leveling driver, it's likely that the flash size is incorrectly detected, usually as an MCU with larger flash and may require overriding.
+
+## Wear-leveling SPI Flash Driver Configuration :id=wear_leveling-flash_spi-driver-configuration
+
+This driver performs writes to an external SPI NOR Flash peripheral. It also requires a working configuration for the SPI NOR Flash peripheral -- see the [flash driver](flash_driver.md) documentation for more information.
+
+Configurable options in your keyboard's `config.h`:
+
+`config.h` override                                 | Default                        | Description
+----------------------------------------------------|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------
+`#define WEAR_LEVELING_EXTERNAL_FLASH_BLOCK_COUNT`  | `1`                            | Number of blocks in the external flash used by the wear-leveling algorithm.
+`#define WEAR_LEVELING_EXTERNAL_FLASH_BLOCK_OFFSET` | `0`                            | The index first block in the external flash used by the wear-leveling algorithm.
+`#define WEAR_LEVELING_LOGICAL_SIZE`                | `((block_count*block_size)/2)` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM. Result must be <= 64kB.
+`#define WEAR_LEVELING_BACKING_SIZE`                | `(block_count*block_size)`     | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size.
+`#define BACKING_STORE_WRITE_SIZE`                  | `8`                            | The write width used whenever a write is performed on the external flash peripheral.
+
+!> There is currently a limit of 64kB for the EEPROM subsystem within QMK, so using a larger flash is not going to be beneficial as the logical size cannot be increased beyond 65536. The backing size may be increased to a larger value, but erase timing may suffer as a result.
+
+## Wear-leveling RP2040 Driver Configuration :id=wear_leveling-rp2040-driver-configuration
+
+This driver performs writes to the same underlying storage that the RP2040 executes its code.
+
+Configurable options in your keyboard's `config.h`:
+
+`config.h` override                       | Default                    | Description
+------------------------------------------|----------------------------|--------------------------------------------------------------------------------------------------------------------------------
+`#define WEAR_LEVELING_RP2040_FLASH_SIZE` | `PICO_FLASH_SIZE_BYTES`    | Number of bytes of flash on the board.
+`#define WEAR_LEVELING_RP2040_FLASH_BASE` | `(flash_size-sector_size)` | The byte-wise location that the backing storage should be located.
+`#define WEAR_LEVELING_LOGICAL_SIZE`      | `4096`                     | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM.
+`#define WEAR_LEVELING_BACKING_SIZE`      | `8192`                     | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size as well as the sector size.
+`#define BACKING_STORE_WRITE_SIZE`        | `2`                        | The write width used whenever a write is performed on the external flash peripheral.
+
+## Wear-leveling Legacy EEPROM Emulation Driver Configuration :id=wear_leveling-legacy-driver-configuration
+
+This driver performs writes to the embedded flash storage embedded in the MCU much like the normal Embedded Flash Driver, and is only for use with STM32F0xx and STM32F4x1 devices. This flash implementation is still currently provided as the EFL driver is currently non-functional for the previously mentioned families.
+
+By default, `1024` bytes of emulated EEPROM is provided:
+
+MCU       | EEPROM Provided | Flash Used
+----------|-----------------|--------------
+STM32F042 | `1024` bytes    | `2048` bytes
+STM32F070 | `1024` bytes    | `2048` bytes
+STM32F072 | `1024` bytes    | `2048` bytes
+STM32F401 | `1024` bytes    | `16384` bytes
+STM32F411 | `1024` bytes    | `16384` bytes
+
+Under normal circumstances configuration of this driver requires intimate knowledge of the MCU's flash structure -- reconfiguration is at your own risk and will require referring to the code.

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)
+* [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_bootmagic.md

@@ -23,14 +23,35 @@ And to trigger the bootloader, you hold this key down when plugging the keyboard
 
 ## Split Keyboards
 
-When handedness is predetermined via an option like `SPLIT_HAND_PIN`, you might need to configure a different key between halves. To do so, add these entries to your `config.h` file:
+When [handedness](feature_split_keyboard.md#setting-handedness) is predetermined via options like `SPLIT_HAND_PIN` or `EE_HANDS`, you might need to configure a different key between halves. To identify the correct key for the right half, examine the split key matrix defined in the `<keyboard>.h` file, e.g.:
+
+```c
+#define LAYOUT_split_3x5_2( \
+        L01, L02, L03, L04, L05,   R01, R02, R03, R04, R05, \
+        L06, L07, L08, L09, L10,   R06, R07, R08, R09, R10, \
+        L11, L12, L13, L14, L15,   R11, R12, R13, R14, R15, \
+                       L16, L17,   R16, R17                 \
+    ) \
+    { \
+        { L01, L02, L03, L04, L05 }, \
+        { L06, L07, L08, L09, L10 }, \
+        { L11, L12, L13, L14, L15 }, \
+        { L16, L17, KC_NO, KC_NO, KC_NO }, \
+        { R01, R02, R03, R04, R05 }, \
+        { R06, R07, R08, R09, R10 }, \
+        { R11, R12, R13, R14, R15 }, \
+        { R16, R17, KC_NO, KC_NO, KC_NO }  \
+    }
+```
+
+If you pick the top right key for the right half, it is `R05` on the top layout. Within the key matrix below, `R05` is located on row 4 columnn 4. To use that key as the right half's Bootmagic Lite trigger, add these entries to your `config.h` file:
 
 ```c
 #define BOOTMAGIC_LITE_ROW_RIGHT 4
-#define BOOTMAGIC_LITE_COLUMN_RIGHT 1
+#define BOOTMAGIC_LITE_COLUMN_RIGHT 4
 ```
 
-By default, these values are not set.
+?> These values are not set by default.
 
 ## Advanced Bootmagic Lite
 
@@ -51,7 +72,7 @@ void bootmagic_lite(void) {
 }
 ```
 
-You can additional feature here. For instance, resetting the EEPROM or requiring additional keys to be pressed to trigger Bootmagic Lite. Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware.
+You can define additional logic here. For instance, resetting the EEPROM or requiring additional keys to be pressed to trigger Bootmagic Lite. Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware.
 
 ## Addenda
 

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_converters.md

@@ -0,0 +1,98 @@
+# Converters
+
+Since many drop-in replacement controllers now exist, we've done our best to make them easy to use in existing designs.
+
+This page documents the handy automated process for converting keyboards.
+
+### Supported Converters
+
+Currently the following converters are available:
+
+| From       | To                |
+|------------|-------------------|
+| `promicro` | `proton_c`        |
+| `promicro` | `kb2040`          |
+| `promicro` | `promicro_rp2040` |
+| `promicro` | `blok`            |
+
+See below for more in depth information on each converter.
+
+## Overview
+
+Each converter category is broken down by its declared `pin compatibility`.
+This ensures that only valid combinations are attempted.
+
+You can generate the firmware by appending `-e CONVERT_TO=<target>` to your compile/flash command. For example:
+
+```sh
+qmk flash -c -kb keebio/bdn9/rev1 -km default -e CONVERT_TO=proton_c
+```
+
+You can also add the same `CONVERT_TO=<target>` to your keymap's `rules.mk`, which will accomplish the same thing.
+
+?> If you get errors about `PORTB/DDRB`, etc not being defined, you'll need to convert the keyboard's code to use the [GPIO Controls](gpio_control.md) that will work for both ARM and AVR. This shouldn't affect the AVR builds at all.
+
+### Conditional Configuration
+
+Once a converter is enabled, it exposes the `CONVERT_TO_<target_uppercase>` flag that you can use in your code with `#ifdef`s, For example:
+
+```c
+#ifdef CONVERT_TO_PROTON_C
+    // Proton C code
+#else
+    // Pro Micro code
+#endif
+```
+
+## Pro Micro
+
+If a board currently supported in QMK uses a [Pro Micro](https://www.sparkfun.com/products/12640) (or compatible board), the supported alternative controllers are:
+
+| Device                                                                 | Target            |
+|------------------------------------------------------------------------|-------------------|
+| [Proton C](https://qmk.fm/proton-c/)                                   | `proton_c`        |
+| [Adafruit KB2040](https://learn.adafruit.com/adafruit-kb2040)          | `kb2040`          |
+| [SparkFun Pro Micro - RP2040](https://www.sparkfun.com/products/18288) | `promicro_rp2040` |
+| [Blok](https://boardsource.xyz/store/628b95b494dfa308a6581622)         | `blok`            |
+
+Converter summary:
+
+| Target            | Argument                        | `rules.mk`                   | Condition                           |
+|-------------------|---------------------------------|------------------------------|-------------------------------------|
+| `proton_c`        | `-e CONVERT_TO=proton_c`        | `CONVERT_TO=proton_c`        | `#ifdef CONVERT_TO_PROTON_C`        |
+| `kb2040`          | `-e CONVERT_TO=kb2040`          | `CONVERT_TO=kb2040`          | `#ifdef CONVERT_TO_KB2040`          |
+| `promicro_rp2040` | `-e CONVERT_TO=promicro_rp2040` | `CONVERT_TO=promicro_rp2040` | `#ifdef CONVERT_TO_PROMICRO_RP2040` |
+| `blok`            | `-e CONVERT_TO=blok`            | `CONVERT_TO=blok`            | `#ifdef CONVERT_TO_BLOK`            |
+
+### Proton C :id=proton_c
+
+The Proton C only has one on-board LED (C13), and by default, the TXLED (D5) is mapped to it. If you want the RXLED (B0) mapped to it instead, add this line to your `config.h`:
+
+```c
+#define CONVERT_TO_PROTON_C_RXLED
+```
+
+The following defaults are based on what has been implemented for STM32 boards.
+
+| Feature                                      | Notes                                                                                                            |
+|----------------------------------------------|------------------------------------------------------------------------------------------------------------------|
+| [Audio](feature_audio.md)                    | Enabled                                                                                                          |
+| [RGB Lighting](feature_rgblight.md)          | Disabled                                                                                                         |
+| [Backlight](feature_backlight.md)            | Forces [task driven PWM](feature_backlight.md#software-pwm-driver) until ARM can provide automatic configuration |
+| USB Host (e.g. USB-USB converter)            | Not supported (USB host code is AVR specific and is not currently supported on ARM)                              |
+| [Split keyboards](feature_split_keyboard.md) | Partial - heavily dependent on enabled features                                                                  |
+
+### Adafruit KB2040 :id=kb2040
+
+The following defaults are based on what has been implemented for [RP2040](platformdev_rp2040.md) boards.
+
+| Feature                                      | Notes                                                                                                            |
+|----------------------------------------------|------------------------------------------------------------------------------------------------------------------|
+| [RGB Lighting](feature_rgblight.md)          | Enabled via `PIO` vendor driver                                                                                  |
+| [Backlight](feature_backlight.md)            | Forces [task driven PWM](feature_backlight.md#software-pwm-driver) until ARM can provide automatic configuration |
+| USB Host (e.g. USB-USB converter)            | Not supported (USB host code is AVR specific and is not currently supported on ARM)                              |
+| [Split keyboards](feature_split_keyboard.md) | Partial via `PIO` vendor driver - heavily dependent on enabled features                                          |
+
+### SparkFun Pro Micro - RP2040 and Blok :id=promicro_rp2040 
+
+Currently identical to  [Adafruit KB2040](#kb2040).

docs/feature_dynamic_macros.md

@@ -35,6 +35,7 @@ There are a number of options added that should allow some additional degree of
 |`DYNAMIC_MACRO_SIZE`        |128             |Sets the amount of memory that Dynamic Macros can use. This is a limited resource, dependent on the controller.  |
 |`DYNAMIC_MACRO_USER_CALL`   |*Not defined*   |Defining this falls back to using the user `keymap.c` file to trigger the macro behavior.                        |
 |`DYNAMIC_MACRO_NO_NESTING`  |*Not Defined*   |Defining this disables the ability to call a macro from another macro (nested macros).                           | 
+|`DYNAMIC_MACRO_DELAY`        |*Not Defined*   |Sets the waiting time (ms unit) when sending each key.                                                           |
 
 
 If the LEDs start blinking during the recording with each keypress, it means there is no more space for the macro in the macro buffer. To fit the macro in, either make the other macro shorter (they share the same buffer) or increase the buffer size by adding the `DYNAMIC_MACRO_SIZE` define in your `config.h` (default value: 128; please read the comments for it in the header).

docs/feature_encoders.md

@@ -54,9 +54,43 @@ If you are using different pinouts for the encoders on each half of a split keyb
 #define ENCODER_RESOLUTIONS_RIGHT { 2, 4 }
 ```
 
+If the `_RIGHT` definitions aren't specified in your `config.h`, then the non-`_RIGHT` versions will be applied to both sides of the split.
+
+Additionally, if one side does not have an encoder, you can specify `{}` for the pins/resolution -- for example, a split keyboard with only a right-side encoder:
+
+```c
+#define ENCODERS_PAD_A { }
+#define ENCODERS_PAD_B { }
+#define ENCODER_RESOLUTIONS { }
+#define ENCODERS_PAD_A_RIGHT { B12 }
+#define ENCODERS_PAD_B_RIGHT { B13 }
+#define ENCODER_RESOLUTIONS_RIGHT { 4 }
+```
+
+## 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`:
+
+```make
+ENCODER_MAP_ENABLE = yes
+```
+
+Your `keymap.c` will then need an encoder mapping defined (for four layers and two encoders):
+
+```c
+#if defined(ENCODER_MAP_ENABLE)
+const uint16_t PROGMEM encoder_map[][NUM_ENCODERS][2] = {
+    [_BASE] =   { ENCODER_CCW_CW(KC_MS_WH_UP, KC_MS_WH_DOWN), ENCODER_CCW_CW(KC_VOLD, KC_VOLU)  },
+    [_LOWER] =  { ENCODER_CCW_CW(RGB_HUD, RGB_HUI),           ENCODER_CCW_CW(RGB_SAD, RGB_SAI)  },
+    [_RAISE] =  { ENCODER_CCW_CW(RGB_VAD, RGB_VAI),           ENCODER_CCW_CW(RGB_SPD, RGB_SPI)  },
+    [_ADJUST] = { ENCODER_CCW_CW(RGB_RMOD, RGB_MOD),          ENCODER_CCW_CW(KC_RIGHT, KC_LEFT) },
+};
+#endif
+```
+
 ## Callbacks
 
-The callback functions can be inserted into your `<keyboard>.c`:
+When not using `ENCODER_MAP_ENABLE = yes`, the callback functions can be inserted into your `<keyboard>.c`:
 
 ```c
 bool encoder_update_kb(uint8_t index, bool clockwise) {

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_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_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    |
+|`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_hd44780.md

@@ -1,57 +1,298 @@
-# HD44780 LCD Displays
+# HD44780 LCD Driver
 
-This is an integration of Peter Fleury's LCD library. This page will explain the basics. [For in depth documentation visit his page.](http://www.peterfleury.epizy.com/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)
+## Supported Hardware
 
-You can enable support for HD44780 Displays by setting the `HD44780_ENABLE` flag in your keyboards `rules.mk` to yes.
+LCD modules using [HD44780U](https://www.sparkfun.com/datasheets/LCD/HD44780.pdf) IC or equivalent, communicating in 4-bit mode.
 
-## Configuration
+|Module|Size          |Notes                            |
+|------|--------------|---------------------------------|
+|1602A |16x2, 5x8 dots|                                 |
+|2004A |20x4, 5x8 dots|Untested, not currently supported|
 
-You will need to configure the pins used by your display, and its number of lines and columns in your keyboard's `config.h`.
-
-
-Uncomment the section labled HD44780 and change the parameters as needed.
-````
-/*
- * HD44780 LCD Display Configuration
- */
-
-#define LCD_LINES           2     //< number of visible lines of the display
-#define LCD_DISP_LENGTH    16     //< visibles characters per line of the display
-#define LCD_IO_MODE      1            //< 0: memory mapped mode, 1: IO port mode
-#if LCD_IO_MODE
-#define LCD_PORT         PORTB        //< port for the LCD lines
-#define LCD_DATA0_PORT   LCD_PORT     //< port for 4bit data bit 0
-#define LCD_DATA1_PORT   LCD_PORT     //< port for 4bit data bit 1
-#define LCD_DATA2_PORT   LCD_PORT     //< port for 4bit data bit 2
-#define LCD_DATA3_PORT   LCD_PORT     //< port for 4bit data bit 3
-#define LCD_DATA0_PIN    4            //< pin for 4bit data bit 0
-#define LCD_DATA1_PIN    5            //< pin for 4bit data bit 1
-#define LCD_DATA2_PIN    6            //< pin for 4bit data bit 2
-#define LCD_DATA3_PIN    7            //< pin for 4bit data bit 3
-#define LCD_RS_PORT      LCD_PORT     //< port for RS line        
-#define LCD_RS_PIN       3            //< pin  for RS line        
-#define LCD_RW_PORT      LCD_PORT     //< port for RW line        
-#define LCD_RW_PIN       2            //< pin  for RW line        
-#define LCD_E_PORT       LCD_PORT     //< port for Enable line     
-#define LCD_E_PIN        1            //< pin  for Enable line    
-#endif
-````
-
-Should you need to configure other properties you can copy them from `quantum/hd44780.h` and set them in your `config.h`
+To run these modules at 3.3V, an additional MAX660 voltage converter IC must be soldered on, along with two 10µF capacitors. See [this page](https://www.codrey.com/electronic-circuits/hack-your-16x2-lcd/) for more details.
 
 ## Usage
 
-To initialize your display, call `lcd_init()` with one of these parameters:
-````
-LCD_DISP_OFF             : display off
-LCD_DISP_ON              : display on, cursor off
-LCD_DISP_ON_CURSOR       : display on, cursor on
-LCD_DISP_ON_CURSOR_BLINK : display on, cursor on flashing
-````
-This is best done in your keyboards `matrix_init_kb` or your keymaps `matrix_init_user`.  
-It is advised to clear the display before use.  
-To do so call `lcd_clrscr()`.
+Add the following to your `rules.mk`:
 
-To now print something to your Display you first call `lcd_gotoxy(column, line)`. To go to the start of the first line you would call `lcd_gotoxy(0, 0)` and then print a string with `lcd_puts("example string")`.
+```make
+HD44780_ENABLE = yes
+```
 
-There are more methods available to control the display. [For in depth documentation please visit the linked page.](http://www.peterfleury.epizy.com/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)
+## Basic Configuration
+
+Add the following to your `config.h`:
+
+|Define                 |Default       |Description                                                                                          |
+|-----------------------|--------------|-----------------------------------------------------------------------------------------------------|
+|`HD44780_DATA_PINS`    |*Not defined* |(Required) An array of four GPIO pins connected to the display's D4-D7 pins, eg. `{ B1, B3, B2, B6 }`|
+|`HD44780_RS_PIN`       |*Not defined* |(Required) The GPIO connected to the display's RS pin                                                |
+|`HD44780_RW_PIN`       |*Not defined* |(Required) The GPIO connected to the display's RW pin                                                |
+|`HD44780_E_PIN`        |*Not defined* |(Required) The GPIO connected to the display's E pin                                                 |
+|`HD44780_DISPLAY_COLS` |`16`          |The number of visible characters on a single line of the display                                     |
+|`HD44780_DISPLAY_LINES`|`2`           |The number of visible lines on the display                                                           |
+|`HD44780_WRAP_LINES`   |*Not defined* |If defined, input characters will wrap to the next line                                              |
+
+## Examples
+
+### Hello World
+
+Add the following to your `keymap.c`:
+
+```c
+void keyboard_post_init_user(void) {
+    hd44780_init(true, true); // Show blinking cursor
+    hd44780_puts_P(PSTR("Hello, world!\n"));
+}
+```
+
+### Custom Character Definition
+
+Up to eight custom characters can be defined. This data is stored in the Character Generator RAM (CGRAM), and is not persistent across power cycles.
+
+This example defines the QMK Psi as the first custom character. The first 16 positions in the character set are reserved for the eight custom characters duplicated.
+
+```
+Byte |      16 8 4 2 1
+   1 | x x x ■ □ ■ □ ■
+   2 | x x x ■ □ ■ □ ■
+   3 | x x x ■ □ ■ □ ■
+   4 | x x x □ ■ ■ ■ □
+   5 | x x x □ □ ■ □ □
+   6 | x x x □ □ ■ □ □
+   7 | x x x □ □ ■ □ □
+   8 | x x x □ □ □ □ □
+```
+
+```c
+const uint8_t PROGMEM psi[8] = { 0x15, 0x15, 0x15, 0x0E, 0x04, 0x04, 0x04, 0x00 };
+
+void keyboard_post_init_user(void) {
+    hd44780_init(false, false);
+    hd44780_define_char_P(0, psi);
+    // Cursor is incremented while defining characters so must be reset
+    hd44780_home();
+    // 0x08 to avoid null terminator
+    hd44780_puts_P(PSTR("\x08 QMK Firmware"));
+}
+```
+
+## API
+
+### `void hd44780_init(bool cursor, bool blink)`
+
+Initialize the display.
+
+This function should be called only once, before any of the other functions can be called.
+
+#### Arguments
+
+ - `bool cursor`  
+   Whether to show the cursor.
+ - `bool blink`  
+   Whether to blink the cursor, if shown.
+
+---
+
+### `void hd44780_clear(void)`
+
+Clear the display.
+
+This function is called on init.
+
+---
+
+### `void hd44780_home(void)`
+
+Move the cursor to the home position.
+
+This function is called on init.
+
+---
+
+### `void hd44780_on(bool cursor, bool blink)`
+
+Turn the display on, and/or set the cursor properties.
+
+This function is called on init.
+
+#### Arguments
+
+ - `bool cursor`  
+   Whether to show the cursor.
+ - `bool blink`  
+   Whether to blink the cursor, if shown.
+
+---
+
+### `void hd44780_off(void)`
+
+Turn the display off.
+
+---
+
+### `void hd44780_set_cursor(uint8_t col, uint8_t line)`
+
+Move the cursor to the specified position on the display.
+
+#### Arguments
+
+ - `uint8_t col`  
+   The column number to move to, from 0 to 15 on 16x2 displays.
+ - `bool line`  
+   The line number to move to, either 0 or 1 on 16x2 displays.
+
+---
+
+### `void hd44780_putc(char c)`
+
+Print a character to the display. The newline character `\n` will move the cursor to the start of the next line.
+
+The exact character shown may depend on the ROM code of your particular display - refer to the datasheet for the full character set.
+
+#### Arguments
+
+ - `char c`  
+   The character to print.
+
+---
+
+### `void hd44780_puts(const char *s)`
+
+Print a string of characters to the display.
+
+#### Arguments
+
+ - `const char *s`  
+   The string to print.
+
+---
+
+### `void hd44780_puts_P(const char *s)`
+
+Print a string of characters from PROGMEM to the display.
+
+On ARM devices, this function is simply an alias of `hd44780_puts()`.
+
+#### Arguments
+
+ - `const char *s`  
+   The PROGMEM string to print (ie. `PSTR("Hello")`).
+
+---
+
+### `void hd44780_define_char(uint8_t index, uint8_t *data)`
+
+Define a custom character.
+
+#### Arguments
+
+ - `uint8_t index`  
+   The index of the custom character to define, from 0 to 7.
+ - `uint8_t *data`  
+   An array of 8 bytes containing the 5-bit row data of the character, where the first byte is the topmost row, and the least significant bit of each byte is the rightmost column.
+
+---
+
+### `void hd44780_define_char_P(uint8_t index, const uint8_t *data)`
+
+Define a custom character from PROGMEM.
+
+On ARM devices, this function is simply an alias of `hd44780_define_char()`.
+
+#### Arguments
+
+ - `uint8_t index`  
+   The index of the custom character to define, from 0 to 7.
+ - `const uint8_t *data`  
+   A PROGMEM array of 8 bytes containing the 5-bit row data of the character, where the first byte is the topmost row, and the least significant bit of each byte is the rightmost column.
+
+---
+
+### `bool hd44780_busy(void)`
+
+Indicates whether the display is currently processing, and cannot accept instructions.
+
+#### Return Value
+
+`true` if the display is busy.
+
+---
+
+### `void hd44780_write(uint8_t data, bool isData)`
+
+Write a byte to the display.
+
+#### Arguments
+
+ - `uint8_t data`  
+   The byte to send to the display.
+ - `bool isData`  
+   Whether the byte is an instruction or character data.
+
+---
+
+### `uint8_t hd44780_read(bool isData)`
+
+Read a byte from the display.
+
+#### Arguments
+
+ - `bool isData`  
+   Whether to read the current cursor position, or the character at the cursor.
+
+#### Return Value
+
+If `isData` is `true`, the returned byte will be the character at the current DDRAM address. Otherwise, it will be the current DDRAM address and the busy flag.
+
+---
+
+### `void hd44780_command(uint8_t command)`
+
+Send a command to the display. Refer to the datasheet and `hd44780.h` for the valid commands and defines.
+
+This function waits for the display to clear the busy flag before sending the command.
+
+#### Arguments
+
+ - `uint8_t command`  
+   The command to send.
+
+---
+
+### `void hd44780_data(uint8_t data)`
+
+Send a byte of data to the display.
+
+This function waits for the display to clear the busy flag before sending the data.
+
+#### Arguments
+
+ - `uint8_t data`  
+   The byte of data to send.
+
+---
+
+### `void hd44780_set_cgram_address(uint8_t address)`
+
+Set the CGRAM address.
+
+This function is used when defining custom characters.
+
+#### Arguments
+
+ - `uint8_t address`  
+   The CGRAM address to move to, from `0x00` to `0x3F`.
+
+---
+
+### `void hd44780_set_ddram_address(uint8_t address)`
+
+Set the DDRAM address.
+
+This function is used when printing characters to the display, and setting the cursor.
+
+#### Arguments
+
+ - `uint8_t address`  
+   The DDRAM address to move to, from `0x00` to `0x7F`.

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 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_macros.md

@@ -106,6 +106,8 @@ Only basic keycodes (prefixed by `KC_`) are supported. Do not include the `KC_`
 
 ### `SEND_STRING()` & `process_record_user`
 
+See also: [Send String](feature_send_string.md)
+
 Sometimes you want a key to type out words or phrases. For the most common situations, we've provided `SEND_STRING()`, which will type out a string (i.e. a sequence of characters) for you. All ASCII characters that are easily translatable to a keycode are supported (e.g. `qmk 123\n\t`).
 
 Here is an example `keymap.c` for a two-key keyboard:

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`:
@@ -254,7 +258,7 @@ For the above, the `MI_C` keycode will produce a C3 (note number 48), and so on.
 <!--
 #### QMK Internals (Autogenerated)
  
- * [Internals/MIDI Device Setup Process](internals_midi_device_setup_process.md)
- * [Internals/MIDI Device](internals_midi_device.md)
- * [Internals/MIDI Util](internals_midi_util.md)
+ * [Internals/MIDI Device Setup Process](internals/midi_device_setup_process.md)
+ * [Internals/MIDI Device](internals/midi_device.md)
+ * [Internals/MIDI Util](internals/midi_util.md)
 -->

docs/feature_mouse_keys.md

@@ -87,9 +87,9 @@ This is an extension of the accelerated mode. The kinetic mode uses a quadratic
 |`MK_KINETIC_SPEED`                    |undefined|Enable kinetic mode                                            |
 |`MOUSEKEY_DELAY`                      |5        |Delay between pressing a movement key and cursor movement      |
 |`MOUSEKEY_INTERVAL`                   |10       |Time between cursor movements in milliseconds                  |
-|`MOUSEKEY_MOVE_DELTA`                 |5        |Step size for accelerating from initial to base speed          |
+|`MOUSEKEY_MOVE_DELTA`                 |16       |Step size for accelerating from initial to base speed          |
 |`MOUSEKEY_INITIAL_SPEED`              |100      |Initial speed of the cursor in pixel per second                |
-|`MOUSEKEY_BASE_SPEED`                 |1000     |Maximum cursor speed at which acceleration stops               |
+|`MOUSEKEY_BASE_SPEED`                 |5000     |Maximum cursor speed at which acceleration stops               |
 |`MOUSEKEY_DECELERATED_SPEED`          |400      |Decelerated cursor speed                                       |
 |`MOUSEKEY_ACCELERATED_SPEED`          |3000     |Accelerated cursor speed                                       |
 |`MOUSEKEY_WHEEL_INITIAL_MOVEMENTS`    |16       |Initial number of movements of the mouse wheel                 |
@@ -100,7 +100,7 @@ This is an extension of the accelerated mode. The kinetic mode uses a quadratic
 Tips:
 
 * The smoothness of the cursor movement depends on the `MOUSEKEY_INTERVAL` setting. The shorter the interval is set the smoother the movement will be.  Setting the value too low makes the cursor unresponsive.  Lower settings are possible if the micro processor is fast enough. For example: At an interval of `8` milliseconds, `125` movements per second will be initiated.  With a base speed of `1000` each movement will move the cursor by `8` pixels.
-* Mouse wheel movements are implemented differently from cursor movements. While it's okay for the cursor to move multiple pixels at once for the mouse wheel this would lead to jerky movements. Instead, the mouse wheel operates at step size `1`. Setting mouse wheel speed is done by adjusting the number of wheel movements per second.
+* Mouse wheel movements are implemented differently from cursor movements. While it's okay for the cursor to move multiple pixels at once for the mouse wheel this would lead to jerky movements. Instead, the mouse wheel operates at step size `2`. Setting mouse wheel speed is done by adjusting the number of wheel movements per second.
 
 ### Constant mode
 

docs/feature_pointing_device.md

@@ -23,10 +23,10 @@ POINTING_DEVICE_DRIVER = adns5050
 The ADNS 5050 sensor uses a serial type protocol for communication, and requires an additional light source. 
 
 | Setting             | Description                                                         |
-|--------------------|---------------------------------------------------------------------|
-|`ADNS5050_SCLK_PIN` | (Required) The pin connected to the clock pin of the sensor.        |
-|`ADNS5050_SDIO_PIN` | (Required) The pin connected to the data pin of the sensor.         |
-|`ADNS5050_CS_PIN`   | (Required) The pin connected to the cable select pin of the sensor. |
+| ------------------- | ------------------------------------------------------------------- |
+| `ADNS5050_SCLK_PIN` | (Required) The pin connected to the clock pin of the sensor.        |
+| `ADNS5050_SDIO_PIN` | (Required) The pin connected to the data pin of the sensor.         |
+| `ADNS5050_CS_PIN`   | (Required) The pin connected to the cable select pin of the sensor. |
 
 The CPI range is 125-1375, in increments of 125. Defaults to 500 CPI.
 
@@ -41,12 +41,12 @@ POINTING_DEVICE_DRIVER = adns9800
 The ADNS 9800 is an SPI driven optical sensor, that uses laser output for surface tracking. 
 
 | Setting                 | Description                                                            | Default       |
-|--------------------------------|------------------------------------------------------------------------|---------------|
-|`ADNS9800_CLOCK_SPEED`          | (Optional) Sets the clock speed that the sensor runs at.               | `2000000`     |
-|`ADNS9800_SPI_LSBFIRST`         | (Optional) Sets the Least/Most Significant Byte First setting for SPI. | `false`       |
-|`ADNS9800_SPI_MODE`             | (Optional) Sets the SPI Mode for the sensor.                           | `3`           |
-|`ADNS9800_SPI_DIVISOR`          | (Optional) Sets the SPI Divisor used for SPI communication.            | _varies_      |
-|`ADNS9800_CS_PIN`               | (Required) Sets the Cable Select pin connected to the sensor.          | _not defined_ |
+| ----------------------- | ---------------------------------------------------------------------- | ------------- |
+| `ADNS9800_CLOCK_SPEED`  | (Optional) Sets the clock speed that the sensor runs at.               | `2000000`     |
+| `ADNS9800_SPI_LSBFIRST` | (Optional) Sets the Least/Most Significant Byte First setting for SPI. | `false`       |
+| `ADNS9800_SPI_MODE`     | (Optional) Sets the SPI Mode for the sensor.                           | `3`           |
+| `ADNS9800_SPI_DIVISOR`  | (Optional) Sets the SPI Divisor used for SPI communication.            | _varies_      |
+| `ADNS9800_CS_PIN`       | (Required) Sets the Cable Select pin connected to the sensor.          | _not defined_ |
 
 
 The CPI range is 800-8200, in increments of 200. Defaults to 1800 CPI. 
@@ -62,16 +62,15 @@ POINTING_DEVICE_DRIVER = analog_joystick
 The Analog Joystick is an analog (ADC) driven sensor.  There are a variety of joysticks that you can use for this.
 
 | Setting                           | Description                                                                | Default       |
-|----------------------------------|----------------------------------------------------------------------------|---------------|
-|`ANALOG_JOYSTICK_X_AXIS_PIN`      | (Required) The pin used for the vertical/X axis.                           | _not defined_ |
-|`ANALOG_JOYSTICK_Y_AXIS_PIN`      | (Required) The pin used for the horizontal/Y axis.                         | _not defined_ |
-|`ANALOG_JOYSTICK_AXIS_MIN`        | (Optional) Sets the lower range to be considered movement.                 | `0`           |
-|`ANALOG_JOYSTICK_AXIS_MAX`        | (Optional) Sets the upper range to be considered movement.                 | `1023`        |
-|`ANALOG_JOYSTICK_SPEED_REGULATOR` | (Optional) The divisor used to slow down movement. (lower makes it faster) | `20`          |
-|`ANALOG_JOYSTICK_READ_INTERVAL`   | (Optional) The interval in milliseconds between reads.                     | `10`          |
-|`ANALOG_JOYSTICK_SPEED_MAX`       | (Optional) The maximum value used for motion.                              | `2`           |
-|`ANALOG_JOYSTICK_CLICK_PIN`       | (Optional) The pin wired up to the press switch of the analog stick.       | _not defined_ |
-
+| --------------------------------- | -------------------------------------------------------------------------- | ------------- |
+| `ANALOG_JOYSTICK_X_AXIS_PIN`      | (Required) The pin used for the vertical/X axis.                           | _not defined_ |
+| `ANALOG_JOYSTICK_Y_AXIS_PIN`      | (Required) The pin used for the horizontal/Y axis.                         | _not defined_ |
+| `ANALOG_JOYSTICK_AXIS_MIN`        | (Optional) Sets the lower range to be considered movement.                 | `0`           |
+| `ANALOG_JOYSTICK_AXIS_MAX`        | (Optional) Sets the upper range to be considered movement.                 | `1023`        |
+| `ANALOG_JOYSTICK_SPEED_REGULATOR` | (Optional) The divisor used to slow down movement. (lower makes it faster) | `20`          |
+| `ANALOG_JOYSTICK_READ_INTERVAL`   | (Optional) The interval in milliseconds between reads.                     | `10`          |
+| `ANALOG_JOYSTICK_SPEED_MAX`       | (Optional) The maximum value used for motion.                              | `2`           |
+| `ANALOG_JOYSTICK_CLICK_PIN`       | (Optional) The pin wired up to the press switch of the analog stick.       | _not defined_ |
 
 ### Cirque Trackpad
 
@@ -91,28 +90,69 @@ POINTING_DEVICE_DRIVER = cirque_pinnacle_spi
 This supports the Cirque Pinnacle 1CA027 Touch Controller, which is used in the TM040040, TM035035 and the TM023023 trackpads. These are I2C or SPI compatible, and both configurations are supported.
 
 | Setting                          | Description                                                | Default            |
-|---------------------------------|---------------------------------------------------------------------------------|-----------------------|
-|`CIRQUE_PINNACLE_X_LOWER`        | (Optional) The minimum reachable X value on the sensor.                         | `127`                 |
-|`CIRQUE_PINNACLE_X_UPPER`        | (Optional) The maximum reachable X value on the sensor.                         | `1919`                |
-|`CIRQUE_PINNACLE_Y_LOWER`        | (Optional) The minimum reachable Y value on the sensor.                         | `63`                  |
-|`CIRQUE_PINNACLE_Y_UPPER`        | (Optional) The maximum reachable Y value on the sensor.                         | `1471`                |
-|`CIRQUE_PINNACLE_TAPPING_TERM`   | (Optional) Length of time that a touch can be to be considered a tap.           | `TAPPING_TERM`/`200`  |
-|`CIRQUE_PINNACLE_TOUCH_DEBOUNCE` | (Optional) Length of time that a touch can be to be considered a tap.           | `TAPPING_TERM`/`200`  |
+| -------------------------------- | ---------------------------------------------------------- | ------------------ |
+| `CIRQUE_PINNACLE_X_LOWER`        | (Optional) The minimum reachable X value on the sensor.    | `127`              |
+| `CIRQUE_PINNACLE_X_UPPER`        | (Optional) The maximum reachable X value on the sensor.    | `1919`             |
+| `CIRQUE_PINNACLE_Y_LOWER`        | (Optional) The minimum reachable Y value on the sensor.    | `63`               |
+| `CIRQUE_PINNACLE_Y_UPPER`        | (Optional) The maximum reachable Y value on the sensor.    | `1471`             |
+| `CIRQUE_PINNACLE_DIAMETER_MM`    | (Optional) Diameter of the trackpad sensor in millimeters. | `40`               |
+| `CIRQUE_PINNACLE_ATTENUATION`    | (Optional) Sets the attenuation of the sensor data.        | `ADC_ATTENUATE_4X` |
+| `CIRQUE_PINNACLE_CURVED_OVERLAY` | (Optional) Applies settings tuned for curved overlay.      | _not defined_      |
+
+**`CIRQUE_PINNACLE_ATTENUATION`** is a measure of how much data is suppressed in regards to sensitivity. The higher the attenuation, the less sensitive the touchpad will be. 
+
+Default attenuation is set to 4X, although if you are using a thicker overlay (such as the curved overlay) you will want a lower attenuation such as 2X. The possible values are:
+* `ADC_ATTENUATE_4X`: Least sensitive
+* `ADC_ATTENUATE_3X`
+* `ADC_ATTENUATE_2X`
+* `ADC_ATTENUATE_1X`: Most sensitive
 
 | I2C Setting               | Description                                                                     | Default |
-|--------------------------|---------------------------------------------------------------------------------|---------|
-|`CIRQUE_PINNACLE_ADDR`    | (Required) Sets the I2C Address for the Cirque Trackpad                         | `0x2A`  |
-|`CIRQUE_PINNACLE_TIMEOUT` | (Optional) The timeout for i2c communication with the trackpad in milliseconds. | `20`    |
+| ------------------------- | ------------------------------------------------------------------------------- | ------- |
+| `CIRQUE_PINNACLE_ADDR`    | (Required) Sets the I2C Address for the Cirque Trackpad                         | `0x2A`  |
+| `CIRQUE_PINNACLE_TIMEOUT` | (Optional) The timeout for i2c communication with the trackpad in milliseconds. | `20`    |
 
 | SPI Setting                    | Description                                                            | Default       |
-|-------------------------------|------------------------------------------------------------------------|---------------|
-|`CIRQUE_PINNACLE_CLOCK_SPEED`  | (Optional) Sets the clock speed that the sensor runs at.               | `1000000`     |
-|`CIRQUE_PINNACLE_SPI_LSBFIRST` | (Optional) Sets the Least/Most Significant Byte First setting for SPI. | `false`       |
-|`CIRQUE_PINNACLE_SPI_MODE`     | (Optional) Sets the SPI Mode for the sensor.                           | `1`           |
-|`CIRQUE_PINNACLE_SPI_DIVISOR`  | (Optional) Sets the SPI Divisor used for SPI communication.            | _varies_      |
-|`CIRQUE_PINNACLE_SPI_CS_PIN`   | (Required) Sets the Cable Select pin connected to the sensor.          | _not defined_ |
+| ------------------------------ | ---------------------------------------------------------------------- | ------------- |
+| `CIRQUE_PINNACLE_CLOCK_SPEED`  | (Optional) Sets the clock speed that the sensor runs at.               | `1000000`     |
+| `CIRQUE_PINNACLE_SPI_LSBFIRST` | (Optional) Sets the Least/Most Significant Byte First setting for SPI. | `false`       |
+| `CIRQUE_PINNACLE_SPI_MODE`     | (Optional) Sets the SPI Mode for the sensor.                           | `1`           |
+| `CIRQUE_PINNACLE_SPI_DIVISOR`  | (Optional) Sets the SPI Divisor used for SPI communication.            | _varies_      |
+| `CIRQUE_PINNACLE_SPI_CS_PIN`   | (Required) Sets the Cable Select pin connected to the sensor.          | _not defined_ |
+
+Default Scaling is 1024. Actual CPI depends on trackpad diameter.
+
+Also see the `POINTING_DEVICE_TASK_THROTTLE_MS`, which defaults to 10ms when using Cirque Pinnacle, which matches the internal update rate of the position registers (in standard configuration). Advanced configuration for pen/stylus usage might require lower values.
+
+#### Cirque Trackpad gestures
+
+| Gesture Setting                                | Description                                                                                                                                                                                      | Default              |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- |
+| `POINTING_DEVICE_GESTURES_CURSOR_GLIDE_ENABLE` | (Optional) Enable inertial cursor. Cursor continues moving after a flick gesture and slows down by kinetic friction                                                                              | _not defined_        |
+| `CIRQUE_PINNACLE_CIRCULAR_SCROLL_ENABLE`       | (Optional) Enable circular scroll. Touch originating in outer ring can trigger scroll by moving along the perimeter. Near side triggers vertical scroll and far side triggers horizontal scroll. | _not defined_        |
+| `CIRQUE_PINNACLE_TAP_ENABLE`                   | (Optional) Enable tap to click. This currently only works on the master side.                                                                                                                    | _not defined_        |
+| `CIRQUE_PINNACLE_TAPPING_TERM`                 | (Optional) Length of time that a touch can be to be considered a tap.                                                                                                                            | `TAPPING_TERM`/`200` |
+| `CIRQUE_PINNACLE_TOUCH_DEBOUNCE`               | (Optional) Length of time that a touch can be to be considered a tap.                                                                                                                            | `TAPPING_TERM`/`200` |
+
+**`POINTING_DEVICE_GESTURES_CURSOR_GLIDE_ENABLE`** is not specific to Cirque trackpad; any pointing device with a lift/contact status can integrate this gesture into its driver. e.g. PMW3360 can use Lift_Stat from Motion register. Note that `POINTING_DEVICE_MOTION_PIN` cannot be used with this feature; continuous polling of `pointing_device_get_report()` is needed to generate glide reports.
+
+### PAW 3204 Sensor
+
+To use the paw 3204 sensor, add this to your `rules.mk`
+
+```make
+POINTING_DEVICE_DRIVER = paw3204
+```
+
+The paw 3204 sensor uses a serial type protocol for communication, and requires an additional light source. 
+
+| Setting            | Description                                                         |
+|--------------------|---------------------------------------------------------------------|
+|`PAW3204_SCLK_PIN` | (Required) The pin connected to the clock pin of the sensor.        |
+|`PAW3204_SDIO_PIN` | (Required) The pin connected to the data pin of the sensor.         |
+
+The CPI range is 400-1600, with supported values of (400, 500, 600, 800, 1000, 1200 and 1600).  Defaults to 1000 CPI.
 
-Default Scaling/CPI is 1024.
 
 ### Pimoroni Trackball
 
@@ -125,59 +165,74 @@ POINTING_DEVICE_DRIVER = pimoroni_trackball
 The Pimoroni Trackball module is a I2C based breakout board with an RGB enable trackball. 
 
 | Setting                              | Description                                                                        | Default |
-|-------------------------------------|------------------------------------------------------------------------------------|---------|
-|`PIMORONI_TRACKBALL_ADDRESS`         | (Required) Sets the I2C Address for the Pimoroni Trackball.                        | `0x0A`  |
-|`PIMORONI_TRACKBALL_TIMEOUT`         | (Optional) The timeout for i2c communication with the trackball in milliseconds.   | `100`   |
-|`PIMORONI_TRACKBALL_SCALE`           | (Optional) The multiplier used to generate reports from the sensor.                | `5`     |
-|`PIMORONI_TRACKBALL_DEBOUNCE_CYCLES` | (Optional) The number of scan cycles used for debouncing on the ball press.        | `20`    |
-|`PIMORONI_TRACKBALL_ERROR_COUNT`     | (Optional) Specifies the number of read/write errors until the sensor is disabled. | `10`    |
+| ------------------------------------ | ---------------------------------------------------------------------------------- | ------- |
+| `PIMORONI_TRACKBALL_ADDRESS`         | (Required) Sets the I2C Address for the Pimoroni Trackball.                        | `0x0A`  |
+| `PIMORONI_TRACKBALL_TIMEOUT`         | (Optional) The timeout for i2c communication with the trackball in milliseconds.   | `100`   |
+| `PIMORONI_TRACKBALL_SCALE`           | (Optional) The multiplier used to generate reports from the sensor.                | `5`     |
+| `PIMORONI_TRACKBALL_DEBOUNCE_CYCLES` | (Optional) The number of scan cycles used for debouncing on the ball press.        | `20`    |
+| `PIMORONI_TRACKBALL_ERROR_COUNT`     | (Optional) Specifies the number of read/write errors until the sensor is disabled. | `10`    |
 
-### PMW 3360 Sensor
+### PMW 3360 and PMW 3389 Sensor
 
-To use the PMW 3360 sensor, add this to your `rules.mk`
+This drivers supports both the PMW 3360 and PMW 3389 sensor as well as multiple sensors of the same type _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
 POINTING_DEVICE_DRIVER = pmw3360
 ```
 
-The PMW 3360 is an SPI driven optical sensor, that uses a built in IR LED for surface tracking.
-
-| Setting                     | Description                                                                                | Default       |
-|-----------------------------|--------------------------------------------------------------------------------------------|---------------|
-|`PMW3360_CS_PIN`                 | (Required) Sets the Cable Select pin connected to the sensor.                              | _not defined_ |
-|`PMW3360_CLOCK_SPEED`            | (Optional) Sets the clock speed that the sensor runs at.                                   | `2000000`     |
-|`PMW3360_SPI_LSBFIRST`           | (Optional) Sets the Least/Most Significant Byte First setting for SPI.                     | `false`       |
-|`PMW3360_SPI_MODE`               | (Optional) Sets the SPI Mode for the sensor.                                               | `3`           |
-|`PMW3360_SPI_DIVISOR`            | (Optional) Sets the SPI Divisor used for SPI communication.                                | _varies_      |
-|`PMW3360_LIFTOFF_DISTANCE`       | (Optional) Sets the lift off distance at run time                                          | `0x02`        |
-|`ROTATIONAL_TRANSFORM_ANGLE`     | (Optional) Allows for the sensor data to be rotated +/- 127 degrees directly in the sensor.| `0`           |
-|`PMW3360_FIRMWARE_UPLOAD_FAST`   | (Optional) Skips the 15us wait between firmware blocks.                                    | _not defined_ |
-
 The CPI range is 100-12000, in increments of 100. Defaults to 1600 CPI.
 
-### PMW 3389 Sensor
-
-To use the PMW 3389 sensor, add this to your `rules.mk`
+To use the **PMW 3389** sensor, add this to your `rules.mk`
 
 ```make
 POINTING_DEVICE_DRIVER = pmw3389
 ```
 
-The PMW 3389 is an SPI driven optical sensor, that uses a built in IR LED for surface tracking.
-
-| Setting                         | Description                                                                                | Default       |
-|---------------------------------|--------------------------------------------------------------------------------------------|---------------|
-|`PMW3389_CS_PIN`                 | (Required) Sets the Cable Select pin connected to the sensor.                              | _not defined_ |
-|`PMW3389_CLOCK_SPEED`            | (Optional) Sets the clock speed that the sensor runs at.                                   | `2000000`     |
-|`PMW3389_SPI_LSBFIRST`           | (Optional) Sets the Least/Most Significant Byte First setting for SPI.                     | `false`       |
-|`PMW3389_SPI_MODE`               | (Optional) Sets the SPI Mode for the sensor.                                               | `3`           |
-|`PMW3389_SPI_DIVISOR`            | (Optional) Sets the SPI Divisor used for SPI communication.                                | _varies_      |
-|`PMW3389_LIFTOFF_DISTANCE`       | (Optional) Sets the lift off distance at run time                                          | `0x02`        |
-|`ROTATIONAL_TRANSFORM_ANGLE`     | (Optional) Allows for the sensor data to be rotated +/- 30 degrees directly in the sensor. | `0`           |
-|`PMW3389_FIRMWARE_UPLOAD_FAST`   | (Optional) Skips the 15us wait between firmware blocks.                                    | _not defined_ |
-
 The CPI range is 50-16000, in increments of 50. Defaults to 2000 CPI.
 
+Both PMW 3360 and PMW 3389 are SPI driven optical sensors, that use a built in IR LED for surface tracking.
+
+| Setting                      | Description                                                                                 | Default       |
+| ---------------------------- | ------------------------------------------------------------------------------------------- | ------------- |
+| `PMW33XX_CS_PIN`             | (Required) Sets the Cable Select pin connected to the sensor.                               | _not defined_ |
+| `PMW33XX_CS_PINS`            | (Alternative) Sets the Cable Select pins connected to multiple sensors.                     | _not defined_ |
+| `PMW33XX_CPI`                | (Optional) Sets counts per inch sensitivity of the sensor.                                  | _varies_      |
+| `PMW33XX_CLOCK_SPEED`        | (Optional) Sets the clock speed that the sensor runs at.                                    | `2000000`     |
+| `PMW33XX_SPI_DIVISOR`        | (Optional) Sets the SPI Divisor used for SPI communication.                                 | _varies_      |
+| `PMW33XX_LIFTOFF_DISTANCE`   | (Optional) Sets the lift off distance at run time                                           | `0x02`        |
+| `ROTATIONAL_TRANSFORM_ANGLE` | (Optional) Allows for the sensor data to be rotated +/- 127 degrees directly in the sensor. | `0`           |
+
+To use multiple sensors, instead of setting `PMW33XX_CS_PIN` you need to set `PMW33XX_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 PMW33XX_CS_PINS { B5, B6 }
+// in keyboard.c:
+#ifdef POINTING_DEVICE_ENABLE
+void pointing_device_init_kb(void) {
+    pmw33xx_init(1);         // index 1 is the second device.
+    pmw33xx_set_cpi(0, 800); // applies to first sensor
+    pmw33xx_set_cpi(1, 800); // applies to second sensor
+    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) {
+    pmw33xx_report_t report = pmw33xx_read_burst(1);
+    if (!report.motion.b.is_lifted && report.motion.b.is_motion) {
+// 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 + report.delta_x);
+        mouse_report.y = constrain_hid(mouse_report.y + report.delta_y);
+    }
+    return pointing_device_task_user(mouse_report);
+}
+#endif
+
+```
 
 ### Custom Driver
 
@@ -201,14 +256,14 @@ void           pointing_device_driver_set_cpi(uint16_t cpi) {}
 ## Common Configuration
 
 | Setting                            | Description                                                           | Default       |
-|----------------------------------|-----------------------------------------------------------------------|-------------------|
-|`POINTING_DEVICE_ROTATION_90`     | (Optional) Rotates the X and Y data by  90 degrees.                   | _not defined_     |
-|`POINTING_DEVICE_ROTATION_180`    | (Optional) Rotates the X and Y data by 180 degrees.                   | _not defined_     |
-|`POINTING_DEVICE_ROTATION_270`    | (Optional) Rotates the X and Y data by 270 degrees.                   | _not defined_     |
-|`POINTING_DEVICE_INVERT_X`        | (Optional) Inverts the X axis report.                                 | _not defined_     |
-|`POINTING_DEVICE_INVERT_Y`        | (Optional) Inverts the Y axis report.                                 | _not defined_     |
-|`POINTING_DEVICE_MOTION_PIN`      | (Optional) If supported, will only read from sensor if pin is active. | _not defined_     |
-|`POINTING_DEVICE_TASK_THROTTLE_MS`      | (Optional) Limits the frequency that the sensor is polled for motion. | _not defined_     |
+| ---------------------------------- | --------------------------------------------------------------------- | ------------- |
+| `POINTING_DEVICE_ROTATION_90`      | (Optional) Rotates the X and Y data by  90 degrees.                   | _not defined_ |
+| `POINTING_DEVICE_ROTATION_180`     | (Optional) Rotates the X and Y data by 180 degrees.                   | _not defined_ |
+| `POINTING_DEVICE_ROTATION_270`     | (Optional) Rotates the X and Y data by 270 degrees.                   | _not defined_ |
+| `POINTING_DEVICE_INVERT_X`         | (Optional) Inverts the X axis report.                                 | _not defined_ |
+| `POINTING_DEVICE_INVERT_Y`         | (Optional) Inverts the Y axis report.                                 | _not defined_ |
+| `POINTING_DEVICE_MOTION_PIN`       | (Optional) If supported, will only read from sensor if pin is active. | _not defined_ |
+| `POINTING_DEVICE_TASK_THROTTLE_MS` | (Optional) Limits the frequency that the sensor is polled for motion. | _not defined_ |
 
 !> When using `SPLIT_POINTING_ENABLE` the `POINTING_DEVICE_MOTION_PIN` functionality is not supported and `POINTING_DEVICE_TASK_THROTTLE_MS` will default to `1`. Increasing this value will increase transport performance at the cost of possible mouse responsiveness.
 
@@ -218,15 +273,16 @@ void           pointing_device_driver_set_cpi(uint16_t cpi) {}
 The following configuration options are only available when using `SPLIT_POINTING_ENABLE` see [data sync options](feature_split_keyboard.md?id=data-sync-options). The rotation and invert `*_RIGHT` options are only used with `POINTING_DEVICE_COMBINED`. If using `POINTING_DEVICE_LEFT` or `POINTING_DEVICE_RIGHT` use the common configuration above to configure your pointing device.
 
 | Setting                              | Description                                                                                           | Default       |
-|----------------------------------------|-----------------------------------------------------------------------|---------------|
-|`POINTING_DEVICE_LEFT`                  | Pointing device on the left side (Required - pick one only)           | _not defined_ |
-|`POINTING_DEVICE_RIGHT`                 | Pointing device on the right side (Required - pick one only)          | _not defined_ |
-|`POINTING_DEVICE_COMBINED`              | Pointing device on both sides (Required - pick one only)              | _not defined_ |
-|`POINTING_DEVICE_ROTATION_90_RIGHT`     | (Optional) Rotates the X and Y data by  90 degrees.                   | _not defined_ |
-|`POINTING_DEVICE_ROTATION_180_RIGHT`    | (Optional) Rotates the X and Y data by 180 degrees.                   | _not defined_ |
-|`POINTING_DEVICE_ROTATION_270_RIGHT`    | (Optional) Rotates the X and Y data by 270 degrees.                   | _not defined_ |
-|`POINTING_DEVICE_INVERT_X_RIGHT`        | (Optional) Inverts the X axis report.                                 | _not defined_ |
-|`POINTING_DEVICE_INVERT_Y_RIGHT`        | (Optional) Inverts the Y axis report.                                 | _not defined_ |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------- | ------------- |
+| `POINTING_DEVICE_LEFT`               | Pointing device on the left side (Required - pick one only)                                           | _not defined_ |
+| `POINTING_DEVICE_RIGHT`              | Pointing device on the right side (Required - pick one only)                                          | _not defined_ |
+| `POINTING_DEVICE_COMBINED`           | Pointing device on both sides (Required - pick one only)                                              | _not defined_ |
+| `POINTING_DEVICE_ROTATION_90_RIGHT`  | (Optional) Rotates the X and Y data by  90 degrees.                                                   | _not defined_ |
+| `POINTING_DEVICE_ROTATION_180_RIGHT` | (Optional) Rotates the X and Y data by 180 degrees.                                                   | _not defined_ |
+| `POINTING_DEVICE_ROTATION_270_RIGHT` | (Optional) Rotates the X and Y data by 270 degrees.                                                   | _not defined_ |
+| `POINTING_DEVICE_INVERT_X_RIGHT`     | (Optional) Inverts the X axis report.                                                                 | _not defined_ |
+| `POINTING_DEVICE_INVERT_Y_RIGHT`     | (Optional) Inverts the Y axis report.                                                                 | _not defined_ |
+| `MOUSE_EXTENDED_REPORT`              | (Optional) Enables support for extended mouse reports. (-32767 to 32767, instead of just -127 to 127) |
 
 !> If there is a `_RIGHT` configuration option or callback, the [common configuration](feature_pointing_device.md?id=common-configuration) option will work for the left. For correct left/right detection you should setup a [handedness option](feature_split_keyboard?id=setting-handedness), `EE_HANDS` is usually a good option for an existing board that doesn't do handedness by hardware.
 
@@ -234,7 +290,7 @@ The following configuration options are only available when using `SPLIT_POINTIN
 ## Callbacks and Functions 
 
 | Function                                                   | Description                                                                                                   |
-|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
 | `pointing_device_init_kb(void)`                            | Callback to allow for keyboard level initialization. Useful for additional hardware sensors.                  |
 | `pointing_device_init_user(void)`                          | Callback to allow for user level initialization. Useful for additional hardware sensors.                      |
 | `pointing_device_task_kb(mouse_report)`                    | Callback that sends sensor data, so keyboard code can intercept and modify the data.  Returns a mouse report. |
@@ -254,7 +310,7 @@ The following configuration options are only available when using `SPLIT_POINTIN
 The combined functions below are only available when using `SPLIT_POINTING_ENABLE` and `POINTING_DEVICE_COMBINED`. The 2 callbacks `pointing_device_task_combined_*` replace the single sided equivalents above. See the [combined pointing devices example](feature_pointing_device.md?id=combined-pointing-devices)
 
 | Function                                                        | Description                                                                                                              |
-|-----------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
 | `pointing_device_set_shared_report(mouse_report)`               | Sets the shared mouse report to the assigned `mouse_report_t` data structured passed to the function.                    |
 | `pointing_device_set_cpi_on_side(bool, uint16_t)`               | Sets the CPI/DPI of one side, if supported. Passing `true` will set the left and `false` the right`                      |
 | `pointing_device_combine_reports(left_report, right_report)`    | Returns a combined mouse_report of left_report and right_report (as a `mouse_report_t` data structure)                   |
@@ -325,7 +381,8 @@ report_mouse_t pointing_device_task_user(report_mouse_t mouse_report) {
     if (set_scrolling) {
         mouse_report.h = mouse_report.x;
         mouse_report.v = mouse_report.y;
-        mouse_report.x = mouse_report.y = 0
+        mouse_report.x = 0;
+        mouse_report.y = 0;
     }
     return mouse_report;
 }

docs/feature_rgb_matrix.md

@@ -86,6 +86,7 @@ You can use between 1 and 4 IS31FL3733 IC's. Do not specify `DRIVER_ADDR_<N>` de
 | `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 |
 | `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 |
 | `ISSI_PWM_FREQUENCY` | (Optional) PWM Frequency Setting - IS31FL3733B only | 0 |
+| `ISSI_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF |
 | `ISSI_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) |
 | `ISSI_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) |
 | `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | |
@@ -171,6 +172,8 @@ Configure the hardware via your `config.h`:
 |----------|-------------|---------|
 | `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 |
 | `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 |
+| `ISSI_PWM_FREQUENCY` | (Optional) PWM Frequency Setting - IS31FL3737B only | 0 |
+| `ISSI_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF |
 | `ISSI_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) |
 | `ISSI_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) |
 | `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | |
@@ -408,6 +411,7 @@ You can use up to 2 AW20216 IC's. Do not specify `DRIVER_<N>_xxx` defines for IC
 | `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | |
 | `AW_SCALING_MAX` | (Optional) LED current scaling value (0-255, higher values mean LED is brighter at full PWM) | 150 |
 | `AW_GLOBAL_CURRENT_MAX` | (Optional) Driver global current limit (0-255, higher values means the driver may consume more power) | 150 |
+| `AW_SPI_MODE` | (Optional) Mode for SPI communication (0-3, defines polarity and phase of the clock) | 3 |
 | `AW_SPI_DIVISOR` | (Optional) Clock divisor for SPI communication (powers of 2, smaller numbers means faster communication, should not be less than 4) | 4 |
 
 Here is an example using 2 drivers.
@@ -519,7 +523,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) |
@@ -656,18 +660,44 @@ 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
 ```
 
+As heatmap uses the physical position of the leds set in the g_led_config, you may need to tweak the following options to get the best effect for your keyboard. Note the size of this grid is `224x64`.
+
+Limit the distance the effect spreads to surrounding keys. 
+
+```c
+#define RGB_MATRIX_TYPING_HEATMAP_SPREAD 40
+```
+
+Limit how hot surrounding keys get from each press.
+
+```c
+#define RGB_MATRIX_TYPING_HEATMAP_AREA_LIMIT 16
+```
+
+Remove the spread effect entirely.
+
+```c
+#define RGB_MATRIX_TYPING_HEATMAP_SLIM
+```
+
+### RGB Matrix Effect Solid Reactive :id=rgb-matrix-effect-solid-reactive
+
+Solid reactive effects will pulse RGB light on key presses with user configurable hues. To enable gradient mode that will automatically change reactive color, add the following define:
+
+```c
+#define RGB_MATRIX_SOLID_REACTIVE_GRADIENT_MODE
+```
+
+Gradient mode will loop through the color wheel hues over time and its duration can be controlled with the effect speed keycodes (`RGB_SPI`/`RGB_SPD`).
+
 ## 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.
@@ -775,6 +805,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

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_send_string.md

@@ -0,0 +1,224 @@
+# Send String
+
+The Send String API is part of QMK's macro system. It allows for sequences of keystrokes to be sent automatically.
+
+The full ASCII character set is supported, along with all of the keycodes in the Basic Keycode range (as these are the only ones that will actually be sent to the host).
+
+?> Unicode characters are **not** supported with this API -- see the [Unicode](feature_unicode.md) feature instead.
+
+## Usage
+
+Send String is enabled by default, so there is usually no need for any special setup. However, if it is disabled, add the following to your `rules.mk`:
+
+```make
+SEND_STRING_ENABLE = yes
+```
+
+## Basic Configuration
+
+Add the following to your `config.h`:
+
+|Define           |Default         |Description                                                                                                 |
+|-----------------|----------------|------------------------------------------------------------------------------------------------------------|
+|`SENDSTRING_BELL`|*Not defined*   |If the [Audio](feature_audio.md) feature is enabled, the `\a` character (ASCII `BEL`) will beep the speaker.|
+|`BELL_SOUND`     |`TERMINAL_SOUND`|The song to play when the `\a` character is encountered. By default, this is an eighth note of C5.          |
+
+## Keycodes
+
+The Send String functions accept C string literals, but specific keycodes can be injected with the below macros. All of the keycodes in the [Basic Keycode range](keycodes_basic.md) are supported (as these are the only ones that will actually be sent to the host), but with an `X_` prefix instead of `KC_`.
+
+|Macro         |Description                                                        |
+|--------------|-------------------------------------------------------------------|
+|`SS_TAP(x)`   |Send a keydown, then keyup, event for the given Send String keycode|
+|`SS_DOWN(x)`  |Send a keydown event for the given Send String keycode             |
+|`SS_UP(x)`    |Send a keyup event for the given Send String keycode               |
+|`SS_DELAY(ms)`|Wait for `ms` milliseconds                                         |
+
+The following characters are also mapped to their respective keycodes for convenience:
+
+|Character|Hex   |ASCII|Keycode       |
+|---------|------|-----|--------------|
+|`\b`     |`\x08`|`BS` |`KC_BACKSPACE`|
+|`\e`     |`\x09`|`ESC`|`KC_ESCAPE`   |
+|`\n`     |`\x0A`|`LF` |`KC_ENTER`    |
+|`\t`     |`\x1B`|`TAB`|`KC_TAB`      |
+|         |`\x7F`|`DEL`|`KC_DELETE`   |
+
+### Language Support
+
+By default, Send String assumes your OS keyboard layout is set to US ANSI. If you are using a different keyboard layout, you can [override the lookup tables used to convert ASCII characters to keystrokes](reference_keymap_extras.md#sendstring-support).
+
+## Examples
+
+### Hello World
+
+A simple custom keycode which types out "Hello, world!" and the Enter key when pressed.
+
+Add the following to your `keymap.c`:
+
+```c
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+    switch (keycode) {
+        case SS_HELLO:
+            if (record->event.pressed) {
+                SEND_STRING("Hello, world!\n");
+            }
+            return false;
+    }
+
+    return true;
+}
+```
+
+### Keycode Injection
+
+This example types out opening and closing curly braces, then taps the left arrow key to move the cursor between the two.
+
+```c
+SEND_STRING("{}" SS_TAP(X_LEFT));
+```
+
+This example types Ctrl+A, then Ctrl+C, without releasing Ctrl.
+
+```c
+SEND_STRING(SS_LCTL("ac"));
+```
+
+## API
+
+### `void send_string(const char *string)`
+
+Type out a string of ASCII characters.
+
+This function simply calls `send_string_with_delay(string, 0)`.
+
+#### Arguments
+
+ - `const char *string`  
+   The string to type out.
+
+---
+
+### `void send_string_with_delay(const char *string, uint8_t interval)`
+
+Type out a string of ASCII characters, with a delay between each character.
+
+#### Arguments
+
+ - `const char *string`  
+   The string to type out.
+ - `uint8_t interval`  
+   The amount of time, in milliseconds, to wait before typing the next character.
+
+---
+
+### `void send_string_P(const char *string)`
+
+Type out a PROGMEM string of ASCII characters.
+
+On ARM devices, this function is simply an alias for `send_string_with_delay(string, 0)`.
+
+#### Arguments
+
+ - `const char *string`  
+   The string to type out.
+
+---
+
+### `void send_string_with_delay_P(const char *string, uint8_t interval)`
+
+Type out a PROGMEM string of ASCII characters, with a delay between each character.
+
+On ARM devices, this function is simply an alias for `send_string_with_delay(string, interval)`.
+
+#### Arguments
+
+ - `const char *string`  
+   The string to type out.
+ - `uint8_t interval`  
+   The amount of time, in milliseconds, to wait before typing the next character.
+
+---
+
+### `void send_char(char ascii_code)`
+
+Type out an ASCII character.
+
+#### Arguments
+
+ - `char ascii_code`  
+   The character to type.
+
+---
+
+### `void send_dword(uint32_t number)`
+
+Type out an eight digit (unsigned 32-bit) hexadecimal value.
+
+The format is `[0-9a-f]{8}`, eg. `00000000` through `ffffffff`.
+
+#### Arguments
+
+ - `uint32_t number`  
+   The value to type, from 0 to 4,294,967,295.
+
+---
+
+### `void send_word(uint16_t number)`
+
+Type out a four digit (unsigned 16-bit) hexadecimal value.
+
+The format is `[0-9a-f]{4}`, eg. `0000` through `ffff`.
+
+#### Arguments
+
+ - `uint16_t number`  
+   The value to type, from 0 to 65,535.
+
+---
+
+### `void send_byte(uint8_t number)`
+
+Type out a two digit (8-bit) hexadecimal value.
+
+The format is `[0-9a-f]{2}`, eg. `00` through `ff`.
+
+#### Arguments
+
+ - `uint8_t number`  
+   The value to type, from 0 to 255.
+
+---
+
+### `void send_nibble(uint8_t number)`
+
+Type out a single hexadecimal digit.
+
+The format is `[0-9a-f]{1}`, eg. `0` through `f`.
+
+#### Arguments
+
+ - `uint8_t number`  
+   The value to type, from 0 to 15.
+
+---
+
+### `void tap_random_base64(void)`
+
+Type a pseudorandom character from the set `A-Z`, `a-z`, `0-9`, `+` and `/`.
+
+---
+
+### `SEND_STRING(string)`
+
+Shortcut macro for `send_string_with_delay_P(PSTR(string), 0)`.
+
+On ARM devices, this define evaluates to `send_string_with_delay(string, 0)`.
+
+---
+
+### `SEND_STRING_DELAY(string, interval)`
+
+Shortcut macro for `send_string_with_delay_P(PSTR(string), interval)`.
+
+On ARM devices, this define evaluates to `send_string_with_delay(string, interval)`.

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                |
@@ -141,6 +143,9 @@ Next, you will have to flash the EEPROM files once for the correct hand to the c
 * ARM controllers with a DFU compatible bootloader (e.g. Proton-C):
   * `:dfu-util-split-left`
   * `:dfu-util-split-right`
+* ARM controllers with a UF2 compatible bootloader:
+  * `:uf2-split-left`
+  * `:uf2-split-right`
 
 Example:
 
@@ -365,7 +370,7 @@ There are some settings that you may need to configure, based on how the hardwar
 #define MATRIX_COL_PINS_RIGHT { <col pins> }
 ```
 
-This allows you to specify a different set of pins for the matrix on the right side.  This is useful if you have a board with differently-shaped halves that requires a different configuration (such as Keebio's Quefrency).
+This allows you to specify a different set of pins for the matrix on the right side.  This is useful if you have a board with differently-shaped halves that requires a different configuration (such as Keebio's Quefrency). The number of pins in the right and left matrices must be the same, if you have a board with a different number of rows or columns on one side, pad out the extra spaces with `NO_PIN` and make sure you add the unused rows or columns to your matrix.
 
 ```c
 #define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }

docs/feature_stenography.md

@@ -8,46 +8,107 @@ The [Open Steno Project](https://www.openstenoproject.org/) has built an open-so
 
 Plover can work with any standard QWERTY keyboard, although it is more efficient if the keyboard supports NKRO (n-key rollover) to allow Plover to see all the pressed keys at once. An example keymap for Plover can be found in `planck/keymaps/default`. Switching to the `PLOVER` layer adjusts the position of the keyboard to support the number bar.
 
-To use Plover with QMK just enable NKRO and optionally adjust your layout if you have anything other than a standard layout. You may also want to purchase some steno-friendly keycaps to make it easier to hit multiple keys.
+To enable NKRO, add `NKRO_ENABLE = yes` in your `rules.mk` and make sure to press `NK_ON` to turn it on because `NKRO_ENABLE = yes` merely adds the possibility of switching to NKRO mode but it doesn't automatically switch to it. If you want to automatically switch, add `#define FORCE_NKRO` in your `config.h`.
+
+You may also need to adjust your layout, either in QMK or in Plover, if you have anything other than a standard layout. You may also want to purchase some steno-friendly keycaps to make it easier to hit multiple keys.
 
 ## Plover with Steno Protocol :id=plover-with-steno-protocol
 
-Plover also understands the language of several steno machines. QMK can speak a couple of these languages, TX Bolt and GeminiPR. An example layout can be found in `planck/keymaps/steno`.
+Plover also understands the language of several steno machines. QMK can speak a couple of these languages: TX Bolt and GeminiPR. An example layout can be found in `planck/keymaps/steno`.
 
-When QMK speaks to Plover over a steno protocol Plover will not use the keyboard as input. This means that you can switch back and forth between a standard keyboard and your steno keyboard, or even switch layers from Plover to standard and back without needing to activate/deactivate Plover.
+When QMK speaks to Plover over a steno protocol, Plover will not use the keyboard as input. This means that you can switch back and forth between a standard keyboard and your steno keyboard, or even switch layers from Plover to standard and back without needing to activate/deactivate Plover.
 
-In this mode Plover expects to speak with a steno machine over a serial port so QMK will present itself to the operating system as a virtual serial port in addition to a keyboard. By default QMK will speak the TX Bolt protocol but can be switched to GeminiPR; the last protocol used is stored in non-volatile memory so QMK will use the same protocol on restart.
+In this mode, Plover expects to speak with a steno machine over a serial port so QMK will present itself to the operating system as a virtual serial port in addition to a keyboard.
 
-> Note: Due to hardware limitations you may not be able to run both a virtual serial port and mouse emulation at the same time.
+> Note: Due to hardware limitations, you might not be able to run both a virtual serial port and mouse emulation at the same time.
+
+!> Serial stenography protocols are not supported on [V-USB keyboards](compatible_microcontrollers#atmel-avr).
+
+To enable stenography protocols, add the following lines to your `rules.mk`:
+```mk
+STENO_ENABLE = yes
+```
 
 ### TX Bolt :id=tx-bolt
 
-TX Bolt communicates the status of 24 keys over a very simple protocol in variable-sized (1-5 byte) packets.
+TX Bolt communicates the status of 24 keys over a simple protocol in variable-sized (1–4 bytes) packets.
+
+To select TX Bolt, add the following lines to your `rules.mk`:
+```mk
+STENO_ENABLE = yes
+STENO_PROTOCOL = txbolt
+```
+
+Each byte of the packet represents a different group of steno keys. Determining the group of a certain byte of the packet is done by checking the first two bits, the remaining bits are set if the corresponding steno key was pressed for the stroke. The last set of keys (as indicated by leading `11`) needs to keep track of less keys than there are bits so one of the bits is constantly 0.
+
+The start of a new packet can be detected by comparing the group “ID” (the two MSBs) of the current byte to that of the previously received byte. If the group “ID” of the current byte is smaller or equal to that of the previous byte, it means that the current byte is the beginning of a new packet.
+
+The format of TX Bolt packets is shown below.
+```
+00HWPKTS 01UE*OAR 10GLBPRF 110#ZDST
+```
+
+Examples of steno strokes and the associated packet:
+- `EUBG`    = `01110000 10101000`
+- `WAZ`     = `00010000 01000010 11001000`
+- `PHAPBGS` = `00101000 01000010 10101100 11000010`
 
 ### GeminiPR :id=geminipr
 
-GeminiPR encodes 42 keys into a 6-byte packet. While TX Bolt contains everything that is necessary for standard stenography, GeminiPR opens up many more options, including supporting non-English theories.
+GeminiPR encodes 42 keys into a 6-byte packet. While TX Bolt contains everything that is necessary for standard stenography, GeminiPR opens up many more options, including differentiating between top and bottom `S-`, and supporting non-English theories.
+
+To select GeminiPR, add the following lines to your `rules.mk`:
+```mk
+STENO_ENABLE = yes
+STENO_PROTOCOL = geminipr
+```
+
+All packets in the GeminiPR protocol consist of exactly six bytes, used as bit-arrays for different groups of keys. The beginning of a packet is indicated by setting the most significant bit (MSB) to 1 while setting the MSB of the remaining five bytes to 0.
+
+The format of GeminiPR packets is shown below.
+```
+1 Fn  #1  #2 #3 #4 #5   #6
+0 S1- S2- T- K- P- W-   H-
+0 R-  A-  O- *1 *2 res1 res2
+0 pwr *3  *4 -E -U -F   -R
+0 -P  -B  -L -G -T -S   -D
+0 #7  #8  #9 #A #B #C   -Z
+```
+
+Examples of steno strokes and the associated packet:
+- `EUBG`    = `10000000 00000000 00000000 00001100 00101000 00000000`
+- `WAZ`     = `10000000 00000010 00100000 00000000 00000000 00000001`
+- `PHAPBGS` = `10000000 00000101 00100000 00000000 01101010 00000000`
+
+### Switching protocols on the fly :id=switching-protocols-on-the-fly
+
+If you wish to switch the serial protocol used to transfer the steno chords without having to recompile your keyboard firmware every time, you can press the `QK_STENO_BOLT` and `QK_STENO_GEMINI` keycodes in order to switch protocols on the fly.
+
+To enable these special keycodes, add the following lines to your `rules.mk`:
+```mk
+STENO_ENABLE = yes
+STENO_PROTOCOL = all
+```
+
+If you want to switch protocols programatically, as part of a custom macro for example, don't use `tap_code(QK_STENO_*)`, as `tap_code` only supports [basic keycodes](keycodes_basic). Instead, you should use `steno_set_mode(STENO_MODE_*)`, whose valid arguments are `STENO_MODE_BOLT` and `STENO_MODE_GEMINI`.
+
+The default protocol is Gemini PR but the last protocol used is stored in non-volatile memory so QMK will remember your choice between reboots of your keyboard — assuming that your keyboard features (emulated) EEPROM.
+
+Naturally, this option takes the most amount of firmware space as it needs to compile the code for all the available stenography protocols. In most cases, compiling a single stenography protocol is sufficient.
+
+The default value for `STENO_PROTOCOL` is `all`.
 
 ## Configuring QMK for Steno :id=configuring-qmk-for-steno
 
-Firstly, enable steno in your keymap's Makefile. You may also need disable mousekeys, extra keys, or another USB endpoint to prevent conflicts. The builtin USB stack for some processors only supports a certain number of USB endpoints and the virtual serial port needed for steno fills 3 of them.
+After enabling stenography and optionally selecting a protocol, you may also need disable mouse keys, extra keys, or another USB endpoint to prevent conflicts. The builtin USB stack for some processors only supports a certain number of USB endpoints and the virtual serial port needed for steno fills 3 of them.
 
-```make
-STENO_ENABLE = yes
-MOUSEKEY_ENABLE = no
-```
+!> If you had *explicitly* set `VIRSTER_ENABLE = no`, none of the serial stenography protocols (GeminiPR, TX Bolt) will work properly. You are expected to either set it to `yes`, remove the line from your `rules.mk` or send the steno chords yourself in an alternative way using the [provided interceptable hooks](#interfacing-with-the-code).
 
-In your keymap create a new layer for Plover. You will need to include `keymap_steno.h`. See `planck/keymaps/steno/keymap.c` for an example. Remember to create a key to switch to the layer as well as a key for exiting the layer. If you would like to switch modes on the fly you can use the keycodes `QK_STENO_BOLT` and `QK_STENO_GEMINI`. If you only want to use one of the protocols you may set it up in your initialization function:
+In your keymap, create a new layer for Plover, that you can fill in with the [steno keycodes](#keycode-reference) (you will need to include `keymap_steno.h`, see `planck/keymaps/steno/keymap.c` for an example). Remember to create a key to switch to the layer as well as a key for exiting the layer.
 
-```c
-void eeconfig_init_user() {
-    steno_set_mode(STENO_MODE_GEMINI); // or STENO_MODE_BOLT
-}
-```
+Once you have your keyboard flashed, launch Plover. Click the 'Configure...' button. In the 'Machine' tab, select the Stenotype Machine that corresponds to your desired protocol. Click the 'Configure...' button on this tab and enter the serial port or click 'Scan'. Baud rate is fine at 9600 (although you should be able to set as high as 115200 with no issues). Use the default settings for everything else (Data Bits: 8, Stop Bits: 1, Parity: N, no flow control).
 
-Once you have your keyboard flashed launch Plover. Click the 'Configure...' button. In the 'Machine' tab select the Stenotype Machine that corresponds to your desired protocol. Click the 'Configure...' button on this tab and enter the serial port or click 'Scan'. Baud rate is fine at 9600 (although you should be able to set as high as 115200 with no issues). Use the default settings for everything else (Data Bits: 8, Stop Bits: 1, Parity: N, no flow control).
-
-On the display tab click 'Open stroke display'. With Plover disabled you should be able to hit keys on your keyboard and see them show up in the stroke display window. Use this to make sure you have set up your keymap correctly. You are now ready to steno!
+To test your keymap, you can chord keys on your keyboard and either look at the output of the 'paper tape' (Tools > Paper Tape) or that of the 'layout display' (Tools > Layout Display). If your strokes correctly show up, you are now ready to steno!
 
 ## Learning Stenography :id=learning-stenography
 
@@ -60,7 +121,7 @@ On the display tab click 'Open stroke display'. With Plover disabled you should
 The steno code has three interceptable hooks. If you define these functions, they will be called at certain points in processing; if they return true, processing continues, otherwise it's assumed you handled things.
 
 ```c
-bool send_steno_chord_user(steno_mode_t mode, uint8_t chord[6]);
+bool send_steno_chord_user(steno_mode_t mode, uint8_t chord[MAX_STROKE_SIZE]);
 ```
 
 This function is called when a chord is about to be sent. Mode will be one of `STENO_MODE_BOLT` or `STENO_MODE_GEMINI`. This represents the actual chord that would be sent via whichever protocol. You can modify the chord provided to alter what gets sent. Remember to return true if you want the regular sending process to happen.
@@ -72,15 +133,23 @@ bool process_steno_user(uint16_t keycode, keyrecord_t *record) { return true; }
 This function is called when a keypress has come in, before it is processed. The keycode should be one of `QK_STENO_BOLT`, `QK_STENO_GEMINI`, or one of the `STN_*` key values.
 
 ```c
-bool postprocess_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t mode, uint8_t chord[6], int8_t pressed);
+bool postprocess_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t mode, uint8_t chord[MAX_STROKE_SIZE], int8_t n_pressed_keys);
 ```
 
-This function is called after a key has been processed, but before any decision about whether or not to send a chord. If `IS_PRESSED(record->event)` is false, and `pressed` is 0 or 1, the chord will be sent shortly, but has not yet been sent. This is where to put hooks for things like, say, live displays of steno chords or keys.
+This function is called after a key has been processed, but before any decision about whether or not to send a chord. This is where to put hooks for things like, say, live displays of steno chords or keys.
 
+If `IS_PRESSED(record->event)` is false, and `n_pressed_keys` is 0 or 1, the chord will be sent shortly, but has not yet been sent. This relieves you of the need of keeping track of where a packet ends and another begins.
+
+The `chord` argument contains the packet of the current chord as specified by the protocol in use. This is *NOT* simply a list of chorded steno keys of the form `[STN_E, STN_U, STN_BR, STN_GR]`. Refer to the appropriate protocol section of this document to learn more about the format of the packets in your steno protocol/mode of choice.
+
+The `n_pressed_keys` argument is the number of physical keys actually being held down.
+This is not always equal to the number of bits set to 1 (aka the [Hamming weight](https://en.wikipedia.org/wiki/Hamming_weight)) in `chord` because it is possible to simultaneously press down four keys, then release three of those four keys and then press yet another key while the fourth finger is still holding down its key.
+At the end of this scenario given as an example, `chord` would have five bits set to 1 but
+`n_pressed_keys` would be set to 2 because there are only two keys currently being pressed down.
 
 ## Keycode Reference :id=keycode-reference
 
-As defined in `keymap_steno.h`.
+You must include `keymap_steno.h` to your `keymap.c` with `#include "keymap_steno.h"` before you can use these keycodes
 
 > Note: TX Bolt does not support the full set of keys. The TX Bolt implementation in QMK will map the GeminiPR keys to the nearest TX Bolt key so that one key map will work for both.
 
@@ -115,8 +184,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`|
@@ -124,10 +193,10 @@ As defined in `keymap_steno.h`.
 |`STN_SR`|`STN_SR`| `-S`|
 |`STN_DR`|`STN_DR`| `-D`|
 |`STN_ZR`|`STN_ZR`| `-Z`|
-|`STN_FN`|| (GeminiPR only)|
-|`STN_RES1`||(GeminiPR only)|
-|`STN_RES2`||(GeminiPR only)|
-|`STN_PWR`||(GeminiPR only)|
+|`STN_FN`|| (Function)|
+|`STN_RES1`||(Reset 1)|
+|`STN_RES2`||(Reset 2)|
+|`STN_PWR`||(Power)|
 
 If you do not want to hit two keys with one finger combined keycodes can be used. These are also defined in `keymap_steno.h`, and causes both keys to be reported as pressed or released. To use these keycodes define `STENO_COMBINEDMAP` in your `config.h` file.
 

docs/feature_swap_hands.md

@@ -31,3 +31,16 @@ Note that the array indices are reversed same as the matrix and the values are o
 |`SH_OS`    |One shot swap hands: toggles while pressed or until next key press.      |
 
 `SH_TT` swap-hands tap-toggle key is similar to [layer tap-toggle](feature_layers.md?id=switching-and-toggling-layers). Tapping repeatedly (5 taps by default) will toggle swap-hands on or off, like `SH_TG`. Tap-toggle count can be changed by defining a value for `TAPPING_TOGGLE`.
+
+## Encoder Mapping
+
+When using an encoder mapping, it's also able to handle swapping encoders between sides, too.
+
+Encoder indexes are defined as left-to-right, and the extent of the array needs to match the number of encoders on the keyboard.
+
+As an example, if a split keyboard has a single encoder per side, you can swap the order by using the following code in your keymap:
+```c
+#if defined(SWAP_HANDS_ENABLE) && defined(ENCODER_MAP_ENABLE)
+const uint8_t PROGMEM encoder_hand_swap_config[NUM_ENCODERS] = { 1, 0 };
+#endif
+```

docs/feature_tap_dance.md

@@ -14,55 +14,48 @@ Optionally, you might want to set a custom `TAPPING_TERM` time by adding somethi
 
 ```c
 #define TAPPING_TERM 175
+#define TAPPING_TERM_PER_KEY
 ```
 
-The `TAPPING_TERM` time is the maximum time allowed between taps of your Tap Dance key, and is measured in milliseconds. For example, if you used the above `#define` statement and set up a Tap Dance key that sends `Space` on single-tap and `Enter` on double-tap, then this key will send `ENT` only if you tap this key twice in less than 175ms. If you tap the key, wait more than 175ms, and tap the key again you'll end up sending `SPC SPC` instead.
+The `TAPPING_TERM` time is the maximum time allowed between taps of your Tap Dance key, and is measured in milliseconds. For example, if you used the above `#define` statement and set up a Tap Dance key that sends `Space` on single-tap and `Enter` on double-tap, then this key will send `ENT` only if you tap this key twice in less than 175ms. If you tap the key, wait more than 175ms, and tap the key again you'll end up sending `SPC SPC` instead. The `TAPPING_TERM_PER_KEY` definition is only needed if you control the tapping term through a [custom `get_tapping_term` function](tap_hold.md#tapping_term), which may be needed because `TAPPING_TERM` affects not just tap-dance keys.
 
-Next, you will want to define some tap-dance keys, which is easiest to do with the `TD()` macro, that takes a number which will later be used as an index into the `tap_dance_actions` array.
+Next, you will want to define some tap-dance keys, which is easiest to do with the `TD()` macro. That macro takes a number which will later be used as an index into the `tap_dance_actions` array and turns it into a tap-dance keycode.
 
 After this, you'll want to use the `tap_dance_actions` array to specify what actions shall be taken when a tap-dance key is in action. Currently, there are five possible options:
 
 * `ACTION_TAP_DANCE_DOUBLE(kc1, kc2)`: Sends the `kc1` keycode when tapped once, `kc2` otherwise. When the key is held, the appropriate keycode is registered: `kc1` when pressed and held, `kc2` when tapped once, then pressed and held.
 * `ACTION_TAP_DANCE_LAYER_MOVE(kc, layer)`: Sends the `kc` keycode when tapped once, or moves to `layer`. (this functions like the `TO` layer keycode).
-    * This is the same as `ACTION_TAP_DANCE_DUAL_ROLE`, but renamed to something that is clearer about its functionality.  Both names will work.
 * `ACTION_TAP_DANCE_LAYER_TOGGLE(kc, layer)`: Sends the `kc` keycode when tapped once, or toggles the state of `layer`. (this functions like the `TG` layer keycode).
 * `ACTION_TAP_DANCE_FN(fn)`: Calls the specified function - defined in the user keymap - with the final tap count of the tap dance action.
 * `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn)`: Calls the first specified function - defined in the user keymap - on every tap, the second function when the dance action finishes (like the previous option), and the last function when the tap dance action resets.
-* ~~`ACTION_TAP_DANCE_FN_ADVANCED_TIME(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn, tap_specific_tapping_term)`~~: This functions identically to the `ACTION_TAP_DANCE_FN_ADVANCED` function, but uses a custom tapping term for it, instead of the predefined `TAPPING_TERM`.
-    * This is deprecated in favor of the Per Key Tapping Term functionality, as outlined [here](tap_hold.md#tapping-term). You'd want to check for the specific `TD()` macro that you want to use (such as `TD(TD_ESC_CAPS)`) instead of using this specific Tap Dance function.
 
 
 The first option is enough for a lot of cases, that just want dual roles. For example, `ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT)` will result in `Space` being sent on single-tap, `Enter` otherwise. 
 
 !> Keep in mind that only [basic keycodes](keycodes_basic.md) are supported here. Custom keycodes are not supported.
 
-Similar to the first option, the second option is good for simple layer-switching cases.
+Similar to the first option, the second and third option are good for simple layer-switching cases.
 
-For more complicated cases, use the third or fourth options (examples of each are listed below).
-
-Finally, the fifth option is particularly useful if your non-Tap-Dance keys start behaving weirdly after adding the code for your Tap Dance keys. The likely problem is that you changed the `TAPPING_TERM` time to make your Tap Dance keys easier for you to use, and that this has changed the way your other keys handle interrupts.
+For more complicated cases, like blink the LEDs, fiddle with the backlighting, and so on, use the fourth or fifth option. Examples of each are listed below.
 
 ## Implementation Details :id=implementation
 
 Well, that's the bulk of it! You should now be able to work through the examples below, and to develop your own Tap Dance functionality. But if you want a deeper understanding of what's going on behind the scenes, then read on for the explanation of how it all works!
 
-The main entry point is `process_tap_dance()`, called from `process_record_quantum()`, which is run for every keypress, and our handler gets to run early. This function checks whether the key pressed is a tap-dance key. If it is not, and a tap-dance was in action, we handle that first, and enqueue the newly pressed key. If it is a tap-dance key, then we check if it is the same as the already active one (if there's one active, that is). If it is not, we fire off the old one first, then register the new one. If it was the same, we increment the counter and reset the timer.
+Let's go over the three functions mentioned in `ACTION_TAP_DANCE_FN_ADVANCED` in a little more detail. They all receive the same too arguments: a pointer to a structure that holds all dance related state information, and a pointer to a use case specific state variable. The three functions differ in when they are called. The first, `on_each_tap_fn()`, is called every time the tap dance key is *pressed*. Before it is called, the counter is incremented and the timer is reset. The second function, `on_dance_finished_fn()`, is called when the tap dance is interrupted or ends because `TAPPING_TERM` milliseconds have passed since the last tap. When the `finished` field of the dance state structure is set to `true`, the `on_dance_finished_fn()` is skipped. After `on_dance_finished_fn()` was called or would have been called, but no sooner than when the tap dance key is *released*, `on_dance_reset_fn()` is called. It is possible to end a tap dance immediately, skipping `on_dance_finished_fn()`, but not `on_dance_reset_fn`, by calling `reset_tap_dance(state)`.
+
+To accomplish this logic, the tap dance mechanics use three entry points. The main entry point is `process_tap_dance()`, called from `process_record_quantum()` *after* `process_record_kb()` and `process_record_user()`. This function is responsible for calling `on_each_tap_fn()` and `on_dance_reset_fn()`. In order to handle interruptions of a tap dance, another entry point, `preprocess_tap_dance()` is run right at the beginning of `process_record_quantum()`. This function checks whether the key pressed is a tap-dance key. If it is not, and a tap-dance was in action, we handle that first, and enqueue the newly pressed key. If it is a tap-dance key, then we check if it is the same as the already active one (if there's one active, that is). If it is not, we fire off the old one first, then register the new one. Finally, `tap_dance_task()` periodically checks whether `TAPPING_TERM` has passed since the last key press and finishes a tap dance if that is the case.
 
 This means that you have `TAPPING_TERM` time to tap the key again; you do not have to input all the taps within a single `TAPPING_TERM` timeframe. This allows for longer tap counts, with minimal impact on responsiveness.
 
-Our next stop is `tap_dance_task()`. This handles the timeout of tap-dance keys.
-
-For the sake of flexibility, tap-dance actions can be either a pair of keycodes, or a user function. The latter allows one to handle higher tap counts, or do extra things, like blink the LEDs, fiddle with the backlighting, and so on. This is accomplished by using an union, and some clever macros.
-
 ## Examples :id=examples
 
-### Simple Example :id=simple-example
+### Simple Example: Send `ESC` on Single Tap, `CAPS_LOCK` on Double Tap :id=simple-example
 
 Here's a simple example for a single definition:
 
 1. In your `rules.mk`, add `TAP_DANCE_ENABLE = yes`
-2. In your `config.h` (which you can copy from `qmk_firmware/keyboards/planck/config.h` to your keymap directory), add `#define TAPPING_TERM 200`
-3. In your `keymap.c` file, define the variables and definitions, then add to your keymap:
+2. In your `keymap.c` file, define the variables and definitions, then add to your keymap:
 
 ```c
 // Tap Dance declarations
@@ -92,40 +85,15 @@ All the enums used in the examples are declared like this:
 ```c
 // Enums defined for all examples:
 enum {
-    CT_SE,
-    CT_CLN,
+    TD_ESC_CAPS,
     CT_EGG,
     CT_FLSH,
-    X_TAP_DANCE
+    CT_CLN,
+    X_CTL,
 };
 ```
 
-#### Example 1: Send `:` on Single Tap, `;` on Double Tap :id=example-1
-
-```c
-void dance_cln_finished(qk_tap_dance_state_t *state, void *user_data) {
-    if (state->count == 1) {
-        register_code16(KC_COLN);
-    } else {
-        register_code(KC_SCLN);
-    }
-}
-
-void dance_cln_reset(qk_tap_dance_state_t *state, void *user_data) {
-    if (state->count == 1) {
-        unregister_code16(KC_COLN);
-    } else {
-        unregister_code(KC_SCLN);
-    }
-}
-
-// All tap dance functions would go here. Only showing this one.
-qk_tap_dance_action_t tap_dance_actions[] = {
-    [CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, dance_cln_finished, dance_cln_reset),
-};
-```
-
-#### Example 2: Send "Safety Dance!" After 100 Taps :id=example-2
+#### Example 1: Send "Safety Dance!" After 100 Taps :id=example-1
 
 ```c
 void dance_egg(qk_tap_dance_state_t *state, void *user_data) {
@@ -140,7 +108,7 @@ qk_tap_dance_action_t tap_dance_actions[] = {
 };
 ```
 
-#### Example 3: Turn LED Lights On Then Off, One at a Time :id=example-3
+#### Example 2: Turn LED Lights On Then Off, One at a Time :id=example-2
 
 ```c
 // On each tap, light up one LED, from right to left
@@ -181,15 +149,74 @@ void dance_flsh_reset(qk_tap_dance_state_t *state, void *user_data) {
     ergodox_right_led_3_off();
 }
 
-// All tap dances now put together. Example 3 is "CT_FLASH"
+// All tap dances now put together. Example 2 is "CT_FLSH"
 qk_tap_dance_action_t tap_dance_actions[] = {
-    [CT_SE] = ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT),
-    [CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, dance_cln_finished, dance_cln_reset),
+    [TD_ESC_CAPS] = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS),
     [CT_EGG] = ACTION_TAP_DANCE_FN(dance_egg),
     [CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED(dance_flsh_each, dance_flsh_finished, dance_flsh_reset)
 };
 ```
 
+#### Example 3: Send `:` on Tap, `;` on Hold :id=example-3
+
+With a little effort, powerful tap-hold configurations can be implemented as tap dances. To emit taps as early as possible, we need to act on releases of the tap dance key. There is no callback for this in the tap dance framework, so we use `process_record_user()`.
+
+```c
+typedef struct {
+    uint16_t tap;
+    uint16_t hold;
+    uint16_t held;
+} tap_dance_tap_hold_t;
+
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+    qk_tap_dance_action_t *action;
+
+    switch (keycode) {
+        case TD(CT_CLN):  // list all tap dance keycodes with tap-hold configurations
+            action = &tap_dance_actions[TD_INDEX(keycode)];
+            if (!record->event.pressed && action->state.count && !action->state.finished) {
+                tap_dance_tap_hold_t *tap_hold = (tap_dance_tap_hold_t *)action->user_data;
+                tap_code16(tap_hold->tap);
+            }
+    }
+    return true;
+}
+
+void tap_dance_tap_hold_finished(qk_tap_dance_state_t *state, void *user_data) {
+    tap_dance_tap_hold_t *tap_hold = (tap_dance_tap_hold_t *)user_data;
+
+    if (state->pressed) {
+        if (state->count == 1
+#ifndef PERMISSIVE_HOLD
+            && !state->interrupted
+#endif
+        ) {
+            register_code16(tap_hold->hold);
+            tap_hold->held = tap_hold->hold;
+        } else {
+            register_code16(tap_hold->tap);
+            tap_hold->held = tap_hold->tap;
+        }
+    }
+}
+
+void tap_dance_tap_hold_reset(qk_tap_dance_state_t *state, void *user_data) {
+    tap_dance_tap_hold_t *tap_hold = (tap_dance_tap_hold_t *)user_data;
+
+    if (tap_hold->held) {
+        unregister_code16(tap_hold->held);
+        tap_hold->held = 0;
+    }
+}
+
+#define ACTION_TAP_DANCE_TAP_HOLD(tap, hold) \
+    { .fn = {NULL, tap_dance_tap_hold_finished, tap_dance_tap_hold_reset}, .user_data = (void *)&((tap_dance_tap_hold_t){tap, hold, 0}), }
+
+qk_tap_dance_action_t tap_dance_actions[] = {
+    [CT_CLN] = ACTION_TAP_DANCE_TAP_HOLD(KC_COLN, KC_SCLN),
+};
+```
+
 #### Example 4: 'Quad Function Tap-Dance' :id=example-4
 
 By [DanielGGordon](https://github.com/danielggordon)
@@ -329,7 +356,7 @@ And then simply use `TD(X_CTL)` anywhere in your keymap.
 
 If you want to implement this in your userspace, then you may want to check out how [DanielGGordon](https://github.com/qmk/qmk_firmware/tree/master/users/gordon) has implemented this in their userspace.
 
-> In this configuration "hold" takes place **after** tap dance timeout (see `ACTION_TAP_DANCE_FN_ADVANCED_TIME`). To achieve instant hold, remove `state->interrupted` checks in conditions. As a result you may use comfortable longer tapping periods to have more time for taps and not to wait too long for holds (try starting with doubled `TAPPING_TERM`).
+> In this configuration "hold" takes place **after** tap dance timeout. To achieve instant hold, remove `state->interrupted` checks in conditions. As a result you may use comfortable longer tapping periods to have more time for taps and not to wait too long for holds (try starting with doubled `TAPPING_TERM`).
 
 #### Example 5: Using tap dance for advanced mod-tap and layer-tap keys :id=example-5
 
@@ -511,8 +538,18 @@ void ql_reset(qk_tap_dance_state_t *state, void *user_data) {
 
 // Associate our tap dance key with its functionality
 qk_tap_dance_action_t tap_dance_actions[] = {
-    [QUOT_LAYR] = ACTION_TAP_DANCE_FN_ADVANCED_TIME(NULL, ql_finished, ql_reset, 275)
+    [QUOT_LAYR] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, ql_finished, ql_reset)
 };
+
+// Set a long-ish tapping term for tap-dance keys
+uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) {
+    switch (keycode) {
+        case QK_TAP_DANCE ... QK_TAP_DANCE_MAX:
+            return 275;
+        default:
+            return TAPPING_TERM;
+    }
+}
 ```
 
 The above code is similar to that used in previous examples. The one point to note is that we need to be able to check which layers are active at any time so we can toggle them if needed. To do this we use the `layer_state_is(layer)` function which returns `true` if the given `layer` is active.
@@ -521,6 +558,6 @@ The use of `cur_dance()` and `ql_tap_state` mirrors the above examples.
 
 The `case: TD_SINGLE_TAP` in `ql_finished` is similar to the above examples. The `TD_SINGLE_HOLD` case works in conjunction with `ql_reset()` to switch to `_MY_LAYER` while the tap dance key is held, and to switch away from `_MY_LAYER` when the key is released. This mirrors the use of `MO(_MY_LAYER)`. The `TD_DOUBLE_TAP` case works by checking whether `_MY_LAYER` is the active layer, and toggling it on or off accordingly. This mirrors the use of `TG(_MY_LAYER)`.
 
-`tap_dance_actions[]` works similar to the above examples. Note that I used `ACTION_TAP_DANCE_FN_ADVANCED_TIME()` instead of `ACTION_TAP_DANCE_FN_ADVANCED()`. This is because I like my `TAPPING_TERM` to be short (\~175ms) for my non-tap-dance keys but find that this is too quick for me to reliably complete tap dance actions - thus the increased time of 275ms here.
+`tap_dance_actions[]` works similar to the above examples. Note that, additionally, I set a longer tapping term for the tap dance keys. This is because I like my `TAPPING_TERM` to be short (\~175ms) for my non-tap-dance keys but find that this is too quick for me to reliably complete tap dance actions - thus the increased time of 275ms here. In order for the per-key tapping terms to take effect, `TAPPING_TERM_PER_KEY` must be defined in your `config.h`.
 
 Finally, to get this tap dance key working, be sure to include `TD(QUOT_LAYR)` in your `keymaps[]`.

docs/feature_terminal.md

@@ -1,107 +0,0 @@
-# Terminal
-
-> This feature is currently *huge*, and should probably only be put on boards with a lot of memory, or for fun.
-
-The terminal feature is a command-line-like interface designed to communicate through a text editor with keystrokes. It's beneficial to turn off auto-indent features in your editor.
-
-To enable, stick this in your `rules.mk` or `Makefile`:
-
-    TERMINAL_ENABLE = yes
-
-And use the `TERM_ON` and `TERM_OFF` keycodes to turn it on or off.
-
-When enabled, a `> ` prompt will appear, where you'll be able to type, backspace (a bell will ding if you reach the beginning and audio is enabled), and hit enter to send the command. Arrow keys are currently disabled so it doesn't get confused. Moving your cursor around with the mouse is discouraged.
-
-`#define TERMINAL_HELP` enables some other output helpers that aren't really needed with this page.
-
-Pressing "up" and "down" will allow you to cycle through the past 5 commands entered.
-
-## Future Ideas
-
-* Keyboard/user-extensible commands
-* Smaller footprint
-* Arrow key support
-* Command history - Done
-* SD card support
-* LCD support for buffer display
-* Keycode -> name string LUT
-* Layer status
-* *Analog/digital port read/write*
-* RGB mode stuff
-* Macro definitions
-* EEPROM read/write
-* Audio control
-
-## Current Commands
-
-### `about`
-
-Prints out the current version of QMK with a build date:
-
-```
-> about
-QMK Firmware
-  v0.5.115-7-g80ed73-dirty
-  Built: 2017-08-29-20:24:44
-```
-
-
-### `print-buffer`
-
-Outputs the last 5 commands entered
-
-```
-> print-buffer
-0. print-buffer
-1. help
-2. about
-3. keymap 0
-4. help
-5. flush-buffer
-```
-
-### `flush-buffer`
-
-Clears command buffer
-```
-> flush-buffer
-Buffer cleared!
-```
-
-
-### `help`
-
-
-Prints out the available commands:
-
-```
-> help
-commands available:
-  about help keycode keymap exit print-buffer flush-buffer
-```
-
-### `keycode <layer> <row> <col>`
-
-Prints out the keycode value of a certain layer, row, and column:
-
-```
-> keycode 0 1 0
-0x29 (41)
-```
-
-### `keymap <layer>`
-
-Prints out the entire keymap for a certain layer
-
-```
-> keymap 0
-0x002b, 0x0014, 0x001a, 0x0008, 0x0015, 0x0017, 0x001c, 0x0018, 0x000c, 0x0012, 0x0013, 0x002a,
-0x0029, 0x0004, 0x0016, 0x0007, 0x0009, 0x000a, 0x000b, 0x000d, 0x000e, 0x000f, 0x0033, 0x0034,
-0x00e1, 0x001d, 0x001b, 0x0006, 0x0019, 0x0005, 0x0011, 0x0010, 0x0036, 0x0037, 0x0038, 0x0028,
-0x5cd6, 0x00e0, 0x00e2, 0x00e3, 0x5cd4, 0x002c, 0x002c, 0x5cd5, 0x0050, 0x0051, 0x0052, 0x004f,
->
-```
-
-### `exit`
-
-Exits the terminal - same as `TERM_OFF`.

docs/feature_unicode.md

@@ -230,17 +230,6 @@ send_unicode_string("(ノಠ痊ಠ)ノ彡┻━┻");
 
 Example uses include sending Unicode strings when a key is pressed, as described in [Macros](feature_macros.md).
 
-### `send_unicode_hex_string()` (Deprecated)
-
-Similar to `send_unicode_string()`, but the characters are represented by their Unicode code points, written in hexadecimal and separated by spaces. For example, the table flip above would be achieved with:
-
-```c
-send_unicode_hex_string("0028 30CE 0CA0 75CA 0CA0 0029 30CE 5F61 253B 2501 253B");
-```
-
-An easy way to convert your Unicode string to this format is to use [this site](https://r12a.github.io/app-conversion/) and take the result in the "Hex/UTF-32" section.
-
-
 ## Additional Language Support
 
 In `quantum/keymap_extras`, you'll see various language files — these work the same way as the ones for alternative layouts such as Colemak or BÉPO. When you include one of these language headers, you gain access to keycodes specific to that language / national layout. Such keycodes are defined by a 2-letter country/language code, followed by an underscore and a 4-letter abbreviation of the character to which the key corresponds. For example, including `keymap_french.h` and using `FR_UGRV` in your keymap will output `ù` when typed on a system with a native French AZERTY layout.

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.
 
@@ -347,3 +347,57 @@ Flashing sequence:
 2. Wait for the OS to detect the device
 3. Copy the .uf2 file to the new USB disk
 4. Wait for the keyboard to become available
+
+or
+
+CLI Flashing sequence:
+
+1. Enter the bootloader using any of the following methods:
+    * Tap the `RESET` keycode
+    * Double-tap the `nRST` button on the PCB.
+2. Wait for the OS to detect the device
+3. Flash via QMK CLI eg. `qmk flash --keyboard handwired/onekey/blackpill_f411_tinyuf2 --keymap default`
+4. Wait for the keyboard to become available
+
+### `make` Targets
+
+* `:uf2-split-left` and `:uf2-split-right`: Flashes the firmware but also sets the handedness setting in EEPROM by generating a side specific firmware.
+
+## Raspberry Pi RP2040 UF2
+
+The `rules.mk` setting for this bootloader is `rp2040`, and can be specified at the keymap or user level.
+
+To ensure compatibility with the rp2040 bootloader, make sure this block is present in your `rules.mk`:
+
+```make
+# Bootloader selection
+BOOTLOADER = rp2040
+```
+
+Compatible flashers:
+
+* Any application able to copy a file from one place to another, such as _macOS Finder_ or _Windows Explorer_.
+
+Flashing sequence:
+
+1. Enter the bootloader using any of the following methods:
+    * Tap the `QK_BOOTLOADER` keycode
+    * Hold the `BOOTSEL` button on the PCB while plugin in the usb cable.
+    * Double-tap the `RESET` button on the PCB<sup>1</sup>.
+2. Wait for the OS to detect the device
+3. Copy the .uf2 file to the new USB disk
+4. Wait for the keyboard to become available
+
+or
+
+CLI Flashing sequence:
+
+1. Enter the bootloader using any of the following methods:
+    * Tap the `QK_BOOTLOADER` keycode
+    * Hold the `BOOTSEL` button on the PCB while plugin in the usb cable.
+    * Double-tap the `RESET` button on the PCB<sup>1</sup>.
+2. Wait for the OS to detect the device
+3. Flash via QMK CLI eg. `qmk flash --keyboard handwired/onekey/rpi_pico --keymap default`
+4. Wait for the keyboard to become available
+
+<sup>1</sup>: This works only if QMK was compiled with `RP2040_BOOTLOADER_DOUBLE_TAP_RESET` defined.

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>
@@ -128,9 +128,11 @@
   <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
   <script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
   <script src="//unpkg.com/docsify/lib/plugins/emoji.min.js"></script>
+  <script src="//unpkg.com/mermaid/dist/mermaid.js"></script>
+  <script src="//unpkg.com/docsify-mermaid@latest/dist/docsify-mermaid.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>
@@ -143,5 +145,6 @@
       navigator.serviceWorker.register('sw.js')
     }
   </script>
+  <script>mermaid.initialize({ startOnLoad: true });</script>
 </body>
 </html>