keyboard/qmk-keychron-q3-colemak-dh
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'qmk/master' into vial

Browse Source
This commit is contained in:
Ilya Zhuravlev 2021-03-03 11:12:07 -05:00
commit ce49d6f644
8590 changed files with 251958 additions and 200116 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

47
.github/workflows/format.yaml vendored Normal file
View File

@ -0,0 +1,47 @@
name: Format Codebase
on:
push:
branches:
- master
- develop
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: rlespinasse/github-slug-action@v3.x
- 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
branch: bugfix/format_${{ env.GITHUB_REF_SLUG }}
author: QMK Bot <hello@qmk.fm>
committer: QMK Bot <hello@qmk.fm>
commit-message: Format code according to conventions
title: '[CI] Format code according to conventions'

54
.github/workflows/info.yml vendored
View File

@ -1,54 +0,0 @@
name: PR Lint keyboards
on:
pull_request:
paths:
- 'keyboards/**'
jobs:
info:
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 info
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}"
# TODO: info info always returns 0 - right now the only way to know failure is to inspect log lines
qmk info -l -kb ${KB} 2>&1 | tee /tmp/$$
!(grep -cq ☒ /tmp/$$)
: $((exit_code = $exit_code + $?))
fi
done
exit $exit_code

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

1
.gitignore vendored
View File

@ -17,6 +17,7 @@
*.swp
tags
*~
api_data/v1
build/
.build/
*.bak

6
.travis.yml
View File

@ -18,21 +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:

135
Makefile
View File

@ -68,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:
@ -158,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
@ -217,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,)
@ -272,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
@ -398,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 := \
@ -447,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
@ -466,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 \
@ -557,13 +496,13 @@ 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 bin/qmk works. This will be a failing check after the next develop merge on 2020 Aug 29.
if ! bin/qmk hello 1> /dev/null 2>&1; then printf "$(MSG_PYTHON_MISSING)"; fi
# Ensure that bin/qmk works.
if ! bin/qmk hello 1> /dev/null 2>&1; then printf "$(MSG_PYTHON_MISSING)"; exit 1; fi
# Check if the submodules are dirty, and display a warning if they are
ifndef SKIP_GIT
if [ ! -e lib/chibios ]; then git submodule sync lib/chibios && git submodule update --depth 50 --init lib/chibios; fi
@ -593,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 $?
@ -637,13 +557,14 @@ 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)
$(shell python3 util/build_id.py >> $(ROOT_DIR)/quantum/version.h)
else
BUILD_DATE := NA
endif
include $(ROOT_DIR)/testlist.mk

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.

3
bin/qmk
View File

@ -27,7 +27,8 @@ def _check_modules(requirements):
line = line.split('#')[0]
module = dict()
module['name'] = module['import'] = line.split('=')[0] if '=' in line else line
module['name'] = line.split('=')[0] if '=' in line else line
module['import'] = module['name'].replace('-', '_')
# Not every module is importable by its own name.
if module['name'] == "pep8-naming":

49
bootloader.mk
View File

@ -20,15 +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)
# kiibohd Input:Club Kiibohd bootloader (only used on their boards)
# stm32duino STM32Duino (STM32F103x8)
# 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
@ -36,7 +40,7 @@
ifeq ($(strip $(BOOTLOADER)), atmel-dfu)
OPT_DEFS += -DBOOTLOADER_ATMEL_DFU
OPT_DEFS += -DBOOTLOADER_DFU
ifneq (,$(filter $(MCU), atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647))
ifneq (,$(filter $(MCU), at90usb162 atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647))
BOOTLOADER_SIZE = 4096
endif
ifneq (,$(filter $(MCU), at90usb1286 at90usb1287))
@ -46,7 +50,7 @@ endif
ifeq ($(strip $(BOOTLOADER)), lufa-dfu)
OPT_DEFS += -DBOOTLOADER_LUFA_DFU
OPT_DEFS += -DBOOTLOADER_DFU
ifneq (,$(filter $(MCU), atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647))
ifneq (,$(filter $(MCU), at90usb162 atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647))
BOOTLOADER_SIZE = 4096
endif
ifneq (,$(filter $(MCU), at90usb1286 at90usb1287))
@ -56,7 +60,7 @@ endif
ifeq ($(strip $(BOOTLOADER)), qmk-dfu)
OPT_DEFS += -DBOOTLOADER_QMK_DFU
OPT_DEFS += -DBOOTLOADER_DFU
ifneq (,$(filter $(MCU), atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647))
ifneq (,$(filter $(MCU), at90usb162 atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647))
BOOTLOADER_SIZE = 4096
endif
ifneq (,$(filter $(MCU), at90usb1286 at90usb1287))
@ -95,6 +99,20 @@ 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)
@ -104,18 +122,19 @@ ifeq ($(strip $(BOOTLOADER)), kiibohd)
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
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
DFU_ARGS = -d 1EAF:0003 -a2 -R
# 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

67
build_keyboard.mk
View File

@ -90,13 +90,16 @@ ifneq ("$(wildcard $(KEYBOARD_PATH_1)/rules.mk)","")
include $(KEYBOARD_PATH_1)/rules.mk
endif
MAIN_KEYMAP_PATH_1 := $(KEYBOARD_PATH_1)/keymaps/$(KEYMAP)
MAIN_KEYMAP_PATH_2 := $(KEYBOARD_PATH_2)/keymaps/$(KEYMAP)
MAIN_KEYMAP_PATH_3 := $(KEYBOARD_PATH_3)/keymaps/$(KEYMAP)
MAIN_KEYMAP_PATH_4 := $(KEYBOARD_PATH_4)/keymaps/$(KEYMAP)
MAIN_KEYMAP_PATH_5 := $(KEYBOARD_PATH_5)/keymaps/$(KEYMAP)
# Pull in rules from info.json
INFO_RULES_MK = $(shell bin/qmk generate-rules-mk --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/rules.mk)
include $(INFO_RULES_MK)
# Check for keymap.json first, so we can regenerate keymap.c
include build_json.mk
@ -136,9 +139,7 @@ ifeq ($(strip $(CTPC)), yes)
endif
ifeq ($(strip $(CONVERT_TO_PROTON_C)), yes)
TARGET := $(TARGET)_proton_c
include platforms/chibios/GENERIC_STM32_F303XC/configs/proton_c.mk
OPT_DEFS += -DCONVERT_TO_PROTON_C
include platforms/chibios/QMK_PROTON_C/convert_to_proton_c.mk
endif
ifneq ($(FORCE_LAYOUT),)
@ -272,6 +273,36 @@ ifneq ("$(wildcard $(KEYBOARD_PATH_5)/post_config.h)","")
POST_CONFIG_H += $(KEYBOARD_PATH_5)/post_config.h
endif
# Pull in stuff from info.json
INFO_JSON_FILES :=
ifneq ("$(wildcard $(KEYBOARD_PATH_1)/info.json)","")
INFO_JSON_FILES += $(KEYBOARD_PATH_1)/info.json
endif
ifneq ("$(wildcard $(KEYBOARD_PATH_2)/info.json)","")
INFO_JSON_FILES += $(KEYBOARD_PATH_2)/info.json
endif
ifneq ("$(wildcard $(KEYBOARD_PATH_3)/info.json)","")
INFO_JSON_FILES += $(KEYBOARD_PATH_3)/info.json
endif
ifneq ("$(wildcard $(KEYBOARD_PATH_4)/info.json)","")
INFO_JSON_FILES += $(KEYBOARD_PATH_4)/info.json
endif
ifneq ("$(wildcard $(KEYBOARD_PATH_5)/info.json)","")
INFO_JSON_FILES += $(KEYBOARD_PATH_5)/info.json
endif
CONFIG_H += $(KEYBOARD_OUTPUT)/src/info_config.h $(KEYBOARD_OUTPUT)/src/layouts.h
$(KEYBOARD_OUTPUT)/src/info_config.h: $(INFO_JSON_FILES)
bin/qmk generate-config-h --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/info_config.h
$(KEYBOARD_OUTPUT)/src/layouts.h: $(INFO_JSON_FILES)
bin/qmk generate-layouts --quiet --keyboard $(KEYBOARD) --output $(KEYBOARD_OUTPUT)/src/layouts.h
generated-files: $(KEYBOARD_OUTPUT)/src/info_config.h $(KEYBOARD_OUTPUT)/src/layouts.h
.INTERMEDIATE : generated-files
# Userspace setup and definitions
ifeq ("$(USER_NAME)","")
USER_NAME := $(KEYMAP)
@ -282,6 +313,12 @@ USER_PATH := users/$(USER_NAME)
ifneq ("$(wildcard $(USER_PATH)/config.h)","")
CONFIG_H += $(USER_PATH)/config.h
endif
ifneq ("$(wildcard $(USER_PATH)/post_config.h)","")
POST_CONFIG_H += $(USER_PATH)/post_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
@ -317,6 +354,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
@ -341,7 +385,7 @@ ALL_CONFIGS := $(PROJECT_CONFIG) $(CONFIG_H)
OUTPUTS := $(KEYMAP_OUTPUT) $(KEYBOARD_OUTPUT)
$(KEYMAP_OUTPUT)_SRC := $(SRC)
$(KEYMAP_OUTPUT)_DEFS := $(OPT_DEFS) $(GFXDEFS) \
-DQMK_KEYBOARD=\"$(KEYBOARD)\" -DQMK_KEYBOARD_H=\"$(QMK_KEYBOARD_H)\" -DQMK_KEYBOARD_CONFIG_H=\"$(KEYBOARD_PATH_1)/config.h\" \
-DQMK_KEYBOARD=\"$(KEYBOARD)\" -DQMK_KEYBOARD_H=\"$(QMK_KEYBOARD_H)\" \
-DQMK_KEYMAP=\"$(KEYMAP)\" -DQMK_KEYMAP_H=\"$(KEYMAP).h\" -DQMK_KEYMAP_CONFIG_H=\"$(KEYMAP_PATH)/config.h\" \
-DQMK_SUBPROJECT -DQMK_SUBPROJECT_H -DQMK_SUBPROJECT_CONFIG_H
$(KEYMAP_OUTPUT)_INC := $(VPATH) $(EXTRAINCDIRS)
@ -352,10 +396,23 @@ $(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
include $(TMK_PATH)/rules.mk
# Ensure we have generated files available for each of the objects
define GEN_FILES
$1: generated-files
endef
$(foreach O,$(OBJ),$(eval $(call GEN_FILES,$(patsubst %.a,%.o,$(O)))))

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)

246
common_features.mk
View File

@ -17,9 +17,19 @@ SERIAL_PATH := $(QUANTUM_PATH)/serial_link
QUANTUM_SRC += \
$(QUANTUM_DIR)/quantum.c \
$(QUANTUM_DIR)/send_string.c \
$(QUANTUM_DIR)/bitwise.c \
$(QUANTUM_DIR)/led.c \
$(QUANTUM_DIR)/keymap_common.c \
$(QUANTUM_DIR)/keycode_config.c
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
@ -28,16 +38,47 @@ 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
AUDIO_ENABLE ?= no
ifeq ($(strip $(AUDIO_ENABLE)), yes)
ifeq ($(PLATFORM),CHIBIOS)
AUDIO_DRIVER ?= dac_basic
ifeq ($(strip $(AUDIO_DRIVER)), dac_basic)
OPT_DEFS += -DAUDIO_DRIVER_DAC
else ifeq ($(strip $(AUDIO_DRIVER)), dac_additive)
OPT_DEFS += -DAUDIO_DRIVER_DAC
## stm32f2 and above have a usable DAC unit, f1 do not, and need to use pwm instead
else ifeq ($(strip $(AUDIO_DRIVER)), pwm_software)
OPT_DEFS += -DAUDIO_DRIVER_PWM
else ifeq ($(strip $(AUDIO_DRIVER)), pwm_hardware)
OPT_DEFS += -DAUDIO_DRIVER_PWM
endif
else
# fallback for all other platforms is pwm
AUDIO_DRIVER ?= pwm_hardware
OPT_DEFS += -DAUDIO_DRIVER_PWM
endif
OPT_DEFS += -DAUDIO_ENABLE
MUSIC_ENABLE = yes
SRC += $(QUANTUM_DIR)/process_keycode/process_audio.c
SRC += $(QUANTUM_DIR)/process_keycode/process_clicky.c
SRC += $(QUANTUM_DIR)/audio/audio_$(PLATFORM_KEY).c
SRC += $(QUANTUM_DIR)/audio/audio.c ## common audio code, hardware agnostic
SRC += $(QUANTUM_DIR)/audio/driver_$(PLATFORM_KEY)_$(strip $(AUDIO_DRIVER)).c
SRC += $(QUANTUM_DIR)/audio/voices.c
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
@ -59,9 +100,10 @@ ifeq ($(strip $(VIRTSER_ENABLE)), yes)
OPT_DEFS += -DVIRTSER_ENABLE
endif
ifeq ($(strip $(FAUXCLICKY_ENABLE)), yes)
OPT_DEFS += -DFAUXCLICKY_ENABLE
SRC += $(QUANTUM_DIR)/fauxclicky.c
ifeq ($(strip $(MOUSEKEY_ENABLE)), yes)
OPT_DEFS += -DMOUSEKEY_ENABLE
OPT_DEFS += -DMOUSE_ENABLE
SRC += $(QUANTUM_DIR)/mousekey.c
endif
ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
@ -114,6 +156,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
@ -130,26 +183,47 @@ else
endif
endif
RGBLIGHT_ENABLE ?= no
VALID_RGBLIGHT_TYPES := WS2812 APA102 custom
ifeq ($(strip $(RGBLIGHT_CUSTOM_DRIVER)), yes)
RGBLIGHT_DRIVER ?= custom
endif
ifeq ($(strip $(RGBLIGHT_ENABLE)), yes)
POST_CONFIG_H += $(QUANTUM_DIR)/rgblight_post_config.h
OPT_DEFS += -DRGBLIGHT_ENABLE
SRC += $(QUANTUM_DIR)/color.c
SRC += $(QUANTUM_DIR)/rgblight.c
CIE1931_CURVE := yes
RGB_KEYCODES_ENABLE := yes
ifeq ($(strip $(RGBLIGHT_CUSTOM_DRIVER)), yes)
OPT_DEFS += -DRGBLIGHT_CUSTOM_DRIVER
RGBLIGHT_DRIVER ?= WS2812
ifeq ($(filter $(RGBLIGHT_DRIVER),$(VALID_RGBLIGHT_TYPES)),)
$(error RGBLIGHT_DRIVER="$(RGBLIGHT_DRIVER)" is not a valid RGB type)
else
POST_CONFIG_H += $(QUANTUM_DIR)/rgblight_post_config.h
OPT_DEFS += -DRGBLIGHT_ENABLE
SRC += $(QUANTUM_DIR)/color.c
SRC += $(QUANTUM_DIR)/rgblight.c
CIE1931_CURVE := yes
RGB_KEYCODES_ENABLE := yes
endif
ifeq ($(strip $(RGBLIGHT_DRIVER)), WS2812)
WS2812_DRIVER_REQUIRED := yes
endif
ifeq ($(strip $(RGBLIGHT_DRIVER)), APA102)
APA102_DRIVER_REQUIRED := yes
endif
ifeq ($(strip $(RGBLIGHT_DRIVER)), custom)
OPT_DEFS += -DRGBLIGHT_CUSTOM_DRIVER
endif
endif
VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 IS31FL3737 IS31FL3741 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,72 +231,78 @@ 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 at90usb162))
# ATmegaxxU2 does not have hardware MUL instruction - lib8tion must be told to use software multiplication routines
OPT_DEFS += -DLIB8_ATTINY
endif
SRC += $(QUANTUM_DIR)/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)), 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_DRIVER)), WS2812)
OPT_DEFS += -DWS2812
WS2812_DRIVER_REQUIRED := yes
endif
ifeq ($(strip $(RGB_MATRIX_ENABLE)), WS2812)
OPT_DEFS += -DWS2812
WS2812_DRIVER_REQUIRED := yes
endif
ifeq ($(strip $(RGB_MATRIX_DRIVER)), APA102)
OPT_DEFS += -DAPA102
APA102_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)
@ -318,6 +398,11 @@ ifeq ($(strip $(WS2812_DRIVER_REQUIRED)), yes)
endif
endif
ifeq ($(strip $(APA102_DRIVER_REQUIRED)), yes)
COMMON_VPATH += $(DRIVER_PATH)/apa102
SRC += apa102.c
endif
ifeq ($(strip $(VISUALIZER_ENABLE)), yes)
CIE1931_CURVE := yes
endif
@ -443,15 +528,18 @@ ifeq ($(strip $(SPLIT_KEYBOARD)), yes)
# Determine which (if any) transport files are required
ifneq ($(strip $(SPLIT_TRANSPORT)), custom)
QUANTUM_SRC += $(QUANTUM_DIR)/split_common/transport.c
QUANTUM_LIB_SRC += $(QUANTUM_DIR)/split_common/transport.c
# 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
@ -581,3 +669,27 @@ endif
ifeq ($(strip $(JOYSTICK_ENABLE)), digital)
OPT_DEFS += -DDIGITAL_JOYSTICK_ENABLE
endif
USBPD_ENABLE ?= no
VALID_USBPD_DRIVER_TYPES = custom vendor
USBPD_DRIVER ?= vendor
ifeq ($(strip $(USBPD_ENABLE)), yes)
ifeq ($(filter $(strip $(USBPD_DRIVER)),$(VALID_USBPD_DRIVER_TYPES)),)
$(error USBPD_DRIVER="$(USBPD_DRIVER)" is not a valid USBPD driver)
else
OPT_DEFS += -DUSBPD_ENABLE
ifeq ($(strip $(USBPD_DRIVER)), vendor)
# Vendor-specific implementations
OPT_DEFS += -DUSBPD_VENDOR
ifeq ($(strip $(MCU_SERIES)), STM32G4xx)
OPT_DEFS += -DUSBPD_STM32G4
SRC += usbpd_stm32g4.c
else
$(error There is no vendor-provided USBPD driver available)
endif
else ifeq ($(strip $(USBPD_DRIVER)), custom)
OPT_DEFS += -DUSBPD_CUSTOM
# Board designers can add their own driver to $(SRC)
endif
endif
endif

46
data/mappings/info_config.json Normal file
View File

