darkkirb/qmk_firmware
1
0
Fork 0
forked from mirrors/qmk_firmware
Code Issues Pull requests Projects Releases Packages Wiki Activity

merge from master

Browse source
This commit is contained in:
Jack Humbert 2021-02-07 21:01:30 -05:00
commit 3996250d81
11279 changed files with 499671 additions and 99678 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
.github/PULL_REQUEST_TEMPLATE.md vendored
View file

@ -26,7 +26,8 @@
<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
- [ ] My code follows the code style of this project.
- [ ] My code follows the code style of this project: [**C**](https://docs.qmk.fm/#/coding_conventions_c), [**Python**](https://docs.qmk.fm/#/coding_conventions_python)
- [ ] I have read the [**PR Checklist** document](https://docs.qmk.fm/#/pr_checklist) and have made the appropriate changes.
- [ ] My change requires a change to the documentation.
- [ ] I have updated the documentation accordingly.
- [ ] I have read the [**CONTRIBUTING** document](https://docs.qmk.fm/#/contributing).

42
.github/labeler.yml vendored Normal file
View file

@ -0,0 +1,42 @@
core:
- quantum/**/*
- tmk_core/**/*
- drivers/**/*
- tests/**/*
- util/**/*
- platforms/**/*
- Makefile
- '*.mk'
dependencies:
- any:
- 'lib/**/*'
- '!lib/python/**/*'
keyboard:
- any:
- 'keyboards/**/*'
- '!keyboards/**/keymaps/**/*'
keymap:
- users/**/*
- layouts/**/*
- keyboards/**/keymaps/**/*
via:
- keyboards/**/keymaps/via/*
cli:
- bin/qmk
- requirements.txt
- lib/python/**/*
python:
- '**/*.py'
documentation:
- docs/**/*
translation:
- docs/fr-fr/**/*
- docs/es/**/*
- docs/ja/**/*
- docs/he-il/**/*
- docs/pt-br/**/*
- docs/zh-cn/**/*
- docs/de/**/*
- docs/ru-ru/**/*
CI:
- .github/**/*

42
.github/workflows/api.yml vendored Normal file
View file

@ -0,0 +1,42 @@
name: Update API Data
on:
push:
branches:
- master
paths:
- 'keyboards/**'
- 'layouts/community/**'
jobs:
api_data:
runs-on: ubuntu-latest
container: qmkfm/base_container
# protect against those who develop with their fork on master
if: github.repository == 'qmk/qmk_firmware'
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 1
persist-credentials: false
- name: Generate API Data
run: qmk generate-api
- name: Install rsync
run: |
apt-get update && apt-get install -y rsync
- name: Upload API Data
uses: JamesIves/github-pages-deploy-action@3.7.1
with:
ACCESS_TOKEN: ${{ secrets.API_TOKEN_GITHUB }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
BRANCH: main
FOLDER: api_data/v1
CLEAN: true
GIT_CONFIG_EMAIL: hello@qmk.fm
REPOSITORY_NAME: qmk/qmk_keyboards
TARGET_FOLDER: v1

33
.github/workflows/auto_tag.yaml vendored Normal file
View file

@ -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@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'

42
.github/workflows/develop_api.yml vendored Normal file
View file

@ -0,0 +1,42 @@
name: Update Develop API Data
on:
push:
branches:
- develop
paths:
- 'keyboards/**'
- 'layouts/community/**'
jobs:
api_data:
runs-on: ubuntu-latest
container: qmkfm/base_container
# protect against those who work in their fork on develop
if: github.repository == 'qmk/qmk_firmware'
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 1
persist-credentials: false
- name: Generate API Data
run: qmk generate-api
- name: Install rsync
run: |
apt-get update && apt-get install -y rsync
- name: Upload API Data
uses: JamesIves/github-pages-deploy-action@3.7.1
with:
ACCESS_TOKEN: ${{ secrets.API_TOKEN_GITHUB }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
BRANCH: main
FOLDER: api_data/v1
CLEAN: true
GIT_CONFIG_EMAIL: hello@qmk.fm
REPOSITORY_NAME: qmk/qmk_keyboards_devel
TARGET_FOLDER: v1

37
.github/workflows/develop_update.yml vendored Normal file
View file

@ -0,0 +1,37 @@
name: Update develop after master merge
on:
push:
branches:
- master
jobs:
develop_update:
runs-on: ubuntu-latest
if: github.repository == 'qmk/qmk_firmware'
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 0
- name: Checkout develop
run: |
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"
git merge origin/master
git push origin develop

43
.github/workflows/docs.yml vendored Normal file
View file

@ -0,0 +1,43 @@
name: Generate Docs
on:
push:
branches:
- master
paths:
- 'tmk_core/**'
- 'quantum/**'
- 'platforms/**'
- 'docs/**'
- '.github/workflows/docs.yml'
jobs:
generate:
runs-on: ubuntu-latest
container: qmkfm/base_container
# protect against those who develop with their fork on master
if: github.repository == 'qmk/qmk_firmware'
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 1
- name: Install dependencies
run: |
apt-get update && apt-get install -y rsync nodejs npm doxygen
npm install -g moxygen
- name: Build docs
run: |
qmk --verbose generate-docs
- name: Deploy
uses: JamesIves/github-pages-deploy-action@3.7.1
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
BASE_BRANCH: master
BRANCH: gh-pages
FOLDER: .build/docs
GIT_CONFIG_EMAIL: hello@qmk.fm

43
.github/workflows/format.yaml vendored Normal file
View file

@ -0,0 +1,43 @@
name: Format Codebase
on:
push:
branches:
- master
jobs:
format:
runs-on: ubuntu-latest
container: qmkfm/base_container
# protect against those who develop with their fork on master
if: github.repository == 'qmk/qmk_firmware'
steps:
- uses: actions/checkout@v2
with:
token: ${{ secrets.API_TOKEN_GITHUB }}
- name: Install dependencies
run: |
apt-get update && apt-get install -y dos2unix
- name: Format files
run: |
bin/qmk cformat -a
bin/qmk pyformat
bin/qmk fileformat
- 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
with:
delete-branch: true
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'

14
.github/workflows/labeler.yml vendored Normal file
View file

@ -0,0 +1,14 @@
name: "Pull Request Labeler"
on:
pull_request_target:
types: [opened, synchronize, reopened, ready_for_review, locked]
jobs:
triage:
runs-on: ubuntu-latest
steps:
- uses: actions/labeler@main
with:
repo-token: "${{ secrets.GITHUB_TOKEN }}"
configuration-path: '.github/labeler.yml'

55
.github/workflows/lint.yml vendored Normal file
View file

@ -0,0 +1,55 @@
name: PR Lint keyboards
on:
pull_request:
paths:
- 'keyboards/**'
jobs:
lint:
runs-on: ubuntu-latest
container: qmkfm/base_container
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 0
- uses: trilom/file-changes-action@v1.2.4
id: file_changes
with:
output: '\n'
- name: Print info
run: |
git rev-parse --short HEAD
echo ${{ github.event.pull_request.base.sha }}
echo '${{ steps.file_changes.outputs.files}}'
- name: Run qmk lint
shell: 'bash {0}'
run: |
QMK_CHANGES=$(echo -e '${{ steps.file_changes.outputs.files}}')
QMK_KEYBOARDS=$(qmk list-keyboards)
exit_code=0
for KB in $QMK_KEYBOARDS; do
KEYBOARD_CHANGES=$(echo "$QMK_CHANGES" | grep -E '^(keyboards/'${KB}'/)')
if [[ -z "$KEYBOARD_CHANGES" ]]; then
# skip as no changes for this keyboard
continue
fi
KEYMAP_ONLY=$(echo "$KEYBOARD_CHANGES" | grep -cv /keymaps/)
if [[ $KEYMAP_ONLY -gt 0 ]]; then
echo "linting ${KB}"
qmk lint --keyboard ${KB} && qmk info -l --keyboard ${KB}
exit_code=$(($exit_code + $?))
fi
done
if [[ $exit_code -gt 255 ]]; then
exit 255
fi
exit $exit_code

4
.gitignore vendored
View file

@ -16,6 +16,7 @@
*.swp
tags
*~
api_data/v1
build/
.build/
*.bak
@ -73,3 +74,6 @@ __pycache__
# prerequisites for updating ChibiOS
/util/fmpp*
# Allow to exist but don't include it in the repo
user_song_list.h

8
.gitmodules vendored
View file

@ -12,7 +12,13 @@
branch = master
[submodule "lib/googletest"]
path = lib/googletest
url = https://github.com/google/googletest
url = https://github.com/qmk/googletest
[submodule "lib/lufa"]
path = lib/lufa
url = https://github.com/qmk/lufa
[submodule "lib/vusb"]
path = lib/vusb
url = https://github.com/qmk/v-usb
[submodule "lib/printf"]
path = lib/printf
url = https://github.com/qmk/printf

7
.travis.yml
View file

@ -18,20 +18,15 @@ addons:
- ubuntu-toolchain-r-test
- llvm-toolchain-trusty-7
packages:
- pandoc
- diffutils
- dos2unix
- doxygen
- clang-format-7
- libstdc++-7-dev
install:
- npm install -g moxygen
script:
- git fetch --depth=50 origin $TRAVIS_BRANCH:$TRAVIS_BRANCH
- git rev-parse --short HEAD
- git diff --name-only HEAD $TRAVIS_BRANCH
- bash util/travis_test.sh
- bash util/travis_build.sh
- bash util/travis_docs.sh
after_script:
bash util/travis_compiled_push.sh
notifications:

3
.vscode/settings.json vendored
View file

@ -16,7 +16,8 @@
"*.hpp": "cpp",
"xstddef": "c",
"type_traits": "c",
"utility": "c"
"utility": "c",
"ranges": "c"
},
"[markdown]": {
"editor.trimAutoWhitespace": false,

144
Makefile
View file

@ -29,6 +29,9 @@ $(info QMK Firmware $(QMK_VERSION))
endif
endif
# avoid 'Entering|Leaving directory' messages
MAKEFLAGS += --no-print-directory
ON_ERROR := error_occurred=1
BREAK_ON_ERRORS = no
@ -65,71 +68,15 @@ PATH_ELEMENTS := $(subst /, ,$(STARTING_DIR))
# Initialize the path elements list for further processing
$(eval $(call NEXT_PATH_ELEMENT))
# This function sets the KEYBOARD; KEYMAP and SUBPROJECT to the correct
# variables depending on which directory you stand in.
# It's really a very simple if else chain, if you squint enough,
# but the makefile syntax makes it very verbose.
# If we are in a subfolder of keyboards
#
# *** No longer needed **
#
# ifeq ($(CURRENT_PATH_ELEMENT),keyboards)
# $(eval $(call NEXT_PATH_ELEMENT))
# KEYBOARD := $(CURRENT_PATH_ELEMENT)
# $(eval $(call NEXT_PATH_ELEMENT))
# # If we are in a subfolder of keymaps, or in other words in a keymap
# # folder
# ifeq ($(CURRENT_PATH_ELEMENT),keymaps)
# $(eval $(call NEXT_PATH_ELEMENT))
# KEYMAP := $(CURRENT_PATH_ELEMENT)
# # else if we are not in the keyboard folder itself
# else ifneq ($(CURRENT_PATH_ELEMENT),)
# # the we can assume it's a subproject, as no other folders
# # should have make files in them
# SUBPROJECT := $(CURRENT_PATH_ELEMENT)
# $(eval $(call NEXT_PATH_ELEMENT))
# # if we are inside a keymap folder of a subproject
# ifeq ($(CURRENT_PATH_ELEMENT),keymaps)
# $(eval $(call NEXT_PATH_ELEMENT))
# KEYMAP := $(CURRENT_PATH_ELEMENT)
# endif
# endif
# endif
define GET_KEYBOARDS
ifndef ALT_GET_KEYBOARDS
All_RULES_MK := $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/rules.mk))
All_RULES_MK += $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/*/rules.mk))
All_RULES_MK += $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/*/*/rules.mk))
All_RULES_MK += $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/*/*/*/rules.mk))
KEYMAPS_MK := $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/keymaps/*/rules.mk))
KEYMAPS_MK += $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/*/keymaps/*/rules.mk))
KEYMAPS_MK += $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/*/*/keymaps/*/rules.mk))
KEYMAPS_MK += $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/*/*/*/keymaps/*/rules.mk))
KEYBOARDS := $$(sort $$(filter-out $$(KEYMAPS_MK), $$(All_RULES_MK)))
else
KEYBOARDS := $(shell find keyboards/ -type f -iname "rules.mk" | grep -v keymaps | sed 's!keyboards/\(.*\)/rules.mk!\1!' | sort | uniq)
endif
endef
$(eval $(call GET_KEYBOARDS))
# Only consider folders with makefiles, to prevent errors in case there are extra folders
#KEYBOARDS += $(patsubst $(ROOD_DIR)/keyboards/%/rules.mk,%,$(wildcard $(ROOT_DIR)/keyboards/*/*/rules.mk))
# Phony targets to enable a few simple make commands outside the main processing below.
.PHONY: list-keyboards
list-keyboards:
echo $(KEYBOARDS)
define PRINT_KEYBOARD
$(info $(PRINTING_KEYBOARD))
endef
util/list_keyboards.sh | sort -u | tr '\n' ' '
.PHONY: generate-keyboards-file
generate-keyboards-file:
$(foreach PRINTING_KEYBOARD,$(KEYBOARDS),$(eval $(call PRINT_KEYBOARD)))
util/list_keyboards.sh | sort -u
.PHONY: clean
clean:
@ -155,8 +102,6 @@ endif
# Uncomment these for debugging
# $(info Keyboard: $(KEYBOARD))
# $(info Keymap: $(KEYMAP))
# $(info Subproject: $(SUBPROJECT))
# $(info Keyboards: $(KEYBOARDS))
# Set the default goal depending on where we are running make from
@ -214,7 +159,6 @@ endef
# A recursive helper function for finding the longest match
# $1 The list to be checked
# It works by always removing the currently matched item from the list
# and call itself recursively, until a match is found
define TRY_TO_MATCH_RULE_FROM_LIST_HELPER2
# Stop the recursion when the list is empty
ifneq ($1,)
@ -269,16 +213,29 @@ endef
define PARSE_RULE
RULE := $1
COMMANDS :=
REQUIRE_PLATFORM_KEY :=
# If the rule starts with all, then continue the parsing from
# PARSE_ALL_KEYBOARDS
ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,all),true)
KEYBOARD_RULE=all
$$(eval $$(call PARSE_ALL_KEYBOARDS))
else ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,all-avr),true)
KEYBOARD_RULE=all
REQUIRE_PLATFORM_KEY := avr
$$(eval $$(call PARSE_ALL_KEYBOARDS))
else ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,all-chibios),true)
KEYBOARD_RULE=all
REQUIRE_PLATFORM_KEY := chibios
$$(eval $$(call PARSE_ALL_KEYBOARDS))
else ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,all-arm_atsam),true)
KEYBOARD_RULE=all
REQUIRE_PLATFORM_KEY := arm_atsam
$$(eval $$(call PARSE_ALL_KEYBOARDS))
else ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,test),true)
$$(eval $$(call PARSE_TEST))
# If the rule starts with the name of a known keyboard, then continue
# the parsing from PARSE_KEYBOARD
else ifeq ($$(call TRY_TO_MATCH_RULE_FROM_LIST,$$(KEYBOARDS)),true)
else ifeq ($$(call TRY_TO_MATCH_RULE_FROM_LIST,$$(shell util/list_keyboards.sh | sort -u)),true)
KEYBOARD_RULE=$$(MATCHED_ITEM)
$$(eval $$(call PARSE_KEYBOARD,$$(MATCHED_ITEM)))
# Otherwise use the KEYBOARD variable, which is determined either by
@ -291,8 +248,8 @@ define PARSE_RULE
$$(info | QMK's make format recently changed to use folder locations and colons:)
$$(info | make project_folder:keymap[:target])
$$(info | Examples:)
$$(info | make planck/rev4:default:dfu)
$$(info | make planck:default)
$$(info | make dz60:default)
$$(info | make planck/rev6:default:flash)
$$(info |)
endif
endef
@ -395,26 +352,9 @@ endef
# if we are going to compile all keyboards, match the rest of the rule
# for each of them
define PARSE_ALL_KEYBOARDS
$$(eval $$(call PARSE_ALL_IN_LIST,PARSE_KEYBOARD,$(KEYBOARDS)))
$$(eval $$(call PARSE_ALL_IN_LIST,PARSE_KEYBOARD,$(shell util/list_keyboards.sh noci | sort -u)))
endef
# $1 Subproject
# When entering this, the keyboard and subproject are known, so now we need
# to determine which keymaps are going to get compiled
# define PARSE_SUBPROJECT
# endef
# If we want to parse all subprojects, but the keyboard doesn't have any,
# then use defaultsp instead
# define PARSE_ALL_SUBPROJECTS
# ifeq ($$(SUBPROJECTS),)
# $$(eval $$(call PARSE_SUBPROJECT,defaultsp))
# else
# $$(eval $$(call PARSE_ALL_IN_LIST,PARSE_SUBPROJECT,$$(SUBPROJECTS)))
# endif
# endef
# Prints a list of all known keymaps for the given keyboard
define LIST_ALL_KEYMAPS
COMMAND_true_LIST_KEYMAPS := \
@ -444,7 +384,7 @@ define PARSE_KEYMAP
# Format it in bold
KB_SP := $(BOLD)$$(KB_SP)$(NO_COLOR)
# Specify the variables that we are passing forward to submake
MAKE_VARS := KEYBOARD=$$(CURRENT_KB) KEYMAP=$$(CURRENT_KM)
MAKE_VARS := KEYBOARD=$$(CURRENT_KB) KEYMAP=$$(CURRENT_KM) REQUIRE_PLATFORM_KEY=$$(REQUIRE_PLATFORM_KEY)
# And the first part of the make command
MAKE_CMD := $$(MAKE) -r -R -C $(ROOT_DIR) -f build_keyboard.mk $$(MAKE_TARGET)
# The message to display
@ -463,6 +403,8 @@ define BUILD
LOG=$$$$($$(MAKE_CMD) $$(MAKE_VARS) SILENT=true 2>&1) ; \
if [ $$$$? -gt 0 ]; \
then $$(PRINT_ERROR_PLAIN); \
elif [ "$$$$LOG" = "skipped" ] ; \
then $$(PRINT_SKIPPED_PLAIN); \
elif [ "$$$$LOG" != "" ] ; \
then $$(PRINT_WARNING_PLAIN); \
else \
@ -554,19 +496,21 @@ if [ $$error_occurred -gt 0 ]; then $(HANDLE_ERROR); fi;
endef
# Let's match everything, we handle all the rule parsing ourselves
# Catch everything and parse the command line ourselves.
.PHONY: %
%:
# Check if we have the CMP tool installed
cmp $(ROOT_DIR)/Makefile $(ROOT_DIR)/Makefile >/dev/null 2>&1; if [ $$? -gt 0 ]; then printf "$(MSG_NO_CMP)"; exit 1; fi;
# Ensure that python3 is installed. This check can be removed after python is used in more places.
if ! python3 --version 1> /dev/null 2>&1; then printf "$(MSG_PYTHON_MISSING)"; fi
# Ensure that bin/qmk works. This will be a failing check after the next develop merge
if ! bin/qmk hello 1> /dev/null 2>&1; then printf "$(MSG_PYTHON_MISSING)"; fi
# Check if the submodules are dirty, and display a warning if they are
ifndef SKIP_GIT
if [ ! -e lib/chibios ]; then git submodule sync lib/chibios && git submodule update --depth 50 --init lib/chibios; fi
if [ ! -e lib/chibios-contrib ]; then git submodule sync lib/chibios-contrib && git submodule update --depth 50 --init lib/chibios-contrib; fi
if [ ! -e lib/ugfx ]; then git submodule sync lib/ugfx && git submodule update --depth 50 --init lib/ugfx; fi
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
git submodule status --recursive 2>/dev/null | \
while IFS= read -r x; do \
case "$$x" in \
@ -588,25 +532,6 @@ endif
$(foreach TEST,$(sort $(TESTS)),$(RUN_TEST))
if [ -f $(ERROR_FILE) ]; then printf "$(MSG_ERRORS)" & exit 1; fi;
# These no longer work because of the colon system
# All should compile everything
# .PHONY: all
# all: all-keyboards test-all
# Define some shortcuts, mostly for compatibility with the old syntax
# .PHONY: all-keyboards
# all-keyboards: all\:all\:all
# .PHONY: all-keyboards-defaults
# all-keyboards-defaults: all\:default
# .PHONY: test
# test: test-all
# .PHONY: test-clean
# test-clean: test-all-clean
lib/%:
git submodule sync $?
git submodule update --init $?
@ -632,12 +557,13 @@ else
endif
ifndef SKIP_VERSION
BUILD_DATE := $(shell date +"%Y-%m-%d-%H:%M:%S")
else
BUILD_DATE := 2020-01-01-00:00:00
endif
$(shell echo '#define QMK_VERSION "$(GIT_VERSION)"' > $(ROOT_DIR)/quantum/version.h)
$(shell echo '#define QMK_BUILDDATE "$(BUILD_DATE)"' >> $(ROOT_DIR)/quantum/version.h)
$(shell echo '#define CHIBIOS_VERSION "$(CHIBIOS_VERSION)"' >> $(ROOT_DIR)/quantum/version.h)
$(shell echo '#define CHIBIOS_CONTRIB_VERSION "$(CHIBIOS_CONTRIB_VERSION)"' >> $(ROOT_DIR)/quantum/version.h)
else
BUILD_DATE := NA
endif
include $(ROOT_DIR)/testlist.mk

2
Vagrantfile vendored
View file

@ -89,7 +89,7 @@ Vagrant.configure(2) do |config|
Examples:
make planck/rev4:default:dfu
make planck:default
make planck/rev4:default
EOT
end

1
api_data/_config.yml Normal file
View file

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

5
api_data/readme.md Normal file
View file

@ -0,0 +1,5 @@
# QMK Keyboard Metadata
This directory contains machine parsable data about keyboards supported by QMK. The latest version is always available online at <https://keyboards.qmk.fm>.
Do not edit anything here by hand. It is generated with the `qmk generate-api` command.

72
bootloader.mk
View file

@ -20,13 +20,19 @@
# Sets the bootloader defined in the keyboard's/keymap's rules.mk
# Current options:
#
# halfkay PJRC Teensy
# caterina Pro Micro (Sparkfun/generic)
# atmel-dfu Atmel factory DFU
# lufa-dfu LUFA DFU
# qmk-dfu QMK DFU (LUFA + blinkenlight)
# bootloadHID HIDBootFlash compatible (ATmega32A)
# USBasp USBaspLoader (ATmega328P)
# AVR:
# halfkay PJRC Teensy
# caterina Pro Micro (Sparkfun/generic)
# atmel-dfu Atmel factory DFU
# lufa-dfu LUFA DFU
# qmk-dfu QMK DFU (LUFA + blinkenlight)
# bootloadHID HIDBootFlash compatible (ATmega32A)
# USBasp USBaspLoader (ATmega328P)
# ARM:
# kiibohd Input:Club Kiibohd bootloader (only used on their boards)
# stm32duino STM32Duino (STM32F103x8)
# stm32-dfu STM32 USB DFU in ROM
# apm32-dfu APM32 USB DFU in ROM
#
# BOOTLOADER_SIZE can still be defined manually, but it's recommended
# you add any possible configuration to this list
@ -34,30 +40,30 @@
ifeq ($(strip $(BOOTLOADER)), atmel-dfu)
OPT_DEFS += -DBOOTLOADER_ATMEL_DFU
OPT_DEFS += -DBOOTLOADER_DFU
ifneq (,$(filter $(MCU), at90usb646 atmega16u2 atmega16u4 atmega32u2 atmega32u4))
ifneq (,$(filter $(MCU), atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647))
BOOTLOADER_SIZE = 4096
endif
ifeq ($(strip $(MCU)), at90usb1286)
ifneq (,$(filter $(MCU), at90usb1286 at90usb1287))
BOOTLOADER_SIZE = 8192
endif
endif
ifeq ($(strip $(BOOTLOADER)), lufa-dfu)
OPT_DEFS += -DBOOTLOADER_LUFA_DFU
OPT_DEFS += -DBOOTLOADER_DFU
ifneq (,$(filter $(MCU), at90usb646 atmega16u2 atmega16u4 atmega32u2 atmega32u4))
ifneq (,$(filter $(MCU), atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647))
BOOTLOADER_SIZE = 4096
endif
ifeq ($(strip $(MCU)), at90usb1286)
ifneq (,$(filter $(MCU), at90usb1286 at90usb1287))
BOOTLOADER_SIZE = 8192
endif
endif
ifeq ($(strip $(BOOTLOADER)), qmk-dfu)
OPT_DEFS += -DBOOTLOADER_QMK_DFU
OPT_DEFS += -DBOOTLOADER_DFU
ifneq (,$(filter $(MCU), at90usb646 atmega16u2 atmega16u4 atmega32u2 atmega32u4))
ifneq (,$(filter $(MCU), atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647))
BOOTLOADER_SIZE = 4096
endif
ifeq ($(strip $(MCU)), at90usb1286)
ifneq (,$(filter $(MCU), at90usb1286 at90usb1287))
BOOTLOADER_SIZE = 8192
endif
endif
@ -89,7 +95,45 @@ ifeq ($(strip $(BOOTLOADER)), lufa-ms)
BOOTLOADER_SIZE = 6144
FIRMWARE_FORMAT = bin
endif
ifdef BOOTLOADER_SIZE
OPT_DEFS += -DBOOTLOADER_SIZE=$(strip $(BOOTLOADER_SIZE))
endif
ifeq ($(strip $(BOOTLOADER)), stm32-dfu)
OPT_DEFS += -DBOOTLOADER_STM32_DFU
# Options to pass to dfu-util when flashing
DFU_ARGS ?= -d 0483:DF11 -a 0 -s 0x08000000:leave
DFU_SUFFIX_ARGS ?= -v 0483 -p DF11
endif
ifeq ($(strip $(BOOTLOADER)), apm32-dfu)
OPT_DEFS += -DBOOTLOADER_APM32_DFU
# Options to pass to dfu-util when flashing
DFU_ARGS ?= -d 314B:0106 -a 0 -s 0x08000000:leave
DFU_SUFFIX_ARGS ?= -v 314B -p 0106
endif
ifeq ($(strip $(BOOTLOADER)), kiibohd)
OPT_DEFS += -DBOOTLOADER_KIIBOHD
ifeq ($(strip $(MCU_ORIG)), MK20DX128)
MCU_LDSCRIPT = MK20DX128BLDR4
endif
ifeq ($(strip $(MCU_ORIG)), MK20DX256)
MCU_LDSCRIPT = MK20DX256BLDR8
endif
# Options to pass to dfu-util when flashing
DFU_ARGS = -d 1C11:B007
DFU_SUFFIX_ARGS = -v 1C11 -p B007
endif
ifeq ($(strip $(BOOTLOADER)), stm32duino)
OPT_DEFS += -DBOOTLOADER_STM32DUINO
MCU_LDSCRIPT = STM32F103x8_stm32duino_bootloader
BOARD = STM32_F103_STM32DUINO
# STM32F103 does NOT have an USB bootloader in ROM (only serial), so setting anything here does not make much sense
STM32_BOOTLOADER_ADDRESS = 0x80000000
# Options to pass to dfu-util when flashing
DFU_ARGS = -d 1EAF:0003 -a 2 -R
DFU_SUFFIX_ARGS = -v 1EAF -p 0003
endif

2
build_full_test.mk
View file

@ -30,4 +30,4 @@ $(TEST)_SRC += $(patsubst $(ROOTDIR)/%,%,$(wildcard $(TEST_PATH)/*.cpp))
$(TEST)_DEFS=$(TMK_COMMON_DEFS) $(OPT_DEFS)
$(TEST)_CONFIG=$(TEST_PATH)/config.h
VPATH+=$(TOP_DIR)/tests/test_common
VPATH+=$(TOP_DIR)/tests/test_common

26
build_keyboard.mk
View file

@ -16,7 +16,6 @@ include common.mk
KEYBOARD_FILESAFE := $(subst /,_,$(KEYBOARD))
TARGET ?= $(KEYBOARD_FILESAFE)_$(KEYMAP)
KEYBOARD_OUTPUT := $(BUILD_DIR)/obj_$(KEYBOARD_FILESAFE)
STM32_PATH := quantum/stm32
# Force expansion
TARGET := $(TARGET)
@ -138,7 +137,7 @@ endif
ifeq ($(strip $(CONVERT_TO_PROTON_C)), yes)
TARGET := $(TARGET)_proton_c
include $(STM32_PATH)/proton_c.mk
include platforms/chibios/GENERIC_STM32_F303XC/configs/proton_c.mk
OPT_DEFS += -DCONVERT_TO_PROTON_C
endif
@ -148,12 +147,6 @@ endif
include quantum/mcu_selection.mk
ifdef MCU_FAMILY
OPT_DEFS += -DQMK_STM32
KEYBOARD_PATHS += $(STM32_PATH)
endif
# Find all the C source files to be compiled in subfolders.
KEYBOARD_SRC :=
@ -290,6 +283,9 @@ ifneq ("$(wildcard $(USER_PATH)/config.h)","")
CONFIG_H += $(USER_PATH)/config.h
endif
# Disable features that a keyboard doesn't support
-include disable_features.mk
# Object files directory
# To put object files in current directory, use a dot (.), do NOT make
# this an empty or blank macro!
@ -324,6 +320,13 @@ SRC += $(TMK_COMMON_SRC)
OPT_DEFS += $(TMK_COMMON_DEFS)
EXTRALDFLAGS += $(TMK_COMMON_LDFLAGS)
SKIP_COMPILE := no
ifneq ($(REQUIRE_PLATFORM_KEY),)
ifneq ($(REQUIRE_PLATFORM_KEY),$(PLATFORM_KEY))
SKIP_COMPILE := yes
endif
endif
include $(TMK_PATH)/$(PLATFORM_KEY).mk
ifneq ($(strip $(PROTOCOL)),)
include $(TMK_PATH)/protocol/$(strip $(shell echo $(PROTOCOL) | tr '[:upper:]' '[:lower:]')).mk
@ -359,9 +362,16 @@ $(KEYBOARD_OUTPUT)_INC := $(PROJECT_INC) $(GFXINC)
$(KEYBOARD_OUTPUT)_CONFIG := $(PROJECT_CONFIG)
# Default target.
ifeq ($(SKIP_COMPILE),no)
all: build check-size
else
all:
echo "skipped" >&2
endif
build: elf cpfirmware
check-size: build
check-md5: build
objs-size: build
include show_options.mk

13
build_layout.mk
View file

@ -3,8 +3,14 @@ LAYOUTS_REPOS := $(patsubst %/,%,$(sort $(dir $(wildcard $(LAYOUTS_PATH)/*/))))
define SEARCH_LAYOUTS_REPO
LAYOUT_KEYMAP_PATH := $$(LAYOUTS_REPO)/$$(LAYOUT)/$$(KEYMAP)
LAYOUT_KEYMAP_JSON := $$(LAYOUT_KEYMAP_PATH)/keymap.json
LAYOUT_KEYMAP_C := $$(LAYOUT_KEYMAP_PATH)/keymap.c
ifneq ("$$(wildcard $$(LAYOUT_KEYMAP_C))","")
ifneq ("$$(wildcard $$(LAYOUT_KEYMAP_JSON))","")
-include $$(LAYOUT_KEYMAP_PATH)/rules.mk
KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c
KEYMAP_JSON := $$(LAYOUT_KEYMAP_JSON)
KEYMAP_PATH := $$(LAYOUT_KEYMAP_PATH)
else ifneq ("$$(wildcard $$(LAYOUT_KEYMAP_C))","")
-include $$(LAYOUT_KEYMAP_PATH)/rules.mk
KEYMAP_C := $$(LAYOUT_KEYMAP_C)
KEYMAP_PATH := $$(LAYOUT_KEYMAP_PATH)
@ -24,4 +30,7 @@ ifneq ($(FORCE_LAYOUT),)
endif
endif
$(foreach LAYOUT,$(LAYOUTS),$(eval $(call SEARCH_LAYOUTS)))
$(foreach LAYOUT,$(LAYOUTS),$(eval $(call SEARCH_LAYOUTS)))
# Use rule from build_json.mk, but update prerequisite in case KEYMAP_JSON was updated
$(KEYBOARD_OUTPUT)/src/keymap.c: $(KEYMAP_JSON)

6
build_test.mk
View file

@ -17,7 +17,7 @@ OUTPUTS := $(TEST_OBJ)/$(TEST) $(GTEST_OUTPUT)
GTEST_INC := \
$(LIB_PATH)/googletest/googletest/include\
$(LIB_PATH)/googletest/googlemock/include\
GTEST_INTERNAL_INC :=\
$(LIB_PATH)/googletest/googletest\
$(LIB_PATH)/googletest/googlemock
@ -27,7 +27,7 @@ $(GTEST_OUTPUT)_SRC :=\
googletest/src/gtest_main.cc\
googlemock/src/gmock-all.cc
$(GTEST_OUTPUT)_DEFS :=
$(GTEST_OUTPUT)_DEFS :=
$(GTEST_OUTPUT)_INC := $(GTEST_INC) $(GTEST_INTERNAL_INC)
LDFLAGS += -lstdc++ -lpthread -shared-libgcc
@ -49,6 +49,7 @@ endif
include common_features.mk
include $(TMK_PATH)/common.mk
include $(QUANTUM_PATH)/sequencer/tests/rules.mk
include $(QUANTUM_PATH)/serial_link/tests/rules.mk
ifneq ($(filter $(FULL_TESTS),$(TEST)),)
include build_full_test.mk
@ -65,4 +66,3 @@ include $(TMK_PATH)/rules.mk
$(shell mkdir -p $(BUILD_DIR)/test 2>/dev/null)
$(shell mkdir -p $(TEST_OBJ) 2>/dev/null)

1
common.mk
View file

@ -21,4 +21,5 @@ COMMON_VPATH += $(QUANTUM_PATH)/keymap_extras
COMMON_VPATH += $(QUANTUM_PATH)/audio
COMMON_VPATH += $(QUANTUM_PATH)/process_keycode
COMMON_VPATH += $(QUANTUM_PATH)/api
COMMON_VPATH += $(QUANTUM_PATH)/sequencer
COMMON_VPATH += $(DRIVER_PATH)

189
common_features.mk
View file

@ -17,6 +17,8 @@ SERIAL_PATH := $(QUANTUM_PATH)/serial_link
QUANTUM_SRC += \
$(QUANTUM_DIR)/quantum.c \
$(QUANTUM_DIR)/bitwise.c \
$(QUANTUM_DIR)/led.c \
$(QUANTUM_DIR)/keymap_common.c \
$(QUANTUM_DIR)/keycode_config.c
@ -25,6 +27,13 @@ ifeq ($(strip $(KEYBOARD_ENABLE)), yes)
OPT_DEFS += -DKEYBOARD_ENABLE
endif
ifeq ($(strip $(DEBUG_MATRIX_SCAN_RATE_ENABLE)), yes)
OPT_DEFS += -DDEBUG_MATRIX_SCAN_RATE
CONSOLE_ENABLE = yes
else ifeq ($(strip $(DEBUG_MATRIX_SCAN_RATE_ENABLE)), api)
OPT_DEFS += -DDEBUG_MATRIX_SCAN_RATE
endif
ifeq ($(strip $(API_SYSEX_ENABLE)), yes)
OPT_DEFS += -DAPI_SYSEX_ENABLE
OPT_DEFS += -DAPI_ENABLE
@ -33,6 +42,11 @@ ifeq ($(strip $(API_SYSEX_ENABLE)), yes)
SRC += $(QUANTUM_DIR)/api.c
endif
ifeq ($(strip $(COMMAND_ENABLE)), yes)
SRC += $(QUANTUM_DIR)/command.c
OPT_DEFS += -DCOMMAND_ENABLE
endif
ifeq ($(strip $(AUDIO_ENABLE)), yes)
OPT_DEFS += -DAUDIO_ENABLE
MUSIC_ENABLE = yes
@ -43,6 +57,13 @@ ifeq ($(strip $(AUDIO_ENABLE)), yes)
SRC += $(QUANTUM_DIR)/audio/luts.c
endif
ifeq ($(strip $(SEQUENCER_ENABLE)), yes)
OPT_DEFS += -DSEQUENCER_ENABLE
MUSIC_ENABLE = yes
SRC += $(QUANTUM_DIR)/sequencer/sequencer.c
SRC += $(QUANTUM_DIR)/process_keycode/process_sequencer.c
endif
ifeq ($(strip $(MIDI_ENABLE)), yes)
OPT_DEFS += -DMIDI_ENABLE
MUSIC_ENABLE = yes
@ -75,7 +96,7 @@ ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
SRC += $(QUANTUM_DIR)/pointing_device.c
endif
VALID_EEPROM_DRIVER_TYPES := vendor custom transient i2c
VALID_EEPROM_DRIVER_TYPES := vendor custom transient i2c spi
EEPROM_DRIVER ?= vendor
ifeq ($(filter $(EEPROM_DRIVER),$(VALID_EEPROM_DRIVER_TYPES)),)
$(error EEPROM_DRIVER="$(EEPROM_DRIVER)" is not a valid EEPROM driver)
@ -90,6 +111,11 @@ else
COMMON_VPATH += $(DRIVER_PATH)/eeprom
QUANTUM_LIB_SRC += i2c_master.c
SRC += eeprom_driver.c eeprom_i2c.c
else ifeq ($(strip $(EEPROM_DRIVER)), spi)
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)
OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_TRANSIENT
COMMON_VPATH += $(DRIVER_PATH)/eeprom
@ -114,6 +140,17 @@ else
SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
OPT_DEFS += -DEEPROM_EMU_STM32F072xB
OPT_DEFS += -DSTM32_EEPROM_ENABLE
else ifeq ($(MCU_SERIES)_$(MCU_LDSCRIPT), STM32F0xx_STM32F042x6)
# Stack sizes: Since this chip has limited RAM capacity, the stack area needs to be reduced.
# This ensures that the EEPROM page buffer fits into RAM
USE_PROCESS_STACKSIZE = 0x600
USE_EXCEPTIONS_STACKSIZE = 0x300
SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c
SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c
OPT_DEFS += -DEEPROM_EMU_STM32F042x6
OPT_DEFS += -DSTM32_EEPROM_ENABLE
else ifneq ($(filter $(MCU_SERIES),STM32L0xx STM32L1xx),)
OPT_DEFS += -DEEPROM_DRIVER
COMMON_VPATH += $(DRIVER_PATH)/eeprom
@ -144,12 +181,14 @@ ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
endif
endif
VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 IS31FL3737 WS2812 custom
LED_MATRIX_ENABLE ?= no
ifneq ($(strip $(LED_MATRIX_ENABLE)), no)
ifeq ($(filter $(LED_MATRIX_ENABLE),$(VALID_MATRIX_TYPES)),)
$(error LED_MATRIX_ENABLE="$(LED_MATRIX_ENABLE)" is not a valid matrix type)
VALID_LED_MATRIX_TYPES := IS31FL3731 custom
# TODO: IS31FL3733 IS31FL3737 IS31FL3741
ifeq ($(strip $(LED_MATRIX_ENABLE)), yes)
ifeq ($(filter $(LED_MATRIX_DRIVER),$(VALID_LED_MATRIX_TYPES)),)
$(error LED_MATRIX_DRIVER="$(LED_MATRIX_DRIVER)" is not a valid matrix type)
else
BACKLIGHT_ENABLE = yes
BACKLIGHT_DRIVER = custom
@ -157,65 +196,73 @@ ifneq ($(strip $(LED_MATRIX_ENABLE)), no)
SRC += $(QUANTUM_DIR)/led_matrix.c
SRC += $(QUANTUM_DIR)/led_matrix_drivers.c
endif
endif
ifeq ($(strip $(LED_MATRIX_ENABLE)), IS31FL3731)
OPT_DEFS += -DIS31FL3731
COMMON_VPATH += $(DRIVER_PATH)/issi
SRC += is31fl3731-simple.c
QUANTUM_LIB_SRC += i2c_master.c
ifeq ($(strip $(LED_MATRIX_DRIVER)), IS31FL3731)
OPT_DEFS += -DIS31FL3731 -DSTM32_I2C -DHAL_USE_I2C=TRUE
COMMON_VPATH += $(DRIVER_PATH)/issi
SRC += is31fl3731-simple.c
QUANTUM_LIB_SRC += i2c_master.c
endif
endif
RGB_MATRIX_ENABLE ?= no
VALID_RGB_MATRIX_TYPES := IS31FL3731 IS31FL3733 IS31FL3737 IS31FL3741 WS2812 custom
ifneq ($(strip $(RGB_MATRIX_ENABLE)), no)
ifeq ($(filter $(RGB_MATRIX_ENABLE),$(VALID_MATRIX_TYPES)),)
$(error RGB_MATRIX_ENABLE="$(RGB_MATRIX_ENABLE)" is not a valid matrix type)
endif
ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
ifeq ($(filter $(RGB_MATRIX_DRIVER),$(VALID_RGB_MATRIX_TYPES)),)
$(error "$(RGB_MATRIX_DRIVER)" is not a valid matrix type)
endif
OPT_DEFS += -DRGB_MATRIX_ENABLE
ifneq (,$(filter $(MCU), atmega16u2 atmega32u2))
# ATmegaxxU2 does not have hardware MUL instruction - lib8tion must be told to use software multiplication routines
OPT_DEFS += -DLIB8_ATTINY
endif
SRC += $(QUANTUM_DIR)/color.c
SRC += $(QUANTUM_DIR)/rgb_matrix.c
SRC += $(QUANTUM_DIR)/rgb_matrix_drivers.c
CIE1931_CURVE := yes
RGB_KEYCODES_ENABLE := yes
endif
ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes)
RGB_MATRIX_ENABLE := IS31FL3731
endif
ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3731)
OPT_DEFS += -DIS31FL3731 -DSTM32_I2C -DHAL_USE_I2C=TRUE
COMMON_VPATH += $(DRIVER_PATH)/issi
SRC += is31fl3731.c
QUANTUM_LIB_SRC += i2c_master.c
endif
ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3731)
OPT_DEFS += -DIS31FL3731 -DSTM32_I2C -DHAL_USE_I2C=TRUE
COMMON_VPATH += $(DRIVER_PATH)/issi
SRC += is31fl3731.c
QUANTUM_LIB_SRC += i2c_master.c
endif
ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3733)
OPT_DEFS += -DIS31FL3733 -DSTM32_I2C -DHAL_USE_I2C=TRUE
COMMON_VPATH += $(DRIVER_PATH)/issi
SRC += is31fl3733.c
QUANTUM_LIB_SRC += i2c_master.c
endif
ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3733)
OPT_DEFS += -DIS31FL3733 -DSTM32_I2C -DHAL_USE_I2C=TRUE
COMMON_VPATH += $(DRIVER_PATH)/issi
SRC += is31fl3733.c
QUANTUM_LIB_SRC += i2c_master.c
endif
ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3737)
OPT_DEFS += -DIS31FL3737 -DSTM32_I2C -DHAL_USE_I2C=TRUE
COMMON_VPATH += $(DRIVER_PATH)/issi
SRC += is31fl3737.c
QUANTUM_LIB_SRC += i2c_master.c
endif
ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3737)
OPT_DEFS += -DIS31FL3737 -DSTM32_I2C -DHAL_USE_I2C=TRUE
COMMON_VPATH += $(DRIVER_PATH)/issi
SRC += is31fl3737.c
QUANTUM_LIB_SRC += i2c_master.c
endif
ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3741)
OPT_DEFS += -DIS31FL3741 -DSTM32_I2C -DHAL_USE_I2C=TRUE
COMMON_VPATH += $(DRIVER_PATH)/issi
SRC += is31fl3741.c
QUANTUM_LIB_SRC += i2c_master.c
endif
ifeq ($(strip $(RGB_MATRIX_ENABLE)), WS2812)
OPT_DEFS += -DWS2812
WS2812_DRIVER_REQUIRED := yes
endif
ifeq ($(strip $(RGB_MATRIX_DRIVER)), WS2812)
OPT_DEFS += -DWS2812
WS2812_DRIVER_REQUIRED := yes
endif
ifeq ($(strip $(RGB_MATRIX_CUSTOM_KB)), yes)
OPT_DEFS += -DRGB_MATRIX_CUSTOM_KB
endif
ifeq ($(strip $(RGB_MATRIX_CUSTOM_KB)), yes)
OPT_DEFS += -DRGB_MATRIX_CUSTOM_KB
endif
ifeq ($(strip $(RGB_MATRIX_CUSTOM_USER)), yes)
OPT_DEFS += -DRGB_MATRIX_CUSTOM_USER
ifeq ($(strip $(RGB_MATRIX_CUSTOM_USER)), yes)
OPT_DEFS += -DRGB_MATRIX_CUSTOM_USER
endif
endif
ifeq ($(strip $(RGB_KEYCODES_ENABLE)), yes)
@ -239,12 +286,13 @@ ifeq ($(strip $(SERIAL_LINK_ENABLE)), yes)
VAPTH += $(SERIAL_PATH)
endif
ifneq ($(strip $(VARIABLE_TRACE)),)
VARIABLE_TRACE ?= no
ifneq ($(strip $(VARIABLE_TRACE)),no)
SRC += $(QUANTUM_DIR)/variable_trace.c
OPT_DEFS += -DNUM_TRACED_VARIABLES=$(strip $(VARIABLE_TRACE))
ifneq ($(strip $(MAX_VARIABLE_TRACE_SIZE)),)
OPT_DEFS += -DMAX_VARIABLE_TRACE_SIZE=$(strip $(MAX_VARIABLE_TRACE_SIZE))
endif
ifneq ($(strip $(MAX_VARIABLE_TRACE_SIZE)),)
OPT_DEFS += -DMAX_VARIABLE_TRACE_SIZE=$(strip $(MAX_VARIABLE_TRACE_SIZE))
endif
endif
ifeq ($(strip $(LCD_ENABLE)), yes)
@ -256,7 +304,7 @@ ifeq ($(strip $(BACKLIGHT_CUSTOM_DRIVER)), yes)
BACKLIGHT_DRIVER := custom
endif
VALID_BACKLIGHT_TYPES := pwm software custom
VALID_BACKLIGHT_TYPES := pwm timer software custom
BACKLIGHT_ENABLE ?= no
BACKLIGHT_DRIVER ?= pwm
@ -296,6 +344,12 @@ ifeq ($(strip $(WS2812_DRIVER_REQUIRED)), yes)
SRC += ws2812.c
else
SRC += ws2812_$(strip $(WS2812_DRIVER)).c
ifeq ($(strip $(PLATFORM)), CHIBIOS)
ifeq ($(strip $(WS2812_DRIVER)), pwm)
OPT_DEFS += -DSTM32_DMA_REQUIRED=TRUE
endif
endif
endif
# add extra deps
@ -383,9 +437,20 @@ ifneq ($(strip $(CUSTOM_MATRIX)), yes)
endif
endif
# Support for translating old names to new names:
ifeq ($(strip $(DEBOUNCE_TYPE)),sym_g)
DEBOUNCE_TYPE:=sym_defer_g
else ifeq ($(strip $(DEBOUNCE_TYPE)),eager_pk)
DEBOUNCE_TYPE:=sym_eager_pk
else ifeq ($(strip $(DEBOUNCE_TYPE)),sym_pk)
DEBOUNCE_TYPE:=sym_defer_pk
else ifeq ($(strip $(DEBOUNCE_TYPE)),eager_pr)
DEBOUNCE_TYPE:=sym_eager_pr
endif
DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce
# Debounce Modules. Set DEBOUNCE_TYPE=custom if including one manually.
DEBOUNCE_TYPE?= sym_g
DEBOUNCE_TYPE?= sym_defer_g
ifneq ($(strip $(DEBOUNCE_TYPE)), custom)
QUANTUM_SRC += $(DEBOUNCE_DIR)/$(strip $(DEBOUNCE_TYPE)).c
endif
@ -403,11 +468,14 @@ ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
# Functions added via QUANTUM_LIB_SRC are only included in the final binary if they're called.
# Unused functions are pruned away, which is why we can add multiple drivers here without bloat.
ifeq ($(PLATFORM),AVR)
QUANTUM_LIB_SRC += i2c_master.c \
i2c_slave.c
ifneq ($(NO_I2C),yes)
QUANTUM_LIB_SRC += i2c_master.c \
i2c_slave.c
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
@ -522,14 +590,23 @@ ifeq ($(strip $(AUTO_SHIFT_ENABLE)), yes)
endif
endif
ifeq ($(strip $(JOYSTICK_ENABLE)), yes)
JOYSTICK_ENABLE ?= no
ifneq ($(strip $(JOYSTICK_ENABLE)), no)
OPT_DEFS += -DJOYSTICK_ENABLE
SRC += $(QUANTUM_DIR)/process_keycode/process_joystick.c
SRC += $(QUANTUM_DIR)/joystick.c
endif
ifeq ($(strip $(JOYSTICK_ENABLE)), analog)
OPT_DEFS += -DANALOG_JOYSTICK_ENABLE
SRC += analog.c
endif
ifeq ($(strip $(JOYSTICK_ENABLE)), digital)
OPT_DEFS += -DDIGITAL_JOYSTICK_ENABLE
endif
ifeq ($(strip $(SWITCH_CONTROLLER_ENABLE)), yes)
OPT_DEFS += -DSWITCH_CONTROLLER_ENABLE
OPT_DEFS += -DGAMEPAD_ENABLE
endif
endif

31
disable_features.mk Normal file
View file

@ -0,0 +1,31 @@
# Unconditionally disable features that a keyboard advertises it doesn't support
FEATURE_NAMES :=
FEATURE_NAMES += ADAFRUIT_BLE
FEATURE_NAMES += AUDIO
FEATURE_NAMES += BACKLIGHT
FEATURE_NAMES += BLUETOOTH
FEATURE_NAMES += DIP_SWITCH
FEATURE_NAMES += DYNAMIC_KEYMAP
FEATURE_NAMES += ENCODER
FEATURE_NAMES += HAPTIC
FEATURE_NAMES += HD44780
FEATURE_NAMES += IOS_DEVICE
FEATURE_NAMES += LCD_BACKLIGHT
FEATURE_NAMES += LCD
FEATURE_NAMES += OLED
FEATURE_NAMES += POINTING_DEVICE
FEATURE_NAMES += PRINTING
FEATURE_NAMES += PS2_MOUSE
FEATURE_NAMES += RGBLIGHT
FEATURE_NAMES += RGB_MATRIX
FEATURE_NAMES += SLEEP_LED
FEATURE_NAMES += SERIAL_LINK
FEATURE_NAMES += STENO
FEATURE_NAMES += SWAP_HANDS
FEATURE_NAMES += VISUALIZER
FEATURE_NAMES += WATCHDOG
FEATURE_NAMES += XT
$(foreach AFEATURE,$(FEATURE_NAMES),\
$(if $(filter $($(AFEATURE)_SUPPORTED),no),$(eval $(AFEATURE)_ENABLE=no)))

1
docs/ChangeLog/20190830.md
View file

@ -50,4 +50,3 @@ This document marks the inaugural Breaking Change merge. A list of changes follo
* `KC_DELT` was a redundant, undocumented alias for `KC_DELETE`
* It has been removed and all its uses replaced with the more common `KC_DEL` alias
* Around 90 keymaps (mostly for ErgoDox boards) have been modified as a result

239
docs/ChangeLog/20200530.md Normal file
View file