@ -0,0 +1,46 @@
# This file maps keys between `config.h` and `info.json`. It is used by QMK
# to correctly and consistently map back and forth between the two systems.
{
# Format:
# <config.h key>: {"info_key": <info.json key>, ["value_type": <value_type>], ["to_json": <true/false>], ["to_c": <true/false>]}
# value_type: one of "array", "array.int", "int", "hex", "list", "mapping"
# to_json: Default `true`. Set to `false` to exclude this mapping from info.json
# to_c: Default `true`. Set to `false` to exclude this mapping from config.h
# warn_duplicate: Default `true`. Set to `false` to turn off warning when a value exists in both places
"DEBOUNCE": {"info_key": "debounce", "value_type": "int"}
"DEVICE_VER": {"info_key": "usb.device_ver", "value_type": "hex"},
"DESCRIPTION": {"info_key": "keyboard_folder", "to_json": false},
"DIODE_DIRECTION": {"info_key": "diode_direction"},
"LAYOUTS": {"info_key": "layout_aliases", "value_type": "mapping"},
"LED_CAPS_LOCK_PIN": {"info_key": "indicators.caps_lock"},
"LED_NUM_LOCK_PIN": {"info_key": "indicators.num_lock"},
"LED_SCROLL_LOCK_PIN": {"info_key": "indicators.scroll_lock"},
"MANUFACTURER": {"info_key": "manufacturer"},
"RGB_DI_PIN": {"info_key": "rgblight.pin"},
"RGBLED_NUM": {"info_key": "rgblight.led_count", "value_type": "int"},
"RGBLED_SPLIT": {"info_key": "rgblight.split_count", "value_type": "array.int"},
"RGBLIGHT_ANIMATIONS": {"info_key": "rgblight.animations.all", "value_type": "bool"},
"RGBLIGHT_EFFECT_ALTERNATING": {"info_key": "rgblight.animations.alternating", "value_type": "bool"},
"RGBLIGHT_EFFECT_BREATHING": {"info_key": "rgblight.animations.breathing", "value_type": "bool"},
"RGBLIGHT_EFFECT_CHRISTMAS": {"info_key": "rgblight.animations.christmas", "value_type": "bool"},
"RGBLIGHT_EFFECT_KNIGHT": {"info_key": "rgblight.animations.knight", "value_type": "bool"},
"RGBLIGHT_EFFECT_RAINBOW_MOOD": {"info_key": "rgblight.animations.rainbow_mood", "value_type": "bool"},
"RGBLIGHT_EFFECT_RAINBOW_SWIRL": {"info_key": "rgblight.animations.rainbow_swirl", "value_type": "bool"},
"RGBLIGHT_EFFECT_RGB_TEST": {"info_key": "rgblight.animations.rgb_test", "value_type": "bool"},
"RGBLIGHT_EFFECT_SNAKE": {"info_key": "rgblight.animations.snake", "value_type": "bool"},
"RGBLIGHT_EFFECT_STATIC_GRADIENT": {"info_key": "rgblight.animations.static_gradient", "value_type": "bool"},
"RGBLIGHT_EFFECT_TWINKLE": {"info_key": "rgblight.animations.twinkle"},
"RGBLIGHT_LIMIT_VAL": {"info_key": "rgblight.max_brightness", "value_type": "int"},
"RGBLIGHT_HUE_STEP": {"info_key": "rgblight.hue_steps", "value_type": "int"},
"RGBLIGHT_SAT_STEP": {"info_key": "rgblight.saturation_steps", "value_type": "int"},
"RGBLIGHT_VAL_STEP": {"info_key": "rgblight.brightness_steps", "value_type": "int"},
"RGBLIGHT_SLEEP": {"info_key": "rgblight.sleep", "value_type": "bool"},
"RGBLIGHT_SPLIT": {"info_key": "rgblight.split", "value_type": "bool"},
"PRODUCT": {"info_key": "keyboard_folder", "to_json": false},
"PRODUCT_ID": {"info_key": "usb.pid", "value_type": "hex"},
"VENDOR_ID": {"info_key": "usb.vid", "value_type": "hex"},
"QMK_ESC_OUTPUT": {"info_key": "qmk_lufa_bootloader.esc_output"},
"QMK_ESC_INPUT": {"info_key": "qmk_lufa_bootloader.esc_input"},
"QMK_LED": {"info_key": "qmk_lufa_bootloader.led"},
"QMK_SPEAKER": {"info_key": "qmk_lufa_bootloader.speaker"}
}

15
data/mappings/info_rules.json Normal file
View File

@ -0,0 +1,15 @@
# This file maps keys between `rules.mk` and `info.json`. It is used by QMK
# to correctly and consistently map back and forth between the two systems.
{
# Format:
# <rules.mk key>: {"info_key": <info.json key>, ["value_type": <value_type>], ["to_json": <true/false>], ["to_c": <true/false>]}
# value_type: one of "array", "array.int", "int", "list", "hex", "mapping"
# to_json: Default `true`. Set to `false` to exclude this mapping from info.json
# to_c: Default `true`. Set to `false` to exclude this mapping from rules.mk
# warn_duplicate: Default `true`. Set to `false` to turn off warning when a value exists in both places
"BOARD": {"info_key": "board"},
"BOOTLOADER": {"info_key": "bootloader", "warn_duplicate": false},
"LAYOUTS": {"info_key": "community_layouts", "value_type": "list"},
"LED_MATRIX_DRIVER": {"info_key": "led_matrix.driver"},
"MCU": {"info_key": "processor", "warn_duplicate": false},
}

35
data/schemas/api_keyboard.jsonschema Normal file
View File

@ -0,0 +1,35 @@
{
"allOf": [
{ "$ref": "qmk.keyboard.v1" },
{
"$id": "qmk.api.keyboard.v1",
"keymaps": {
"type": "string"
},
"parse_errors": {
"type": "array",
"items": {
"type": "string"
}
},
"parse_warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"processor_type": {
"type": "string"
},
"protocol": {
"type": "string"
},
"keyboard_folder": {
"type": "string"
},
"platform": {
"type": "string"
}
}
]
}

1
data/schemas/false.jsonschema Normal file
View File

@ -0,0 +1 @@
false

326
data/schemas/keyboard.jsonschema Normal file
View File

@ -0,0 +1,326 @@
{
"$schema": "http://json-schema.org/schema#",
"$id": "qmk.keyboard.v1",
"title": "Keyboard Information",
"type": "object",
"properties": {
"keyboard_name": {
"type": "string",
"minLength": 2,
"maxLength": 250
},
"maintainer": {
"type": "string",
"minLength": 2,
"maxLength": 250
},
"manufacturer": {
"type": "string",
"minLength": 2,
"maxLength": 250
},
"url": {
"type": "string",
"format": "uri"
},
"processor": {
"type": "string",
"enum": ["cortex-m0", "cortex-m0plus", "cortex-m3", "cortex-m4", "MKL26Z64", "MK20DX128", "MK20DX256", "STM32F042", "STM32F072", "STM32F103", "STM32F303", "STM32F401", "STM32F411", "STM32G431", "STM32G474", "atmega16u2", "atmega32u2", "atmega16u4", "atmega32u4", "at90usb162", "at90usb646", "at90usb647", "at90usb1286", "at90usb1287", "atmega32a", "atmega328p", "atmega328", "attiny85", "unknown"]
},
"board": {
"type": "string",
"minLength": 2,
"pattern": "^[a-zA-Z_][0-9a-zA-Z_]*$"
},
"bootloader": {
"type": "string",
"enum": ["atmel-dfu", "bootloadHID", "caterina", "halfkay", "kiibohd", "lufa-dfu", "lufa-ms", "micronucleus", "qmk-dfu", "stm32-dfu", "stm32duino", "unknown", "USBasp"]
},
"diode_direction": {
"type": "string",
"enum": ["COL2ROW", "ROW2COL"]
},
"debounce": {
"type": "number",
"min": 0,
"multipleOf": 1
},
"height": {
"type": "number",
"min": 0.25
},
"width": {
"type": "number",
"min": 0.25
},
"community_layouts": {
"type": "array",
"items": {
"type": "string",
"minLength": 2,
"pattern": "^[0-9a-z_]*$"
}
},
"features": {
"type": "object",
"additionalProperties": {"type": "boolean"}
},
"indicators": {
"type": "object",
"properties": {
"caps_lock": {
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
"num_lock": {
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
"scroll_lock": {
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
}
}
},
"layout_aliases": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "string",
"enum": ["LAYOUT", "LAYOUT_planck_1x2uC"]
},
{
"type": "string",
"pattern": "^LAYOUT_[0-9a-z_]*$"
}
]
}
},
"layouts": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": false,
"properties": {
"filename": {
"type": "string"
},
"c_macro": {
"type": "boolean"
},
"key_count": {
"type": "number",
"min": 0,
"multipleOf": 1
},
"layout": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"label": {"type": "string"},
"matrix": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "number",
"min": 0,
"multipleOf": 1
}
},
"h": {
"type": "number",
"min": 0.25
},
"r": {
"type": "number",
"min": 0
},
"rx": {
"type": "number",
"min": 0
},
"ry": {
"type": "number",
"min": 0
},
"w": {
"type": "number",
"min": 0.25
},
"x": {
"type": "number",
"min": 0
},
"y": {
"type": "number",
"min": 0
}
}
}
}
}
}
},
"matrix_pins": {
"type": "object",
"additionalProperties": false,
"properties": {
"direct": {
"type": "array",
"items": {
"type": "array",
"items": {
"oneOf": [
{
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
{
"type": "number",
"multipleOf": 1
},
{
"type": "null"
}
]
}
}
},
"cols": {
"type": "array",
"items": {
"oneOf": [
{
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
{
"type": "number",
"multipleOf": 1
},
{
"type": "null"
}
]
}
},
"rows": {
"type": "array",
"items": {
"oneOf": [
{
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
{
"type": "number",
"multipleOf": 1
},
{
"type": "null"
}
]
}
}
}
},
"rgblight": {
"type": "object",
"additionalProperties": false,
"properties": {
"animations": {
"type": "object",
"additionalProperties": {
"type": "boolean"
}
},
"brightness_steps": {
"type": "number",
"min": 0,
"multipleOf": 1
},
"hue_steps": {
"type": "number",
"min": 0,
"multipleOf": 1
},
"led_count": {
"type": "number",
"min": 0,
"multipleOf": 1
},
"max_brightness": {
"type": "number",
"min": 0,
"max": 255,
"multipleOf": 1
},
"pin": {
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
"saturation_steps": {
"type": "number",
"min": 0,
"multipleOf": 1
},
"sleep": {"type": "boolean"},
"split": {"type": "boolean"},
"split_count": {
"type": "array",
"minLength": 2,
"maxLength": 2,
"items": {
"type": "number",
"min": 0,
"multipleOf": 1
}
}
}
},
"usb": {
"type": "object",
"additionalProperties": false,
"properties": {
"device_ver": {
"type": "string",
"pattern": "^[0-9A-F]x[0-9A-F][0-9A-F][0-9A-F][0-9A-F]"
},
"pid": {
"type": "string",
"pattern": "^[0-9A-F]x[0-9A-F][0-9A-F][0-9A-F][0-9A-F]"
},
"vid": {
"type": "string",
"pattern": "^[0-9A-F]x[0-9A-F][0-9A-F][0-9A-F][0-9A-F]"
}
}
},
"qmk_lufa_bootloader": {
"type": "object",
"additionalProperties": false,
"properties": {
"esc_output": {
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
"esc_input": {
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
"led": {
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
},
"speaker": {
"type": "string",
"pattern": "^[A-K]\\d{1,2}$"
}
}
}
}
}

1
data/schemas/true.jsonschema Normal file
View File

@ -0,0 +1 @@
true

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

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))

169
docs/ChangeLog/20210227.md Normal file
View File

@ -0,0 +1,169 @@
# QMK Breaking Changes - 2021 February 27 Changelog
## Changes Requiring User Action
The following keyboards have had their source moved within QMK:
Old Keyboard Name | New Keyboard Name
:---------------- | :----------------
bear_65 | jacky_studio/bear_65
s7_elephant/rev1 | jacky_studio/s7_elephant/rev1
s7_elephant/rev2 | jacky_studio/s7_elephant/rev2
aplx6 | aplyard/aplx6/rev1
southpaw75 | fr4/southpaw75
The [Aplyard Aplx6 rev2](https://github.com/qmk/qmk_firmware/tree/0.12.0/keyboards/aplyard/aplx6/rev1) and the [FR4Boards Unix60](https://github.com/qmk/qmk_firmware/tree/0.12.0/keyboards/fr4/unix60) have also been added as part of these changes.
Additionally, the `handwired/bluepill/bluepill70` keyboard has been removed.
## Core Changes
### ChibiOS Update and Config Migration
QMK's ChibiOS and ChibiOS-Contrib submodules have been updated to version 20.3.2.
Along with this, QMK now provides default configuration files for all commonly-supported ARM microcontrollers running on ChibiOS. As such, keyboards are now only required to define settings which differ from the defaults, thereby reducing the size of pull requests for keyboards running atop ChibiOS.
### QMK Infrastructure and Internals
Python is now required to build QMK. The minimum Python version has been increased to 3.7.
The power of `info.json` has been massively expanded. Most keyboard parameters can now be expressed in `info.json` instead of `config.h`/`rules.mk`. This should make maintaining keyboards easier, and will enable tooling that can allow non-technical users to add and maintain QMK keyboards without writing any code.
To ease migration a new command has been provided, `qmk generate-info-json -kb <keyboard>`. You can use this command to generate a complete `info.json` file for a keyboard and then remove the duplicate information from `config.h` and `rules.mk`.
Detailed example showing how to generate a new info.json and identify duplicate keys:
```
user@hostname:~/qmk_firmware/keyboards/lets_split:0$ qmk generate-info-json > new-info.json
user@hostname:~/qmk_firmware/keyboards/lets_split:0$ mv new-info.json info.json
user@hostname:~/qmk_firmware/keyboards/lets_split:0$ qmk info
⚠ lets_split/rev2: DEBOUNCE in config.h is overwriting debounce in info.json
⚠ lets_split/rev2: DEVICE_VER in config.h is overwriting usb.device_ver in info.json
⚠ lets_split/rev2: DIODE_DIRECTION in config.h is overwriting diode_direction in info.json
⚠ lets_split/rev2: MANUFACTURER in config.h is overwriting manufacturer in info.json
⚠ lets_split/rev2: RGB_DI_PIN in config.h is overwriting rgblight.pin in info.json
⚠ lets_split/rev2: RGBLED_NUM in config.h is overwriting rgblight.led_count in info.json
⚠ lets_split/rev2: PRODUCT_ID in config.h is overwriting usb.pid in info.json
⚠ lets_split/rev2: VENDOR_ID in config.h is overwriting usb.vid in info.json
⚠ lets_split/rev2: Matrix pins are specified in both info.json and config.h, the config.h values win.
⚠ lets_split/rev2: LAYOUTS in rules.mk is overwriting community_layouts in info.json
⚠ lets_split/rev2: Feature bootmagic is specified in both info.json and rules.mk, the rules.mk value wins.
⚠ lets_split/rev2: Feature mousekey is specified in both info.json and rules.mk, the rules.mk value wins.
⚠ lets_split/rev2: Feature extrakey is specified in both info.json and rules.mk, the rules.mk value wins.
⚠ lets_split/rev2: Feature console is specified in both info.json and rules.mk, the rules.mk value wins.
⚠ lets_split/rev2: Feature command is specified in both info.json and rules.mk, the rules.mk value wins.
⚠ lets_split/rev2: Feature nkro is specified in both info.json and rules.mk, the rules.mk value wins.
⚠ lets_split/rev2: Feature backlight is specified in both info.json and rules.mk, the rules.mk value wins.
⚠ lets_split/rev2: Feature midi is specified in both info.json and rules.mk, the rules.mk value wins.
⚠ lets_split/rev2: Feature audio is specified in both info.json and rules.mk, the rules.mk value wins.
⚠ lets_split/rev2: Feature unicode is specified in both info.json and rules.mk, the rules.mk value wins.
⚠ lets_split/rev2: Feature bluetooth is specified in both info.json and rules.mk, the rules.mk value wins.
⚠ lets_split/rev2: Feature rgblight is specified in both info.json and rules.mk, the rules.mk value wins.
⚠ lets_split/rev2: Feature sleep_led is specified in both info.json and rules.mk, the rules.mk value wins.
Keyboard Name: Let's Split
Manufacturer: Wootpatoot
Website:
Maintainer: QMK Community
Keyboard Folder: lets_split/rev2
Layouts: LAYOUT, LAYOUT_ortho_4x12
Size: 13 x 4
Processor: atmega32u4
Bootloader: caterina
```
## Detailed Change List
### Changes Requiring User Action
* Refactor Jacky's boards (Bear65 and S7 Elephant) ([#10528](https://github.com/qmk/qmk_firmware/pull/10528), [#11981](https://github.com/qmk/qmk_firmware/pull/11981))
* Remove handwired/bluepill ([#11415](https://github.com/qmk/qmk_firmware/pull/11415))
* Aplyard Aplx6 Added rev2 & move rev1+rev2 to parent folder ([#10973](https://github.com/qmk/qmk_firmware/pull/10973))
* added `unix60`, moved together with `southpaw75` into `fr4` folder ([#11195](https://github.com/qmk/qmk_firmware/pull/11195))
### Fixes
* GCC 10 can now compile Drop Alt firmware ([#9485](https://github.com/qmk/qmk_firmware/pull/9485))
* Fix compiling on `develop` branch ([#11409](https://github.com/qmk/qmk_firmware/pull/11409))
* Fix broken keyboards and keymaps ([#11412](https://github.com/qmk/qmk_firmware/pull/11412), [#11427](https://github.com/qmk/qmk_firmware/pull/11427), [#11448](https://github.com/qmk/qmk_firmware/pull/11448), [#11447](https://github.com/qmk/qmk_firmware/pull/11447), [#11473](https://github.com/qmk/qmk_firmware/pull/11473), [#11584](https://github.com/qmk/qmk_firmware/pull/11584), [#11600](https://github.com/qmk/qmk_firmware/pull/11600))
* Fixed up build dependencies so that generated files are made available before compiling any object files ([#11435](https://github.com/qmk/qmk_firmware/pull/11435))
* Formatting fixes ([`378edd9`](https://github.com/qmk/qmk_firmware/commit/378edd9491f2ab0d3d8a970c9a8e64bc03ca15cf), [#11594](https://github.com/qmk/qmk_firmware/pull/11594), [`27749e1`](https://github.com/qmk/qmk_firmware/commit/27749e1c967c02c05e62a89a0ae2776dd7e5158c))
* Include `stdbool.h` in `uart.h` to fix compiler errors ([#11728](https://github.com/qmk/qmk_firmware/pull/11728))
* Decouple USB events from the USB interrupt handler in ChibiOS ([#10437](https://github.com/qmk/qmk_firmware/pull/10437))
* Fixes an issue while using Backlight and External EEPROM at the same time that would cause the MCU to lock up.
* Address wake from sleep instability ([#11450](https://github.com/qmk/qmk_firmware/pull/11450))
* Fix pressing media key on a momentarily activated layer may lead to missing key up events ([#11162](https://github.com/qmk/qmk_firmware/pull/11162))
* Fix an RGB initialisation bug on Massdrop keyboards ([#12022](https://github.com/qmk/qmk_firmware/pull/12022))
* Fix file encoding errors on Windows, and layouts not correctly merging into info.json ([#12039](https://github.com/qmk/qmk_firmware/pull/12039))
### Additions and Enhancements
* Allow configuration of serial USART timeout ([#11057](https://github.com/qmk/qmk_firmware/pull/11057))
* Added Sync Timer feature for Split Common keyboards ([#10997](https://github.com/qmk/qmk_firmware/pull/10997))
* Add modifier state to the Split Common transport ([#10400](https://github.com/qmk/qmk_firmware/pull/10400))
* Add Pix keyboard by sendz (`sendyyeah/pix`) ([#11154](https://github.com/qmk/qmk_firmware/pull/11154))
* Implement option for kinetic mouse movement algorithm for mouse keys ([#6739](https://github.com/qmk/qmk_firmware/pull/6739))
* Improved Language Specific Keycodes for US International and Extended Layouts ([#11307](https://github.com/qmk/qmk_firmware/pull/11307))
* Modified `QWIIC_ENABLE` in `rules.mk` to be yes/no choice, adding `QWIIC_DRIVERS` to allow for inclusion of specific drivers ([#11426](https://github.com/qmk/qmk_firmware/pull/11426))
* Allow AVR-based keyboards to override the `bootloader_jump` function ([#11418](https://github.com/qmk/qmk_firmware/pull/11418))
* Refine RGBLight Twinkle effect to be smoother (use breathing curve) ([#11350](https://github.com/qmk/qmk_firmware/pull/11350))
* Keep track of last matrix activity ([#10730](https://github.com/qmk/qmk_firmware/pull/10730), [`ab375d3`](https://github.com/qmk/qmk_firmware/commit/ab375d3d075c105f09a1ddd0e155f178225518bc), [#11552](https://github.com/qmk/qmk_firmware/pull/11552))
* fix `matrix_io_delay()` timing in `quantum/matrix.c` ([#9603](https://github.com/qmk/qmk_firmware/pull/9603))
* Keep track of encoder activity ([#11595](https://github.com/qmk/qmk_firmware/pull/11595))
* Backport ChibiOS Audio changes from ZSA ([#11687](https://github.com/qmk/qmk_firmware/pull/11687))
* Add support for 8 buttons to mouse report ([#10807](https://github.com/qmk/qmk_firmware/pull/10807))
* Allow `post_config.h` to be implemented in userspace ([#11519](https://github.com/qmk/qmk_firmware/pull/11519))
* Adds AT90USB162 support ([#11570](https://github.com/qmk/qmk_firmware/pull/11570))
* Stop sounds when suspended ([#11553](https://github.com/qmk/qmk_firmware/pull/11553))
* Revamp spidey3 userspace and keymaps ([#11768](https://github.com/qmk/qmk_firmware/pull/11768))
* Add support for analog USBPD on STM32G4xx ([#11824](https://github.com/qmk/qmk_firmware/pull/11824))
* Master matrix can now be transported to the slave side in Split Common keyboards ([#11046](https://github.com/qmk/qmk_firmware/pull/11046))
* RGBLight: Allow configurable default settings ([#11912](https://github.com/qmk/qmk_firmware/pull/11912))
* Add `tap_code_delay(code, delay)` ([#11913](https://github.com/qmk/qmk_firmware/pull/11913), [#11938](https://github.com/qmk/qmk_firmware/pull/11938))
### Clean-ups and Optimizations
* Fix duplicate `I2C_KEYMAP_START` define ([#11237](https://github.com/qmk/qmk_firmware/pull/11237))
* Rewrite APA102 support for RGBLight ([#10894](https://github.com/qmk/qmk_firmware/pull/10894))
* Update ADB Protocol implementation in TMK Core ([#11168](https://github.com/qmk/qmk_firmware/pull/11168))
* Remove unused `action_get_macro()` usages in user files ([#11165](https://github.com/qmk/qmk_firmware/pull/11165))
* Remove `QMK_KEYBOARD_CONFIG_H` ([#11576](https://github.com/qmk/qmk_firmware/pull/11576))
* Remove duplicated housekeeping in `arm_atsam` ([#11672](https://github.com/qmk/qmk_firmware/pull/11672))
* UART driver refactor ([#11637](https://github.com/qmk/qmk_firmware/pull/11637))
* Move `transport.c` to `QUANTUM_LIB_SRC` ([#11751](https://github.com/qmk/qmk_firmware/pull/11751))
* Remove `MIDI_ENABLE_STRICT` from user keymaps ([#11750](https://github.com/qmk/qmk_firmware/pull/11750))
* Remove legacy print backward compatiblitly ([#11805](https://github.com/qmk/qmk_firmware/pull/11805))
* Migrate mousekey to quantum ([#11804](https://github.com/qmk/qmk_firmware/pull/11804))
* remove deprecated `qmk json-keymap` ([#11823](https://github.com/qmk/qmk_firmware/pull/11823))
* Remove FAUXCLICKY feature (deprecated) ([#11829](https://github.com/qmk/qmk_firmware/pull/11829))
* Refactor platform logic within `print.h` ([#11863](https://github.com/qmk/qmk_firmware/pull/11863))
* Audio system overhaul ([#11820](https://github.com/qmk/qmk_firmware/pull/11820))
* Output selection: Remove "USB and BT" option for Bluetooth ([#11940](https://github.com/qmk/qmk_firmware/pull/11940))
* `tmk_core/common/action.c`: refactor for code size; merge multiple `case`s into one ([#11943](https://github.com/qmk/qmk_firmware/pull/11943))
* Remove rules and settings from user keymaps that are already defined at keyboard level ([#11966](https://github.com/qmk/qmk_firmware/pull/11966))
### QMK Infrastructure and Internals
* bump to python 3.7 ([#11408](https://github.com/qmk/qmk_firmware/pull/11408))
* `develop` branch is now formatted as part of CI tasks ([#11893](https://github.com/qmk/qmk_firmware/pull/11893), [#11905](https://github.com/qmk/qmk_firmware/pull/11905), [#11907](https://github.com/qmk/qmk_firmware/pull/11907), [#11928](https://github.com/qmk/qmk_firmware/pull/11928), [#11936](https://github.com/qmk/qmk_firmware/pull/11936))
* Configure keyboard matrix from info.json ([#10817](https://github.com/qmk/qmk_firmware/pull/10817))
* Validate our JSON data using json_schema ([#11101](https://github.com/qmk/qmk_firmware/pull/11101))
* Use the schema to eliminate custom code ([#11108](https://github.com/qmk/qmk_firmware/pull/11108))
* Add support for specifying BOARD in `info.json` ([#11492](https://github.com/qmk/qmk_firmware/pull/11492))
* Document how to add data driven configurations ([#11502](https://github.com/qmk/qmk_firmware/pull/11502))
* Process info.json rules ahead of userspace rules ([#11542](https://github.com/qmk/qmk_firmware/pull/11542))
* Remove duplicate manufacturer definitions ([#11544](https://github.com/qmk/qmk_firmware/pull/11544))
* Update list of MCUs in `keyboard.jsonschema` to mirror `qmk.constants.py` ([#11688](https://github.com/qmk/qmk_firmware/pull/11688))
* Create a system to map between `info.json` and `config.h`/`rules.mk` ([#11548](https://github.com/qmk/qmk_firmware/pull/11548))
* Make LAYOUT parsing more robust ([#12000](https://github.com/qmk/qmk_firmware/pull/12000))
### ChibiOS Update and Config Migration
* Add board specific to Proton-C, with usual defaults turned on to match Pro-Micro ([#10976](https://github.com/qmk/qmk_firmware/pull/10976))
* Disable almost all ChibiOS subsystems in default configs ([#11111](https://github.com/qmk/qmk_firmware/pull/11111))
* Config Migrations ([#10418](https://github.com/qmk/qmk_firmware/pull/10418), [#11123](https://github.com/qmk/qmk_firmware/pull/11123), [#11261](https://github.com/qmk/qmk_firmware/pull/11261), [#11413](https://github.com/qmk/qmk_firmware/pull/11413), [#11414](https://github.com/qmk/qmk_firmware/pull/11414), [#11495](https://github.com/qmk/qmk_firmware/pull/11495), [#11504](https://github.com/qmk/qmk_firmware/pull/11504), [#11529](https://github.com/qmk/qmk_firmware/pull/11529), [#11588](https://github.com/qmk/qmk_firmware/pull/11588), [#11598](https://github.com/qmk/qmk_firmware/pull/11598), [#11607](https://github.com/qmk/qmk_firmware/pull/11607), [#11617](https://github.com/qmk/qmk_firmware/pull/11617), [#11620](https://github.com/qmk/qmk_firmware/pull/11620), [#11630](https://github.com/qmk/qmk_firmware/pull/11630), [#11646](https://github.com/qmk/qmk_firmware/pull/11646), [#11689](https://github.com/qmk/qmk_firmware/pull/11689), [#11846](https://github.com/qmk/qmk_firmware/pull/11846), [#11927](https://github.com/qmk/qmk_firmware/pull/11927), [#12001](https://github.com/qmk/qmk_firmware/pull/12001))
* Disable subsystems repo-wide ([#11449](https://github.com/qmk/qmk_firmware/pull/11449))
* Leftover early initialisation conversions ([#11615](https://github.com/qmk/qmk_firmware/pull/11615))
* Fix up comments showing how to execute config migration ([#11621](https://github.com/qmk/qmk_firmware/pull/11621))
* Add STM32G431 and STM32G474 board definitions ([#11793](https://github.com/qmk/qmk_firmware/pull/11793))

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?

16
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)
@ -79,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)
@ -104,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)
@ -116,10 +119,8 @@
* Breaking Changes
* [Overview](breaking_changes.md)
* [My Pull Request Was Flagged](breaking_changes_instructions.md)
* History
* [2020 May 30](ChangeLog/20200530.md)
* [2020 Feb 29](ChangeLog/20200229.md)
* [2019 Aug 30](ChangeLog/20190830.md)
* [Most Recent ChangeLog](ChangeLog/20210227.md "QMK v0.12.0 - 2021 Feb 27")
* [Past Breaking Changes](breaking_changes_history.md)
* C Development
* [ARM Debugging Guide](arm_debugging.md)
@ -128,11 +129,13 @@
* [Compatible Microcontrollers](compatible_microcontrollers.md)
* [Drivers](hardware_drivers.md)
* [ADC Driver](adc_driver.md)
* [Audio Driver](audio_driver.md)
* [I2C Driver](i2c_driver.md)
* [SPI Driver](spi_driver.md)
* [WS2812 Driver](ws2812_driver.md)
* [EEPROM Driver](eeprom_driver.md)
* ['serial' Driver](serial_driver.md)
* [UART Driver](uart_driver.md)
* [GPIO Controls](internals_gpio_control.md)
* [Keyboard Guidelines](hardware_keyboard_guidelines.md)
@ -154,6 +157,7 @@
* [Contributing to QMK](contributing.md)
* [Translating the QMK Docs](translating.md)
* [Config Options](config_options.md)
* [Data Driven Configuration](data_driven_config.md)
* [Make Documentation](getting_started_make_guide.md)
* [Documentation Best Practices](documentation_best_practices.md)
* [Documentation Templates](documentation_templates.md)

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

221
docs/audio_driver.md Normal file
View File

@ -0,0 +1,221 @@
# Audio Driver :id=audio-driver
The [Audio feature](feature_audio.md) breaks the hardware specifics out into separate, exchangeable driver units, with a common interface to the audio-"core" - which itself handles playing songs and notes while tracking their progress in an internal state, initializing/starting/stopping the driver as needed.
Not all MCUs support every available driver, either the platform-support is not there (yet?) or the MCU simply does not have the required hardware peripheral.
## AVR :id=avr
Boards built around an Atmega32U4 can use two sets of PWM capable pins, each driving a separate speaker.
The possible configurations are:
| | Timer3 | Timer1 |
|--------------|-------------|--------------|
| one speaker | C4,C5 or C6 | |
| one speaker | | B4, B5 or B7 |
| two speakers | C4,C5 or C6 | B4, B5 or B7 |
Currently there is only one/default driver for AVR based boards, which is automatically configured to:
```make
AUDIO_DRIVER = pwm_hardware
```
## ARM :id=arm
For Arm based boards, QMK depends on ChibiOS - hence any MCU supported by the later is likely usable, as long as certain hardware peripherals are available.
Supported wiring configurations, with their ChibiOS/MCU peripheral requirement are listed below;
piezo speakers are marked with :one: for the first/primary and :two: for the secondary.
| driver | GPTD6<br>Tim6 | GPTD7<br>Tim7 | GPTD8<br>Tim8 | PWMD1<sup>1</sup><br>Tim1_Ch1 |
|--------------|------------------------------------------|------------------------|---------------|-------------------------------|
| dac_basic | A4+DACD1 = :one: | A5+DACD2 = :one: | state | |
| | A4+DACD1 = :one: + Gnd | A5+DACD2 = :two: + Gnd | state | |
| | A4+DACD1 = :two: + Gnd | A5+DACD2 = :one: + Gnd | state | |
| | A4+DACD1 = :one: + Gnd | | state | |
| | | A5+DACD2 = :one: + Gnd | state | |
| dac_additive | A4+DACD1 = :one: + Gnd | | | |
| | A5+DACD2 = :one: + Gnd | | | |
| | A4+DACD1 + A5+DACD2 = :one: <sup>2</sup> | | | |
| pwm_software | state-update | | | any = :one: |
| pwm hardware | state-update | | | A8 = :one: <sup>3</sup> |
<sup>1</sup>: the routing and alternate functions for PWM differ sometimes between STM32 MCUs, if in doubt consult the data-sheet
<sup>2</sup>: one piezo connected to A4 and A5, with AUDIO_PIN_ALT_AS_NEGATIVE set
<sup>3</sup>: TIM1_CH1 = A8 on STM32F103C8, other combinations are possible, see Data-sheet. configured with: AUDIO_PWM_DRIVER and AUDIO_PWM_CHANNEL
### DAC basic :id=dac-basic
The default driver for ARM boards, in absence of an overriding configuration.
This driver needs one Timer per enabled/used DAC channel, to trigger conversion; and a third timer to trigger state updates with the audio-core.
Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timers 6, 7 and 8:
``` c
//halconf.h:
#define HAL_USE_DAC TRUE
#define HAL_USE_GPT TRUE
#include_next <halconf.h>
```
``` c
// mcuconf.h:
#include_next <mcuconf.h>
#undef STM32_DAC_USE_DAC1_CH1
#define STM32_DAC_USE_DAC1_CH1 TRUE
#undef STM32_DAC_USE_DAC1_CH2
#define STM32_DAC_USE_DAC1_CH2 TRUE
#undef STM32_GPT_USE_TIM6
#define STM32_GPT_USE_TIM6 TRUE
#undef STM32_GPT_USE_TIM7
#define STM32_GPT_USE_TIM7 TRUE
#undef STM32_GPT_USE_TIM8
#define STM32_GPT_USE_TIM8 TRUE
```
?> Note: DAC1 (A4) uses TIM6, DAC2 (A5) uses TIM7, and the audio state timer uses TIM8 (configurable).
You can also change the timer used for the overall audio state by defining the driver. For instance:
```c
#define AUDIO_STATE_TIMER GPTD9
```
### DAC additive :id=dac-additive
only needs one timer (GPTD6, Tim6) to trigger the DAC unit to do a conversion; the audio state updates are in turn triggered during the DAC callback.
Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timer 6:
``` c
//halconf.h:
#define HAL_USE_DAC TRUE
#define HAL_USE_GPT TRUE
#include_next <halconf.h>
```
``` c
// mcuconf.h:
#include_next <mcuconf.h>
#undef STM32_DAC_USE_DAC1_CH1
#define STM32_DAC_USE_DAC1_CH1 TRUE
#undef STM32_DAC_USE_DAC1_CH2
#define STM32_DAC_USE_DAC1_CH2 TRUE
#undef STM32_GPT_USE_TIM6
#define STM32_GPT_USE_TIM6 TRUE
```
### DAC Config
| Define | Defaults | Description --------------------------------------------------------------------------------------------- |
| `AUDIO_DAC_SAMPLE_MAX` | `4095U` | Highest value allowed. Lower value means lower volume. And 4095U is the upper limit, since this is limited to a 12 bit value. Only effects non-pregenerated samples. |
| `AUDIO_DAC_OFF_VALUE` | `AUDIO_DAC_SAMPLE_MAX / 2` | The value of the DAC when notplaying anything. Some setups may require a high (`AUDIO_DAC_SAMPLE_MAX`) or low (`0`) value here. |
| `AUDIO_MAX_SIMULTANEOUS_TONES` | __see next table__ | The number of tones that can be played simultaneously. A value that is too high may freeze the controller or glitch out when too many tones are being played. |
| `AUDIO_DAC_SAMPLE_RATE` | __see next table__ | Effective bit rate of the DAC (in hertz), higher limits simultaneous tones, and lower sacrifices quality. |
There are a number of predefined quality settings that you can use, with "sane minimum" being the default. You can use custom values by simply defining the sample rate and number of simultaneous tones, instead of using one of the listed presets.
| Define | Sample Rate | Simultaneous tones |
| `AUDIO_DAC_QUALITY_VERY_LOW` | `11025U` | `8` |
| `AUDIO_DAC_QUALITY_LOW` | `22040U` | `4` |
| `AUDIO_DAC_QUALITY_HIGH` | `44100U` | `2` |
| `AUDIO_DAC_QUALITY_VERY_HIGH` | `88200U` | `1` |
| `AUDIO_DAC_QUALITY_SANE_MINIMUM` | `16384U` | `8` |
```c
/* zero crossing (or approach, whereas zero == DAC_OFF_VALUE, which can be configured to anything from 0 to DAC_SAMPLE_MAX)
* ============================*=*========================== AUDIO_DAC_SAMPLE_MAX
* * *
* * *
* ---------------------------------------------------------
* * * } AUDIO_DAC_SAMPLE_MAX/100
* --------------------------------------------------------- AUDIO_DAC_OFF_VALUE
* * * } AUDIO_DAC_SAMPLE_MAX/100
* ---------------------------------------------------------
* *
* * *
* * *
* =====*=*================================================= 0x0
*/
```
### PWM hardware :id=pwm-hardware
This driver uses the ChibiOS-PWM system to produce a square-wave on specific output pins that are connected to the PWM hardware.
The hardware directly toggles the pin via its alternate function. See your MCU's data-sheet for which pin can be driven by what timer - looking for TIMx_CHy and the corresponding alternate function.
A configuration example for the STM32F103C8 would be:
``` c
//halconf.h:
#define HAL_USE_PWM TRUE
#define HAL_USE_PAL TRUE
#define HAL_USE_GPT TRUE
#include_next <halconf.h>
```
``` c
// mcuconf.h:
#include_next <mcuconf.h>
#undef STM32_PWM_USE_TIM1
#define STM32_PWM_USE_TIM1 TRUE
#undef STM32_GPT_USE_TIM4
#define STM32_GPT_USE_TIM4 TRUE
```
If we now target pin A8, looking through the data-sheet of the STM32F103C8, for the timers and alternate functions
- TIM1_CH1 = PA8 <- alternate0
- TIM1_CH2 = PA9
- TIM1_CH3 = PA10
- TIM1_CH4 = PA11
with all this information, the configuration would contain these lines:
``` c
//config.h:
#define AUDIO_PIN A8
#define AUDIO_PWM_DRIVER PWMD1
#define AUDIO_PWM_CHANNEL 1
#define AUDIO_STATE_TIMER GPTD4
```
ChibiOS uses GPIOv1 for the F103, which only knows of one alternate function.
On 'larger' STM32s, GPIOv2 or GPIOv3 are used; with them it is also necessary to configure `AUDIO_PWM_PAL_MODE` to the correct alternate function for the selected pin, timer and timer-channel.
### PWM software :id=pwm-software
This driver uses the PWM callbacks from PWMD1 with TIM1_CH1 to toggle the selected AUDIO_PIN in software.
During the same callback, with AUDIO_PIN_ALT_AS_NEGATIVE set, the AUDIO_PIN_ALT is toggled inversely to AUDIO_PIN. This is useful for setups that drive a piezo from two pins (instead of one and Gnd).
You can also change the timer used for software PWM by defining the driver. For instance:
```c
#define AUDIO_STATE_TIMER GPTD8
```
### Testing Notes :id=testing-notes
While not an exhaustive list, the following table provides the scenarios that have been partially validated:
| | DAC basic | DAC additive | PWM hardware | PWM software |
|--------------------------|--------------------|--------------------|--------------------|--------------------|
| Atmega32U4 | :o: | :o: | :heavy_check_mark: | :o: |
| STM32F103C8 (bluepill) | :x: | :x: | :heavy_check_mark: | :heavy_check_mark: |
| STM32F303CCT6 (proton-c) | :heavy_check_mark: | :heavy_check_mark: | ? | :heavy_check_mark: |
| STM32F405VG | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| L0xx | :x: (no Tim8) | ? | ? | ? |
:heavy_check_mark: : works and was tested
:o: : does not apply
:x: : not supported by MCU
*Other supported ChibiOS boards and/or pins may function, it will be highly chip and configuration dependent.*

31
docs/breaking_changes.md
View File

@ -6,6 +6,8 @@ The breaking change period is when we will merge PR's that change QMK in dangero
## What has been included in past Breaking Changes?
* [2021 Feb 27](ChangeLog/20210227.md)
* [2020 Nov 28](ChangeLog/20201128.md)
* [2020 Aug 29](ChangeLog/20200829.md)
* [2020 May 30](ChangeLog/20200530.md)
* [2020 Feb 29](ChangeLog/20200229.md)
@ -13,16 +15,16 @@ The breaking change period is when we will merge PR's that change QMK in dangero
## When is the next Breaking Change?
The next Breaking Change is scheduled for November 28, 2020.
The next Breaking Change is scheduled for February 27, 2021.
### Important Dates
* [x] 2020 Aug 29 - `develop` is created. It will be rebased weekly.
* [ ] 2020 Oct 31 - `develop` closed to new PR's.
* [ ] 2020 Oct 31 - Call for testers.
* [ ] 2020 Nov 26 - `master` is locked, no PR's merged.
* [ ] 2020 Nov 28 - Merge `develop` to `master`.
* [ ] 2020 Nov 28 - `master` is unlocked. PR's can be merged again.
* [x] 2021 Feb 27 - `develop` is created. Each push to `master` is subsequently merged to `develop`
* [ ] 2021 May 01 - `develop` closed to new PR's.
* [ ] 2021 May 01 - Call for testers.
* [ ] 2021 May 27 - `master` is locked, no PR's merged.
* [ ] 2021 May 29 - Merge `develop` to `master`.
* [ ] 2021 May 29 - `master` is unlocked. PR's can be merged again.
## What changes will be included?
@ -39,21 +41,6 @@ Criteria for acceptance:
This section documents various processes we use when running the Breaking Changes process.
## Rebase `develop` from `master`
This is run every Friday while `develop` is open.
Process:
```
cd qmk_firmware
git checkout master
git pull --ff-only
git checkout develop
git rebase master
git push --force
```
## Creating the `develop` branch
This happens immediately after the previous `develop` branch is merged.

10
docs/breaking_changes_history.md Normal file
View File

@ -0,0 +1,10 @@
# Past Breaking Changes
This page links to all previous changelogs from the QMK Breaking Changes process.
* [2021 Feb 27](ChangeLog/20210227.md) - version 0.12.0
* [2020 Nov 28](ChangeLog/20201128.md) - version 0.11.0
* [2020 Aug 29](ChangeLog/20200829.md) - version 0.10.0
* [2020 May 30](ChangeLog/20200530.md) - version 0.9.0
* [2020 Feb 29](ChangeLog/20200229.md) - version 0.8.0
* [2019 Aug 30](ChangeLog/20190830.md) - version 0.7.0

59
docs/cli_commands.md
View File

@ -11,13 +11,13 @@ This command is directory aware. It will automatically fill in KEYBOARD and/or K
**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**:
@ -82,13 +82,13 @@ This command is directory aware. It will automatically fill in KEYBOARD and/or K
**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**
@ -175,9 +175,27 @@ Creates a keymap.json from a keymap.c.
**Usage**:
```
qmk c2json [--no-cpp] [-o OUTPUT] filename
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`
@ -212,6 +230,16 @@ This command is directory aware. It will automatically fill in KEYBOARD and/or K
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
@ -258,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.
@ -299,4 +347,3 @@ This command runs the python test suite. If you make changes to python code you
```
qmk pytest
```

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.

7
docs/compatible_microcontrollers.md
View File

@ -9,6 +9,7 @@ The following use [LUFA](https://www.fourwalledcubicle.com/LUFA.php) as the USB
* [ATmega16U2](https://www.microchip.com/wwwproducts/en/ATmega16U2) / [ATmega32U2](https://www.microchip.com/wwwproducts/en/ATmega32U2)
* [ATmega16U4](https://www.microchip.com/wwwproducts/en/ATmega16U4) / [ATmega32U4](https://www.microchip.com/wwwproducts/en/ATmega32U4)
* [AT90USB64](https://www.microchip.com/wwwproducts/en/AT90USB646) / [AT90USB128](https://www.microchip.com/wwwproducts/en/AT90USB1286)
* [AT90USB162](https://www.microchip.com/wwwproducts/en/AT90USB162)
Certain MCUs which do not have native USB will use [V-USB](https://www.obdev.at/products/vusb/index.html) instead:
@ -18,13 +19,17 @@ Certain MCUs which do not have native USB will use [V-USB](https://www.obdev.at/
## 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)
* [STM32F0x2](https://www.st.com/en/microcontrollers-microprocessors/stm32f0x2.html)
* [STM32F103](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html)
* [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html)
* [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html)
* [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html)
* [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html)
* [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html)
### NXP (Kinetis)

20
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
@ -65,16 +67,22 @@ This is a C header file that is one of the first things included, and will persi
* turns on the alternate audio voices (to cycle through)
* `#define C4_AUDIO`
* enables audio on pin C4
* Deprecated. Use `#define AUDIO_PIN C4`
* `#define C5_AUDIO`
* enables audio on pin C5
* Deprecated. Use `#define AUDIO_PIN C5`
* `#define C6_AUDIO`
* enables audio on pin C6
* Deprecated. Use `#define AUDIO_PIN C6`
* `#define B5_AUDIO`
* enables audio on pin B5 (duophony is enables if one of B[5-7]\_AUDIO is enabled along with one of C[4-6]\_AUDIO)
* enables audio on pin B5 (duophony is enabled if one of B pins is enabled along with one of C pins)
* Deprecated. Use `#define AUDIO_PIN B5`, or use `#define AUDIO_PIN_ALT B5` if a `C` pin is enabled with `AUDIO_PIN`
* `#define B6_AUDIO`
* enables audio on pin B6 (duophony is enables if one of B[5-7]\_AUDIO is enabled along with one of C[4-6]\_AUDIO)
* enables audio on pin B5 (duophony is enabled if one of B pins is enabled along with one of C pins)
* Deprecated. Use `#define AUDIO_PIN B6`, or use `#define AUDIO_PIN_ALT B6` if a `C` pin is enabled with `AUDIO_PIN`
* `#define B7_AUDIO`
* enables audio on pin B7 (duophony is enables if one of B[5-7]\_AUDIO is enabled along with one of C[4-6]\_AUDIO)
* enables audio on pin B5 (duophony is enabled if one of B pins is enabled along with one of C pins)
* Deprecated. Use `#define AUDIO_PIN B7`, or use `#define AUDIO_PIN_ALT B7` if a `C` pin is enabled with `AUDIO_PIN`
* `#define BACKLIGHT_PIN B7`
* pin of the backlight
* `#define BACKLIGHT_LEVELS 3`
@ -95,6 +103,8 @@ This is a C header file that is one of the first things included, and will persi
* sets the maximum power (in mA) over USB for the device (default: 500)
* `#define USB_POLLING_INTERVAL_MS 10`
* sets the USB polling rate in milliseconds for the keyboard, mouse, and shared (NKRO/media keys) interfaces
* `#define USB_SUSPEND_WAKEUP_DELAY 200`
* set the number of milliseconde to pause after sending a wakeup packet
* `#define F_SCL 100000L`
* sets the I2C clock rate speed for keyboards using I2C. The default is `400000L`, except for keyboards using `split_common`, where the default is `100000L`.
@ -135,6 +145,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`

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/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. -->

110
docs/custom_quantum_functions.md
View File

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

91
docs/data_driven_config.md Normal file
View File

@ -0,0 +1,91 @@
# Data Driven Configuration
This page describes how QMK's data driven JSON configuration system works. It is aimed at developers who want to work on QMK itself.
## History
Historically QMK has been configured through a combination of two mechanisms- `rules.mk` and `config.h`. While this worked well when QMK was only a handful of keyboards we've grown to encompass nearly 1500 supported keyboards. That extrapolates out to 6000 configuration files under `keyboards/` alone! The freeform nature of these files and the unique patterns people have used to avoid duplication have made ongoing maintenance a challenge, and a large number of our keyboards follow patterns that are outdated and sometimes harder to understand.
We have also been working on bringing the power of QMK to people who aren't comformable with a CLI, and other projects such as VIA are working to make using QMK as easy as installing a program. These tools need information about how a keyboard is laid out or what pins and features are available so that users can take full advantage of QMK. We introduced `info.json` as a first step towards this. The QMK API is an effort to combine these 3 sources of information- `config.h`, `rules.mk`, and `info.json`- into a single source of truth that end-user tools can use.
Now we have support for generating `rules.mk` and `config.h` values from `info.json`, allowing us to have a single source of truth. This will allow us to use automated tooling to maintain keyboards saving a lot of time and maintenance work.
## Overview
On the C side of things nothing changes. When you need to create a new rule or define you follow the same process:
1. Add it to `docs/config_options.md`
1. Set a default in the appropriate core file
1. Add your ifdef statements as needed
You will then need to add support for your new configuration to `info.json`. The basic process is:
1. Add it to the schema in `data/schemas/keyboards.jsonschema`
1. Add a mapping in `data/maps`
1. (optional and discoraged) Add code to extract/generate it to:
* `lib/python/qmk/info.py`
* `lib/python/qmk/cli/generate/config_h.py`
* `lib/python/qmk/cli/generate/rules_mk.py`
## Adding an option to info.json
This section describes adding support for a `config.h`/`rules.mk` value to info.json.
### Add it to the schema
QMK maintains [jsonschema](https://json-schema.org/) files in `data/schemas`. The values that go into keyboard-specific `info.json` files are kept in `keyboard.jsonschema`. Any value you want to make available to end users to edit must go in here.
In some cases you can simply add a new top-level key. Some examples to follow are `keyboard_name`, `maintainer`, `processor`, and `url`. This is appropriate when your option is self-contained and not directly related to other options.
In other cases you should group like options together in an `object`. This is particularly true when adding support for a feature. Some examples to follow for this are `indicators`, `matrix_pins`, and `rgblight`. If you are not sure how to integrate your new option(s) [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and start a conversation there.
### Add a mapping
In most cases you can add a simple mapping. These are maintained as JSON files in `data/mappings/info_config.json` and `data/mappings/info_rules.json`, and control mapping for `config.h` and `rules.mk`, respectively. Each mapping is keyed by the `config.h` or `rules.mk` variable, and the value is a hash with the following keys:
* `info_key`: (required) The location within `info.json` for this value. See below.
* `value_type`: (optional) Default `str`. The format for this variable's value. See below.
* `to_json`: (optional) Default `true`. Set to `false` to exclude this mapping from info.json
* `to_c`: (optional) Default `true`. Set to `false` to exclude this mapping from config.h
* `warn_duplicate`: (optional) Default `true`. Set to `false` to turn off warning when a value exists in both places
#### Info Key
We use JSON dot notation to address variables within info.json. For example, to access `info_json["rgblight"]["split_count"]` I would specify `rgblight.split_count`. This allows you to address deeply nested keys with a simple string.
Under the hood we use [Dotty Dict](https://dotty-dict.readthedocs.io/en/latest/), you can refer to that documentation for how these strings are converted to object access.
#### Value Types
By default we treat all values as simple strings. If your value is more complex you can use one of these types to intelligently parse the data:
* `array`: A comma separated array of strings
* `array.int`: A comma separated array of integers
* `int`: An integer
* `hex`: A number formatted as hex
* `list`: A space separate array of strings
* `mapping`: A hash of key/value pairs
### Add code to extract it
Most use cases can be solved by the mapping files described above. If yours can't you can instead write code to extract your config values.
Whenever QMK generates a complete `info.json` it extracts information from `config.h` and `rules.mk`. You will need to add code for your new config value to `lib/python/qmk/info.py`. Typically this means adding a new `_extract_<feature>()` function and then calling your function in either `_extract_config_h()` or `_extract_rules_mk()`.
If you are not sure how to edit this file or are not comfortable with Python [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and someone can help you with this part.
### Add code to generate it
The final piece of the puzzle is providing your new option to the build system. This is done by generating two files:
* `.build/obj_<keyboard>/src/info_config.h`
* `.build/obj_<keyboard>/src/rules.mk`
These two files are generated by the code here:
* `lib/python/qmk/cli/generate/config_h.py`
* `lib/python/qmk/cli/generate/rules_mk.py`
For `config.h` values you'll need to write a function for your rule(s) and call that function in `generate_config_h()`.
If you have a new top-level `info.json` key for `rules.mk` you can simply add your keys to `info_to_rules` at the top of `lib/python/qmk/cli/generate/rules_mk.py`. Otherwise you'll need to create a new if block for your feature in `generate_rules_mk()`.

2
docs/de/README.md
View File

@ -9,7 +9,7 @@
## 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

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`

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:

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. USBAspLoader devices must use the `libusbK` driver.
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 |

1
docs/eeprom_driver.md
View File

@ -40,6 +40,7 @@ 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>

4
docs/es/README.md
View File

@ -9,7 +9,7 @@
## ¿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
@ -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/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)

2
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`

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_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`.

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:

72
docs/faq_build.md
View File

@ -17,73 +17,9 @@ or just:
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
### 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, or place this file in `/etc/udev/rules.d/`:
**/etc/udev/rules.d/50-qmk.rules:**
```
# Atmel DFU
### ATmega16U2
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="2FEF", TAG+="uaccess", RUN{builtin}+="uaccess"
### ATmega32U2
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="2FF0", TAG+="uaccess", RUN{builtin}+="uaccess"
### ATmega16U4
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="2FF3", TAG+="uaccess", RUN{builtin}+="uaccess"
### ATmega32U4
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="2FF4", TAG+="uaccess", RUN{builtin}+="uaccess"
### AT90USB64
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="2FF9", TAG+="uaccess", RUN{builtin}+="uaccess"
### AT90USB128
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="2FFB", TAG+="uaccess", RUN{builtin}+="uaccess"
# Input Club
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1C11", ATTRS{idProduct}=="B007", TAG+="uaccess", RUN{builtin}+="uaccess"
# STM32duino
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1EAF", ATTRS{idProduct}=="0003", TAG+="uaccess", RUN{builtin}+="uaccess"
# STM32 DFU
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="DF11", TAG+="uaccess", RUN{builtin}+="uaccess"
# BootloadHID
SUBSYSTEMS=="usb", ATTRS{idVendor}=="16C0", ATTRS{idProduct}=="05DF", TAG+="uaccess", RUN{builtin}+="uaccess"
# USBAspLoader
SUBSYSTEMS=="usb", ATTRS{idVendor}=="16C0", ATTRS{idProduct}=="05DC", TAG+="uaccess", RUN{builtin}+="uaccess"
# ModemManager should ignore the following devices
# Atmel SAM-BA (Massdrop)
SUBSYSTEMS=="usb", ATTRS{idVendor}=="03EB", ATTRS{idProduct}=="6124", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
# Caterina (Pro Micro)
## Spark Fun Electronics
### Pro Micro 3V3/8MHz
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1B4F", ATTRS{idProduct}=="9203", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
### Pro Micro 5V/16MHz
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1B4F", ATTRS{idProduct}=="9205", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
### LilyPad 3V3/8MHz (and some Pro Micro clones)
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1B4F", ATTRS{idProduct}=="9207", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
## Pololu Electronics
### A-Star 32U4
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1FFB", ATTRS{idProduct}=="0101", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
## Arduino SA
### Leonardo
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2341", ATTRS{idProduct}=="0036", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
### Micro
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2341", ATTRS{idProduct}=="0037", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
## Adafruit Industries LLC
### Feather 32U4
SUBSYSTEMS=="usb", ATTRS{idVendor}=="239A", ATTRS{idProduct}=="000C", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
### ItsyBitsy 32U4 3V3/8MHz
SUBSYSTEMS=="usb", ATTRS{idVendor}=="239A", ATTRS{idProduct}=="000D", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
### ItsyBitsy 32U4 5V/16MHz
SUBSYSTEMS=="usb", ATTRS{idVendor}=="239A", ATTRS{idProduct}=="000E", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
## dog hunter AG
### Leonardo
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2A03", ATTRS{idProduct}=="0036", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
### Micro
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2A03", ATTRS{idProduct}=="0037", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
```
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:
@ -121,8 +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
- 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.

218
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,129 +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).
***
# 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

135
docs/feature_advanced_keycodes.md
View File

@ -23,6 +23,141 @@ These allow you to combine a modifier with a keycode. When pressed, the keydown
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.
# Checking Modifier State :id=checking-modifier-state
The current modifier state can mainly be accessed with two functions: `get_mods()` for normal modifiers and modtaps and `get_oneshot_mods()` for one-shot modifiers (unless they're held, in which case they act like normal modifier keys).
The presence of one or more specific modifiers in the current modifier state can be detected by ANDing the modifier state with a mod mask corresponding to the set of modifiers you want to match for. The reason why bitwise operators are used is that the modifier state is stored as a single byte in the format (GASC)<sub>R</sub>(GASC)<sub>L</sub>.
Thus, to give an example, `01000010` would be the internal representation of LShift+RAlt.
For more information on bitwise operators in C, click [here](https://en.wikipedia.org/wiki/Bitwise_operations_in_C) to open the Wikipedia page on the topic.
In practice, this means that you can check whether a given modifier is active with `get_mods() & MOD_BIT(KC_<modifier>)` (see the [list of modifier keycodes](keycodes_basic.md#modifiers)) or with `get_mods() & MOD_MASK_<modifier>` if the difference between left and right hand modifiers is not important and you want to match both. Same thing can be done for one-shot modifiers if you replace `get_mods()` with `get_oneshot_mods()`.
To check that *only* a specific set of mods is active at a time, AND the modifier state and your desired mod mask as explained above and compare the result to the mod mask itself: `get_mods() & <mod mask> == <mod mask>`.
For example, let's say you want to trigger a piece of custom code if one-shot left control and one-shot left shift are on but every other one-shot mods are off. To do so, you can compose the desired mod mask by combining the mod bits for left control and shift with `(MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT))` and then plug it in: `get_oneshot_mods & (MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT)) == (MOD_BIT(KC_LCTL) | MOD_BIT(KC_LSFT))`. Using `MOD_MASK_CS` instead for the mod bitmask would have forced you to press four modifier keys (both versions of control and shift) to fulfill the condition.
The full list of mod masks is as follows:
| Mod Mask Name | Matching Modifiers |
|--------------------|------------------------------------------------|
| `MOD_MASK_CTRL` | LCTRL , RCTRL |
| `MOD_MASK_SHIFT` | LSHIFT , RSHIFT |
| `MOD_MASK_ALT` | LALT , RALT |
| `MOD_MASK_GUI` | LGUI , RGUI |
| `MOD_MASK_CS` | CTRL , SHIFT |
| `MOD_MASK_CA` | (L/R)CTRL , (L/R)ALT |
| `MOD_MASK_CG` | (L/R)CTRL , (L/R)GUI |
| `MOD_MASK_SA` | (L/R)SHIFT , (L/R)ALT |
| `MOD_MASK_SG` | (L/R)SHIFT , (L/R)GUI |
| `MOD_MASK_AG` | (L/R)ALT , (L/R)GUI |
| `MOD_MASK_CSA` | (L/R)CTRL , (L/R)SHIFT , (L/R)ALT |
| `MOD_MASK_CSG` | (L/R)CTRL , (L/R)SHIFT , (L/R)GUI |
| `MOD_MASK_CAG` | (L/R)CTRL , (L/R)ALT , (L/R)GUI |
| `MOD_MASK_SAG` | (L/R)SHIFT , (L/R)ALT , (L/R)GUI |
| `MOD_MASK_CSAG` | (L/R)CTRL , (L/R)SHIFT , (L/R)ALT , (L/R)GUI |
Aside from accessing the currently active modifiers using `get_mods()`, there exists some other functions you can use to modify the modifier state, where the `mods` argument refers to the modifiers bitmask.
* `add_mods(mods)`: Enable `mods` without affecting any other modifiers
* `register_mods(mods)`: Like `add_mods` but send a keyboard report immediately.
* `del_mods(mods)`: Disable `mods` without affecting any other modifiers
* `unregister_mods(mods)`: Like `del_mods` but send a keyboard report immediately.
* `set_mods(mods)`: Overwrite current modifier state with `mods`
* `clear_mods()`: Reset the modifier state by disabling all modifiers
Similarly, in addition to `get_oneshot_mods()`, there also exists these functions for one-shot mods:
* `add_oneshot_mods(mods)`: Enable `mods` without affecting any other one-shot modifiers
* `del_oneshot_mods(mods)`: Disable `mods` without affecting any other one-shot modifiers
* `set_oneshot_mods(mods)`: Overwrite current one-shot modifier state with `mods`
* `clear_oneshot_mods()`: Reset the one-shot modifier state by disabling all one-shot modifiers
## Examples :id=examples
The following examples use [advanced macro functions](feature_macros.md#advanced-macro-functions) which you can read more about in the [documentation page on macros](feature_macros.md).
### Alt + Escape for Alt + Tab :id=alt-escape-for-alt-tab
Simple example where chording Left Alt with `KC_ESC` makes it behave like `KC_TAB` for alt-tabbing between applications. This example strictly checks if only Left Alt is active, meaning you can't do Alt+Shift+Esc to switch between applications in reverse order. Also keep in mind that this removes the ability to trigger the actual Alt+Escape keyboard shortcut, though it keeps the ability to do AltGr+Escape.
```c
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case KC_ESC:
// Detect the activation of only Left Alt
if ((get_mods() & MOD_BIT(KC_LALT)) == MOD_BIT(KC_LALT)) {
if (record->event.pressed) {
// No need to register KC_LALT because it's already active.
// The Alt modifier will apply on this KC_TAB.
register_code(KC_TAB);
} else {
unregister_code(KC_TAB);
}
// Do not let QMK process the keycode further
return false;
}
// Else, let QMK process the KC_ESC keycode as usual
return true;
}
return true;
};
```
### Shift + Backspace for Delete :id=shift-backspace-for-delete
Advanced example where the original behaviour of shift is cancelled when chorded with `KC_BSPC` and is instead fully replaced by `KC_DEL`. Two main variables are created to make this work well: `mod_state` and `delkey_registered`. The first one stores the modifier state and is used to restore it after registering `KC_DEL`. The second variable is a boolean variable (true or false) which keeps track of the status of `KC_DEL` to manage the release of the whole Backspace/Delete key correctly.
As opposed to the previous example, this doesn't use strict modifier checking. Pressing `KC_BSPC` while one or two shifts are active is enough to trigger this custom code, regardless of the state of other modifiers. That approach offers some perks: Ctrl+Shift+Backspace lets us delete the next word (Ctrl+Delete) and Ctrl+Alt+Shift+Backspace lets us execute the Ctrl+Alt+Del keyboard shortcut.
```c
// Initialize variable holding the binary
// representation of active modifiers.
uint8_t mod_state;
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
// Store the current modifier state in the variable for later reference
mod_state = get_mods();
switch (keycode) {
case KC_BSPC:
{
// Initialize a boolean variable that keeps track
// of the delete key status: registered or not?
static bool delkey_registered;
if (record->event.pressed) {
// Detect the activation of either shift keys
if (mod_state & MOD_MASK_SHIFT) {
// First temporarily canceling both shifts so that
// shift isn't applied to the KC_DEL keycode
del_mods(MOD_MASK_SHIFT);
register_code(KC_DEL);
// Update the boolean variable to reflect the status of KC_DEL
delkey_registered = true;
// Reapplying modifier state so that the held shift key(s)
// still work even after having tapped the Backspace/Delete key.
set_mods(mod_state);
return false;
}
} else { // on release of KC_BSPC
// In case KC_DEL is still being sent even after the release of KC_BSPC
if (delkey_registered) {
unregister_code(KC_DEL);
delkey_registered = false;
return false;
}
}
// Let QMK process the KC_BSPC keycode as usual outside of shift
return true;
}
}
return true;
};
```
# Legacy Content :id=legacy-content
This page used to encompass a large set of features. We have moved many sections that used to be part of this page to their own pages. Everything below this point is simply a redirect so that people following old links on the web find what they're looking for.

149
docs/feature_audio.md
View File

@ -1,21 +1,117 @@
# Audio
Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any AVR keyboard that allows access to certain PWM-capable pins, you can hook up a simple speaker and make it beep. You can use those beeps to indicate layer transitions, modifiers, special keys, or just to play some funky 8bit tunes.
Your keyboard can make sounds! If you've got a spare pin you can hook up a simple speaker and make it beep. You can use those beeps to indicate layer transitions, modifiers, special keys, or just to play some funky 8bit tunes.
Up to two simultaneous audio voices are supported, one driven by timer 1 and another driven by timer 3. The following pins can be defined as audio outputs in config.h:
To activate this feature, add `AUDIO_ENABLE = yes` to your `rules.mk`.
Timer 1:
`#define B5_AUDIO`
`#define B6_AUDIO`
`#define B7_AUDIO`
## AVR based boards
On Atmega32U4 based boards, up to two simultaneous tones can be rendered.
With one speaker connected to a PWM capable pin on PORTC driven by timer 3 and the other on one of the PWM pins on PORTB driven by timer 1.
Timer 3:
`#define C4_AUDIO`
`#define C5_AUDIO`
`#define C6_AUDIO`
The following pins can be configured as audio outputs in `config.h` - for one speaker set eiter one out of:
If you add `AUDIO_ENABLE = yes` to your `rules.mk`, there's a couple different sounds that will automatically be enabled without any other configuration:
* `#define AUDIO_PIN C4`
* `#define AUDIO_PIN C5`
* `#define AUDIO_PIN C6`
* `#define AUDIO_PIN B5`
* `#define AUDIO_PIN B6`
* `#define AUDIO_PIN B7`
and *optionally*, for a second speaker, one of:
* `#define AUDIO_PIN_ALT B5`
* `#define AUDIO_PIN_ALT B6`
* `#define AUDIO_PIN_ALT B7`
### Wiring
per speaker is - for example with a piezo buzzer - the black lead to Ground, and the red lead connected to the selected AUDIO_PIN for the primary; and similarly with AUDIO_PIN_ALT for the secondary.
## ARM based boards
for more technical details, see the notes on [Audio driver](audio_driver.md).
<!-- because I'm not sure where to fit this in: https://waveeditonline.com/ -->
### DAC (basic)
Most STM32 MCUs have DAC peripherals, with a notable exception of the STM32F1xx series. Generally, the DAC peripheral drives pins A4 or A5. To enable DAC-based audio output on STM32 devices, add `AUDIO_DRIVER = dac_basic` to `rules.mk` and set in `config.h` either:
`#define AUDIO_PIN A4` or `#define AUDIO_PIN A5`
the other DAC channel can optionally be used with a secondary speaker, just set:
`#define AUDIO_PIN_ALT A4` or `#define AUDIO_PIN_ALT A5`
Do note though that the dac_basic driver is only capable of reproducing one tone per speaker/channel at a time, for more tones simultaneously, try the dac_additive driver.
#### Wiring:
for two piezos, for example configured as `AUDIO_PIN A4` and `AUDIO_PIN_ALT A5` would be: red lead to A4 and black to Ground, and similarly with the second one: A5 = red, and Ground = black
another alternative is to drive *one* piezo with both DAC pins - for an extra "push".
wiring red to A4 and black to A5 (or the other way round) and add `#define AUDIO_PIN_ALT_AS_NEGATIVE` to `config.h`
##### Proton-C Example:
The Proton-C comes (optionally) with one 'builtin' piezo, which is wired to A4+A5.
For this board `config.h` would include these defines:
```c
#define AUDIO_PIN A5
#define AUDIO_PIN_ALT A4
#define AUDIO_PIN_ALT_AS_NEGATIVE
```
### DAC (additive)
Another option, besides dac_basic (which produces sound through a square-wave), is to use the DAC to do additive wave synthesis.
With a number of predefined wave-forms or by providing your own implementation to generate samples on the fly.
To use this feature set `AUDIO_DRIVER = dac_additive` in your `rules.mk`, and select in `config.h` EITHER `#define AUDIO_PIN A4` or `#define AUDIO_PIN A5`.
The used waveform *defaults* to sine, but others can be selected by adding one of the following defines to `config.h`:
* `#define AUDIO_DAC_SAMPLE_WAVEFORM_SINE`
* `#define AUDIO_DAC_SAMPLE_WAVEFORM_TRIANGLE`
* `#define AUDIO_DAC_SAMPLE_WAVEFORM_TRAPEZOID`
* `#define AUDIO_DAC_SAMPLE_WAVEFORM_SQUARE`
Should you rather choose to generate and use your own sample-table with the DAC unit, implement `uint16_t dac_value_generate(void)` with your keyboard - for an example implementation see keyboards/planck/keymaps/synth_sample or keyboards/planck/keymaps/synth_wavetable
### PWM (software)
if the DAC pins are unavailable (or the MCU has no usable DAC at all, like STM32F1xx); PWM can be an alternative.
Note that there is currently only one speaker/pin supported.
set in `rules.mk`:
`AUDIO_DRIVER = pwm_software` and in `config.h`:
`#define AUDIO_PIN C13` (can be any pin) to have the selected pin output a pwm signal, generated from a timer callback which toggles the pin in software.
#### Wiring
the usual piezo wiring: red goes to the selected AUDIO_PIN, black goes to ground.
OR if you can chose to drive one piezo with two pins, for example `#define AUDIO_PIN B1`, `#define AUDIO_PIN_ALT B2` in `config.h`, with `#define AUDIO_PIN_ALT_AS_NEGATIVE` - then the red lead could go to B1, the black to B2.
### PWM (hardware)
STM32F1xx have to fall back to using PWM, but can do so in hardware; but again on currently only one speaker/pin.
`AUDIO_DRIVER = pwm_hardware` in `rules.mk`, and in `config.h`:
`#define AUDIO_PIN A8`
`#define AUDIO_PWM_DRIVER PWMD1`
`#define AUDIO_PWM_CHANNEL 1`
(as well as `#define AUDIO_PWM_PAL_MODE 42` if you are on STM32F2 or larger)
which will use Timer 1 to directly drive pin PA8 through the PWM hardware (TIM1_CH1 = PA8).
Should you want to use the pwm-hardware on another pin and timer - be ready to dig into the STM32 data-sheet to pick the right TIMx_CHy and pin-alternate function.
## Tone Multiplexing
Since most drivers can only render one tone per speaker at a time (with the one exception: arm dac-additive) there also exists a "workaround-feature" that does time-slicing/multiplexing - which does what the name implies: cycle through a set of active tones (e.g. when playing chords in Music Mode) at a given rate, and put one tone at a time out through the one/few speakers that are available.
To enable this feature, and configure a starting-rate, add the following defines to `config.h`:
```c
#define AUDIO_ENABLE_TONE_MULTIPLEXING
#define AUDIO_TONE_MULTIPLEXING_RATE_DEFAULT 10
```
The audio core offers interface functions to get/set/change the tone multiplexing rate from within `keymap.c`.
## Songs
There's a couple of different sounds that will automatically be enabled without any other configuration:
```
STARTUP_SONG // plays when the keyboard starts up (audio.c)
GOODBYE_SONG // plays when you press the RESET key (quantum.c)
@ -67,15 +163,34 @@ The available keycodes for audio are:
* `AU_OFF` - Turn Audio Feature off
* `AU_TOG` - Toggle Audio Feature state
!> These keycodes turn all of the audio functionality on and off. Turning it off means that audio feedback, audio clicky, music mode, etc. are disabled, completely.
!> These keycodes turn all of the audio functionality on and off. Turning it off means that audio feedback, audio clicky, music mode, etc. are disabled, completely.
## Tempo
the 'speed' at which SONGs are played is dictated by the set Tempo, which is measured in beats-per-minute. Note lenghts are defined relative to that.
The initial/default tempo is set to 120 bpm, but can be configured by setting `TEMPO_DEFAULT` in `config.c`.
There is also a set of functions to modify the tempo from within the user/keymap code:
```c
void audio_set_tempo(uint8_t tempo);
void audio_increase_tempo(uint8_t tempo_change);
void audio_decrease_tempo(uint8_t tempo_change);
```
## ARM Audio Volume
For ARM devices, you can adjust the DAC sample values. If your board is too loud for you or your coworkers, you can set the max using `DAC_SAMPLE_MAX` in your `config.h`:
For ARM devices, you can adjust the DAC sample values. If your board is too loud for you or your coworkers, you can set the max using `AUDIO_DAC_SAMPLE_MAX` in your `config.h`:
```c
#define DAC_SAMPLE_MAX 65535U
#define AUDIO_DAC_SAMPLE_MAX 4095U
```
the DAC usually runs in 12Bit mode, hence a volume of 100% = 4095U
Note: this only adjusts the volume aka 'works' if you stick to WAVEFORM_SQUARE, since its samples are generated on the fly - any other waveform uses a hardcoded/precomputed sample-buffer.
## Voices
Aka "audio effects", different ones can be enabled by setting in `config.h` these defines:
`#define AUDIO_VOICES` to enable the feature, and `#define AUDIO_VOICE_DEFAULT something` to select a specific effect
for details see quantum/audio/voices.h and .c
## Music Mode
@ -215,12 +330,6 @@ This is still a WIP, but check out `quantum/process_keycode/process_midi.c` to s
AU_OFF,
AU_TOG,
#ifdef FAUXCLICKY_ENABLE
FC_ON,
FC_OFF,
FC_TOG,
#endif
// Music mode on/off/toggle
MU_ON,
MU_OFF,

42
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`.

41
docs/feature_backlight.md
View File

@ -62,14 +62,15 @@ Valid driver values are `pwm`, `software`, `custom` or `no`. See below for help
To configure 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|
| 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. |
Unless you are designing your own keyboard, you generally should not need to change the `BACKLIGHT_PIN` or `BACKLIGHT_ON_STATE`.
@ -92,18 +93,18 @@ BACKLIGHT_DRIVER = pwm
On AVR boards, QMK automatically decides which driver to use according to the following table:
|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 | |
|Backlight Pin|AT90USB64/128|AT90USB162|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 |Timer 1 | | |
|`C4` |Timer 3 | | | | | |
|`C5` |Timer 3 |Timer 1 | |Timer 1 | | |
|`C6` |Timer 3 |Timer 1 |Timer 3 |Timer 1 | | |
|`D4` | | | | |Timer 1 | |
|`D5` | | | | |Timer 1 | |
All other pins will use timer-assisted software PWM:

1
docs/feature_debounce_type.md
View File

@ -148,4 +148,3 @@ The following old names for existing algorithms will continue to be supported, h
* eager_pk - old name for sym_eager_pk
* sym_pk - old name for sym_defer_pk
* eager_pr - old name for sym_eager_pr

9
docs/feature_encoders.md
View File

@ -32,13 +32,20 @@ Additionally, the resolution, which defines how many pulses the encoder register
#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

23
docs/feature_haptic_feedback.md
View File

@ -39,17 +39,24 @@ Not all keycodes below will work depending on which haptic mechanism you have ch
First you will need a build a circuit to drive the solenoid through a mosfet as most MCU will not be able to provide the current needed to drive the coil in the solenoid.
[Wiring diagram provided by Adafruit](https://playground.arduino.cc/uploads/Learning/solenoid_driver.pdf)
[Wiring diagram provided by Adafruit](https://cdn-shop.adafruit.com/product-files/412/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_joystick.md
View File

@ -141,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.

2
docs/feature_leader_key.md
View File

@ -92,7 +92,7 @@ void leader_start(void) {
}
void leader_end(void) {
// sequence ended (no success/failuer detection)
// sequence ended (no success/failure detection)
}
```

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).

86
docs/feature_led_matrix.md
View File

@ -10,8 +10,11 @@ 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
```make
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`:
| Variable | Description | Default |
@ -19,7 +22,7 @@ You can use between 1 and 4 IS31FL3731 IC's. Do not specify `LED_DRIVER_ADDR_<N>
| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages | 100 |
| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 |
| `LED_DRIVER_COUNT` | (Required) How many LED driver IC's are present | |
| `LED_DRIVER_LED_COUNT` | (Required) How many LED lights are present across all drivers | |
| `DRIVER_LED_TOTAL` | (Required) How many LED lights are present across all drivers | |
| `LED_DRIVER_ADDR_1` | (Required) Address for the first LED driver | |
| `LED_DRIVER_ADDR_2` | (Optional) Address for the second LED driver | |
| `LED_DRIVER_ADDR_3` | (Optional) Address for the third LED driver | |
@ -27,35 +30,40 @@ You can use between 1 and 4 IS31FL3731 IC's. Do not specify `LED_DRIVER_ADDR_<N>
Here is an example using 2 drivers.
// This is a 7-bit address, that gets left-shifted and bit 0
// set to 0 for write, 1 for read (as per I2C protocol)
// The address will vary depending on your wiring:
// 0b1110100 AD <-> GND
// 0b1110111 AD <-> VCC
// 0b1110101 AD <-> SCL
// 0b1110110 AD <-> SDA
#define LED_DRIVER_ADDR_1 0b1110100
#define LED_DRIVER_ADDR_2 0b1110110
```c
// This is a 7-bit address, that gets left-shifted and bit 0
// set to 0 for write, 1 for read (as per I2C protocol)
// The address will vary depending on your wiring:
// 0b1110100 AD <-> GND
// 0b1110111 AD <-> VCC
// 0b1110101 AD <-> SCL
// 0b1110110 AD <-> SDA
#define LED_DRIVER_ADDR_1 0b1110100
#define LED_DRIVER_ADDR_2 0b1110110
#define LED_DRIVER_COUNT 2
#define LED_DRIVER_1_LED_COUNT 25
#define LED_DRIVER_2_LED_COUNT 24
#define LED_DRIVER_LED_COUNT LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL
#define LED_DRIVER_COUNT 2
#define LED_DRIVER_1_LED_COUNT 25
#define LED_DRIVER_2_LED_COUNT 24
#define DRIVER_LED_TOTAL LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL
```
Currently only 2 drivers are supported, but it would be trivial to support all 4 combinations.
Define these arrays listing all the LEDs in your `<keyboard>.c`:
const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
/* Refer to IS31 manual for these locations
* driver
* | LED address
* | | */
{0, C3_3},
....
}
```c
const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
/* Refer to IS31 manual for these locations
* driver
* | LED address
* | | */
{ 0, C1_1 },
{ 0, C1_15 },
// ...
}
```
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
@ -65,26 +73,28 @@ All LED matrix keycodes are currently shared with the [backlight system](feature
Currently no LED matrix effects have been created.
## Custom layer effects
## Custom Layer Effects
Custom layer effects can be done by defining this in your `<keyboard>.c`:
void led_matrix_indicators_kb(void) {
led_matrix_set_index_value(index, value);
}
```c
void led_matrix_indicators_kb(void) {
led_matrix_set_index_value(index, value);
}
```
A similar function works in the keymap as `led_matrix_indicators_user`.
## Suspended state
## Suspended State
To use the suspend feature, add this to your `<keyboard>.c`:
void suspend_power_down_kb(void)
{
led_matrix_set_suspend_state(true);
}
```c
void suspend_power_down_kb(void) {
led_matrix_set_suspend_state(true);
}
void suspend_wakeup_init_kb(void)
{
led_matrix_set_suspend_state(false);
}
void suspend_wakeup_init_kb(void) {
led_matrix_set_suspend_state(false);
}
```

129
docs/feature_macros.md
View File

@ -4,7 +4,7 @@ Macros allow you to send multiple keystrokes when pressing just one key. QMK has
!> **Security Note**: While it is possible to use macros to send passwords, credit card numbers, and other sensitive information it is a supremely bad idea to do so. Anyone who gets a hold of your keyboard will be able to access that information by opening a text editor.
## The New Way: `SEND_STRING()` & `process_record_user`
## `SEND_STRING()` & `process_record_user`
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`).
@ -182,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
@ -207,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 function](ref_functions.md) and [Checking modifier state](feature_advanced_keycodes#checking-modifier-state) for additional functionality. For example, `reset_keyboard()` allows you to reset the keyboard as part of a macro and `get_mods() & MOD_MASK_SHIFT` lets you check for the existence of active shift modifiers.
### `record->event.pressed`
@ -231,9 +233,15 @@ Parallel to `register_code` function, this sends the `<kc>` keyup event to the c
### `tap_code(<kc>);`
This will send `register_code(<kc>)` and then `unregister_code(<kc>)`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it).
Sends `register_code(<kc>)` and then `unregister_code(<kc>)`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it).
If you're having issues with taps (un)registering, you can add a delay between the register and unregister events by setting `#define TAP_CODE_DELAY 100` in your `config.h` file. The value is in milliseconds.
If `TAP_CODE_DELAY` is defined (default 0), this function waits that many milliseconds before calling `unregister_code(<kc>)`. This can be useful when you are having issues with taps (un)registering.
If the keycode is `KC_CAPS`, it waits `TAP_HOLD_CAPS_DELAY` milliseconds instead (default 80), as macOS prevents accidental Caps Lock activation by waiting for the key to be held for a certain amount of time.
### `tap_code_delay(<kc>, <delay>);`
Like `tap_code(<kc>)`, but with a `delay` parameter for specifying arbitrary intervals before sending the unregister event.
### `register_code16(<kc>);`, `unregister_code16(<kc>);` and `tap_code16(<kc>);`
@ -260,15 +268,15 @@ This will clear all keys besides the mods currently pressed.
This macro will register `KC_LALT` and tap `KC_TAB`, then wait for 1000ms. If the key is tapped again, it will send another `KC_TAB`; if there is no tap, `KC_LALT` will be unregistered, thus allowing you to cycle through windows.
```c
bool is_alt_tab_active = false; # ADD this near the begining of keymap.c
uint16_t alt_tab_timer = 0; # we will be using them soon.
bool is_alt_tab_active = false; // ADD this near the begining of keymap.c
uint16_t alt_tab_timer = 0; // we will be using them soon.
enum custom_keycodes { # Make sure have the awesome keycode ready
enum custom_keycodes { // Make sure have the awesome keycode ready
ALT_TAB = SAFE_RANGE,
};
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) { # This will do most of the grunt work with the keycodes.
switch (keycode) { // This will do most of the grunt work with the keycodes.
case ALT_TAB:
if (record->event.pressed) {
if (!is_alt_tab_active) {
@ -285,7 +293,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
return true;
}
void matrix_scan_user(void) { # The very important timer.
void matrix_scan_user(void) { // The very important timer.
if (is_alt_tab_active) {
if (timer_elapsed(alt_tab_timer) > 1000) {
unregister_code(KC_LALT);
@ -294,104 +302,3 @@ void matrix_scan_user(void) { # The very important timer.
}
}
```
---
## **(DEPRECATED)** The Old Way: `MACRO()` & `action_get_macro`
!> This is inherited from TMK, and hasn't been updated - it's recommended that you use `SEND_STRING` and `process_record_user` instead.
By default QMK assumes you don't have any macros. To define your macros you create an `action_get_macro()` function. For example:
```c
const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
if (record->event.pressed) {
switch(id) {
case 0:
return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END);
case 1:
return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END);
}
}
return MACRO_NONE;
};
```
This defines two macros which will be run when the key they are assigned to is pressed. If instead you'd like them to run when the key is released you can change the if statement:
if (!record->event.pressed) {
### Macro Commands
A macro can include the following commands:
* I() change interval of stroke in milliseconds.
* D() press key.
* U() release key.
* T() type key(press and release).
* W() wait (milliseconds).
* END end mark.
### Mapping a Macro to a Key
Use the `M()` function within your keymap to call a macro. For example, here is the keymap for a 2-key keyboard:
```c
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = LAYOUT(
M(0), M(1)
),
};
const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
if (record->event.pressed) {
switch(id) {
case 0:
return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END);
case 1:
return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END);
}
}
return MACRO_NONE;
};
```
When you press the key on the left it will type "Hi!" and when you press the key on the right it will type "Bye!".
### Naming Your Macros
If you have a bunch of macros you want to refer to from your keymap while keeping the keymap easily readable you can name them using `#define` at the top of your file.
```c
#define M_HI M(0)
#define M_BYE M(1)
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = LAYOUT(
M_HI, M_BYE
),
};
```
## Advanced Example:
### Single-Key Copy/Paste
This example defines a macro which sends `Ctrl-C` when pressed down, and `Ctrl-V` when released.
```c
const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) {
switch(id) {
case 0: {
if (record->event.pressed) {
return MACRO( D(LCTL), T(C), U(LCTL), END );
} else {
return MACRO( D(LCTL), T(V), U(LCTL), END );
}
break;
}
}
return MACRO_NONE;
};
```

35
docs/feature_mouse_keys.md
View File

@ -29,6 +29,9 @@ In your keymap you can use the following keycodes to map key presses to mouse ac
|`KC_MS_BTN3` |`KC_BTN3`|Press button 3 |
|`KC_MS_BTN4` |`KC_BTN4`|Press button 4 |
|`KC_MS_BTN5` |`KC_BTN5`|Press button 5 |
|`KC_MS_BTN6` |`KC_BTN6`|Press button 6 |
|`KC_MS_BTN7` |`KC_BTN7`|Press button 7 |
|`KC_MS_BTN8` |`KC_BTN8`|Press button 8 |
|`KC_MS_WH_UP` |`KC_WH_U`|Move wheel up |
|`KC_MS_WH_DOWN` |`KC_WH_D`|Move wheel down |
|`KC_MS_WH_LEFT` |`KC_WH_L`|Move wheel left |
@ -42,6 +45,7 @@ In your keymap you can use the following keycodes to map key presses to mouse ac
Mouse keys supports three different modes to move the cursor:
* **Accelerated (default):** Holding movement keys accelerates the cursor until it reaches its maximum speed.
* **Kinetic:** Holding movement keys accelerates the cursor with its speed following a quadratic curve 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.
@ -56,7 +60,8 @@ This is the default mode. You can adjust the cursor and scrolling acceleration u
|Define |Default|Description |
|----------------------------|-------|---------------------------------------------------------|
|`MOUSEKEY_DELAY` |300 |Delay between pressing a movement key and cursor movement|
|`MOUSEKEY_INTERVAL` |50 |Time between cursor movements |
|`MOUSEKEY_INTERVAL` |50 |Time between cursor movements in milliseconds |
|`MOUSEKEY_MOVE_DELTA` |5 |Step size |
|`MOUSEKEY_MAX_SPEED` |10 |Maximum cursor speed at which acceleration stops |
|`MOUSEKEY_TIME_TO_MAX` |20 |Time until maximum cursor speed is reached |
|`MOUSEKEY_WHEEL_DELAY` |300 |Delay between pressing a wheel key and wheel movement |
@ -73,6 +78,30 @@ Tips:
Cursor acceleration uses the same algorithm as the X Window System MouseKeysAccel feature. You can read more about it [on Wikipedia](https://en.wikipedia.org/wiki/Mouse_keys).
### Kinetic Mode
This is an extension of the accelerated mode. The kinetic mode uses a quadratic curve on the cursor speed which allows precise movements at the beginning and allows to cover large distances by increasing cursor speed quickly thereafter. You can adjust the cursor and scrolling acceleration using the following settings in your keymap’s `config.h` file:
|Define |Default |Description |
|--------------------------------------|---------|---------------------------------------------------------------|
|`MK_KINETIC_SPEED` |undefined|Enable kinetic mode |
|`MOUSEKEY_DELAY` |8 |Delay between pressing a movement key and cursor movement |
|`MOUSEKEY_INTERVAL` |8 |Time between cursor movements in milliseconds |
|`MOUSEKEY_MOVE_DELTA` |25 |Step size for accelerating from initial to base speed |
|`MOUSEKEY_INITIAL_SPEED` |100 |Initial speed of the cursor in pixel per second |
|`MOUSEKEY_BASE_SPEED` |1000 |Maximum cursor speed at which acceleration stops |
|`MOUSEKEY_DECELERATED_SPEED` |400 |Decelerated cursor speed |
|`MOUSEKEY_ACCELERATED_SPEED` |3000 |Accelerated cursor speed |
|`MOUSEKEY_WHEEL_INITIAL_MOVEMENTS` |16 |Initial number of movements of the mouse wheel |
|`MOUSEKEY_WHEEL_BASE_MOVEMENTS` |32 |Maximum number of movements at which acceleration stops |
|`MOUSEKEY_WHEEL_ACCELERATED_MOVEMENTS`|48 |Accelerated wheel movements |
|`MOUSEKEY_WHEEL_DECELERATED_MOVEMENTS`|8 |Decelerated wheel movements |
Tips:
* The smoothness of the cursor movement depends on the `MOUSEKEY_INTERVAL` setting. The shorter the interval is set the smoother the movement will be. Setting the value too low makes the cursor unresponsive. Lower settings are possible if the micro processor is fast enough. For example: At an interval of `8` milliseconds, `125` movements per second will be initiated. With a base speed of `1000` each movement will move the cursor by `8` pixels.
* Mouse wheel movements are implemented differently from cursor movements. While it's okay for the cursor to move multiple pixels at once for the mouse wheel this would lead to jerky movements. Instead, the mouse wheel operates at step size `1`. Setting mouse wheel speed is done by adjusting the number of wheel movements per second.
### Constant mode
In this mode you can define multiple different speeds for both the cursor and the mouse wheel. There is no acceleration. `KC_ACL0`, `KC_ACL1` and `KC_ACL2` change the cursor and scroll speed to their respective setting.
@ -140,3 +169,7 @@ To use constant speed mode, you must at least define `MK_COMBINED` in your keyma
```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.

12
docs/feature_oled_driver.md
View File

@ -140,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. |
@ -149,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
@ -304,6 +306,12 @@ bool oled_off(void);
// 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);

6
docs/feature_pointing_device.md
View File

@ -19,7 +19,7 @@ Keep in mind that a report_mouse_t (here "mouseReport") has the following proper
* `mouseReport.y` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing movement (+ upward, - downward) on the y axis.
* `mouseReport.v` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing vertical scrolling (+ upward, - downward).
* `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.
* `mouseReport.buttons` - this is a uint8_t in which all 8 bits are used. These bits represent the mouse button state - bit 0 is mouse button 1, and bit 7 is mouse button 8.
Once you have made the necessary changes to the mouse report, you need to send it:
@ -27,6 +27,10 @@ Once you have made the necessary changes to the mouse report, you need to send i
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

2
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:

2
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.

62
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`:
@ -126,6 +129,28 @@ Configure the hardware via your `config.h`:
---
### APA102 :id=apa102
There is basic support for APA102 based addressable LED strands. To enable it, add this to your `rules.mk`:
```makefile
RGB_MATRIX_ENABLE = yes
RGB_MATRIX_DRIVER = APA102
```
Configure the hardware via your `config.h`:
```c
// The pin connected to the data pin of the LEDs
#define RGB_DI_PIN D7
// The pin connected to the clock pin of the LEDs
#define RGB_CI_PIN D6
// The number of LEDs connected
#define DRIVER_LED_TOTAL 70
```
---
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
@ -293,6 +318,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
@ -303,6 +341,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 !!! //
@ -482,6 +526,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.

84
docs/feature_rgblight.md
View File

@ -10,6 +10,7 @@ Currently QMK supports the following addressable LEDs (however, the white LED in
* WS2811, WS2812, WS2812B, WS2812C, etc.
* SK6812, SK6812MINI, SK6805
* APA102
These LEDs are called "addressable" because instead of using a wire per color, each LED contains a small microchip that understands a special protocol sent over a single wire. The chip passes on the remaining data to the next LED, allowing them to be chained together. In this way, you can easily control the color of the individual LEDs.
@ -21,11 +22,19 @@ On keyboards with onboard RGB LEDs, it is usually enabled by default. If it is n
RGBLIGHT_ENABLE = yes
```
At minimum you must define the data pin your LED strip is connected to, and the number of LEDs in the strip, in your `config.h`. If your keyboard has onboard RGB LEDs, and you are simply creating a keymap, you usually won't need to modify these.
For APA102 LEDs, add the following to your `rules.mk`:
```make
RGBLIGHT_ENABLE = yes
RGBLIGHT_DRIVER = APA102
```
At minimum you must define the data pin your LED strip is connected to, and the number of LEDs in the strip, in your `config.h`. For APA102 LEDs, you must also define the clock pin. If your keyboard has onboard RGB LEDs, and you are simply creating a keymap, you usually won't need to modify these.
|Define |Description |
|---------------|---------------------------------------------------------------------------------------------------------|
|`RGB_DI_PIN` |The pin connected to the data pin of the LEDs |
|`RGB_CI_PIN` |The pin connected to the clock pin of the LEDs (APA102 only) |
|`RGBLED_NUM` |The number of LEDs connected |
|`RGBLED_SPLIT` |(Optional) For split keyboards, the number of LEDs connected on each half directly wired to `RGB_DI_PIN` |
@ -41,6 +50,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 |
@ -71,15 +82,20 @@ Changing the **Value** sets the overall brightness.<br>
Your RGB lighting can be configured by placing these `#define`s in your `config.h`:
|Define |Default |Description |
|---------------------|-------------|-----------------------------------------------------------------------------|
|`RGBLIGHT_HUE_STEP` |`10` |The number of steps to cycle through the hue by |
|`RGBLIGHT_SAT_STEP` |`17` |The number of steps to increment the saturation by |
|`RGBLIGHT_VAL_STEP` |`17` |The number of steps to increment the brightness by |
|`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|
|Define |Default |Description |
|---------------------------|----------------------------|---------------------------------------------------------------------------------------------------------------------------|
|`RGBLIGHT_HUE_STEP` |`10` |The number of steps to cycle through the hue by |
|`RGBLIGHT_SAT_STEP` |`17` |The number of steps to increment the saturation by |
|`RGBLIGHT_VAL_STEP` |`17` |The number of steps to increment the brightness by |
|`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|
|`RGBLIGHT_DEFAULT_MODE` |`RGBLIGHT_MODE_STATIC_LIGHT`|The default mode to use upon clearing the EEPROM |
|`RGBLIGHT_DEFAULT_HUE` |`0` (red) |The default hue to use upon clearing the EEPROM |
|`RGBLIGHT_DEFAULT_SAT` |`UINT8_MAX` (255) |The default saturation to use upon clearing the EEPROM |
|`RGBLIGHT_DEFAULT_VAL` |`RGBLIGHT_LIMIT_VAL` |The default value (brightness) to use upon clearing the EEPROM |
|`RGBLIGHT_DEFAULT_SPD` |`0` |The default speed to use upon clearing the EEPROM |
## Effects and Animations
@ -137,7 +153,7 @@ The following options are used to tweak the various animations:
|`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_LIFE` |`200` |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
@ -185,6 +201,8 @@ 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.
@ -192,7 +210,7 @@ it easy to use your underglow LEDs as status indicators to show which keyboard l
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 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:
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!
@ -208,6 +226,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..
```
@ -218,7 +240,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) {
@ -234,17 +257,21 @@ 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;
}
```
### Lighting layer blink :id=lighting-layer-blink
@ -348,6 +375,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 |
@ -366,14 +394,14 @@ 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) |

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

40
docs/feature_split_keyboard.md
View File

@ -109,6 +109,10 @@ Normally, when a diode is connected to an intersection, it is judged to be left.
#define SPLIT_HAND_MATRIX_GRID_LOW_IS_RIGHT
```
Note that adding a diode at a previously unused intersection will effectively tell the firmware that there is a key held down at that point. You can instruct qmk to ignore that intersection by defining `MATRIX_MASKED` and then defining a `matrix_row_t matrix_mask[MATRIX_ROWS]` array in your keyboard config. Each bit of a single value (starting form the least-significant bit) is used to tell qmk whether or not to pay attention to key presses at that intersection.
While `MATRIX_MASKED` isn't necessary to use `SPLIT_HAND_MATRIX_GRID` successfully, without it you may experience issues trying to suspend your computer with your keyboard attached as the matrix will always report at least one key-press.
#### Handedness by EEPROM
This method sets the keyboard's handedness by setting a flag in the persistent storage (`EEPROM`). This is checked when the controller first starts up, and determines what half the keyboard is, and how to orient the keyboard layout.
@ -181,6 +185,22 @@ If you're having issues with serial communication, you can change this value, as
* **`4`**: about 26kbps
* **`5`**: about 20kbps
```c
#define SPLIT_MODS_ENABLE
```
This enables transmitting modifier state (normal, weak and oneshot) to the non
primary side of the split keyboard. This adds a few bytes of data to the split
communication protocol and may impact the matrix scan speed when enabled.
The purpose of this feature is to support cosmetic use of modifer state (e.g.
displaying status on an OLED screen).
```c
#define SPLIT_TRANSPORT_MIRROR
```
This mirrors the master side matrix to the slave side for features that react or require knowledge of master side key presses on the slave side. This adds a few bytes of data to the split communication protocol and may impact the matrix scan speed when enabled. The purpose of this feature is to support cosmetic use of key events (e.g. RGB reacting to Keypresses).
### Hardware Configuration Options
There are some settings that you may need to configure, based on how the hardware is set up.
@ -237,6 +257,26 @@ This sets the maximum timeout when detecting master/slave when using `SPLIT_USB_
```
This sets the poll frequency when detecting master/slave when using `SPLIT_USB_DETECT`
## Hardware Considerations and Mods
While most any Pro Micro can be used, micro controllers like the AVR Teensys and most (if not all) ARM boards require the Split USB Detect.
However, with the Teensy 2.0 and Teensy++ 2.0, there is a simple hardware mod that you can perform to add VBUS detection, so you don't need the Split USB detection option.
You'll only need a few things:
* A knife (x-acto knife, ideally)
* A solder station or hot air station
* An appropriate Schottky diode, such as the [PMEG2005EH](https://www.digikey.com/en/products/detail/nexperia-usa-inc/PMEG2005EH,115/1589924)
You'll need to cut the small trace between the 5V and center pads on the back of the Teensy.
Once you have done that, you will want to solder the diode from the 5V pad to the center pad.
You may need to use the 5V pad from the regulator block above as the pads were too small and placed too closely together to place the Schottky diode properly.
![Teensy++ 2.0](https://i.imgur.com/BPEC5n5.png)
## Additional Resources
Nicinabox has a [very nice and detailed guide](https://github.com/nicinabox/lets-split-guide) for the Let's Split keyboard, that covers most everything you need to know, including troubleshooting information.

4
docs/feature_stenography.md
View File

@ -2,7 +2,7 @@
[Stenography](https://en.wikipedia.org/wiki/Stenotype) is a method of writing most often used by court reports, closed-captioning, and real-time transcription for the deaf. In stenography words are chorded syllable by syllable with a mixture of spelling, phonetic, and shortcut (briefs) strokes. Professional stenographers can reach 200-300 WPM without any of the strain usually found in standard typing and with far fewer errors (>99.9% accuracy).
The [Open Steno Project](http://www.openstenoproject.org/) has built an open-source program called Plover that provides real-time translation of steno strokes into words and commands. It has an established dictionary and supports
The [Open Steno Project](https://www.openstenoproject.org/) has built an open-source program called Plover that provides real-time translation of steno strokes into words and commands. It has an established dictionary and supports
## Plover with QWERTY Keyboard :id=plover-with-qwerty-keyboard
@ -52,7 +52,6 @@ On the display tab click 'Open stroke display'. With Plover disabled you should
## Learning Stenography :id=learning-stenography
* [Learn Plover!](https://sites.google.com/site/learnplover/)
* [QWERTY Steno](http://qwertysteno.com/Home/)
* [Steno Jig](https://joshuagrams.github.io/steno-jig/)
* More resources at the Plover [Learning Stenography](https://github.com/openstenoproject/plover/wiki/Learning-Stenography) wiki
@ -129,4 +128,3 @@ As defined in `keymap_steno.h`.
|`STN_RES1`||(GeminiPR only)|
|`STN_RES2`||(GeminiPR only)|
|`STN_PWR`||(GeminiPR only)|

23
docs/feature_unicode.md
View File

@ -87,7 +87,7 @@ const qk_ucis_symbol_t ucis_symbol_table[] = UCIS_TABLE(
UCIS_SYM("poop", 0x1F4A9), // 💩
UCIS_SYM("rofl", 0x1F923), // 🤣
UCIS_SYM("cuba", 0x1F1E8, 0x1F1FA), // 🇨🇺
UCIS_SYM("look", 0x0CA0, 0x005F, 0x0CA0), // ಠ_ಠ
UCIS_SYM("look", 0x0CA0, 0x005F, 0x0CA0) // ಠ_ಠ
);
```
@ -126,6 +126,8 @@ The following input modes are available:
Enabled by default and works almost anywhere on IBus-enabled distros. Without IBus, this mode works under GTK apps, but rarely anywhere else.
By default, this mode uses Ctrl+Shift+U (`LCTL(LSFT(KC_U))`) to start Unicode input, but this can be changed by defining [`UNICODE_KEY_LNX`](#input-key-configuration) with a different keycode. This might be required for IBus versions ≥1.5.15, where Ctrl+Shift+U behavior is consolidated into Ctrl+Shift+E.
Users who wish support in non-GTK apps without IBus may need to resort to a more indirect method, such as creating a custom keyboard layout ([more on this method](#custom-linux-layout)).
* **`UC_WIN`**: _(not recommended)_ Windows built-in hex numpad Unicode input. Supports code points up to `0xFFFF`.
To enable, create a registry key under `HKEY_CURRENT_USER\Control Panel\Input Method` of type `REG_SZ` called `EnableHexNumpad` and set its value to `1`. This can be done from the Command Prompt by running `reg add "HKCU\Control Panel\Input Method" -v EnableHexNumpad -t REG_SZ -d 1` with administrator privileges. Reboot afterwards.
@ -270,3 +272,22 @@ AutoHotkey inserts the Text right of `Send, ` when this combination is pressed.
If you enable the US International layout on the system, it will use punctuation to accent the characters. For instance, typing "\`a" will result in à.
You can find details on how to enable this [here](https://support.microsoft.com/en-us/help/17424/windows-change-keyboard-layout).
## Software keyboard layout on Linux :id=custom-linux-layout
This method does not require Unicode support on the keyboard itself but instead uses a custom keyboard layout for Xorg. This is how special characters are inserted by regular keyboards. This does not require IBus and works in practically all software. Help on creating a custom layout can be found [here](https://www.linux.com/news/creating-custom-keyboard-layouts-x11-using-xkb/), [here](http://karols.github.io/blog/2013/11/18/creating-custom-keyboard-layouts-for-linux/) and [here](https://wiki.archlinux.org/index.php/X_keyboard_extension). An example of how you could edit the `us` layout to gain 🤣 on `RALT(KC_R)`:
Edit the keyboard layout file `/usr/share/X11/xkb/symbols/us`.
Inside `xkb_symbols "basic" {`, add `include "level3(ralt_switch)"`.
Find the line defining the R key and add an entry to the list, making it look like this:
```
key <AD04> { [ r, R, U1F923 ] };
```
Save the file and run the command `setxkbmap us` to reload the layout.
You can define one custom character for key defined in the layout, and another if you populate the fourth layer. Additional layers up to 8th are also possible.
This method is specific to the computer on which you set the custom layout. The custom keys will be available only when Xorg is running. To avoid accidents, you should always reload the layout using `setxkbmap`, otherwise an invalid layout could prevent you from logging into your system, locking you out.

2
docs/feature_userspace.md
View File

@ -184,7 +184,7 @@ If you wanted to consolidate macros and other functions into your userspace for
First, you'd want to go through all of your `keymap.c` files and replace `process_record_user` with `process_record_keymap` instead. This way, you can still use keyboard specific codes on those boards, and use your custom "global" keycodes as well. You'll also want to replace `SAFE_RANGE` with `NEW_SAFE_RANGE` so that you wont have any overlapping keycodes
Then add `#include <name.h>` to all of your keymap.c files. This allows you to use these new keycodes without having to redefine them in each keymap.
Then add `#include "<name>.h"` to all of your keymap.c files. This allows you to use these new keycodes without having to redefine them in each keymap.
Once you've done that, you'll want to set the keycode definitions that you need to the `<name>.h` file. For instance:
```c

239
docs/flashing.md
View File

@ -1,242 +1,251 @@
# Flashing Instructions and Bootloader Information
There are quite a few different types of bootloaders that keyboards use, and just about all of them use a different flashing method. Luckily, projects like the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) aim to be compatible with all the different types without having to think about it much, but this article will describe the different types of bootloaders, and available methods for flashing them.
There are quite a few different types of bootloaders that keyboards use, and almost all of them use their own flashing method and tools. Luckily, projects like the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) aim to support as many of them as possible, but this article will describe the different types of bootloaders, and available methods for flashing them.
If you have a bootloader selected with the `BOOTLOADER` variable in your `rules.mk`, QMK will automatically calculate if your .hex file is the right size to be flashed to the device, and output the total size in bytes (along with the max).
For AVR-based keyboards, QMK will automatically calculate if your `.hex` file is the right size to be flashed to the device based on the `BOOTLOADER` value set in `rules.mk`, and output the total size in bytes (along with the max).
## DFU
You will also be able to use the CLI to flash your keyboard, by running:
```
$ qmk flash -kb <keyboard> -km <keymap>
```
See the [`qmk flash`](cli_commands.md#qmk-flash) documentation for more information.
Atmel's DFU bootloader comes on all atmega32u4 chips by default, and is used by many keyboards that have their own ICs on their PCBs (Older OLKB boards, Clueboards). Some keyboards may also use LUFA's DFU bootloader (or QMK's fork) (Newer OLKB boards) that adds in additional features specific to that hardware.
## Atmel DFU
To ensure compatibility with the DFU bootloader, make sure this block is present your `rules.mk` (optionally with `lufa-dfu` or `qmk-dfu` instead):
Atmel's DFU bootloader comes on all USB AVRs by default (except for 16/32U4RC), and is used by many keyboards that have their own ICs on their PCBs (older OLKB boards, Clueboards). Some keyboards may also use LUFA's DFU bootloader, or QMK's fork of it (newer OLKB boards), that adds in additional features specific to that hardware.
To ensure compatibility with the DFU bootloader, make sure this block is present in your `rules.mk` (optionally with `lufa-dfu` or `qmk-dfu` instead):
```make
# Bootloader selection
# Teensy halfkay
# Pro Micro caterina
# Atmel DFU atmel-dfu
# LUFA DFU lufa-dfu
# QMK DFU qmk-dfu
# ATmega32A bootloadHID
# ATmega328P USBasp
BOOTLOADER = atmel-dfu
```
Compatible flashers:
* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
* [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` in QMK (recommended command line)
* [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` target in QMK (recommended command line)
Flashing sequence:
1. Press the `RESET` keycode, or tap the RESET button (or short RST to GND).
1. Enter the bootloader using any of the following methods:
* Press the `RESET` keycode
* Press the `RESET` button on the PCB if available
* Short RST to GND quickly
2. Wait for the OS to detect the device
3. Erase the memory (may be done automatically)
3. Erase the flash memory (will be done automatically if using the Toolbox or CLI/`make` command)
4. Flash a .hex file
5. Reset the device into application mode (may be done automatically)
or:
make <keyboard>:<keymap>:dfu
5. Reset the device into application mode (will be done automatically as above)
### QMK DFU
QMK has a fork of the LUFA DFU bootloader that allows for a simple matrix scan for exiting the bootloader and returning to the application, as well as flashing an LED/making a ticking noise with a speaker when things are happening. To enable these features, use this block in your `config.h` (The key that exits the bootloader needs to be hooked-up to the INPUT and OUTPUT defined here):
QMK maintains [a fork of the LUFA DFU bootloader](https://github.com/qmk/lufa/tree/master/Bootloaders/DFU) that additionally performs a simple matrix scan for exiting the bootloader and returning to the application, as well as flashing an LED/making a ticking noise with a speaker when things are happening. To enable these features, add the following defines to your `config.h`:
#define QMK_ESC_OUTPUT F1 // usually COL
#define QMK_ESC_INPUT D5 // usually ROW
#define QMK_LED E6
#define QMK_SPEAKER C6
```c
#define QMK_ESC_OUTPUT F1 // COL pin if COL2ROW
#define QMK_ESC_INPUT D5 // ROW pin if COL2ROW
// Optional:
//#define QMK_LED E6
//#define QMK_SPEAKER C6
```
Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md#bootmagic-lite), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader.
The Manufacturer and Product names are automatically pulled from your `config.h`, and "Bootloader" is added to the product.
The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string.
To generate this bootloader, use the `bootloader` target, eg `make planck/rev4:default:bootloader`.
To generate this bootloader, use the `bootloader` target, eg. `make planck/rev4:default:bootloader`. To generate a production-ready .hex file (combining QMK and the bootloader), use the `production` target, eg. `make planck/rev4:default:production`.
To generate a production-ready .hex file (containing the application and the bootloader), use the `production` target, eg `make planck/rev4:default:production`.
### `make` Targets
### DFU commands
There are a number of DFU commands that you can use to flash firmware to a DFU device:
* `:dfu` - This is the normal option and waits until a DFU device is available, and then flashes the firmware. This will check every 5 seconds, to see if a DFU device has appeared.
* `:dfu-ee` - This flashes an `eep` file instead of the normal hex. This is uncommon.
* `:dfu-split-left` - This flashes the normal firmware, just like the default option (`:dfu`). However, this also flashes the "Left Side" EEPROM file for split keyboards. _This is ideal for Elite C based split keyboards._
* `:dfu-split-right` - This flashes the normal firmware, just like the default option (`:dfu`). However, this also flashes the "Right Side" EEPROM file for split keyboards. _This is ideal for Elite C based split keyboards._
* `:dfu`: Checks every 5 seconds until a DFU device is available, and then flashes the firmware.
* `:dfu-split-left` and `:dfu-split-right`: Flashes the firmware as with `:dfu`, but also sets the handedness setting in EEPROM. This is ideal for Elite-C-based split keyboards.
## Caterina
Arduino boards and their clones use the [Caterina bootloader](https://github.com/arduino/ArduinoCore-avr/tree/master/bootloaders/caterina) (any keyboard built with a Pro Micro, or clone), and uses the avr109 protocol to communicate through virtual serial. Bootloaders like [A-Star](https://www.pololu.com/docs/0J61/9) are based on Caterina.
Arduino boards and their clones use the [Caterina bootloader](https://github.com/arduino/ArduinoCore-avr/tree/master/bootloaders/caterina) or a variant of it (any keyboard built with a Pro Micro or clone, and the Pololu A-Star), and uses the AVR109 protocol to communicate through virtual serial.
To ensure compatibility with the Caterina bootloader, make sure this block is present your `rules.mk`:
To ensure compatibility with the Caterina bootloader, make sure this block is present in your `rules.mk`:
```make
# Bootloader selection
# Teensy halfkay
# Pro Micro caterina
# Atmel DFU atmel-dfu
# LUFA DFU lufa-dfu
# QMK DFU qmk-dfu
# ATmega32A bootloadHID
# ATmega328P USBasp
BOOTLOADER = caterina
```
Compatible flashers:
* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
* [avrdude](http://www.nongnu.org/avrdude/) with avr109 / `:avrdude` (recommended command line)
* [avrdude](https://www.nongnu.org/avrdude/) with the `avr109` programmer / `:avrdude` target in QMK (recommended command line)
* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)
Flashing sequence:
1. Press the `RESET` keycode, or short RST to GND quickly (you only have 7 seconds to flash once it enters)
1. Enter the bootloader using any of the following methods (you only have 7 seconds to flash once it enters; some variants may require you to reset twice within 750 milliseconds):
* Press the `RESET` keycode
* Press the `RESET` button on the PCB if available
* Short RST to GND quickly
2. Wait for the OS to detect the device
3. Flash a .hex file
4. Wait for the device to reset automatically
or
### `make` Targets
make <keyboard>:<keymap>:avrdude
* `:avrdude`: Checks every 5 seconds until a Caterina device is available (by detecting a new COM port), and then flashes the firmware.
* `:avrdude-loop`: Flashes the firmware as with `:avrdude`, but after each device is flashed, will attempt to flash again. This is useful for bulk flashing. Hit Ctrl+C to escape the loop.
* `:avrdude-split-left` and `:avrdude-split-right`: Flashes the firmware as with `:avrdude`, but also sets the handedness setting in EEPROM. This is ideal for Pro Micro-based split keyboards.
## HalfKay
### Caterina commands
HalfKay is a super-slim bootloader developed by PJRC that presents itself as an HID device (which requires no additional driver), and comes preflashed on all Teensys, namely the 2.0. It is currently closed-source, and thus once overwritten (eg. via ISP flashing another bootloader), cannot be restored.
There are a number of DFU commands that you can use to flash firmware to a DFU device:
* `:avrdude` - This is the normal option which waits until a Caterina device is available (by detecting a new COM port), and then flashes the firmware.
* `:avrdude-loop` - This runs the same command as `:avrdude`, but after each device is flashed, it will attempt to flash again. This is useful for bulk flashing. _This requires you to manually escape the loop by hitting Ctrl+C._
* `:avrdude-split-left` - This flashes the normal firmware, just like the default option (`:avrdude`). However, this also flashes the "Left Side" EEPROM file for split keyboards. _This is ideal for Pro Micro based split keyboards._
* `:avrdude-split-right` - This flashes the normal firmware, just like the default option (`:avrdude`). However, this also flashes the "Right Side" EEPROM file for split keyboards. _This is ideal for Pro Micro based split keyboards._
## Halfkay
Halfkay is a super-slim protocol developed by PJRC that uses HID, and comes on all Teensys (namely the 2.0).
To ensure compatibility with the Halfkay bootloader, make sure this block is present your `rules.mk`:
To ensure compatibility with the Halfkay bootloader, make sure this block is present in your `rules.mk`:
```make
# Bootloader selection
# Teensy halfkay
# Pro Micro caterina
# Atmel DFU atmel-dfu
# LUFA DFU lufa-dfu
# QMK DFU qmk-dfu
# ATmega32A bootloadHID
# ATmega328P USBasp
BOOTLOADER = halfkay
```
Compatible flashers:
* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
* [Teensy Loader Command Line](https://www.pjrc.com/teensy/loader_cli.html) / `:teensy` target in QMK (recommended command line)
* [Teensy Loader](https://www.pjrc.com/teensy/loader.html)
* [Teensy Loader Command Line](https://www.pjrc.com/teensy/loader_cli.html) (recommended command line)
Flashing sequence:
1. Press the `RESET` keycode, or short RST to GND quickly (you only have 7 seconds to flash once it enters)
1. Enter the bootloader using any of the following methods (you only have 7 seconds to flash once it enters):
* Press the `RESET` keycode
* Press the `RESET` button on the Teensy or PCB if available
* short RST to GND quickly
2. Wait for the OS to detect the device
3. Flash a .hex file
4. Reset the device into application mode (may be done automatically)
## USBasploader
USBasploader is a bootloader developed by matrixstorm. It is used in some non-USB AVR chips such as the ATmega328P, which run V-USB.
USBasploader is a bootloader originally by [Objective Development](https://www.obdev.at/products/vusb/usbasploader.html). It emulates a USBasp ISP programmer and is used in some non-USB AVR chips such as the ATmega328P, which run V-USB.
To ensure compatibility with the USBasploader bootloader, make sure this block is present in your `rules.mk`:
```make
# Bootloader selection
# Teensy halfkay
# Pro Micro caterina
# Atmel DFU atmel-dfu
# LUFA DFU lufa-dfu
# QMK DFU qmk-dfu
# ATmega32A bootloadHID
# ATmega328P USBasp
BOOTLOADER = USBasp
```
Compatible flashers:
* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
* [avrdude](http://www.nongnu.org/avrdude/) with the `usbasp` programmer
* [avrdude](https://www.nongnu.org/avrdude/) with the `usbasp` programmer / `:usbasp` target in QMK (recommended command line)
* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)
Flashing sequence:
1. Press the `RESET` keycode, or keep the boot pin shorted to GND while quickly shorting RST to GND
1. Enter the bootloader using any of the following methods:
* Press the `RESET` keycode
* Keep the `BOOT` button held while quickly tapping the `RESET` button on the PCB
2. Wait for the OS to detect the device
3. Flash a .hex file
4. Reset the device into application mode (may be done automatically)
4. Press the `RESET` button on the PCB or short RST to GND
## BootloadHID
BootloadHID is a USB bootloader for AVR microcontrollers. The uploader tool requires no kernel level driver on Windows and can therefore be run without installing any DLLs.
BootloadHID is a USB bootloader for AVR microcontrollers. It presents itself as an HID input device, much like HalfKay, and can therefore be run without installing any driver on Windows.
To ensure compatibility with the bootloadHID bootloader, make sure this block is present your `rules.mk`:
To ensure compatibility with the bootloadHID bootloader, make sure this block is present in your `rules.mk`:
```make
# Bootloader selection
# Teensy halfkay
# Pro Micro caterina
# Atmel DFU atmel-dfu
# LUFA DFU lufa-dfu
# QMK DFU qmk-dfu
# ATmega32A bootloadHID
# ATmega328P USBasp
BOOTLOADER = bootloadHID
```
Compatible flashers:
* [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) (recommended Windows GUI)
* [bootloadhid Command Line](https://www.obdev.at/products/vusb/bootloadhid.html) / `:BootloadHID` in QMK (recommended command line)
* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
* [bootloadHID CLI](https://www.obdev.at/products/vusb/bootloadhid.html) / `:bootloadHID` target in QMK (recommended command line)
* [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash)
Flashing sequence:
1. Enter the bootloader using any of the following methods:
* Tap the `RESET` keycode (may not work on all devices)
* Hold the salt key while plugging the keyboard in (usually documented within keyboard readme)
* Tap the `RESET` keycode
* Hold the salt key while plugging the keyboard in - for PS2AVRGB boards, this is usually the key connected to MCU pins A0 and B0, otherwise it will be documented in your keyboard's readme
2. Wait for the OS to detect the device
3. Flash a .hex file
4. Reset the device into application mode (may be done automatically)
or:
## STM32/APM32 DFU
make <keyboard>:<keymap>:bootloadHID
All STM32 and APM32 MCUs, except for F103 (see the [STM32duino section](#stm32duino)) come preloaded with a factory bootloader that cannot be modified nor deleted.
## STM32
To ensure compatibility with the STM32-DFU bootloader, make sure this block is present in your `rules.mk` (optionally with `apm32-dfu` instead):
All STM32 chips come preloaded with a factory bootloader that cannot be modified nor deleted. Some STM32 chips have bootloaders that do not come with USB programming (e.g. STM32F103) but the process is still the same.
At the moment, no `BOOTLOADER` variable is needed on `rules.mk` for STM32.
```make
# Bootloader selection
BOOTLOADER = stm32-dfu
```
Compatible flashers:
* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
* [dfu-util](https://github.com/Stefan-Schmidt/dfu-util) / `:dfu-util` (recommended command line)
* [dfu-util](https://dfu-util.sourceforge.net/) / `:dfu-util` target in QMK (recommended command line)
Flashing sequence:
1. Enter the bootloader using any of the following methods:
* Tap the `RESET` keycode (may not work on STM32F042 devices)
* If a reset circuit is present, tap the RESET button
* Otherwise, you need to bridge BOOT0 to VCC (via BOOT0 button or bridge), short RESET to GND (via RESET button or bridge), and then let go of the BOOT0 bridge
* If a reset circuit is present, tap the `RESET` button on the PCB; some boards may also have a toggle switch that must be flipped
* Otherwise, you need to bridge `BOOT0` to VCC (via `BOOT0` button or jumper), short `RESET` to GND (via `RESET` button or jumper), and then let go of the `BOOT0` bridge
2. Wait for the OS to detect the device
3. Flash a .bin file
* You will receive a warning about the DFU signature; Just ignore it
4. Reset the device into application mode (may be done automatically)
* If you are building from command line (e.g. `make planck/rev6:default:dfu-util`), make sure that `:leave` is passed to the `DFU_ARGS` variable inside your `rules.mk` (e.g. `DFU_ARGS = -d 0483:df11 -a 0 -s 0x08000000:leave`) so that your device resets after flashing
### STM32 Commands
### `make` Targets
There are a number of DFU commands that you can use to flash firmware to a STM32 device:
* `:dfu-util`: Waits until an STM32 bootloader device is available, and then flashes the firmware.
* `:dfu-util-split-left` and `:dfu-util-split-right`: Flashes the firmware as with `:avrdude`, but also sets the handedness setting in EEPROM. This is ideal for Proton-C-based split keyboards.
* `:st-link-cli`: Allows you to flash the firmware via the ST-Link CLI utility, rather than dfu-util. Requires an ST-Link dongle.
* `:st-flash`: Allows you to flash the firmware via the `st-flash` utility from [STLink Tools](https://github.com/stlink-org/stlink), rather than dfu-util. Requires an ST-Link dongle.
* `:dfu-util` - The default command for flashing to STM32 devices, and will wait until an STM32 bootloader device is present.
* `:dfu-util-split-left` - This flashes the normal firmware, just like the default option (`:dfu-util`). However, this also configures the "Left Side" EEPROM setting for split keyboards.
* `:dfu-util-split-right` - This flashes the normal firmware, just like the default option (`:dfu-util`). However, this also configures the "Right Side" EEPROM setting for split keyboards.
* `:st-link-cli` - This allows you to flash the firmware via ST-LINK's CLI utility, rather than dfu-util.
* `:st-flash` - This allows you to flash the firmware via the `st-flash` utility from [STLink Tools](https://github.com/stlink-org/stlink), rather than dfu-util.
## STM32duino
This bootloader is used almost exclusively for STM32F103 boards, as they do not come with a USB DFU bootloader. The source code and prebuilt binaries can be found [here](https://github.com/rogerclarkmelbourne/STM32duino-bootloader).
To ensure compatibility with the STM32duino bootloader, make sure this block is present in your `rules.mk`:
```make
# Bootloader selection
BOOTLOADER = stm32duino
```
Compatible flashers:
* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
* [dfu-util](https://dfu-util.sourceforge.net/) / `:dfu-util` target in QMK (recommended command line)
Flashing sequence:
1. Enter the bootloader using any of the following methods:
* Tap the `RESET` keycode
* If a reset circuit is present, tap the `RESET` button on the PCB
* Otherwise, you need to bridge `BOOT0` to VCC (via `BOOT0` button or jumper), short `RESET` to GND (via `RESET` button or jumper), and then let go of the `BOOT0` bridge
2. Wait for the OS to detect the device
3. Flash a .bin file
4. Reset the device into application mode (may be done automatically)
## Kiibohd DFU
Keyboards produced by Input Club use NXP Kinetis microcontrollers rather than STM32, and come with their own [custom bootloader](https://github.com/kiibohd/controller/tree/master/Bootloader), however the process and protocol is largely the same.
The `rules.mk` setting for this bootloader is `kiibohd`, but since this bootloader is limited to Input Club boards, it should not be necessary to set at keymap or user level.
Compatible flashers:
* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (recommended GUI)
* [dfu-util](https://dfu-util.sourceforge.net/) / `:dfu-util` target in QMK (recommended command line)
Flashing sequence:
1. Enter the bootloader using any of the following methods:
* Tap the `RESET` keycode (this may only enter the MCU into a "secure" bootloader mode; see https://github.com/qmk/qmk_firmware/issues/6112)
* Press the `RESET` button on the PCB
2. Wait for the OS to detect the device
3. Flash a .bin file
4. Reset the device into application mode (may be done automatically)

4
docs/fr-fr/README.md
View File

@ -9,7 +9,7 @@
## Qu'est-ce que QMK Firmware ?
QMK (*Quantum Mechanical Keyboard*) est une communauté open source qui maintient le firmware QMK, la QMK Toolbox (*Boite à outil*), qmk.fm et leurs documentations. QMK Firmware est un firmware dédié aux claviers qui est basé sur [tmk\_keyboard](http://github.com/tmk/tmk_keyboard). Il offre des fonctionnalités très utiles pour les contrôleurs Atmel AVR, et, plus spécifiquement pour [les produits d'OLKB](http://olkb.com), le clavier [ErgoDox EZ](http://www.ergodox-ez.com), et pour les [produits Clueboard](http://clueboard.co/). Il prend désormais aussi en charge les processeurs ARM qui utilisent ChibiOS. Vous pouvez l'utiliser pour contrôler un clavier personnalisé soudé à la main ou alors sur un clavier avec un PCB personnalisé.
QMK (*Quantum Mechanical Keyboard*) est une communauté open source qui maintient le firmware QMK, la QMK Toolbox (*Boite à outil*), qmk.fm et leurs documentations. QMK Firmware est un firmware dédié aux claviers qui est basé sur [tmk\_keyboard](https://github.com/tmk/tmk_keyboard). Il offre des fonctionnalités très utiles pour les contrôleurs Atmel AVR, et, plus spécifiquement pour [les produits d'OLKB](https://olkb.com), le clavier [ErgoDox EZ](https://www.ergodox-ez.com), et pour les [produits Clueboard](https://clueboard.co/). Il prend désormais aussi en charge les processeurs ARM qui utilisent ChibiOS. Vous pouvez l'utiliser pour contrôler un clavier personnalisé soudé à la main ou alors sur un clavier avec un PCB personnalisé.
## Comment l'obtenir
@ -29,4 +29,4 @@ Cette commande compilera la révision `rev4` du clavier `planck` avec la disposi
## Comment le personnaliser
QMK a beaucoup de [fonctionnalités](fr-fr/features.md) à explorer, et [une documentation](http://docs.qmk.fm) très abondante que vous pourrez parcourir. La plupart des fonctionnalités vous permettrons de modifier vos [dispositions](fr-fr/keymap.md) (keymaps) et de changer [les codes de caractères](fr-fr/keycodes.md) (keycodes).
QMK a beaucoup de [fonctionnalités](fr-fr/features.md) à explorer, et [une documentation](https://docs.qmk.fm) très abondante que vous pourrez parcourir. La plupart des fonctionnalités vous permettrons de modifier vos [dispositions](fr-fr/keymap.md) (keymaps) et de changer [les codes de caractères](fr-fr/keycodes.md) (keycodes).

4
docs/fr-fr/contributing.md
View File

@ -23,7 +23,7 @@ Merci de garder ceci en tête:
# Aperçu du projet
QMK est majoritairement écrit en C, avec quelques fonctions et parties spécifiques écrites en C++. Il est destiné aux processeurs intégrés que l'on trouve dans des clavier, particulièrement AVR ([LUFA](http://www.fourwalledcubicle.com/LUFA.php)) et ARM ([ChibiOS](http://www.chibios.com)). Si vous maîtrisez déjà la programmation sur Arduino, vous trouverez beaucoup de concepts et de limitations familiers. Une expérience préalable avec les Arduino n'est pas nécessaire à contribuer avec succès à QMK.
QMK est majoritairement écrit en C, avec quelques fonctions et parties spécifiques écrites en C++. Il est destiné aux processeurs intégrés que l'on trouve dans des clavier, particulièrement AVR ([LUFA](https://www.fourwalledcubicle.com/LUFA.php)) et ARM ([ChibiOS](https://www.chibios.org)). Si vous maîtrisez déjà la programmation sur Arduino, vous trouverez beaucoup de concepts et de limitations familiers. Une expérience préalable avec les Arduino n'est pas nécessaire à contribuer avec succès à QMK.
<!-- FIXME: We should include a list of resources for learning C here. -->
@ -83,7 +83,7 @@ Limited experimentation on the devices I have available shows that 7 is high eno
La documentation est l'une des manières les plus simples de démarrer la contribution sur QMK. Il est simple de trouver des endroits où la documentation est fausse ou incomplète, et il est tout aussi simple de la corriger! Nous avons aussi grandement besoin de quelqu'un pour éditer notre documentation, donc si vous avez des compétences en édition mais que vous n'êtes pas sûr de savoir où aller, n'hésitez pas [demandez de l'aide](#where-can-i-go-for-help)!
Vous trouverez toute notre documentation dans le répertoire `qmk_firmware/docs`, ou si vous préférez utiliser des outils web, vous pouvez cliquer sur le bouton "Suggest An Edit" en haut de chaque page sur http://docs.qmk.fm/.
Vous trouverez toute notre documentation dans le répertoire `qmk_firmware/docs`, ou si vous préférez utiliser des outils web, vous pouvez cliquer sur le bouton "Suggest An Edit" en haut de chaque page sur https://docs.qmk.fm/.
Lorsque vous donnez des exemples de code dans la documentation, essayez de suivre les conventions de nommage utilisées ailleurs dans la documentation. Par exemple, standardisez les enums en utilisant `my_layers` ou `my_keycodes` afin de garder une consistance:

4
docs/fr-fr/faq_build.md
View File

@ -96,8 +96,8 @@ La plupart des boards QMK utilisent `0xFEED` comme vendor ID. Vérifiez les autr
https://github.com/tmk/tmk_keyboard/issues/150
Vous pouvez acheter un VID:PID unique ici. Je ne pense pas que ce soit nécessaire pour un usage personnel.
- 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
- 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
## BOOTLOADER_SIZE pour AVR

10
docs/fr-fr/faq_debug.md
View File

@ -93,8 +93,8 @@ https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switc
Sans circuit de réinitialisation vous allez avoir des résultats inconsistants à cause de la mauvaise initialisation du matériel. Regardez le schéma du circuit du TPM754.
- http://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
- http://www.mikrocontroller.net/attachment/52583/tpm754.pdf
- https://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
- https://www.mikrocontroller.net/attachment/52583/tpm754.pdf
## Impossible de lire la colonne de la matrice après 16
@ -102,7 +102,7 @@ Utilisez `1UL<<16` à la place de `1<<16` dans `read_cols()` du fichier [matrix.
En C, `1` implique un type [int] qui est [16 bits] pour les AVR, ce qui implique que vous ne pouvez pas décaler à gauche de plus de 15. Si vous utilisez `1<<16`, vous aurez un résultat non attendu de zéro. Vous devez donc utiliser un type [unsigned long] en utilisant `1UL`.
http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
https://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
## Les touches spéciales ne fonctionnent pas (Touche Système, Touches de contrôle du son)
@ -122,8 +122,8 @@ Appuyer sur n'importe quelle touche en mode veille devrait sortir l'ordinateur d
**Faites attention au fait que le nommage des pin d'un Arduino diffère de la puce**. Par exemple, la pin `D0` n'est pas `PD0`. Vérifiez le circuit avec la fiche technique.
- http://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
- http://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf
- https://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
- https://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf
Les Arduino Leonardo et micro ont des **ATMega32U4** et peuvent être utilisés avec TMK, mais le bootloader Arduino peut causer des problèmes.

10
docs/fr-fr/faq_keymap.md
View File

@ -12,7 +12,7 @@ Les keycodes sont définies dans [common/keycode.h](https://github.com/qmk/qmk_f
Il existe 3 configurations de clavier standard utilisées dans le monde: ANSI, ISO et JIS. L'Amérique du Nord utilise principalement l'ANSI, l'Europe et l'Afrique l'ISO et le Japon utilise JIS. Les autres régions utilisent généralement ANSI ou ISO. Les keycodes correspondant à ces dispositions spécifiques sont affichés ici :
<!-- 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)
## Certaines de mes touches sont permutées ou ne fonctionnent pas
@ -33,8 +33,8 @@ La touche trouvée sur la plupart des claviers modernes située entre `KC_RGUI`
Utilisez le keycode pour Print Screen (`KC_PSCREEN` or `KC_PSCR`) à la place de `KC_SYSREQ`. La combinaison de touche 'Alt + Print Screen' est reconnue comme 'System request'.
Voir [issue #168](https://github.com/tmk/tmk_keyboard/issues/168) et
* 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
## Les touches alimentation ne fonctionnent pas
@ -54,12 +54,12 @@ Les touches de modification ou les calques peuvent être bloquées si la commuta
Pour les touches de modification et les actions de calque, vous devez placer `KC_TRANS` sur la même position du calque de destination afin de désenregistrer la clé de modificateur ou de revenir au calque précédent lors de la libération.
* 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
## Support de touche à verrouillage mécanique
Cette fonctionnalité permet l'usage de *touches à verrouillage mécanique* comme [ces interrupteurs Alps](http://deskthority.net/wiki/Alps_SKCL_Lock). Vous pouvez l'activer en ajoutant ceci à votre `config.h` :
Cette fonctionnalité permet l'usage de *touches à verrouillage mécanique* comme [ces interrupteurs Alps](https://deskthority.net/wiki/Alps_SKCL_Lock). Vous pouvez l'activer en ajoutant ceci à votre `config.h` :
```
#define LOCKING_SUPPORT_ENABLE

4
docs/fr-fr/flashing.md
View File

@ -84,7 +84,7 @@ BOOTLOADER = caterina
Flashers compatibles :
* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (Interface graphique recommandée)
* [avrdude](http://www.nongnu.org/avrdude/) avec avr109 / `:avrdude` (Outil en ligne de commande recommandé)
* [avrdude](https://www.nongnu.org/avrdude/) avec avr109 / `:avrdude` (Outil en ligne de commande recommandé)
* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)
Séquence de flash : 
@ -159,7 +159,7 @@ BOOTLOADER = USBasp
Flashers compatibles :
* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (Interface graphique recommandé)
* [avrdude](http://www.nongnu.org/avrdude/) avec le programmeur `usbasp`.
* [avrdude](https://www.nongnu.org/avrdude/) avec le programmeur `usbasp`.
* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)
Séquence de flash :

10
docs/fr-fr/getting_started_github.md
View File

@ -6,15 +6,15 @@ GitHub peut être un peu compliqué pour ceux qui n'y sont pas familier. Ce guid
Commencez par la [page GitHub de QMK](https://github.com/qmk/qmk_firmware), et vous verrez un bouton dans le coin en haut à droite qui indique "Fork":
![Fork on GitHub](http://i.imgur.com/8Toomz4.jpg)
![Fork on GitHub](https://i.imgur.com/8Toomz4.jpg)
Si vous faites partie d'une organisation, vous aurez besoin de savoir quel compte utiliser pour le fork. Dans la plupart des cas, vous voudrez créer le fork dans votre compte personnel. Une fois le fork complet (cela peut quelques fois prendre un peu de temps), appuyez sur le bouton "Clone or download":
![Download from GitHub](http://i.imgur.com/N1NYcSz.jpg)
![Download from GitHub](https://i.imgur.com/N1NYcSz.jpg)
Faites attention à sélectionner "HTTPS", et sélectionnez le lien et copiez-le:
![HTTPS link](http://i.imgur.com/eGO0ohO.jpg)
![HTTPS link](https://i.imgur.com/eGO0ohO.jpg)
Ensuite, entrez `git clone --recurse-submodules ` dans la ligne de commande, et collez votre lien:
@ -56,11 +56,11 @@ To https://github.com/whoeveryouare/qmk_firmware.git
Vos changements existent maintenant dans votre fork sur GitHub. Si vous allez à cette adresse (`https://github.com/<whoeveryouare>/qmk_firmware`), vous pouvez créer un nouveau "Pull Request" en cliquant sur ce bouton:
![New Pull Request](http://i.imgur.com/DxMHpJ8.jpg)
![New Pull Request](https://i.imgur.com/DxMHpJ8.jpg)
Maintenant, vous pourrez voir exactement ce que vous avez commité. Si ça vous semble bien, vous pouvez le finaliser en cliquant sur "Create Pull Request":
![Create Pull Request](http://i.imgur.com/Ojydlaj.jpg)
![Create Pull Request](https://i.imgur.com/Ojydlaj.jpg)
Une fois transmis, nous pourrons vous parler de vos changements, vous demander de faire des changements, et éventuellement de les accepter!

2
docs/fr-fr/newbs.md
View File

@ -2,7 +2,7 @@
QMK est un firmware Open Source pour votre clavier mécanique. Vous pouvez utiliser QMK pour customiser votre clavier de manière simple et puissante. Tout le monde, du débutant complet au développeur avancé, ont utilisé avec succès QMK pour customiser leur clavier. Ce guide vous aidera à faire de même, quelles que soient vos compétences.
Vous voulez savoir si votre clavier peut utiliser QMK? Si c'est un clavier mécanique que vous avez vous-même construit, il y a de bonnes chances que vous pouvez. Nous supportons un [grand nombre de "hobbyist boards"](http://qmk.fr/keyboards), donc même si votre clavier ne peut pas utiliser QMK, vous ne devriez pas avoir trop de problème pour en trouver un qui vous convienne.
Vous voulez savoir si votre clavier peut utiliser QMK? Si c'est un clavier mécanique que vous avez vous-même construit, il y a de bonnes chances que vous pouvez. Nous supportons un [grand nombre de "hobbyist boards"](https://qmk.fm/keyboards), donc même si votre clavier ne peut pas utiliser QMK, vous ne devriez pas avoir trop de problème pour en trouver un qui vous convienne.
## Vue d'ensemble

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