@ -0,0 +1,239 @@
# QMK Breaking Change - 2020 May 30 Changelog
Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps.
The list of changes follows.
## Core Changes
### Converting V-USB usbdrv to a submodule
[#8321](https://github.com/qmk/qmk_firmware/pull/8321) and [qmk_compiler#62](https://github.com/qmk/qmk_compiler/pull/62).
These PRs move the V-USB driver code out of the qmk_firmware repository and into a submodule pointed at https://github.com/obdev/v-usb. This will make it easier to update the codebase if needed, while applying any potential QMK-specific modifications by forking it to the QMK GitHub organization.
### Unify Tap Hold functions and documentation
[#8348](https://github.com/qmk/qmk_firmware/pull/8348)
Updates all of the per key tap-hold functions to pass the `keyrecord_t` structure, and include documentation changes.
Any remaining versions or code outside of the main repo will need to be converted:
| Old function | New Function |
|------------------------------------------------------|---------------------------------------------------------------------------|
|`uint16_t get_tapping_term(uint16_t keycode)` |`uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record)` |
|`bool get_ignore_mod_tap_interrupt(uint16_t keycode)` |`bool get_ignore_mod_tap_interrupt(uint16_t keycode, keyrecord_t *record)` |
### Python Required In The Build Process
[#9000](https://github.com/qmk/qmk_firmware/pull/9000)
This is the last release of QMK that will work without having Python 3.6 (or later) installed. If your environment is not fully setup you will get a warning instructing you to set it up.
After the next breaking change you will not be able to build if `bin/qmk hello` does not work.
### Upgrade from tinyprintf to mpaland/printf
[#8269](https://github.com/qmk/qmk_firmware/pull/8269)
- Provides debug functionality on ChibiOS/ARM that is more compliant than previous integrations.
- Less maintenence, fewer QMK customisations, and allows QMK to sidestep previous compile and runtime issues.
- A `make git-submodule` may be required after pulling the latest QMK Firmware code to update to the new dependency.
### Fixed RGB_DISABLE_AFTER_TIMEOUT to be seconds based & small internals cleanup
[#6480](https://github.com/qmk/qmk_firmware/pull/6480)
- Changes `RGB_DISABLE_AFTER_TIMEOUT` to be based on milliseconds instead of ticks.
- Includes a code cleanup, resulting in a savings of 100 bytes, depending on features used.
- Fixed issues with timeouts / suspending at the wrong time not turning off all LEDs in some cases.
The `RGB_DISABLE_AFTER_TIMEOUT` definition is now deprecated, and has been superseded by `RGB_DISABLE_TIMEOUT`. To use the new definition, rename `RGB_DISABLE_AFTER_TIMEOUT` to `RGB_DISABLE_TIMEOUT` in your `config.h` file, and multiply the value set by 1200.
Before: `#define RGB_DISABLE_AFTER_TIMEOUT 100`
After: `#define RGB_DISABLE_TIMEOUT 120000`
### Switch to qmk forks for everything
[#9019](https://github.com/qmk/qmk_firmware/pull/9019)
Fork all QMK submodules to protect against upstream repositories disappearing.
### code cleanup regarding deprecated macro PLAY_NOTE_ARRAY by replacing it with PLAY_SONG
[#8484](https://github.com/qmk/qmk_firmware/pull/8484)
Removes the deprecated `PLAY_NOTE_ARRAY` macro. References to it are replaced with `PLAY_SONG`, which references the same function.
### fixing wrong configuration of AUDIO feature
[#8903](https://github.com/qmk/qmk_firmware/pull/8903) and [#8974](https://github.com/qmk/qmk_firmware/pull/8974)
`audio_avr.c` does not default to any pin; there has to be a #define XX_AUDIO in config.h at some level for Audio to actually work. Otherwise, the Audio code ends up cluttering the firmware, possibly breaking builds because the maximum allowed firmware size is exceeded.
These changes fix this by disabling Audio on keyboards that have the feature misconfigured, and therefore non-functional.
Also, add a compile-time error to alert the user to a missing pin-configuration (on AVR boards) when `AUDIO_ENABLE = yes` is set.
## Keyboard Refactors
### Migrating Lily58 to use split_common
[#6260](https://github.com/qmk/qmk_firmware/pull/6260)
Modifies the default firmware for Lily58 to use the `split_common` library, instead of including and depending on its own set of libraries for the following functionality:
- SSD1306 display
- i2c for OLED
- Serial Communication
This allows current lily58 firmware to advance with updates to the `split_common` library, which is shared with many other split keyboards.
#### To migrate existing Lily58 firmware:
[Changes to `config.h`](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-445ac369c8717dcd6fc6fc3630836fc1):
- Remove `#define SSD1306OLED` from config.h
[Changes to `keymap.c`](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7):
- Find/Replace each instance of `#ifdef SSD1306OLED` with `#ifdef OLED_DRIVER_ENABLE`
- The following changes are for compatibility with the OLED driver. If you don't use the OLED driver you may safely delete [this section](https://github.com/qmk/qmk_firmware/blob/e6b9980bd45c186f7360df68c24b6e05a80c10dc/keyboards/lily58/keymaps/default/keymap.c#L144-L190)
- Alternatively, if you did not change the OLED code from that in `default`, you may find it easier to simply copy the [relevant section](https://github.com/qmk/qmk_firmware/blob/4ac310668501ae6786c711ecc8f01f62ddaa1c0b/keyboards/lily58/keymaps/default/keymap.c#L138-L172). Otherwise, the changes you need to make are as follows (sample change [here](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7R138-R173))
- [Remove](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7L138-L141) the block
```c
#ifdef SSD1306OLED
iota_gfx_init(!has_usb()); // turns on the display
#endif
```
- Within the block bounded by `#ifdef OLED_DRIVER_ENABLE` and `#endif // OLED_DRIVER_ENABLE`, add the following block to ensure that your two OLEDs are rotated correctly across the left and right sides:
```c
oled_rotation_t oled_init_user(oled_rotation_t rotation) {
if (!is_keyboard_master())
return OLED_ROTATION_180; // flips the display 180 degrees if offhand
return rotation;
}
```
- Remove the functions `matrix_scan_user`, `matrix_update` and `iota_gfx_task_user`
- Find/Replace `matrix_render_user(struct CharacterMatrix *matrix)` with `iota_gfx_task_user(void)`
- Find/Replace `is_master` with `is_keyboard_master()`
- For each instance of `matrix_write_ln(matrix, display_fn())`, rewrite it as `oled_write_ln(read_layer_state(), false);`
- For each instance of `matrix_write(matrix, read_logo());`, replace with `oled_write(read_logo(), false);`
### Refactor zinc to use split_common
[#7114](https://github.com/qmk/qmk_firmware/pull/7114) and [#9171](https://github.com/qmk/qmk_firmware/pull/9171)
* Refactor to use split_common and remove split codes under the zinc/revx/
* Add - backlight RGB LED and/or underglow RGB LED option
* Add - continuous RGB animations feature (between L and R halves)
* Fix - keymap files to adapt to changes
* all authors of keymaps confirmed this PR
* Update - documents and rules.mk
### Refactor of TKC1800 to use common OLED code
[#8472](https://github.com/qmk/qmk_firmware/pull/8472)
Modifies the default firmware for TKC1800 to use the in-built I2C and OLED drivers, instead of including and depending on its own set of libraries for the following functionality:
- SSD1306 display
- i2c for OLED
This allows current TKC1800 firmware to advance with updates to those drivers, which are shared with other keyboards.
#### To migrate existing TKC1800 firmware:
[Changes to `config.h`](https://github.com/qmk/qmk_firmware/pull/8472/files#diff-d10b26e676b4a55cbb00d71955116526):
- Remove `#define SSD1306OLED` from config.h
[Changes to `tkc1800.c`](https://github.com/qmk/qmk_firmware/pull/8472/files#diff-3b35bd30abe89c8110717c6972cd2cc5):
- Add the following to avoid debug errors on HID_listen if the screen is not present
```c
void keyboard_pre_init_kb(void) {
setPinInputHigh(D0);
setPinInputHigh(D1);
keyboard_pre_init_user();
}
```
[Changes to `keymap.c`](https://github.com/qmk/qmk_firmware/pull/8472/files#diff-05a2a344ce27e4d045fe68520ccd4771):
- Find/Replace each instance of `#ifdef SSD1306OLED` with `#ifdef OLED_DRIVER_ENABLE`
- The following changes are for compatibility with the OLED driver. If you don't use the OLED driver you may safely delete [this section](https://github.com/qmk/qmk_firmware/blob/e6b9980bd45c186f7360df68c24b6e05a80c10dc/keyboards/lily58/keymaps/default/keymap.c#L144-L190)
- [Remove](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7L91-L158) the block
```c
#ifdef SSD1306OLED
iota_gfx_init(!has_usb()); // turns on the display
#endif
```
- Within the block bounded by `#ifdef OLED_DRIVER_ENABLE` and `#endif // OLED_DRIVER_ENABLE`, add the following block to ensure that your two OLEDs are rotated correctly across the left and right sides:
```c
oled_rotation_t oled_init_user(oled_rotation_t rotation) {
if (!is_keyboard_master())
return OLED_ROTATION_180; // flips the display 180 degrees if offhand
return rotation;
}
```
- Remove the function `iota_gfx_task_user`
### Split HHKB to ANSI and JP layouts and Add VIA support for each
[#8582](https://github.com/qmk/qmk_firmware/pull/8582)
- Splits the HHKB codebase into two separate folders `keyboards/hhkb/ansi` and `keyboards/hhkb/jp`.
- Adds VIA Configurator support for both versions.
#### Migrating existing HHKB keymaps
- Remove any checks for the `HHKB_JP` definition
- All checks for this definition have been removed, and each version uses the source that is appropriate to that version.
- Move the directory for your keymap into the appropriate `keymaps` directory
- `keyboards/hhkb/ansi/keymaps/` for ANSI HHKBs
- `keyboards/hhkb/jp/keymaps/` for HHKB JPs
- Compile with the new keyboard names
- This PR changes the compilation instructions for the HHKB Alternate Controller. To compile firmware for this controller moving forward, use:
- `make hhkb/ansi` for ANSI-layout HHKBs
- `make hhkb/jp` for HHKB JP keyboards
## Keyboard Moves
- [#8412](https://github.com/qmk/qmk_firmware/pull/8412 "Changing board names to prevent confusion") by blindassassin111
- [#8499](https://github.com/qmk/qmk_firmware/pull/8499 "Move the Keyboardio Model01 to a keyboardio/ subdir") by algernon
- [#8830](https://github.com/qmk/qmk_firmware/pull/8830 "Move spaceman keyboards") by Spaceman (formerly known as Rionlion100)
- [#8537](https://github.com/qmk/qmk_firmware/pull/8537 "Organizing my keyboards (plaid, tartan, ergoinu)") by hsgw
Keyboards by Keyboardio, Spaceman, and hsgw move to vendor folders, while PCBs designed by blindassassin111 are renamed.
Old Name | New Name
:----------------- | :-----------------
2_milk | spaceman/2_milk
at101_blackheart | at101_bh
ergoinu | dm9records/ergoinu
model01 | keyboardio/model01
omnikey_blackheart | omnikey_bh
pancake | spaceman/pancake
plaid | dm9records/plaid
tartan | dm9records/tartan
z150_blackheart | z150_bh
If you own one of these PCBs, please use the new names to compile your firmware moving forward.
## Keycode Migration PRs
[#8954](https://github.com/qmk/qmk_firmware/pull/8954 "Migrate `ACTION_LAYER_TOGGLE` to `TG()`"), [#8957](https://github.com/qmk/qmk_firmware/pull/8957 "Migrate `ACTION_MODS_ONESHOT` to `OSM()`"), [#8958](https://github.com/qmk/qmk_firmware/pull/8958 "Migrate `ACTION_DEFAULT_LAYER_SET` to `DF()`"), [#8959](https://github.com/qmk/qmk_firmware/pull/8959 "Migrate `ACTION_LAYER_MODS` to `LM()`"), [#8968](https://github.com/qmk/qmk_firmware/pull/8968 "Migrate `ACTION_MODS_TAP_KEY` to `MT()`"), [#8977](https://github.com/qmk/qmk_firmware/pull/8977 "Migrate miscellaneous `fn_actions` entries"), and [#8979](https://github.com/qmk/qmk_firmware/pull/8979 "Migrate `ACTION_MODS_KEY` to chained mod keycodes")
Authored by fauxpark, these pull requests remove references to deprecated TMK macros that have been superseded by native QMK keycodes.
Old `fn_actions` action | New QMK keycode
:---------------------- | :--------------
`ACTION_DEFAULT_LAYER_SET(layer)` | `DF(layer)`
`ACTION_LAYER_MODS(layer, mod)` | `LM(layer, mod)`
`ACTION_LAYER_ONESHOT(mod)` | `OSL(mod)`
`ACTION_LAYER_TOGGLE(layer)` | `TG(layer)`
`ACTION_MODS_ONESHOT(mod)` | `OSM(mod)`
`ACTION_MODS_TAP_KEY(mod, kc)` | `MT(mod, kc)`
`ACTION_MODS_KEY(mod, kc)`<br>e.g. `ACTION_MODS_KEY(MOD_LCTL, KC_0)` | `MOD(kc)`<br>e.g. `LCTL(KC_0)`

148
docs/ChangeLog/20200829.md Normal file
View file

@ -0,0 +1,148 @@
# QMK Breaking Change - 2020 Aug 29 Changelog
Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps.
## Changes Requiring User Action :id=changes-requiring-user-action
### Relocated Keyboards :id-relocated-keyboards
#### The Key Company project consolidation ([#9547](https://github.com/qmk/qmk_firmware/pull/9547))
#### relocating boards by flehrad to flehrad/ folder ([#9635](https://github.com/qmk/qmk_firmware/pull/9635))
Keyboards released by The Key Company and keyboards designed by flehrad have moved to vendor folders. If you own any of the keyboards listed below, please use the new names to compile your firmware moving forward.
Old Name | New Name
:--------------------- | :------------------
candybar/lefty | tkc/candybar/lefty
candybar/righty | tkc/candybar/righty
m0lly | tkc/m0lly
tkc1800 | tkc/tkc1800
bigswitch | flehrad/bigswitch
handwired/downbubble | flehrad/downbubble
handwired/numbrero | flehrad/numbrero
snagpad | flehrad/snagpad
handwired/tradestation | flehrad/tradestation
### Updated Keyboard Codebases :id=keyboard-updates
#### Keebio RGB wiring update ([#7754](https://github.com/qmk/qmk_firmware/pull/7754))
This pull request changes the configuration for Keebio split boards to use the same RGB strip wiring for each half, which provides the following improvements:
* Easier wiring due to one fewer wire needed (the wire between left DOut to extra data pin) and the fact that wiring is the same for both halves.
* RGB LEDs can be controlled by each half now instead of just master half.
* Extra data line is freed up to allow for I2C usage instead of serial.
If you have customized the value of `RGBLED_SPLIT` for your keymap, you will need to undefine it using `#undef RGBLED_SPLIT` before defining it to your customized value.
This change affects:
* BFO-9000
* Fourier
* Iris rev2
* Levinson, revs. 1 and 2
* Nyquist, revs. 1 and 2
* Quefrency rev1
* Viterbi, revs. 1 and 2
### Changes to Core Functionality :id=core-updates
* Bigger Combo index ([#9318](https://github.com/qmk/qmk_firmware/pull/9318))
Allows the Combo feature to support more than 256 combos.
Any fork that uses `process_combo_event` needs to update the function's first argument to `uint16_t`:
* Old function: `void process_combo_event(uint8_t combo_index, bool pressed)`
* New function: `void process_combo_event(uint16_t combo_index, bool pressed)`
## Core Changes :id=core-changes
### Fixes :id=core-fixes
* Mousekeys: scrolling acceleration is no longer coupled to mouse movement acceleration ([#9174](https://github.com/qmk/qmk_firmware/pull/9174))
* Keymap Extras: correctly assign Question Mark in Czech layout ([#9987](https://github.com/qmk/qmk_firmware/pull/9987))
### Additions and Enhancements :id=core-additions
* allow for WS2812 PWM to work on DMAMUX-capable devices ([#9471](https://github.com/qmk/qmk_firmware/pull/9471))
* Newer STM32 MCUs have a DMAMUX peripheral, which allows mapping of DMAs to different DMA streams, rather than hard-defining the target streams in silicon.
* Affects STM32L4+ devices, as well as the soon-to-be-supported-by-QMK STM32G4/H7 families.
* Tested on F303/Proton C (ChibiOS v19, non-DMAMUX), G474 (ChibiOS v20, with DMAMUX).
* dual-bank STM32 bootloader support ([#8778](https://github.com/qmk/qmk_firmware/pull/8778) and [#9738](https://github.com/qmk/qmk_firmware/pull/9738))
* Adds support for STM32 dual-bank flash bootloaders, by toggling a GPIO during early init in order to charge an RC circuit attached to `BOOT0`.
* The main rationale behind this is that dual-bank STM32 devices unconditionally execute user-mode code, regardless of whether or not the user-mode code jumps to the bootloader. If either flash bank is valid (and `BOOT0` is low), then the built-in bootloader will skip any sort of DFU.
* This PR allows for the initialisation sequencing to charge the RC circuit based on the example circuit posted on Discord, effectively pulling `BOOT0` high before issuing the system reset. As the RC circuit takes a while to discharge, the system reset executes the ROM bootloader which subsequently sees `BOOT0` high, and starts executing the DFU routines.
* Tested with STM32L082 (with current QMK+current ChibiOS), and STM32G474 (against ChibiOS 20.x).
* update Space Cadet and Tap Dance features to use Custom Tapping Term when appropriate ([#6259](https://github.com/qmk/qmk_firmware/pull/6259))
* For the Tap Dance feature, this completely removes the need for the `ACTION_TAP_DANCE_FN_ADVANCED_TIME` dance.
* HID Joystick Interface ([#4226](https://github.com/qmk/qmk_firmware/pull/4226) and [#9949](https://github.com/qmk/qmk_firmware/pull/9949 "Fix Joystick Compile Issues"))
* This implements a joystick feature, including a joystick_task function called from TMK, specific keycodes for joystick buttons and a USB HID interface.
* Tested on V-USB backend and Proton C; compiles but untested on LUFA.
* In order to test, you have to add `JOYSTICK_ENABLE = yes` to your `rules.mk` and
```c
#define JOYSTICK_BUTTON_COUNT 8
#define JOYSTICK_AXES_COUNT 2
```
in your config.h.
* Christmas RGB Underglow animation now fades between green and red ([#7648](https://github.com/qmk/qmk_firmware/pull/7648))
* `RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL` has been greatly decreased; please check your animation if you have customized this value.
* layer state now initializes on startup ([#8318](https://github.com/qmk/qmk_firmware/pull/8318))
* This should produce more consistent behavior between the two functions and layer masks.
* added support for HSV->RGB conversion without using CIE curve ([#9856](https://github.com/qmk/qmk_firmware/pull/9856))
* added NOEEPROM functions for RGB Matrix ([#9487](https://github.com/qmk/qmk_firmware/pull/9487))
* Added eeprom_helpers for toggle, mode, sethsv, speed, similar to rgblight versions.
* Added set_speed function.
* Added helper functions, similar to those in rgblight, in order to add NOEEPROM versions of toggle, step, hue, sat, val, and speed.
* Minor: spelling correction for EEPROM in a debug message.
* flashing firmware using `st-flash` utility from [STLink Tools](https://github.com/stlink-org/stlink) is now supported ([#9964](https://github.com/qmk/qmk_firmware/pull/9964))
* add ability to dump all makefile variables for the specified target ([#8256](https://github.com/qmk/qmk_firmware/pull/8256))
* Adds a new subtarget to builds, `dump_vars`, which allows for printing out all the variables that make knows about, after all substitutions occur.
* Example: `make handwired/onekey/proton_c:default:dump_vars`
* add ability to change the Auto Shift timeout in real time ([#8441](https://github.com/qmk/qmk_firmware/pull/8441))
* added a timer implementation for backlight on ChibiOS ([#8291](https://github.com/qmk/qmk_firmware/pull/8291))
* added a third endpoint to V-USB keyboards ([#9020](https://github.com/qmk/qmk_firmware/pull/9020))
* added a method to read the OLED display buffer from user space ([#8777](https://github.com/qmk/qmk_firmware/pull/8777))
* K-Type refactor ([#9864](https://github.com/qmk/qmk_firmware/pull/9864))
* The K-Type has been refactored to use QMK's native matrix scanning routine, and now has partial support for the RGB Matrix feature.
* Joysticks can now be used without defining analog pins ([#10169](https://github.com/qmk/qmk_firmware/pull/10169))
### Clean-ups and Optimizations :id=core-optimizations
* iWRAP protocol removed ([#9284](https://github.com/qmk/qmk_firmware/pull/9284))
* work begun for consolidation of ChibiOS platform files ([#8327](https://github.com/qmk/qmk_firmware/pull/8327) and [#9315](https://github.com/qmk/qmk_firmware/pull/9315))
* Start of the consolidation work to move the ChibiOS board definitions as well as the default set of configuration files for existing board definitions used by keyboards.
* Uses `/platforms/chibios` as previously discussed on discord.
* Consolidates the Proton C configs into the generic F303 definitions.
* Allows for defining a default set of `chconf.h`, `halconf.h`, and `mcuconf.h` files within the platform definition, which is able to be overridden by the keyboard directly, though include path ordering.
* Adds template `chconf.h`, `halconf.h`, `mcuconf.h`, and `board.h` that can be dropped into a keyboard directory, in order to override rather than replace the entire contents of the respective files.
* Removed Proton C QMK board definitions, falling back to ChibiOS board definitions with QMK overrides.
* Various tidy-ups for USB descriptor code ([#9005](https://github.com/qmk/qmk_firmware/pull/9005))
* Renamed `keyboard_led_stats` in lufa.c and ChibiOS usb_main.c to `keyboard_led_state`, as well as `vusb_keyboard_leds`, for consistency
* Formatted CDC and MIDI descriptors better
* Removed `ENDPOINT_CONFIG` macro, it seems pointless and removes the need for endpoint address defines in the middle of the endpoint numbering enum
* Fixed (possibly?) V-USB `GET_REPORT` request handling. Not sure about this one, but the existing code appears to always return an empty report - now `send_keyboard` sets this variable to the current report, matching what the LUFA code does.
* converted `CONSUMER2BLUEFRUIT()` and `CONSUMER2RN42()` macros to static inline functions ([#9055](https://github.com/qmk/qmk_firmware/pull/9055))
* Additional cleanups for V-USB code ([#9310](https://github.com/qmk/qmk_firmware/pull/9310))
* Removing the UART stuff entirely, now that we have Console support. Also fixing up various other things; switching some `debug()` calls to `dprintf()`, moved `raw_hid_report` out of the way so that we can implement the shared endpoint stuff.
* removed inclusion of `adafruit_ble.h` from `ssd1306.c` ([#9355](https://github.com/qmk/qmk_firmware/pull/9355))
* `outputselect.c` is no longer compiled if Bluetooth is disabled ([#9356](https://github.com/qmk/qmk_firmware/pull/9356))
* `analogRead()` deprecated in favor of `analogReadPin()` ([#9023](https://github.com/qmk/qmk_firmware/pull/9023))
* forcibly disable NKRO on V-USB controllers ([#9054](https://github.com/qmk/qmk_firmware/pull/9054))
* removed warning if running backlight on STM32F072 ([#10040](https://github.com/qmk/qmk_firmware/pull/10040))
* removed unused CORTEX_VTOR_INIT rules.mk option ([#10053](https://github.com/qmk/qmk_firmware/pull/10053))
* improved handling for enabling Link Time Optimization ([#9832](https://github.com/qmk/qmk_firmware/pull/9832))
* streamline rules for supporting Kiibohd bootloader ([#10129](https://github.com/qmk/qmk_firmware/pull/10129))
* Define `STM32_DMA_REQUIRED` when using DMA-based WS2812 driver on STM32 ([#10127](https://github.com/qmk/qmk_firmware/pull/10127))
* fix DMA stream ID calculation in ws2812_pwm ([#10008](https://github.com/qmk/qmk_firmware/pull/10008))
* remove support for Adafruit EZ Key Bluetooth controller ([#10103](https://github.com/qmk/qmk_firmware/pull/10103))
## QMK Infrastructure and Internals :id=qmk-internals
* Attempt to fix CI for non-master branches. ([#9308](https://github.com/qmk/qmk_firmware/pull/9308))
* Actually fetch the branch we're attempting to compare against.
* Run `qmk cformat` on `develop` branch ([#9501](https://github.com/qmk/qmk_firmware/pull/9501))
* minor refactor of Bluetooth API ([#9905](https://github.com/qmk/qmk_firmware/pull/9905))

150
docs/ChangeLog/20201128.md Normal file
View file

@ -0,0 +1,150 @@
# QMK Breaking Change - 2020 Nov 28 Changelog
Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps.
## Changes Requiring User Action :id=changes-requiring-user-action
### Relocated Keyboards :id-relocated-keyboards
#### Reduce Helix keyboard build variation ([#8669](https://github.com/qmk/qmk_firmware/pull/8669))
The build commands for the Helix keyboard are:
```
make <helix_build_name>:<keymap_name>
```
For `<helix_build_name>`, specify the one in the rightmost column of the table below, such as `helix`,` helix/pico`.
| before Oct 17 2019 | Oct 17 2019 | Mar 10 2020 | Nov 28 2020 |
| ---------------------|-------------------------|-------------------------| ------------------------|
| helix/rev1 | helix/rev1 | helix/rev1 | helix/rev1 |
| helix/pico | helix/pico | helix/pico | helix/pico |
| | helix/pico/back | helix/pico/back | helix/pico/back |
| | helix/pico/under | helix/pico/under | helix/pico/under |
| | | helix/pico/sc | -- |
| | | helix/pico/sc/back | helix/pico/sc |
| | | helix/pico/sc/under | -- |
| helix/rev2 (=helix) | helix/rev2 (=helix) | helix/rev2 (=helix) | -- |
| | helix/rev2/back | helix/rev2/back | -- |
| | helix/rev2/back/oled | helix/rev2/back/oled | ( --> helix/rev2/back) |
| | helix/rev2/oled | helix/rev2/oled | helix/rev2　(=helix) |
| | helix/rev2/oled/back | helix/rev2/oled/back | helix/rev2/back |
| | helix/rev2/oled/under | helix/rev2/oled/under | helix/rev2/under |
| | | helix/rev2/sc | -- |
| | | helix/rev2/sc/back | -- |
| | | helix/rev2/sc/oled | -- |
| | | helix/rev2/sc/oledback | helix/rev2/sc |
| | | helix/rev2/sc/oledunder | -- |
| | | helix/rev2/sc/under | -- |
| | helix/rev2/under | helix/rev2/under | -- |
| | helix/rev2/under/oled | helix/rev2/under/oled | ( --> helix/rev2/under) |
#### Update the Speedo firmware for v3.0 ([#10657](https://github.com/qmk/qmk_firmware/pull/10657))
The Speedo keyboard has moved to `cozykeys/speedo/v2` as the designer prepares to release the Speedo v3.0.
| Previous Name | New Name |
| :------------ | :------------------------- |
| speedo | cozykeys/speedo/v2 |
| -- | cozykeys/speedo/v3 **new** |
#### Maartenwut/Maarten name change to evyd13/Evy ([#10274](https://github.com/qmk/qmk_firmware/pull/10274))
Maartenwut has rebranded as @evyd13, and all released Maartenwut boards have moved.
| Previous Name | New Name |
| :--------------------- | :----------------- |
| maartenwut/atom47/rev2 | evyd13/atom47/rev2 |
| maartenwut/atom47/rev3 | evyd13/atom47/rev3 |
| maartenwut/eon40 | evyd13/eon40 |
| maartenwut/eon65 | evyd13/eon65 |
| maartenwut/eon75 | evyd13/eon75 |
| maartenwut/eon87 | evyd13/eon87 |
| maartenwut/eon95 | evyd13/eon95 |
| maartenwut/gh80_1800 | evyd13/gh80_1800 |
| maartenwut/gh80_3700 | evyd13/gh80_3700 |
| maartenwut/minitomic | evyd13/minitomic |
| maartenwut/mx5160 | evyd13/mx5160 |
| maartenwut/nt660 | evyd13/nt660 |
| maartenwut/omrontkl | evyd13/omrontkl |
| maartenwut/plain60 | evyd13/plain60 |
| maartenwut/pockettype | evyd13/pockettype |
| maartenwut/quackfire | evyd13/quackfire |
| maartenwut/solheim68 | evyd13/solheim68 |
| maartenwut/ta65 | evyd13/ta65 |
| maartenwut/wasdat | evyd13/wasdat |
| maartenwut/wasdat_code | evyd13/wasdat_code |
| maartenwut/wonderland | evyd13/wonderland |
#### Xelus Valor and Dawn60 Refactors ([#10512](https://github.com/qmk/qmk_firmware/pull/10512), [#10584](https://github.com/qmk/qmk_firmware/pull/10584))
The Valor and Dawn60 keyboards by Xelus22 both now require their revisions to be specified when compiling.
| Previous Name | New Name |
| :------------ | :---------------- |
| xelus/dawn60 | xelus/dawn60/rev1 |
| xelus/valor | xelus/valor/rev1 |
### Updated Keyboard Codebases :id=keyboard-updates
#### AEboards EXT65 Refactor ([#10820](https://github.com/qmk/qmk_firmware/pull/10820))
The EXT65 codebase has been reworked so keymaps can be used with either revision.
## Core Changes :id=core-changes
### Fixes :id=core-fixes
* Reconnect the USB if users wake up a computer from the keyboard to restore the USB state ([#10088](https://github.com/qmk/qmk_firmware/pull/10088))
* Fix cursor position bug in oled_write_raw functions ([#10800](https://github.com/qmk/qmk_firmware/pull/10800))
### Additions and Enhancements :id=core-additions
* Allow MATRIX_ROWS to be greater than 32 ([#10183](https://github.com/qmk/qmk_firmware/pull/10183))
* Add support for soft serial to ATmega32U2 ([#10204](https://github.com/qmk/qmk_firmware/pull/10204))
* Allow direct control of MIDI velocity value ([#9940](https://github.com/qmk/qmk_firmware/pull/9940))
* Joystick 16-bit support ([#10439](https://github.com/qmk/qmk_firmware/pull/10439))
* Allow encoder resolutions to be set per encoder ([#10259](https://github.com/qmk/qmk_firmware/pull/10259))
* Share button state from mousekey to pointing_device ([#10179](https://github.com/qmk/qmk_firmware/pull/10179))
* Add advanced/efficient RGB Matrix Indicators ([#8564](https://github.com/qmk/qmk_firmware/pull/8564))
* OLED display update interval support ([#10388](https://github.com/qmk/qmk_firmware/pull/10388))
* Per-Key Retro Tapping ([#10622](https://github.com/qmk/qmk_firmware/pull/10622))
* Allow backlight duty cycle limit ([#10260](https://github.com/qmk/qmk_firmware/pull/10260))
* Add step sequencer feature ([#9703](https://github.com/qmk/qmk_firmware/pull/9703))
* Added `add_oneshot_mods` & `del_oneshot_mods` ([#10549](https://github.com/qmk/qmk_firmware/pull/10549))
* Add AT90USB support for serial.c ([#10706](https://github.com/qmk/qmk_firmware/pull/10706))
* Auto shift: support repeats and early registration (#9826)
### Clean-ups and Optimizations :id=core-optimizations
* Haptic and solenoid cleanup ([#9700](https://github.com/qmk/qmk_firmware/pull/9700))
* XD75 cleanup ([#10524](https://github.com/qmk/qmk_firmware/pull/10524))
* Minor change to behavior allowing display updates to continue between task ticks ([#10750](https://github.com/qmk/qmk_firmware/pull/10750))
* Change some GPIO manipulations in matrix.c to be atomic ([#10491](https://github.com/qmk/qmk_firmware/pull/10491))
* combine repeated lines of code for ATmega32U2, ATmega16U2, ATmega328 and ATmega328P ([#10837](https://github.com/qmk/qmk_firmware/pull/10837))
* Remove references to HD44780 ([#10735](https://github.com/qmk/qmk_firmware/pull/10735))
## QMK Infrastructure and Internals :id=qmk-internals
* Add ability to build a subset of all keyboards based on platform. ([#10420](https://github.com/qmk/qmk_firmware/pull/10420))
* Initialise EEPROM drivers at startup, instead of upon first execution ([#10438](https://github.com/qmk/qmk_firmware/pull/10438))
* Make bootloader_jump weak for ChibiOS ([#10417](https://github.com/qmk/qmk_firmware/pull/10417))
* Support for STM32 GPIOF,G,H,I,J,K ([#10206](https://github.com/qmk/qmk_firmware/pull/10206))
* Add milc as a dependency and remove the installed milc ([#10563](https://github.com/qmk/qmk_firmware/pull/10563))
* ChibiOS upgrade: early init conversions ([#10214](https://github.com/qmk/qmk_firmware/pull/10214))
* ChibiOS upgrade: configuration file migrator ([#9952](https://github.com/qmk/qmk_firmware/pull/9952))
* Add definition based on currently-selected serial driver. ([#10716](https://github.com/qmk/qmk_firmware/pull/10716))
* Allow for modification of output RGB values when using rgblight/rgb_matrix. ([#10638](https://github.com/qmk/qmk_firmware/pull/10638))
* Allow keyboards/keymaps to execute code at each main loop iteration ([#10530](https://github.com/qmk/qmk_firmware/pull/10530))
* qmk cformat ([#10767](https://github.com/qmk/qmk_firmware/pull/10767))
* Add a Make variable to easily enable DEBUG_MATRIX_SCAN_RATE on the command line ([#10824](https://github.com/qmk/qmk_firmware/pull/10824))
* update Chibios OS USB for the OTG driver ([#8893](https://github.com/qmk/qmk_firmware/pull/8893))
* Fixup version.h writing when using `SKIP_VERSION=yes` ([#10972](https://github.com/qmk/qmk_firmware/pull/10972), [#10974](https://github.com/qmk/qmk_firmware/pull/10974))
* Rename ledmatrix.h to match .c file ([#7949](https://github.com/qmk/qmk_firmware/pull/7949))
* Split RGB_MATRIX_ENABLE into _ENABLE and _DRIVER ([#10231](https://github.com/qmk/qmk_firmware/pull/10231))
* Split LED_MATRIX_ENABLE into _ENABLE and _DRIVER ([#10840](https://github.com/qmk/qmk_firmware/pull/10840))

24
docs/README.md
View file

@ -1,30 +1,24 @@
# Quantum Mechanical Keyboard Firmware
[![Current Version](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags)
[![Build Status](https://travis-ci.org/qmk/qmk_firmware.svg?branch=master)](https://travis-ci.org/qmk/qmk_firmware)
[![Discord](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh)
[![Docs Status](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm)
[![GitHub contributors](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
[![GitHub forks](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
## What is QMK Firmware?
QMK (*Quantum Mechanical Keyboard*) is an open source community centered around developing computer input devices. The community encompasses all sorts of input devices, such as keyboards, mice, and MIDI devices. A core group of collaborators maintains [QMK Firmware](https://github.com/qmk/qmk_firmware), [QMK Configurator](https://config.qmk.fm), [QMK Toolbox](https://github.com/qmk/qmk_toolbox), [qmk.fm](https://qmk.fm), and this documentation with the help of community members like you.
## Get Started
Totally new to QMK? There are two ways to get started:
<div class="flex-container">
* Basic: [QMK Configurator](https://config.qmk.fm)
* Just select your keyboard from the dropdown and program your keyboard.
* We have an [introductory video](https://www.youtube.com/watch?v=-imgglzDMdY) you can watch.
* There is also an overview [document you can read](newbs_building_firmware_configurator.md).
* Advanced: [Use The Source](newbs.md)
* More powerful, but harder to use
?> **Basic** [QMK Configurator](newbs_building_firmware_configurator.md) <br>
User friendly graphical interfaces, no programming knowledge required.
?> **Advanced** [Use The Source](newbs.md) <br>
More powerful, but harder to use.
</div>
## Make It Yours
QMK has lots of [features](features.md) to explore, and a good deal of reference documentation to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md).
QMK has lots of features to explore, and a good deal of reference documentation to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md).
## Need help?

18
docs/_summary.md
View file

@ -3,7 +3,6 @@
* [Setup](newbs_getting_started.md)
* [Building Your First Firmware](newbs_building_firmware.md)
* [Flashing Firmware](newbs_flashing.md)
* [Testing and Debugging](newbs_testing_debugging.md)
* [Getting Help/Support](support.md)
* [Other Resources](newbs_learn_more_resources.md)
* [Syllabus](syllabus.md)
@ -11,7 +10,8 @@
* FAQs
* [General FAQ](faq_general.md)
* [Build/Compile QMK](faq_build.md)
* [Debugging/Troubleshooting QMK](faq_debug.md)
* [Troubleshooting QMK](faq_misc.md)
* [Debugging QMK](faq_debug.md)
* [Keymap FAQ](faq_keymap.md)
* [Glossary](reference_glossary.md)
@ -23,6 +23,7 @@
* [Overview](api_overview.md)
* [API Documentation](api_docs.md)
* [Keyboard Support](reference_configurator_support.md)
* [Adding Default Keymaps](configurator_default_keymaps.md)
* CLI
* [Overview](cli.md)
@ -34,7 +35,9 @@
* [Customizing Functionality](custom_quantum_functions.md)
* [Driver Installation with Zadig](driver_installation_zadig.md)
* [Keymap Overview](keymap.md)
* [Vagrant Guide](getting_started_vagrant.md)
* Development Environments
* [Docker Guide](getting_started_docker.md)
* [Vagrant Guide](getting_started_vagrant.md)
* Flashing
* [Flashing](flashing.md)
* [Flashing ATmega32A (ps2avrgb)](flashing_bootloadhid.md)
@ -53,6 +56,7 @@
* Simple Keycodes
* [Full List](keycodes.md)
* [Basic Keycodes](keycodes_basic.md)
* [Language-Specific Keycodes](reference_keymap_extras.md)
* [Modifier Keys](feature_advanced_keycodes.md)
* [Quantum Keycodes](quantum_keycodes.md)
@ -76,6 +80,7 @@
* [One Shot Keys](one_shot_keys.md)
* [Pointing Device](feature_pointing_device.md)
* [Raw HID](feature_rawhid.md)
* [Sequencer](feature_sequencer.md)
* [Swap Hands](feature_swap_hands.md)
* [Tap Dance](feature_tap_dance.md)
* [Tap-Hold Configuration](tap_hold.md)
@ -101,6 +106,7 @@
* [Encoders](feature_encoders.md)
* [Haptic Feedback](feature_haptic_feedback.md)
* [Joystick](feature_joystick.md)
* [LED Indicators](feature_led_indicators.md)
* [Proton C Conversion](proton_c_conversion.md)
* [PS/2 Mouse](feature_ps2_mouse.md)
* [Split Keyboard](feature_split_keyboard.md)
@ -109,10 +115,14 @@
* [Velocikey](feature_velocikey.md)
* Developing QMK
* [PR Checklist](pr_checklist.md)
* Breaking Changes
* [Overview](breaking_changes.md)
* [My Pull Request Was Flagged](breaking_changes_instructions.md)
* History
* [2020 Nov 28](ChangeLog/20201128.md)
* [2020 Aug 29](ChangeLog/20200829.md)
* [2020 May 30](ChangeLog/20200530.md)
* [2020 Feb 29](ChangeLog/20200229.md)
* [2019 Aug 30](ChangeLog/20190830.md)
@ -127,6 +137,7 @@
* [SPI Driver](spi_driver.md)
* [WS2812 Driver](ws2812_driver.md)
* [EEPROM Driver](eeprom_driver.md)
* ['serial' Driver](serial_driver.md)
* [GPIO Controls](internals_gpio_control.md)
* [Keyboard Guidelines](hardware_keyboard_guidelines.md)
@ -141,6 +152,7 @@
* Hardware Platform Development
* Arm/ChibiOS
* [Selecting an MCU](platformdev_selecting_arm_mcu.md)
* [Early initialization](platformdev_chibios_earlyinit.md)
* QMK Reference

43
docs/adc_driver.md
View file

@ -22,7 +22,7 @@ Then place this include at the top of your code:
### AVR
|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328P|
|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328/P|
|-------|-------------|-------------|---------|----------|
|0 |`F0` |`F0` |`A0` |`C0` |
|1 |`F1` |`F1` |`A1` |`C1` |
@ -39,15 +39,15 @@ Then place this include at the top of your code:
|12 | |`B5` | | |
|13 | |`B6` | | |
<sup>\* The ATmega328P possesses two extra ADC channels; however, they are not present on the DIP pinout, and are not shared with GPIO pins. You can use `adc_read()` directly to gain access to these.</sup>
<sup>\* The ATmega328/P possesses two extra ADC channels; however, they are not present on the DIP pinout, and are not shared with GPIO pins. You can use `adc_read()` directly to gain access to these.</sup>
### ARM
Note that some of these pins are doubled-up on ADCs with the same channel. This is because the pins can be used for either ADC.
Also note that the F0 and F3 use different numbering schemes. The F0 has a single ADC and the channels are 0-based, whereas the F3 has 4 ADCs and the channels are 1 based. This is because the F0 uses the `ADCv1` implementation of the ADC, whereas the F3 uses the `ADCv3` implementation.
Also note that the F0 and F3 use different numbering schemes. The F0 has a single ADC and the channels are 0-indexed, whereas the F3 has 4 ADCs and the channels are 1-indexed. This is because the F0 uses the `ADCv1` implementation of the ADC, whereas the F3 uses the `ADCv3` implementation.
|ADC|Channel|STM32F0XX|STM32F3XX|
|ADC|Channel|STM32F0xx|STM32F3xx|
|---|-------|---------|---------|
|1 |0 |`A0` | |
|1 |1 |`A1` |`A0` |
@ -122,32 +122,29 @@ Also note that the F0 and F3 use different numbering schemes. The F0 has a singl
|Function |Description |
|----------------------------|-------------------------------------------------------------------------------------------------------------------|
|`analogReference(mode)` |Sets the analog voltage reference source. Must be one of `ADC_REF_EXTERNAL`, `ADC_REF_POWER` or `ADC_REF_INTERNAL`.|
|`analogRead(pin)` |Reads the value from the specified Arduino pin, eg. `4` for ADC6 on the ATmega32U4. |
|`analogReadPin(pin)` |Reads the value from the specified QMK pin, eg. `F6` for ADC6 on the ATmega32U4. |
|`pinToMux(pin)` |Translates a given QMK pin to a mux value. If an unsupported pin is given, returns the mux value for "0V (GND)". |
|`analogReadPin(pin)` |Reads the value from the specified pin, eg. `F6` for ADC6 on the ATmega32U4. |
|`pinToMux(pin)` |Translates a given pin to a mux value. If an unsupported pin is given, returns the mux value for "0V (GND)". |
|`adc_read(mux)` |Reads the value from the ADC according to the specified mux. See your MCU's datasheet for more information. |
### ARM
Note that care was taken to match all of the functions used for AVR devices, however complications in the ARM platform prevent that from always being possible. For example, the `STM32` chips do not have assigned Arduino pins. We could use the default pin numbers, but those numbers change based on the package type of the device. For this reason, please specify your target pins with their identifiers (`A0`, `F3`, etc.). Also note that there are some variants of functions that accept the target ADC for the pin. Some pins can be used for multiple ADCs, and this specified can help you pick which ADC will be used to interact with that pin.
|Function |Description |
|----------------------------|--------------------------------------------------------------------------------------------------------------------|
|`analogReadPin(pin)` |Reads the value from the specified QMK pin, eg. `A0` for channel 0 on the STM32F0 and ADC1 channel 1 on the STM32F3. Note that if a pin can be used for multiple ADCs, it will pick the lower numbered ADC for this function. eg. `C0` will be channel 6 of ADC 1 when it could be used for ADC 2 as well.|
|`analogReadPinAdc(pin, adc)`|Reads the value from the specified QMK pin and ADC, eg. `C0, 1` will read from channel 6, ADC 2 instead of ADC 1. Note that the ADCs are 0-indexed for this function.|
|`pinToMux(pin)` |Translates a given QMK pin to a channel and ADC combination. If an unsupported pin is given, returns the mux value for "0V (GND)".|
|`adc_read(mux)` |Reads the value from the ADC according to the specified pin and adc combination. See your MCU's datasheet for more information.|
|Function |Description |
|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`analogReadPin(pin)` |Reads the value from the specified pin, eg. `A0` for channel 0 on the STM32F0 and ADC1 channel 1 on the STM32F3. Note that if a pin can be used for multiple ADCs, it will pick the lower numbered ADC for this function. eg. `C0` will be channel 6 of ADC 1 when it could be used for ADC 2 as well.|
|`analogReadPinAdc(pin, adc)`|Reads the value from the specified pin and ADC, eg. `C0, 1` will read from channel 6, ADC 2 instead of ADC 1. Note that the ADCs are 0-indexed for this function. |
|`pinToMux(pin)` |Translates a given pin to a channel and ADC combination. If an unsupported pin is given, returns the mux value for "0V (GND)". |
|`adc_read(mux)` |Reads the value from the ADC according to the specified pin and ADC combination. See your MCU's datasheet for more information. |
## Configuration
## ARM
The ARM implementation of the ADC has a few additional options that you can override in your own keyboards and keymaps to change how it operates.
The ARM implementation of the ADC has a few additional options that you can override in your own keyboards and keymaps to change how it operates. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.
|`#define` |Type |Default |Description|
|-------------------|------|---------------------|-----------|
|ADC_CIRCULAR_BUFFER|`bool`|`false` |If `TRUE`, then the implementation will use a circular buffer.|
|ADC_NUM_CHANNELS |`int` |`1` |Sets the number of channels that will be scanned as part of an ADC operation. The current implementation only supports `1`.|
|ADC_BUFFER_DEPTH |`int` |`2` |Sets the depth of each result. Since we are only getting a 12-bit result by default, we set this to `2` bytes so we can contain our one value. This could be set to 1 if you opt for a 8-bit or lower result.|
|ADC_SAMPLING_RATE |`int` |`ADC_SMPR_SMP_1P5` |Sets the sampling rate of the ADC. By default, it is set to the fastest setting. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.|
|ADC_RESOLUTION |`int` |`ADC_CFGR1_RES_12BIT`|The resolution of your result. We choose 12 bit by default, but you can opt for 12, 10, 8, or 6 bit. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.|
|`#define` |Type |Default |Description |
|---------------------|------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`ADC_CIRCULAR_BUFFER`|`bool`|`false` |If `true`, then the implementation will use a circular buffer. |
|`ADC_NUM_CHANNELS` |`int` |`1` |Sets the number of channels that will be scanned as part of an ADC operation. The current implementation only supports `1`. |
|`ADC_BUFFER_DEPTH` |`int` |`2` |Sets the depth of each result. Since we are only getting a 12-bit result by default, we set this to 2 bytes so we can contain our one value. This could be set to 1 if you opt for an 8-bit or lower result.|
|`ADC_SAMPLING_RATE` |`int` |`ADC_SMPR_SMP_1P5` |Sets the sampling rate of the ADC. By default, it is set to the fastest setting. |
|`ADC_RESOLUTION` |`int` |`ADC_CFGR1_RES_12BIT`|The resolution of your result. We choose 12 bit by default, but you can opt for 12, 10, 8, or 6 bit. |

4
docs/api_docs.md
View file

@ -28,7 +28,7 @@ As you can see the payload describes all aspects of a keyboard necessary to crea
To compile your keymap into a firmware simply POST your JSON to the `/v1/compile` endpoint. In the following example we've placed the JSON payload into a file named `json_data`.
```
$ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" http://api.qmk.fm/v1/compile
$ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" https://api.qmk.fm/v1/compile
{
"enqueued": true,
"job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6"
@ -40,7 +40,7 @@ $ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" http://ap
After submitting your keymap you can check the status using a simple HTTP GET call:
```
$ curl http://api.qmk.fm/v1/compile/ea1514b3-bdfc-4a7b-9b5c-08752684f7f6
$ curl https://api.qmk.fm/v1/compile/ea1514b3-bdfc-4a7b-9b5c-08752684f7f6
{
"created_at": "Sat, 19 Aug 2017 21:39:12 GMT",
"enqueued_at": "Sat, 19 Aug 2017 21:39:12 GMT",

2
docs/api_overview.md
View file

@ -1,6 +1,6 @@
# QMK API
The QMK API provides an asynchronous API that Web and GUI tools can use to compile arbitrary keymaps for any keyboard supported by [QMK](http://qmk.fm/). The stock keymap template supports all QMK keycodes that do not require supporting C code. Keyboard maintainers can supply their own custom templates to enable more functionality.
The QMK API provides an asynchronous API that Web and GUI tools can use to compile arbitrary keymaps for any keyboard supported by [QMK](https://qmk.fm/). The stock keymap template supports all QMK keycodes that do not require supporting C code. Keyboard maintainers can supply their own custom templates to enable more functionality.
## App Developers

58
docs/breaking_changes.md
View file

@ -6,27 +6,30 @@ The breaking change period is when we will merge PR's that change QMK in dangero
## What has been included in past Breaking Changes?
* [2020 Nov 28](ChangeLog/20201128.md)
* [2020 Aug 29](ChangeLog/20200829.md)
* [2020 May 30](ChangeLog/20200530.md)
* [2020 Feb 29](ChangeLog/20200229.md)
* [2019 Aug 30](ChangeLog/20190830.md)
## When is the next Breaking Change?
The next Breaking Change is scheduled for May 30, 2020.
The next Breaking Change is scheduled for February 27, 2021.
### Important Dates
* [x] 2020 Feb 29 - `future` is created. It will be rebased weekly.
* [ ] 2020 May 2 - `future` closed to new PR's.
* [ ] 2020 May 2 - Call for testers.
* [ ] 2020 May 28 - `master` is locked, no PR's merged.
* [ ] 2020 May 30 - Merge `future` to `master`.
* [ ] 2020 May 30 - `master` is unlocked. PR's can be merged again.
* [x] 2020 Nov 28 - `develop` is created. Each push to `master` is subsequently merged to `develop`
* [ ] 2021 Jan 30 - `develop` closed to new PR's.
* [ ] 2021 Jan 30 - Call for testers.
* [ ] 2021 Feb 25 - `master` is locked, no PR's merged.
* [ ] 2021 Feb 27 - Merge `develop` to `master`.
* [ ] 2021 Feb 27 - `master` is unlocked. PR's can be merged again.
## What changes will be included?
To see a list of breaking change candidates you can look at the [`breaking_change` label](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr). New changes might be added between now and when `future` is closed, and a PR with that label applied is not guaranteed to be merged.
To see a list of breaking change candidates you can look at the [`breaking_change` label](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr). New changes might be added between now and when `develop` is closed, and a PR with that label applied is not guaranteed to be merged.
If you want your breaking change to be included in this round you need to create a PR with the `breaking_change` label and have it accepted before `future` closes. After `future` closes no new breaking changes will be accepted.
If you want your breaking change to be included in this round you need to create a PR with the `breaking_change` label and have it accepted before `develop` closes. After `develop` closes no new breaking changes will be accepted.
Criteria for acceptance:
@ -37,41 +40,26 @@ Criteria for acceptance:
This section documents various processes we use when running the Breaking Changes process.
## Rebase `future` from `master`
## Creating the `develop` branch
This is run every Friday while `future` is open.
Process:
```
cd qmk_firmware
git checkout master
git pull --ff-only
git checkout future
git rebase master
git push --force
```
## Creating the `future` branch
This happens immediately after the previous `future` branch is merged.
This happens immediately after the previous `develop` branch is merged.
* `qmk_firmware` git commands
* [ ] `git checkout master`
* [ ] `git pull --ff-only`
* [ ] `git checkout -b future`
* [ ] `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 origin future`
* [ ] `git push origin develop`
* [ ] `git push --tags`
## 4 Weeks Before Merge
* `future` is now closed to new PR's, only fixes for current PR's may be merged
* `develop` is now closed to new PR's, only fixes for current PR's may be merged
* Post call for testers
* [ ] Discord
* [ ] GitHub PR
@ -94,15 +82,15 @@ This happens immediately after the previous `future` branch is merged.
## Day Of Merge
* `qmk_firmware` git commands
* [ ] `git checkout future`
* [ ] `git checkout develop`
* [ ] `git pull --ff-only`
* [ ] `git rebase origin/master`
* [ ] Edit `readme.md`
* [ ] Remove the notes about `future`
* [ ] Remove the notes about `develop`
* [ ] Roll up the ChangeLog into one file.
* [ ] `git commit -m 'Merge point for <DATE> Breaking Change'`
* [ ] `git push origin future`
* Github Actions
* [ ] Create a PR for `future`
* [ ] `git push origin develop`
* GitHub Actions
* [ ] Create a PR for `develop`
* [ ] Make sure travis comes back clean
* [ ] Merge `future` PR
* [ ] Merge `develop` PR

2
docs/breaking_changes_instructions.md
View file

@ -27,7 +27,7 @@ If you are contributing core code, and the only reason it needs to go through br
We require submissions that go through the Breaking Change process to include a changelog entry. The entry should be a short summary of the changes your pull request makes &ndash; [each section here started as a changelog](ChangeLog/20190830.md "n.b. This should link to the 2019 Aug 30 Breaking Changes doc - @noroadsleft").
Your changelog should be located at `docs/ChangeLog/YYYYMMDD/PR####.md`, where `YYYYMMDD` is the date on which QMK's breaking change branch &ndash; usually named `future` &ndash; will be merged into the `master` branch, and `####` is the number of your pull request.
Your changelog should be located at `docs/ChangeLog/YYYYMMDD/PR####.md`, where `YYYYMMDD` is the date on which QMK's breaking change branch &ndash; usually named `develop` &ndash; will be merged into the `master` branch, and `####` is the number of your pull request.
If your submission requires action on the part of users, your changelog should instruct users what action(s) must be taken, or link to a location that does so.

9
docs/cli.md
View file

@ -13,18 +13,17 @@ QMK requires Python 3.6 or greater. We try to keep the number of requirements sm
If you have installed [Homebrew](https://brew.sh) you can tap and install QMK:
```
brew tap qmk/qmk
brew install qmk
brew install qmk/qmk/qmk
export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment
```
### Install Using easy_install or pip :id=install-using-easy_install-or-pip
### Install Using pip :id=install-using-easy_install-or-pip
If your system is not listed above you can install QMK manually. First ensure that you have python 3.6 (or later) installed and have installed pip. Then install QMK with this command:
If your system is not listed above you can install QMK manually. First ensure that you have Python 3.6 (or later) installed and have installed pip. Then install QMK with this command:
```
pip3 install qmk
python3 -m pip install qmk
export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment
```

105
docs/cli_commands.md
View file

@ -6,16 +6,18 @@
This command allows you to compile firmware from any directory. You can compile JSON exports from <https://config.qmk.fm>, compile keymaps in the repo, or compile the keyboard in the current working directory.
This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
**Usage for Configurator Exports**:
```
qmk compile <configuratorExport.json>
qmk compile [-c] <configuratorExport.json>
```
**Usage for Keymaps**:
```
qmk compile -kb <keyboard_name> -km <keymap_name>
qmk compile [-c] [-e <var>=<value>] -kb <keyboard_name> -km <keymap_name>
```
**Usage in Keyboard Directory**:
@ -73,19 +75,20 @@ $ qmk compile -kb dz60
## `qmk flash`
This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default.
To specify a different bootloader, use `-bl <bootloader>`. Visit the [Flashing Firmware](flashing.md) guide for more details of the available bootloaders.
This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default. To specify a different bootloader, use `-bl <bootloader>`. Visit the [Flashing Firmware](flashing.md) guide for more details of the available bootloaders.
This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
**Usage for Configurator Exports**:
```
qmk flash <configuratorExport.json> -bl <bootloader>
qmk flash [-bl <bootloader>] [-c] [-e <var>=<value>] <configuratorExport.json>
```
**Usage for Keymaps**:
```
qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader>
qmk flash -kb <keyboard_name> -km <keymap_name> [-bl <bootloader>] [-c] [-e <var>=<value>]
```
**Listing the Bootloaders**
@ -128,6 +131,32 @@ Check your environment and report problems only:
qmk doctor -n
## `qmk info`
Displays information about keyboards and keymaps in QMK. You can use this to get information about a keyboard, show the layouts, display the underlying key matrix, or to pretty-print JSON keymaps.
**Usage**:
```
qmk info [-f FORMAT] [-m] [-l] [-km KEYMAP] [-kb KEYBOARD]
```
This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
**Examples**:
Show basic information for a keyboard:
qmk info -kb planck/rev5
Show the matrix for a keyboard:
qmk info -kb ergodox_ez -m
Show a JSON keymap for a keyboard:
qmk info -kb clueboard/california -km default
## `qmk json2c`
Creates a keymap.c from a QMK Configurator export.
@ -138,6 +167,35 @@ Creates a keymap.c from a QMK Configurator export.
qmk json2c [-o OUTPUT] filename
```
## `qmk c2json`
Creates a keymap.json from a keymap.c.
**Note:** Parsing C source files is not easy, therefore this subcommand may not work your keymap. In some cases not using the C pre-processor helps.
**Usage**:
```
qmk c2json -km KEYMAP -kb KEYBOARD [-q] [--no-cpp] [-o OUTPUT] filename
```
## `qmk lint`
Checks over a keyboard and/or keymap and highlights common errors, problems, and anti-patterns.
**Usage**:
```
qmk lint [-km KEYMAP] [-kb KEYBOARD] [--strict]
```
This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
**Examples**:
Do a basic lint check:
qmk lint -kb rominronin/katana60/rev2
## `qmk list-keyboards`
This command lists all the keyboards currently defined in `qmk_firmware`
@ -152,6 +210,8 @@ qmk list-keyboards
This command lists all the keymaps for a specified keyboard (and revision).
This command is directory aware. It will automatically fill in KEYBOARD if you are in a keyboard directory.
**Usage**:
```
@ -162,12 +222,24 @@ qmk list-keymaps -kb planck/ez
This command creates a new keymap based on a keyboard's existing default keymap.
This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory.
**Usage**:
```
qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
```
## `qmk clean`
This command cleans up the `.build` folder. If `--all` is passed, any .hex or .bin files present in the `qmk_firmware` directory will also be deleted.
**Usage**:
```
qmk clean [-a]
```
---
# Developer Commands
@ -214,6 +286,26 @@ This command starts a local HTTP server which you can use for browsing or improv
qmk docs [-p PORT]
```
## `qmk generate-docs`
This command allows you to generate QMK documentation locally. It can be uses for general browsing or improving the docs. External tools such as [serve](https://www.npmjs.com/package/serve) can be used to browse the generated files.
**Usage**:
```
qmk generate-docs
```
## `qmk generate-rgb-breathe-table`
This command generates a lookup table (LUT) header file for the [RGB Lighting](feature_rgblight.md) feature's breathing animation. Place this file in your keyboard or keymap directory as `rgblight_breathe_table.h` to override the default LUT in `quantum/`.
**Usage**:
```
qmk generate-rgb-breathe-table [-q] [-o OUTPUT] [-m MAX] [-c CENTER]
```
## `qmk kle2json`
This command allows you to convert from raw KLE data to QMK Configurator JSON. It accepts either an absolute file path, or a file name in the current directory. By default it will not overwrite `info.json` if it is already present. Use the `-f` or `--force` flag to overwrite.
@ -255,4 +347,3 @@ This command runs the python test suite. If you make changes to python code you
```
qmk pytest
```

2
docs/cli_configuration.md
View file

@ -108,7 +108,7 @@ compile.keymap: skully -> None
|-----|---------------|-------------|
| user.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) |
| user.keymap | None | The keymap name (Example: `default`) |
| user.name | None | The user's github username. |
| user.name | None | The user's GitHub username. |
# All Configuration Options

2
docs/cli_development.md
View file

@ -210,7 +210,7 @@ Our tests can be found in `lib/python/qmk/tests/`. You will find both unit and i
If your PR does not include a comprehensive set of tests please add comments like this to your code so that other people know where they can help:
# TODO(unassigned/<yourGithubUsername>): Write <unit|integration> tests
# TODO(unassigned/<your_github_username>): Write <unit|integration> tests
We use [nose2](https://nose2.readthedocs.io/en/latest/getting_started.html) to run our tests. You can refer to the nose2 documentation for more details on what you can do in your test functions.

2
docs/coding_conventions_c.md
View file

@ -49,7 +49,7 @@ int foo(void) {
[Clang-format](https://clang.llvm.org/docs/ClangFormat.html) is part of LLVM and can automatically format your code for you, because ain't nobody got time to do it manually. We supply a configuration file for it that applies most of the coding conventions listed above. It will only change whitespace and newlines, so you will still have to remember to include optional braces yourself.
Use the [full LLVM installer](http://llvm.org/builds/) to get clang-format on Windows, or use `sudo apt install clang-format` on Ubuntu.
Use the [full LLVM installer](https://llvm.org/builds/) to get clang-format on Windows, or use `sudo apt install clang-format` on Ubuntu.
If you run it from the command-line, pass `-style=file` as an option and it will automatically find the .clang-format configuration file in the QMK root directory.

3
docs/compatible_microcontrollers.md
View file

@ -14,10 +14,11 @@ Certain MCUs which do not have native USB will use [V-USB](https://www.obdev.at/
* [ATmega32A](https://www.microchip.com/wwwproducts/en/ATmega32A)
* [ATmega328P](https://www.microchip.com/wwwproducts/en/ATmega328P)
* [ATmega328](https://www.microchip.com/wwwproducts/en/ATmega328)
## ARM
You can also use any ARM chip with USB that [ChibiOS](http://www.chibios.org) supports. Most have plenty of flash. Known to work are:
You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) supports. Most have plenty of flash. Known to work are:
### STMicroelectronics (STM32)

30
docs/config_options.md
View file

@ -29,7 +29,9 @@ This level contains all of the options for that particular keymap. If you wish t
This is a C header file that is one of the first things included, and will persist over the whole project (if included). Lots of variables can be set here and accessed elsewhere. The `config.h` file shouldn't be including other `config.h` files, or anything besides this:
#include "config_common.h"
```c
#include "config_common.h"
```
## Hardware Options
@ -43,8 +45,6 @@ This is a C header file that is one of the first things included, and will persi
* generally who/whatever brand produced the board
* `#define PRODUCT Board`
* the name of the keyboard
* `#define DESCRIPTION a keyboard`
* a short description of what the keyboard is
* `#define MATRIX_ROWS 5`
* the number of rows in your keyboard's matrix
* `#define MATRIX_COLS 15`
@ -137,6 +137,8 @@ If you define these options you will enable the associated feature, which may in
* `#define RETRO_TAPPING`
* tap anyway, even after TAPPING_TERM, if there was no other key interruption between press and release
* See [Retro Tapping](tap_hold.md#retro-tapping) for details
* `#define RETRO_TAPPING_PER_KEY`
* enables handling for per key `RETRO_TAPPING` settings
* `#define TAPPING_TOGGLE 2`
* how many taps before triggering the toggle
* `#define PERMISSIVE_HOLD`
@ -191,7 +193,14 @@ If you define these options you will enable the associated feature, which may in
* `#define RGBLIGHT_ANIMATIONS`
* run RGB animations
* `#define RGBLIGHT_LAYERS`
* Lets you define [lighting layers](feature_rgblight.md) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state.
* Lets you define [lighting layers](feature_rgblight.md?id=lighting-layers) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state.
* `#define RGBLIGHT_MAX_LAYERS`
* Defaults to 8. Can be expanded up to 32 if more [lighting layers](feature_rgblight.md?id=lighting-layers) are needed.
* Note: Increasing the maximum will increase the firmware size and slow sync on split keyboards.
* `#define RGBLIGHT_LAYER_BLINK`
* Adds ability to [blink](feature_rgblight.md?id=lighting-layer-blink) a lighting layer for a specified number of milliseconds (e.g. to acknowledge an action).
* `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF`
* If defined, then [lighting layers](feature_rgblight?id=overriding-rgb-lighting-onoff-status) will be shown even if RGB Light is off.
* `#define RGBLED_NUM 12`
* number of LEDs
* `#define RGBLIGHT_SPLIT`
@ -243,7 +252,10 @@ There are a few different ways to set handedness for split keyboards (listed in
* `#define SPLIT_HAND_PIN B7`
* For using high/low pin to determine handedness, low = right hand, high = left hand. Replace `B7` with the pin you are using. This is optional, and if you leave `SPLIT_HAND_PIN` undefined, then you can still use the EE_HANDS method or MASTER_LEFT / MASTER_RIGHT defines like the stock Let's Split uses.
* `#define EE_HANDS` (only works if `SPLIT_HAND_PIN` is not defined)
* `#define SPLIT_HAND_MATRIX_GRID <out_pin>,<in_pin>`
* The handedness is determined by using the intersection of the keyswitches in the key matrix, which does not exist. Normally, when this intersection is shorted (level low), it is considered left. If you define `#define SPLIT_HAND_MATRIX_GRID_LOW_IS_RIGHT`, it is determined to be right when the level is low.
* `#define EE_HANDS` (only works if `SPLIT_HAND_PIN` and `SPLIT_HAND_MATRIX_GRID` are not defined)
* Reads the handedness value stored in the EEPROM after `eeprom-lefthand.eep`/`eeprom-righthand.eep` has been flashed to their respective halves.
* `#define MASTER_RIGHT`
@ -316,11 +328,9 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
```
* `LAYOUTS`
* A list of [layouts](feature_layouts.md) this keyboard supports.
* `LINK_TIME_OPTIMIZATION_ENABLE`
* `LTO_ENABLE`
* Enables Link Time Optimization (LTO) when compiling the keyboard. This makes the process take longer, but it can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable).
However, this will automatically disable the legacy TMK Macros and Functions features, as these break when LTO is enabled. It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION`. (Note: This does not affect QMK [Macros](feature_macros.md) and [Layers](feature_layers.md).)
* `LTO_ENABLE`
* Has the same meaning as `LINK_TIME_OPTIMIZATION_ENABLE`. You can use `LTO_ENABLE` instead of `LINK_TIME_OPTIMIZATION_ENABLE`.
## AVR MCU Options
* `MCU = atmega32u4`
@ -365,10 +375,8 @@ Use these to enable or disable building certain features. The more you have enab
* MIDI controls
* `UNICODE_ENABLE`
* Unicode
* `BLUETOOTH_ENABLE`
* Legacy option to Enable Bluetooth with the Adafruit EZ-Key HID. See BLUETOOTH
* `BLUETOOTH`
* Current options are AdafruitEzKey, AdafruitBLE, RN42
* Current options are AdafruitBLE, RN42
* `SPLIT_KEYBOARD`
* Enables split keyboard support (dual MCU like the let's split and bakingpy's boards) and includes all necessary files located at quantum/split_common
* `CUSTOM_MATRIX`

193
docs/configurator_default_keymaps.md Normal file
View file

@ -0,0 +1,193 @@
# Adding Default Keymaps to QMK Configurator :id=adding-default-keymaps
This page covers how to add a default keymap for a keyboard to QMK Configurator.
## Technical Information :id=technical-information
QMK Configurator uses JSON as its native file format for keymaps. As much as possible, these should be kept such that they behave the same as running `make <keyboard>:default` from `qmk_firmware`.
Keymaps in this directory require four key-value pairs:
* `keyboard` (string)
* This is the name of the keyboard, the same as would be used when running a compile job through `make` (e.g. `make 1upkeyboards/1up60rgb:default`).
* `keymap` (string)
* Should be set to `default`.
* `layout` (string)
* This is the layout macro used by the default keymap.
* `layers` (array)
* The keymap itself. This key should contain one array per layer, which themselves should contain the keycodes that make up that layer.
Additionally, most keymaps contain a `commit` key. This key is not consumed by the API that back-stops QMK Configurator, but is used by Configurator's maintainers to tell which version of a keymap was used to create the JSON keymap in this repository. The value is the SHA of the last commit to modify a board's default `keymap.c` in the `qmk_firmware` repository. The SHA is found by checking out [the `master` branch of the `qmk/qmk_firmware` repository](https://github.com/qmk/qmk_firmware/tree/master/) and running `git log -1 --pretty=oneline -- keyboards/<keyboard>/keymaps/default/keymap.c` (use `keymap.json` if the keyboard in question has this file instead), which should return something similar to:
```shell
f14629ed1cd7c7ec9089604d64f29a99981558e8 Remove/migrate action_get_macro()s from default keymaps (#5625)
```
In this example, `f14629ed1cd7c7ec9089604d64f29a99981558e8` is the value that should be used for `commit`.
## Example :id=example
If one wished to add a default keymap for the H87a by Hineybush, one would run the `git log` command above against the H87a's default keymap in `qmk_firmware`:
```shell
user ~/qmk_firmware (master)
$ git log -1 --pretty=oneline master -- keyboards/hineybush/h87a/keymaps/default/keymap.c
ef8878fba5d3786e3f9c66436da63a560cd36ac9 Hineybush h87a lock indicators (#8237)
```
Now that we have the commit hash, we need the keymap (edited for readability):
```c
...
#include QMK_KEYBOARD_H
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = LAYOUT_all(
KC_ESC, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, KC_PSCR, KC_SLCK, KC_PAUS,
KC_GRV, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_BSPC, KC_BSPC, KC_INS, KC_HOME, KC_PGUP,
KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS, KC_DEL, KC_END, KC_PGDN,
KC_CAPS, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_NUHS, KC_ENT,
KC_LSFT, KC_NUBS, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RSFT, KC_TRNS, KC_UP,
KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_RALT, MO(1), KC_RGUI, KC_RCTL, KC_LEFT, KC_DOWN, KC_RGHT),
[1] = LAYOUT_all(
KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, RGB_TOG, RGB_MOD, RGB_HUD, RGB_HUI, RGB_SAD, RGB_SAI, RGB_VAD, RGB_VAI, BL_TOGG, BL_DEC, BL_INC,
KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_VOLU,
KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, RESET, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_MPLY, KC_MNXT, KC_VOLD,
KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,
KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,
KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS),
};
```
The default keymap uses the `LAYOUT_all` macro, so that will be the value of the `layout` key. Compiled to a QMK Configurator JSON keymap, our resulting file should be:
```json
{
"keyboard": "hineybush/h87a",
"keymap": "default",
"commit": "ef8878fba5d3786e3f9c66436da63a560cd36ac9",
"layout": "LAYOUT_all",
"layers": [
[
"KC_ESC", "KC_F1", "KC_F2", "KC_F3", "KC_F4", "KC_F5", "KC_F6", "KC_F7", "KC_F8", "KC_F9", "KC_F10", "KC_F11", "KC_F12", "KC_PSCR", "KC_SLCK", "KC_PAUS",
"KC_GRV", "KC_1", "KC_2", "KC_3", "KC_4", "KC_5", "KC_6", "KC_7", "KC_8", "KC_9", "KC_0", "KC_MINS", "KC_EQL", "KC_BSPC", "KC_BSPC", "KC_INS", "KC_HOME", "KC_PGUP",
"KC_TAB", "KC_Q", "KC_W", "KC_E", "KC_R", "KC_T", "KC_Y", "KC_U", "KC_I", "KC_O", "KC_P", "KC_LBRC", "KC_RBRC", "KC_BSLS", "KC_DEL", "KC_END", "KC_PGDN",
"KC_CAPS", "KC_A", "KC_S", "KC_D", "KC_F", "KC_G", "KC_H", "KC_J", "KC_K", "KC_L", "KC_SCLN", "KC_QUOT", "KC_NUHS", "KC_ENT",
"KC_LSFT", "KC_NUBS", "KC_Z", "KC_X", "KC_C", "KC_V", "KC_B", "KC_N", "KC_M", "KC_COMM", "KC_DOT", "KC_SLSH", "KC_RSFT", "KC_TRNS", "KC_UP",
"KC_LCTL", "KC_LGUI", "KC_LALT", "KC_SPC", "KC_RALT", "MO(1)", "KC_RGUI", "KC_RCTL", "KC_LEFT", "KC_DOWN", "KC_RGHT"
],
[
"KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "RGB_TOG", "RGB_MOD", "RGB_HUD", "RGB_HUI", "RGB_SAD", "RGB_SAI", "RGB_VAD", "RGB_VAI", "BL_TOGG", "BL_DEC", "BL_INC",
"KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_VOLU",
"KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "RESET", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_MPLY", "KC_MNXT", "KC_VOLD",
"KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS",
"KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS",
"KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS"
]
]
}
```
The white space in the `layers` arrays have no effect on the functionality of the keymap, but are used to make these files easier for humans to read.
## Caveats :id=caveats
### Layers can only be referenced by number :id=layer-references
A common QMK convention is to name layers using a series of `#define`s, or an `enum` statement:
```c
enum layer_names {
_BASE,
_MEDIA,
_FN
};
```
This works in C, but for Configurator, you *must* use the layer's numeric index – `MO(_FN)` would need to be `MO(2)` in the above example.
### No support for custom code of any kind :id=custom-code
Features that require adding functions to the keymap.c file, such as Tap Dance or Unicode, can not be compiled in Configurator **at all**. Even setting `TAP_DANCE_ENABLE = yes` in the `qmk_firmware` repository at the keyboard level will prevent Configurator from compiling **any** firmware for that keyboard. This is limited both by the API and the current spec of our JSON keymap format.
### Limited Support for Custom keycodes :id=custom-keycodes
There is a way to support custom keycodes: if the logic for a custom keycode is implemented at the keyboard level instead of the keymap level in qmk_firmware, that keycode *can* be used in Configurator and it *will* compile and work. Instead of using the following in your `keymap.c`:
```c
enum custom_keycodes {
MACRO_1 = SAFE_RANGE,
MACRO_2,
MACRO_3
};
...
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch(keycode) {
case MACRO_1:
if (record->event.pressed) {
SEND_STRING("This is macro #1.");
}
return false;
case MACRO_2:
if (record->event.pressed) {
SEND_STRING("This is macro #2.");
}
return false;
case MACRO_3:
if (record->event.pressed) {
SEND_STRING("This is macro #3.");
}
return false;
}
return true;
};
```
... add the keycode `enum` block to your keyboard's header file (`<keyboard>.h`) as follows (note that the `enum` is named `keyboard_keycodes` here):
```c
enum keyboard_keycodes {
MACRO_1 = SAFE_RANGE,
MACRO_2,
MACRO_3,
NEW_SAFE_RANGE // Important!
};
```
... then the logic to your `<keyboard>.c` through `process_record_kb()`:
```c
bool process_record_kb(uint16_t keycode, keyrecord_t *record) {
switch(keycode) {
case MACRO_1:
if (record->event.pressed) {
SEND_STRING("This is macro #1.");
}
return false;
case MACRO_2:
if (record->event.pressed) {
SEND_STRING("This is macro #2.");
}
return false;
case MACRO_3:
if (record->event.pressed) {
SEND_STRING("This is macro #3.");
}
return false;
}
return process_record_user(keycode, record);
};
```
Note the call to `process_record_user()` at the end. Additionally, users of the keyboard will need to use `NEW_SAFE_RANGE` instead of `SAFE_RANGE` if they wish to add their own custom keycodes at keymap level, beyond what is provided by the keyboard.
## Additional Reading :id=additional-reading
For QMK Configurator to support your keyboard, your keyboard must be present in the `master` branch of the `qmk_firmware` repository. For instructions on this, please see [Supporting Your Keyboard in QMK Configurator](reference_configurator_support.md).

2
docs/configurator_step_by_step.md
View file

@ -12,7 +12,7 @@ I'll say that again because it's important:
!> **MAKE SURE YOU SELECT THE RIGHT VERSION!**
If your keyboard has been advertised to be powered by QMK but is not in the list, chances are a developer hasn't gotten to it yet or we haven't had a chance to merge it in yet. File an issue at [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) requesting to support that particular keyboard, if there is no active [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) for it. There are also QMK powered keyboards that are in their manufacturer's own github accounts. Double check for that as well. <!-- FIXME(skullydazed): This feels too wordy and I'm not sure we want to encourage these kinds of issues. Also, should we prompt them to bug the manufacutrer? -->
If your keyboard has been advertised to be powered by QMK but is not in the list, chances are a developer hasn't gotten to it yet or we haven't had a chance to merge it in yet. File an issue at [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) requesting to support that particular keyboard, if there is no active [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) for it. There are also QMK powered keyboards that are in their manufacturer's own GitHub accounts. Double check for that as well. <!-- FIXME(skullydazed): This feels too wordy and I'm not sure we want to encourage these kinds of issues. Also, should we prompt them to bug the manufacutrer? -->
## Step 2: Select Your Keyboard Layout

2
docs/contributing.md
View file

@ -23,7 +23,7 @@ Please keep these things in mind:
# Project Overview
QMK is largely written in C, with specific features and parts written in C++. It targets embedded processors found in keyboards, particularly AVR ([LUFA](http://www.fourwalledcubicle.com/LUFA.php)) and ARM ([ChibiOS](http://www.chibios.com)). If you are already well versed in Arduino programming you'll find a lot of the concepts and limitations familiar. Prior experience with Arduino is not required to successfully contribute to QMK.
QMK is largely written in C, with specific features and parts written in C++. It targets embedded processors found in keyboards, particularly AVR ([LUFA](https://www.fourwalledcubicle.com/LUFA.php)) and ARM ([ChibiOS](https://www.chibios.org)). If you are already well versed in Arduino programming you'll find a lot of the concepts and limitations familiar. Prior experience with Arduino is not required to successfully contribute to QMK.
<!-- FIXME: We should include a list of resources for learning C here. -->

176
docs/custom_quantum_functions.md
View file

@ -57,7 +57,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
case KC_ENTER:
// Play a tone when enter is pressed
if (record->event.pressed) {
PLAY_NOTE_ARRAY(tone_qwerty);
PLAY_SONG(tone_qwerty);
}
return true; // Let QMK send the enter press/release events
default:
@ -88,108 +88,6 @@ keyrecord_t record {
}
```
# LED Control
QMK provides methods to read 5 of the LEDs defined in the HID spec:
* Num Lock
* Caps Lock
* Scroll Lock
* Compose
* Kana
There are two ways to get the lock LED state:
* 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()`
!> `host_keyboard_led_state()` may already reflect a new value before `led_update_user()` is called.
Two more deprecated functions exist that provide the LED state as a `uint8_t`:
* `uint8_t led_set_kb(uint8_t usb_led)` and `_user(uint8_t usb_led)`
* `uint8_t host_keyboard_leds()`
## `led_update_user()`
This function will be called when the state of one of those 5 LEDs changes. It receives the LED state as a struct parameter.
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()`.
Some examples include:
- 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.
?> 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 `led_update_kb()` Implementation
```c
bool led_update_kb(led_t led_state) {
bool res = led_update_user(led_state);
if(res) {
// writePin sets the pin high for 1 and low for 0.
// In this example the pins are inverted, setting
// it low/0 turns it on, and high/1 turns the LED off.
// This behavior depends on whether the LED is between the pin
// and VCC or the pin and GND.
writePin(B0, !led_state.num_lock);
writePin(B1, !led_state.caps_lock);
writePin(B2, !led_state.scroll_lock);
writePin(B3, !led_state.compose);
writePin(B4, !led_state.kana);
}
return res;
}
```
### Example `led_update_user()` 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.
```c
#ifdef AUDIO_ENABLE
float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND);
float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND);
#endif
bool led_update_user(led_t led_state) {
#ifdef AUDIO_ENABLE
static uint8_t caps_state = 0;
if (caps_state != led_state.caps_lock) {
led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off);
caps_state = led_state.caps_lock;
}
#endif
return true;
}
```
### `led_update_*` Function Documentation
* Keyboard/Revision: `bool led_update_kb(led_t led_state)`
* Keymap: `bool led_update_user(led_t led_state)`
## `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).
## Setting Physical LED State
Some keyboard implementations provide convenience methods for setting the state of the physical LEDs.
### Ergodox Boards
The Ergodox implementations provide `ergodox_right_led_1`/`2`/`3_on`/`off()` to turn individual LEDs on or off, as well as `ergodox_right_led_on`/`off(uint8_t led)` to turn them on or off by their index.
In addition, it is possible to specify the brightness level of all LEDs with `ergodox_led_all_set(uint8_t n)`; of individual LEDs with `ergodox_right_led_1`/`2`/`3_set(uint8_t n)`; or by index with `ergodox_right_led_set(uint8_t led, uint8_t n)`.
Ergodox boards also define `LED_BRIGHTNESS_LO` for the lowest brightness and `LED_BRIGHTNESS_HI` for the highest brightness (which is the default).
# Keyboard Initialization Code
There are several steps in the keyboard initialization process. Depending on what you want to do, it will influence which function you should use.
@ -287,6 +185,14 @@ This function gets called at every matrix scan, which is basically as often as t
You should use this function if you need custom matrix scanning code. It can also be used for custom status output (such as LEDs or a display) or other functionality that you want to trigger regularly even when the user isn't typing.
# Keyboard housekeeping
* Keyboard/Revision: `void housekeeping_task_kb(void)`
* Keymap: `void housekeeping_task_user(void)`
This function gets called at the end of all QMK processing, before starting the next iteration. You can safely assume that QMK has dealt with the last matrix scan at the time that these functions are invoked -- layer states have been updated, USB reports have been sent, LEDs have been updated, and displays have been drawn.
Similar to `matrix_scan_*`, these are called as often as the MCU can handle. To keep your board responsive, it's suggested to do as little as possible during these function calls, potentially throtting their behaviour if you do indeed require implementing something special.
# Keyboard Idling/Wake Code
@ -319,7 +225,7 @@ This runs code every time that the layers get changed. This can be useful for l
### Example `layer_state_set_*` Implementation
This example shows how to set the [RGB Underglow](feature_rgblight.md) lights based on the layer, using the Planck as an example
This example shows how to set the [RGB Underglow](feature_rgblight.md) lights based on the layer, using the Planck as an example.
```c
layer_state_t layer_state_set_user(layer_state_t state) {
@ -343,6 +249,11 @@ layer_state_t layer_state_set_user(layer_state_t state) {
return state;
}
```
Use the `IS_LAYER_ON_STATE(state, layer)` and `IS_LAYER_OFF_STATE(state, layer)` macros to check the status of a particular layer.
Outside of `layer_state_set_*` functions, you can use the `IS_LAYER_ON(layer)` and `IS_LAYER_OFF(layer)` macros to check global layer state.
### `layer_state_set_*` Function Documentation
* Keyboard/Revision: `layer_state_t layer_state_set_kb(layer_state_t state)`
@ -438,7 +349,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
case KC_ENTER:
// Play a tone when enter is pressed
if (record->event.pressed) {
PLAY_NOTE_ARRAY(tone_qwerty);
PLAY_SONG(tone_qwerty);
}
return true; // Let QMK send the enter press/release events
case RGB_LYR: // This allows me to use underglow as layer indication, or as normal
@ -449,7 +360,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
layer_state_set(layer_state); // then immediately update the layer color
}
}
return false; break;
return false;
case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // For any of the RGB codes (see quantum_keycodes.h, L400 for reference)
if (record->event.pressed) { //This disables layer indication, as it's assumed that if you're changing this ... you want that disabled
if (user_config.rgb_layer_change) { // only if this is enabled
@ -486,56 +397,3 @@ And you're done. The RGB layer indication will only work if you want it to. And
* Keymap: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` and `void eeconfig_update_user(uint32_t val)`
The `val` is the value of the data that you want to write to EEPROM. And the `eeconfig_read_*` function return a 32 bit (DWORD) value from the EEPROM.
# Custom Tapping Term
By default, the tapping term and related options (such as `IGNORE_MOD_TAP_INTERRUPT`) are defined globally, and are not configurable by key. For most users, this is perfectly fine. But in some cases, dual function keys would be greatly improved by different timeout behaviors than `LT` keys, or because some keys may be easier to hold than others. Instead of using custom key codes for each, this allows for per key configurable timeout behaviors.
There are two configurable options to control per-key timeout behaviors:
- `TAPPING_TERM_PER_KEY`
- `IGNORE_MOD_TAP_INTERRUPT_PER_KEY`
You need to add `#define` lines to your `config.h` for each feature you want.
```
#define TAPPING_TERM_PER_KEY
#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY
```
## Example `get_tapping_term` Implementation
To change the `TAPPING_TERM` based on the keycode, you'd want to add something like the following to your `keymap.c` file:
```c
uint16_t get_tapping_term(uint16_t keycode) {
switch (keycode) {
case SFT_T(KC_SPC):
return TAPPING_TERM + 1250;
case LT(1, KC_GRV):
return 130;
default:
return TAPPING_TERM;
}
}
```
## Example `get_ignore_mod_tap_interrupt` Implementation
To change the `IGNORE_MOD_TAP_INTERRUPT` value based on the keycode, you'd want to add something like the following to your `keymap.c` file:
```c
bool get_ignore_mod_tap_interrupt(uint16_t keycode) {
switch (keycode) {
case SFT_T(KC_SPC):
return true;
default:
return false;
}
}
```
## `get_tapping_term` / `get_ignore_mod_tap_interrupt` Function Documentation
Unlike many of the other functions here, there isn't a need (or even reason) to have a quantum or keyboard level function. Only user level functions are useful here, so no need to mark them as such.

4
docs/de/README.md
View file

@ -9,11 +9,11 @@
## Was ist QMK Firmware?
QMK (*Quantum Mechanical Keyboard*) ist eine Open-Source-Community, welche die QMK-Firmware, die QMK-Toolbox, [qmk.fm](https://qmk.fm) und diese Dokumententation betreut. QMK-Firmware ist eine Weiterentwicklung der [tmk\_keyboard](http://github.com/tmk/tmk_keyboard)-Tastatur-Firmware mit vielen nützlichen Zusatzfunktionen für Atmel AVR-Prozessoren. Ursprünglich wurde sie für Produkte von [OLKB](http://olkb.com), das [ErgoDox EZ](http://www.ergodox-ez.com) und das [Clueboard](http://clueboard.co/) entwickelt. Im Laufe der Zeit wurde sie mit Hilfe von [ChibiOS](http://chibios.org) auch für die ARM-Architektur angepasst. Außerdem ist es inzwischen möglich, auch handverdrahtete Tastaturen und selbst geätzte PCBs mit QMK zu verwenden.
QMK (*Quantum Mechanical Keyboard*) ist eine Open-Source-Community, welche die QMK-Firmware, die QMK-Toolbox, [qmk.fm](https://qmk.fm) und diese Dokumententation betreut. QMK-Firmware ist eine Weiterentwicklung der [tmk\_keyboard](https://github.com/tmk/tmk_keyboard)-Tastatur-Firmware mit vielen nützlichen Zusatzfunktionen für Atmel AVR-Prozessoren. Ursprünglich wurde sie für Produkte von [OLKB](https://olkb.com), das [ErgoDox EZ](https://www.ergodox-ez.com) und das [Clueboard](https://clueboard.co/) entwickelt. Im Laufe der Zeit wurde sie mit Hilfe von [ChibiOS](https://chibios.org) auch für die ARM-Architektur angepasst. Außerdem ist es inzwischen möglich, auch handverdrahtete Tastaturen und selbst geätzte PCBs mit QMK zu verwenden.
## Bezugsquelle für QMK
Wenn Du vorhast, deine Tastatur, Tastaturbelegung oder Features zu QMK beizusteuern, geht das am einfachsten, indem Du das [Repository auf Github](https://github.com/qmk/qmk_firmware#fork-destination-box) forkst, die Änderungen in deinem lokalen Repo vornimmst und anschließend einen [Pull Request](https://github.com/qmk/qmk_firmware/pulls) einreichst.
Wenn Du vorhast, deine Tastatur, Tastaturbelegung oder Features zu QMK beizusteuern, geht das am einfachsten, indem Du das [Repository auf GitHub](https://github.com/qmk/qmk_firmware#fork-destination-box) forkst, die Änderungen in deinem lokalen Repo vornimmst und anschließend einen [Pull Request](https://github.com/qmk/qmk_firmware/pulls) einreichst.
Ansonsten kannst Du es als [zip](https://github.com/qmk/qmk_firmware/zipball/master) oder [tar](https://github.com/qmk/qmk_firmware/tarball/master) herunterladen, oder es direkt via git klonen (`git clone git@github.com:qmk/qmk_firmware.git` bzw. `git clone https://github.com/qmk/qmk_firmware.git`).

2
docs/de/_summary.md
View file

@ -11,7 +11,7 @@
* [QMK CLI](de/cli.md)
* [QMK CLI Konfiguration](de/cli_configuration.md)
* [Zu QMK beitragen](de/contributing.md)
* [Anleitung für Github](de/getting_started_github.md)
* [Anleitung für GitHub](de/getting_started_github.md)
* [Nach Hilfe fragen](de/getting_started_getting_help.md)
* [Breaking Changes](de/breaking_changes.md)

4
docs/de/newbs_getting_started.md
View file

@ -18,7 +18,7 @@ Wenn Du es vorziehst mit einer grafischen Oberfläche zu entwickeln kannst Du au
Du wirst ein Programm benötigen, mit dem Du **plain text** (= reiner Text) Dateien bearbeiten und speichern kannst. Wenn Du Windows benutzt, reicht dafür schon das normale `Notepad` und für Linux z.B. `gedit` oder `leafpad`. Beide sind sehr rudimentäre Editoren deren Funktionsumfang aber vollkommen ausreicht. Für macOS' standard `TextEdit` muss man ein bisschen vorsichtig sein und darauf achten, beim Speichern explizit unter _Format_ die Option _Reiner Text_ auszuwählen.
Ansonsten ist es empfehlenswert, einen Editor herunterzuladen der für die Programmierung und das Bearbeiten von Code ausgelegt ist wie z.b [Notepad++](http://notepad-plus-plus.org/), [Sublime Text](https://www.sublimetext.com/) oder [VS Code](https://code.visualstudio.com/).
Ansonsten ist es empfehlenswert, einen Editor herunterzuladen der für die Programmierung und das Bearbeiten von Code ausgelegt ist wie z.b [Notepad++](https://notepad-plus-plus.org/), [Sublime Text](https://www.sublimetext.com/) oder [VS Code](https://code.visualstudio.com/).
?> Immer noch unsicher, welcher Text Editor der Richtige für Dich ist? Laurence Bradford hat eine hervorragende [Einleitung](https://learntocodewith.me/programming/basics/text-editors/) zu dem Thema geschrieben (auf Englisch).
@ -44,7 +44,7 @@ Wir haben versucht, die Installation der Entwicklungsumgebung für QMK so einfac
Du wirst MSYS2 (o.Ä.) und Git benötigen.
* Befolge die Installationsanleitung auf der [MSYS2 Homepage](http://www.msys2.org)
* Befolge die Installationsanleitung auf der [MSYS2 Homepage](https://www.msys2.org)
* Schließe alle offenen MSYS2 Fenster und öffne ein neues MSYS2 MinGW 64-bit Terminal
* Installiere Git mit dem Kommando: `pacman -S git`

2
docs/de/newbs_learn_more_resources.md
View file

@ -6,7 +6,7 @@ Git Ressourcen:
* [Gutes allgemeines Tutorial](https://www.codecademy.com/learn/learn-git) (auf Englisch)
* [Git spielerisch anhand von Beispielen lernen](https://learngitbranching.js.org/) (auf Englisch)
* [Mehr über den allgemeinen Umgang mit Github](getting_started_github.md)
* [Mehr über den allgemeinen Umgang mit GitHub](getting_started_github.md)
* [Mehr über Git im Bezug zu QMK](contributing.md)
Mehr über die Arbeit mit der Befehlszeile:

8
docs/de/newbs_testing_debugging.md
View file

@ -10,8 +10,8 @@ Anmerkung: Diese Programme werden weder von QMK bereitgestellt oder gutgeheißen
* [Switch Hitter](https://elitekeyboards.com/switchhitter.php) (Nur für Windows)
* [Keyboard Viewer](https://www.imore.com/how-use-keyboard-viewer-your-mac) (Nur für Mac)
* [Keyboard Tester](http://www.keyboardtester.com) (Web basiert)
* [Keyboard Checker](http://keyboardchecker.com) (Web basiert)
* [Keyboard Tester](https://www.keyboardtester.com) (Web basiert)
* [Keyboard Checker](https://keyboardchecker.com) (Web basiert)
## Debuggen
@ -41,7 +41,9 @@ Bevorzugst Du es lieber auf der Befehlszeile zu debuggen? Dafür eignet sich das
Manchmal ist es hilfreich Debug-Nachrichten innerhalb deines eigenen [Custom Codes](de/custom_quantum_functions.md) zu drucken. Das ist ziemlich einfach. Beginne damit `print.h` am Anfang deiner Datei zu inkludieren:
#include <print.h>
```c
#include "print.h"
```
Danach stehen dir verschiedene Druck-Funktionen zur Verfügung:

2
docs/documentation_best_practices.md
View file

@ -61,4 +61,4 @@ This page describes my cool feature. You can use my cool feature to make coffee
|KC_SUGAR||Order Sugar|
```
Place your documentation into `docs/feature_<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_sidebar.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.
Place your documentation into `docs/feature_<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_summary.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.

8
docs/documentation_templates.md
View file

@ -4,12 +4,12 @@ This page documents the templates you should use when submitting new Keymaps and
## Keymap `readme.md` Template :id=keyboard-readmemd-template
Most keymaps have an image depicting the layout. You can use [Keyboard Layout Editor](http://keyboard-layout-editor.com) to create an image. Upload it to [Imgur](http://imgur.com) or another hosting service, please do not include images in your Pull Request.
Most keymaps have an image depicting the layout. You can use [Keyboard Layout Editor](https://keyboard-layout-editor.com) to create an image. Upload it to [Imgur](https://imgur.com) or another hosting service, please do not include images in your Pull Request.
Below the image you should write a short description to help people understand your keymap.
```
![Clueboard Layout Image](http://i.imgur.com/7Capi8W.png)
![Clueboard Layout Image](https://i.imgur.com/7Capi8W.png)
# Default Clueboard Layout
@ -24,9 +24,9 @@ the Ctrl, Alt, or GUI modifiers are held down.
```
# Planck
![Planck](http://i.imgur.com/q2M3uEU.jpg)
![Planck](https://i.imgur.com/q2M3uEU.jpg)
A compact 40% (12x4) ortholinear keyboard kit made and sold by OLKB and Massdrop. [More info on qmk.fm](http://qmk.fm/planck/)
A compact 40% (12x4) ortholinear keyboard kit made and sold by OLKB and Massdrop. [More info on qmk.fm](https://qmk.fm/planck/)
* Keyboard Maintainer: [Jack Humbert](https://github.com/jackhumbert)
* Hardware Supported: Planck PCB rev1, rev2, rev3, rev4, Teensy 2.0

47
docs/driver_installation_zadig.md
View file

@ -4,7 +4,7 @@ QMK presents itself to the host as a regular HID keyboard device, and as such re
There are two notable exceptions: the Caterina bootloader, usually seen on Pro Micros, and the HalfKay bootloader shipped with PJRC Teensys, appear as a serial port and a generic HID device respectively, and so do not require a driver.
We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have set up the development environment with MSYS2 or WSL, the `qmk_install.sh` script will have asked if you want it to install the drivers for you.
We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have set up the development environment with MSYS2, the `qmk_install.sh` script will have already installed the drivers for you.
## Installation
@ -14,16 +14,11 @@ Some keyboards may have specific instructions for entering the bootloader. For e
To put a device in bootloader mode with USBaspLoader, tap the `RESET` button while holding down the `BOOT` button.
Alternatively, hold `BOOT` while inserting the USB cable.
Zadig will automatically detect the bootloader device. You may sometimes need to check **Options → List All Devices**.
- For keyboards with Atmel AVR MCUs, the bootloader will be named something similar to `ATm32U4DFU`, and have a Vendor ID of `03EB`.
- USBasp bootloaders will appear as `USBasp`, with a VID/PID of `16C0:05DC`.
- AVR keyboards flashed with the QMK-DFU bootloader will be named `<keyboard name> Bootloader` and will also have the VID `03EB`.
- For most ARM keyboards, it will be called `STM32 BOOTLOADER`, and have a VID/PID of `0483:DF11`.
Zadig should automatically detect the bootloader device, but you may sometimes need to check **Options → List All Devices** and select the device from the dropdown instead.
!> If Zadig lists one or more devices with the `HidUsb` driver, your keyboard is probably not in bootloader mode. The arrow will be colored orange and you will be asked to confirm modifying a system driver. **Do not** proceed if this is the case!
If the arrow appears green, select the driver, and click **Install Driver**. The `libusb-win32` driver will usually work for AVR, and `WinUSB` for ARM, but if you still cannot flash the board, try installing a different driver from the list. For flashing a USBaspLoader device via command line with msys2, the `libusbk` driver is recommended, otherwise `libusb-win32` will work fine if you are using QMK Toolbox for flashing.
If the arrow appears green, select the driver, and click **Install Driver**. See the [list of known bootloaders](#list-of-known-bootloaders) for the correct driver to install.
![Zadig with a bootloader driver correctly installed](https://i.imgur.com/b8VgXzx.png)
@ -43,6 +38,40 @@ Right-click it and hit **Uninstall device**. Make sure to tick **Delete the driv
![The Device Uninstall dialog, with the "delete driver" checkbox ticked](https://i.imgur.com/aEs2RuA.png)
Click **Action → Scan for hardware changes**. At this point, you should be able to type again. Double check in Zadig that the keyboard device(s) are using the `HidUsb` driver. If so, you're all done, and your board should be functional again!
Click **Action → Scan for hardware changes**. At this point, you should be able to type again. Double check in Zadig that the keyboard device(s) are using the `HidUsb` driver. If so, you're all done, and your board should be functional again! Otherwise, repeat the process until Zadig reports the correct driver.
?> A full reboot of your computer may sometimes be necessary at this point, to get Windows to pick up the new driver.
## List of Known Bootloaders
This is a list of known bootloader devices and their USB vendor and product IDs, as well as the correct driver to assign for flashing with QMK. Note that the usbser and HidUsb drivers are built in to Windows, and cannot be assigned with Zadig - if your device has an incorrect driver, you must use the Device Manager to uninstall it as described in the previous section.
The device name here is the name that appears in Zadig, and may not be what the Device Manager or QMK Toolbox displays.
|Bootloader |Device Name |VID/PID |Driver |
|-------------|------------------------------|--------------|-------|
|`atmel-dfu` |ATmega16u2 DFU |`03EB:2FEF` |libusb0|
|`atmel-dfu` |ATmega32U2 DFU |`03EB:2FF0` |libusb0|
|`atmel-dfu` |ATm16U4 DFU V1.0.2 |`03EB:2FF3` |libusb0|
|`atmel-dfu` |ATm32U4DFU |`03EB:2FF4` |libusb0|
|`atmel-dfu` |*none* (AT90USB64) |`03EB:2FF9` |libusb0|
|`atmel-dfu` |AT90USB128 DFU |`03EB:2FFB` |libusb0|
|`qmk-dfu` |(keyboard name) Bootloader |As `atmel-dfu`|libusb0|
|`halfkay` |*none* |`16C0:0478` |HidUsb |
|`caterina` |Pro Micro 3.3V |`1B4F:9203` |usbser |
|`caterina` |Pro Micro 5V |`1B4F:9205` |usbser |
|`caterina` |LilyPadUSB |`1B4F:9207` |usbser |
|`caterina` |Pololu A-Star 32U4 Bootloader |`1FFB:0101` |usbser |
|`caterina` |Arduino Leonardo |`2341:0036` |usbser |
|`caterina` |Arduino Micro |`2341:0037` |usbser |
|`caterina` |Adafruit Feather 32u4 |`239A:000C` |usbser |
|`caterina` |Adafruit ItsyBitsy 32u4 3V |`239A:000D` |usbser |
|`caterina` |Adafruit ItsyBitsy 32u4 5V |`239A:000E` |usbser |
|`caterina` |Arduino Leonardo |`2A03:0036` |usbser |
|`caterina` |Arduino Micro |`2A03:0037` |usbser |
|`bootloadHID`|HIDBoot |`16C0:05DF` |HidUsb |
|`USBasp` |USBasp |`16C0:05DC` |libusbK|
|`apm32-dfu` |APM32 DFU ISP Mode |`314B:0106` |WinUSB |
|`stm32-dfu` |STM32 BOOTLOADER |`0483:DF11` |WinUSB |
|`kiibohd` |Kiibohd DFU Bootloader |`1C11:B007` |WinUSB |
|`stm32duino` |Maple 003 |`1EAF:0003` |WinUSB |

30
docs/eeprom_driver.md
View file

@ -1,4 +1,4 @@
# EEPROM Driver Configuration
# EEPROM Driver Configuration :id=eeprom-driver-configuration
The EEPROM driver can be swapped out depending on the needs of the keyboard, or whether extra hardware is present.
@ -6,15 +6,20 @@ 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.
## Vendor Driver Configuration
## Vendor Driver Configuration :id=vendor-eeprom-driver-configuration
#### STM32 L0/L1 Configuration :id=stm32l0l1-eeprom-driver-configuration
!> Resetting EEPROM using an STM32L0/L1 device takes up to 1 second for every 1kB of internal EEPROM used.
No configurable options are available.
`config.h` override | Description | Default Value
------------------------------------|--------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------
`#define STM32_ONBOARD_EEPROM_SIZE` | The size of the EEPROM to use, in bytes. Erase times can be high, so it's configurable here, if not using the default value. | Minimum required to cover base _eeconfig_ data, or `1024` if VIA is enabled.
## I2C Driver Configuration
## I2C Driver Configuration :id=i2c-eeprom-driver-configuration
Currently QMK supports 24xx-series chips over I2C. As such, requires a working i2c_master driver configuration. You can override the driver configuration via your config.h:
@ -35,13 +40,28 @@ 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>
24LC256 EEPROM | `#define EEPROM_I2C_24LC256` | <https://www.sparkfun.com/products/525>
MB85RC256V FRAM | `#define EEPROM_I2C_MB85RC256V` | <https://www.adafruit.com/product/1895>
?> If you find that the EEPROM is not cooperating, ensure you've correctly shifted up your EEPROM address by 1. For example, the datasheet might state the address as `0b01010000` -- the correct value of `EXTERNAL_EEPROM_I2C_BASE_ADDRESS` needs to be `0b10100000`.
## Transient Driver configuration
## SPI Driver Configuration :id=spi-eeprom-driver-configuration
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
!> There's no way to determine if there is an SPI EEPROM actually responding. Generally, this will result in reads of nothing but zero.
## Transient Driver configuration :id=transient-eeprom-driver-configuration
The only configurable item for the transient EEPROM driver is its size:

6
docs/es/README.md
View file

@ -9,11 +9,11 @@
## ¿Qué es el firmware QMK?
QMK (*Quantum Mechanical Keyboard*) es una comunidad open source que mantiene el firmware QMK, QMK Toolbox, qmk.fm, y estos documentos. El firmware QMK es un firmware para teclados basado en [tmk\_keyboard](http://github.com/tmk/tmk_keyboard) con algunas características útiles para controladores Atmel AVR, y más específicamente, la [línea de productos OLKB](http://olkb.com), el teclado [ErgoDox EZ](http://www.ergodox-ez.com), y la [línea de productos Clueboard](http://clueboard.co/). También ha sido portado a chips ARM chips usando ChibiOS. Lo puedes utilizar para manejar tu propio teclado ya sea cableado a mano o basado en una PCB personalizada.
QMK (*Quantum Mechanical Keyboard*) es una comunidad open source que mantiene el firmware QMK, QMK Toolbox, qmk.fm, y estos documentos. El firmware QMK es un firmware para teclados basado en [tmk\_keyboard](https://github.com/tmk/tmk_keyboard) con algunas características útiles para controladores Atmel AVR, y más específicamente, la [línea de productos OLKB](https://olkb.com), el teclado [ErgoDox EZ](https://www.ergodox-ez.com), y la [línea de productos Clueboard](https://clueboard.co/). También ha sido portado a chips ARM chips usando ChibiOS. Lo puedes utilizar para manejar tu propio teclado ya sea cableado a mano o basado en una PCB personalizada.
## Cómo conseguirlo
Si estás pensando en contribuir con un keymap, teclado, or característica a QMK, la manera más sencilla es hacer un [fork del repositorio en Github](https://github.com/qmk/qmk_firmware#fork-destination-box), y clonar tu repositorio localmente para hacer los cambios, subirlos, y abir un [Pull Request](https://github.com/qmk/qmk_firmware/pulls) desde tu fork.
Si estás pensando en contribuir con un keymap, teclado, or característica a QMK, la manera más sencilla es hacer un [fork del repositorio en GitHub](https://github.com/qmk/qmk_firmware#fork-destination-box), y clonar tu repositorio localmente para hacer los cambios, subirlos, y abir un [Pull Request](https://github.com/qmk/qmk_firmware/pulls) desde tu fork.
De cualquier manera, también puedes descargarlo directamente en formatos ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), o clonarlo via git (`git@github.com:qmk/qmk_firmware.git`), o https (`https://github.com/qmk/qmk_firmware.git`).
@ -29,4 +29,4 @@ Este ejemplo compilaría la revisión `rev4` del teclado `planck` con el keymap
## Cómo personalizar
QMK tiene montones de [características](es/features.md) para explorar, y una buena cantidad de [documentación de referencia](http://docs.qmk.fm) en la que sumergirse. Se pueden sacar provecho de la mayoría de las características modificando tu [keymap](es/keymap.md), y cambiando los [keycodes](es/keycodes.md).
QMK tiene montones de [características](es/features.md) para explorar, y una buena cantidad de [documentación de referencia](https://docs.qmk.fm) en la que sumergirse. Se pueden sacar provecho de la mayoría de las características modificando tu [keymap](es/keymap.md), y cambiando los [keycodes](es/keycodes.md).

2
docs/es/_summary.md
View file

@ -11,7 +11,7 @@
* [QMK CLI](es/cli.md)
* [Configuración de QMK CLI](es/cli_configuration.md)
* [Contribuyendo a QMK](es/contributing.md)
* [Cómo usar Github](es/getting_started_github.md)
* [Cómo usar GitHub](es/getting_started_github.md)
* [Obtener ayuda](es/getting_started_getting_help.md)
* [Cambios incompatibles](es/breaking_changes.md)

2
docs/es/hardware.md
View file

@ -1,6 +1,6 @@
# Hardware
QMK es compatible con una variedad de hardware. Si tu procesador puede ser dirigido por [LUFA](http://www.fourwalledcubicle.com/LUFA.php) o [ChibiOS](http://www.chibios.com), probablemente puedes hacer que QMK se ejecute en él. Esta sección explora cómo hacer que QMK se ejecute y se comunique con hardware de todo tipo.
QMK es compatible con una variedad de hardware. Si tu procesador puede ser dirigido por [LUFA](https://www.fourwalledcubicle.com/LUFA.php) o [ChibiOS](https://www.chibios.org), probablemente puedes hacer que QMK se ejecute en él. Esta sección explora cómo hacer que QMK se ejecute y se comunique con hardware de todo tipo.
* [Pautas de teclados](hardware_keyboard_guidelines.md)
* [Procesadores AVR](hardware_avr.md)

5
docs/es/hardware_avr.md
View file

@ -32,7 +32,7 @@ Esto creará todos los archivos necesarios para tu nuevo teclado, y rellenará l
## `readme.md`
Aquí es donde describirás tu teclado. Por favor sigue la [Plantilla del readme de teclados](documentation_templates.md#keyboard-readmemd-template) al escribir tu `readme.md`. Te animamos a colocar una imagen en la parte superior de tu `readme.md`. Por favor, utiliza un servicio externo como [Imgur](http://imgur.com) para alojar las imágenes.
Aquí es donde describirás tu teclado. Por favor sigue la [Plantilla del readme de teclados](documentation_templates.md#keyboard-readmemd-template) al escribir tu `readme.md`. Te animamos a colocar una imagen en la parte superior de tu `readme.md`. Por favor, utiliza un servicio externo como [Imgur](https://imgur.com) para alojar las imágenes.
## `<keyboard>.c`
@ -67,7 +67,7 @@ El archivo `config.h` es donde configuras el hardware y el conjunto de caracter
En la parte superior de `config.h` encontrarás ajustes relacionados con USB. Estos controlan la apariencia de tu teclado en el Sistema Operativo. Si no tienes una buena razón para cambiar debes dejar el `VENDOR_ID` como `0xFEED`. Para el `PRODUCT_ID` debes seleccionar un número que todavía no esté en uso.
Cambia las líneas de `MANUFACTURER`, `PRODUCT`, y `DESCRIPTION` para reflejar con precisión tu teclado.
Cambia las líneas de `MANUFACTURER` y `PRODUCT` para reflejar con precisión tu teclado.
```c
#define VENDOR_ID 0xFEED
@ -75,7 +75,6 @@ Cambia las líneas de `MANUFACTURER`, `PRODUCT`, y `DESCRIPTION` para reflejar c
#define DEVICE_VER 0x0001
#define MANUFACTURER Tú
#define PRODUCT mi_teclado_fantastico
#define DESCRIPTION Un teclado personalizado
```
?> Windows y macOS mostrarán el `MANUFACTURER` y `PRODUCT` en la lista de dispositivos USB. `lsusb` en Linux toma estos de la lista mantenida por el [Repositorio de ID USB](http://www.linux-usb.org/usb-ids.html) por defecto. `lsusb -v` mostrará los valores reportados por el dispositivo, y también están presentes en los registros del núcleo después de conectarlo.

1
docs/es/hardware_drivers.md
View file

@ -33,4 +33,3 @@ Soporte para hasta 2 controladores. Cada controlador implementa 2 matrices charl
## IS31FL3733
Soporte para hasta un solo controlador con espacio para expansión. Cada controlador puede controlar 192 LEDs individuales o 64 LEDs RGB. Para obtener más información sobre cómo configurar el controlador, consulta la página de [Matriz RGB](feature_rgb_matrix.md).

4
docs/es/hardware_keyboard_guidelines.md
View file

@ -98,7 +98,7 @@ Por ejemplo, si tienes un PCB de 60% que soporta ANSI e ISO podría definir los
En un esfuerzo por mantener el tamaño de repo abajo ya no estamos aceptando archivos binarios de cualquier formato, con pocas excepciones. Alojarlos en otro lugar (por ejemplo <https://imgur.com>) y enlazarlos en el `readme.md` es preferible.
Para archivos de hardware (tales como placas, casos, pcb) puedes contribuir a [qmk.fm repo](https://github.com/qmk/qmk.fm) y estarán disponibles en [qmk.fm](http://qmk.fm). Archivos descargables se almacenan en `/<teclado>/` (nombre sigue el mismo formato que el anterior), se sirven en `http://qmk.fm/<teclado>/`, y se generan páginas de `/_pages/<teclado>/` que se sirven en la misma ubicación (Los archivos .md se generan en archivos .html mediante Jekyll). Echa un vistazo a la carpeta `lets_split` para ver un ejemplo.
Para archivos de hardware (tales como placas, casos, pcb) puedes contribuir a [qmk.fm repo](https://github.com/qmk/qmk.fm) y estarán disponibles en [qmk.fm](https://qmk.fm). Archivos descargables se almacenan en `/<teclado>/` (nombre sigue el mismo formato que el anterior), se sirven en `https://qmk.fm/<teclado>/`, y se generan páginas de `/_pages/<teclado>/` que se sirven en la misma ubicación (Los archivos .md se generan en archivos .html mediante Jekyll). Echa un vistazo a la carpeta `lets_split` para ver un ejemplo.
## Predeterminados de teclado
@ -140,7 +140,7 @@ El año debe ser el primer año en que se crea el archivo. Si el trabajo se hizo
## Licencia
El núcleo de QMC está licenciado bajo la [GNU General Public License](https://www.gnu.org/licenses/licenses.en.html). Si estás enviando binarios para los procesadores AVR puedes elegir cualquiera [GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) o [GPLv3](https://www.gnu.org/licenses/gpl.html). Si estás enviando binarios para ARM procesadores debes elegir [GPL Versión 3](https://www.gnu.org/licenses/gpl.html) para cumplir con los [ChibiOS](http://www.chibios.org) licencia GPLv3.
El núcleo de QMC está licenciado bajo la [GNU General Public License](https://www.gnu.org/licenses/licenses.en.html). Si estás enviando binarios para los procesadores AVR puedes elegir cualquiera [GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) o [GPLv3](https://www.gnu.org/licenses/gpl.html). Si estás enviando binarios para ARM procesadores debes elegir [GPL Versión 3](https://www.gnu.org/licenses/gpl.html) para cumplir con los [ChibiOS](https://www.chibios.org) licencia GPLv3.
Si tu teclado hace uso de la [uGFX](https://gfx.io) características dentro de QMK debes cumplir con la [Licencia de uGFX](https://ugfx.io/license.html), que requiere una licencia comercial separada antes de vender un dispositivo que contiene uGFX.

2
docs/es/newbs.md
View file

@ -2,7 +2,7 @@
QMK es un poderoso firmware Open Source para tu teclado mecánico. Puedes utilizar QMK para personalizar tu teclado en maneras a la vez simples y potentes. Gente de todos los niveles de habilidad, desde completos novatos hasta expertos programadores, han utilizado con éxito QMK para personalizar sus teclados. Esta guía te ayudará a hacer lo mismo, sin importar tu nivel de habilidad.
¿No estás seguro de si tu teclado puede ejecutar QMK? Si es un teclado mecánico construido por ti mismo probablemente puedas. Damos soporte a [gran número de placas de hobbistas](http://qmk.fm/keyboards/), e incluso si tu teclado actual no pudiera ejecutar QMK no deberías tener problemas encontrando uno que cumpliera tus necesidades.
¿No estás seguro de si tu teclado puede ejecutar QMK? Si es un teclado mecánico construido por ti mismo probablemente puedas. Damos soporte a [gran número de placas de hobbistas](https://qmk.fm/keyboards/), e incluso si tu teclado actual no pudiera ejecutar QMK no deberías tener problemas encontrando uno que cumpliera tus necesidades.
## Visión general

2
docs/es/newbs_best_practices.md
View file

@ -6,7 +6,7 @@ Este documento procura instruir a los novatos en las mejores prácticas para ten
En este documento suponemos un par de cosas:
1. Tienes una cuenta de Github, y has hecho un [fork del repo qmk_firmware](getting_started_github.md) en tu cuenta.
1. Tienes una cuenta de GitHub, y has hecho un [fork del repo qmk_firmware](getting_started_github.md) en tu cuenta.
2. Has [configurado tu entorno de desarrollo](newbs_getting_started.md?id=environment-setup).

2
docs/es/newbs_building_firmware_configurator.md
View file

@ -21,7 +21,7 @@ Lo diré otra vez porque es importante
!> **ASEGÚRATE DE QUE SELECCIONAS LA VERSIÓN CORRECTA!**
Si se ha anunciado que tu teclado funciona con QMK pero no está en la lista, es probable que un desarrollador no se haya encargado de él aún o que todavía no hemos tenido la oportunidad de incluirlo. Abre un issue en [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) solicitando soportar ese teclado un particular, si no hay un [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) activo para ello. Hay también teclados que funcionan con QMK que están en las cuentas de github de sus manufacturantes. Acuérdate de comprobar esto también.
Si se ha anunciado que tu teclado funciona con QMK pero no está en la lista, es probable que un desarrollador no se haya encargado de él aún o que todavía no hemos tenido la oportunidad de incluirlo. Abre un issue en [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) solicitando soportar ese teclado un particular, si no hay un [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) activo para ello. Hay también teclados que funcionan con QMK que están en las cuentas de GitHub de sus manufacturantes. Acuérdate de comprobar esto también.
## Eligiendo el layout de tu teclado

2
docs/es/newbs_getting_started.md
View file

@ -43,7 +43,7 @@ instale el resto.
Necesitarás instalar MSYS2 y Git.
* Sigue las instrucciones de instalación en la [página de MSYS2](http://www.msys2.org).
* Sigue las instrucciones de instalación en la [página de MSYS2](https://www.msys2.org).
* Cierra las terminales abiertas de MSYS2 y abre una nueva termial de MSYS2 MinGW 64-bit.
* Instala Git ejecutando este comando: `pacman -S git`.

2
docs/es/newbs_learn_more_resources.md
View file

@ -6,7 +6,7 @@ Recursos de Git:
* [Excelente tutorial general](https://www.codecademy.com/learn/learn-git)
* [Juego de Git para aprender usando ejemplos](https://learngitbranching.js.org/)
* [Recursos de Git para aprender más sobre Github](getting_started_github.md)
* [Recursos de Git para aprender más sobre GitHub](getting_started_github.md)
* [Recursos de Git dirigidos específicamente a QMK](contributing.md)

8
docs/es/newbs_testing_debugging.md
View file

@ -10,8 +10,8 @@ Nota: Estos programas no los provée ni están relacionados con QMK.
* [Switch Hitter](https://elitekeyboards.com/switchhitter.php) (Sólo Windows)
* [Keyboard Viewer](https://www.imore.com/how-use-keyboard-viewer-your-mac) (Sólo Mac)
* [Keyboard Tester](http://www.keyboardtester.com) (Aplicación web)
* [Keyboard Checker](http://keyboardchecker.com) (Aplicación web)
* [Keyboard Tester](https://www.keyboardtester.com) (Aplicación web)
* [Keyboard Checker](https://keyboardchecker.com) (Aplicación web)
## Depurando
@ -41,7 +41,9 @@ Para plataformas compatibles, [QMK Toolbox](https://github.com/qmk/qmk_toolbox)
A veces, es útil imprimir mensajes de depuración desde tu [código personalizado](custom_quantum_functions.md). Hacerlo es bastante simple. Comienza incluyendo `print.h` al principio de tu fichero:
#include <print.h>
```c
#include "print.h"
```
Después de eso puedes utilzar algunas funciones print diferentes:

113
docs/faq_build.md
View file

@ -13,68 +13,29 @@ An example of using `sudo`, when your controller is ATMega32u4:
or just:
$ sudo make <keyboard>:<keymap>:dfu
$ sudo make <keyboard>:<keymap>:flash
Note that running `make` with `sudo` is generally ***not*** a good idea, and you should use one of the former methods, if possible.
### Linux `udev` Rules
On Linux, you'll need proper privileges to access the MCU. You can either use
`sudo` when flashing firmware, or place these files in `/etc/udev/rules.d/`. Once added run the following:
```console
### Linux `udev` Rules :id=linux-udev-rules
On Linux, you'll need proper privileges to communicate with the bootloader device. You can either use `sudo` when flashing firmware (not recommended), or place [this file](https://github.com/qmk/qmk_firmware/tree/master/util/udev/50-qmk.rules) into `/etc/udev/rules.d/`.
Once added, run the following:
```
sudo udevadm control --reload-rules
sudo udevadm trigger
```
**/etc/udev/rules.d/50-atmel-dfu.rules:**
```
# Atmel ATMega32U4
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", MODE:="0666"
# Atmel USBKEY AT90USB1287
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", MODE:="0666"
# Atmel ATMega32U2
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="0666"
```
**/etc/udev/rules.d/52-tmk-keyboard.rules:**
```
# tmk keyboard products https://github.com/tmk/tmk_keyboard
SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
```
**/etc/udev/rules.d/54-input-club-keyboard.rules:**
**Note:** With older versions of ModemManager (< 1.12), filtering only works when not in strict mode. The following commands can update that setting:
```
# Input Club keyboard bootloader
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666"
```
**/etc/udev/rules.d/55-caterina.rules:**
```
# ModemManager should ignore the following devices
ATTRS{idVendor}=="2a03", ENV{ID_MM_DEVICE_IGNORE}="1"
ATTRS{idVendor}=="2341", ENV{ID_MM_DEVICE_IGNORE}="1"
```
**Note:** ModemManager filtering only works when not in strict mode, the following commands can update that settings:
```console
sudo sed -i 's/--filter-policy=strict/--filter-policy=default/' /lib/systemd/system/ModemManager.service
printf '[Service]\nExecStart=\nExecStart=/usr/sbin/ModemManager --filter-policy=default' | sudo tee /etc/systemd/system/ModemManager.service.d/policy.conf
sudo systemctl daemon-reload
sudo systemctl restart ModemManager
```
**/etc/udev/rules.d/56-dfu-util.rules:**
```
# stm32duino
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0003", MODE:="0666"
# Generic stm32
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE:="0666"
```
**/etc/udev/rules.d/57-bootloadhid.rules:**
```
# bootloadHID
SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05df", MODE:="0666"
```
### Serial device is not detected in bootloader mode on Linux
Make sure your kernel has appropriate support for your device. If your device uses USB ACM, such as
Pro Micro (Atmega32u4), make sure to include `CONFIG_USB_ACM=y`. Other devices may require `USB_SERIAL` and any of its sub options.
@ -96,58 +57,8 @@ Also see this.
https://github.com/tmk/tmk_keyboard/issues/150
You can buy a really unique VID:PID here. I don't think you need this for personal use.
- http://www.obdev.at/products/vusb/license.html
- http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1
## BOOTLOADER_SIZE for AVR
Note that Teensy2.0++ bootloader size is 2048byte. Some Makefiles may have wrong comment.
```
# Boot Section Size in *bytes*
# Teensy halfKay 512
# Teensy++ halfKay 2048
# Atmel DFU loader 4096 (TMK Alt Controller)
# LUFA bootloader 4096
# USBaspLoader 2048
OPT_DEFS += -DBOOTLOADER_SIZE=2048
```
## `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)` on MacOS
This is an issue with updating on brew, causing symlinks that avr-gcc depend on getting mangled.
The solution is to remove and reinstall all affected modules.
```
brew rm avr-gcc
brew rm avr-gcc@8
brew rm dfu-programmer
brew rm dfu-util
brew rm gcc-arm-none-eabi
brew rm arm-gcc-bin@8
brew rm avrdude
brew install avr-gcc@8
brew install dfu-programmer
brew install dfu-util
brew install arm-gcc-bin@8
brew install avrdude
brew link --force avr-gcc@8
brew link --force arm-gcc-bin@8
```
### `avr-gcc` and LUFA
If you updated your `avr-gcc` and you see errors involving LUFA, for example:
`lib/lufa/LUFA/Drivers/USB/Class/Device/AudioClassDevice.h:380:5: error: 'const' attribute on function returning 'void'`
For now, you need to rollback `avr-gcc` to 8 in Homebrew.
```
brew uninstall --force avr-gcc
brew install avr-gcc@8
brew link --force avr-gcc@8
```
- https://www.obdev.at/products/vusb/license.html
- https://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1
### I just flashed my keyboard and it does nothing/keypresses don't register - it's also ARM (rev6 planck, clueboard 60, hs60v2, etc...) (Feb 2019)
Due to how EEPROM works on ARM based chips, saved settings may no longer be valid. This affects the default layers, and *may*, under certain circumstances we are still figuring out, make the keyboard unusable. Resetting the EEPROM will correct this.

232
docs/faq_debug.md
View file

@ -2,7 +2,94 @@
This page details various common questions people have about troubleshooting their keyboards.
# Debug Console
## Debugging :id=debugging
Your keyboard will output debug information if you have `CONSOLE_ENABLE = yes` in your `rules.mk`. By default the output is very limited, but you can turn on debug mode to increase the amount of debug output. Use the `DEBUG` keycode in your keymap, use the [Command](feature_command.md) feature to enable debug mode, or add the following code to your keymap.
```c
void keyboard_post_init_user(void) {
// Customise these values to desired behaviour
debug_enable=true;
debug_matrix=true;
//debug_keyboard=true;
//debug_mouse=true;
}
```
## Debugging Tools
There are two different tools you can use to debug your keyboard.
### Debugging With QMK Toolbox
For compatible platforms, [QMK Toolbox](https://github.com/qmk/qmk_toolbox) can be used to display debug messages from your keyboard.
### Debugging With hid_listen
Prefer a terminal based solution? [hid_listen](https://www.pjrc.com/teensy/hid_listen.html), provided by PJRC, can also be used to display debug messages. Prebuilt binaries for Windows,Linux,and MacOS are available.
## Sending Your Own Debug Messages
Sometimes it's useful to print debug messages from within your [custom code](custom_quantum_functions.md). Doing so is pretty simple. Start by including `print.h` at the top of your file:
```c
#include "print.h"
```
After that you can use a few different print functions:
* `print("string")`: Print a simple string.
* `uprintf("%s string", var)`: Print a formatted string
* `dprint("string")` Print a simple string, but only when debug mode is enabled
* `dprintf("%s string", var)`: Print a formatted string, but only when debug mode is enabled
## Debug Examples
Below is a collection of real world debugging examples. For additional information, refer to [Debugging/Troubleshooting QMK](faq_debug.md).
### Which matrix position is this keypress?
When porting, or when attempting to diagnose pcb issues, it can be useful to know if a keypress is scanned correctly. To enable logging for this scenario, add the following code to your keymaps `keymap.c`
```c
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
// If console is enabled, it will print the matrix position and status of each key pressed
#ifdef CONSOLE_ENABLE
uprintf("KL: kc: 0x%04X, col: %u, row: %u, pressed: %b, time: %u, interrupt: %b, count: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed, record->event.time, record->tap.interrupted, record->tap.count);
#endif
return true;
}
```
Example output
```text
Waiting for device:.......
Listening:
KL: kc: 169, col: 0, row: 0, pressed: 1
KL: kc: 169, col: 0, row: 0, pressed: 0
KL: kc: 174, col: 1, row: 0, pressed: 1
KL: kc: 174, col: 1, row: 0, pressed: 0
KL: kc: 172, col: 2, row: 0, pressed: 1
KL: kc: 172, col: 2, row: 0, pressed: 0
```
### How long did it take to scan for a keypress?
When testing performance issues, it can be useful to know the frequency at which the switch matrix is being scanned. To enable logging for this scenario, add the following code to your keymaps `config.h`
```c
#define DEBUG_MATRIX_SCAN_RATE
```
Example output
```text
> matrix scan frequency: 315
> matrix scan frequency: 313
> matrix scan frequency: 316
> matrix scan frequency: 316
> matrix scan frequency: 316
> matrix scan frequency: 316
```
## `hid_listen` Can't Recognize Device
When debug console of your device is not ready you will see like this:
@ -11,7 +98,7 @@ When debug console of your device is not ready you will see like this:
Waiting for device:.........
```
once the device is plugged in then *hid_listen* finds it you will get this message:
Once the device is plugged in then *hid_listen* finds it you will get this message:
```
Waiting for new device:.........................
@ -20,143 +107,12 @@ Listening:
If you can't get this 'Listening:' message try building with `CONSOLE_ENABLE=yes` in [Makefile]
You may need privilege to access the device on OS like Linux.
- try `sudo hid_listen`
You may need privileges to access the device an OS like Linux. Try `sudo hid_listen`.
## Can't Get Message on Console
Check:
- *hid_listen* finds your device. See above.
- Enable debug with pressing **Magic**+d. See [Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands).
- set `debug_enable=true`. See [Testing and Debugging](newbs_testing_debugging.md#debugging)
- try using 'print' function instead of debug print. See **common/print.h**.
- disconnect other devices with console function. See [Issue #97](https://github.com/tmk/tmk_keyboard/issues/97).
## Linux or UNIX Like System Requires Super User Privilege
Just use 'sudo' to execute *hid_listen* with privilege.
```
$ sudo hid_listen
```
Or add an *udev rule* for TMK devices with placing a file in rules directory. The directory may vary on each system.
File: /etc/udev/rules.d/52-tmk-keyboard.rules(in case of Ubuntu)
```
# tmk keyboard products https://github.com/tmk/tmk_keyboard
SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
```
***
# Miscellaneous
## Safety Considerations
You probably don't want to "brick" your keyboard, making it impossible
to rewrite firmware onto it. Here are some of the parameters to show
what things are (and likely aren't) too risky.
- If your keyboard map does not include RESET, then, to get into DFU
mode, you will need to press the reset button on the PCB, which
requires unscrewing the bottom.
- Messing with tmk_core / common files might make the keyboard
inoperable
- Too large a .hex file is trouble; `make dfu` will erase the block,
test the size (oops, wrong order!), which errors out, failing to
flash the keyboard, leaving it in DFU mode.
- To this end, note that the maximum .hex file size on Planck is
7000h (28672 decimal)
```
Linking: .build/planck_rev4_cbbrowne.elf [OK]
Creating load file for Flash: .build/planck_rev4_cbbrowne.hex [OK]
Size after:
text data bss dec hex filename
0 22396 0 22396 577c planck_rev4_cbbrowne.hex
```
- The above file is of size 22396/577ch, which is less than
28672/7000h
- As long as you have a suitable alternative .hex file around, you
can retry, loading that one
- Some of the options you might specify in your keyboard's Makefile
consume extra memory; watch out for BOOTMAGIC_ENABLE,
MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE
- DFU tools do /not/ allow you to write into the bootloader (unless
you throw in extra fruit salad of options), so there is little risk
there.
- EEPROM has around a 100000 write cycle. You shouldn't rewrite the
firmware repeatedly and continually; that'll burn the EEPROM
eventually.
## NKRO Doesn't work
First you have to compile firmware with this build option `NKRO_ENABLE` in **Makefile**.
Try `Magic` **N** command(`LShift+RShift+N` by default) when **NKRO** still doesn't work. You can use this command to toggle between **NKRO** and **6KRO** mode temporarily. In some situations **NKRO** doesn't work you need to switch to **6KRO** mode, in particular when you are in BIOS.
If your firmware built with `BOOTMAGIC_ENABLE` you need to turn its switch on by `BootMagic` **N** command(`Space+N` by default). This setting is stored in EEPROM and kept over power cycles.
https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch
## TrackPoint Needs Reset Circuit (PS/2 Mouse Support)
Without reset circuit you will have inconsistent result due to improper initialize of the hardware. See circuit schematic of TPM754.
- http://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
- http://www.mikrocontroller.net/attachment/52583/tpm754.pdf
## Can't Read Column of Matrix Beyond 16
Use `1UL<<16` instead of `1<<16` in `read_cols()` in [matrix.h] when your columns goes beyond 16.
In C `1` means one of [int] type which is [16 bit] in case of AVR so you can't shift left more than 15. You will get unexpected zero when you say `1<<16`. You have to use [unsigned long] type with `1UL`.
http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
## Special Extra Key Doesn't Work (System, Audio Control Keys)
You need to define `EXTRAKEY_ENABLE` in `rules.mk` to use them in QMK.
```
EXTRAKEY_ENABLE = yes # Audio control and System control
```
## Wakeup from Sleep Doesn't Work
In Windows check `Allow this device to wake the computer` setting in Power **Management property** tab of **Device Manager**. Also check BIOS setting.
Pressing any key during sleep should wake host.
## Using Arduino?
**Note that Arduino pin naming is different from actual chip.** For example, Arduino pin `D0` is not `PD0`. Check circuit with its schematics yourself.
- http://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
- http://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf
Arduino Leonardo and micro have **ATMega32U4** and can be used for TMK, though Arduino bootloader may be a problem.
## Enabling JTAG
By default, the JTAG debugging interface is disabled as soon as the keyboard starts up. JTAG-capable MCUs come from the factory with the `JTAGEN` fuse set, and it takes over certain pins of the MCU that the board may be using for the switch matrix, LEDs, etc.
If you would like to keep JTAG enabled, just add the following to your `config.h`:
```c
#define NO_JTAG_DISABLE
```
## USB 3 Compatibility
I heard some people have a problem with USB 3 port, try USB 2 port.
## Mac Compatibility
### OS X 10.11 and Hub
https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
## Problem on BIOS (UEFI)/Resume (Sleep & Wake)/Power Cycles
Some people reported their keyboard stops working on BIOS and/or after resume(power cycles).
As of now root of its cause is not clear but some build options seem to be related. In Makefile try to disable those options like `CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE` and/or others.
https://github.com/tmk/tmk_keyboard/issues/266
https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
- Enable debug by pressing **Magic**+d. See [Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands).
- Set `debug_enable=true`. See [Debugging](#debugging)
- Try using `print` function instead of debug print. See **common/print.h**.
- Disconnect other devices with console function. See [Issue #97](https://github.com/tmk/tmk_keyboard/issues/97).

2
docs/faq_general.md
View file

@ -34,7 +34,7 @@ Additionally, you can find additional `git` and GitHub related links [here](newb
Awesome! Open up a Pull Request for it. We'll review the code, and merge it!
### What if I want to do brand it with `QMK`?
### What if I want to brand it with `QMK`?
That's amazing! We would love to assist you with that!

10
docs/faq_keymap.md
View file

@ -11,7 +11,7 @@ Keycodes are actually defined in [common/keycode.h](https://github.com/qmk/qmk_f
There are 3 standard keyboard layouts in use around the world- ANSI, ISO, and JIS. North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS. Regions not mentioned typically use either ANSI or ISO. The keycodes corresponding to these layouts are shown here:
<!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
<!-- Source for this image: https://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
![Keyboard Layout Image](https://i.imgur.com/5wsh5wM.png)
## How Can I Make Custom Names For Complex Keycodes?
@ -42,8 +42,8 @@ The key found on most modern keyboards that is located between `KC_RGUI` and `KC
Use keycode for Print Screen(`KC_PSCREEN` or `KC_PSCR`) instead of `KC_SYSREQ`. Key combination of 'Alt + Print Screen' is recognized as 'System request'.
See [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) and
* http://en.wikipedia.org/wiki/Magic_SysRq_key
* http://en.wikipedia.org/wiki/System_request
* https://en.wikipedia.org/wiki/Magic_SysRq_key
* https://en.wikipedia.org/wiki/System_request
## Power Keys Aren't Working
@ -60,13 +60,13 @@ Modifier keys or layers can be stuck unless layer switching is configured proper
For Modifier keys and layer actions you have to place `KC_TRANS` on same position of destination layer to unregister the modifier key or return to previous layer on release event.
* https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
* http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
* 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](http://deskthority.net/wiki/Alps_SKCL_Lock). You can enable it by adding this to your `config.h`:
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`:
```
#define LOCKING_SUPPORT_ENABLE

117
docs/faq_misc.md Normal file
View file

@ -0,0 +1,117 @@
# Miscellaneous FAQ
## How do I test my keyboard? :id=testing
Testing your keyboard is usually pretty straightforward. Press every single key and make sure it sends the keys you expect. You can use [QMK Configurator](https://config.qmk.fm/#/test/)'s test mode to check your keyboard, even if it doesn't run QMK.
## Safety Considerations
You probably don't want to "brick" your keyboard, making it impossible
to rewrite firmware onto it. Here are some of the parameters to show
what things are (and likely aren't) too risky.
- If your keyboard map does not include RESET, then, to get into DFU
mode, you will need to press the reset button on the PCB, which
requires unscrewing the bottom.
- Messing with tmk_core / common files might make the keyboard
inoperable
- Too large a .hex file is trouble; `make dfu` will erase the block,
test the size (oops, wrong order!), which errors out, failing to
flash the keyboard, leaving it in DFU mode.
- To this end, note that the maximum .hex file size on e.g. Planck
is 7000h (28672 decimal)
```
Linking: .build/planck_rev4_cbbrowne.elf [OK]
Creating load file for Flash: .build/planck_rev4_cbbrowne.hex [OK]
Size after:
text data bss dec hex filename
0 22396 0 22396 577c planck_rev4_cbbrowne.hex
```
- The above file is of size 22396/577ch, which is less than
28672/7000h
- As long as you have a suitable alternative .hex file around, you
can retry, loading that one
- Some of the options you might specify in your keyboard's Makefile
consume extra memory; watch out for BOOTMAGIC_ENABLE,
MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE
- DFU tools do /not/ allow you to write into the bootloader (unless
you throw in an extra fruit salad of options), so there is little risk
there.
- EEPROM has around a 100000 (100k) write cycle. You shouldn't rewrite
the firmware repeatedly and continually; that'll burn the EEPROM
eventually.
## NKRO Doesn't work
First you have to compile firmware with the build option `NKRO_ENABLE` in **Makefile**.
Try `Magic` **N** command(`LShift+RShift+N` by default) when **NKRO** still doesn't work. You can use this command to toggle between **NKRO** and **6KRO** mode temporarily. In some situations **NKRO** doesn't work and you will need to switch to **6KRO** mode, in particular when you are in BIOS.
If your firmware was built with `BOOTMAGIC_ENABLE` you need to turn its switch on by `BootMagic` **N** command(`Space+N` by default). This setting is stored in EEPROM and kept over power cycles.
https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch
## TrackPoint Needs Reset Circuit (PS/2 Mouse Support)
Without reset circuit you will have inconsistent result due to improper initialization of the hardware. See circuit schematic of TPM754:
- https://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
- https://www.mikrocontroller.net/attachment/52583/tpm754.pdf
## Can't Read Column of Matrix Beyond 16
Use `1UL<<16` instead of `1<<16` in `read_cols()` in [matrix.h] when your columns goes beyond 16.
In C `1` means one of [int] type which is [16 bit] in case of AVR, so you can't shift left more than 15. Thus, calculating `1<<16` will unexpectedly equal zero. To work around this, you have to use [unsigned long] type with `1UL`.
https://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
## Special Extra Key Doesn't Work (System, Audio Control Keys)
You need to define `EXTRAKEY_ENABLE` in `rules.mk` to use them in QMK.
```
EXTRAKEY_ENABLE = yes # Audio control and System control
```
## Wake from Sleep Doesn't Work
In Windows check `Allow this device to wake the computer` setting in **Power Management** property tab of **Device Manager**. Also check your BIOS settings. Pressing any key during sleep should wake host.
## Using Arduino?
**Note that Arduino pin naming is different from actual chip.** For example, Arduino pin `D0` is not `PD0`. Check circuit with its schematics yourself.
- https://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
- https://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf
Arduino Leonardo and micro have **ATMega32U4** and can be used for TMK, though Arduino bootloader may be a problem.
## Enabling JTAG
By default, the JTAG debugging interface is disabled as soon as the keyboard starts up. JTAG-capable MCUs come from the factory with the `JTAGEN` fuse set, and it takes over certain pins of the MCU that the board may be using for the switch matrix, LEDs, etc.
If you would like to keep JTAG enabled, just add the following to your `config.h`:
```c
#define NO_JTAG_DISABLE
```
## USB 3 Compatibility
Some problems can be fixed by switching from a USB 3.x port to a USB 2.0 port.
## Mac Compatibility
### OS X 10.11 and Hub
See here: https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
## Problem in BIOS (UEFI) Setup/Resume (Sleep & Wake)/Power Cycles
Some people reported their keyboard stops working in BIOS and/or after resume(power cycles).
As of now the root cause is not clear, but some build options seem to be related. In Makefile, try to disable options like `CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE` and/or others.
More info:
- https://github.com/tmk/tmk_keyboard/issues/266
- https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778

33
docs/feature_advanced_keycodes.md
View file

@ -2,21 +2,24 @@
These allow you to combine a modifier with a keycode. When pressed, the keydown event for the modifier, then `kc` will be sent. On release, the keyup event for `kc`, then the modifier will be sent.
|Key |Aliases |Description |
|----------|-------------------------------|----------------------------------------------------|
|`LCTL(kc)`|`C(kc)` |Hold Left Control and press `kc` |
|`LSFT(kc)`|`S(kc)` |Hold Left Shift and press `kc` |
|`LALT(kc)`|`A(kc)`, `LOPT(kc)` |Hold Left Alt and press `kc` |
|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc` |
|`RCTL(kc)`| |Hold Right Control and press `kc` |
|`RSFT(kc)`| |Hold Right Shift and press `kc` |
|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)` |Hold Right Alt and press `kc` |
|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)` |Hold Right GUI and press `kc` |
|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)` |Hold Left Shift and GUI and press `kc` |
|`LCA(kc)` | |Hold Left Control and Alt and press `kc` |
|`LCAG(kc)`| |Hold Left Control, Alt and GUI and press `kc` |
|`MEH(kc)` | |Hold Left Control, Shift and Alt and press `kc` |
|`HYPR(kc)`| |Hold Left Control, Shift, Alt and GUI and press `kc`|
|Key |Aliases |Description |
|----------|-------------------------------|------------------------------------------------------|
|`LCTL(kc)`|`C(kc)` |Hold Left Control and press `kc` |
|`LSFT(kc)`|`S(kc)` |Hold Left Shift and press `kc` |
|`LALT(kc)`|`A(kc)`, `LOPT(kc)` |Hold Left Alt and press `kc` |
|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc` |
|`RCTL(kc)`| |Hold Right Control and press `kc` |
|`RSFT(kc)`| |Hold Right Shift and press `kc` |
|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)` |Hold Right Alt and press `kc` |
|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)` |Hold Right GUI and press `kc` |
|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)` |Hold Left Shift and GUI and press `kc` |
|`LCA(kc)` | |Hold Left Control and Alt and press `kc` |
|`LSA(kc)` | |Hold Left Shift and Left Alt and press `kc` |
|`RSA(kc)` |`SAGR(kc)` |Hold Right Shift and Right Alt (AltGr) and press `kc` |
|`RCS(kc)` | |Hold Right Control and Right Shift and press `kc` |
|`LCAG(kc)`| |Hold Left Control, Alt and GUI and press `kc` |
|`MEH(kc)` | |Hold Left Control, Shift and Alt and press `kc` |
|`HYPR(kc)`| |Hold Left Control, Shift, Alt and GUI and press `kc` |
You can also chain them, for example `LCTL(LALT(KC_DEL))` or `C(A(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress.

44
docs/feature_auto_shift.md
View file

@ -15,25 +15,31 @@ problem.
When you tap a key, it stays depressed for a short period of time before it is
then released. This depressed time is a different length for everyone. Auto Shift
defines a constant `AUTO_SHIFT_TIMEOUT` which is typically set to twice your
normal pressed state time. When you press a key, a timer starts and then stops
when you release the key. If the time depressed is greater than or equal to the
`AUTO_SHIFT_TIMEOUT`, then a shifted version of the key is emitted. If the time
is less than the `AUTO_SHIFT_TIMEOUT` time, then the normal state is emitted.
normal pressed state time. When you press a key, a timer starts, and if you
have not released the key after the `AUTO_SHIFT_TIMEOUT` period, then a shifted
version of the key is emitted. If the time is less than the `AUTO_SHIFT_TIMEOUT`
time, or you press another key, then the normal state is emitted.
If `AUTO_SHIFT_REPEAT` is defined, there is keyrepeat support. Holding the key
down will repeat the shifted key, though this can be disabled with
`AUTO_SHIFT_NO_AUTO_REPEAT`. If you want to repeat the normal key, then tap it
once then immediately (within `TAPPING_TERM`) hold it down again (this works
with the shifted value as well if auto-repeat is disabled).
## Are There Limitations to Auto Shift?
Yes, unfortunately.
1. Key repeat will cease to work. For example, before if you wanted 20 'a'
characters, you could press and hold the 'a' key for a second or two. This no
longer works with Auto Shift because it is timing your depressed time instead
of emitting a depressed key state to your operating system.
2. You will have characters that are shifted when you did not intend on shifting, and
other characters you wanted shifted, but were not. This simply comes down to
practice. As we get in a hurry, we think we have hit the key long enough
for a shifted version, but we did not. On the other hand, we may think we are
tapping the keys, but really we have held it for a little longer than
anticipated.
You will have characters that are shifted when you did not intend on shifting, and
other characters you wanted shifted, but were not. This simply comes down to
practice. As we get in a hurry, we think we have hit the key long enough for a
shifted version, but we did not. On the other hand, we may think we are tapping
the keys, but really we have held it for a little longer than anticipated.
Additionally, with keyrepeat the desired shift state can get mixed up. It will
always 'belong' to the last key pressed. For example, keyrepeating a capital
and then tapping something lowercase (whether or not it's an Auto Shift key)
will result in the capital's *key* still being held, but shift not.
## How Do I Enable Auto Shift?
@ -103,6 +109,14 @@ Do not Auto Shift numeric keys, zero through nine.
Do not Auto Shift alpha characters, which include A through Z.
### AUTO_SHIFT_REPEAT (simple define)
Enables keyrepeat.
### AUTO_SHIFT_NO_AUTO_REPEAT (simple define)
Disables automatically keyrepeating when `AUTO_SHIFT_TIMEOUT` is exceeded.
## Using Auto Shift Setup
This will enable you to define three keys temporarily to increase, decrease and report your `AUTO_SHIFT_TIMEOUT`.
@ -139,7 +153,7 @@ completely normal and with no intention of shifted keys.
`KC_ASRP`. The keyboard will type by itself the value of your
`AUTO_SHIFT_TIMEOUT`.
7. Update `AUTO_SHIFT_TIMEOUT` in your `config.h` with the value reported.
8. Remove `AUTO_SHIFT_SETUP` from your `config.h`.
8. Add `AUTO_SHIFT_NO_SETUP` to your `config.h`.
9. Remove the key bindings `KC_ASDN`, `KC_ASUP` and `KC_ASRP`.
10. Compile and upload your new firmware.

250
docs/feature_backlight.md
View file

@ -1,4 +1,4 @@
# Backlighting
# Backlighting :id=backlighting
Many keyboards support backlit keys by way of individual LEDs placed through or underneath the keyswitches. This feature is distinct from both the [RGB underglow](feature_rgblight.md) and [RGB matrix](feature_rgb_matrix.md) features as it usually allows for only a single colour per switch, though you can obviously install multiple different single coloured LEDs on a keyboard.
@ -6,103 +6,107 @@ QMK is able to control the brightness of these LEDs by switching them on and off
The MCU can only supply so much current to its GPIO pins. Instead of powering the backlight directly from the MCU, the backlight pin is connected to a transistor or MOSFET that switches the power to the LEDs.
## Feature Configuration
Most keyboards have backlighting enabled by default if they support it, but if it is not working for you, check that your `rules.mk` includes the following:
```makefile
BACKLIGHT_ENABLE = yes
```
## Keycodes
Once enabled the following keycodes below can be used to change the backlight level.
## Keycodes :id=keycodes
|Key |Description |
|---------|------------------------------------------|
|`BL_TOGG`|Turn the backlight on or off |
|`BL_STEP`|Cycle through backlight levels |
|`BL_ON` |Set the backlight to max brightness |
|`BL_OFF` |Turn the backlight off |
|`BL_INC` |Increase the backlight level |
|`BL_DEC` |Decrease the backlight level |
|`BL_BRTG`|Toggle backlight breathing |
Once enabled, the following keycodes below can be used to change the backlight level.
## Backlight Functions
|Key |Description |
|---------|-----------------------------------|
|`BL_TOGG`|Turn the backlight on or off |
|`BL_STEP`|Cycle through backlight levels |
|`BL_ON` |Set the backlight to max brightness|
|`BL_OFF` |Turn the backlight off |
|`BL_INC` |Increase the backlight level |
|`BL_DEC` |Decrease the backlight level |
|`BL_BRTG`|Toggle backlight breathing |
|Function |Description |
|----------|-----------------------------------------------------------|
|`backlight_toggle()` |Turn the backlight on or off |
|`backlight_enable()` |Turn the backlight on |
|`backlight_disable()` |Turn the backlight off |
|`backlight_step()` |Cycle through backlight levels |
|`backlight_increase()` |Increase the backlight level |
|`backlight_decrease()` |Decrease the backlight level |
|`backlight_level(x)` |Sets the backlight level to specified level |
|`get_backlight_level()` |Return the current backlight level |
|`is_backlight_enabled()`|Return whether the backlight is currently on |
## Functions :id=functions
### Backlight Breathing Functions
These functions can be used to change the backlighting in custom code:
|Function |Description |
|----------|---------------------------------------------------|
|`breathing_toggle()` |Turn the backlight breathing on or off |
|`breathing_enable()` |Turns on backlight breathing |
|`breathing_disable()` |Turns off backlight breathing |
|Function |Description |
|------------------------|--------------------------------------------|
|`backlight_toggle()` |Turn the backlight on or off |
|`backlight_enable()` |Turn the backlight on |
|`backlight_disable()` |Turn the backlight off |
|`backlight_step()` |Cycle through backlight levels |
|`backlight_increase()` |Increase the backlight level |
|`backlight_decrease()` |Decrease the backlight level |
|`backlight_level(x)` |Sets the backlight level to specified level |
|`get_backlight_level()` |Return the current backlight level |
|`is_backlight_enabled()`|Return whether the backlight is currently on|
## Driver Configuration
If backlight breathing is enabled (see below), the following functions are also available:
|Function |Description |
|---------------------|--------------------------------------|
|`breathing_toggle()` |Turn the backlight breathing on or off|
|`breathing_enable()` |Turns on backlight breathing |
|`breathing_disable()`|Turns off backlight breathing |
## Configuration :id=configuration
To select which driver to use, configure your `rules.mk` with the following:
```makefile
BACKLIGHT_DRIVER = software # Valid driver values are 'pwm,software,no'
BACKLIGHT_DRIVER = software
```
See below for help on individual drivers.
Valid driver values are `pwm`, `software`, `custom` or `no`. See below for help on individual drivers.
## Common Driver Configuration
To configure the backlighting, `#define` these in your `config.h`:
To change the behavior of the backlighting, `#define` these in your `config.h`:
| Define | Default | Description |
|------------------------|---------------|-------------------------------------------------------------------------------------------------------------------|
| `BACKLIGHT_PIN` | *Not defined* | The pin that controls the LED(s) |
| `BACKLIGHT_LEVELS` | `3` | The number of brightness levels (maximum 31 excluding off) |
| `BACKLIGHT_CAPS_LOCK` | *Not defined* | Enable Caps Lock indicator using backlight (for keyboards without dedicated LED) |
| `BACKLIGHT_BREATHING` | *Not defined* | Enable backlight breathing, if supported |
| `BREATHING_PERIOD` | `6` | The length of one backlight "breath" in seconds |
| `BACKLIGHT_ON_STATE` | `1` | The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low |
| `BACKLIGHT_LIMIT_VAL ` | `255` | The maximum duty cycle of the backlight -- `255` allows for full brightness, any lower will decrease the maximum. |
|Define |Default |Description |
|---------------------|-------------|--------------------------------------------------------------------------------------|
|`BACKLIGHT_LEVELS` |`3` |The number of brightness levels (maximum 31 excluding off) |
|`BACKLIGHT_CAPS_LOCK`|*Not defined*|Enable Caps Lock indicator using backlight (for keyboards without dedicated LED) |
|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported |
|`BREATHING_PERIOD` |`6` |The length of one backlight "breath" in seconds |
|`BACKLIGHT_ON_STATE` |`0` |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low |
Unless you are designing your own keyboard, you generally should not need to change the `BACKLIGHT_PIN` or `BACKLIGHT_ON_STATE`.
### Backlight On State
### Backlight On State :id=backlight-on-state
Most backlight circuits are driven by an N-channel MOSFET or NPN transistor. This means that to turn the transistor *on* and light the LEDs, you must drive the backlight pin, connected to the gate or base, *high*.
Sometimes, however, a P-channel MOSFET, or a PNP transistor is used. In this case, when the transistor is on, the pin is driven *low* instead.
This functionality is configured at the keyboard level with the `BACKLIGHT_ON_STATE` define.
## AVR driver
### AVR Driver :id=avr-driver
The `pwm` driver is configured by default, however the equivalent setting within `rules.mk` would be:
On AVR boards, the default driver currently sniffs the configuration to pick the best scenario. The driver is configured by default, however the equivalent setting within rules.mk would be:
```makefile
BACKLIGHT_DRIVER = pwm
```
### Caveats
#### Caveats :id=avr-caveats
Hardware PWM is supported according to the following table:
On AVR boards, QMK automatically decides which driver to use according to the following table:
|Backlight Pin|AT90USB64/128|ATmega16/32U4|ATmega16/32U2|ATmega32A|ATmega328P|
|-------------|-------------|-------------|-------------|---------|----------|
|`B1` | | | | |Timer 1 |
|`B2` | | | | |Timer 1 |
|`B5` |Timer 1 |Timer 1 | | | |
|`B6` |Timer 1 |Timer 1 | | | |
|`B7` |Timer 1 |Timer 1 |Timer 1 | | |
|`C4` |Timer 3 | | | | |
|`C5` |Timer 3 | |Timer 1 | | |
|`C6` |Timer 3 |Timer 3 |Timer 1 | | |
|`D4` | | | |Timer 1 | |
|`D5` | | | |Timer 1 | |
|Backlight Pin|AT90USB64/128|ATmega16/32U4|ATmega16/32U2|ATmega32A|ATmega328/P|
|-------------|-------------|-------------|-------------|---------|-----------|
|`B1` | | | | |Timer 1 |
|`B2` | | | | |Timer 1 |
|`B5` |Timer 1 |Timer 1 | | | |
|`B6` |Timer 1 |Timer 1 | | | |
|`B7` |Timer 1 |Timer 1 |Timer 1 | | |
|`C4` |Timer 3 | | | | |
|`C5` |Timer 3 | |Timer 1 | | |
|`C6` |Timer 3 |Timer 3 |Timer 1 | | |
|`D4` | | | |Timer 1 | |
|`D5` | | | |Timer 1 | |
All other pins will use software PWM. If the [Audio](feature_audio.md) feature is disabled or only using one timer, the backlight PWM can be triggered by a hardware timer:
All other pins will use timer-assisted software PWM:
|Audio Pin|Audio Timer|Software PWM Timer|
|---------|-----------|------------------|
@ -113,44 +117,9 @@ All other pins will use software PWM. If the [Audio](feature_audio.md) feature i
|`B6` |Timer 1 |Timer 3 |
|`B7` |Timer 1 |Timer 3 |
When both timers are in use for Audio, the backlight PWM will not use a hardware timer, but will instead be triggered during the matrix scan. In this case, breathing is not supported, and the backlight might flicker, because the PWM computation may not be called with enough timing precision.
When both timers are in use for Audio, the backlight PWM cannot use a hardware timer, and will instead be triggered during the matrix scan. In this case, breathing is not supported, and the backlight might flicker, because the PWM computation may not be called with enough timing precision.
### AVR Configuration
To change the behavior of the backlighting, `#define` these in your `config.h`:
|Define |Default |Description |
|---------------------|-------------|-------------------------------------------------------------------------------------------------------------|
|`BACKLIGHT_PIN` |`B7` |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this|
|`BACKLIGHT_PINS` |*Not defined*|experimental: see below for more information |
|`BACKLIGHT_LEVELS` |`3` |The number of brightness levels (maximum 31 excluding off) |
|`BACKLIGHT_CAPS_LOCK`|*Not defined*|Enable Caps Lock indicator using backlight (for keyboards without dedicated LED) |
|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported |
|`BREATHING_PERIOD` |`6` |The length of one backlight "breath" in seconds |
|`BACKLIGHT_ON_STATE` |`1` |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low |
### Backlight On State
Most backlight circuits are driven by an N-channel MOSFET or NPN transistor. This means that to turn the transistor *on* and light the LEDs, you must drive the backlight pin, connected to the gate or base, *high*.
Sometimes, however, a P-channel MOSFET, or a PNP transistor is used. In this case, when the transistor is on, the pin is driven *low* instead.
This functionality is configured at the keyboard level with the `BACKLIGHT_ON_STATE` define.
### Multiple backlight pins
Most keyboards have only one backlight pin which control all backlight LEDs (especially if the backlight is connected to an hardware PWM pin).
In software PWM, it is possible to define multiple backlight pins. All those pins will be turned on and off at the same time during the PWM duty cycle.
This feature allows to set for instance the Caps Lock LED (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped LCTRL in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on.
To activate multiple backlight pins, you need to add something like this to your user `config.h`:
```c
#define BACKLIGHT_LED_COUNT 2
#undef BACKLIGHT_PIN
#define BACKLIGHT_PINS { F5, B2 }
```
### Hardware PWM Implementation
#### Hardware PWM Implementation :id=hardware-pwm-implementation
When using the supported pins for backlighting, QMK will use a hardware timer configured to output a PWM signal. This timer will count up to `ICRx` (by default `0xFFFF`) before resetting to 0.
The desired brightness is calculated and stored in the `OCRxx` register. When the counter reaches this value, the backlight pin will go low, and is pulled high again when the counter resets.
@ -159,7 +128,7 @@ In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus th
The breathing effect is achieved by registering an interrupt handler for `TIMER1_OVF_vect` that is called whenever the counter resets, roughly 244 times per second.
In this handler, the value of an incrementing counter is mapped onto a precomputed brightness curve. To turn off breathing, the interrupt handler is simply disabled, and the brightness reset to the level stored in EEPROM.
### Timer Assisted PWM Implementation
#### Timer Assisted PWM Implementation :id=timer-assisted-implementation
When `BACKLIGHT_PIN` is not set to a hardware backlight pin, QMK will use a hardware timer configured to trigger software interrupts. This time will count up to `ICRx` (by default `0xFFFF`) before resetting to 0.
When resetting to 0, the CPU will fire an OVF (overflow) interrupt that will turn the LEDs on, starting the duty cycle.
@ -168,81 +137,82 @@ In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus th
The breathing effect is the same as in the hardware PWM implementation.
## ARM Driver
### ARM Driver :id=arm-configuration
While still in its early stages, ARM backlight support aims to eventually have feature parity with AVR. The `pwm` driver is configured by default, however the equivalent setting within `rules.mk` would be:
While still in its early stages, ARM backlight support aims to eventually have feature parity with AVR. The driver is configured by default, however the equivalent setting within rules.mk would be:
```makefile
BACKLIGHT_DRIVER = pwm
```
### Caveats
#### ChibiOS Configuration :id=arm-configuration
The following `#define`s apply only to ARM-based keyboards:
|Define |Default|Description |
|-----------------------|-------|-----------------------------------|
|`BACKLIGHT_PWM_DRIVER` |`PWMD4`|The PWM driver to use |
|`BACKLIGHT_PWM_CHANNEL`|`3` |The PWM channel to use |
|`BACKLIGHT_PAL_MODE` |`2` |The pin alternative function to use|
See the ST datasheet for your particular MCU to determine these values. Unless you are designing your own keyboard, you generally should not need to change them.
#### Caveats :id=arm-caveats
Currently only hardware PWM is supported, not timer assisted, and does not provide automatic configuration.
?> Backlight support for STMF072 has had limited testing, YMMV. If unsure, set `BACKLIGHT_ENABLE = no` in your rules.mk.
### Software PWM Driver :id=software-pwm-driver
### ARM Configuration
In this mode, PWM is "emulated" while running other keyboard tasks. It offers maximum hardware compatibility without extra platform configuration. The tradeoff is the backlight might jitter when the keyboard is busy. To enable, add this to your `rules.mk`:
To change the behavior of the backlighting, `#define` these in your `config.h`:
|Define |Default |Description |
|------------------------|-------------|-------------------------------------------------------------------------------------------------------------|
|`BACKLIGHT_PIN` |`B7` |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this|
|`BACKLIGHT_PWM_DRIVER` |`PWMD4` |The PWM driver to use, see ST datasheets for pin to PWM timer mapping. Unless you are designing your own keyboard, you shouldn't need to change this|
|`BACKLIGHT_PWM_CHANNEL` |`3` |The PWM channel to use, see ST datasheets for pin to PWM channel mapping. Unless you are designing your own keyboard, you shouldn't need to change this|
|`BACKLIGHT_PAL_MODE` |`2` |The pin alternative function to use, see ST datasheets for pin AF mapping. Unless you are designing your own keyboard, you shouldn't need to change this|
## Software PWM Driver :id=software-pwm-driver
Emulation of PWM while running other keyboard tasks, it offers maximum hardware compatibility without extra platform configuration. The tradeoff is the backlight might jitter when the keyboard is busy. To enable, add this to your rules.mk:
```makefile
BACKLIGHT_DRIVER = software
```
### Software PWM Configuration
To change the behavior of the backlighting, `#define` these in your `config.h`:
|Define |Default |Description |
|-----------------|-------------|-------------------------------------------------------------------------------------------------------------|
|`BACKLIGHT_PIN` |`B7` |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this|
|`BACKLIGHT_PINS` |*Not defined*|experimental: see below for more information |
### Multiple backlight pins
#### Multiple Backlight Pins :id=multiple-backlight-pins
Most keyboards have only one backlight pin which control all backlight LEDs (especially if the backlight is connected to an hardware PWM pin).
In software PWM, it is possible to define multiple backlight pins. All those pins will be turned on and off at the same time during the PWM duty cycle.
This feature allows to set for instance the Caps Lock LED (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped LCTRL in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on.
In software PWM, it is possible to define multiple backlight pins, which will be turned on and off at the same time during the PWM duty cycle.
To activate multiple backlight pins, you need to add something like this to your user `config.h`:
This feature allows to set, for instance, the Caps Lock LED's (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped Control in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on, as it is usually wired to a separate pin from the backlight.
To activate multiple backlight pins, add something like this to your `config.h`, instead of `BACKLIGHT_PIN`:
```c
#undef BACKLIGHT_PIN
#define BACKLIGHT_PINS { F5, B2 }
```
## Custom Driver
### Custom Driver :id=custom-driver
To enable, add this to your rules.mk:
If none of the above drivers apply to your board (for example, you are using a separate IC to control the backlight), you can implement a custom backlight driver using this simple API provided by QMK. To enable, add this to your `rules.mk`:
```makefile
BACKLIGHT_DRIVER = custom
```
When implementing the custom driver API, the provided keyboard hooks are as follows:
Then implement any of these hooks:
```c
void backlight_init_ports(void) {
// Optional - Run on startup
// - usually you want to configure pins here
// Optional - runs on startup
// Usually you want to configure pins here
}
void backlight_set(uint8_t level) {
// Optional - Run on level change
// - usually you want to respond to the new value
// Optional - runs on level change
// Usually you want to respond to the new value
}
void backlight_task(void) {
// Optional - Run periodically
// - long running actions here can cause performance issues
// Optional - runs periodically
// Note that this is called in the main keyboard loop,
// so long running actions here can cause performance issues
}
```
## Example Schematic
In this typical example, the backlight LEDs are all connected in parallel towards an N-channel MOSFET. Its gate pin is wired to one of the microcontroller's GPIO pins through a 470Ω resistor to avoid ringing.
A pulldown resistor is also placed between the gate pin and ground to keep it at a defined state when it is not otherwise being driven by the MCU.
The values of these resistors are not critical - see [this Electronics StackExchange question](https://electronics.stackexchange.com/q/68748) for more information.
![Backlight example circuit](https://i.imgur.com/BmAvoUC.png)

12
docs/feature_bluetooth.md
View file

@ -2,11 +2,10 @@
## Bluetooth Known Supported Hardware
Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1, QMK has support for RN-42 modules and the Bluefruit EZ-Key, the latter of which is not produced anymore. For more recent BLE protocols, currently only the Adafruit Bluefruit SPI Friend is directly supported. BLE is needed to connect to iOS devices. Note iOS does not support mouse input.
Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1, QMK has support for RN-42 modules. For more recent BLE protocols, currently only the Adafruit Bluefruit SPI Friend is directly supported. BLE is needed to connect to iOS devices. Note iOS does not support mouse input.
|Board |Bluetooth Protocol |Connection Type |rules.mk |Bluetooth Chip|
|----------------------------------------------------------------|----------------------------|----------------|---------------------------|--------------|
|[Adafruit EZ-Key HID](https://www.adafruit.com/product/1535) |Bluetooth Classic | UART |`BLUETOOTH = AdafruitEZKey` | |
|Roving Networks RN-42 (Sparkfun Bluesmirf) |Bluetooth Classic | UART |`BLUETOOTH = RN42` | RN-42 |
|[Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633)|Bluetooth Low Energy | SPI |`BLUETOOTH = AdafruitBLE` | nRF51822 |
@ -24,16 +23,15 @@ Currently The only bluetooth chipset supported by QMK is the Adafruit Bluefruit
A Bluefruit UART friend can be converted to an SPI friend, however this [requires](https://github.com/qmk/qmk_firmware/issues/2274) some reflashing and soldering directly to the MDBT40 chip.
## Adafruit EZ-Key hid
This requires [some hardware changes](https://www.reddit.com/r/MechanicalKeyboards/comments/3psx0q/the_planck_keyboard_with_bluetooth_guide_and/?ref=search_posts), but can be enabled via the Makefile. The firmware will still output characters via USB, so be aware of this when charging via a computer. It would make sense to have a switch on the Bluefruit to turn it off at will.
<!-- FIXME: Document bluetooth support more completely. -->
## Bluetooth Rules.mk Options
Use only one of these
The currently supported Bluetooth chipsets do not support [N-Key Rollover (NKRO)](reference_glossary.md#n-key-rollover-nkro), so `rules.mk` must contain `NKRO_ENABLE = no`.
Use only one of these to enable Bluetooth:
* BLUETOOTH_ENABLE = yes (Legacy Option)
* BLUETOOTH = RN42
* BLUETOOTH = AdafruitEZKey
* BLUETOOTH = AdafruitBLE
## Bluetooth Keycodes

2
docs/feature_combo.md
View file

@ -55,7 +55,7 @@ combo_t key_combos[COMBO_COUNT] = {
[XV_PASTE] = COMBO_ACTION(paste_combo),
};
void process_combo_event(uint8_t combo_index, bool pressed) {
void process_combo_event(uint16_t combo_index, bool pressed) {
switch(combo_index) {
case ZC_COPY:
if (pressed) {

147
docs/feature_debounce_type.md
View file

@ -1,43 +1,150 @@
# Debounce algorithm
# Contact bounce / contact chatter
Mechanical switches often don't have a clean single transition between pressed and unpressed states.
In an ideal world, when you press a switch, you would expect the digital pin to see something like this:
(X axis showing time
```
voltage +----------------------
^ |
| |
| ------------------+
----> time
```
However in the real world you will actually see contact bounce, which will look like multiple 1->0 and 0->1 transitions,
until the value finally settles.
```
+-+ +--+ +-------------
| | | | |
| | | | |
+-----------------+ +-+ +-+
```
The time it takes for the switch to settle might vary with switch type, age, and even pressing technique.
If the device chooses not to mitigate contact bounce, then often actions that happen when the switch is pressed are repeated
multiple times.
There are many ways to handle contact bounce ("Debouncing"). Some include employing additional hardware, for example an RC filter,
while there are various ways to do debouncing in software too, often called debounce algorithms. This page discusses software
debouncing methods available in QMK.
While technically not considered contact bounce/contact chatter, some switch technologies are susceptible to noise, meaning,
while the key is not changing state, sometimes short random 0->1 or 1->0 transitions might be read by the digital circuit, for example:
```
+-+
| |
| |
+-----------------+ +--------------------
```
Many debounce methods (but not all) will also make the device resistant to noise. If you are working with a technology that is
susceptible to noise, you must choose a debounce method that will also mitigate noise for you.
## Types of debounce algorithms
1) Unit of time: Timestamp (milliseconds) vs Cycles (scans)
* Debounce algorithms often have a 'debounce time' parameter, that specifies the maximum settling time of the switch contacts.
This time might be measured in various units:
* Cycles-based debouncing waits n cycles (scans), decreasing count by one each matrix_scan
* Timestamp-based debouncing stores the millisecond timestamp a change occurred, and does substraction to figure out time elapsed.
* Timestamp-based debouncing is usually superior, especially in the case of noise-resistant devices because settling times of physical
switches is specified in units of time, and should not depend on the matrix scan-rate of the keyboard.
* Cycles-based debouncing is sometimes considered inferior, because the settling time that it is able to compensate for depends on the
performance of the matrix scanning code. If you use cycles-based debouncing, and you significantly improve the performance of your scanning
code, you might end up with less effective debouncing. A situation in which cycles-based debouncing might be preferable is when
noise is present, and the scanning algorithm is slow, or variable speed. Even if your debounce algorithm is fundamentally noise-resistant,
if the scanning is slow, and you are using a timestamp-based algorithm, you might end up making a debouncing decision based on only two
sampled values, which will limit the noise-resistance of the algorithm.
* Currently all built-in debounce algorithms support timestamp-based debouncing only. In the future we might
implement cycles-based debouncing, and it will be selectable via a ```config.h``` macro.
2) Symmetric vs Asymmetric
* Symmetric - apply the same debouncing algorithm, to both key-up and key-down events.
* Recommended naming convention: ```sym_*```
* Asymmetric - apply different debouncing algorithms to key-down and key-up events. E.g. Eager key-down, Defer key-up.
* Recommended naming convention: ```asym_*``` followed by details of the type of algorithm in use, in order, for key-down and then key-up
3) Eager vs Defer
* Eager - any key change is reported immediately. All further inputs for DEBOUNCE ms are ignored.
* Eager algorithms are not noise-resistant.
* Recommended naming conventions:
* ```sym_eager_*```
* ```asym_eager_*_*```: key-down is using eager algorithm
* ```asym_*_eager_*```: key-up is using eager algorithm
* Defer - wait for no changes for DEBOUNCE ms before reporting change.
* Defer algorithms are noise-resistant
* Recommended naming conventions:
* ```sym_defer_*```
* ```asym_defer_*_*```: key-down is using defer algorithm
* ```asym_*_defer_*```: key-up is using defer algorithm
4) Global vs Per-Key vs Per-Row
* Global - one timer for all keys. Any key change state affects global timer
* Recommended naming convention: ```*_g```
* Per-key - one timer per key
* Recommended naming convention: ```*_pk```
* Per-row - one timer per row
* Recommended naming convention: ```*_pr```
* Per-key and per-row algorithms consume more resources (in terms of performance,
and ram usage), but fast typists might prefer them over global.
## Debounce algorithms supported by QMK
QMK supports multiple debounce algorithms through its debounce API.
The logic for which debounce method called is below. It checks various defines that you have set in rules.mk
The logic for which debounce method called is below. It checks various defines that you have set in ```rules.mk```
```
DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce
DEBOUNCE_TYPE?= sym_g
DEBOUNCE_TYPE?= sym_defer_g
ifneq ($(strip $(DEBOUNCE_TYPE)), custom)
QUANTUM_SRC += $(DEBOUNCE_DIR)/$(strip $(DEBOUNCE_TYPE)).c
endif
```
# Debounce selection
### Debounce selection
| DEBOUNCE_TYPE | Description | What else is needed |
| ------------- | --------------------------------------------------- | ----------------------------- |
| Not defined | Use the default algorithm, currently sym_g | Nothing |
| Not defined | Use the default algorithm, currently sym_defer_g | Nothing |
| custom | Use your own debounce code | ```SRC += debounce.c``` add your own debounce.c and implement necessary functions |
| anything_else | Use another algorithm from quantum/debounce/* | Nothing |
| Anything Else | Use another algorithm from quantum/debounce/* | Nothing |
**Regarding split keyboards**:
The debounce code is compatible with split keyboards.
# Use your own debouncing code
* Set ```DEBOUNCE_TYPE = custom```.
* Add ```SRC += debounce.c```
### Selecting an included debouncing method
Keyboards may select one of the already implemented debounce methods, by adding to ```rules.mk``` the following line:
```
DEBOUNCE_TYPE = <name of algorithm>
```
Where name of algorithm is one of:
* ```sym_defer_g``` - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occurred, all input changes are pushed.
* This is the current default algorithm. This is the highest performance algorithm with lowest memory usage, and it's also noise-resistant.
* ```sym_eager_pr``` - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row.
For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be
appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use.
* ```sym_eager_pk``` - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key
* ```sym_defer_pk``` - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key status change is pushed.
### A couple algorithms that could be implemented in the future:
* ```sym_defer_pr```
* ```sym_eager_g```
* ```asym_eager_defer_pk```
### Use your own debouncing code
You have the option to implement you own debouncing algorithm. To do this:
* Set ```DEBOUNCE_TYPE = custom``` in ```rules.mk```.
* Add ```SRC += debounce.c``` in ```rules.mk```
* Add your own ```debounce.c```. Look at current implementations in ```quantum/debounce``` for examples.
* Debouncing occurs after every raw matrix scan.
* Use num_rows rather than MATRIX_ROWS, so that split keyboards are supported correctly.
* If the algorithm might be applicable to other keyboards, please consider adding it to ```quantum/debounce```
# Changing between included debouncing methods
You can either use your own code, by including your own debounce.c, or switch to another included one.
Included debounce methods are:
* eager_pr - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row.
For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be
appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use.
* eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key
* sym_g - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occured, all input changes are pushed.
* sym_pk - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occured on that key, the key status change is pushed.
### Old names
The following old names for existing algorithms will continue to be supported, however it is recommended to use the new names instead.
* sym_g - old name for sym_defer_g
* eager_pk - old name for sym_eager_pk
* sym_pk - old name for sym_defer_pk
* eager_pr - old name for sym_eager_pr

14
docs/feature_dip_switch.md
View file

@ -7,9 +7,17 @@ DIP switches are supported by adding this to your `rules.mk`:
and this to your `config.h`:
```c
// Connects each switch in the dip switch to the GPIO pin of the MCU
#define DIP_SWITCH_PINS { B14, A15, A10, B9 }
```
or
```c
// Connect each switch in the DIP switch to an unused intersections in the key matrix.
#define DIP_SWITCH_MATRIX_GRID { {0,6}, {1,6}, {2,6} } // List of row and col pairs
```
## Callbacks
The callback functions can be inserted into your `<keyboard>.c`:
@ -87,4 +95,10 @@ void dip_switch_update_mask_user(uint32_t state) {
## Hardware
### Connects each switch in the dip switch to the GPIO pin of the MCU
One side of the DIP switch should be wired directly to the pin on the MCU, and the other side to ground. It should not matter which side is connected to which, as it should be functionally the same.
### Connect each switch in the DIP switch to an unused intersections in the key matrix.
As with the keyswitch, a diode and DIP switch connect the ROW line to the COL line.

4
docs/feature_dynamic_macros.md
View file

@ -18,11 +18,11 @@ That should be everything necessary.
To start recording the macro, press either `DYN_REC_START1` or `DYN_REC_START2`.
To finish the recording, press the `DYN_REC_STOP` layer button.
To finish the recording, press the `DYN_REC_STOP` layer button. You can also press `DYN_REC_START1` or `DYN_REC_START2` again to stop the recording.
To replay the macro, press either `DYN_MACRO_PLAY1` or `DYN_MACRO_PLAY2`.
It is possible to replay a macro as part of a macro. It's ok to replay macro 2 while recording macro 1 and vice versa but never create recursive macros i.e. macro 1 that replays macro 1. If you do so and the keyboard will get unresponsive, unplug the keyboard and plug it again. You can disable this completly by defining `DYNAMIC_MACRO_NO_NESTING` in your `config.h` file.
It is possible to replay a macro as part of a macro. It's ok to replay macro 2 while recording macro 1 and vice versa but never create recursive macros i.e. macro 1 that replays macro 1. If you do so and the keyboard will get unresponsive, unplug the keyboard and plug it again. You can disable this completely by defining `DYNAMIC_MACRO_NO_NESTING` in your `config.h` file.
?> For the details about the internals of the dynamic macros, please read the comments in the `process_dynamic_macro.h` and `process_dynamic_macro.c` files.

11
docs/feature_encoders.md
View file

@ -26,19 +26,26 @@ If your encoder's clockwise directions are incorrect, you can swap the A & B pad
#define ENCODER_DIRECTION_FLIP
```
Additionally, the resolution can be specified in the same file (the default & suggested is 4):
Additionally, the resolution, which defines how many pulses the encoder registers between each detent, can be defined with:
```c
#define ENCODER_RESOLUTION 4
```
It can also be defined per-encoder, by instead defining:
```c
#define ENCODER_RESOLUTIONS { 4, 2 }
```
## Split Keyboards
If you are using different pinouts for the encoders on each half of a split keyboard, you can define the pinout for the right half like this:
If you are using different pinouts for the encoders on each half of a split keyboard, you can define the pinout (and optionally, resolutions) for the right half like this:
```c
#define ENCODERS_PAD_A_RIGHT { encoder1a, encoder2a }
#define ENCODERS_PAD_B_RIGHT { encoder1b, encoder2b }
#define ENCODER_RESOLUTIONS_RIGHT { 2, 4 }
```
## Callbacks

21
docs/feature_haptic_feedback.md
View file

@ -42,14 +42,21 @@ First you will need a build a circuit to drive the solenoid through a mosfet as
[Wiring diagram provided by Adafruit](https://playground.arduino.cc/uploads/Learning/solenoid_driver.pdf)
| Settings | Default | Description |
|--------------------------|---------------|-------------------------------------------------------|
|`SOLENOID_PIN` | *Not defined* |Configures the pin that the Solenoid is connected to. |
|`SOLENOID_DEFAULT_DWELL` | `12` ms |Configures the default dwell time for the solenoid. |
|`SOLENOID_MIN_DWELL` | `4` ms |Sets the lower limit for the dwell. |
|`SOLENOID_MAX_DWELL` | `100` ms |Sets the upper limit for the dwell. |
| Settings | Default | Description |
|----------------------------|----------------------|-------------------------------------------------------|
|`SOLENOID_PIN` | *Not defined* |Configures the pin that the Solenoid is connected to. |
|`SOLENOID_DEFAULT_DWELL` | `12` ms |Configures the default dwell time for the solenoid. |
|`SOLENOID_MIN_DWELL` | `4` ms |Sets the lower limit for the dwell. |
|`SOLENOID_MAX_DWELL` | `100` ms |Sets the upper limit for the dwell. |
|`SOLENOID_DWELL_STEP_SIZE` | `1` ms |The step size to use when `HPT_DWL*` keycodes are sent |
|`SOLENOID_DEFAULT_BUZZ` | `0` (disabled) |On HPT_RST buzz is set "on" if this is "1" |
|`SOLENOID_BUZZ_ACTUATED` | `SOLENOID_MIN_DWELL` |Actuated-time when the solenoid is in buzz mode |
|`SOLENOID_BUZZ_NONACTUATED` | `SOLENOID_MIN_DWELL` |Non-Actuated-time when the solenoid is in buzz mode |
?> Dwell time is how long the "plunger" stays activated. The dwell time changes how the solenoid sounds.
* 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.
* With the current implementation, for any of the above time settings, the precision of these settings may be affected by how fast the keyboard is able to scan the matrix.
Therefore, if the keyboards scanning routine is slow, it may be preferable to set `SOLENOID_DWELL_STEP_SIZE` to a value slightly smaller than the time it takes to scan the keyboard.
Beware that some pins may be powered during bootloader (ie. A13 on the STM32F303 chip) and will result in the solenoid kept in the on state through the whole flashing process. This may overheat and damage the solenoid. If you find that the pin the solenoid is connected to is triggering the solenoid during bootloader/DFU, select another pin.

6
docs/feature_hd44780.md
View file

@ -1,6 +1,6 @@
# HD44780 LCD Displays
This is an integration of Peter Fleury's LCD library. This page will explain the basics. [For in depth documentation visit his page.](http://homepage.hispeed.ch/peterfleury/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)
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)
You can enable support for HD44780 Displays by setting the `HD44780_ENABLE` flag in your keyboards `rules.mk` to yes.
@ -50,8 +50,8 @@ LCD_DISP_ON_CURSOR_BLINK : display on, cursor on flashing
````
This is best done in your keyboards `matrix_init_kb` or your keymaps `matrix_init_user`.
It is advised to clear the display before use.
To do so call `lcd_clrsrc()`.
To do so call `lcd_clrscr()`.
To now print something to your Display you first call `lcd_gotoxy(column, line)`. To go to the start of the first line you would call `lcd_gotoxy(0, 0)` and then print a string with `lcd_puts("example string")`.
There are more methods available to control the display. [For in depth documentation please visit the linked page.](http://homepage.hispeed.ch/peterfleury/doxygen/avr-gcc-libraries/group__pfleury__lcd.html)
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)

22
docs/feature_joystick.md
View file

@ -2,11 +2,7 @@
The keyboard can be made to be recognized as a joystick HID device by the operating system.
This is enabled by adding the following to `rules.mk`:
```makefile
JOYSTICK_ENABLE = yes
```
This is enabled by adding `JOYSTICK_ENABLE` to `rules.mk`. You can set this value to `analog`, `digital`, or `no`.
!> Joystick support is not currently available on V-USB devices.
@ -19,6 +15,12 @@ or send gamepad reports based on values computed by the keyboard.
### Analog Input
To use analog input you must first enable it in `rules.mk`:
```makefile
JOYSTICK_ENABLE = analog
```
An analog device such as a potentiometer found on a gamepad's analog axes is based on a [voltage divider](https://en.wikipedia.org/wiki/Voltage_divider).
It is composed of three connectors linked to the ground, the power input and power output (usually the middle one). The power output holds the voltage that varies based on the position of the cursor,
which value will be read using your MCU's [ADC](https://en.wikipedia.org/wiki/Analog-to-digital_converter).
@ -75,7 +77,7 @@ You assign a value by writing to `joystick_status.axes[axis_index]` a signed 8-b
The following example writes two axes based on keypad presses, with `KC_P5` as a precision modifier:
```c
#ifdef JOYSTICK_ENABLE
#ifdef ANALOG_JOYSTICK_ENABLE
static uint8_t precision_val = 70;
static uint8_t axesFlags = 0;
enum axes {
@ -89,7 +91,7 @@ enum axes {
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch(keycode) {
#ifdef JOYSTICK_ENABLE
#ifdef ANALOG_JOYSTICK_ENABLE
// virtual joystick
# if JOYSTICK_AXES_COUNT > 1
case KC_P8:
@ -139,6 +141,12 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
}
```
### Axis Resolution
By default, the resolution of each axis is 8 bit, giving a range of -127 to +127. If you need higher precision, you can increase it by defining eg. `JOYSTICK_AXES_RESOLUTION 12` in your `config.h`. The resolution must be between 8 and 16.
Note that the supported AVR MCUs have a 10-bit ADC, and 12-bit for most STM32 MCUs.
### Triggering Joystick Buttons
Joystick buttons are normal Quantum keycodes, defined as `JS_BUTTON0` to `JS_BUTTON31`, depending on the number of buttons you have configured.

17
docs/feature_layers.md
View file

@ -19,7 +19,7 @@ These functions allow you to activate layers in various ways. Note that layers a
### Caveats :id=caveats
Currently, `LT()` and `MT()` are limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. Specifically, dual function keys like `LT` and `MT` use a 16 bit keycode. 4 bits are used for the function identifier, the next 12 are divided into the parameters. Layer Tap uses 4 bits for the layer (and is why it's limited to layers 0-16, actually), while Mod Tap does the same, 4 bits for the identifier, 4 bits for which mods are used, and all of them use 8 bits for the keycode. Because of this, the keycode used is limited to `0xFF` (0-255), which are the basic keycodes only.
Currently, `LT()` and `MT()` are limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. Specifically, dual function keys like `LT` and `MT` use a 16 bit keycode. 4 bits are used for the function identifier, the next 12 are divided into the parameters. Layer Tap uses 4 bits for the layer (and is why it's limited to layers 0-15, actually), while Mod Tap does the same, 4 bits for the identifier, 4 bits for which mods are used, and all of them use 8 bits for the keycode. Because of this, the keycode used is limited to `0xFF` (0-255), which are the basic keycodes only.
Expanding this would be complicated, at best. Moving to a 32-bit keycode would solve a lot of this, but would double the amount of space that the keymap matrix uses. And it could potentially cause issues, too. If you need to apply modifiers to your tapped keycode, [Tap Dance](feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this.
@ -74,10 +74,9 @@ There are a number of functions (and variables) related to how you can use or ma
| [`update_tri_layer(x, y, z)`](ref_functions.md#update_tri_layerx-y-z) | Checks if layers `x` and `y` are both on, and sets `z` based on that (on if both on, otherwise off). |
| [`update_tri_layer_state(state, x, y, z)`](ref_functions.md#update_tri_layer_statestate-x-y-z) | Does the same as `update_tri_layer(x, y, z)`, but from `layer_state_set_*` functions. |
In addition to the functions that you can call, there are a number of callback functions that get called every time the layer changes. This passes the layer state to the function, where it can be read or modified.
In additional to the functions that you can call, there are a number of callback functions that get called every time the layer changes. This passed the layer state to the function, which can be read or modified.
|Callbacks |Description |
|Callback |Description |
|-----------------------------------------------------|----------------------------------------------------------------------------------------|
| `layer_state_set_kb(layer_state_t state)` | Callback for layer functions, for keyboard. |
| `layer_state_set_user(layer_state_t state)` | Callback for layer functions, for users. |
@ -86,9 +85,9 @@ In additional to the functions that you can call, there are a number of callback
?> For additional details on how you can use these callbacks, check out the [Layer Change Code](custom_quantum_functions.md#layer-change-code) document.
|Check functions |Description |
|-------------------------------------------|------------------------------------------------------------------------------|
| `layer_state_cmp(cmp_layer_state, layer)` | This checks the `cmp_layer_state` to see if the specific `layer` is enabled. This is meant for use with the layer callbacks. |
| `layer_state_is(layer)` | This checks the layer state to see if the specific `layer` is enabled. (calls `layer_state_cmp` for the global layer state). |
It is also possible to check the state of a particular layer using the following functions and macros.
!> There is `IS_LAYER_ON(layer)` as well, however the `layer_state_cmp` function has some additional handling to ensure that on layer 0 that it returns the correct value. Otherwise, if you check to see if layer 0 is on, you may get an incorrect value returned.
|Function |Description |Aliases
|---------------------------------|-------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| `layer_state_is(layer)` | Checks if the specified `layer` is enabled globally. | `IS_LAYER_ON(layer)`, `IS_LAYER_OFF(layer)` |
| `layer_state_cmp(state, layer)` | Checks `state` to see if the specified `layer` is enabled. Intended for use in layer callbacks. | `IS_LAYER_ON_STATE(state, layer)`, `IS_LAYER_OFF_STATE(state, layer)` |

2
docs/feature_leader_key.md
View file

@ -5,7 +5,7 @@ If you've ever used Vim, you know what a Leader key is. If not, you're about to
That's what `KC_LEAD` does. Here's an example:
1. Pick a key on your keyboard you want to use as the Leader key. Assign it the keycode `KC_LEAD`. This key would be dedicated just for this -- it's a single action key, can't be used for anything else.
2. Include the line `#define LEADER_TIMEOUT 300` in your `config.h`. This sets the timeout for the `KC_LEAD` key. Specifically, when you press the `KC_LEAD` key, you only have a certain amount of time to complete the Leader Key sequence. The `300` here sets that to 300ms, and you can increase this value to give you more time to hit the sequence. But any keys pressed during this timeout are intercepted and not sent, so you may want to keep this value low. .
2. Include the line `#define LEADER_TIMEOUT 300` in your `config.h`. This sets the timeout for the `KC_LEAD` key. Specifically, when you press the `KC_LEAD` key, you only have a certain amount of time to complete the Leader Key sequence. The `300` here sets that to 300ms, and you can increase this value to give you more time to hit the sequence. But any keys pressed during this timeout are intercepted and not sent, so you may want to keep this value low.
* By default, this timeout is how long after pressing `KC_LEAD` to complete your entire sequence. This may be very low for some people. So you may want to increase this timeout. Optionally, you may want to enable the `LEADER_PER_KEY_TIMING` option, which resets the timeout after each key is tapped. This allows you to maintain a low value here, but still be able to use the longer sequences. To enable this option, add `#define LEADER_PER_KEY_TIMING` to your `config.h`.
3. Within your `matrix_scan_user` function, add something like this:

116
docs/feature_led_indicators.md Normal file
View file

@ -0,0 +1,116 @@
# LED Indicators
QMK provides methods to read 5 of the LEDs defined in the HID spec:
* Num Lock
* Caps Lock
* Scroll Lock
* Compose
* 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()`
!> `host_keyboard_led_state()` may already reflect a new value before `led_update_user()` is called.
Two more deprecated functions exist that provide the LED state as a `uint8_t`:
* `uint8_t led_set_kb(uint8_t usb_led)` and `_user(uint8_t usb_led)`
* `uint8_t host_keyboard_leds()`
## Configuration Options
To configure the indicators, `#define` these in your `config.h`:
|Define |Default |Description |
|---------------------|-------------|-------------------------------------------|
|`LED_NUM_LOCK_PIN` |*Not defined*|The pin that controls the `Num Lock` LED |
|`LED_CAPS_LOCK_PIN` |*Not defined*|The pin that controls the `Caps Lock` LED |
|`LED_SCROLL_LOCK_PIN`|*Not defined*|The pin that controls the `Scroll Lock` LED|
|`LED_COMPOSE_PIN` |*Not defined*|The pin that controls the `Compose` LED |
|`LED_KANA_PIN` |*Not defined*|The pin that controls the `Kana` LED |
|`LED_PIN_ON_STATE` |`1` |The state of the indicator pins when the LED is "on" - `1` for high, `0` for low|
Unless you are designing your own keyboard, you generally should not need to change the above config options.
## `led_update_*()`
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.
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()`.
Some examples include:
- 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.
?> 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 `led_update_kb()` Implementation
```c
bool led_update_kb(led_t led_state) {
bool res = led_update_user(led_state);
if(res) {
// writePin sets the pin high for 1 and low for 0.
// In this example the pins are inverted, setting
// it low/0 turns it on, and high/1 turns the LED off.
// This behavior depends on whether the LED is between the pin
// and VCC or the pin and GND.
writePin(B0, !led_state.num_lock);
writePin(B1, !led_state.caps_lock);
writePin(B2, !led_state.scroll_lock);
writePin(B3, !led_state.compose);
writePin(B4, !led_state.kana);
}
return res;
}
```
### Example `led_update_user()` 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.
```c
#ifdef AUDIO_ENABLE
float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND);
float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND);
#endif
bool led_update_user(led_t led_state) {
#ifdef AUDIO_ENABLE
static uint8_t caps_state = 0;
if (caps_state != led_state.caps_lock) {
led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off);
caps_state = led_state.caps_lock;
}
#endif
return true;
}
```
### `led_update_*` Function Documentation
* Keyboard/Revision: `bool led_update_kb(led_t led_state)`
* Keymap: `bool led_update_user(led_t led_state)`
## `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).
## Setting Physical LED State
Some keyboard implementations provide convenience methods for setting the state of the physical LEDs.
### Ergodox Boards
The Ergodox implementations provide `ergodox_right_led_1`/`2`/`3_on`/`off()` to turn individual LEDs on or off, as well as `ergodox_right_led_on`/`off(uint8_t led)` to turn them on or off by their index.
In addition, it is possible to specify the brightness level of all LEDs with `ergodox_led_all_set(uint8_t n)`; of individual LEDs with `ergodox_right_led_1`/`2`/`3_set(uint8_t n)`; or by index with `ergodox_right_led_set(uint8_t led, uint8_t n)`.
Ergodox boards also define `LED_BRIGHTNESS_LO` for the lowest brightness and `LED_BRIGHTNESS_HI` for the highest brightness (which is the default).

5
docs/feature_led_matrix.md
View file

@ -10,7 +10,8 @@ If you want to use RGB LED's you should use the [RGB Matrix Subsystem](feature_r
There is basic support for addressable LED matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`:
LED_MATRIX_ENABLE = IS31FL3731
LED_MATRIX_ENABLE = yes
LED_MATRIX_DRIVER = IS31FL3731
You can use between 1 and 4 IS31FL3731 IC's. Do not specify `LED_DRIVER_ADDR_<N>` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`:
@ -55,7 +56,7 @@ Define these arrays listing all the LEDs in your `<keyboard>.c`:
....
}
Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731-simple.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` ).
Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731-simple.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` ).
## Keycodes

95
docs/feature_macros.md
View file

@ -6,34 +6,34 @@ Macros allow you to send multiple keystrokes when pressing just one key. QMK has
## The New Way: `SEND_STRING()` & `process_record_user`
Sometimes you just want a key to type out words or phrases. For the most common situations we've provided `SEND_STRING()`, which will type out your string (i.e. a sequence of characters) for you. All ASCII characters that are easily translated to a keycode are supported (e.g. `\n\t`).
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:
```c
enum custom_keycodes {
QMKBEST = SAFE_RANGE,
QMKBEST = SAFE_RANGE,
};
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
switch (keycode) {
case QMKBEST:
if (record->event.pressed) {
// when keycode QMKBEST is pressed
SEND_STRING("QMK is the best thing ever!");
} else {
// when keycode QMKBEST is released
}
break;
}
return true;
if (record->event.pressed) {
// when keycode QMKBEST is pressed
SEND_STRING("QMK is the best thing ever!");
} else {
// when keycode QMKBEST is released
}
break;
}
return true;
};
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = {
{QMKBEST, KC_ESC}
}
[0] = {
{QMKBEST, KC_ESC},
// ...
},
};
```
@ -49,42 +49,45 @@ You can do that by adding another keycode and adding another case to the switch
```c
enum custom_keycodes {
QMKBEST = SAFE_RANGE,
QMKURL,
MY_OTHER_MACRO
QMKBEST = SAFE_RANGE,
QMKURL,
MY_OTHER_MACRO,
};
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
switch (keycode) {
case QMKBEST:
if (record->event.pressed) {
// when keycode QMKBEST is pressed
SEND_STRING("QMK is the best thing ever!");
} else {
// when keycode QMKBEST is released
}
break;
if (record->event.pressed) {
// when keycode QMKBEST is pressed
SEND_STRING("QMK is the best thing ever!");
} else {
// when keycode QMKBEST is released
}
break;
case QMKURL:
if (record->event.pressed) {
// when keycode QMKURL is pressed
SEND_STRING("https://qmk.fm/\n");
} else {
// when keycode QMKURL is released
}
break;
if (record->event.pressed) {
// when keycode QMKURL is pressed
SEND_STRING("https://qmk.fm/\n");
} else {
// when keycode QMKURL is released
}
break;
case MY_OTHER_MACRO:
if (record->event.pressed) {
SEND_STRING(SS_LCTL("ac")); // selects all and copies
}
break;
}
return true;
if (record->event.pressed) {
SEND_STRING(SS_LCTL("ac")); // selects all and copies
}
break;
}
return true;
};
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = {
{MY_CUSTOM_MACRO, MY_OTHER_MACRO}
}
[0] = {
{MY_CUSTOM_MACRO, MY_OTHER_MACRO},
// ...
},
};
```
@ -179,7 +182,9 @@ Which would send Left Control+`a` (Left Control down, `a`, Left Control up) - no
By default, it assumes a US keymap with a QWERTY layout; if you want to change that (e.g. if your OS uses software Colemak), include this somewhere in your keymap:
#include <sendstring_colemak.h>
```c
#include "sendstring_colemak.h"
```
### Strings in Memory
@ -204,7 +209,7 @@ SEND_STRING(".."SS_TAP(X_END));
There are some functions you may find useful in macro-writing. Keep in mind that while you can write some fairly advanced code within a macro, if your functionality gets too complex you may want to define a custom keycode instead. Macros are meant to be simple.
?> You can also use the functions described in [Useful function](ref_functions.md) for additional functionality. For example `reset_keyboard()` allows you to reset the keyboard as part of a macro.
?> You can also use the functions described in [Useful functions](ref_functions.md) for additional functionality. For example `reset_keyboard()` allows you to reset the keyboard as part of a macro.
### `record->event.pressed`

26
docs/feature_mouse_keys.md
View file

@ -39,10 +39,11 @@ In your keymap you can use the following keycodes to map key presses to mouse ac
## Configuring mouse keys
Mouse keys supports two different modes to move the cursor:
Mouse keys supports three different modes to move the cursor:
* **Accelerated (default):** Holding movement keys accelerates the cursor until it reaches its maximum speed.
* **Constant:** Holding movement keys moves the cursor at constant speeds.
* **Combined:** Holding movement keys accelerates the cursor until it reaches its maximum speed, but holding acceleration and movement keys simultaneously moves the cursor at constant speeds.
The same principle applies to scrolling.
@ -120,3 +121,26 @@ Use the following settings if you want to adjust cursor movement or scrolling:
|`MK_W_INTERVAL_1` |120 |Time between scroll steps (`KC_ACL1`) |
|`MK_W_OFFSET_2` |1 |Scroll steps per scroll action (`KC_ACL2`) |
|`MK_W_INTERVAL_2` |20 |Time between scroll steps (`KC_ACL2`) |
### Combined mode
This mode functions like **Accelerated** mode, however, you can hold `KC_ACL0`, `KC_ACL1` and `KC_ACL2`
to momentarily (while held) set the cursor and scroll speeds to constant speeds. When no acceleration
keys are held, this mode is identical to **Accelerated** mode, and can be modified using all of the
relevant settings.
* **KC_ACL0:** This acceleration sets your cursor to the slowest possible speed. This is useful for very
small and detailed movements of the cursor.
* **KC_ACL1:** This acceleration sets your cursor to half the maximum (user defined) speed.
* **KC_ACL2:** This acceleration sets your cursor to the maximum (computer defined) speed. This is
useful for moving the cursor large distances without much accuracy.
To use constant speed mode, you must at least define `MK_COMBINED` in your keymap’s `config.h` file:
```c
#define MK_COMBINED
```
## Use with PS/2 Mouse and Pointing Device
Mouse keys button state is shared with [PS/2 mouse](feature_ps2_mouse.md) and [pointing device](feature_pointing_device.md) so mouse keys button presses can be used for clicks and drags.

61
docs/feature_oled_driver.md
View file

@ -72,6 +72,43 @@ static void render_logo(void) {
}
```
## Buffer Read Example
For some purposes, you may need to read the current state of the OLED display
buffer. The `oled_read_raw` function can be used to safely read bytes from the
buffer.
In this example, calling `fade_display` in the `oled_task_user` function will
slowly fade away whatever is on the screen by turning random pixels black over
time.
```c
//Setup some mask which can be or'd with bytes to turn off pixels
const uint8_t single_bit_masks[8] = {127, 191, 223, 239, 247, 251, 253, 254};
static void fade_display(void) {
//Define the reader structure
oled_buffer_reader_t reader;
uint8_t buff_char;
if (random() % 30 == 0) {
srand(timer_read());
// Fetch a pointer for the buffer byte at index 0. The return structure
// will have the pointer and the number of bytes remaining from this
// index position if we want to perform a sequential read by
// incrementing the buffer pointer
reader = oled_read_raw(0);
//Loop over the remaining buffer and erase pixels as we go
for (uint16_t i = 0; i < reader.remaining_element_count; i++) {
//Get the actual byte in the buffer by dereferencing the pointer
buff_char = *reader.current_element;
if (buff_char != 0) {
oled_write_raw_byte(buff_char & single_bit_masks[rand() % 8], i);
}
//increment the pointer to fetch a new byte during the next loop
reader.current_element++;
}
}
}
```
## Other Examples
In split keyboards, it is very common to have two OLED displays that each render different content and are oriented or flipped differently. You can do this by switching which content to render by using the return value from `is_keyboard_master()` or `is_keyboard_left()` found in `split_util.h`, e.g:
@ -103,8 +140,8 @@ void oled_task_user(void) {
|---------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------|
|`OLED_DISPLAY_ADDRESS` |`0x3C` |The i2c address of the OLED Display |
|`OLED_FONT_H` |`"glcdfont.c"` |The font code file to use for custom fonts |
|`OLED_FONT_START` |`0` |The starting characer index for custom fonts |
|`OLED_FONT_END` |`223` |The ending characer index for custom fonts |
|`OLED_FONT_START` |`0` |The starting character index for custom fonts |
|`OLED_FONT_END` |`223` |The ending character index for custom fonts |
|`OLED_FONT_WIDTH` |`6` |The font width |
|`OLED_FONT_HEIGHT` |`8` |The font height (untested) |
|`OLED_TIMEOUT` |`60000` |Turns off the OLED screen after 60000ms of keyboard inactivity. Helps reduce OLED Burn-in. Set to 0 to disable. |
@ -112,6 +149,8 @@ void oled_task_user(void) {
|`OLED_SCROLL_TIMEOUT_RIGHT`|*Not defined* |Scroll timeout direction is right when defined, left when undefined. |
|`OLED_IC` |`OLED_IC_SSD1306`|Set to `OLED_IC_SH1106` if you're using the SH1106 OLED controller. |
|`OLED_COLUMN_OFFSET` |`0` |(SH1106 only.) Shift output to the right this many pixels.<br />Useful for 128x64 displays centered on a 132x64 SH1106 IC.|
|`OLED_BRIGHTNESS` |`255` |The default brightness level of the OLED, from 0 to 255. |
|`OLED_UPDATE_INTERVAL` |`0` |Set the time interval for updating the OLED display in ms. This will improve the matrix scan rate. |
## 128x64 & Custom sized OLED Displays
@ -238,6 +277,10 @@ void oled_write_P(const char *data, bool invert);
// Remapped to call 'void oled_write_ln(const char *data, bool invert);' on ARM
void oled_write_ln_P(const char *data, bool invert);
// Returns a pointer to the requested start index in the buffer plus remaining
// buffer length as struct
oled_buffer_reader_t oled_read_raw(uint16_t start_index);
// Writes a string to the buffer at current cursor position
void oled_write_raw(const char *data, uint16_t size);
@ -247,6 +290,10 @@ void oled_write_raw_byte(const char data, uint16_t index);
// Writes a PROGMEM string to the buffer at current cursor position
void oled_write_raw_P(const char *data, uint16_t size);
// Sets a specific pixel on or off
// Coordinates start at top-left and go right and down for positive x and y
void oled_write_pixel(uint8_t x, uint8_t y, bool on);
// Can be used to manually turn on the screen if it is off
// Returns true if the screen was on or turns on
bool oled_on(void);
@ -255,6 +302,16 @@ bool oled_on(void);
// Returns true if the screen was off or turns off
bool oled_off(void);
// Returns true if the oled is currently on, false if it is
// not
bool is_oled_on(void);
// Sets the brightness level of the display
uint8_t oled_set_brightness(uint8_t level);
// Gets the current brightness level of the display
uint8_t oled_get_brightness(void);
// Basically it's oled_render, but with timeout management and oled_task_user calling!
void oled_task(void);

26
docs/feature_pointing_device.md
View file

@ -21,26 +21,32 @@ Keep in mind that a report_mouse_t (here "mouseReport") has the following proper
* `mouseReport.h` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing horizontal scrolling (+ right, - left).
* `mouseReport.buttons` - this is a uint8_t in which the last 5 bits are used. These bits represent the mouse button state - bit 3 is mouse button 5, and bit 7 is mouse button 1.
When the mouse report is sent, the x, y, v, and h values are set to 0 (this is done in "pointing_device_send()", which can be overridden to avoid this behavior). This way, button states persist, but movement will only occur once. For further customization, both `pointing_device_init` and `pointing_device_task` can be overridden.
Once you have made the necessary changes to the mouse report, you need to send it:
* `pointing_device_send()` - Sends the mouse report to the host and zeroes out the report.
When the mouse report is sent, the x, y, v, and h values are set to 0 (this is done in `pointing_device_send()`, which can be overridden to avoid this behavior). This way, button states persist, but movement will only occur once. For further customization, both `pointing_device_init` and `pointing_device_task` can be overridden.
Additionally, by default, `pointing_device_send()` will only send a report when the report has actually changed. This prevents it from continuously sending mouse reports, which will keep the host system awake. This behavior can be changed by creating your own `pointing_device_send()` function.
Also, you use the `has_mouse_report_changed(new, old)` function to check to see if the report has changed.
In the following example, a custom key is used to click the mouse and scroll 127 units vertically and horizontally, then undo all of that when released - because that's a totally useful function. Listen, this is an example:
```c
case MS_SPECIAL:
report_mouse_t currentReport = pointing_device_get_report();
if (record->event.pressed)
{
report_mouse_t currentReport = pointing_device_get_report();
if (record->event.pressed) {
currentReport.v = 127;
currentReport.h = 127;
currentReport.buttons |= MOUSE_BTN1; //this is defined in report.h
}
else
{
currentReport.h = 127;
currentReport.buttons |= MOUSE_BTN1; // this is defined in report.h
} else {
currentReport.v = -127;
currentReport.h = -127;
currentReport.buttons &= ~MOUSE_BTN1;
}
pointing_device_set_report(currentReport);
pointing_device_set_report(currentReport);
pointing_device_send();
break;
```

12
docs/feature_ps2_mouse.md
View file

@ -206,7 +206,7 @@ It's possible to enable a "scroll button/s" that when pressed will cause the mou
To enable the feature, you must set a scroll button mask as follows:
```c
#define PS2_MOUSE_SCROLL_BTN_MASK (1<<PS2_MOUSE_BUTTON_MIDDLE) /* Default */
#define PS2_MOUSE_SCROLL_BTN_MASK (1<<PS2_MOUSE_BTN_MIDDLE) /* Default */
```
To disable the scroll button feature:
@ -294,3 +294,13 @@ To debug the mouse, add `debug_mouse = true` or enable via bootmagic.
#define PS2_MOUSE_DEBUG_HID
#define PS2_MOUSE_DEBUG_RAW
```
### Movement Hook :id=movement-hook
Process mouse movement in the keymap before it is sent to the host. Example
uses include filtering noise, adding acceleration, and automatically activating
a layer. To use, define the following function in your keymap:
```c
void ps2_mouse_moved_user(report_mouse_t *mouse_report);
```

8
docs/feature_rawhid.md
View file

@ -29,7 +29,7 @@ void raw_hid_receive(uint8_t *data, uint8_t length) {
}
```
`raw_hid_receive` can receive variable size packets from host with maximum length `RAW_EPSIZE`. `raw_hid_send` on the other hand can send packets to host of exactly `RAW_EPSIZE` length, therefore it should be used with data of length `RAW_EPSIZE`.
These two functions send and receive packets of length `RAW_EPSIZE` bytes to and from the host (32 on LUFA/ChibiOS/V-USB, 64 on ATSAM).
Make sure to flash raw enabled firmware before proceeding with working on the host side.
@ -44,7 +44,11 @@ To connect your host computer to your keyboard with raw HID you need four pieces
3. Usage Page
4. Usage
The first two can easily be found in your keyboard's `config.h` in the keyboard's main directory under `VENDOR_ID` and `PRODUCT_ID`. **Usage Page** is **`0xFF60`** and **Usage** is **`0x0061`**.
The first two can easily be found in your keyboard's `config.h` in the keyboard's main directory under `VENDOR_ID` and `PRODUCT_ID`.
The final two can be overridden in your keyboard's `config.h` in the keyboard's main directory by redefining the values: `#define RAW_USAGE_PAGE 0xFF60` and `#define RAW_USAGE_ID 0x61`.
By default, **Usage Page** is `0xFF60` and **Usage** is `0x61`.
### Building your host

111
docs/feature_rgb_matrix.md
View file

@ -11,7 +11,8 @@ If you want to use single color LED's you should use the [LED Matrix Subsystem](
There is basic support for addressable RGB matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`:
```makefile
RGB_MATRIX_ENABLE = IS31FL3731
RGB_MATRIX_ENABLE = yes
RGB_MATRIX_DRIVER = IS31FL3731
```
Configure the hardware via your `config.h`:
@ -52,7 +53,7 @@ const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
}
```
Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0` or `1` right now).
Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0` or `1` right now).
---
### IS31FL3733/IS31FL3737 :id=is31fl3733is31fl3737
@ -62,7 +63,8 @@ Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet]
There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`:
```makefile
RGB_MATRIX_ENABLE = IS31FL3733
RGB_MATRIX_ENABLE = yes
RGB_MATRIX_DRIVER = IS31FL3733
```
Configure the hardware via your `config.h`:
@ -103,7 +105,7 @@ const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
}
```
Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3733.pdf) and the header file `drivers/issi/is31fl3733.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0` right now).
Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3733.pdf) and the header file `drivers/issi/is31fl3733.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0` right now).
---
@ -112,7 +114,8 @@ Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](
There is basic support for addressable RGB matrix lighting with a WS2811/WS2812{a,b,c} addressable LED strand. To enable it, add this to your `rules.mk`:
```makefile
RGB_MATRIX_ENABLE = WS2812
RGB_MATRIX_ENABLE = yes
RGB_MATRIX_DRIVER = WS2812
```
Configure the hardware via your `config.h`:
@ -129,7 +132,7 @@ Configure the hardware via your `config.h`:
From this point forward the configuration is the same for all the drivers. The `led_config_t` struct provides a key electrical matrix to led index lookup table, what the physical position of each LED is on the board, and what type of key or usage the LED if the LED represents. Here is a brief example:
```c
const led_config_t g_led_config = { {
led_config_t g_led_config = { {
// Key Matrix to LED Index
{ 5, NO_LED, NO_LED, 0 },
{ NO_LED, NO_LED, NO_LED, NO_LED },
@ -159,15 +162,16 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{
## Flags :id=flags
|Define |Description |
|------------------------------------|-------------------------------------------|
|`#define HAS_FLAGS(bits, flags)` |Returns true if `bits` has all `flags` set.|
|`#define HAS_ANY_FLAGS(bits, flags)`|Returns true if `bits` has any `flags` set.|
|`#define LED_FLAG_NONE 0x00` |If this LED has no flags. |
|`#define LED_FLAG_ALL 0xFF` |If this LED has all flags. |
|`#define LED_FLAG_MODIFIER 0x01` |If the Key for this LED is a modifier. |
|`#define LED_FLAG_UNDERGLOW 0x02` |If the LED is for underglow. |
|`#define LED_FLAG_KEYLIGHT 0x04` |If the LED is for key backlight. |
|Define |Value |Description |
|----------------------------|------|-------------------------------------------------|
|`HAS_FLAGS(bits, flags)` |*n/a* |Evaluates to `true` if `bits` has all `flags` set|
|`HAS_ANY_FLAGS(bits, flags)`|*n/a* |Evaluates to `true` if `bits` has any `flags` set|
|`LED_FLAG_NONE` |`0x00`|If this LED has no flags |
|`LED_FLAG_ALL` |`0xFF`|If this LED has all flags |
|`LED_FLAG_MODIFIER` |`0x01`|If the LED is on a modifier key |
|`LED_FLAG_UNDERGLOW` |`0x02`|If the LED is for underglow |
|`LED_FLAG_KEYLIGHT` |`0x04`|If the LED is for key backlight |
|`LED_FLAG_INDICATOR` |`0x08`|If the LED is for keyboard state indication |
## Keycodes :id=keycodes
@ -186,8 +190,16 @@ 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_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) |
* `RGB_MODE_*` keycodes will generally work, but are not currently mapped to the correct effects for the RGB Matrix system
* `RGB_MODE_*` keycodes will generally work, but not all of the modes are currently mapped to the correct effects for the RGB Matrix system.
`RGB_MODE_PLAIN`, `RGB_MODE_BREATHE`, `RGB_MODE_RAINBOW`, and `RGB_MATRIX_SWIRL` are the only ones that are mapped properly. The rest don't have a direct equivalent, and are not mapped.
!> By default, if you have both the [RGB Light](feature_rgblight.md) and the RGB Matrix feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature.
## RGB Matrix Effects :id=rgb-matrix-effects
@ -284,6 +296,19 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con
|`#define DISABLE_RGB_MATRIX_SOLID_SPLASH` |Disables `RGB_MATRIX_SOLID_SPLASH` |
|`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH` |Disables `RGB_MATRIX_SOLID_MULTISPLASH` |
### 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.
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
```
## Custom RGB Matrix Effects :id=custom-rgb-matrix-effects
@ -294,6 +319,12 @@ To declare new effects, create a new `rgb_matrix_user/kb.inc` that looks somethi
`rgb_matrix_user.inc` should go in the root of the keymap directory.
`rgb_matrix_kb.inc` should go in the root of the keyboard directory.
To use custom effects in your code, simply prepend `RGB_MATRIX_CUSTOM_` to the effect name specified in `RGB_MATRIX_EFFECT()`. For example, an effect declared as `RGB_MATRIX_EFFECT(my_cool_effect)` would be referenced with:
```c
rgb_matrix_mode(RGB_MATRIX_CUSTOM_my_cool_effect);
```
```c
// !!! DO NOT ADD #pragma once !!! //
@ -374,7 +405,8 @@ These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blo
```c
#define RGB_MATRIX_KEYPRESSES // reacts to keypresses
#define RGB_MATRIX_KEYRELEASES // reacts to keyreleases (instead of keypresses)
#define RGB_DISABLE_AFTER_TIMEOUT 0 // number of ticks to wait until disabling effects
#define RGB_DISABLE_TIMEOUT 0 // number of milliseconds to wait until rgb automatically turns off
#define RGB_DISABLE_AFTER_TIMEOUT 0 // OBSOLETE: number of ticks to wait until disabling effects
#define RGB_DISABLE_WHEN_USB_SUSPENDED false // turn off effects when suspended
#define RGB_MATRIX_LED_PROCESS_LIMIT (DRIVER_LED_TOTAL + 4) / 5 // limits the number of LEDs to process in an animation per task run (increases keyboard responsiveness)
#define RGB_MATRIX_LED_FLUSH_LIMIT 16 // limits in milliseconds how frequently an animation will update the LEDs. 16 (16ms) is equivalent to limiting to 60fps (increases keyboard responsiveness)
@ -384,6 +416,7 @@ These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blo
#define RGB_MATRIX_STARTUP_SAT 255 // Sets the default saturation value, if none has been set
#define RGB_MATRIX_STARTUP_VAL RGB_MATRIX_MAXIMUM_BRIGHTNESS // Sets the default brightness value, if none has been set
#define RGB_MATRIX_STARTUP_SPD 127 // Sets the default animation speed, if none has been set
#define RGB_MATRIX_DISABLE_KEYCODES // disables control of rgb matrix by keycodes (must use code functions to control the feature)
```
## EEPROM storage :id=eeprom-storage
@ -411,8 +444,8 @@ Where `28` is an unused index from `eeconfig.h`.
|`rgb_matrix_toggle_noeeprom()` |Toggle effect range LEDs between on and off (not written to EEPROM) |
|`rgb_matrix_enable()` |Turn effect range LEDs on, based on their previous state |
|`rgb_matrix_enable_noeeprom()` |Turn effect range LEDs on, based on their previous state (not written to EEPROM) |
|`rgb_matrix_disable()` |Turn effect range LEDs off |
|`rgb_matrix_disable_noeeprom()` |Turn effect range LEDs off (not written to EEPROM) |
|`rgb_matrix_disable()` |Turn effect range LEDs off, based on their previous state |
|`rgb_matrix_disable_noeeprom()` |Turn effect range LEDs off, based on their previous state (not written to EEPROM) |
### Change Effect Mode :id=change-effect-mode
|Function |Description |
@ -420,29 +453,45 @@ Where `28` is an unused index from `eeconfig.h`.
|`rgb_matrix_mode(mode)` |Set the mode, if RGB animations are enabled |
|`rgb_matrix_mode_noeeprom(mode)` |Set the mode, if RGB animations are enabled (not written to EEPROM) |
|`rgb_matrix_step()` |Change the mode to the next RGB animation in the list of enabled RGB animations |
|`rgb_matrix_step_noeeprom()` |Change the mode to the next RGB animation in the list of enabled RGB animations (not written to EEPROM) |
|`rgb_matrix_step_reverse()` |Change the mode to the previous RGB animation in the list of enabled RGB animations |
|`rgb_matrix_increase_speed()` |Increases the speed of the animations |
|`rgb_matrix_decrease_speed()` |Decreases the speed of the animations |
|`rgb_matrix_step_reverse_noeeprom()` |Change the mode to the previous RGB animation in the list of enabled RGB animations (not written to EEPROM) |
|`rgb_matrix_increase_speed()` |Increase the speed of the animations |
|`rgb_matrix_increase_speed_noeeprom()` |Increase the speed of the animations (not written to EEPROM) |
|`rgb_matrix_decrease_speed()` |Decrease the speed of the animations |
|`rgb_matrix_decrease_speed_noeeprom()` |Decrease the speed of the animations (not written to EEPROM) |
|`rgb_matrix_set_speed(speed)` |Set the speed of the animations to the given value where `speed` is between 0 and 255 |
|`rgb_matrix_set_speed_noeeprom(speed)` |Set the speed of the animations to the given value where `speed` is between 0 and 255 (not written to EEPROM) |
### Change Color :id=change-color
|Function |Description |
|--------------------------------------------|-------------|
|`rgb_matrix_increase_hue()` |Increase the hue for effect range LEDs. This wraps around at maximum hue |
|`rgb_matrix_increase_hue_noeeprom()` |Increase the hue for effect range LEDs. This wraps around at maximum hue (not written to EEPROM) |
|`rgb_matrix_decrease_hue()` |Decrease the hue for effect range LEDs. This wraps around at minimum hue |
|`rgb_matrix_decrease_hue_noeeprom()` |Decrease the hue for effect range LEDs. This wraps around at minimum hue (not written to EEPROM) |
|`rgb_matrix_increase_sat()` |Increase the saturation for effect range LEDs. This wraps around at maximum saturation |
|`rgb_matrix_increase_sat_noeeprom()` |Increase the saturation for effect range LEDs. This wraps around at maximum saturation (not written to EEPROM) |
|`rgb_matrix_decrease_sat()` |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation |
|`rgb_matrix_decrease_sat_noeeprom()` |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation (not written to EEPROM) |
|`rgb_matrix_increase_val()` |Increase the value for effect range LEDs. This wraps around at maximum value |
|`rgb_matrix_increase_val_noeeprom()` |Increase the value for effect range LEDs. This wraps around at maximum value (not written to EEPROM) |
|`rgb_matrix_decrease_val()` |Decrease the value for effect range LEDs. This wraps around at minimum value |
|`rgb_matrix_decrease_val_noeeprom()` |Decrease the value for effect range LEDs. This wraps around at minimum value (not written to EEPROM) |
|`rgb_matrix_sethsv(h, s, v)` |Set LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 |
|`rgb_matrix_sethsv_noeeprom(h, s, v)` |Set LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) |
### Query Current Status :id=query-current-status
|Function |Description |
|-----------------------|-----------------|
|`rgb_matrix_get_mode()` |Get current mode |
|`rgb_matrix_get_hue()` |Get current hue |
|`rgb_matrix_get_sat()` |Get current sat |
|`rgb_matrix_get_val()` |Get current val |
|Function |Description |
|---------------------------------|---------------------------|
|`rgb_matrix_is_enabled()` |Gets current on/off status |
|`rgb_matrix_get_mode()` |Gets current mode |
|`rgb_matrix_get_hue()` |Gets current hue |
|`rgb_matrix_get_sat()` |Gets current sat |
|`rgb_matrix_get_val()` |Gets current val |
|`rgb_matrix_get_hsv()` |Gets hue, sat, and val and returns a [`HSV` structure](https://github.com/qmk/qmk_firmware/blob/7ba6456c0b2e041bb9f97dbed265c5b8b4b12192/quantum/color.h#L56-L61)|
|`rgb_matrix_get_speed()` |Gets current speed |
|`rgb_matrix_get_suspend_state()` |Gets current suspend state |
## Callbacks :id=callbacks
@ -455,6 +504,14 @@ void rgb_matrix_indicators_kb(void) {
}
```
In addition, there are the advanced indicator functions. These are aimed at those with heavily customized displays, where rendering every LED per cycle is expensive. Such as some of the "drashna" layouts. This includes a special macro to help make this easier to use: `RGB_MATRIX_INDICATOR_SET_COLOR(i, r, g, b)`.
```c
void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) {
RGB_MATRIX_INDICATOR_SET_COLOR(index, red, green, blue);
}
```
### Suspended state :id=suspended-state
To use the suspend feature, make sure that `#define RGB_DISABLE_WHEN_USB_SUSPENDED true` is added to the `config.h` file.

157
docs/feature_rgblight.md
View file

@ -41,6 +41,8 @@ Changing the **Hue** cycles around the circle.<br>
Changing the **Saturation** moves between the inner and outer sections of the wheel, affecting the intensity of the color.<br>
Changing the **Value** sets the overall brightness.<br>
![QMK Color Wheel with HSV Values](https://i.imgur.com/vkYVo66.jpg)
## Keycodes
|Key |Aliases |Description |
@ -64,6 +66,9 @@ Changing the **Value** sets the overall brightness.<br>
|`RGB_MODE_GRADIENT`|`RGB_M_G` |Static gradient animation mode |
|`RGB_MODE_RGBTEST` |`RGB_M_T` |Red, Green, Blue test animation mode |
!> By default, if you have both the RGB Light and the [RGB Matrix](feature_rgb_matrix.md) feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature.
## Configuration
Your RGB lighting can be configured by placing these `#define`s in your `config.h`:
@ -76,6 +81,7 @@ Your RGB lighting can be configured by placing these `#define`s in your `config.
|`RGBLIGHT_LIMIT_VAL` |`255` |The maximum brightness level |
|`RGBLIGHT_SLEEP` |*Not defined*|If defined, the RGB lighting will be switched off when the host goes to sleep|
|`RGBLIGHT_SPLIT` |*Not defined*|If defined, synchronization functionality for split keyboards is added|
|`RGBLIGHT_DISABLE_KEYCODES`|*not defined*|If defined, disables the ability to control RGB Light from the keycodes. You must use code functions to control the feature|
## Effects and Animations
@ -94,6 +100,7 @@ if `RGBLIGHT_EFFECT_xxxx` or `RGBLIGHT_ANIMATIONS` is defined, you also have a n
|`RGBLIGHT_MODE_STATIC_GRADIENT`| 0,1,..,9 |Static gradient |
|`RGBLIGHT_MODE_RGB_TEST` | *None* |RGB Test |
|`RGBLIGHT_MODE_ALTERNATING` | *None* |Alternating |
|`RGBLIGHT_MODE_TWINKLE` | 0,1,2,3,4,5 |Twinkle |
Check out [this video](https://youtube.com/watch?v=VKrpPAHlisY) for a demonstration.
@ -103,8 +110,8 @@ Note: For versions older than 0.6.117, The mode numbers were written directly. I
Use these defines to add or remove animations from the firmware. When you are running low on flash space, it can be helpful to disable animations you are not using.
|Define |Default |Description |
|------------------------------------|-------------|-------------------------------------------------------------------------------------|
|Define |Default |Description |
|------------------------------------|-------------|-------------------------------------------------------------------------|
|`RGBLIGHT_ANIMATIONS` |*Not defined*|Enable all additional animation modes. |
|`RGBLIGHT_EFFECT_ALTERNATING` |*Not defined*|Enable alternating animation mode. |
|`RGBLIGHT_EFFECT_BREATHING` |*Not defined*|Enable breathing animation mode. |
@ -115,22 +122,25 @@ Use these defines to add or remove animations from the firmware. When you are ru
|`RGBLIGHT_EFFECT_RGB_TEST` |*Not defined*|Enable RGB test animation mode. |
|`RGBLIGHT_EFFECT_SNAKE` |*Not defined*|Enable snake animation mode. |
|`RGBLIGHT_EFFECT_STATIC_GRADIENT` |*Not defined*|Enable static gradient mode. |
|`RGBLIGHT_EFFECT_TWINKLE` |*Not defined*|Enable twinkle animation mode. |
### Effect and Animation Settings
The following options are used to tweak the various animations:
|Define |Default |Description |
|------------------------------------|-------------|-------------------------------------------------------------------------------------|
|Define |Default |Description |
|------------------------------------|-------------|-----------------------------------------------------------------------------------------------|
|`RGBLIGHT_EFFECT_BREATHE_CENTER` |*Not defined*|If defined, used to calculate the curve for the breathing animation. Valid values are 1.0 to 2.7 |
|`RGBLIGHT_EFFECT_BREATHE_MAX` |`255` |The maximum brightness for the breathing mode. Valid values are 1 to 255 |
|`RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL`|`1000` |How long to wait between light changes for the "Christmas" animation, in milliseconds|
|`RGBLIGHT_EFFECT_CHRISTMAS_STEP` |`2` |The number of LEDs to group the red/green colors by for the "Christmas" animation |
|`RGBLIGHT_EFFECT_KNIGHT_LED_NUM` |`RGBLED_NUM` |The number of LEDs to have the "Knight" animation travel |
|`RGBLIGHT_EFFECT_KNIGHT_LENGTH` |`3` |The number of LEDs to light up for the "Knight" animation |
|`RGBLIGHT_EFFECT_KNIGHT_OFFSET` |`0` |The number of LEDs to start the "Knight" animation from the start of the strip by |
|`RGBLIGHT_RAINBOW_SWIRL_RANGE` |`255` |Range adjustment for the rainbow swirl effect to get different swirls |
|`RGBLIGHT_EFFECT_SNAKE_LENGTH` |`4` |The number of LEDs to light up for the "Snake" animation |
|`RGBLIGHT_EFFECT_BREATHE_MAX` |`255` |The maximum brightness for the breathing mode. Valid values are 1 to 255 |
|`RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL`|`40` |How long (in milliseconds) to wait between animation steps for the "Christmas" animation |
|`RGBLIGHT_EFFECT_CHRISTMAS_STEP` |`2` |The number of LEDs to group the red/green colors by for the "Christmas" animation |
|`RGBLIGHT_EFFECT_KNIGHT_LED_NUM` |`RGBLED_NUM` |The number of LEDs to have the "Knight" animation travel |
|`RGBLIGHT_EFFECT_KNIGHT_LENGTH` |`3` |The number of LEDs to light up for the "Knight" animation |
|`RGBLIGHT_EFFECT_KNIGHT_OFFSET` |`0` |The number of LEDs to start the "Knight" animation from the start of the strip by |
|`RGBLIGHT_RAINBOW_SWIRL_RANGE` |`255` |Range adjustment for the rainbow swirl effect to get different swirls |
|`RGBLIGHT_EFFECT_SNAKE_LENGTH` |`4` |The number of LEDs to light up for the "Snake" animation |
|`RGBLIGHT_EFFECT_TWINKLE_LIFE` |`75` |Adjusts how quickly each LED brightens and dims when twinkling (in animation steps) |
|`RGBLIGHT_EFFECT_TWINKLE_PROBABILITY`|`1/127` |Adjusts how likely each LED is to twinkle (on each animation step) |
### Example Usage to Reduce Memory Footprint
1. Remove `RGBLIGHT_ANIMATIONS` from `config.h`.
@ -168,16 +178,25 @@ const uint8_t RGBLED_SNAKE_INTERVALS[] PROGMEM = {100, 50, 20};
// How long (in milliseconds) to wait between animation steps for each of the "Knight" animations
const uint8_t RGBLED_KNIGHT_INTERVALS[] PROGMEM = {127, 63, 31};
// How long (in milliseconds) to wait between animation steps for each of the "Twinkle" animations
const uint8_t RGBLED_TWINKLE_INTERVALS[] PROGMEM = {50, 25, 10};
// These control which hues are selected for each of the "Static gradient" modes
const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64};
```
## Lighting Layers
?> **Note:** Lighting Layers is an RGB Light feature, it will not work for RGB Matrix. See [RGB Matrix Indicators](feature_rgb_matrix.md?indicators) for details on how to do so.
By including `#define RGBLIGHT_LAYERS` in your `config.h` file you can enable lighting layers. These make
it easy to use your underglow LEDs as status indicators to show which keyboard layer is currently active, or the state of caps lock, all without disrupting any animations. [Here's a video](https://youtu.be/uLGE1epbmdY) showing an example of what you can do.
To define a layer, we modify `keymap.c` to list out LED ranges and the colors we want to overlay on them using an array of `rgblight_segment_t` using the `RGBLIGHT_LAYER_SEGMENTS` macro. We can define multiple layers and enable/disable them independently:
### Defining Lighting Layers :id=defining-lighting-layers
By default, 8 layers are possible. This can be expanded to as many as 32 by overriding the definition of `RGBLIGHT_MAX_LAYERS` in `config.h` (e.g. `#define RGBLIGHT_MAX_LAYERS 32`). Please note, if you use a split keyboard, you will need to flash both sides of the split after changing this. Also, increasing the maximum will increase the firmware size, and will slow sync on split keyboards.
To define a layer, we modify `keymap.c` to list the LED ranges and the colors we want to overlay on them using an array of `rgblight_segment_t` using the `RGBLIGHT_LAYER_SEGMENTS` macro. We can define multiple layers and enable/disable them independently:
```c
// Light LEDs 6 to 9 and 12 to 15 red when caps lock is active. Hard to ignore!
@ -193,6 +212,10 @@ const rgblight_segment_t PROGMEM my_layer1_layer[] = RGBLIGHT_LAYER_SEGMENTS(
const rgblight_segment_t PROGMEM my_layer2_layer[] = RGBLIGHT_LAYER_SEGMENTS(
{11, 2, HSV_PURPLE}
);
// Light LEDs 13 & 14 in green when keyboard layer 3 is active
const rgblight_segment_t PROGMEM my_layer3_layer[] = RGBLIGHT_LAYER_SEGMENTS(
{13, 2, HSV_GREEN}
);
// etc..
```
@ -203,7 +226,8 @@ We combine these layers into an array using the `RGBLIGHT_LAYERS_LIST` macro, an
const rgblight_segment_t* const PROGMEM my_rgb_layers[] = RGBLIGHT_LAYERS_LIST(
my_capslock_layer,
my_layer1_layer, // Overrides caps lock layer
my_layer2_layer // Overrides other layers
my_layer2_layer, // Overrides other layers
my_layer3_layer // Overrides other layers
);
void keyboard_post_init_user(void) {
@ -211,24 +235,69 @@ void keyboard_post_init_user(void) {
rgblight_layers = my_rgb_layers;
}
```
Note: For split keyboards with two controllers, both sides need to be flashed when updating the contents of rgblight_layers.
Finally, we enable and disable the lighting layers whenever the state of the keyboard changes:
### Enabling and disabling lighting layers :id=enabling-lighting-layers
Everything above just configured the definition of each lighting layer.
We can now enable and disable the lighting layers whenever the state of the keyboard changes:
```c
layer_state_t layer_state_set_user(layer_state_t state) {
// Both layers will light up if both kb layers are active
rgblight_set_layer_state(1, layer_state_cmp(state, 1));
rgblight_set_layer_state(2, layer_state_cmp(state, 2));
return state;
}
bool led_update_user(led_t led_state) {
rgblight_set_layer_state(0, led_state.caps_lock);
return true;
}
layer_state_t default_layer_state_set_user(layer_state_t state) {
rgblight_set_layer_state(1, layer_state_cmp(state, _DVORAK));
return state;
}
layer_state_t layer_state_set_user(layer_state_t state) {
rgblight_set_layer_state(2, layer_state_cmp(state, _FN));
rgblight_set_layer_state(3, layer_state_cmp(state, _ADJUST));
return state;
}
```
Note: For split keyboards with two controllers, both sides need to be flashed when updating the contents of rgblight_layers.
### Lighting layer blink :id=lighting-layer-blink
By including `#define RGBLIGHT_LAYER_BLINK` in your `config.h` file you can turn a lighting
layer on for a specified duration. Once the specified number of milliseconds has elapsed
the layer will be turned off. This is useful, e.g., if you want to acknowledge some
action (e.g. toggling some setting):
```c
const rgblight_segment_t PROGMEM _yes_layer[] = RGBLIGHT_LAYER_SEGMENTS( {9, 6, HSV_GREEN} );
const rgblight_segment_t PROGMEM _no_layer[] = RGBLIGHT_LAYER_SEGMENTS( {9, 6, HSV_RED} );
const rgblight_segment_t* const PROGMEM _rgb_layers[] =
RGBLIGHT_LAYERS_LIST( _yes_layer, _no_layer );
void keyboard_post_init_user(void) {
rgblight_layers = _rgb_layers;
}
// Note we user post_process_record_user because we want the state
// after the flag has been flipped...
void post_process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case DEBUG:
rgblight_blink_layer(debug_enable ? 0 : 1, 500);
break;
case NK_TOGG:
case NK_ON:
case NK_OFF:
rgblight_blink_layer(keymap_config.nkro ? 0 : 1, 500);
break;
}
}
```
### Overriding RGB Lighting on/off status
Normally lighting layers are not shown when RGB Lighting is disabled (e.g. with `RGB_TOG` keycode). If you would like lighting layers to work even when the RGB Lighting is otherwise off, add `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF` to your `config.h`.
## Functions
@ -292,6 +361,7 @@ rgblight_sethsv(HSV_GREEN, 2); // led 2
|`rgblight_step_noeeprom()` |Change the mode to the next RGB animation in the list of enabled RGB animations (not written to EEPROM) |
|`rgblight_step_reverse()` |Change the mode to the previous RGB animation in the list of enabled RGB animations |
|`rgblight_step_reverse_noeeprom()` |Change the mode to the previous RGB animation in the list of enabled RGB animations (not written to EEPROM) |
|`rgblight_reload_from_eeprom()` |Reload the effect configuration (enabled, mode and color) from EEPROM |
#### effects mode disable/enable
|Function |Description |
@ -310,17 +380,28 @@ rgblight_sethsv(HSV_GREEN, 2); // led 2
|`rgblight_increase_hue_noeeprom()` |Increase the hue for effect range LEDs. This wraps around at maximum hue (not written to EEPROM) |
|`rgblight_decrease_hue()` |Decrease the hue for effect range LEDs. This wraps around at minimum hue |
|`rgblight_decrease_hue_noeeprom()` |Decrease the hue for effect range LEDs. This wraps around at minimum hue (not written to EEPROM) |
|`rgblight_increase_sat()` |Increase the saturation for effect range LEDs. This wraps around at maximum saturation |
|`rgblight_increase_sat_noeeprom()` |Increase the saturation for effect range LEDs. This wraps around at maximum saturation (not written to EEPROM) |
|`rgblight_decrease_sat()` |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation |
|`rgblight_decrease_sat_noeeprom()` |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation (not written to EEPROM) |
|`rgblight_increase_val()` |Increase the value for effect range LEDs. This wraps around at maximum value |
|`rgblight_increase_val_noeeprom()` |Increase the value for effect range LEDs. This wraps around at maximum value (not written to EEPROM) |
|`rgblight_decrease_val()` |Decrease the value for effect range LEDs. This wraps around at minimum value |
|`rgblight_decrease_val_noeeprom()` |Decrease the value for effect range LEDs. This wraps around at minimum value (not written to EEPROM) |
|`rgblight_increase_sat()` |Increase the saturation for effect range LEDs. This stops at maximum saturation |
|`rgblight_increase_sat_noeeprom()` |Increase the saturation for effect range LEDs. This stops at maximum saturation (not written to EEPROM) |
|`rgblight_decrease_sat()` |Decrease the saturation for effect range LEDs. This stops at minimum saturation |
|`rgblight_decrease_sat_noeeprom()` |Decrease the saturation for effect range LEDs. This stops at minimum saturation (not written to EEPROM) |
|`rgblight_increase_val()` |Increase the value for effect range LEDs. This stops at maximum value |
|`rgblight_increase_val_noeeprom()` |Increase the value for effect range LEDs. This stops at maximum value (not written to EEPROM) |
|`rgblight_decrease_val()` |Decrease the value for effect range LEDs. This stops at minimum value |
|`rgblight_decrease_val_noeeprom()` |Decrease the value for effect range LEDs. This stops at minimum value (not written to EEPROM) |
|`rgblight_sethsv(h, s, v)` |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 |
|`rgblight_sethsv_noeeprom(h, s, v)` |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) |
#### Speed functions
|Function |Description |
|--------------------------------------------|-------------|
|`rgblight_increase_speed()` |Increases the animation speed |
|`rgblight_increase_speed_noeeprom()` |Increases the animation speed (not written to EEPROM) |
|`rgblight_decrease_speed()` |Decreases the animation speed |
|`rgblight_decrease_speed_noeeprom()` |Decreases the animation speed (not written to EEPROM) |
|`rgblight_set_speed()` |Sets the speed. Value is between 0 and 255 |
|`rgblight_set_speed_noeeprom()` |Sets the speed. Value is between 0 and 255 (not written to EEPROM) |
#### layer functions
|Function |Description |
|--------------------------------------------|-------------|
@ -328,12 +409,14 @@ rgblight_sethsv(HSV_GREEN, 2); // led 2
|`rgblight_set_layer_state(i, is_on)` |Enable or disable lighting layer `i` based on value of `bool is_on` |
#### query
|Function |Description |
|-----------------------|-----------------|
|`rgblight_get_mode()` |Get current mode |
|`rgblight_get_hue()` |Get current hue |
|`rgblight_get_sat()` |Get current sat |
|`rgblight_get_val()` |Get current val |
|Function |Description |
|-----------------------|---------------------------|
|`rgblight_is_enabled()`|Gets current on/off status |
|`rgblight_get_mode()` |Gets current mode |
|`rgblight_get_hue()` |Gets current hue |
|`rgblight_get_sat()` |Gets current sat |
|`rgblight_get_val()` |Gets current val |
|`rgblight_get_speed()` |Gets current speed |
## Colors

87
docs/feature_sequencer.md Normal file
View file

@ -0,0 +1,87 @@
# Sequencer
Since QMK has experimental support for MIDI, you can now turn your keyboard into a [step sequencer](https://en.wikipedia.org/wiki/Music_sequencer#Step_sequencers)!
!> **IMPORTANT:** This feature is highly experimental, it has only been tested on a Planck EZ so far. Also, the scope will be limited to support the drum machine use-case to start with.
## Enable the step sequencer
Add the following line to your `rules.mk`:
```make
SEQUENCER_ENABLE = yes
```
By default the sequencer has 16 steps, but you can override this setting in your `config.h`:
```c
#define SEQUENCER_STEPS 32
```
## Tracks
You can program up to 8 independent tracks with the step sequencer. Select the tracks you want to edit, enable or disable some steps, and start the sequence!
## Resolutions
While the tempo defines the absolute speed at which the sequencer goes through the steps, the resolution defines the granularity of these steps (from coarser to finer).
|Resolution |Description |
|---------- |----------- |
|`SQ_RES_2` |Every other beat |
|`SQ_RES_2T` |Every 1.5 beats |
|`SQ_RES_4` |Every beat |
|`SQ_RES_4T` |Three times per 2 beats|
|`SQ_RES_8` |Twice per beat |
|`SQ_RES_8T` |Three times per beat |
|`SQ_RES_16` |Four times per beat |
|`SQ_RES_16T` |Six times per beat |
|`SQ_RES_32` |Eight times per beat |
## Keycodes
|Keycode |Description |
|------- |----------- |
|`SQ_ON` |Start the step sequencer |
|`SQ_OFF` |Stop the step sequencer |
|`SQ_TOG` |Toggle the step sequencer playback |
|`SQ_SALL`|Enable all the steps |
|`SQ_SCLR`|Disable all the steps |
|`SQ_S(n)`|Toggle the step `n` |
|`SQ_TMPD`|Decrease the tempo |
|`SQ_TMPU`|Increase the tempo |
|`SQ_R(n)`|Set the resolution to n |
|`SQ_RESD`|Change to the slower resolution |
|`SQ_RESU`|Change to the faster resolution |
|`SQ_T(n)`|Set `n` as the only active track or deactivate all |
## Functions
|Function |Description |
|-------- |----------- |
|`bool is_sequencer_on(void);` |Return whether the sequencer is playing |
|`void sequencer_toggle(void);` |Toggle the step sequencer playback |
|`void sequencer_on(void);` |Start the step sequencer |
|`void sequencer_off(void);` |Stop the step sequencer |
|`bool is_sequencer_step_on(uint8_t step);` |Return whether the step is currently enabled |
|`void sequencer_set_step(uint8_t step, bool value);` |Enable or disable the step |
|`void sequencer_set_step_on();` |Enable the step |
|`void sequencer_set_step_off();` |Disable the step |
|`void sequencer_toggle_step(uint8_t step);` |Toggle the step |
|`void sequencer_set_all_steps(bool value);` |Enable or disable all the steps |
|`void sequencer_set_all_steps_on();` |Enable all the steps |
|`void sequencer_set_all_steps_off();` |Disable all the steps |
|`uint8_t sequencer_get_tempo(void);` |Return the current tempo |
|`void sequencer_set_tempo(uint8_t tempo);` |Set the tempo to `tempo` (between 1 and 255) |
|`void sequencer_increase_tempo(void);` |Increase the tempo |
|`void sequencer_decrease_tempo(void);` |Decrease the tempo |
|`sequencer_resolution_t sequencer_get_resolution(void);` |Return the current resolution |
|`void sequencer_set_resolution(sequencer_resolution_t resolution);` |Set the resolution to `resolution` |
|`void sequencer_increase_resolution(void);` |Change to the faster resolution |
|`void sequencer_decrease_resolution(void);` |Change to the slower resolution |
|`bool is_sequencer_track_active(uint8_t track);` |Return whether the track is active |
|`void sequencer_set_track_activation(uint8_t track, bool value);` |Activate or deactivate the `track` |
|`void sequencer_toggle_track_activation(uint8_t track);` |Toggle the `track` |
|`void sequencer_activate_track(uint8_t track);` |Activate the `track` |
|`void sequencer_deactivate_track(uint8_t track);` |Deactivate the `track` |
|`void sequencer_toggle_single_active_track(uint8_t track);` |Set `track` as the only active track or deactivate all |

2
docs/feature_space_cadet.md
View file

@ -1,6 +1,6 @@
# Space Cadet: The Future, Built In
Steve Losh described the [Space Cadet Shift](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) quite well. Essentially, when you tap Left Shift on its own, you get an opening parenthesis; tap Right Shift on its own and you get the closing one. When held, the Shift keys function as normal. Yes, it's as cool as it sounds, and now even cooler supporting Control and Alt as well!
Steve Losh described the [Space Cadet Shift](https://stevelosh.com/blog/2012/10/a-modern-space-cadet/) quite well. Essentially, when you tap Left Shift on its own, you get an opening parenthesis; tap Right Shift on its own and you get the closing one. When held, the Shift keys function as normal. Yes, it's as cool as it sounds, and now even cooler supporting Control and Alt as well!
## Usage

Some files were not shown because too many files have changed in this diff Show more