diff --git a/.clang_complete b/.clang_complete deleted file mode 100644 index 21434586c73..00000000000 --- a/.clang_complete +++ /dev/null @@ -1,24 +0,0 @@ - --I. --I./drivers --I./drivers/avr --I./keyboards/ergodox_ez --I./keyboards/ergodox_ez/keymaps/vim --I./lib --I./lib/lufa --I./quantum --I./quantum/api --I./quantum/audio --I./quantum/keymap_extras --I./quantum/process_keycode --I./quantum/serial_link --I./quantum/template --I./quantum/tools --I./quantum/visualizer --I./tmk_core --I./tmk_core/common --I./tmk_core/common/debug.h --I./tmk_core/protocol --I./tmk_core/protocol/lufa --I./util --DQMK_KEYBOARD=\"$(KEYBOARD)\" -DQMK_KEYMAP=\"$(KEYMAP)\" diff --git a/.github/ISSUE_TEMPLATE/blank.md b/.github/ISSUE_TEMPLATE/zzz_blank.md similarity index 100% rename from .github/ISSUE_TEMPLATE/blank.md rename to .github/ISSUE_TEMPLATE/zzz_blank.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index cbc018ea057..d402488d407 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -26,7 +26,8 @@ -- [ ] My code follows the code style of this project. +- [ ] My code follows the code style of this project: [**C**](https://docs.qmk.fm/#/coding_conventions_c), [**Python**](https://docs.qmk.fm/#/coding_conventions_python) +- [ ] I have read the [**PR Checklist** document](https://docs.qmk.fm/#/pr_checklist) and have made the appropriate changes. - [ ] My change requires a change to the documentation. - [ ] I have updated the documentation accordingly. - [ ] I have read the [**CONTRIBUTING** document](https://docs.qmk.fm/#/contributing). diff --git a/.github/labeler.yml b/.github/labeler.yml new file mode 100644 index 00000000000..53921f7f959 --- /dev/null +++ b/.github/labeler.yml @@ -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/**/* diff --git a/.github/workflows/api.yml b/.github/workflows/api.yml new file mode 100644 index 00000000000..c8d988d0f0e --- /dev/null +++ b/.github/workflows/api.yml @@ -0,0 +1,37 @@ +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: Upload API Data + uses: jakejarvis/s3-sync-action@master + with: + args: --acl public-read --follow-symlinks --delete + env: + AWS_S3_BUCKET: ${{ secrets.API_SPACE_MASTER }} + AWS_ACCESS_KEY_ID: ${{ secrets.SPACES_ACCESS_KEY }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.SPACES_SECRET_KEY }} + AWS_S3_ENDPOINT: https://nyc3.digitaloceanspaces.com + SOURCE_DIR: 'api_data' diff --git a/.github/workflows/auto_tag.yaml b/.github/workflows/auto_tag.yaml new file mode 100644 index 00000000000..29e85c41ca5 --- /dev/null +++ b/.github/workflows/auto_tag.yaml @@ -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' diff --git a/.github/workflows/cli.yml b/.github/workflows/cli.yml new file mode 100644 index 00000000000..28c6bb36798 --- /dev/null +++ b/.github/workflows/cli.yml @@ -0,0 +1,28 @@ +name: CLI CI + +on: + push: + branches: + - master + - future + pull_request: + paths: + - 'lib/python/**' + - 'bin/qmk' + - 'requirements.txt' + - '.github/workflows/cli.yml' + +jobs: + test: + runs-on: ubuntu-latest + + container: qmkfm/base_container + + steps: + - uses: actions/checkout@v2 + with: + submodules: recursive + - name: Install dependencies + run: pip3 install -r requirements.txt + - name: Run tests + run: bin/qmk pytest diff --git a/.github/workflows/develop_api.yml b/.github/workflows/develop_api.yml new file mode 100644 index 00000000000..4e64cbcf8c2 --- /dev/null +++ b/.github/workflows/develop_api.yml @@ -0,0 +1,37 @@ +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: Upload API Data + uses: jakejarvis/s3-sync-action@master + with: + args: --acl public-read --follow-symlinks --delete + env: + AWS_S3_BUCKET: ${{ secrets.API_SPACE_DEVELOP }} + AWS_ACCESS_KEY_ID: ${{ secrets.SPACES_ACCESS_KEY }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.SPACES_SECRET_KEY }} + AWS_S3_ENDPOINT: https://nyc3.digitaloceanspaces.com + SOURCE_DIR: 'api_data' diff --git a/.github/workflows/develop_update.yml b/.github/workflows/develop_update.yml new file mode 100644 index 00000000000..285720fefe6 --- /dev/null +++ b/.github/workflows/develop_update.yml @@ -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 diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000000..8855d1107f1 --- /dev/null +++ b/.github/workflows/docs.yml @@ -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 diff --git a/.github/workflows/format.yaml b/.github/workflows/format.yaml new file mode 100644 index 00000000000..201f3c230fb --- /dev/null +++ b/.github/workflows/format.yaml @@ -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 + committer: QMK Bot + commit-message: Format code according to conventions + title: '[CI] Format code according to conventions' diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml new file mode 100644 index 00000000000..3b99a8f43e6 --- /dev/null +++ b/.github/workflows/labeler.yml @@ -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' diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 00000000000..cd67de9d8be --- /dev/null +++ b/.github/workflows/lint.yml @@ -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 diff --git a/.gitignore b/.gitignore index 7b15615625c..d6846cf63be 100644 --- a/.gitignore +++ b/.gitignore @@ -16,6 +16,7 @@ *.swp tags *~ +api_data/v1 build/ .build/ *.bak @@ -24,6 +25,7 @@ quantum/version.h .idea/ CMakeLists.txt cmake-build-debug +.clang_complete doxygen/ .DS_Store /util/wsl_downloaded @@ -47,7 +49,6 @@ doxygen/ *.iml .browse.VC.db* *.stackdump -util/Win_Check_Output.txt # Let these ones be user specific, since we have so many different configurations .vscode/c_cpp_properties.json .vscode/launch.json @@ -63,9 +64,6 @@ util/Win_Check_Output.txt *.gif *.jpg -# Do not ignore MiniDox left/right hand eeprom files -!keyboards/minidox/*.eep - # things travis sees secrets.tar id_rsa_* @@ -73,3 +71,9 @@ id_rsa_* # python things __pycache__ + +# prerequisites for updating ChibiOS +/util/fmpp* + +# Allow to exist but don't include it in the repo +user_song_list.h diff --git a/.gitmodules b/.gitmodules index f2e96bedc85..324ef790d34 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,16 +1,24 @@ [submodule "lib/chibios"] path = lib/chibios url = https://github.com/qmk/ChibiOS + branch = master [submodule "lib/chibios-contrib"] path = lib/chibios-contrib url = https://github.com/qmk/ChibiOS-Contrib - branch = k-type-fix + branch = master [submodule "lib/ugfx"] path = lib/ugfx url = https://github.com/qmk/uGFX + branch = master [submodule "lib/googletest"] path = lib/googletest - url = https://github.com/google/googletest + url = https://github.com/qmk/googletest [submodule "lib/lufa"] path = lib/lufa url = https://github.com/qmk/lufa +[submodule "lib/vusb"] + path = lib/vusb + url = https://github.com/qmk/v-usb +[submodule "lib/printf"] + path = lib/printf + url = https://github.com/qmk/printf diff --git a/.travis.yml b/.travis.yml index bfac998c11e..17f401da45c 100644 --- a/.travis.yml +++ b/.travis.yml @@ -12,21 +12,21 @@ env: - MAKEFLAGS="-j3 --output-sync" services: - docker -install: - - npm install -g moxygen +addons: + apt: + sources: + - ubuntu-toolchain-r-test + - llvm-toolchain-trusty-7 + packages: + - diffutils + - clang-format-7 + - libstdc++-7-dev 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 -addons: - apt: - packages: - - pandoc - - diffutils - - dos2unix - - doxygen after_script: bash util/travis_compiled_push.sh notifications: diff --git a/.vscode/settings.json b/.vscode/settings.json index e5089a55bad..775b3df1722 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -5,15 +5,22 @@ // Configure glob patterns for excluding files and folders. "files.exclude": { "**/.build": true, - "**/*.hex": true + "**/*.hex": true, + "**/*.bin": true }, "files.associations": { - "*.h": "c", - "*.c": "c", - "*.cpp": "cpp", - "*.hpp": "cpp", - "xstddef": "c", - "type_traits": "c", - "utility": "c" + "*.h": "c", + "*.c": "c", + "*.inc": "c", + "*.cpp": "cpp", + "*.hpp": "cpp", + "xstddef": "c", + "type_traits": "c", + "utility": "c", + "ranges": "c" + }, + "[markdown]": { + "editor.trimAutoWhitespace": false, + "files.trimTrailingWhitespace": false } } diff --git a/Makefile b/Makefile index 8f02eea0496..91ab9e4e8ea 100644 --- a/Makefile +++ b/Makefile @@ -29,6 +29,9 @@ $(info QMK Firmware $(QMK_VERSION)) endif endif +# avoid 'Entering|Leaving directory' messages +MAKEFLAGS += --no-print-directory + ON_ERROR := error_occurred=1 BREAK_ON_ERRORS = no @@ -65,71 +68,15 @@ PATH_ELEMENTS := $(subst /, ,$(STARTING_DIR)) # Initialize the path elements list for further processing $(eval $(call NEXT_PATH_ELEMENT)) -# This function sets the KEYBOARD; KEYMAP and SUBPROJECT to the correct -# variables depending on which directory you stand in. -# It's really a very simple if else chain, if you squint enough, -# but the makefile syntax makes it very verbose. -# If we are in a subfolder of keyboards -# -# *** No longer needed ** -# -# ifeq ($(CURRENT_PATH_ELEMENT),keyboards) -# $(eval $(call NEXT_PATH_ELEMENT)) -# KEYBOARD := $(CURRENT_PATH_ELEMENT) -# $(eval $(call NEXT_PATH_ELEMENT)) -# # If we are in a subfolder of keymaps, or in other words in a keymap -# # folder -# ifeq ($(CURRENT_PATH_ELEMENT),keymaps) -# $(eval $(call NEXT_PATH_ELEMENT)) -# KEYMAP := $(CURRENT_PATH_ELEMENT) -# # else if we are not in the keyboard folder itself -# else ifneq ($(CURRENT_PATH_ELEMENT),) -# # the we can assume it's a subproject, as no other folders -# # should have make files in them -# SUBPROJECT := $(CURRENT_PATH_ELEMENT) -# $(eval $(call NEXT_PATH_ELEMENT)) -# # if we are inside a keymap folder of a subproject -# ifeq ($(CURRENT_PATH_ELEMENT),keymaps) -# $(eval $(call NEXT_PATH_ELEMENT)) -# KEYMAP := $(CURRENT_PATH_ELEMENT) -# endif -# endif -# endif - -define GET_KEYBOARDS -ifndef ALT_GET_KEYBOARDS - All_RULES_MK := $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/rules.mk)) - All_RULES_MK += $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/*/rules.mk)) - All_RULES_MK += $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/*/*/rules.mk)) - All_RULES_MK += $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/*/*/*/rules.mk)) - - KEYMAPS_MK := $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/keymaps/*/rules.mk)) - KEYMAPS_MK += $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/*/keymaps/*/rules.mk)) - KEYMAPS_MK += $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/*/*/keymaps/*/rules.mk)) - KEYMAPS_MK += $$(patsubst $(ROOT_DIR)/keyboards/%/rules.mk,%,$$(wildcard $(ROOT_DIR)/keyboards/*/*/*/*/keymaps/*/rules.mk)) - - KEYBOARDS := $$(sort $$(filter-out $$(KEYMAPS_MK), $$(All_RULES_MK))) -else - KEYBOARDS := $(shell find keyboards/ -type f -iname "rules.mk" | grep -v keymaps | sed 's!keyboards/\(.*\)/rules.mk!\1!' | sort | uniq) -endif -endef - -$(eval $(call GET_KEYBOARDS)) - -# Only consider folders with makefiles, to prevent errors in case there are extra folders -#KEYBOARDS += $(patsubst $(ROOD_DIR)/keyboards/%/rules.mk,%,$(wildcard $(ROOT_DIR)/keyboards/*/*/rules.mk)) +# Phony targets to enable a few simple make commands outside the main processing below. .PHONY: list-keyboards list-keyboards: - echo $(KEYBOARDS) - -define PRINT_KEYBOARD - $(info $(PRINTING_KEYBOARD)) -endef + util/list_keyboards.sh | sort -u | tr '\n' ' ' .PHONY: generate-keyboards-file generate-keyboards-file: - $(foreach PRINTING_KEYBOARD,$(KEYBOARDS),$(eval $(call PRINT_KEYBOARD))) + util/list_keyboards.sh | sort -u .PHONY: clean clean: @@ -155,8 +102,6 @@ endif # Uncomment these for debugging # $(info Keyboard: $(KEYBOARD)) # $(info Keymap: $(KEYMAP)) -# $(info Subproject: $(SUBPROJECT)) -# $(info Keyboards: $(KEYBOARDS)) # Set the default goal depending on where we are running make from @@ -214,7 +159,6 @@ endef # A recursive helper function for finding the longest match # $1 The list to be checked # It works by always removing the currently matched item from the list -# and call itself recursively, until a match is found define TRY_TO_MATCH_RULE_FROM_LIST_HELPER2 # Stop the recursion when the list is empty ifneq ($1,) @@ -269,16 +213,29 @@ endef define PARSE_RULE RULE := $1 COMMANDS := + REQUIRE_PLATFORM_KEY := # If the rule starts with all, then continue the parsing from # PARSE_ALL_KEYBOARDS ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,all),true) KEYBOARD_RULE=all $$(eval $$(call PARSE_ALL_KEYBOARDS)) + else ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,all-avr),true) + KEYBOARD_RULE=all + REQUIRE_PLATFORM_KEY := avr + $$(eval $$(call PARSE_ALL_KEYBOARDS)) + else ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,all-chibios),true) + KEYBOARD_RULE=all + REQUIRE_PLATFORM_KEY := chibios + $$(eval $$(call PARSE_ALL_KEYBOARDS)) + else ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,all-arm_atsam),true) + KEYBOARD_RULE=all + REQUIRE_PLATFORM_KEY := arm_atsam + $$(eval $$(call PARSE_ALL_KEYBOARDS)) else ifeq ($$(call COMPARE_AND_REMOVE_FROM_RULE,test),true) $$(eval $$(call PARSE_TEST)) # If the rule starts with the name of a known keyboard, then continue # the parsing from PARSE_KEYBOARD - else ifeq ($$(call TRY_TO_MATCH_RULE_FROM_LIST,$$(KEYBOARDS)),true) + else ifeq ($$(call TRY_TO_MATCH_RULE_FROM_LIST,$$(shell util/list_keyboards.sh | sort -u)),true) KEYBOARD_RULE=$$(MATCHED_ITEM) $$(eval $$(call PARSE_KEYBOARD,$$(MATCHED_ITEM))) # Otherwise use the KEYBOARD variable, which is determined either by @@ -291,8 +248,8 @@ define PARSE_RULE $$(info | QMK's make format recently changed to use folder locations and colons:) $$(info | make project_folder:keymap[:target]) $$(info | Examples:) - $$(info | make planck/rev4:default:dfu) - $$(info | make planck:default) + $$(info | make dz60:default) + $$(info | make planck/rev6:default:flash) $$(info |) endif endef @@ -395,26 +352,9 @@ endef # if we are going to compile all keyboards, match the rest of the rule # for each of them define PARSE_ALL_KEYBOARDS - $$(eval $$(call PARSE_ALL_IN_LIST,PARSE_KEYBOARD,$(KEYBOARDS))) + $$(eval $$(call PARSE_ALL_IN_LIST,PARSE_KEYBOARD,$(shell util/list_keyboards.sh noci | sort -u))) endef -# $1 Subproject -# When entering this, the keyboard and subproject are known, so now we need -# to determine which keymaps are going to get compiled -# define PARSE_SUBPROJECT - -# endef - -# If we want to parse all subprojects, but the keyboard doesn't have any, -# then use defaultsp instead -# define PARSE_ALL_SUBPROJECTS -# ifeq ($$(SUBPROJECTS),) -# $$(eval $$(call PARSE_SUBPROJECT,defaultsp)) -# else -# $$(eval $$(call PARSE_ALL_IN_LIST,PARSE_SUBPROJECT,$$(SUBPROJECTS))) -# endif -# endef - # Prints a list of all known keymaps for the given keyboard define LIST_ALL_KEYMAPS COMMAND_true_LIST_KEYMAPS := \ @@ -444,7 +384,7 @@ define PARSE_KEYMAP # Format it in bold KB_SP := $(BOLD)$$(KB_SP)$(NO_COLOR) # Specify the variables that we are passing forward to submake - MAKE_VARS := KEYBOARD=$$(CURRENT_KB) KEYMAP=$$(CURRENT_KM) + MAKE_VARS := KEYBOARD=$$(CURRENT_KB) KEYMAP=$$(CURRENT_KM) REQUIRE_PLATFORM_KEY=$$(REQUIRE_PLATFORM_KEY) # And the first part of the make command MAKE_CMD := $$(MAKE) -r -R -C $(ROOT_DIR) -f build_keyboard.mk $$(MAKE_TARGET) # The message to display @@ -463,6 +403,8 @@ define BUILD LOG=$$$$($$(MAKE_CMD) $$(MAKE_VARS) SILENT=true 2>&1) ; \ if [ $$$$? -gt 0 ]; \ then $$(PRINT_ERROR_PLAIN); \ + elif [ "$$$$LOG" = "skipped" ] ; \ + then $$(PRINT_SKIPPED_PLAIN); \ elif [ "$$$$LOG" != "" ] ; \ then $$(PRINT_WARNING_PLAIN); \ else \ @@ -554,19 +496,21 @@ if [ $$error_occurred -gt 0 ]; then $(HANDLE_ERROR); fi; endef -# Let's match everything, we handle all the rule parsing ourselves +# Catch everything and parse the command line ourselves. .PHONY: % %: # Check if we have the CMP tool installed cmp $(ROOT_DIR)/Makefile $(ROOT_DIR)/Makefile >/dev/null 2>&1; if [ $$? -gt 0 ]; then printf "$(MSG_NO_CMP)"; exit 1; fi; - # Ensure that python3 is installed. This check can be removed after python is used in more places. - if ! python3 --version 1> /dev/null 2>&1; then printf "$(MSG_PYTHON_MISSING)"; fi + # Ensure that bin/qmk works. + 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 if [ ! -e lib/chibios-contrib ]; then git submodule sync lib/chibios-contrib && git submodule update --depth 50 --init lib/chibios-contrib; fi if [ ! -e lib/ugfx ]; then git submodule sync lib/ugfx && git submodule update --depth 50 --init lib/ugfx; fi if [ ! -e lib/lufa ]; then git submodule sync lib/lufa && git submodule update --depth 50 --init lib/lufa; fi + if [ ! -e lib/vusb ]; then git submodule sync lib/vusb && git submodule update --depth 50 --init lib/vusb; fi + if [ ! -e lib/printf ]; then git submodule sync lib/printf && git submodule update --depth 50 --init lib/printf; fi git submodule status --recursive 2>/dev/null | \ while IFS= read -r x; do \ case "$$x" in \ @@ -588,25 +532,6 @@ endif $(foreach TEST,$(sort $(TESTS)),$(RUN_TEST)) if [ -f $(ERROR_FILE) ]; then printf "$(MSG_ERRORS)" & exit 1; fi; -# These no longer work because of the colon system - -# All should compile everything -# .PHONY: all -# all: all-keyboards test-all - -# Define some shortcuts, mostly for compatibility with the old syntax -# .PHONY: all-keyboards -# all-keyboards: all\:all\:all - -# .PHONY: all-keyboards-defaults -# all-keyboards-defaults: all\:default - -# .PHONY: test -# test: test-all - -# .PHONY: test-clean -# test-clean: test-all-clean - lib/%: git submodule sync $? git submodule update --init $? @@ -623,15 +548,22 @@ endif # Generate the version.h file ifndef SKIP_GIT GIT_VERSION := $(shell git describe --abbrev=6 --dirty --always --tags 2>/dev/null || date +"%Y-%m-%d-%H:%M:%S") + CHIBIOS_VERSION := $(shell cd lib/chibios && git describe --abbrev=6 --dirty --always --tags 2>/dev/null || date +"%Y-%m-%d-%H:%M:%S") + CHIBIOS_CONTRIB_VERSION := $(shell cd lib/chibios-contrib && git describe --abbrev=6 --dirty --always --tags 2>/dev/null || date +"%Y-%m-%d-%H:%M:%S") else GIT_VERSION := NA + CHIBIOS_VERSION := NA + CHIBIOS_CONTRIB_VERSION := NA endif ifndef SKIP_VERSION BUILD_DATE := $(shell date +"%Y-%m-%d-%H:%M:%S") -$(shell echo '#define QMK_VERSION "$(GIT_VERSION)"' > $(ROOT_DIR)/quantum/version.h) -$(shell echo '#define QMK_BUILDDATE "$(BUILD_DATE)"' >> $(ROOT_DIR)/quantum/version.h) else -BUILD_DATE := NA +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) + include $(ROOT_DIR)/testlist.mk diff --git a/Vagrantfile b/Vagrantfile index dae4e0d53d9..adb93a3cee1 100644 --- a/Vagrantfile +++ b/Vagrantfile @@ -89,7 +89,7 @@ Vagrant.configure(2) do |config| Examples: make planck/rev4:default:dfu - make planck:default + make planck/rev4:default EOT end diff --git a/api_data/_config.yml b/api_data/_config.yml new file mode 100644 index 00000000000..277f1f2c510 --- /dev/null +++ b/api_data/_config.yml @@ -0,0 +1 @@ +theme: jekyll-theme-cayman diff --git a/api_data/readme.md b/api_data/readme.md new file mode 100644 index 00000000000..a4b2c6bce7b --- /dev/null +++ b/api_data/readme.md @@ -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 . + +Do not edit anything here by hand. It is generated with the `qmk generate-api` command. diff --git a/autocomplete.sh b/autocomplete.sh deleted file mode 100644 index dffb260c425..00000000000 --- a/autocomplete.sh +++ /dev/null @@ -1 +0,0 @@ -complete -W " 9key-default alps64-default amj40-default amj40-fabian amj60-default_60_ansi amj60-iso_split_rshift amj60-maximized amjpad-default amjpad-max amjpad-ortho_left amjpad-ortho_right atomic-default atomic-default_ortho_5x15 atomic-pvc atreus-alphadox atreus-classic atreus-default atreus-erlandsona atreus-gerb atreus-jeremy atreus-replicaJunction atreus-xyverz atreus62-atreus52 atreus62-default atreus62-mneme atreus62-xyverz bananasplit-0010 bananasplit-coloneljesus bananasplit-default bananasplit-hhkbanana bananasplit-nic bananasplit-rask bantam44-default chibios_test-default clueboard-bloodlvst clueboard-caps_fn clueboard-colemak clueboard-default clueboard-jokrik clueboard-mac_optimized clueboard-magicmonty clueboard-maximised clueboard-mouse_keys clueboard-serubin clueboard-shift_fn clueboard-skully clueboard-smt clueboard-tetris clueboard-unix_optimized clueboard-win_optimized clueboard-xyverz cluecard-default cluecard-rgb_effects cluepad-default deltasplit75-default deltasplit75-itsaferbie deltasplit75-protosplit dk60-default eco-default eco-that_canadian ergodone-333fred ergodone-ab ergodone-absenth ergodone-adam ergodone-adnw_k_o_y ergodone-albert ergodone-alexjj ergodone-algernon ergodone-alphadox ergodone-andrew_osx ergodone-belak ergodone-bepo ergodone-bepo_csa ergodone-bryan ergodone-coderkun_neo2 ergodone-colemak ergodone-colemak_osx_pc_no ergodone-colemak_programmer ergodone-common_nighthawk ergodone-csharp_dev ergodone-dave ergodone-deadcyclo ergodone-default ergodone-default_ergodox ergodone-dragon788 ergodone-dvorak ergodone-dvorak_emacs ergodone-dvorak_emacs_software ergodone-dvorak_intl_squisher ergodone-dvorak_plover ergodone-dvorak_programmer ergodone-dvorak_programmer_swe ergodone-dvorak_spanish ergodone-emacs_osx_dk ergodone-erez_experimental ergodone-familiar ergodone-french_hacker ergodone-galson ergodone-german ergodone-german-kinergo ergodone-german-lukas ergodone-german-manuneo ergodone-guni ergodone-ishigoya-jp ergodone-italian ergodone-j3rn ergodone-jack ergodone-jacobono ergodone-jafo ergodone-jgarr ergodone-josh ergodone-kastyle ergodone-kines-ish ergodone-kristian ergodone-maz ergodone-mclennon_osx ergodone-mpiechotka ergodone-msc ergodone-naps62 ergodone-neo2_on_qwertz_hardware ergodone-norwegian_programmer_osx_pc ergodone-norwegian_programmer_osx_pc_colemak ergodone-ordinary ergodone-osx_de ergodone-osx_de_adnw_koy ergodone-osx_de_experimental ergodone-osx_fr ergodone-osx_kinesis_pnut ergodone-osx_whiskey_tango_foxtrot_capslock ergodone-phoenix ergodone-plover ergodone-plums ergodone-pvinis ergodone-replicaJunction ergodone-reset_eeprom ergodone-robot_test_layout ergodone-romanzolotarev-norman-osx ergodone-romanzolotarev-norman-plover-osx ergodone-romanzolotarev-norman-plover-osx-hjkl ergodone-romanzolotarev-norman-qwerty-osx ergodone-sethbc ergodone-siroken3 ergodone-sneako ergodone-software_neo2 ergodone-supercoder ergodone-swedish ergodone-swedish-lindhe ergodone-swissgerman ergodone-techtomas ergodone-teckinesis ergodone-tkuichooseyou ergodone-tm2030 ergodone-tonyabra_osx ergodone-townk_osx ergodone-twentylives_dvorak_with_hebrew ergodone-twey ergodone-videck ergodone-win10_writers-block ergodone-workman_osx_mdw ergodone-xyverz ergodone-yoruian ergodone-zweihander-osx ergodox_ez-333fred ergodox_ez-ab ergodox_ez-absenth ergodox_ez-adam ergodox_ez-adnw_k_o_y ergodox_ez-albert ergodox_ez-alexjj ergodox_ez-algernon ergodox_ez-alphadox ergodox_ez-andrew_osx ergodox_ez-belak ergodox_ez-bepo ergodox_ez-bepo_csa ergodox_ez-blakedietz ergodox_ez-bryan ergodox_ez-coderkun_neo2 ergodox_ez-colemak ergodox_ez-colemak_osx_pc_no ergodox_ez-colemak_programmer ergodox_ez-common_nighthawk ergodox_ez-csharp_dev ergodox_ez-dave ergodox_ez-deadcyclo ergodox_ez-default ergodox_ez-default_ergodox ergodox_ez-default_osx ergodox_ez-dragon788 ergodox_ez-drashna ergodox_ez-drashna-custom ergodox_ez-dvorak ergodox_ez-dvorak_emacs ergodox_ez-dvorak_emacs_software ergodox_ez-dvorak_intl_squisher ergodox_ez-dvorak_plover ergodox_ez-dvorak_programmer ergodox_ez-dvorak_programmer_swe ergodox_ez-dvorak_spanish ergodox_ez-emacs_osx_dk ergodox_ez-erez_experimental ergodox_ez-familiar ergodox_ez-french_hacker ergodox_ez-galson ergodox_ez-german ergodox_ez-german-kinergo ergodox_ez-german-lukas ergodox_ez-german-manuneo ergodox_ez-guni ergodox_ez-ishigoya-jp ergodox_ez-italian ergodox_ez-j3rn ergodox_ez-jack ergodox_ez-jacobono ergodox_ez-jafo ergodox_ez-jgarr ergodox_ez-josh ergodox_ez-kastyle ergodox_ez-kines-ish ergodox_ez-kristian ergodox_ez-maz ergodox_ez-mclennon_osx ergodox_ez-mpiechotka ergodox_ez-msc ergodox_ez-naps62 ergodox_ez-neo2_on_qwertz_hardware ergodox_ez-norwegian_programmer_osx_pc ergodox_ez-norwegian_programmer_osx_pc_colemak ergodox_ez-ordinary ergodox_ez-osx_de ergodox_ez-osx_de_adnw_koy ergodox_ez-osx_de_experimental ergodox_ez-osx_fr ergodox_ez-osx_kinesis_pnut ergodox_ez-osx_whiskey_tango_foxtrot_capslock ergodox_ez-phoenix ergodox_ez-plover ergodox_ez-plums ergodox_ez-profet_80 ergodox_ez-pvinis ergodox_ez-replicaJunction ergodox_ez-reset_eeprom ergodox_ez-robot_test_layout ergodox_ez-romanzolotarev-norman-osx ergodox_ez-romanzolotarev-norman-plover-osx ergodox_ez-romanzolotarev-norman-plover-osx-hjkl ergodox_ez-romanzolotarev-norman-qwerty-osx ergodox_ez-sethbc ergodox_ez-siroken3 ergodox_ez-sneako ergodox_ez-software_neo2 ergodox_ez-steno ergodox_ez-supercoder ergodox_ez-swedish ergodox_ez-swedish-lindhe ergodox_ez-swissgerman ergodox_ez-techtomas ergodox_ez-teckinesis ergodox_ez-tkuichooseyou ergodox_ez-tm2030 ergodox_ez-tonyabra_osx ergodox_ez-townk_osx ergodox_ez-twentylives_dvorak_with_hebrew ergodox_ez-twey ergodox_ez-videck ergodox_ez-win10_writers-block ergodox_ez-workman_osx_mdw ergodox_ez-xyverz ergodox_ez-yoruian ergodox_ez-zweihander-osx ergodox_infinity-333fred ergodox_infinity-ab ergodox_infinity-absenth ergodox_infinity-adam ergodox_infinity-adnw_k_o_y ergodox_infinity-albert ergodox_infinity-alexjj ergodox_infinity-algernon ergodox_infinity-alphadox ergodox_infinity-andrew_osx ergodox_infinity-belak ergodox_infinity-bepo ergodox_infinity-bepo_csa ergodox_infinity-bryan ergodox_infinity-coderkun_neo2 ergodox_infinity-colemak ergodox_infinity-colemak_osx_pc_no ergodox_infinity-colemak_programmer ergodox_infinity-common_nighthawk ergodox_infinity-csharp_dev ergodox_infinity-dave ergodox_infinity-deadcyclo ergodox_infinity-default_ergodox ergodox_infinity-dragon788 ergodox_infinity-dvorak ergodox_infinity-dvorak_emacs ergodox_infinity-dvorak_emacs_software ergodox_infinity-dvorak_intl_squisher ergodox_infinity-dvorak_plover ergodox_infinity-dvorak_programmer ergodox_infinity-dvorak_programmer_swe ergodox_infinity-dvorak_spanish ergodox_infinity-emacs_osx_dk ergodox_infinity-erez_experimental ergodox_infinity-familiar ergodox_infinity-french_hacker ergodox_infinity-galson ergodox_infinity-german ergodox_infinity-german-kinergo ergodox_infinity-german-lukas ergodox_infinity-german-manuneo ergodox_infinity-guni ergodox_infinity-ishigoya-jp ergodox_infinity-italian ergodox_infinity-j3rn ergodox_infinity-jack ergodox_infinity-jacobono ergodox_infinity-jafo ergodox_infinity-jgarr ergodox_infinity-josh ergodox_infinity-kastyle ergodox_infinity-kines-ish ergodox_infinity-kristian ergodox_infinity-maz ergodox_infinity-mclennon_osx ergodox_infinity-mpiechotka ergodox_infinity-msc ergodox_infinity-naps62 ergodox_infinity-neo2_on_qwertz_hardware ergodox_infinity-norwegian_programmer_osx_pc ergodox_infinity-norwegian_programmer_osx_pc_colemak ergodox_infinity-ordinary ergodox_infinity-osx_de ergodox_infinity-osx_de_adnw_koy ergodox_infinity-osx_de_experimental ergodox_infinity-osx_fr ergodox_infinity-osx_kinesis_pnut ergodox_infinity-osx_whiskey_tango_foxtrot_capslock ergodox_infinity-phoenix ergodox_infinity-plover ergodox_infinity-plums ergodox_infinity-pvinis ergodox_infinity-replicaJunction ergodox_infinity-reset_eeprom ergodox_infinity-robot_test_layout ergodox_infinity-romanzolotarev-norman-osx ergodox_infinity-romanzolotarev-norman-plover-osx ergodox_infinity-romanzolotarev-norman-plover-osx-hjkl ergodox_infinity-romanzolotarev-norman-qwerty-osx ergodox_infinity-sethbc ergodox_infinity-siroken3 ergodox_infinity-sneako ergodox_infinity-software_neo2 ergodox_infinity-supercoder ergodox_infinity-swedish ergodox_infinity-swedish-lindhe ergodox_infinity-swissgerman ergodox_infinity-techtomas ergodox_infinity-teckinesis ergodox_infinity-tkuichooseyou ergodox_infinity-tm2030 ergodox_infinity-tonyabra_osx ergodox_infinity-townk_osx ergodox_infinity-twentylives_dvorak_with_hebrew ergodox_infinity-twey ergodox_infinity-videck ergodox_infinity-win10_writers-block ergodox_infinity-workman_osx_mdw ergodox_infinity-xyverz ergodox_infinity-yoruian ergodox_infinity-zweihander-osx four_banger-default frosty_flake-default frosty_flake-nikchi frosty_flake-tkl gh60-dbroqua gh60-dbroqua_7U gh60-default gh60-default_60_ansi gh60-default_60_ansi_split_bs_rshift gh60-default_60_iso gh60-robotmaxtron gh60-sethbc gh60-talljoe gh60-unxmaal gh60-xyverz gherkin-default gherkin-mjt gherkin-steno gherkin-talljoe gonnerd-default gonnerd-mauin gonnerd-tkl hadron-default hadron-side_numpad hhkb-blakedietz hhkb-cinaeco hhkb-dbroqua hhkb-default hhkb-jp hhkb-jp_mac hhkb-lxol hhkb-mjt hhkb-rdg_jp hhkb-sh_jp hhkb-shela hhkb-smt infinity60-default infinity60-default_60_ansi_split_bs_rshift infinity60-depariel infinity60-hasu infinity60-jpetermans infinity60-talljoe jc65-default jc65-jetpacktuxedo jd40-default jd40-vanagon jd45-blakedietz jd45-default jd45-jeebak jd45-justin jd45-mjt jd45-mjt6u kbd75-default kc60-dbroqua kc60-dbroqua_hhkb kc60-default kc60-default_60_ansi kc60-mechmerlin kc60-sgoodwin kc60-stanleylai kc60-wigguno kc60-workman-dead kc60-ws2812 kinesis-default kinesis-dvorak kinesis-milestogo kinesis-xyverz kitten_paw-default kitten_paw-ickerwx kmac-default kmac-winkeyless lets_split-OLED_sample lets_split-adam lets_split-dale lets_split-default lets_split-default_ortho_4x12 lets_split-ergodoxish lets_split-fabian lets_split-henxing lets_split-hexwire lets_split-khord lets_split-mbsurfer lets_split-mjt lets_split-piemod lets_split-smt lets_split-xk lets_split-xyverz m10a-default maxipad-default mechmini-default minidox-default minidox-that_canadian mitosis-carvac_dv mitosis-default mitosis-mjt miuni32-adam-lee miuni32-default miuni32-ht_156 nyquist-333fred nyquist-default nyquist-default_ortho_5x12 nyquist-hexwire org60-boardy org60-default orthodox-default pegasushoof-blowrak pegasushoof-default phantom-default phantom-rgbmod phantom-xyverz planck-ab planck-alexey planck-angerthosenear planck-austin planck-basic planck-bone2planck planck-brandon planck-callum planck-cbbrowne planck-chance planck-charlie planck-circuit planck-coloneljesus planck-dale planck-daniel planck-david planck-dbroqua planck-default planck-default_ortho_4x12 planck-dshields planck-dzobert planck-ergodoxish planck-espynn planck-experimental planck-gabriel planck-handwired_binaryplease planck-impossible planck-jacob planck-jeebak planck-jeremy-dev planck-jhenahan planck-joe planck-johannes planck-khord planck-kyle planck-lae3 planck-leo planck-lucas planck-lukas planck-luke planck-max planck-mitch planck-mjt planck-mjtnumsym planck-mollat planck-nico planck-originerd planck-pete planck-piemod planck-premek planck-priyadi planck-pvc planck-rai-suta planck-sgoodwin planck-smt planck-steno planck-tak3over planck-thermal_printer planck-tong92 planck-unicode planck-vifon planck-xyverz planck-yale planck-yang planck-zach preonic-0xdec preonic-CMD-Preonic preonic-dale preonic-default preonic-default_ortho_5x12 preonic-jacwib preonic-kinesis preonic-nikchi preonic-smt preonic-xyverz preonic-zach ps2avrGB-default roadkit-default roadkit-default_ortho_4x4 roadkit-flipphone roadkit-mjt roadkit-singles roadkit-singlesBrent s60_x-ansi_qwertz s60_x-bluebear s60_x-custom s60_x-dbroqua s60_x-default s60_x-hasu s60_x-hhkb s60_x-iso s60_x-jpec s60_x-plain s60_x-poker s60_x-poker_bit s60_x-poker_set s60_x-spacefn s65_x-default s65_x-iso s65_x-nall s65_x-smt satan-admiralStrokers satan-ben_iso satan-colemak satan-dbroqua satan-default satan-default_60_ansi satan-default_60_ansi_split_bs_rshift satan-default_60_iso satan-denolfe satan-iso_split_rshift satan-mark1 satan-midi satan-poker satan-rask63 satan-sethbc satan-smt satan-stanleylai satan-talljoe satan-unxmaal sixkeyboard-default subatomic-default sweet16-default tada68-default tada68-maartenwut tada68-rgb tiger_lily-default tv44-belak tv44-core tv44-default tv44-jeebak tv44-jetpacktuxedo tv44-mjt tv44-smt tv44-tong92 tv44-xyverz uk78-default vision_division-default whitefox-default whitefox-jetpacktuxedo whitefox-matt3o xd60-cheese xd60-default xd60-stanleylai xd75-default xd75-default_ortho_5x15 xd75-fabian" make diff --git a/bin/qmk b/bin/qmk index 60555d3d709..a3c1be328ad 100755 --- a/bin/qmk +++ b/bin/qmk @@ -2,52 +2,62 @@ """CLI wrapper for running QMK commands. """ import os -import subprocess import sys from importlib.util import find_spec -from time import strftime +from pathlib import Path # Add the QMK python libs to our path -script_dir = os.path.dirname(os.path.realpath(__file__)) -qmk_dir = os.path.abspath(os.path.join(script_dir, '..')) -python_lib_dir = os.path.abspath(os.path.join(qmk_dir, 'lib', 'python')) -sys.path.append(python_lib_dir) +script_dir = Path(os.path.realpath(__file__)).parent +qmk_dir = script_dir.parent +python_lib_dir = Path(qmk_dir / 'lib' / 'python').resolve() +sys.path.append(str(python_lib_dir)) -# Make sure our modules have been setup -with open(os.path.join(qmk_dir, 'requirements.txt'), 'r') as fd: - for line in fd.readlines(): - line = line.strip().replace('<', '=').replace('>', '=') - if line[0] == '#': - continue +def _check_modules(requirements): + """ Check if the modules in the given requirements.txt are available. + """ + with Path(qmk_dir / requirements).open() as fd: + for line in fd.readlines(): + line = line.strip().replace('<', '=').replace('>', '=') - if '#' in line: - line = line.split('#')[0] + if len(line) == 0 or line[0] == '#' or line.startswith('-r'): + continue - module = line.split('=')[0] if '=' in line else line + if '#' in line: + line = line.split('#')[0] + + module = dict() + module['name'] = line.split('=')[0] if '=' in line else line + module['import'] = module['name'].replace('-', '_') - if module in ['pep8-naming']: # Not every module is importable by its own name. - continue + if module['name'] == "pep8-naming": + module['import'] = "pep8ext_naming" - if not find_spec(module): - print('Could not find module %s!' % module) - print('Please run `pip3 install -r requirements.txt` to install the python dependencies.') - exit(255) + if not find_spec(module['import']): + print('Could not find module %s!' % module['name']) + print('Please run `python3 -m pip install -r %s` to install required python dependencies.' % (qmk_dir / requirements,)) + if developer: + print('You can also turn off developer mode: qmk config user.developer=None') + print() + exit(255) -# Figure out our version -# TODO(skullydazed/anyone): Find a method that doesn't involve git. This is slow in docker and on windows. -command = ['git', 'describe', '--abbrev=6', '--dirty', '--always', '--tags'] -result = subprocess.run(command, universal_newlines=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT) -if result.returncode == 0: - os.environ['QMK_VERSION'] = result.stdout.strip() -else: - os.environ['QMK_VERSION'] = 'nogit-' + strftime('%Y-%m-%d-%H:%M:%S') + '-dirty' +developer = False +# Make sure our modules have been setup +_check_modules('requirements.txt') # Setup the CLI import milc # noqa +# For developers additional modules are needed +if milc.cli.config.user.developer: + # Do not run the check for 'config', + # so users can turn off developer mode + if len(sys.argv) == 1 or (len(sys.argv) > 1 and 'config' != sys.argv[1]): + developer = True + _check_modules('requirements-dev.txt') + milc.EMOJI_LOGLEVELS['INFO'] = '{fg_blue}Ψ{style_reset_all}' diff --git a/bootloader.mk b/bootloader.mk index d615533947b..fd76446e99e 100644 --- a/bootloader.mk +++ b/bootloader.mk @@ -20,13 +20,19 @@ # Sets the bootloader defined in the keyboard's/keymap's rules.mk # Current options: # -# halfkay PJRC Teensy -# caterina Pro Micro (Sparkfun/generic) -# atmel-dfu Atmel factory DFU -# lufa-dfu LUFA DFU -# qmk-dfu QMK DFU (LUFA + blinkenlight) -# bootloadHID HIDBootFlash compatible (ATmega32A) -# USBasp USBaspLoader (ATmega328P) +# AVR: +# halfkay PJRC Teensy +# caterina Pro Micro (Sparkfun/generic) +# atmel-dfu Atmel factory DFU +# lufa-dfu LUFA DFU +# qmk-dfu QMK DFU (LUFA + blinkenlight) +# bootloadHID HIDBootFlash compatible (ATmega32A) +# USBasp USBaspLoader (ATmega328P) +# ARM: +# kiibohd Input:Club Kiibohd bootloader (only used on their boards) +# stm32duino STM32Duino (STM32F103x8) +# stm32-dfu STM32 USB DFU in ROM +# apm32-dfu APM32 USB DFU in ROM # # BOOTLOADER_SIZE can still be defined manually, but it's recommended # you add any possible configuration to this list @@ -34,30 +40,30 @@ ifeq ($(strip $(BOOTLOADER)), atmel-dfu) OPT_DEFS += -DBOOTLOADER_ATMEL_DFU OPT_DEFS += -DBOOTLOADER_DFU - ifneq (,$(filter $(MCU), at90usb646 atmega16u2 atmega16u4 atmega32u2 atmega32u4)) + ifneq (,$(filter $(MCU), at90usb162 atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647)) BOOTLOADER_SIZE = 4096 endif - ifeq ($(strip $(MCU)), at90usb1286) + ifneq (,$(filter $(MCU), at90usb1286 at90usb1287)) BOOTLOADER_SIZE = 8192 endif endif ifeq ($(strip $(BOOTLOADER)), lufa-dfu) OPT_DEFS += -DBOOTLOADER_LUFA_DFU OPT_DEFS += -DBOOTLOADER_DFU - ifneq (,$(filter $(MCU), at90usb646 atmega16u2 atmega16u4 atmega32u2 atmega32u4)) + ifneq (,$(filter $(MCU), at90usb162 atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647)) BOOTLOADER_SIZE = 4096 endif - ifeq ($(strip $(MCU)), at90usb1286) + ifneq (,$(filter $(MCU), at90usb1286 at90usb1287)) BOOTLOADER_SIZE = 8192 endif endif ifeq ($(strip $(BOOTLOADER)), qmk-dfu) OPT_DEFS += -DBOOTLOADER_QMK_DFU OPT_DEFS += -DBOOTLOADER_DFU - ifneq (,$(filter $(MCU), at90usb646 atmega16u2 atmega16u4 atmega32u2 atmega32u4)) + ifneq (,$(filter $(MCU), at90usb162 atmega16u2 atmega32u2 atmega16u4 atmega32u4 at90usb646 at90usb647)) BOOTLOADER_SIZE = 4096 endif - ifeq ($(strip $(MCU)), at90usb1286) + ifneq (,$(filter $(MCU), at90usb1286 at90usb1287)) BOOTLOADER_SIZE = 8192 endif endif @@ -82,7 +88,52 @@ ifeq ($(strip $(BOOTLOADER)), USBasp) OPT_DEFS += -DBOOTLOADER_USBASP BOOTLOADER_SIZE = 4096 endif - +ifeq ($(strip $(BOOTLOADER)), lufa-ms) + # DO NOT USE THIS BOOTLOADER IN NEW PROJECTS! + # It is extremely prone to bricking, and is only included to support existing boards. + OPT_DEFS += -DBOOTLOADER_MS + BOOTLOADER_SIZE = 6144 + FIRMWARE_FORMAT = bin +endif ifdef BOOTLOADER_SIZE OPT_DEFS += -DBOOTLOADER_SIZE=$(strip $(BOOTLOADER_SIZE)) endif + +ifeq ($(strip $(BOOTLOADER)), stm32-dfu) + OPT_DEFS += -DBOOTLOADER_STM32_DFU + + # Options to pass to dfu-util when flashing + DFU_ARGS ?= -d 0483:DF11 -a 0 -s 0x08000000:leave + DFU_SUFFIX_ARGS ?= -v 0483 -p DF11 +endif +ifeq ($(strip $(BOOTLOADER)), apm32-dfu) + OPT_DEFS += -DBOOTLOADER_APM32_DFU + + # Options to pass to dfu-util when flashing + DFU_ARGS ?= -d 314B:0106 -a 0 -s 0x08000000:leave + DFU_SUFFIX_ARGS ?= -v 314B -p 0106 +endif +ifeq ($(strip $(BOOTLOADER)), kiibohd) + OPT_DEFS += -DBOOTLOADER_KIIBOHD + ifeq ($(strip $(MCU_ORIG)), MK20DX128) + MCU_LDSCRIPT = MK20DX128BLDR4 + endif + ifeq ($(strip $(MCU_ORIG)), MK20DX256) + MCU_LDSCRIPT = MK20DX256BLDR8 + endif + + # Options to pass to dfu-util when flashing + DFU_ARGS = -d 1C11:B007 + DFU_SUFFIX_ARGS = -v 1C11 -p B007 +endif +ifeq ($(strip $(BOOTLOADER)), stm32duino) + OPT_DEFS += -DBOOTLOADER_STM32DUINO + MCU_LDSCRIPT = STM32F103x8_stm32duino_bootloader + BOARD = STM32_F103_STM32DUINO + # STM32F103 does NOT have an USB bootloader in ROM (only serial), so setting anything here does not make much sense + STM32_BOOTLOADER_ADDRESS = 0x80000000 + + # Options to pass to dfu-util when flashing + DFU_ARGS = -d 1EAF:0003 -a 2 -R + DFU_SUFFIX_ARGS = -v 1EAF -p 0003 +endif diff --git a/build_full_test.mk b/build_full_test.mk index 170020b9685..f8030cb0600 100644 --- a/build_full_test.mk +++ b/build_full_test.mk @@ -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 \ No newline at end of file +VPATH+=$(TOP_DIR)/tests/test_common diff --git a/build_json.mk b/build_json.mk index e04786144ca..6e2f9c4c8f2 100644 --- a/build_json.mk +++ b/build_json.mk @@ -21,6 +21,11 @@ else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_1)/keymap.json)","") KEYMAP_PATH := $(MAIN_KEYMAP_PATH_1) endif +# Load the keymap-level rules.mk if exists +ifneq ("$(wildcard $(KEYMAP_PATH))", "") + -include $(KEYMAP_PATH)/rules.mk +endif + # Generate the keymap.c $(KEYBOARD_OUTPUT)/src/keymap.c: $(KEYMAP_JSON) - bin/qmk json-keymap --quiet --output $(KEYMAP_C) $(KEYMAP_JSON) + bin/qmk json2c --quiet --output $(KEYMAP_C) $(KEYMAP_JSON) diff --git a/build_keyboard.mk b/build_keyboard.mk index b086420653f..366d1f5d2f9 100644 --- a/build_keyboard.mk +++ b/build_keyboard.mk @@ -16,7 +16,6 @@ include common.mk KEYBOARD_FILESAFE := $(subst /,_,$(KEYBOARD)) TARGET ?= $(KEYBOARD_FILESAFE)_$(KEYMAP) KEYBOARD_OUTPUT := $(BUILD_DIR)/obj_$(KEYBOARD_FILESAFE) -STM32_PATH := quantum/stm32 # Force expansion TARGET := $(TARGET) @@ -91,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 --escape --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 @@ -137,9 +139,7 @@ ifeq ($(strip $(CTPC)), yes) endif ifeq ($(strip $(CONVERT_TO_PROTON_C)), yes) - TARGET := $(TARGET)_proton_c - include $(STM32_PATH)/proton_c.mk - OPT_DEFS += -DCONVERT_TO_PROTON_C + include platforms/chibios/QMK_PROTON_C/convert_to_proton_c.mk endif ifneq ($(FORCE_LAYOUT),) @@ -148,12 +148,6 @@ endif include quantum/mcu_selection.mk -ifdef MCU_FAMILY - OPT_DEFS += -DQMK_STM32 - KEYBOARD_PATHS += $(STM32_PATH) -endif - - # Find all the C source files to be compiled in subfolders. KEYBOARD_SRC := @@ -231,44 +225,19 @@ endif # We can assume a ChibiOS target When MCU_FAMILY is defined since it's # not used for LUFA ifdef MCU_FAMILY - FIRMWARE_FORMAT?=bin PLATFORM=CHIBIOS + PLATFORM_KEY=chibios + FIRMWARE_FORMAT?=bin else ifdef ARM_ATSAM PLATFORM=ARM_ATSAM + PLATFORM_KEY=arm_atsam FIRMWARE_FORMAT=bin else PLATFORM=AVR + PLATFORM_KEY=avr FIRMWARE_FORMAT?=hex endif -ifeq ($(PLATFORM),CHIBIOS) - include $(TMK_PATH)/chibios.mk - OPT_OS = chibios - ifneq ("$(wildcard $(KEYBOARD_PATH_5)/bootloader_defs.h)","") - OPT_DEFS += -include $(KEYBOARD_PATH_5)/bootloader_defs.h - else ifneq ("$(wildcard $(KEYBOARD_PATH_5)/boards/$(BOARD)/bootloader_defs.h)","") - OPT_DEFS += -include $(KEYBOARD_PATH_5)/boards/$(BOARD)/bootloader_defs.h - else ifneq ("$(wildcard $(KEYBOARD_PATH_4)/bootloader_defs.h)","") - OPT_DEFS += -include $(KEYBOARD_PATH_4)/bootloader_defs.h - else ifneq ("$(wildcard $(KEYBOARD_PATH_4)/boards/$(BOARD)/bootloader_defs.h)","") - OPT_DEFS += -include $(KEYBOARD_PATH_4)/boards/$(BOARD)/bootloader_defs.h - else ifneq ("$(wildcard $(KEYBOARD_PATH_3)/bootloader_defs.h)","") - OPT_DEFS += -include $(KEYBOARD_PATH_3)/bootloader_defs.h - else ifneq ("$(wildcard $(KEYBOARD_PATH_3)/boards/$(BOARD)/bootloader_defs.h)","") - OPT_DEFS += -include $(KEYBOARD_PATH_3)/boards/$(BOARD)/bootloader_defs.h - else ifneq ("$(wildcard $(KEYBOARD_PATH_2)/bootloader_defs.h)","") - OPT_DEFS += -include $(KEYBOARD_PATH_2)/bootloader_defs.h - else ifneq ("$(wildcard $(KEYBOARD_PATH_2)/boards/$(BOARD)/bootloader_defs.h)","") - OPT_DEFS += -include $(KEYBOARD_PATH_2)/boards/$(BOARD)/bootloader_defs.h - else ifneq ("$(wildcard $(KEYBOARD_PATH_1)/bootloader_defs.h)","") - OPT_DEFS += -include $(KEYBOARD_PATH_1)/bootloader_defs.h - else ifneq ("$(wildcard $(KEYBOARD_PATH_1)/boards/$(BOARD)/bootloader_defs.h)","") - OPT_DEFS += -include $(KEYBOARD_PATH_1)/boards/$(BOARD)/bootloader_defs.h - else ifneq ("$(wildcard $(TOP_DIR)/drivers/boards/$(BOARD)/bootloader_defs.h)","") - OPT_DEFS += -include $(TOP_DIR)/drivers/boards/$(BOARD)/bootloader_defs.h - endif -endif - # Find all of the config.h files and add them to our CONFIG_H define. CONFIG_H := ifneq ("$(wildcard $(KEYBOARD_PATH_5)/config.h)","") @@ -304,10 +273,35 @@ ifneq ("$(wildcard $(KEYBOARD_PATH_5)/post_config.h)","") POST_CONFIG_H += $(KEYBOARD_PATH_5)/post_config.h endif -# Save the defines and includes here, so we don't include any keymap specific ones -PROJECT_DEFS := $(OPT_DEFS) -PROJECT_INC := $(VPATH) $(EXTRAINCDIRS) $(KEYBOARD_PATHS) -PROJECT_CONFIG := $(CONFIG_H) +# 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)","") @@ -319,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 @@ -354,23 +354,24 @@ SRC += $(TMK_COMMON_SRC) OPT_DEFS += $(TMK_COMMON_DEFS) EXTRALDFLAGS += $(TMK_COMMON_LDFLAGS) -ifeq ($(PLATFORM),AVR) -ifeq ($(strip $(PROTOCOL)), VUSB) - include $(TMK_PATH)/protocol/vusb.mk +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 else - include $(TMK_PATH)/protocol/lufa.mk -endif - include $(TMK_PATH)/avr.mk + include $(TMK_PATH)/protocol/$(PLATFORM_KEY).mk endif -ifeq ($(PLATFORM),ARM_ATSAM) - include $(TMK_PATH)/arm_atsam.mk - include $(TMK_PATH)/protocol/arm_atsam.mk -endif - -ifeq ($(PLATFORM),CHIBIOS) - include $(TMK_PATH)/protocol/chibios.mk -endif +# TODO: remove this bodge? +PROJECT_DEFS := $(OPT_DEFS) +PROJECT_INC := $(VPATH) $(EXTRAINCDIRS) $(KEYBOARD_PATHS) +PROJECT_CONFIG := $(CONFIG_H) ifeq ($(strip $(VISUALIZER_ENABLE)), yes) VISUALIZER_DIR = $(QUANTUM_DIR)/visualizer @@ -384,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) @@ -395,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))))) diff --git a/build_layout.mk b/build_layout.mk index 6e9f97dae21..4748ad483d8 100644 --- a/build_layout.mk +++ b/build_layout.mk @@ -3,8 +3,14 @@ LAYOUTS_REPOS := $(patsubst %/,%,$(sort $(dir $(wildcard $(LAYOUTS_PATH)/*/)))) define SEARCH_LAYOUTS_REPO LAYOUT_KEYMAP_PATH := $$(LAYOUTS_REPO)/$$(LAYOUT)/$$(KEYMAP) + LAYOUT_KEYMAP_JSON := $$(LAYOUT_KEYMAP_PATH)/keymap.json LAYOUT_KEYMAP_C := $$(LAYOUT_KEYMAP_PATH)/keymap.c - ifneq ("$$(wildcard $$(LAYOUT_KEYMAP_C))","") + ifneq ("$$(wildcard $$(LAYOUT_KEYMAP_JSON))","") + -include $$(LAYOUT_KEYMAP_PATH)/rules.mk + KEYMAP_C := $(KEYBOARD_OUTPUT)/src/keymap.c + KEYMAP_JSON := $$(LAYOUT_KEYMAP_JSON) + KEYMAP_PATH := $$(LAYOUT_KEYMAP_PATH) + else ifneq ("$$(wildcard $$(LAYOUT_KEYMAP_C))","") -include $$(LAYOUT_KEYMAP_PATH)/rules.mk KEYMAP_C := $$(LAYOUT_KEYMAP_C) KEYMAP_PATH := $$(LAYOUT_KEYMAP_PATH) @@ -24,4 +30,7 @@ ifneq ($(FORCE_LAYOUT),) endif endif -$(foreach LAYOUT,$(LAYOUTS),$(eval $(call SEARCH_LAYOUTS))) \ No newline at end of file +$(foreach LAYOUT,$(LAYOUTS),$(eval $(call SEARCH_LAYOUTS))) + +# Use rule from build_json.mk, but update prerequisite in case KEYMAP_JSON was updated +$(KEYBOARD_OUTPUT)/src/keymap.c: $(KEYMAP_JSON) diff --git a/build_test.mk b/build_test.mk index cac2cba5092..77c4265f937 100644 --- a/build_test.mk +++ b/build_test.mk @@ -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 @@ -41,6 +41,7 @@ all: elf VPATH += $(COMMON_VPATH) PLATFORM:=TEST +PLATFORM_KEY:=test ifneq ($(filter $(FULL_TESTS),$(TEST)),) include tests/$(TEST)/rules.mk @@ -48,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 @@ -64,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) - diff --git a/common.mk b/common.mk index aea29a7a20e..c13b5e2768a 100644 --- a/common.mk +++ b/common.mk @@ -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) diff --git a/common_features.mk b/common_features.mk index 640539fd6f4..8c9d0a90c70 100644 --- a/common_features.mk +++ b/common_features.mk @@ -13,55 +13,86 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . -SERIAL_DIR := $(QUANTUM_DIR)/serial_link SERIAL_PATH := $(QUANTUM_PATH)/serial_link -SERIAL_SRC := $(wildcard $(SERIAL_PATH)/protocol/*.c) -SERIAL_SRC += $(wildcard $(SERIAL_PATH)/system/*.c) -SERIAL_DEFS += -DSERIAL_LINK_ENABLE -COMMON_VPATH += $(SERIAL_PATH) + +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 - SRC += $(QUANTUM_DIR)/api/api_sysex.c OPT_DEFS += -DAPI_ENABLE - SRC += $(QUANTUM_DIR)/api.c MIDI_ENABLE=yes + SRC += $(QUANTUM_DIR)/api/api_sysex.c + SRC += $(QUANTUM_DIR)/api.c endif -MUSIC_ENABLE := 0 +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 := 1 + MUSIC_ENABLE = yes SRC += $(QUANTUM_DIR)/process_keycode/process_audio.c SRC += $(QUANTUM_DIR)/process_keycode/process_clicky.c - ifeq ($(PLATFORM),AVR) - SRC += $(QUANTUM_DIR)/audio/audio.c - else - SRC += $(QUANTUM_DIR)/audio/audio_arm.c - endif + 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 := 1 + MUSIC_ENABLE = yes SRC += $(QUANTUM_DIR)/process_keycode/process_midi.c endif -ifeq ($(MUSIC_ENABLE), 1) +MUSIC_ENABLE ?= no +ifeq ($(MUSIC_ENABLE), yes) SRC += $(QUANTUM_DIR)/process_keycode/process_music.c endif -ifeq ($(strip $(COMBO_ENABLE)), yes) - OPT_DEFS += -DCOMBO_ENABLE - SRC += $(QUANTUM_DIR)/process_keycode/process_combo.c -endif - ifeq ($(strip $(STENO_ENABLE)), yes) OPT_DEFS += -DSTENO_ENABLE - VIRTSER_ENABLE := yes + VIRTSER_ENABLE ?= yes SRC += $(QUANTUM_DIR)/process_keycode/process_steno.c endif @@ -69,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) @@ -80,167 +112,239 @@ ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes) SRC += $(QUANTUM_DIR)/pointing_device.c endif -ifeq ($(strip $(UCIS_ENABLE)), yes) - OPT_DEFS += -DUCIS_ENABLE - UNICODE_COMMON = yes - SRC += $(QUANTUM_DIR)/process_keycode/process_ucis.c +VALID_EEPROM_DRIVER_TYPES := vendor custom transient i2c spi +EEPROM_DRIVER ?= vendor +ifeq ($(filter $(EEPROM_DRIVER),$(VALID_EEPROM_DRIVER_TYPES)),) + $(error EEPROM_DRIVER="$(EEPROM_DRIVER)" is not a valid EEPROM driver) +else + OPT_DEFS += -DEEPROM_ENABLE + ifeq ($(strip $(EEPROM_DRIVER)), custom) + OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_CUSTOM + COMMON_VPATH += $(DRIVER_PATH)/eeprom + SRC += eeprom_driver.c + else ifeq ($(strip $(EEPROM_DRIVER)), i2c) + OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_I2C + COMMON_VPATH += $(DRIVER_PATH)/eeprom + QUANTUM_LIB_SRC += i2c_master.c + SRC += eeprom_driver.c eeprom_i2c.c + else ifeq ($(strip $(EEPROM_DRIVER)), spi) + OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_SPI + COMMON_VPATH += $(DRIVER_PATH)/eeprom + QUANTUM_LIB_SRC += spi_master.c + SRC += eeprom_driver.c eeprom_spi.c + else ifeq ($(strip $(EEPROM_DRIVER)), transient) + OPT_DEFS += -DEEPROM_DRIVER -DEEPROM_TRANSIENT + COMMON_VPATH += $(DRIVER_PATH)/eeprom + SRC += eeprom_driver.c eeprom_transient.c + else ifeq ($(strip $(EEPROM_DRIVER)), vendor) + OPT_DEFS += -DEEPROM_VENDOR + ifeq ($(PLATFORM),AVR) + # Automatically provided by avr-libc, nothing required + else ifeq ($(PLATFORM),CHIBIOS) + ifeq ($(MCU_SERIES), STM32F3xx) + SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c + SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c + OPT_DEFS += -DEEPROM_EMU_STM32F303xC + OPT_DEFS += -DSTM32_EEPROM_ENABLE + else ifeq ($(MCU_SERIES), STM32F1xx) + SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c + SRC += $(PLATFORM_COMMON_DIR)/flash_stm32.c + OPT_DEFS += -DEEPROM_EMU_STM32F103xB + OPT_DEFS += -DSTM32_EEPROM_ENABLE + else ifeq ($(MCU_SERIES)_$(MCU_LDSCRIPT), STM32F0xx_STM32F072xB) + SRC += $(PLATFORM_COMMON_DIR)/eeprom_stm32.c + 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 + SRC += eeprom_driver.c eeprom_stm32_L0_L1.c + else + # This will effectively work the same as "transient" if not supported by the chip + SRC += $(PLATFORM_COMMON_DIR)/eeprom_teensy.c + endif + else ifeq ($(PLATFORM),ARM_ATSAM) + SRC += $(PLATFORM_COMMON_DIR)/eeprom.c + else ifeq ($(PLATFORM),TEST) + SRC += $(PLATFORM_COMMON_DIR)/eeprom.c + endif + endif endif -ifeq ($(strip $(UNICODEMAP_ENABLE)), yes) - OPT_DEFS += -DUNICODEMAP_ENABLE - UNICODE_COMMON = yes - SRC += $(QUANTUM_DIR)/process_keycode/process_unicodemap.c -endif +RGBLIGHT_ENABLE ?= no +VALID_RGBLIGHT_TYPES := WS2812 APA102 custom -ifeq ($(strip $(UNICODE_ENABLE)), yes) - OPT_DEFS += -DUNICODE_ENABLE - UNICODE_COMMON = yes - SRC += $(QUANTUM_DIR)/process_keycode/process_unicode.c -endif - -ifeq ($(strip $(UNICODE_COMMON)), yes) - SRC += $(QUANTUM_DIR)/process_keycode/process_unicode_common.c +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 - LED_BREATHING_TABLE = 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 - WS2812_DRIVER_REQUIRED = 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 + 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 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 - OPT_DEFS += -DLED_MATRIX_ENABLE -DBACKLIGHT_ENABLE -DBACKLIGHT_CUSTOM_DRIVER + BACKLIGHT_ENABLE = yes + BACKLIGHT_DRIVER = custom + OPT_DEFS += -DLED_MATRIX_ENABLE 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 + CIE1931_CURVE := yes + RGB_KEYCODES_ENABLE := yes -ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes) - RGB_MATRIX_ENABLE = IS31FL3731 -endif + ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3731) + OPT_DEFS += -DIS31FL3731 -DSTM32_I2C -DHAL_USE_I2C=TRUE + COMMON_VPATH += $(DRIVER_PATH)/issi + SRC += is31fl3731.c + QUANTUM_LIB_SRC += i2c_master.c + endif -ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3731) - OPT_DEFS += -DIS31FL3731 -DSTM32_I2C -DHAL_USE_I2C=TRUE - COMMON_VPATH += $(DRIVER_PATH)/issi - SRC += is31fl3731.c - QUANTUM_LIB_SRC += i2c_master.c -endif + ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3733) + OPT_DEFS += -DIS31FL3733 -DSTM32_I2C -DHAL_USE_I2C=TRUE + COMMON_VPATH += $(DRIVER_PATH)/issi + SRC += is31fl3733.c + QUANTUM_LIB_SRC += i2c_master.c + endif -ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3733) - OPT_DEFS += -DIS31FL3733 -DSTM32_I2C -DHAL_USE_I2C=TRUE - COMMON_VPATH += $(DRIVER_PATH)/issi - SRC += is31fl3733.c - QUANTUM_LIB_SRC += i2c_master.c -endif + ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3737) + OPT_DEFS += -DIS31FL3737 -DSTM32_I2C -DHAL_USE_I2C=TRUE + COMMON_VPATH += $(DRIVER_PATH)/issi + SRC += is31fl3737.c + QUANTUM_LIB_SRC += i2c_master.c + endif -ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3737) - OPT_DEFS += -DIS31FL3737 -DSTM32_I2C -DHAL_USE_I2C=TRUE - COMMON_VPATH += $(DRIVER_PATH)/issi - SRC += is31fl3737.c - QUANTUM_LIB_SRC += i2c_master.c -endif + ifeq ($(strip $(RGB_MATRIX_DRIVER)), IS31FL3741) + OPT_DEFS += -DIS31FL3741 -DSTM32_I2C -DHAL_USE_I2C=TRUE + COMMON_VPATH += $(DRIVER_PATH)/issi + SRC += is31fl3741.c + QUANTUM_LIB_SRC += i2c_master.c + endif -ifeq ($(strip $(RGB_MATRIX_ENABLE)), WS2812) - OPT_DEFS += -DWS2812 - WS2812_DRIVER_REQUIRED = yes -endif + ifeq ($(strip $(RGB_MATRIX_DRIVER)), WS2812) + OPT_DEFS += -DWS2812 + WS2812_DRIVER_REQUIRED := yes + endif -ifeq ($(strip $(RGB_MATRIX_CUSTOM_KB)), yes) - OPT_DEFS += -DRGB_MATRIX_CUSTOM_KB -endif + ifeq ($(strip $(RGB_MATRIX_DRIVER)), APA102) + OPT_DEFS += -DAPA102 + APA102_DRIVER_REQUIRED := yes + endif -ifeq ($(strip $(RGB_MATRIX_CUSTOM_USER)), yes) - OPT_DEFS += -DRGB_MATRIX_CUSTOM_USER + 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 + endif endif ifeq ($(strip $(RGB_KEYCODES_ENABLE)), yes) SRC += $(QUANTUM_DIR)/process_keycode/process_rgb.c endif -ifeq ($(strip $(TAP_DANCE_ENABLE)), yes) - OPT_DEFS += -DTAP_DANCE_ENABLE - SRC += $(QUANTUM_DIR)/process_keycode/process_tap_dance.c -endif - -ifeq ($(strip $(KEY_LOCK_ENABLE)), yes) - OPT_DEFS += -DKEY_LOCK_ENABLE - SRC += $(QUANTUM_DIR)/process_keycode/process_key_lock.c -endif - ifeq ($(strip $(PRINTING_ENABLE)), yes) OPT_DEFS += -DPRINTING_ENABLE SRC += $(QUANTUM_DIR)/process_keycode/process_printer.c SRC += $(TMK_DIR)/protocol/serial_uart.c endif -ifeq ($(strip $(AUTO_SHIFT_ENABLE)), yes) - OPT_DEFS += -DAUTO_SHIFT_ENABLE - SRC += $(QUANTUM_DIR)/process_keycode/process_auto_shift.c - ifeq ($(strip $(AUTO_SHIFT_MODIFIERS)), yes) - OPT_DEFS += -DAUTO_SHIFT_MODIFIERS - endif -endif - ifeq ($(strip $(SERIAL_LINK_ENABLE)), yes) + SERIAL_SRC := $(wildcard $(SERIAL_PATH)/protocol/*.c) + SERIAL_SRC += $(wildcard $(SERIAL_PATH)/system/*.c) + SERIAL_DEFS += -DSERIAL_LINK_ENABLE + COMMON_VPATH += $(SERIAL_PATH) + SRC += $(patsubst $(QUANTUM_PATH)/%,%,$(SERIAL_SRC)) OPT_DEFS += $(SERIAL_DEFS) VAPTH += $(SERIAL_PATH) endif -ifneq ($(strip $(VARIABLE_TRACE)),) +VARIABLE_TRACE ?= no +ifneq ($(strip $(VARIABLE_TRACE)),no) SRC += $(QUANTUM_DIR)/variable_trace.c OPT_DEFS += -DNUM_TRACED_VARIABLES=$(strip $(VARIABLE_TRACE)) -ifneq ($(strip $(MAX_VARIABLE_TRACE_SIZE)),) - OPT_DEFS += -DMAX_VARIABLE_TRACE_SIZE=$(strip $(MAX_VARIABLE_TRACE_SIZE)) -endif + ifneq ($(strip $(MAX_VARIABLE_TRACE_SIZE)),) + OPT_DEFS += -DMAX_VARIABLE_TRACE_SIZE=$(strip $(MAX_VARIABLE_TRACE_SIZE)) + endif endif ifeq ($(strip $(LCD_ENABLE)), yes) - CIE1931_CURVE = yes + CIE1931_CURVE := yes endif # backward compat ifeq ($(strip $(BACKLIGHT_CUSTOM_DRIVER)), yes) - BACKLIGHT_DRIVER = custom + BACKLIGHT_DRIVER := custom endif -VALID_BACKLIGHT_TYPES := pwm software custom +VALID_BACKLIGHT_TYPES := pwm timer software custom BACKLIGHT_ENABLE ?= no BACKLIGHT_DRIVER ?= pwm @@ -249,25 +353,19 @@ ifeq ($(strip $(BACKLIGHT_ENABLE)), yes) $(error BACKLIGHT_DRIVER="$(BACKLIGHT_DRIVER)" is not a valid backlight type) endif - ifeq ($(strip $(VISUALIZER_ENABLE)), yes) - CIE1931_CURVE = yes - endif - COMMON_VPATH += $(QUANTUM_DIR)/backlight SRC += $(QUANTUM_DIR)/backlight/backlight.c + SRC += $(QUANTUM_DIR)/process_keycode/process_backlight.c OPT_DEFS += -DBACKLIGHT_ENABLE - ifeq ($(strip $(BACKLIGHT_DRIVER)), software) - SRC += $(QUANTUM_DIR)/backlight/backlight_soft.c + ifeq ($(strip $(BACKLIGHT_DRIVER)), custom) + OPT_DEFS += -DBACKLIGHT_CUSTOM_DRIVER else - ifeq ($(strip $(BACKLIGHT_DRIVER)), custom) - OPT_DEFS += -DBACKLIGHT_CUSTOM_DRIVER - endif - - ifeq ($(PLATFORM),AVR) - SRC += $(QUANTUM_DIR)/backlight/backlight_avr.c + SRC += $(QUANTUM_DIR)/backlight/backlight_driver_common.c + ifeq ($(strip $(BACKLIGHT_DRIVER)), pwm) + SRC += $(QUANTUM_DIR)/backlight/backlight_$(PLATFORM_KEY).c else - SRC += $(QUANTUM_DIR)/backlight/backlight_arm.c + SRC += $(QUANTUM_DIR)/backlight/backlight_$(strip $(BACKLIGHT_DRIVER)).c endif endif endif @@ -280,10 +378,18 @@ ifeq ($(strip $(WS2812_DRIVER_REQUIRED)), yes) $(error WS2812_DRIVER="$(WS2812_DRIVER)" is not a valid WS2812 driver) endif + OPT_DEFS += -DWS2812_DRIVER_$(strip $(shell echo $(WS2812_DRIVER) | tr '[:lower:]' '[:upper:]')) + ifeq ($(strip $(WS2812_DRIVER)), bitbang) SRC += ws2812.c else SRC += ws2812_$(strip $(WS2812_DRIVER)).c + + ifeq ($(strip $(PLATFORM)), CHIBIOS) + ifeq ($(strip $(WS2812_DRIVER)), pwm) + OPT_DEFS += -DSTM32_DMA_REQUIRED=TRUE + endif + endif endif # add extra deps @@ -292,14 +398,18 @@ ifeq ($(strip $(WS2812_DRIVER_REQUIRED)), yes) endif endif -ifeq ($(strip $(CIE1931_CURVE)), yes) - OPT_DEFS += -DUSE_CIE1931_CURVE - LED_TABLES = yes +ifeq ($(strip $(APA102_DRIVER_REQUIRED)), yes) + COMMON_VPATH += $(DRIVER_PATH)/apa102 + SRC += apa102.c endif -ifeq ($(strip $(LED_BREATHING_TABLE)), yes) - OPT_DEFS += -DUSE_LED_BREATHING_TABLE - LED_TABLES = yes +ifeq ($(strip $(VISUALIZER_ENABLE)), yes) + CIE1931_CURVE := yes +endif + +ifeq ($(strip $(CIE1931_CURVE)), yes) + OPT_DEFS += -DUSE_CIE1931_CURVE + LED_TABLES := yes endif ifeq ($(strip $(LED_TABLES)), yes) @@ -316,16 +426,115 @@ ifeq ($(strip $(USB_HID_ENABLE)), yes) include $(TMK_DIR)/protocol/usb_hid.mk endif +ifeq ($(strip $(WPM_ENABLE)), yes) + SRC += $(QUANTUM_DIR)/wpm.c + OPT_DEFS += -DWPM_ENABLE +endif + ifeq ($(strip $(ENCODER_ENABLE)), yes) SRC += $(QUANTUM_DIR)/encoder.c OPT_DEFS += -DENCODER_ENABLE endif +ifeq ($(strip $(VELOCIKEY_ENABLE)), yes) + OPT_DEFS += -DVELOCIKEY_ENABLE + SRC += $(QUANTUM_DIR)/velocikey.c +endif + +ifeq ($(strip $(VIA_ENABLE)), yes) + DYNAMIC_KEYMAP_ENABLE := yes + RAW_ENABLE := yes + BOOTMAGIC_ENABLE := lite + SRC += $(QUANTUM_DIR)/via.c + OPT_DEFS += -DVIA_ENABLE +endif + +ifeq ($(strip $(DYNAMIC_KEYMAP_ENABLE)), yes) + OPT_DEFS += -DDYNAMIC_KEYMAP_ENABLE + SRC += $(QUANTUM_DIR)/dynamic_keymap.c +endif + +ifeq ($(strip $(DIP_SWITCH_ENABLE)), yes) + OPT_DEFS += -DDIP_SWITCH_ENABLE + SRC += $(QUANTUM_DIR)/dip_switch.c +endif + +VALID_CUSTOM_MATRIX_TYPES:= yes lite no + +CUSTOM_MATRIX ?= no + +ifneq ($(strip $(CUSTOM_MATRIX)), yes) + ifeq ($(filter $(CUSTOM_MATRIX),$(VALID_CUSTOM_MATRIX_TYPES)),) + $(error CUSTOM_MATRIX="$(CUSTOM_MATRIX)" is not a valid custom matrix type) + endif + + # Include common stuff for all non custom matrix users + QUANTUM_SRC += $(QUANTUM_DIR)/matrix_common.c + + # if 'lite' then skip the actual matrix implementation + ifneq ($(strip $(CUSTOM_MATRIX)), lite) + # Include the standard or split matrix code if needed + ifeq ($(strip $(SPLIT_KEYBOARD)), yes) + QUANTUM_SRC += $(QUANTUM_DIR)/split_common/matrix.c + else + QUANTUM_SRC += $(QUANTUM_DIR)/matrix.c + endif + endif +endif + +# Support for translating old names to new names: +ifeq ($(strip $(DEBOUNCE_TYPE)),sym_g) + DEBOUNCE_TYPE:=sym_defer_g +else ifeq ($(strip $(DEBOUNCE_TYPE)),eager_pk) + DEBOUNCE_TYPE:=sym_eager_pk +else ifeq ($(strip $(DEBOUNCE_TYPE)),sym_pk) + DEBOUNCE_TYPE:=sym_defer_pk +else ifeq ($(strip $(DEBOUNCE_TYPE)),eager_pr) + DEBOUNCE_TYPE:=sym_eager_pr +endif + +DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce +# Debounce Modules. Set DEBOUNCE_TYPE=custom if including one manually. +DEBOUNCE_TYPE?= sym_defer_g +ifneq ($(strip $(DEBOUNCE_TYPE)), custom) + QUANTUM_SRC += $(DEBOUNCE_DIR)/$(strip $(DEBOUNCE_TYPE)).c +endif + +ifeq ($(strip $(SPLIT_KEYBOARD)), yes) + POST_CONFIG_H += $(QUANTUM_DIR)/split_common/post_config.h + OPT_DEFS += -DSPLIT_KEYBOARD + + # Include files used by all split keyboards + QUANTUM_SRC += $(QUANTUM_DIR)/split_common/split_util.c + + # Determine which (if any) transport files are required + ifneq ($(strip $(SPLIT_TRANSPORT)), custom) + 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) + 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 + QUANTUM_LIB_SRC += serial_$(strip $(SERIAL_DRIVER)).c + endif + endif + COMMON_VPATH += $(QUANTUM_PATH)/split_common +endif + HAPTIC_ENABLE ?= no ifneq ($(strip $(HAPTIC_ENABLE)),no) - COMMON_VPATH += $(DRIVER_PATH)/haptic - SRC += haptic.c - OPT_DEFS += -DHAPTIC_ENABLE + COMMON_VPATH += $(DRIVER_PATH)/haptic + SRC += haptic.c + OPT_DEFS += -DHAPTIC_ENABLE endif ifneq ($(filter DRV2605L, $(HAPTIC_ENABLE)), ) @@ -344,63 +553,6 @@ ifeq ($(strip $(HD44780_ENABLE)), yes) OPT_DEFS += -DHD44780_ENABLE endif -ifeq ($(strip $(VELOCIKEY_ENABLE)), yes) - OPT_DEFS += -DVELOCIKEY_ENABLE - SRC += $(QUANTUM_DIR)/velocikey.c -endif - -ifeq ($(strip $(DYNAMIC_KEYMAP_ENABLE)), yes) - OPT_DEFS += -DDYNAMIC_KEYMAP_ENABLE - SRC += $(QUANTUM_DIR)/dynamic_keymap.c -endif - -ifeq ($(strip $(LEADER_ENABLE)), yes) - SRC += $(QUANTUM_DIR)/process_keycode/process_leader.c - OPT_DEFS += -DLEADER_ENABLE -endif - -include $(DRIVER_PATH)/qwiic/qwiic.mk - -QUANTUM_SRC:= \ - $(QUANTUM_DIR)/quantum.c \ - $(QUANTUM_DIR)/keymap_common.c \ - $(QUANTUM_DIR)/keycode_config.c - -# Include the standard or split matrix code if needed -ifneq ($(strip $(CUSTOM_MATRIX)), yes) - ifeq ($(strip $(SPLIT_KEYBOARD)), yes) - QUANTUM_SRC += $(QUANTUM_DIR)/split_common/matrix.c - else - QUANTUM_SRC += $(QUANTUM_DIR)/matrix.c - endif -endif - -DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce -# Debounce Modules. Set DEBOUNCE_TYPE=custom if including one manually. -DEBOUNCE_TYPE?= sym_g -ifneq ($(strip $(DEBOUNCE_TYPE)), custom) - QUANTUM_SRC += $(DEBOUNCE_DIR)/$(strip $(DEBOUNCE_TYPE)).c -endif - -ifeq ($(strip $(SPLIT_KEYBOARD)), yes) - POST_CONFIG_H += $(QUANTUM_DIR)/split_common/post_config.h - OPT_DEFS += -DSPLIT_KEYBOARD - - # Include files used by all split keyboards - QUANTUM_SRC += $(QUANTUM_DIR)/split_common/split_util.c - - # Determine which (if any) transport files are required - ifneq ($(strip $(SPLIT_TRANSPORT)), custom) - QUANTUM_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. - QUANTUM_LIB_SRC += $(QUANTUM_DIR)/split_common/serial.c \ - i2c_master.c \ - i2c_slave.c - endif - COMMON_VPATH += $(QUANTUM_PATH)/split_common -endif - ifeq ($(strip $(OLED_DRIVER_ENABLE)), yes) OPT_DEFS += -DOLED_DRIVER_ENABLE COMMON_VPATH += $(DRIVER_PATH)/oled @@ -408,10 +560,34 @@ ifeq ($(strip $(OLED_DRIVER_ENABLE)), yes) SRC += oled_driver.c endif +include $(DRIVER_PATH)/qwiic/qwiic.mk + +ifeq ($(strip $(UCIS_ENABLE)), yes) + OPT_DEFS += -DUCIS_ENABLE + UNICODE_COMMON := yes + SRC += $(QUANTUM_DIR)/process_keycode/process_ucis.c +endif + +ifeq ($(strip $(UNICODEMAP_ENABLE)), yes) + OPT_DEFS += -DUNICODEMAP_ENABLE + UNICODE_COMMON := yes + SRC += $(QUANTUM_DIR)/process_keycode/process_unicodemap.c +endif + +ifeq ($(strip $(UNICODE_ENABLE)), yes) + OPT_DEFS += -DUNICODE_ENABLE + UNICODE_COMMON := yes + SRC += $(QUANTUM_DIR)/process_keycode/process_unicode.c +endif + +ifeq ($(strip $(UNICODE_COMMON)), yes) + SRC += $(QUANTUM_DIR)/process_keycode/process_unicode_common.c +endif + SPACE_CADET_ENABLE ?= yes ifeq ($(strip $(SPACE_CADET_ENABLE)), yes) - SRC += $(QUANTUM_DIR)/process_keycode/process_space_cadet.c - OPT_DEFS += -DSPACE_CADET_ENABLE + SRC += $(QUANTUM_DIR)/process_keycode/process_space_cadet.c + OPT_DEFS += -DSPACE_CADET_ENABLE endif MAGIC_ENABLE ?= yes @@ -420,12 +596,81 @@ ifeq ($(strip $(MAGIC_ENABLE)), yes) OPT_DEFS += -DMAGIC_KEYCODE_ENABLE endif +GRAVE_ESC_ENABLE ?= yes +ifeq ($(strip $(GRAVE_ESC_ENABLE)), yes) + SRC += $(QUANTUM_DIR)/process_keycode/process_grave_esc.c + OPT_DEFS += -DGRAVE_ESC_ENABLE +endif + ifeq ($(strip $(DYNAMIC_MACRO_ENABLE)), yes) SRC += $(QUANTUM_DIR)/process_keycode/process_dynamic_macro.c OPT_DEFS += -DDYNAMIC_MACRO_ENABLE endif -ifeq ($(strip $(DIP_SWITCH_ENABLE)), yes) - SRC += $(QUANTUM_DIR)/dip_switch.c - OPT_DEFS += -DDIP_SWITCH_ENABLE +ifeq ($(strip $(COMBO_ENABLE)), yes) + SRC += $(QUANTUM_DIR)/process_keycode/process_combo.c + OPT_DEFS += -DCOMBO_ENABLE endif + +ifeq ($(strip $(TAP_DANCE_ENABLE)), yes) + SRC += $(QUANTUM_DIR)/process_keycode/process_tap_dance.c + OPT_DEFS += -DTAP_DANCE_ENABLE +endif + +ifeq ($(strip $(KEY_LOCK_ENABLE)), yes) + SRC += $(QUANTUM_DIR)/process_keycode/process_key_lock.c + OPT_DEFS += -DKEY_LOCK_ENABLE +endif + +ifeq ($(strip $(LEADER_ENABLE)), yes) + SRC += $(QUANTUM_DIR)/process_keycode/process_leader.c + OPT_DEFS += -DLEADER_ENABLE +endif + +ifeq ($(strip $(AUTO_SHIFT_ENABLE)), yes) + SRC += $(QUANTUM_DIR)/process_keycode/process_auto_shift.c + OPT_DEFS += -DAUTO_SHIFT_ENABLE + ifeq ($(strip $(AUTO_SHIFT_MODIFIERS)), yes) + OPT_DEFS += -DAUTO_SHIFT_MODIFIERS + endif +endif + +JOYSTICK_ENABLE ?= no +ifneq ($(strip $(JOYSTICK_ENABLE)), no) + OPT_DEFS += -DJOYSTICK_ENABLE + SRC += $(QUANTUM_DIR)/process_keycode/process_joystick.c + SRC += $(QUANTUM_DIR)/joystick.c +endif + +ifeq ($(strip $(JOYSTICK_ENABLE)), analog) + OPT_DEFS += -DANALOG_JOYSTICK_ENABLE + SRC += analog.c +endif + +ifeq ($(strip $(JOYSTICK_ENABLE)), digital) + OPT_DEFS += -DDIGITAL_JOYSTICK_ENABLE +endif + +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 \ No newline at end of file diff --git a/data/mappings/info_config.json b/data/mappings/info_config.json new file mode 100644 index 00000000000..b949b13320d --- /dev/null +++ b/data/mappings/info_config.json @@ -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: + # : {"info_key": , ["value_type": ], ["to_json": ], ["to_c": ]} + # 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"} +} diff --git a/data/mappings/info_rules.json b/data/mappings/info_rules.json new file mode 100644 index 00000000000..97f772c4d5b --- /dev/null +++ b/data/mappings/info_rules.json @@ -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: + # : {"info_key": , ["value_type": ], ["to_json": ], ["to_c": ]} + # 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}, +} diff --git a/data/schemas/api_keyboard.jsonschema b/data/schemas/api_keyboard.jsonschema new file mode 100644 index 00000000000..d570ee99908 --- /dev/null +++ b/data/schemas/api_keyboard.jsonschema @@ -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" + } + } + ] +} diff --git a/data/schemas/false.jsonschema b/data/schemas/false.jsonschema new file mode 100644 index 00000000000..c508d5366f7 --- /dev/null +++ b/data/schemas/false.jsonschema @@ -0,0 +1 @@ +false diff --git a/data/schemas/keyboard.jsonschema b/data/schemas/keyboard.jsonschema new file mode 100644 index 00000000000..ec03a8828be --- /dev/null +++ b/data/schemas/keyboard.jsonschema @@ -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}$" + } + } + } + } +} diff --git a/data/schemas/true.jsonschema b/data/schemas/true.jsonschema new file mode 100644 index 00000000000..27ba77ddaf6 --- /dev/null +++ b/data/schemas/true.jsonschema @@ -0,0 +1 @@ +true diff --git a/disable_features.mk b/disable_features.mk new file mode 100644 index 00000000000..84d8316eac9 --- /dev/null +++ b/disable_features.mk @@ -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))) diff --git a/docs/ChangeLog/20190830.md b/docs/ChangeLog/20190830.md index bd2d5e19c34..ab6e28c4d90 100644 --- a/docs/ChangeLog/20190830.md +++ b/docs/ChangeLog/20190830.md @@ -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 - diff --git a/docs/ChangeLog/20200229.md b/docs/ChangeLog/20200229.md new file mode 100644 index 00000000000..398fe01c0d0 --- /dev/null +++ b/docs/ChangeLog/20200229.md @@ -0,0 +1,75 @@ +# QMK Breaking Change - 2020 Feb 29 Changelog + +Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps. + + +## Update ChibiOS/ChibiOS-Contrib/uGFX submodules + +* General Notes + * A `make git-submodule` may be required after pulling the latest QMK firmware code to update affected submodules to the upgraded revisions + * Enabling link-time-optimization (`LINK_TIME_OPTIMIZATION_ENABLE = yes`) should work on a lot more boards +* Upgrade to ChibiOS ver19.1.3 + * This will allow QMK to update to upstream ChibiOS a lot easier -- the old version was ~2 years out of date. Automated update scripts have been made available to simplify future upgrades. + * Includes improved MCU support and bugfixes + * ChibiOS revision is now included in Command output + * Timers should now be more accurate +* Upgrade to newer ChibiOS-Contrib + * Also includes improved MCU support and bugfixes + * ChibiOS-Contrib revision is now included in Command output +* Upgrade to newer uGFX + * Required in order to support updated ChibiOS + + +## Fix ChibiOS timer overflow for 16-bit SysTick devices + +* On 16-bit SysTick devices, the timer subsystem in QMK was incorrectly dealing with overflow. + * When running at a 100000 SysTick frequency (possible on 16-bit devices, but uncommon), this overflow would occur after 0.65 seconds. +* Timers are now correctly handling this overflow case and timing should now be correct on ChibiOS/ARM. + + +## Update LUFA submodule + +* Updates the LUFA submodule to include updates from upstream (abcminiuser/lufa) +* Includes some cleanup for QMK DFU generation + + +## Encoder flip + +* Flips the encoder direction so that `clockwise == true` is for actually turning the knob clockwise +* Adds `ENCODER_DIRECTION_FLIP` define, so that reversing the expected dirction is simple for users. +* Cleans up documentation page for encoders + + +## Adding support for `BACKLIGHT_ON_STATE` for hardware PWM backlight + +* Previously, the define only affected software PWM, and hardware PWM always assumed an N-channel MOSFET. +* The hardware PWM backlight setup has been updated to respect this option. +* The default "on" state has been changed to `1` - **this impacts all keyboards using software PWM backlight that do not define it explicitly**. If your keyboard's backlight is acting strange, it may have a P-channel MOSFET, and will need to have `#define BACKLIGHT_ON_STATE 0` added to the keyboard-level `config.h`. Please see the PR for more detailed information. + + +## Migrating `ACTION_LAYER_TAP_KEY()` entries in `fn_actions` to `LT()` keycodes + +* `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()` +* The end result of removing this obsolete feature should result in a decent reduction in firmware size and code complexity +* All keymaps affected are recommended to switch away from `fn_actions` in favour of the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features + + +## Moving backlight keycode handling to `process_keycode/` + +* This refactors the backlight keycode logic to be clearer and more modular. +* All backlight-related keycodes are now actioned in a single file. +* The `ACTION_BACKLIGHT_*` macros have also been deleted. If you are still using these in a `fn_actions[]` block, please switch to using the backlight keycodes or functions directly. + + +## Refactor Planck keymaps to use Layout Macros + +* Refactor Planck keymaps to use layout macros instead of raw matrix assignments +* Makes keymaps revision-agnostic +* Should reduce noise and errors in Travis CI logs + + +## GON NerD codebase refactor + +* Splits the codebase for GON NerD 60 and NerdD TKL PCBs into two separate directories. +* If your keymap is for a NerD 60 PCB, your `make` command is now `make gon/nerd60:`. +* If your keymap is for a NerD TKL PCB, your `make` command is now `make gon/nerdtkl:`. diff --git a/docs/ChangeLog/20200530.md b/docs/ChangeLog/20200530.md new file mode 100644 index 00000000000..9def9ae1235 --- /dev/null +++ b/docs/ChangeLog/20200530.md @@ -0,0 +1,239 @@ +# QMK Breaking Change - 2020 May 30 Changelog + +Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps. + +The list of changes follows. + + +## Core Changes + +### Converting V-USB usbdrv to a submodule + +[#8321](https://github.com/qmk/qmk_firmware/pull/8321) and [qmk_compiler#62](https://github.com/qmk/qmk_compiler/pull/62). + +These PRs move the V-USB driver code out of the qmk_firmware repository and into a submodule pointed at https://github.com/obdev/v-usb. This will make it easier to update the codebase if needed, while applying any potential QMK-specific modifications by forking it to the QMK GitHub organization. + +### Unify Tap Hold functions and documentation + +[#8348](https://github.com/qmk/qmk_firmware/pull/8348) + +Updates all of the per key tap-hold functions to pass the `keyrecord_t` structure, and include documentation changes. + +Any remaining versions or code outside of the main repo will need to be converted: +| Old function | New Function | +|------------------------------------------------------|---------------------------------------------------------------------------| +|`uint16_t get_tapping_term(uint16_t keycode)` |`uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record)` | +|`bool get_ignore_mod_tap_interrupt(uint16_t keycode)` |`bool get_ignore_mod_tap_interrupt(uint16_t keycode, keyrecord_t *record)` | + +### Python Required In The Build Process + +[#9000](https://github.com/qmk/qmk_firmware/pull/9000) + +This is the last release of QMK that will work without having Python 3.6 (or later) installed. If your environment is not fully setup you will get a warning instructing you to set it up. + +After the next breaking change you will not be able to build if `bin/qmk hello` does not work. + +### Upgrade from tinyprintf to mpaland/printf + +[#8269](https://github.com/qmk/qmk_firmware/pull/8269) + +- Provides debug functionality on ChibiOS/ARM that is more compliant than previous integrations. +- Less maintenence, fewer QMK customisations, and allows QMK to sidestep previous compile and runtime issues. +- A `make git-submodule` may be required after pulling the latest QMK Firmware code to update to the new dependency. + +### Fixed RGB_DISABLE_AFTER_TIMEOUT to be seconds based & small internals cleanup + +[#6480](https://github.com/qmk/qmk_firmware/pull/6480) + +- Changes `RGB_DISABLE_AFTER_TIMEOUT` to be based on milliseconds instead of ticks. +- Includes a code cleanup, resulting in a savings of 100 bytes, depending on features used. +- Fixed issues with timeouts / suspending at the wrong time not turning off all LEDs in some cases. + +The `RGB_DISABLE_AFTER_TIMEOUT` definition is now deprecated, and has been superseded by `RGB_DISABLE_TIMEOUT`. To use the new definition, rename `RGB_DISABLE_AFTER_TIMEOUT` to `RGB_DISABLE_TIMEOUT` in your `config.h` file, and multiply the value set by 1200. + +Before: `#define RGB_DISABLE_AFTER_TIMEOUT 100` +After: `#define RGB_DISABLE_TIMEOUT 120000` + +### Switch to qmk forks for everything + +[#9019](https://github.com/qmk/qmk_firmware/pull/9019) + +Fork all QMK submodules to protect against upstream repositories disappearing. + +### code cleanup regarding deprecated macro PLAY_NOTE_ARRAY by replacing it with PLAY_SONG + +[#8484](https://github.com/qmk/qmk_firmware/pull/8484) + +Removes the deprecated `PLAY_NOTE_ARRAY` macro. References to it are replaced with `PLAY_SONG`, which references the same function. + +### fixing wrong configuration of AUDIO feature + +[#8903](https://github.com/qmk/qmk_firmware/pull/8903) and [#8974](https://github.com/qmk/qmk_firmware/pull/8974) + +`audio_avr.c` does not default to any pin; there has to be a #define XX_AUDIO in config.h at some level for Audio to actually work. Otherwise, the Audio code ends up cluttering the firmware, possibly breaking builds because the maximum allowed firmware size is exceeded. + +These changes fix this by disabling Audio on keyboards that have the feature misconfigured, and therefore non-functional. + +Also, add a compile-time error to alert the user to a missing pin-configuration (on AVR boards) when `AUDIO_ENABLE = yes` is set. + + +## Keyboard Refactors + +### Migrating Lily58 to use split_common + +[#6260](https://github.com/qmk/qmk_firmware/pull/6260) + +Modifies the default firmware for Lily58 to use the `split_common` library, instead of including and depending on its own set of libraries for the following functionality: + +- SSD1306 display +- i2c for OLED +- Serial Communication + +This allows current lily58 firmware to advance with updates to the `split_common` library, which is shared with many other split keyboards. + +#### To migrate existing Lily58 firmware: + +[Changes to `config.h`](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-445ac369c8717dcd6fc6fc3630836fc1): +- Remove `#define SSD1306OLED` from config.h + + +[Changes to `keymap.c`](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7): +- Find/Replace each instance of `#ifdef SSD1306OLED` with `#ifdef OLED_DRIVER_ENABLE` +- The following changes are for compatibility with the OLED driver. If you don't use the OLED driver you may safely delete [this section](https://github.com/qmk/qmk_firmware/blob/e6b9980bd45c186f7360df68c24b6e05a80c10dc/keyboards/lily58/keymaps/default/keymap.c#L144-L190) +- Alternatively, if you did not change the OLED code from that in `default`, you may find it easier to simply copy the [relevant section](https://github.com/qmk/qmk_firmware/blob/4ac310668501ae6786c711ecc8f01f62ddaa1c0b/keyboards/lily58/keymaps/default/keymap.c#L138-L172). Otherwise, the changes you need to make are as follows (sample change [here](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7R138-R173)) +- [Remove](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7L138-L141) the block +```c +#ifdef SSD1306OLED + iota_gfx_init(!has_usb()); // turns on the display +#endif +``` +- Within the block bounded by `#ifdef OLED_DRIVER_ENABLE` and `#endif // OLED_DRIVER_ENABLE`, add the following block to ensure that your two OLEDs are rotated correctly across the left and right sides: +```c +oled_rotation_t oled_init_user(oled_rotation_t rotation) { + if (!is_keyboard_master()) + return OLED_ROTATION_180; // flips the display 180 degrees if offhand + return rotation; +} +``` +- Remove the functions `matrix_scan_user`, `matrix_update` and `iota_gfx_task_user` +- Find/Replace `matrix_render_user(struct CharacterMatrix *matrix)` with `iota_gfx_task_user(void)` +- Find/Replace `is_master` with `is_keyboard_master()` +- For each instance of `matrix_write_ln(matrix, display_fn())`, rewrite it as `oled_write_ln(read_layer_state(), false);` +- For each instance of `matrix_write(matrix, read_logo());`, replace with `oled_write(read_logo(), false);` + +### Refactor zinc to use split_common + +[#7114](https://github.com/qmk/qmk_firmware/pull/7114) and [#9171](https://github.com/qmk/qmk_firmware/pull/9171) + +* Refactor to use split_common and remove split codes under the zinc/revx/ +* Add - backlight RGB LED and/or underglow RGB LED option +* Add - continuous RGB animations feature (between L and R halves) +* Fix - keymap files to adapt to changes + * all authors of keymaps confirmed this PR +* Update - documents and rules.mk + +### Refactor of TKC1800 to use common OLED code + +[#8472](https://github.com/qmk/qmk_firmware/pull/8472) + +Modifies the default firmware for TKC1800 to use the in-built I2C and OLED drivers, instead of including and depending on its own set of libraries for the following functionality: + +- SSD1306 display +- i2c for OLED + +This allows current TKC1800 firmware to advance with updates to those drivers, which are shared with other keyboards. + +#### To migrate existing TKC1800 firmware: + +[Changes to `config.h`](https://github.com/qmk/qmk_firmware/pull/8472/files#diff-d10b26e676b4a55cbb00d71955116526): +- Remove `#define SSD1306OLED` from config.h + +[Changes to `tkc1800.c`](https://github.com/qmk/qmk_firmware/pull/8472/files#diff-3b35bd30abe89c8110717c6972cd2cc5): +- Add the following to avoid debug errors on HID_listen if the screen is not present +```c +void keyboard_pre_init_kb(void) { + setPinInputHigh(D0); + setPinInputHigh(D1); + + keyboard_pre_init_user(); +} +``` + +[Changes to `keymap.c`](https://github.com/qmk/qmk_firmware/pull/8472/files#diff-05a2a344ce27e4d045fe68520ccd4771): +- Find/Replace each instance of `#ifdef SSD1306OLED` with `#ifdef OLED_DRIVER_ENABLE` +- The following changes are for compatibility with the OLED driver. If you don't use the OLED driver you may safely delete [this section](https://github.com/qmk/qmk_firmware/blob/e6b9980bd45c186f7360df68c24b6e05a80c10dc/keyboards/lily58/keymaps/default/keymap.c#L144-L190) +- [Remove](https://github.com/qmk/qmk_firmware/pull/6260/files#diff-20943ea59856e9bdf3d99ecb2eee40b7L91-L158) the block +```c +#ifdef SSD1306OLED + iota_gfx_init(!has_usb()); // turns on the display +#endif +``` +- Within the block bounded by `#ifdef OLED_DRIVER_ENABLE` and `#endif // OLED_DRIVER_ENABLE`, add the following block to ensure that your two OLEDs are rotated correctly across the left and right sides: +```c +oled_rotation_t oled_init_user(oled_rotation_t rotation) { + if (!is_keyboard_master()) + return OLED_ROTATION_180; // flips the display 180 degrees if offhand + return rotation; +} +``` +- Remove the function `iota_gfx_task_user` + +### Split HHKB to ANSI and JP layouts and Add VIA support for each + +[#8582](https://github.com/qmk/qmk_firmware/pull/8582) + +- Splits the HHKB codebase into two separate folders `keyboards/hhkb/ansi` and `keyboards/hhkb/jp`. +- Adds VIA Configurator support for both versions. + +#### Migrating existing HHKB keymaps + +- Remove any checks for the `HHKB_JP` definition + - All checks for this definition have been removed, and each version uses the source that is appropriate to that version. +- Move the directory for your keymap into the appropriate `keymaps` directory + - `keyboards/hhkb/ansi/keymaps/` for ANSI HHKBs + - `keyboards/hhkb/jp/keymaps/` for HHKB JPs +- Compile with the new keyboard names + - This PR changes the compilation instructions for the HHKB Alternate Controller. To compile firmware for this controller moving forward, use: + - `make hhkb/ansi` for ANSI-layout HHKBs + - `make hhkb/jp` for HHKB JP keyboards + + +## Keyboard Moves + +- [#8412](https://github.com/qmk/qmk_firmware/pull/8412 "Changing board names to prevent confusion") by blindassassin111 +- [#8499](https://github.com/qmk/qmk_firmware/pull/8499 "Move the Keyboardio Model01 to a keyboardio/ subdir") by algernon +- [#8830](https://github.com/qmk/qmk_firmware/pull/8830 "Move spaceman keyboards") by Spaceman (formerly known as Rionlion100) +- [#8537](https://github.com/qmk/qmk_firmware/pull/8537 "Organizing my keyboards (plaid, tartan, ergoinu)") by hsgw + +Keyboards by Keyboardio, Spaceman, and hsgw move to vendor folders, while PCBs designed by blindassassin111 are renamed. + +Old Name | New Name +:----------------- | :----------------- +2_milk | spaceman/2_milk +at101_blackheart | at101_bh +ergoinu | dm9records/ergoinu +model01 | keyboardio/model01 +omnikey_blackheart | omnikey_bh +pancake | spaceman/pancake +plaid | dm9records/plaid +tartan | dm9records/tartan +z150_blackheart | z150_bh + +If you own one of these PCBs, please use the new names to compile your firmware moving forward. + + +## Keycode Migration PRs + +[#8954](https://github.com/qmk/qmk_firmware/pull/8954 "Migrate `ACTION_LAYER_TOGGLE` to `TG()`"), [#8957](https://github.com/qmk/qmk_firmware/pull/8957 "Migrate `ACTION_MODS_ONESHOT` to `OSM()`"), [#8958](https://github.com/qmk/qmk_firmware/pull/8958 "Migrate `ACTION_DEFAULT_LAYER_SET` to `DF()`"), [#8959](https://github.com/qmk/qmk_firmware/pull/8959 "Migrate `ACTION_LAYER_MODS` to `LM()`"), [#8968](https://github.com/qmk/qmk_firmware/pull/8968 "Migrate `ACTION_MODS_TAP_KEY` to `MT()`"), [#8977](https://github.com/qmk/qmk_firmware/pull/8977 "Migrate miscellaneous `fn_actions` entries"), and [#8979](https://github.com/qmk/qmk_firmware/pull/8979 "Migrate `ACTION_MODS_KEY` to chained mod keycodes") + +Authored by fauxpark, these pull requests remove references to deprecated TMK macros that have been superseded by native QMK keycodes. + +Old `fn_actions` action | New QMK keycode +:---------------------- | :-------------- +`ACTION_DEFAULT_LAYER_SET(layer)` | `DF(layer)` +`ACTION_LAYER_MODS(layer, mod)` | `LM(layer, mod)` +`ACTION_LAYER_ONESHOT(mod)` | `OSL(mod)` +`ACTION_LAYER_TOGGLE(layer)` | `TG(layer)` +`ACTION_MODS_ONESHOT(mod)` | `OSM(mod)` +`ACTION_MODS_TAP_KEY(mod, kc)` | `MT(mod, kc)` +`ACTION_MODS_KEY(mod, kc)`
e.g. `ACTION_MODS_KEY(MOD_LCTL, KC_0)` | `MOD(kc)`
e.g. `LCTL(KC_0)` diff --git a/docs/ChangeLog/20200829.md b/docs/ChangeLog/20200829.md new file mode 100644 index 00000000000..00e0bd1a287 --- /dev/null +++ b/docs/ChangeLog/20200829.md @@ -0,0 +1,148 @@ +# QMK Breaking Change - 2020 Aug 29 Changelog + +Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps. + + +## Changes Requiring User Action :id=changes-requiring-user-action + +### Relocated Keyboards :id-relocated-keyboards + +#### The Key Company project consolidation ([#9547](https://github.com/qmk/qmk_firmware/pull/9547)) +#### relocating boards by flehrad to flehrad/ folder ([#9635](https://github.com/qmk/qmk_firmware/pull/9635)) + +Keyboards released by The Key Company and keyboards designed by flehrad have moved to vendor folders. If you own any of the keyboards listed below, please use the new names to compile your firmware moving forward. + +Old Name | New Name +:--------------------- | :------------------ +candybar/lefty | tkc/candybar/lefty +candybar/righty | tkc/candybar/righty +m0lly | tkc/m0lly +tkc1800 | tkc/tkc1800 +bigswitch | flehrad/bigswitch +handwired/downbubble | flehrad/downbubble +handwired/numbrero | flehrad/numbrero +snagpad | flehrad/snagpad +handwired/tradestation | flehrad/tradestation + +### Updated Keyboard Codebases :id=keyboard-updates + +#### Keebio RGB wiring update ([#7754](https://github.com/qmk/qmk_firmware/pull/7754)) + +This pull request changes the configuration for Keebio split boards to use the same RGB strip wiring for each half, which provides the following improvements: + +* Easier wiring due to one fewer wire needed (the wire between left DOut to extra data pin) and the fact that wiring is the same for both halves. +* RGB LEDs can be controlled by each half now instead of just master half. +* Extra data line is freed up to allow for I2C usage instead of serial. + +If you have customized the value of `RGBLED_SPLIT` for your keymap, you will need to undefine it using `#undef RGBLED_SPLIT` before defining it to your customized value. + +This change affects: + +* BFO-9000 +* Fourier +* Iris rev2 +* Levinson, revs. 1 and 2 +* Nyquist, revs. 1 and 2 +* Quefrency rev1 +* Viterbi, revs. 1 and 2 + +### Changes to Core Functionality :id=core-updates + +* Bigger Combo index ([#9318](https://github.com/qmk/qmk_firmware/pull/9318)) + +Allows the Combo feature to support more than 256 combos. + +Any fork that uses `process_combo_event` needs to update the function's first argument to `uint16_t`: + +* Old function: `void process_combo_event(uint8_t combo_index, bool pressed)` +* New function: `void process_combo_event(uint16_t combo_index, bool pressed)` + + +## Core Changes :id=core-changes + +### Fixes :id=core-fixes + +* Mousekeys: scrolling acceleration is no longer coupled to mouse movement acceleration ([#9174](https://github.com/qmk/qmk_firmware/pull/9174)) +* Keymap Extras: correctly assign Question Mark in Czech layout ([#9987](https://github.com/qmk/qmk_firmware/pull/9987)) + +### Additions and Enhancements :id=core-additions + +* allow for WS2812 PWM to work on DMAMUX-capable devices ([#9471](https://github.com/qmk/qmk_firmware/pull/9471)) + * Newer STM32 MCUs have a DMAMUX peripheral, which allows mapping of DMAs to different DMA streams, rather than hard-defining the target streams in silicon. + * Affects STM32L4+ devices, as well as the soon-to-be-supported-by-QMK STM32G4/H7 families. + * Tested on F303/Proton C (ChibiOS v19, non-DMAMUX), G474 (ChibiOS v20, with DMAMUX). +* dual-bank STM32 bootloader support ([#8778](https://github.com/qmk/qmk_firmware/pull/8778) and [#9738](https://github.com/qmk/qmk_firmware/pull/9738)) + * Adds support for STM32 dual-bank flash bootloaders, by toggling a GPIO during early init in order to charge an RC circuit attached to `BOOT0`. + * The main rationale behind this is that dual-bank STM32 devices unconditionally execute user-mode code, regardless of whether or not the user-mode code jumps to the bootloader. If either flash bank is valid (and `BOOT0` is low), then the built-in bootloader will skip any sort of DFU. + * This PR allows for the initialisation sequencing to charge the RC circuit based on the example circuit posted on Discord, effectively pulling `BOOT0` high before issuing the system reset. As the RC circuit takes a while to discharge, the system reset executes the ROM bootloader which subsequently sees `BOOT0` high, and starts executing the DFU routines. + * Tested with STM32L082 (with current QMK+current ChibiOS), and STM32G474 (against ChibiOS 20.x). +* update Space Cadet and Tap Dance features to use Custom Tapping Term when appropriate ([#6259](https://github.com/qmk/qmk_firmware/pull/6259)) + * For the Tap Dance feature, this completely removes the need for the `ACTION_TAP_DANCE_FN_ADVANCED_TIME` dance. +* HID Joystick Interface ([#4226](https://github.com/qmk/qmk_firmware/pull/4226) and [#9949](https://github.com/qmk/qmk_firmware/pull/9949 "Fix Joystick Compile Issues")) + * This implements a joystick feature, including a joystick_task function called from TMK, specific keycodes for joystick buttons and a USB HID interface. + * Tested on V-USB backend and Proton C; compiles but untested on LUFA. + * In order to test, you have to add `JOYSTICK_ENABLE = yes` to your `rules.mk` and + ```c + #define JOYSTICK_BUTTON_COUNT 8 + #define JOYSTICK_AXES_COUNT 2 + ``` + in your config.h. +* Christmas RGB Underglow animation now fades between green and red ([#7648](https://github.com/qmk/qmk_firmware/pull/7648)) + * `RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL` has been greatly decreased; please check your animation if you have customized this value. +* layer state now initializes on startup ([#8318](https://github.com/qmk/qmk_firmware/pull/8318)) + * This should produce more consistent behavior between the two functions and layer masks. +* added support for HSV->RGB conversion without using CIE curve ([#9856](https://github.com/qmk/qmk_firmware/pull/9856)) +* added NOEEPROM functions for RGB Matrix ([#9487](https://github.com/qmk/qmk_firmware/pull/9487)) + * Added eeprom_helpers for toggle, mode, sethsv, speed, similar to rgblight versions. + * Added set_speed function. + * Added helper functions, similar to those in rgblight, in order to add NOEEPROM versions of toggle, step, hue, sat, val, and speed. + * Minor: spelling correction for EEPROM in a debug message. +* flashing firmware using `st-flash` utility from [STLink Tools](https://github.com/stlink-org/stlink) is now supported ([#9964](https://github.com/qmk/qmk_firmware/pull/9964)) +* add ability to dump all makefile variables for the specified target ([#8256](https://github.com/qmk/qmk_firmware/pull/8256)) + * Adds a new subtarget to builds, `dump_vars`, which allows for printing out all the variables that make knows about, after all substitutions occur. + * Example: `make handwired/onekey/proton_c:default:dump_vars` +* add ability to change the Auto Shift timeout in real time ([#8441](https://github.com/qmk/qmk_firmware/pull/8441)) +* added a timer implementation for backlight on ChibiOS ([#8291](https://github.com/qmk/qmk_firmware/pull/8291)) +* added a third endpoint to V-USB keyboards ([#9020](https://github.com/qmk/qmk_firmware/pull/9020)) +* added a method to read the OLED display buffer from user space ([#8777](https://github.com/qmk/qmk_firmware/pull/8777)) +* K-Type refactor ([#9864](https://github.com/qmk/qmk_firmware/pull/9864)) + * The K-Type has been refactored to use QMK's native matrix scanning routine, and now has partial support for the RGB Matrix feature. +* Joysticks can now be used without defining analog pins ([#10169](https://github.com/qmk/qmk_firmware/pull/10169)) + +### Clean-ups and Optimizations :id=core-optimizations + +* iWRAP protocol removed ([#9284](https://github.com/qmk/qmk_firmware/pull/9284)) +* work begun for consolidation of ChibiOS platform files ([#8327](https://github.com/qmk/qmk_firmware/pull/8327) and [#9315](https://github.com/qmk/qmk_firmware/pull/9315)) + * Start of the consolidation work to move the ChibiOS board definitions as well as the default set of configuration files for existing board definitions used by keyboards. + * Uses `/platforms/chibios` as previously discussed on discord. + * Consolidates the Proton C configs into the generic F303 definitions. + * Allows for defining a default set of `chconf.h`, `halconf.h`, and `mcuconf.h` files within the platform definition, which is able to be overridden by the keyboard directly, though include path ordering. + * Adds template `chconf.h`, `halconf.h`, `mcuconf.h`, and `board.h` that can be dropped into a keyboard directory, in order to override rather than replace the entire contents of the respective files. + * Removed Proton C QMK board definitions, falling back to ChibiOS board definitions with QMK overrides. +* Various tidy-ups for USB descriptor code ([#9005](https://github.com/qmk/qmk_firmware/pull/9005)) + * Renamed `keyboard_led_stats` in lufa.c and ChibiOS usb_main.c to `keyboard_led_state`, as well as `vusb_keyboard_leds`, for consistency + * Formatted CDC and MIDI descriptors better + * Removed `ENDPOINT_CONFIG` macro, it seems pointless and removes the need for endpoint address defines in the middle of the endpoint numbering enum + * Fixed (possibly?) V-USB `GET_REPORT` request handling. Not sure about this one, but the existing code appears to always return an empty report - now `send_keyboard` sets this variable to the current report, matching what the LUFA code does. +* converted `CONSUMER2BLUEFRUIT()` and `CONSUMER2RN42()` macros to static inline functions ([#9055](https://github.com/qmk/qmk_firmware/pull/9055)) +* Additional cleanups for V-USB code ([#9310](https://github.com/qmk/qmk_firmware/pull/9310)) + * Removing the UART stuff entirely, now that we have Console support. Also fixing up various other things; switching some `debug()` calls to `dprintf()`, moved `raw_hid_report` out of the way so that we can implement the shared endpoint stuff. +* removed inclusion of `adafruit_ble.h` from `ssd1306.c` ([#9355](https://github.com/qmk/qmk_firmware/pull/9355)) +* `outputselect.c` is no longer compiled if Bluetooth is disabled ([#9356](https://github.com/qmk/qmk_firmware/pull/9356)) +* `analogRead()` deprecated in favor of `analogReadPin()` ([#9023](https://github.com/qmk/qmk_firmware/pull/9023)) +* forcibly disable NKRO on V-USB controllers ([#9054](https://github.com/qmk/qmk_firmware/pull/9054)) +* removed warning if running backlight on STM32F072 ([#10040](https://github.com/qmk/qmk_firmware/pull/10040)) +* removed unused CORTEX_VTOR_INIT rules.mk option ([#10053](https://github.com/qmk/qmk_firmware/pull/10053)) +* improved handling for enabling Link Time Optimization ([#9832](https://github.com/qmk/qmk_firmware/pull/9832)) +* streamline rules for supporting Kiibohd bootloader ([#10129](https://github.com/qmk/qmk_firmware/pull/10129)) +* Define `STM32_DMA_REQUIRED` when using DMA-based WS2812 driver on STM32 ([#10127](https://github.com/qmk/qmk_firmware/pull/10127)) +* fix DMA stream ID calculation in ws2812_pwm ([#10008](https://github.com/qmk/qmk_firmware/pull/10008)) +* remove support for Adafruit EZ Key Bluetooth controller ([#10103](https://github.com/qmk/qmk_firmware/pull/10103)) + + +## QMK Infrastructure and Internals :id=qmk-internals + +* Attempt to fix CI for non-master branches. ([#9308](https://github.com/qmk/qmk_firmware/pull/9308)) + * Actually fetch the branch we're attempting to compare against. +* Run `qmk cformat` on `develop` branch ([#9501](https://github.com/qmk/qmk_firmware/pull/9501)) +* minor refactor of Bluetooth API ([#9905](https://github.com/qmk/qmk_firmware/pull/9905)) diff --git a/docs/ChangeLog/20201128.md b/docs/ChangeLog/20201128.md new file mode 100644 index 00000000000..86abd384df7 --- /dev/null +++ b/docs/ChangeLog/20201128.md @@ -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 : +``` + +For ``, 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)) diff --git a/docs/ChangeLog/20210227.md b/docs/ChangeLog/20210227.md new file mode 100644 index 00000000000..cb34edfd913 --- /dev/null +++ b/docs/ChangeLog/20210227.md @@ -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 `. 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)) diff --git a/docs/README.md b/docs/README.md index 9f9ca166bdf..9330f0facee 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,32 +1,37 @@ # 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 that maintains QMK Firmware, QMK Toolbox, qmk.fm, and these docs. QMK Firmware is a keyboard firmware based on the [tmk\_keyboard](http://github.com/tmk/tmk_keyboard) with some useful features for Atmel AVR controllers, and more specifically, the [OLKB product line](http://olkb.com), the [ErgoDox EZ](http://www.ergodox-ez.com) keyboard, and the [Clueboard product line](http://clueboard.co/). It has also been ported to ARM chips using ChibiOS. You can use it to power your own hand-wired or custom keyboard PCB. +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. -## How to Get It +## Get Started -If you plan on contributing a keymap, keyboard, or features to QMK, the easiest thing to do is [fork the repo through Github](https://github.com/qmk/qmk_firmware#fork-destination-box), and clone your repo locally to make your changes, push them, then open a [Pull Request](https://github.com/qmk/qmk_firmware/pulls) from your fork. +
-Otherwise, you can clone it directly with `git clone https://github.com/qmk/qmk_firmware`. Do not download the zip or tar files; a git repository is required to download the submodules in order to compile. +?> **Basic** [QMK Configurator](newbs_building_firmware_configurator.md)
+User friendly graphical interfaces, no programming knowledge required. -## How to Compile +?> **Advanced** [Use The Source](newbs.md)
+More powerful, but harder to use. -Before you are able to compile, you'll need to [install an environment](getting_started_build_tools.md) for AVR or/and ARM development. Once that is complete, you'll use the `make` command to build a keyboard and keymap with the following notation: +
- make planck/rev4:default +## Make It Yours -This would build the `rev4` revision of the `planck` with the `default` keymap. Not all keyboards have revisions (also called subprojects or folders), in which case, it can be omitted: +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). - make preonic:default +## Need help? -## How to Customize +Check out the [support page](support.md) to see how you can get help using QMK. -QMK has lots of [features](features.md) to explore, and a good deal of [reference documentation](http://docs.qmk.fm) to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md). +## Give Back + +There are a lot of ways you can contribute to the QMK Community. The easiest way to get started is to use it and spread the word to your friends. + +* Help people out on our forums and chat rooms: + * [/r/olkb](https://www.reddit.com/r/olkb/) + * [Discord Server](https://discord.gg/Uq7gcHh) +* Contribute to our documentation by clicking "Edit This Page" at the bottom +* [Translate our documentation into your language](translating.md) +* [Report a bug](https://github.com/qmk/qmk_firmware/issues/new/choose) +* [Open a Pull Request](contributing.md) diff --git a/docs/_summary.md b/docs/_summary.md index f6b03867fcb..83799acdb8b 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -1,127 +1,181 @@ -* [Complete Newbs Guide](newbs.md) - * [Getting Started](newbs_getting_started.md) +* Tutorial + * [Introduction](newbs.md) + * [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) - * [Best Git Practices](newbs_git_best_practices.md) - * [Using Your Fork's Master](newbs_git_using_your_master_branch.md) - * [Resolving Merge Conflicts](newbs_git_resolving_merge_conflicts.md) - * [Resynchronizing a Branch](newbs_git_resynchronize_a_branch.md) - * [Learning Resources](newbs_learn_more_resources.md) + * [Getting Help/Support](support.md) + * [Other Resources](newbs_learn_more_resources.md) + * [Syllabus](syllabus.md) -* [QMK Basics](README.md) - * [QMK Introduction](getting_started_introduction.md) - * [QMK CLI](cli.md) - * [QMK CLI Config](cli_configuration.md) - * [Contributing to QMK](contributing.md) - * [How to Use Github](getting_started_github.md) - * [Getting Help](getting_started_getting_help.md) - -* [Breaking Changes](breaking_changes.md) - * [2019 Aug 30](ChangeLog/20190830.md) - -* [FAQ](faq.md) +* FAQs * [General FAQ](faq_general.md) * [Build/Compile QMK](faq_build.md) - * [Debugging/Troubleshooting QMK](faq_debug.md) - * [Keymap](faq_keymap.md) - * [Driver Installation with Zadig](driver_installation_zadig.md) - -* Detailed Guides - * [Install Build Tools](getting_started_build_tools.md) - * [Vagrant Guide](getting_started_vagrant.md) - * [Build/Compile Instructions](getting_started_make_guide.md) - * [Flashing Firmware](flashing.md) - * [Customizing Functionality](custom_quantum_functions.md) - * [Keymap Overview](keymap.md) - -* [Hardware](hardware.md) - * [Compatible Microcontrollers](compatible_microcontrollers.md) - * [AVR Processors](hardware_avr.md) - * [Drivers](hardware_drivers.md) - -* Reference - * [Keyboard Guidelines](hardware_keyboard_guidelines.md) - * [Config Options](config_options.md) - * [Keycodes](keycodes.md) - * [Coding Conventions - C](coding_conventions_c.md) - * [Coding Conventions - Python](coding_conventions_python.md) - * [Documentation Best Practices](documentation_best_practices.md) - * [Documentation Templates](documentation_templates.md) + * [Troubleshooting QMK](faq_misc.md) + * [Debugging QMK](faq_debug.md) + * [Keymap FAQ](faq_keymap.md) * [Glossary](reference_glossary.md) - * [Unit Testing](unit_testing.md) - * [Useful Functions](ref_functions.md) - * [Configurator Support](reference_configurator_support.md) - * [info.json Format](reference_info_json.md) - * [Python CLI Development](cli_development.md) -* [Features](features.md) - * [Basic Keycodes](keycodes_basic.md) - * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md) - * [Quantum Keycodes](quantum_keycodes.md) - * [Advanced Keycodes](feature_advanced_keycodes.md) - * [Audio](feature_audio.md) - * [Auto Shift](feature_auto_shift.md) - * [Backlight](feature_backlight.md) - * [Bluetooth](feature_bluetooth.md) - * [Bootmagic](feature_bootmagic.md) - * [Combos](feature_combo.md) - * [Command](feature_command.md) - * [Debounce API](feature_debounce_type.md) - * [DIP Switch](feature_dip_switch.md) - * [Dynamic Macros](feature_dynamic_macros.md) - * [Encoders](feature_encoders.md) - * [Grave Escape](feature_grave_esc.md) - * [Haptic Feedback](feature_haptic_feedback.md) - * [HD44780 LCD Controller](feature_hd44780.md) - * [Key Lock](feature_key_lock.md) - * [Layouts](feature_layouts.md) - * [Leader Key](feature_leader_key.md) - * [LED Matrix](feature_led_matrix.md) - * [Macros](feature_macros.md) - * [Mouse Keys](feature_mouse_keys.md) - * [OLED Driver](feature_oled_driver.md) - * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys) - * [Pointing Device](feature_pointing_device.md) - * [PS/2 Mouse](feature_ps2_mouse.md) - * [RGB Lighting](feature_rgblight.md) - * [RGB Matrix](feature_rgb_matrix.md) - * [Space Cadet](feature_space_cadet.md) - * [Split Keyboard](feature_split_keyboard.md) - * [Stenography](feature_stenography.md) - * [Swap Hands](feature_swap_hands.md) - * [Tap Dance](feature_tap_dance.md) - * [Terminal](feature_terminal.md) - * [Thermal Printer](feature_thermal_printer.md) - * [Unicode](feature_unicode.md) - * [Userspace](feature_userspace.md) - * [Velocikey](feature_velocikey.md) +* Configurator + * [Overview](newbs_building_firmware_configurator.md) + * [Step by Step](configurator_step_by_step.md) + * [Troubleshooting](configurator_troubleshooting.md) + * QMK API + * [Overview](api_overview.md) + * [API Documentation](api_docs.md) + * [Keyboard Support](reference_configurator_support.md) + * [Adding Default Keymaps](configurator_default_keymaps.md) -* For Makers and Modders - * [Hand Wiring Guide](hand_wire.md) - * [ISP Flashing Guide](isp_flashing_guide.md) - * [ARM Debugging Guide](arm_debugging.md) - * [ADC Driver](adc_driver.md) - * [I2C Driver](i2c_driver.md) - * [WS2812 Driver](ws2812_driver.md) - * [GPIO Controls](internals_gpio_control.md) - * [Proton C Conversion](proton_c_conversion.md) +* CLI + * [Overview](cli.md) + * [Configuration](cli_configuration.md) + * [Commands](cli_commands.md) -* For a Deeper Understanding - * [How Keyboards Work](how_keyboards_work.md) - * [Understanding QMK](understanding_qmk.md) +* Using QMK + * Guides + * [Customizing Functionality](custom_quantum_functions.md) + * [Driver Installation with Zadig](driver_installation_zadig.md) + * [Keymap Overview](keymap.md) + * Development Environments + * [Docker Guide](getting_started_docker.md) + * [Vagrant Guide](getting_started_vagrant.md) + * Flashing + * [Flashing](flashing.md) + * [Flashing ATmega32A (ps2avrgb)](flashing_bootloadhid.md) + * IDEs + * [Using Eclipse with QMK](other_eclipse.md) + * [Using VSCode with QMK](other_vscode.md) + * Git Best Practices + * [Introduction](newbs_git_best_practices.md) + * [Your Fork](newbs_git_using_your_master_branch.md) + * [Merge Conflicts](newbs_git_resolving_merge_conflicts.md) + * [Fixing Your Branch](newbs_git_resynchronize_a_branch.md) + * Keyboard Building + * [Hand Wiring Guide](hand_wire.md) + * [ISP Flashing Guide](isp_flashing_guide.md) -* Other Topics - * [Using Eclipse with QMK](other_eclipse.md) - * [Using VSCode with QMK](other_vscode.md) - * [Support](support.md) - * [Translating the QMK Docs](translating.md) + * Simple Keycodes + * [Full List](keycodes.md) + * [Basic Keycodes](keycodes_basic.md) + * [Language-Specific Keycodes](reference_keymap_extras.md) + * [Modifier Keys](feature_advanced_keycodes.md) + * [Quantum Keycodes](quantum_keycodes.md) -* QMK Internals (In Progress) - * [Defines](internals_defines.md) - * [Input Callback Reg](internals_input_callback_reg.md) - * [Midi Device](internals_midi_device.md) - * [Midi Device Setup Process](internals_midi_device_setup_process.md) - * [Midi Util](internals_midi_util.md) - * [Send Functions](internals_send_functions.md) - * [Sysex Tools](internals_sysex_tools.md) + * Advanced Keycodes + * [Command](feature_command.md) + * [Dynamic Macros](feature_dynamic_macros.md) + * [Grave Escape](feature_grave_esc.md) + * [Leader Key](feature_leader_key.md) + * [Mod-Tap](mod_tap.md) + * [Macros](feature_macros.md) + * [Mouse Keys](feature_mouse_keys.md) + * [Space Cadet Shift](feature_space_cadet.md) + * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md) + + * Software Features + * [Auto Shift](feature_auto_shift.md) + * [Combos](feature_combo.md) + * [Debounce API](feature_debounce_type.md) + * [Key Lock](feature_key_lock.md) + * [Layers](feature_layers.md) + * [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) + * [Terminal](feature_terminal.md) + * [Unicode](feature_unicode.md) + * [Userspace](feature_userspace.md) + * [WPM Calculation](feature_wpm.md) + + * Hardware Features + * Displays + * [HD44780 LCD Controller](feature_hd44780.md) + * [OLED Driver](feature_oled_driver.md) + * Lighting + * [Backlight](feature_backlight.md) + * [LED Matrix](feature_led_matrix.md) + * [RGB Lighting](feature_rgblight.md) + * [RGB Matrix](feature_rgb_matrix.md) + * [Audio](feature_audio.md) + * [Bluetooth](feature_bluetooth.md) + * [Bootmagic](feature_bootmagic.md) + * [Custom Matrix](custom_matrix.md) + * [DIP Switch](feature_dip_switch.md) + * [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) + * [Stenography](feature_stenography.md) + * [Thermal Printer](feature_thermal_printer.md) + * [Velocikey](feature_velocikey.md) + +* Developing QMK + * [PR Checklist](pr_checklist.md) + * Breaking Changes + * [Overview](breaking_changes.md) + * [My Pull Request Was Flagged](breaking_changes_instructions.md) + * [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) + * [AVR Processors](hardware_avr.md) + * [Coding Conventions](coding_conventions_c.md) + * [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) + + * Python Development + * [Coding Conventions](coding_conventions_python.md) + * [QMK CLI Development](cli_development.md) + + * Configurator Development + * QMK API + * [Development Environment](api_development_environment.md) + * [Architecture Overview](api_development_overview.md) + + * Hardware Platform Development + * Arm/ChibiOS + * [Selecting an MCU](platformdev_selecting_arm_mcu.md) + * [Early initialization](platformdev_chibios_earlyinit.md) + + * QMK Reference + * [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) + * [Community Layouts](feature_layouts.md) + * [Unit Testing](unit_testing.md) + * [Useful Functions](ref_functions.md) + * [info.json Format](reference_info_json.md) + + * For a Deeper Understanding + * [How Keyboards Work](how_keyboards_work.md) + * [How a Matrix Works](how_a_matrix_works.md) + * [Understanding QMK](understanding_qmk.md) + + * QMK Internals (In Progress) + * [Defines](internals_defines.md) + * [Input Callback Reg](internals_input_callback_reg.md) + * [Midi Device](internals_midi_device.md) + * [Midi Device Setup Process](internals_midi_device_setup_process.md) + * [Midi Util](internals_midi_util.md) + * [Send Functions](internals_send_functions.md) + * [Sysex Tools](internals_sysex_tools.md) diff --git a/docs/adc_driver.md b/docs/adc_driver.md index 26e148adddf..6e3d513863b 100644 --- a/docs/adc_driver.md +++ b/docs/adc_driver.md @@ -2,7 +2,7 @@ QMK can leverage the Analog-to-Digital Converter (ADC) on supported MCUs to measure voltages on certain pins. This can be useful for implementing things such as battery level indicators for Bluetooth keyboards, or volume controls using a potentiometer, as opposed to a [rotary encoder](feature_encoders.md). -This driver is currently AVR-only. The values returned are 10-bit integers (0-1023) mapped between 0V and VCC (usually 5V or 3.3V). +This driver currently supports both AVR and a limited selection of ARM devices. The values returned are 10-bit integers (0-1023) mapped between 0V and VCC (usually 5V or 3.3V for AVR, 3.3V only for ARM), however on ARM there is more flexibility in control of operation through `#define`s if you need more precision. ## Usage @@ -20,7 +20,9 @@ Then place this include at the top of your code: ## Channels -|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328P| +### AVR + +|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328/P| |-------|-------------|-------------|---------|----------| |0 |`F0` |`F0` |`A0` |`C0` | |1 |`F1` |`F1` |`A1` |`C1` | @@ -37,14 +39,112 @@ Then place this include at the top of your code: |12 | |`B5` | | | |13 | |`B6` | | | -\* The ATmega328P possesses two extra ADC channels; however, they are not present on the DIP pinout, and are not shared with GPIO pins. You can use `adc_read()` directly to gain access to these. +\* The ATmega328/P possesses two extra ADC channels; however, they are not present on the DIP pinout, and are not shared with GPIO pins. You can use `adc_read()` directly to gain access to these. + +### ARM + +Note that some of these pins are doubled-up on ADCs with the same channel. This is because the pins can be used for either ADC. + +Also note that the F0 and F3 use different numbering schemes. The F0 has a single ADC and the channels are 0-indexed, whereas the F3 has 4 ADCs and the channels are 1-indexed. This is because the F0 uses the `ADCv1` implementation of the ADC, whereas the F3 uses the `ADCv3` implementation. + +|ADC|Channel|STM32F0xx|STM32F3xx| +|---|-------|---------|---------| +|1 |0 |`A0` | | +|1 |1 |`A1` |`A0` | +|1 |2 |`A2` |`A1` | +|1 |3 |`A3` |`A2` | +|1 |4 |`A4` |`A3` | +|1 |5 |`A5` |`F4` | +|1 |6 |`A6` |`C0` | +|1 |7 |`A7` |`C1` | +|1 |8 |`B0` |`C2` | +|1 |9 |`B1` |`C3` | +|1 |10 |`C0` |`F2` | +|1 |11 |`C1` | | +|1 |12 |`C2` | | +|1 |13 |`C3` | | +|1 |14 |`C4` | | +|1 |15 |`C5` | | +|1 |16 | | | +|2 |1 | |`A4` | +|2 |2 | |`A5` | +|2 |3 | |`A6` | +|2 |4 | |`A7` | +|2 |5 | |`C4` | +|2 |6 | |`C0` | +|2 |7 | |`C1` | +|2 |8 | |`C2` | +|2 |9 | |`C3` | +|2 |10 | |`F2` | +|2 |11 | |`C5` | +|2 |12 | |`B2` | +|2 |13 | | | +|2 |14 | | | +|2 |15 | | | +|2 |16 | | | +|3 |1 | |`B1` | +|3 |2 | |`E9` | +|3 |3 | |`E13` | +|3 |4 | | | +|3 |5 | | | +|3 |6 | |`E8` | +|3 |7 | |`D10` | +|3 |8 | |`D11` | +|3 |9 | |`D12` | +|3 |10 | |`D13` | +|3 |11 | |`D14` | +|3 |12 | |`B0` | +|3 |13 | |`E7` | +|3 |14 | |`E10` | +|3 |15 | |`E11` | +|3 |16 | |`E12` | +|4 |1 | |`E14` | +|4 |2 | |`B12` | +|4 |3 | |`B13` | +|4 |4 | |`B14` | +|4 |5 | |`B15` | +|4 |6 | |`E8` | +|4 |7 | |`D10` | +|4 |8 | |`D11` | +|4 |9 | |`D12` | +|4 |10 | |`D13` | +|4 |11 | |`D14` | +|4 |12 | |`D8` | +|4 |13 | |`D9` | +|4 |14 | | | +|4 |15 | | | +|4 |16 | | | ## Functions +### AVR + |Function |Description | |----------------------------|-------------------------------------------------------------------------------------------------------------------| |`analogReference(mode)` |Sets the analog voltage reference source. Must be one of `ADC_REF_EXTERNAL`, `ADC_REF_POWER` or `ADC_REF_INTERNAL`.| -|`analogRead(pin)` |Reads the value from the specified Arduino pin, eg. `4` for ADC6 on the ATmega32U4. | -|`analogReadPin(pin)` |Reads the value from the specified QMK pin, eg. `F6` for ADC6 on the ATmega32U4. | -|`pinToMux(pin)` |Translates a given QMK pin to a mux value. If an unsupported pin is given, returns the mux value for "0V (GND)". | +|`analogReadPin(pin)` |Reads the value from the specified pin, eg. `F6` for ADC6 on the ATmega32U4. | +|`pinToMux(pin)` |Translates a given pin to a mux value. If an unsupported pin is given, returns the mux value for "0V (GND)". | |`adc_read(mux)` |Reads the value from the ADC according to the specified mux. See your MCU's datasheet for more information. | + +### ARM + +|Function |Description | +|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +|`analogReadPin(pin)` |Reads the value from the specified pin, eg. `A0` for channel 0 on the STM32F0 and ADC1 channel 1 on the STM32F3. Note that if a pin can be used for multiple ADCs, it will pick the lower numbered ADC for this function. eg. `C0` will be channel 6 of ADC 1 when it could be used for ADC 2 as well.| +|`analogReadPinAdc(pin, adc)`|Reads the value from the specified pin and ADC, eg. `C0, 1` will read from channel 6, ADC 2 instead of ADC 1. Note that the ADCs are 0-indexed for this function. | +|`pinToMux(pin)` |Translates a given pin to a channel and ADC combination. If an unsupported pin is given, returns the mux value for "0V (GND)". | +|`adc_read(mux)` |Reads the value from the ADC according to the specified pin and ADC combination. See your MCU's datasheet for more information. | + +## Configuration + +## ARM + +The ARM implementation of the ADC has a few additional options that you can override in your own keyboards and keymaps to change how it operates. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options. + +|`#define` |Type |Default |Description | +|---------------------|------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +|`ADC_CIRCULAR_BUFFER`|`bool`|`false` |If `true`, then the implementation will use a circular buffer. | +|`ADC_NUM_CHANNELS` |`int` |`1` |Sets the number of channels that will be scanned as part of an ADC operation. The current implementation only supports `1`. | +|`ADC_BUFFER_DEPTH` |`int` |`2` |Sets the depth of each result. Since we are only getting a 12-bit result by default, we set this to 2 bytes so we can contain our one value. This could be set to 1 if you opt for an 8-bit or lower result.| +|`ADC_SAMPLING_RATE` |`int` |`ADC_SMPR_SMP_1P5` |Sets the sampling rate of the ADC. By default, it is set to the fastest setting. | +|`ADC_RESOLUTION` |`int` |`ADC_CFGR1_RES_12BIT`|The resolution of your result. We choose 12 bit by default, but you can opt for 12, 10, 8, or 6 bit. | diff --git a/docs/api_development_environment.md b/docs/api_development_environment.md new file mode 100644 index 00000000000..50647c42995 --- /dev/null +++ b/docs/api_development_environment.md @@ -0,0 +1,3 @@ +# Development Environment Setup + +To setup a development stack head over to the [qmk_web_stack](https://github.com/qmk/qmk_web_stack). diff --git a/docs/api_development_overview.md b/docs/api_development_overview.md new file mode 100644 index 00000000000..e55d0341006 --- /dev/null +++ b/docs/api_development_overview.md @@ -0,0 +1,44 @@ +# QMK Compiler Development Guide + +This page attempts to introduce developers to the QMK Compiler. It does not go into nitty gritty details- for that you should read code. What this will give you is a framework to hang your understanding on as you read the code. + +# Overview + +The QMK Compile API consists of a few movings parts: + +![Architecture Diagram](https://raw.githubusercontent.com/qmk/qmk_api/master/docs/architecture.svg) + +API Clients interact exclusively with the API service. This is where they submit jobs, check status, and download results. The API service inserts compile jobs into [Redis Queue](https://python-rq.org) and checks both RQ and S3 for the results of those jobs. + +Workers fetch new compile jobs from RQ, compile them, and then upload the source and the binary to an S3 compatible storage engine. + +# Workers + +QMK Compiler Workers are responsible for doing the actual building. When a worker pulls a job from RQ it does several things to complete that job: + +* Make a fresh qmk_firmware checkout +* Use the supplied layers and keyboard metadata to build a `keymap.c` +* Build the firmware +* Zip a copy of the source +* Upload the firmware, source zip, and a metadata file to S3. +* Report the status of the job to RQ + +# API Service + +The API service is a relatively simple Flask application. There are a few main views you should understand. + +## @app.route('/v1/compile', methods=['POST']) + +This is the main entrypoint for the API. A client's interaction starts here. The client POST's a JSON document describing their keyboard, and the API does some (very) basic validation of that JSON before submitting the compile job. + +## @app.route('/v1/compile/<string:job_id>', methods=['GET']) + +This is the most frequently called endpoint. It pulls the job details from redis, if they're still available, or the cached job details on S3 if they're not. + +## @app.route('/v1/compile/<string:job_id>/download', methods=['GET']) + +This method allows users to download the compiled firmware file. + +## @app.route('/v1/compile/<string:job_id>/source', methods=['GET']) + +This method allows users to download the source for their firmware. diff --git a/docs/api_docs.md b/docs/api_docs.md new file mode 100644 index 00000000000..5032dbc87e6 --- /dev/null +++ b/docs/api_docs.md @@ -0,0 +1,68 @@ +# QMK API + +This page describes using the QMK API. If you are an application developer you can use this API to compile firmware for any [QMK](https://qmk.fm) Keyboard. + +## Overview + +This service is an asynchronous API for compiling custom keymaps. You POST some JSON to the API, periodically check the status, and when your firmware has finished compiling you can download the resulting firmware and (if desired) source code for that firmware. + +#### Example JSON Payload: + +```json +{ + "keyboard": "clueboard/66/rev2", + "keymap": "my_awesome_keymap", + "layout": "LAYOUT_all", + "layers": [ + ["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_GRV","KC_BSPC","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_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_RO","KC_RSFT","KC_UP","KC_LCTL","KC_LGUI","KC_LALT","KC_MHEN","KC_SPC","KC_SPC","KC_HENK","KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"], + ["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_TRNS","KC_DEL","BL_STEP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","_______","KC_TRNS","KC_PSCR","KC_SLCK","KC_PAUS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","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_PGUP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_LEFT","KC_PGDN","KC_RGHT"], + ["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","RESET","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","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","MO(1)","KC_TRNS","KC_TRNS","KC_TRNS"] + ] +} +``` + +As you can see the payload describes all aspects of a keyboard necessary to create and generate a firmware. Each layer is a single list of QMK keycodes the same length as the keyboard's `LAYOUT` macro. If a keyboard supports mulitple `LAYOUT` macros you can specify which macro to use. + +## Submitting a Compile Job + +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)" https://api.qmk.fm/v1/compile +{ + "enqueued": true, + "job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6" +} +``` + +## Checking The Status + +After submitting your keymap you can check the status using a simple HTTP GET call: + +``` +$ 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", + "id": "f5f9b992-73b4-479b-8236-df1deb37c163", + "status": "running", + "result": null +} +``` + +This shows us that the job has made it through the queue and is currently running. There are 5 possible statuses: + +* **failed**: Something about the compiling service has broken. +* **finished**: The compilation is complete and you should check `result` to see the results. +* **queued**: The keymap is waiting for a compilation server to become available. +* **running**: The compilation is in progress and should be complete soon. +* **unknown**: A serious error has occurred and you should [file a bug](https://github.com/qmk/qmk_compiler/issues). + +## Examining Finished Results + +Once your compile job has finished you'll check the `result` key. The value of this key is a hash containing several key bits of information: + +* `firmware_binary_url`: A list of URLs for the the flashable firmware +* `firmware_keymap_url`: A list of URLs for the the `keymap.c` +* `firmware_source_url`: A list of URLs for the full firmware source code +* `output`: The stdout and stderr for this compile job. Errors will be found here. diff --git a/docs/api_overview.md b/docs/api_overview.md new file mode 100644 index 00000000000..f851a48a4af --- /dev/null +++ b/docs/api_overview.md @@ -0,0 +1,15 @@ +# 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](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 + +If you are an app developer interested in using this API in your application you should head over to [Using The API](api_docs.md). + +## Keyboard Maintainers + +If you would like to enhance your keyboard's support in the QMK Compiler API head over to the [Keyboard Support](reference_configurator_support.md) section. + +## Backend Developers + +If you are interested in working on the API itself you should start by setting up a [Development Environment](api_development_environment.md), then check out [Hacking On The API](api_development_overview.md). diff --git a/docs/arm_debugging.md b/docs/arm_debugging.md index 448b7a8fcc3..04887d88b7c 100644 --- a/docs/arm_debugging.md +++ b/docs/arm_debugging.md @@ -1,4 +1,4 @@ -# ARM Debugging usign Eclipse +# ARM Debugging using Eclipse This page describes how to setup debugging for ARM MCUs using an SWD adapter and open-source/free tools. In this guide we will install GNU MCU Eclipse IDE for C/C++ Developers and OpenOCD together with all the necessary dependencies. @@ -18,7 +18,7 @@ XPM installation instructions can be found [here](https://www.npmjs.com/package/ ### The ARM Toolchain -Using XPM it is very easy to install the ARM toolchain. Enter the command `xpm install --global @gnu-mcu-eclipse/arm-none-eabi-gcc`. +Using XPM it is very easy to install the ARM toolchain. Enter the command `xpm install --global @xpack-dev-tools/arm-none-eabi-gcc`. ### Windows build tools @@ -33,7 +33,7 @@ If you have an ST-Link the drivers can be found [here](https://www.st.com/en/dev ### OpenOCD -This dependency allows SWD access from GDB and it is essential for debugging. Run `xpm install --global @gnu-mcu-eclipse/openocd`. +This dependency allows SWD access from GDB and it is essential for debugging. Run `xpm install --global @xpack-dev-tools/openocd`. ### Java @@ -45,17 +45,17 @@ Now its finally time to install the IDE. Use the Release page [here](https://git ## Configuring Eclipse -Open up the Eclipse IDE we just downloaded. To import our QMK directory select File -> Import -> C/C++ -> Existing code as Makefile Project. Select next and use Browse to select your QMK folder. In the tool-chain list select ARM Cross GCC and select Finish. +Open up the Eclipse IDE we just downloaded. To import our QMK directory select File -> Import -> C/C++ -> Existing Code as Makefile Project. Select Next and use Browse to select your QMK folder. In the tool-chain list select ARM Cross GCC and select Finish. -Now you can see the QMK folder on the left hand side. Right click it and select Properties. On the left hand side, expand MCU and select ARM Toolchain Paths. Press xPack and OK. Repeat for OpenOCD Path and if you are on windows for Build Tool Path. Select Apply and Close. +Now you can see the QMK folder on the left hand side. Right click it and select Properties. On the left hand side, expand MCU and select ARM Toolchains Paths. Press xPack and OK. Repeat for OpenOCD Path and if you are on Windows for Build Tools Path. Select Apply and Close. -Now its time to install the necessary MCU packages. Go to Packs perspective by selecting Window -> Open Perspective -> Others -> Packs. Now select the yellow refresh symbol next to the Packs tab. This will take a long time as it is requesting the MCU definitions from various places. If some of the links fail you can probably select Ignore. +Now its time to install the necessary MCU packages. Go to Packs perspective by selecting Window -> Perspective -> Open Perspective -> Other... -> Packs. Now select the yellow refresh symbol next to the Packs tab. This will take a long time as it is requesting the MCU definitions from various places. If some of the links fail you can probably select Ignore. -When this finishes you must find the MCU which we will be building/debugging for. In this example I will be using the STM32F3 series MCUs. On the left, select STMicroelectonics -> STM32F3 Series. On the middle window we can see the pack. Right click and select Install. Once that is done we can go back to the default perspective, Window -> Open Perspective -> Others -> C/C++. +When this finishes you must find the MCU which we will be building/debugging for. In this example I will be using the STM32F3 series MCUs. On the left, select STMicroelectronics -> STM32F3 Series. On the middle window we can see the pack. Right click and select Install. Once that is done we can go back to the default perspective, Window -> Perspective -> Open Perspective -> Other... -> C/C++. -We need to let eclipse know the device we intent to build QMK on. Right click on the QMK folder -> Properties -> C/C++ Build -> Settings. Select the Devices tab and under devices select the appropriate variant of your MCU. For my example it is STM32F303CC +We need to let eclipse know the device we intent to build QMK on. Right click on the QMK folder -> Properties -> C/C++ Build -> Settings. Select the Devices tab and under Devices select the appropriate variant of your MCU. For my example it is STM32F303CC -While we are here let's setup the build command as well. Select C/C++ Build and then the Behavior tab. On the build command, replace `all` with your necessary make command. For example for a rev6 Planck with the default keymap this would be `planck/rev6:default`. Select Apply and Close. +While we are here let's setup the build command as well. Select C/C++ Build and then the Behavior tab. On the Build command, replace `all` with your necessary make command. For example for a rev6 Planck with the default keymap this would be `planck/rev6:default`. Select Apply and Close. ## Building @@ -71,7 +71,7 @@ NOTE: Make sure the SWCLK and SWDIO pins are not used in the matrix of your keyb ### Configuring the Debugger -Right click on your QMK folder, select Debug As -> Debug Configuration. Here double click on GDB OpenOCD Debugging. Select the debugger tab and enter the configuration necessary for your MCU. This might take some fiddling and googleing to find out. The default script for the STM32F3 is called stm32f3discovery.cfg. To let OpenOCD know, in the Config options enter `-f board/stm32f3discovery.cfg`. +Right click on your QMK folder, select Debug As -> Debug Configurations... . Here double click on GDB OpenOCD Debugging. Select the Debugger tab and enter the configuration necessary for your MCU. This might take some fiddling and Googling to find out. The default script for the STM32F3 is called `stm32f3discovery.cfg`. To let OpenOCD know, in the Config options enter `-f board/stm32f3discovery.cfg`. NOTE: In my case this configuration script requires editing to disable the reset assertion. The locations of the scripts can be found in the actual executable field usually under the path `openocd/version/.content/scripts/board`. Here I edited `reset_config srst_only` to `reset_config none`. @@ -81,7 +81,7 @@ Select Apply and Close. Reset your keyboard. -Press the bug icon and if all goes well you should soon find yourself in the debug perspective. Here the program counter will pause at the beginning of the main function and way for you to press Play. Most of the features of all debuggers work on ARM MCUs but for exact details google is your friend! +Press the bug icon and if all goes well you should soon find yourself in the Debug perspective. Here the program counter will pause at the beginning of the main function and wait for you to press Play. Most of the features of all debuggers work on Arm MCUs but for exact details Google is your friend! Happy debugging! diff --git a/docs/audio_driver.md b/docs/audio_driver.md new file mode 100644 index 00000000000..7cd5a98d9f4 --- /dev/null +++ b/docs/audio_driver.md @@ -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
Tim6 | GPTD7
Tim7 | GPTD8
Tim8 | PWMD11
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: 2 | | | | + | pwm_software | state-update | | | any = :one: | + | pwm hardware | state-update | | | A8 = :one: 3 | + + +1: the routing and alternate functions for PWM differ sometimes between STM32 MCUs, if in doubt consult the data-sheet +2: one piezo connected to A4 and A5, with AUDIO_PIN_ALT_AS_NEGATIVE set +3: 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 +``` + +``` c +// mcuconf.h: +#include_next +#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 +``` + +``` c +// mcuconf.h: +#include_next +#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 +``` + +``` c +// mcuconf.h: +#include_next +#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.* diff --git a/docs/becoming_a_qmk_collaborator.md b/docs/becoming_a_qmk_collaborator.md deleted file mode 100644 index 16ae0d569ec..00000000000 --- a/docs/becoming_a_qmk_collaborator.md +++ /dev/null @@ -1,9 +0,0 @@ -# Becoming a QMK Collaborator - -A QMK collaborator is a keyboard maker or designer that is interested in helping QMK grow and fully support their keyboard(s), and encouraging their users and customers to submit features, ideas, and keymaps. We're always looking to add more keyboards and collaborators, but we ask that they fulfill these requirements: - -* **Have a PCB available for sale.** Unfortunately there's just too much variation and complications with handwired keyboards. -* **Maintain your keyboard in QMK.** This may just require an initial setup to get your keyboard working, but it could also include accommodating changes made to QMK's core that might break or render any custom code redundant. -* **Approve and merge keymap pull requests for your keyboard.** We like to encourage users to contribute their keymaps for others to see and work from when creating their own. - -If you feel you meet these requirements, shoot us an email at hello@qmk.fm with an introduction and some links to your keyboard! diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md index b5bcb7a1c76..de9148ad62d 100644 --- a/docs/breaking_changes.md +++ b/docs/breaking_changes.md @@ -6,26 +6,31 @@ 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) * [2019 Aug 30](ChangeLog/20190830.md) ## When is the next Breaking Change? -The next Breaking Change is scheduled for Nov 29. +The next Breaking Change is scheduled for February 27, 2021. ### Important Dates -* [x] 2019 Sep 21 - `future` is created. It will be rebased weekly. -* [ ] 2019 Nov 01 - `future` closed to new PR's. -* [ ] 2019 Nov 01 - Call for testers. -* [ ] 2019 Nov 27 - `master` is locked, no PR's merged. -* [ ] 2019 Nov 29 - Merge `future` to `master`. -* [ ] 2019 Nov 30 - `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? -To see a list of breaking change candidates you can look at the [`breaking_change` label](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr). New changes might be added between now and when `future` is closed, and a PR with that label applied is not guaranteed to be merged. +To see a list of breaking change candidates you can look at the [`breaking_change` label](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr). New changes might be added between now and when `develop` is closed, and a PR with that label applied is not guaranteed to be merged. -If you want your breaking change to be included in this round you need to create a PR with the `breaking_change` label and have it accepted before `future` closes. After `future` closes no new breaking changes will be accepted. +If you want your breaking change to be included in this round you need to create a PR with the `breaking_change` label and have it accepted before `develop` closes. After `develop` closes no new breaking changes will be accepted. Criteria for acceptance: @@ -36,41 +41,26 @@ Criteria for acceptance: This section documents various processes we use when running the Breaking Changes process. -## Rebase `future` from `master` +## Creating the `develop` branch -This is run every Friday while `future` is open. - -Process: - -``` -cd qmk_firmware -git checkout master -git pull --ff-only -git checkout future -git rebase master -git push --force -``` - -## Creating the `future` branch - -This happens immediately after the previous `future` branch is merged. +This happens immediately after the previous `develop` branch is merged. * `qmk_firmware` git commands * [ ] `git checkout master` * [ ] `git pull --ff-only` - * [ ] `git checkout -b future` + * [ ] `git checkout -b develop` * [ ] Edit `readme.md` * [ ] Add a big notice at the top that this is a testing branch. * [ ] Include a link to this document * [ ] `git commit -m 'Branch point for Breaking Change'` * [ ] `git tag breakpoint___
` * [ ] `git tag ` # Prevent the breakpoint tag from confusing version incrementing - * [ ] `git push origin future` + * [ ] `git push origin develop` * [ ] `git push --tags` ## 4 Weeks Before Merge -* `future` is now closed to new PR's, only fixes for current PR's may be merged +* `develop` is now closed to new PR's, only fixes for current PR's may be merged * Post call for testers * [ ] Discord * [ ] GitHub PR @@ -93,15 +83,15 @@ This happens immediately after the previous `future` branch is merged. ## Day Of Merge * `qmk_firmware` git commands - * [ ] `git checkout future` + * [ ] `git checkout develop` * [ ] `git pull --ff-only` * [ ] `git rebase origin/master` * [ ] Edit `readme.md` - * [ ] Remove the notes about `future` + * [ ] Remove the notes about `develop` * [ ] Roll up the ChangeLog into one file. * [ ] `git commit -m 'Merge point for Breaking Change'` - * [ ] `git push origin future` -* Github Actions - * [ ] Create a PR for `future` + * [ ] `git push origin develop` +* GitHub Actions + * [ ] Create a PR for `develop` * [ ] Make sure travis comes back clean - * [ ] Merge `future` PR + * [ ] Merge `develop` PR diff --git a/docs/breaking_changes_history.md b/docs/breaking_changes_history.md new file mode 100644 index 00000000000..dd474f1bb7c --- /dev/null +++ b/docs/breaking_changes_history.md @@ -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 diff --git a/docs/breaking_changes_instructions.md b/docs/breaking_changes_instructions.md new file mode 100644 index 00000000000..d835671556d --- /dev/null +++ b/docs/breaking_changes_instructions.md @@ -0,0 +1,42 @@ +# Breaking Changes: My Pull Request Was Flagged + +A QMK member may have replied to your pull request stating that your submission is a breaking change. In their judgment, the changes you have proposed have greater implications for either QMK, or its users. + +Some things that may cause a pull request to be flagged are: + +- **Edits to User Keymaps** + A user may submit their keymap to QMK, then some time later open a pull request with further updates, only to find it can't be merged because it was edited in the `qmk/qmk_firmware` repository. As not all users are proficient at using Git or GitHub, the user may find themself unable to fix the issue on their own. +- **Changes to Expected Behavior** + Changes to QMK behavior may cause users to believe their hardware or QMK is broken if they flash new firmware that incorporates changes to existing QMK features, and find themselves without a means to restore the desired behavior. +- **Changes Requiring User Action** + Changes may also require action to be taken by users, such as updating a toolchain or taking some action in Git. +- **Changes Necessitating Increased Scrutiny** + On occasion, a submission may have implications for QMK as a project. This could be copyright/licensing issues, coding conventions, large feature overhauls, "high-risk" changes that need wider testing by our community, or something else entirely. +- **Changes Requiring Communication to End Users** + This includes warnings about future deprecations, outdated practices, and anything else that needs to be communicated but doesn't fit into one of the above categories. + +## What Do I Do? + +If it is determined that your submission is a breaking change, there are a few things you can do to smooth the process: + +### Consider Splitting Up Your PR + +If you are contributing core code, and the only reason it needs to go through breaking changes is that you are updating keymaps to match your change, consider whether you can submit your feature in a way that the old keymaps continue to work. Then submit a separate PR that goes through the breaking changes process to remove the old code. + +### Contribute a ChangeLog Entry + +We require submissions that go through the Breaking Change process to include a changelog entry. The entry should be a short summary of the changes your pull request makes – [each section here started as a changelog](ChangeLog/20190830.md "n.b. This should link to the 2019 Aug 30 Breaking Changes doc - @noroadsleft"). + +Your changelog should be located at `docs/ChangeLog/YYYYMMDD/PR####.md`, where `YYYYMMDD` is the date on which QMK's breaking change branch – usually named `develop` – will be merged into the `master` branch, and `####` is the number of your pull request. + +If your submission requires action on the part of users, your changelog should instruct users what action(s) must be taken, or link to a location that does so. + +### Document Your Changes + +Understanding the purpose for your submission, and possible implications or actions it will require can make the review process more straightforward. A changelog may suffice for this purpose, but more extensive changes may require a level of detail that is ill-suited for a changelog. + +Commenting on your pull request and being responsive to questions, comments, and change requests is much appreciated. + +### Ask for Help + +Having your submission flagged may have caught you off guard. If you find yourself intimidated or overwhelmed, let us know. Comment on your pull request, or [reach out to the QMK team on Discord](https://discord.gg/Uq7gcHh). diff --git a/docs/cli.md b/docs/cli.md index 1c095272212..8684479d0c1 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,45 +1,34 @@ -# QMK CLI +# QMK CLI :id=qmk-cli -This page describes how to setup and use the QMK CLI. - -# Overview +## Overview :id=overview The QMK CLI makes building and working with QMK keyboards easier. We have provided a number of commands to simplify and streamline tasks such as obtaining and compiling the QMK firmware, creating keymaps, and more. -* [Global CLI](#global-cli) -* [Local CLI](#local-cli) -* [CLI Commands](#cli-commands) +### Requirements :id=requirements -# Requirements +QMK requires Python 3.6 or greater. We try to keep the number of requirements small but you will also need to install the packages listed in [`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt). These are installed automatically when you install the QMK CLI. -The CLI requires Python 3.5 or greater. We try to keep the number of requirements small but you will also need to install the packages listed in [`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt). - -# Global CLI - -QMK provides an installable CLI that can be used to setup your QMK build environment, work with QMK, and which makes working with multiple copies of `qmk_firmware` easier. We recommend installing and updating this periodically. - -## Install Using Homebrew (macOS, some Linux) +### Install Using Homebrew (macOS, some Linux) :id=install-using-homebrew If you have installed [Homebrew](https://brew.sh) you can tap and install QMK: ``` -brew tap qmk/qmk -brew install qmk +brew install qmk/qmk/qmk export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware` qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment ``` -## Install Using easy_install or pip +### Install Using pip :id=install-using-easy_install-or-pip -If your system is not listed above you can install QMK manually. First ensure that you have python 3.5 (or later) installed and have installed pip. Then install QMK with this command: +If your system is not listed above you can install QMK manually. First ensure that you have Python 3.6 (or later) installed and have installed pip. Then install QMK with this command: ``` -pip3 install qmk +python3 -m pip install qmk export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware` qmk setup # This will clone `qmk/qmk_firmware` and optionally set up your build environment ``` -## Packaging For Other Operating Systems +### Packaging For Other Operating Systems :id=packaging-for-other-operating-systems We are looking for people to create and maintain a `qmk` package for more operating systems. If you would like to create a package for your OS please follow these guidelines: @@ -47,176 +36,3 @@ We are looking for people to create and maintain a `qmk` package for more operat * Document why in a comment when you do deviate * Install using a virtualenv * Instruct the user to set the environment variable `QMK_HOME` to have the firmware source checked out somewhere other than `~/qmk_firmware`. - -# Local CLI - -If you do not want to use the global CLI there is a local CLI bundled with `qmk_firmware`. You can find it in `qmk_firmware/bin/qmk`. You can run the `qmk` command from any directory and it will always operate on that copy of `qmk_firmware`. - -**Example**: - -``` -$ ~/qmk_firmware/bin/qmk hello -Ψ Hello, World! -``` - -## Local CLI Limitations - -There are some limitations to the local CLI compared to the global CLI: - -* The local CLI does not support `qmk setup` or `qmk clone` -* The local CLI always operates on the same `qmk_firmware` tree, even if you have multiple repositories cloned. -* The local CLI does not run in a virtualenv, so it's possible that dependencies will conflict - -# CLI Commands - -## `qmk cformat` - -This command formats C code using clang-format. Run it with no arguments to format all core code, or pass filenames on the command line to run it on specific files. - -**Usage**: - -``` -qmk cformat [file1] [file2] [...] [fileN] -``` - -## `qmk compile` - -This command allows you to compile firmware from any directory. You can compile JSON exports from or compile keymaps in the repo. - -**Usage for Configurator Exports**: - -``` -qmk compile -``` - -**Usage for Keymaps**: - -``` -qmk compile -kb -km -``` - -## `qmk flash` - -This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default. -To specify a different bootloader, use `-bl `. Visit -for more details of the available bootloaders. - -**Usage for Configurator Exports**: - -``` -qmk flash -bl -``` - -**Usage for Keymaps**: - -``` -qmk flash -kb -km -bl -``` - -**Listing the Bootloaders** - -``` -qmk flash -b -``` - -## `qmk config` - -This command lets you configure the behavior of QMK. For the full `qmk config` documentation see [CLI Configuration](cli_configuration.md). - -**Usage**: - -``` -qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN] -``` - -## `qmk docs` - -This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936. - -**Usage**: - -``` -qmk docs [-p PORT] -``` - -## `qmk doctor` - -This command examines your environment and alerts you to potential build or flash problems. - -**Usage**: - -``` -qmk doctor -``` - -## `qmk json-keymap` - -Creates a keymap.c from a QMK Configurator export. - -**Usage**: - -``` -qmk json-keymap [-o OUTPUT] filename -``` - -## `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. - -**Usage**: - -``` -qmk kle2json [-f] -``` - -**Examples**: - -``` -$ qmk kle2json kle.txt -☒ File info.json already exists, use -f or --force to overwrite. -``` - -``` -$ qmk kle2json -f kle.txt -f -Ψ Wrote out to info.json -``` - -## `qmk list-keyboards` - -This command lists all the keyboards currently defined in `qmk_firmware` - -**Usage**: - -``` -qmk list-keyboards -``` - -## `qmk new-keymap` - -This command creates a new keymap based on a keyboard's existing default keymap. - -**Usage**: - -``` -qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] -``` - -## `qmk pyformat` - -This command formats python code in `qmk_firmware`. - -**Usage**: - -``` -qmk pyformat -``` - -## `qmk pytest` - -This command runs the python test suite. If you make changes to python code you should ensure this runs successfully. - -**Usage**: - -``` -qmk pytest -``` diff --git a/docs/cli_commands.md b/docs/cli_commands.md new file mode 100644 index 00000000000..5ab49abd279 --- /dev/null +++ b/docs/cli_commands.md @@ -0,0 +1,349 @@ +# QMK CLI Commands + +# User Commands + +## `qmk compile` + +This command allows you to compile firmware from any directory. You can compile JSON exports from , compile keymaps in the repo, or compile the keyboard in the current working directory. + +This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory. + +**Usage for Configurator Exports**: + +``` +qmk compile [-c] +``` + +**Usage for Keymaps**: + +``` +qmk compile [-c] [-e =] -kb -km +``` + +**Usage in Keyboard Directory**: + +Must be in keyboard directory with a default keymap, or in keymap directory for keyboard, or supply one with `--keymap ` +``` +qmk compile +``` + +**Usage for building all keyboards that support a specific keymap**: + +``` +qmk compile -kb all -km +``` + +**Example**: +``` +$ qmk config compile.keymap=default +$ cd ~/qmk_firmware/keyboards/planck/rev6 +$ qmk compile +Ψ Compiling keymap with make planck/rev6:default +... +``` +or with optional keymap argument + +``` +$ cd ~/qmk_firmware/keyboards/clueboard/66/rev4 +$ qmk compile -km 66_iso +Ψ Compiling keymap with make clueboard/66/rev4:66_iso +... +``` +or in keymap directory + +``` +$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak +$ qmk compile +Ψ Compiling keymap with make make gh60/satan:colemak +... +``` + +**Usage in Layout Directory**: + +Must be under `qmk_firmware/layouts/`, and in a keymap folder. +``` +qmk compile -kb +``` + +**Example**: +``` +$ cd ~/qmk_firmware/layouts/community/60_ansi/mechmerlin-ansi +$ qmk compile -kb dz60 +Ψ Compiling keymap with make dz60:mechmerlin-ansi +... +``` + +## `qmk flash` + +This command is similar to `qmk compile`, but can also target a bootloader. The bootloader is optional, and is set to `:flash` by default. To specify a different bootloader, use `-bl `. Visit the [Flashing Firmware](flashing.md) guide for more details of the available bootloaders. + +This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory. + +**Usage for Configurator Exports**: + +``` +qmk flash [-bl ] [-c] [-e =] +``` + +**Usage for Keymaps**: + +``` +qmk flash -kb -km [-bl ] [-c] [-e =] +``` + +**Listing the Bootloaders** + +``` +qmk flash -b +``` + +## `qmk config` + +This command lets you configure the behavior of QMK. For the full `qmk config` documentation see [CLI Configuration](cli_configuration.md). + +**Usage**: + +``` +qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN] +``` + +## `qmk doctor` + +This command examines your environment and alerts you to potential build or flash problems. It can fix many of them if you want it to. + +**Usage**: + +``` +qmk doctor [-y] [-n] +``` + +**Examples**: + +Check your environment for problems and prompt to fix them: + + qmk doctor + +Check your environment and automatically fix any problems found: + + qmk doctor -y + +Check your environment and report problems only: + + qmk doctor -n + +## `qmk info` + +Displays information about keyboards and keymaps in QMK. You can use this to get information about a keyboard, show the layouts, display the underlying key matrix, or to pretty-print JSON keymaps. + +**Usage**: + +``` +qmk info [-f FORMAT] [-m] [-l] [-km KEYMAP] [-kb KEYBOARD] +``` + +This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory. + +**Examples**: + +Show basic information for a keyboard: + + qmk info -kb planck/rev5 + +Show the matrix for a keyboard: + + qmk info -kb ergodox_ez -m + +Show a JSON keymap for a keyboard: + + qmk info -kb clueboard/california -km default + +## `qmk json2c` + +Creates a keymap.c from a QMK Configurator export. + +**Usage**: + +``` +qmk json2c [-o OUTPUT] filename +``` + +## `qmk c2json` + +Creates a keymap.json from a keymap.c. +**Note:** Parsing C source files is not easy, therefore this subcommand may not work your keymap. In some cases not using the C pre-processor helps. + +**Usage**: + +``` +qmk c2json -km KEYMAP -kb KEYBOARD [-q] [--no-cpp] [-o OUTPUT] filename +``` + +## `qmk lint` + +Checks over a keyboard and/or keymap and highlights common errors, problems, and anti-patterns. + +**Usage**: + +``` +qmk lint [-km KEYMAP] [-kb KEYBOARD] [--strict] +``` + +This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory. + +**Examples**: + +Do a basic lint check: + + qmk lint -kb rominronin/katana60/rev2 + +## `qmk list-keyboards` + +This command lists all the keyboards currently defined in `qmk_firmware` + +**Usage**: + +``` +qmk list-keyboards +``` + +## `qmk list-keymaps` + +This command lists all the keymaps for a specified keyboard (and revision). + +This command is directory aware. It will automatically fill in KEYBOARD if you are in a keyboard directory. + +**Usage**: + +``` +qmk list-keymaps -kb planck/ez +``` + +## `qmk new-keymap` + +This command creates a new keymap based on a keyboard's existing default keymap. + +This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory. + +**Usage**: + +``` +qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] +``` + +## `qmk clean` + +This command cleans up the `.build` folder. If `--all` is passed, any .hex or .bin files present in the `qmk_firmware` directory will also be deleted. + +**Usage**: + +``` +qmk clean [-a] +``` + +--- + +# Developer Commands + +## `qmk cformat` + +This command formats C code using clang-format. + +Run it with no arguments to format all core code that has been changed. Default checks `origin/master` with `git diff`, branch can be changed using `-b ` + +Run it with `-a` to format all core code, or pass filenames on the command line to run it on specific files. + +**Usage for specified files**: + +``` +qmk cformat [file1] [file2] [...] [fileN] +``` + +**Usage for all core files**: + +``` +qmk cformat -a +``` + +**Usage for only changed files against origin/master**: + +``` +qmk cformat +``` + +**Usage for only changed files against branch_name**: + +``` +qmk cformat -b branch_name +``` + +## `qmk docs` + +This command starts a local HTTP server which you can use for browsing or improving the docs. Default port is 8936. + +**Usage**: + +``` +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. + +**Usage**: + +``` +qmk kle2json [-f] +``` + +**Examples**: + +``` +$ qmk kle2json kle.txt +☒ File info.json already exists, use -f or --force to overwrite. +``` + +``` +$ qmk kle2json -f kle.txt -f +Ψ Wrote out to info.json +``` + +## `qmk pyformat` + +This command formats python code in `qmk_firmware`. + +**Usage**: + +``` +qmk pyformat +``` + +## `qmk pytest` + +This command runs the python test suite. If you make changes to python code you should ensure this runs successfully. + +**Usage**: + +``` +qmk pytest +``` diff --git a/docs/cli_configuration.md b/docs/cli_configuration.md index ad9ff291c81..50f5dc6e280 100644 --- a/docs/cli_configuration.md +++ b/docs/cli_configuration.md @@ -4,7 +4,7 @@ This document explains how `qmk config` works. # Introduction -Configuration for QMK CLI is a key/value system. Each key consists of a subcommand and an argument name separated by a period. This allows for a straightforward and direct translation between config keys and the arguments they set. +Configuration for the QMK CLI is a key/value system. Each key consists of a subcommand and an argument name separated by a period. This allows for a straightforward and direct translation between config keys and the arguments they set. ## Simple Example @@ -108,7 +108,7 @@ compile.keymap: skully -> None |-----|---------------|-------------| | user.keyboard | None | The keyboard path (Example: `clueboard/66/rev4`) | | user.keymap | None | The keymap name (Example: `default`) | -| user.name | None | The user's github username. | +| user.name | None | The user's GitHub username. | # All Configuration Options diff --git a/docs/cli_development.md b/docs/cli_development.md index cc8c59d067e..07c8f281bac 100644 --- a/docs/cli_development.md +++ b/docs/cli_development.md @@ -6,6 +6,18 @@ This document has useful information for developers wishing to write new `qmk` s The QMK CLI operates using the subcommand pattern made famous by git. The main `qmk` script is simply there to setup the environment and pick the correct entrypoint to run. Each subcommand is a self-contained module with an entrypoint (decorated by `@cli.subcommand()`) that performs some action and returns a shell returncode, or None. +## Developer mode: + +If you intend to maintain keyboards and/or contribute to QMK, you can enable the CLI's "Developer" mode: + +`qmk config user.developer=True` + +This will allow you to see all available subcommands. +**Note:** You will have to install additional requirements: +```bash +python3 -m pip install -r requirements-dev.txt +``` + # Subcommands [MILC](https://github.com/clueboard/milc) is the CLI framework `qmk` uses to handle argument parsing, configuration, logging, and many other features. It lets you focus on writing your tool without wasting your time writing glue code. @@ -32,7 +44,7 @@ def hello(cli): First we import the `cli` object from `milc`. This is how we interact with the user and control the script's behavior. We use `@cli.argument()` to define a command line flag, `--name`. This also creates a configuration variable named `hello.name` (and the corresponding `user.name`) which the user can set so they don't have to specify the argument. The `cli.subcommand()` decorator designates this function as a subcommand. The name of the subcommand will be taken from the name of the function. -Once inside our function we find a typical "Hello, World!" program. We use `cli.log` to access the underlying [Logger Object](https://docs.python.org/3.5/library/logging.html#logger-objects), whose behavior is user controllable. We also access the value for name supplied by the user as `cli.config.hello.name`. The value for `cli.config.hello.name` will be determined by looking at the `--name` argument supplied by the user, if not provided it will use the value in the `qmk.ini` config file, and if neither of those is provided it will fall back to the default supplied in the `cli.argument()` decorator. +Once inside our function we find a typical "Hello, World!" program. We use `cli.log` to access the underlying [Logger Object](https://docs.python.org/3.6/library/logging.html#logger-objects), whose behavior is user controllable. We also access the value for name supplied by the user as `cli.config.hello.name`. The value for `cli.config.hello.name` will be determined by looking at the `--name` argument supplied by the user, if not provided it will use the value in the `qmk.ini` config file, and if neither of those is provided it will fall back to the default supplied in the `cli.argument()` decorator. # User Interaction @@ -44,13 +56,13 @@ There are two main methods for outputting text in a subcommand- `cli.log` and `c You can use special tokens to colorize your text, to make it easier to understand the output of your program. See [Colorizing Text](#colorizing-text) below. -Both of these methods support built-in string formatting using python's [printf style string format operations](https://docs.python.org/3.5/library/stdtypes.html#old-string-formatting). You can use tokens such as `%s` and `%d` within your text strings then pass the values as arguments. See our Hello, World program above for an example. +Both of these methods support built-in string formatting using python's [printf style string format operations](https://docs.python.org/3.6/library/stdtypes.html#old-string-formatting). You can use tokens such as `%s` and `%d` within your text strings then pass the values as arguments. See our Hello, World program above for an example. You should never use the format operator (`%`) directly, always pass values as arguments. ### Logging (`cli.log`) -The `cli.log` object gives you access to a [Logger Object](https://docs.python.org/3.5/library/logging.html#logger-objects). We have configured our log output to show the user a nice emoji for each log level (or the log level name if their terminal does not support unicode.) This way the user can tell at a glance which messages are most important when something goes wrong. +The `cli.log` object gives you access to a [Logger Object](https://docs.python.org/3.6/library/logging.html#logger-objects). We have configured our log output to show the user a nice emoji for each log level (or the log level name if their terminal does not support unicode.) This way the user can tell at a glance which messages are most important when something goes wrong. The default log level is `INFO`. If the user runs `qmk -v ` the default log level will be set to `DEBUG`. @@ -198,7 +210,7 @@ Our tests can be found in `lib/python/qmk/tests/`. You will find both unit and i If your PR does not include a comprehensive set of tests please add comments like this to your code so that other people know where they can help: - # TODO(unassigned/): Write tests + # TODO(unassigned/): Write tests We use [nose2](https://nose2.readthedocs.io/en/latest/getting_started.html) to run our tests. You can refer to the nose2 documentation for more details on what you can do in your test functions. diff --git a/docs/coding_conventions_c.md b/docs/coding_conventions_c.md index 16e28b28849..c4bace66cc0 100644 --- a/docs/coding_conventions_c.md +++ b/docs/coding_conventions_c.md @@ -20,11 +20,11 @@ Most of our style is pretty easy to pick up on, but right now it's not entirely * We accept both forms of preprocessor if's: `#ifdef DEFINED` and `#if defined(DEFINED)` * If you are not sure which to prefer use the `#if defined(DEFINED)` form. * Do not change existing code from one style to the other, except when moving to a multiple condition `#if`. - * Do not put whitespace between `#` and `if`. - * When deciding how (or if) to indent directives keep these points in mind: - * Readability is more important than consistency. - * Follow the file's existing style. If the file is mixed follow the style that makes sense for the section you are modifying. - * When choosing to indent you can follow the indention level of the surrounding C code, or preprocessor directives can have their own indent level. Choose the style that best communicates the intent of your code. +* When deciding how (or if) to indent preprocessor directives, keep these points in mind: + * Readability is more important than consistency. + * Follow the file's existing style. If the file is mixed, follow the style that makes sense for the section you are modifying. + * When indenting, keep the hash at the start of the line and add whitespace between `#` and `if`, starting with 4 spaces after the `#`. + * You can follow the indention level of the surrounding C code, or preprocessor directives can have their own indentation levels. Choose the style that best communicates the intent of your code. Here is an example for easy reference: @@ -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. diff --git a/docs/coding_conventions_python.md b/docs/coding_conventions_python.md index 9dd95e4b731..47dff7f8eea 100644 --- a/docs/coding_conventions_python.md +++ b/docs/coding_conventions_python.md @@ -2,7 +2,7 @@ Most of our style follows PEP8 with some local modifications to make things less nit-picky. -* We target Python 3.5 for compatability with all supported platforms. +* We target Python 3.6 for compatability with all supported platforms. * We indent using four (4) spaces (soft tabs) * We encourage liberal use of comments * Think of them as a story describing the feature @@ -309,6 +309,18 @@ FIXME(username): Revisit this code when the frob feature is done. ...where username is your GitHub username. -# Unit Tests +# Testing -These are good. We should have some one day. +We use a combination of Integration and Unit testing to ensure that the our code is as bug-free as possible. All the tests can be found in `lib/python/qmk/tests/`. You can run all the tests with `qmk pytest`. + +At the time of this writing our tests are not very comprehensive. Looking at the current tests and writing new test cases for untested situations is a great way to both familiarize yourself with the codebase and contribute to QMK. + +## Integration Tests + +Integration tests can be found in `lib/python/qmk/tests/test_cli_commands.py`. This is where CLI commands are actually run and their overall behavior is verified. We use [`subprocess`](https://docs.python.org/3.6/library/subprocess.html#module-subprocess) to launch each CLI command and a combination of checking output and returncode to determine if the right thing happened. + +## Unit Tests + +The other `test_*.py` files in `lib/python/qmk/tests/` contain unit tests. You can write tests for individual functions inside `lib/python/qmk/` here. Generally these files are named after the module, with dots replaced by underscores. + +At the time of this writing we do not do any mocking for our tests. If you would like to help us change this please [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. diff --git a/docs/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md index 85dd440d37b..47a4844e7fc 100644 --- a/docs/compatible_microcontrollers.md +++ b/docs/compatible_microcontrollers.md @@ -9,21 +9,27 @@ 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: * [ATmega32A](https://www.microchip.com/wwwproducts/en/ATmega32A) * [ATmega328P](https://www.microchip.com/wwwproducts/en/ATmega328P) +* [ATmega328](https://www.microchip.com/wwwproducts/en/ATmega328) ## ARM -You can also use any ARM chip with USB that [ChibiOS](http://www.chibios.org) supports. Most have plenty of flash. Known to work are: +You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) supports. Most have plenty of flash. Known to work are: ### STMicroelectronics (STM32) * [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) diff --git a/docs/config_options.md b/docs/config_options.md index 0cf3fb78a69..aeaaf47aaf4 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -29,7 +29,9 @@ This level contains all of the options for that particular keymap. If you wish t This is a C header file that is one of the first things included, and will persist over the whole project (if included). Lots of variables can be set here and accessed elsewhere. The `config.h` file shouldn't be including other `config.h` files, or anything besides this: - #include "config_common.h" +```c +#include "config_common.h" +``` ## Hardware Options @@ -43,8 +45,6 @@ This is a C header file that is one of the first things included, and will persi * generally who/whatever brand produced the board * `#define PRODUCT Board` * the name of the keyboard -* `#define DESCRIPTION a keyboard` - * a short description of what the keyboard is * `#define MATRIX_ROWS 5` * the number of rows in your keyboard's matrix * `#define MATRIX_COLS 15` @@ -53,6 +53,8 @@ This is a C header file that is one of the first things included, and will persi * pins of the rows, from top to bottom * `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }` * pins of the columns, from left to right +* `#define MATRIX_IO_DELAY 30` + * the delay in microseconds when between changing matrix pin state and reading values * `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }` * pins unused by the keyboard for reference * `#define MATRIX_HAS_GHOST` @@ -65,20 +67,26 @@ 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` - * number of levels your backlight will have (maximum 15 excluding off) + * number of levels your backlight will have (maximum 31 excluding off) * `#define BACKLIGHT_BREATHING` * enables backlight breathing * `#define BREATHING_PERIOD 6` @@ -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`. @@ -113,9 +123,9 @@ If you define these options you will disable the associated feature, which can s * `#define NO_ACTION_ONESHOT` * disable one-shot modifiers * `#define NO_ACTION_MACRO` - * disable old style macro handling: MACRO() & action_get_macro + * disable old-style macro handling using `MACRO()`, `action_get_macro()` _(deprecated)_ * `#define NO_ACTION_FUNCTION` - * disable calling of action_function() from the fn_actions array (deprecated) + * disable old-style function handling using `fn_actions`, `action_function()` _(deprecated)_ ## Features That Can Be Enabled @@ -134,19 +144,27 @@ If you define these options you will enable the associated feature, which may in * enables handling for per key `TAPPING_TERM` settings * `#define RETRO_TAPPING` * tap anyway, even after TAPPING_TERM, if there was no other key interruption between press and release - * See [Retro Tapping](feature_advanced_keycodes.md#retro-tapping) for details + * 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` * makes tap and hold keys trigger the hold if another key is pressed before releasing, even if it hasn't hit the `TAPPING_TERM` - * See [Permissive Hold](feature_advanced_keycodes.md#permissive-hold) for details + * See [Permissive Hold](tap_hold.md#permissive-hold) for details +* `#define PERMISSIVE_HOLD_PER_KEY` + * enabled handling for per key `PERMISSIVE_HOLD` settings * `#define IGNORE_MOD_TAP_INTERRUPT` * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold, by enforcing the `TAPPING_TERM` for both keys. - * See [Mod tap interrupt](feature_advanced_keycodes.md#ignore-mod-tap-interrupt) for details + * See [Ignore Mod Tap Interrupt](tap_hold.md#ignore-mod-tap-interrupt) for details +* `#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY` + * enables handling for per key `IGNORE_MOD_TAP_INTERRUPT` settings * `#define TAPPING_FORCE_HOLD` * makes it possible to use a dual role key as modifier shortly after having been tapped - * See [Hold after tap](feature_advanced_keycodes.md#tapping-force-hold) + * See [Tapping Force Hold](tap_hold.md#tapping-force-hold) * Breaks any Tap Toggle functionality (`TT` or the One Shot Tap Toggle) +* `#define TAPPING_FORCE_HOLD_PER_KEY` + * enables handling for per key `TAPPING_FORCE_HOLD` settings * `#define LEADER_TIMEOUT 300` * how long before the leader key times out * If you're having issues finishing the sequence before it times out, you may need to increase the timeout setting. Or you may want to enable the `LEADER_PER_KEY_TIMING` option, which resets the timeout after each key is tapped. @@ -182,6 +200,15 @@ If you define these options you will enable the associated feature, which may in * pin the DI on the WS2812 is hooked-up to * `#define RGBLIGHT_ANIMATIONS` * run RGB animations +* `#define RGBLIGHT_LAYERS` + * Lets you define [lighting layers](feature_rgblight.md?id=lighting-layers) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state. +* `#define RGBLIGHT_MAX_LAYERS` + * Defaults to 8. Can be expanded up to 32 if more [lighting layers](feature_rgblight.md?id=lighting-layers) are needed. + * Note: Increasing the maximum will increase the firmware size and slow sync on split keyboards. +* `#define RGBLIGHT_LAYER_BLINK` + * Adds ability to [blink](feature_rgblight.md?id=lighting-layer-blink) a lighting layer for a specified number of milliseconds (e.g. to acknowledge an action). +* `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF` + * If defined, then [lighting layers](feature_rgblight?id=overriding-rgb-lighting-onoff-status) will be shown even if RGB Light is off. * `#define RGBLED_NUM 12` * number of LEDs * `#define RGBLIGHT_SPLIT` @@ -233,7 +260,10 @@ There are a few different ways to set handedness for split keyboards (listed in * `#define SPLIT_HAND_PIN B7` * For using high/low pin to determine handedness, low = right hand, high = left hand. Replace `B7` with the pin you are using. This is optional, and if you leave `SPLIT_HAND_PIN` undefined, then you can still use the EE_HANDS method or MASTER_LEFT / MASTER_RIGHT defines like the stock Let's Split uses. -* `#define EE_HANDS` (only works if `SPLIT_HAND_PIN` is not defined) +* `#define SPLIT_HAND_MATRIX_GRID ,` + * The handedness is determined by using the intersection of the keyswitches in the key matrix, which does not exist. Normally, when this intersection is shorted (level low), it is considered left. If you define `#define SPLIT_HAND_MATRIX_GRID_LOW_IS_RIGHT`, it is determined to be right when the level is low. + +* `#define EE_HANDS` (only works if `SPLIT_HAND_PIN` and `SPLIT_HAND_MATRIX_GRID` are not defined) * Reads the handedness value stored in the EEPROM after `eeprom-lefthand.eep`/`eeprom-righthand.eep` has been flashed to their respective halves. * `#define MASTER_RIGHT` @@ -272,9 +302,12 @@ There are a few different ways to set handedness for split keyboards (listed in * Default behavior for ARM * Required for AVR Teensy -* `#define SPLIT_USB_TIMEOUT 2500` +* `#define SPLIT_USB_TIMEOUT 2000` * Maximum timeout when detecting master/slave when using `SPLIT_USB_DETECT` +* `#define SPLIT_USB_TIMEOUT_POLL 10` + * Poll frequency when detecting master/slave when using `SPLIT_USB_DETECT` + # The `rules.mk` File This is a [make](https://www.gnu.org/software/make/manual/make.html) file that is included by the top-level `Makefile`. It is used to set some information about the MCU that we will be compiling for as well as enabling and disabling certain features. @@ -287,8 +320,25 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i * Defines which format (bin, hex) is copied to the root `qmk_firmware` folder after building. * `SRC` * Used to add files to the compilation/linking list. +* `LIB_SRC` + * Used to add files as a library to the compilation/linking list. + The files specified by `LIB_SRC` is linked after the files specified by `SRC`. + For example, if you specify: + ``` + SRC += a.c + LIB_SRC += lib_b.c + SRC += c.c + LIB_SRC += lib_d.c + ``` + The link order is as follows. + ``` + ... a.o c.o ... lib_b.a lib_d.a ... + ``` * `LAYOUTS` * A list of [layouts](feature_layouts.md) this keyboard supports. +* `LTO_ENABLE` + * Enables Link Time Optimization (LTO) when compiling the keyboard. This makes the process take longer, but it can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable). +However, this will automatically disable the legacy TMK Macros and Functions features, as these break when LTO is enabled. It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION`. (Note: This does not affect QMK [Macros](feature_macros.md) and [Layers](feature_layers.md).) ## AVR MCU Options * `MCU = atmega32u4` @@ -305,7 +355,7 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i * `bootloadHID` * `USBasp` -## Feature Options +## Feature Options :id=feature-options Use these to enable or disable building certain features. The more you have enabled the bigger your firmware will be, and you run the risk of building a firmware too large for your MCU. @@ -333,10 +383,8 @@ Use these to enable or disable building certain features. The more you have enab * MIDI controls * `UNICODE_ENABLE` * Unicode -* `BLUETOOTH_ENABLE` - * Legacy option to Enable Bluetooth with the Adafruit EZ-Key HID. See BLUETOOTH * `BLUETOOTH` - * Current options are AdafruitEzKey, AdafruitBLE, RN42 + * Current options are AdafruitBLE, RN42 * `SPLIT_KEYBOARD` * Enables split keyboard support (dual MCU like the let's split and bakingpy's boards) and includes all necessary files located at quantum/split_common * `CUSTOM_MATRIX` @@ -347,9 +395,6 @@ Use these to enable or disable building certain features. The more you have enab * Forces the keyboard to wait for a USB connection to be established before it starts up * `NO_USB_STARTUP_CHECK` * Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master. -* `LINK_TIME_OPTIMIZATION_ENABLE` - * Enables Link Time Optimization (`LTO`) when compiling the keyboard. This makes the process take longer, but can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable). However, this will automatically disable the old Macros and Functions features automatically, as these break when `LTO` is enabled. It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION` - * Alternatively, you can use `LTO_ENABLE` instead of `LINK_TIME_OPTIMIZATION_ENABLE`. ## USB Endpoint Limitations diff --git a/docs/configurator_default_keymaps.md b/docs/configurator_default_keymaps.md new file mode 100644 index 00000000000..30f9fa72f32 --- /dev/null +++ b/docs/configurator_default_keymaps.md @@ -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 :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//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 (`.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 `.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). diff --git a/docs/configurator_step_by_step.md b/docs/configurator_step_by_step.md new file mode 100644 index 00000000000..965012a907e --- /dev/null +++ b/docs/configurator_step_by_step.md @@ -0,0 +1,58 @@ +# QMK Configurator: Step by Step + +This page describes the steps for building your firmware in QMK Configurator. + +## Step 1: Select Your Keyboard + +Click the drop down box and select the keyboard you want to create a keymap for. + +?> If your keyboard has several versions, make sure you select the correct one. + +I'll say that again because it's important: + +!> **MAKE SURE YOU SELECT THE RIGHT VERSION!** + +If your keyboard has been advertised to be powered by QMK but is not in the list, chances are a developer hasn't gotten to it yet or we haven't had a chance to merge it in yet. File an issue at [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) requesting to support that particular keyboard, if there is no active [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) for it. There are also QMK powered keyboards that are in their manufacturer's own GitHub accounts. Double check for that as well. + +## Step 2: Select Your Keyboard Layout + +Choose the layout that best represents the keymap you want to create. Some keyboards do not have enough layouts or correct layouts defined yet. They will be supported in the future. + +!> Sometimes there isn't a layout that supports your exact build. In that case select `LAYOUT_all`. + +## Step 3: Name Your Keymap + +Call this keymap what you want. + +?> If you are running into issues when compiling, it may be worth changing this name, as it may already exist in the QMK Firmware repo. + +## Step 4: Define Your Keymap + +Keycode Entry is accomplished in one of 3 ways: + +1. Drag and drop +2. Clicking on an empty spot on the layout, then clicking the keycode you desire +3. Clicking on an empty spot on the layout, then pressing the physical key on your keyboard + +?> Hover your mouse over a key and a short blurb will tell you what that keycode does. For a more verbose description please see: + +* [Basic Keycode Reference](keycodes_basic.md) +* [Advanced Keycode Reference](feature_advanced_keycodes.md) + +!> If your selected layout doesn't match your physical build leave the unused keys blank. If you're not sure which key is in use, for example you have a one backspace key but `LAYOUT_all` has 2 keys, put the same keycode in both locations. + +## Step 5: Save Your Keymap for Future Changes + +When you're satisfied with your keymap or just want to work on it later, press the `Export Keymap` button. It will save your keymap to your computer. You can then load this .json file in the future by pressing the `Import Keymap` button. + +!> **CAUTION:** This is not the same type of .json file used for kbfirmware.com or any other tool. If you try to use this for those tools, or the .json from those tools with QMK Configurator, you will encounter problems. + +## Step 6: Compile Your Firmware File + +Press the green `Compile` button. + +When the compilation is done, you will be able to press the green `Download Firmware` button. + +## Next steps: Flashing Your Keyboard + +Please refer to [Flashing Firmware](newbs_flashing.md). diff --git a/docs/configurator_troubleshooting.md b/docs/configurator_troubleshooting.md new file mode 100644 index 00000000000..80b9713b64e --- /dev/null +++ b/docs/configurator_troubleshooting.md @@ -0,0 +1,26 @@ +# Configurator Troubleshooting + +## My .json file is not working + +If the .json file was generated with QMK Configurator, congratulations you have stumbled upon a bug. File an issue at [qmk_configurator](https://github.com/qmk/qmk_configurator/issues). + +If not... how did you miss the big bold message at the top saying not to use other .json files? + +## There are extra spaces in my layout? What do I do? + +If you're referring to having three spots for space bar, the best course of action is to just fill them all with Space. The same can be done for Backspace and Shift keys. + +## What is the keycode for... + +Please see: + +* [Basic Keycode Reference](keycodes_basic.md) +* [Advanced Keycode Reference](feature_advanced_keycodes.md) + +## It won't compile + +Please double check the other layers of your keymap to make sure there are no random keys present. + +## Problems and Bugs + +We are always accepting customer requests and bug reports. Please file them at [qmk_configurator](https://github.com/qmk/qmk_configurator/issues). diff --git a/docs/contributing.md b/docs/contributing.md index c4d5057a07a..fe48619e418 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -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. @@ -101,7 +101,7 @@ enum my_keycodes { }; ``` -### Previewing the Documentation +### Previewing the Documentation :id=previewing-the-documentation Before opening a pull request, you can preview your changes if you have set up the development environment by running this command from the `qmk_firmware/` folder: diff --git a/docs/custom_matrix.md b/docs/custom_matrix.md new file mode 100644 index 00000000000..cfa900a33d3 --- /dev/null +++ b/docs/custom_matrix.md @@ -0,0 +1,108 @@ +# Custom Matrix + +QMK provides a mechanism to supplement or replace the default matrix scanning routine with your own code. + +The reasons to use this feature include: + +* Extra hardware between the keyboard's switches and MCU pins + * I/O multiplexer + * Line decoder +* Irregular switch matrix + * Simultaneous use of `COL2ROW` and `ROW2COL` + +## Prerequisites + +Implementing custom matrix usually involves compilation of an additional source file. It is recommended that for consistency, this file is called `matrix.c`. + +Add a new file to your keyboard directory: +```text +keyboards//matrix.c +``` + +And to configure compilation for the new file, add this to your `rules.mk`: +```make +SRC += matrix.c +``` + +## 'lite' + +Provides a default implementation for various scanning functions, reducing the boilerplate code when implementing custom matrix. +To configure it, add this to your `rules.mk`: + +```make +CUSTOM_MATRIX = lite +``` + +And implement the following functions in a `matrix.c` file in your keyboard folder: + +```c +void matrix_init_custom(void) { + // TODO: initialize hardware here +} + +bool matrix_scan_custom(matrix_row_t current_matrix[]) { + bool matrix_has_changed = false; + + // TODO: add matrix scanning routine here + + return matrix_has_changed; +} +``` + + +## Full Replacement + +When more control over the scanning routine is required, you can choose to implement the full scanning routine. +To configure it, add this to your rules.mk: + +```make +CUSTOM_MATRIX = yes +``` + +And implement the following functions in a `matrix.c` file in your keyboard folder: + +```c +matrix_row_t matrix_get_row(uint8_t row) { + // TODO: return the requested row data +} + +void matrix_print(void) { + // TODO: use print() to dump the current matrix state to console +} + +void matrix_init(void) { + // TODO: initialize hardware and global matrix state here + + // Unless hardware debouncing - Init the configured debounce routine + debounce_init(MATRIX_ROWS); + + // This *must* be called for correct keyboard behavior + matrix_init_quantum(); +} + +uint8_t matrix_scan(void) { + bool matrix_has_changed = false; + + // TODO: add matrix scanning routine here + + // Unless hardware debouncing - use the configured debounce routine + debounce(raw_matrix, matrix, MATRIX_ROWS, changed); + + // This *must* be called for correct keyboard behavior + matrix_scan_quantum(); + + return matrix_has_changed; +} +``` + +And also provide defaults for the following callbacks: + +```c +__attribute__((weak)) void matrix_init_kb(void) { matrix_init_user(); } + +__attribute__((weak)) void matrix_scan_kb(void) { matrix_scan_user(); } + +__attribute__((weak)) void matrix_init_user(void) {} + +__attribute__((weak)) void matrix_scan_user(void) {} +``` diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index 71a30bc7c6b..694b421e79c 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -4,7 +4,7 @@ For a lot of people a custom keyboard is about more than sending button presses This page does not assume any special knowledge about QMK, but reading [Understanding QMK](understanding_qmk.md) will help you understand what is going on at a more fundamental level. -## A Word on Core vs Keyboards vs Keymap +## A Word on Core vs Keyboards vs Keymap :id=a-word-on-core-vs-keyboards-vs-keymap We have structured QMK as a hierarchy: @@ -34,7 +34,7 @@ enum my_keycodes { }; ``` -## Programming the Behavior of Any Keycode +## Programming the Behavior of Any Keycode :id=programming-the-behavior-of-any-keycode When you want to override the behavior of an existing key, or define the behavior for a new key, you should use the `process_record_kb()` and `process_record_user()` functions. These are called by QMK during key processing before the actual key event is handled. If these functions return `true` QMK will process the keycodes as usual. That can be handy for extending the functionality of a key rather than replacing it. If these functions return `false` QMK will skip the normal key handling, and it will be up to you to send any key up or down events that are required. @@ -57,7 +57,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { case KC_ENTER: // Play a tone when enter is pressed if (record->event.pressed) { - PLAY_NOTE_ARRAY(tone_qwerty); + PLAY_SONG(tone_qwerty); } return true; // Let QMK send the enter press/release events default: @@ -88,108 +88,6 @@ keyrecord_t record { } ``` -# LED Control - -QMK provides methods to read 5 of the LEDs defined in the HID spec: - -* Num Lock -* Caps Lock -* Scroll Lock -* Compose -* Kana - -There are two ways to get the lock LED state: - -* by implementing `bool led_update_kb(led_t led_state)` or `_user(led_t led_state)`; or -* by calling `led_t host_keyboard_led_state()` - -!> `host_keyboard_led_state()` may already reflect a new value before `led_update_user()` is called. - -Two more deprecated functions exist that provide the LED state as a `uint8_t`: - -* `uint8_t led_set_kb(uint8_t usb_led)` and `_user(uint8_t usb_led)` -* `uint8_t host_keyboard_leds()` - -## `led_update_user()` - -This function will be called when the state of one of those 5 LEDs changes. It receives the LED state as a struct parameter. - -By convention, return `true` from `led_update_user()` to get the `led_update_kb()` hook to run its code, and -return `false` when you would prefer not to run the code in `led_update_kb()`. - -Some examples include: - - - overriding the LEDs to use them for something else like layer indication - - return `false` because you do not want the `_kb()` function to run, as it would override your layer behavior. - - play a sound when an LED turns on or off. - - return `true` because you want the `_kb` function to run, and this is in addition to the default LED behavior. - -?> Because the `led_set_*` functions return `void` instead of `bool`, they do not allow for overriding the keyboard LED control, and thus it's recommended to use `led_update_*` instead. - -### Example `led_update_kb()` Implementation - -```c -bool led_update_kb(led_t led_state) { - bool res = led_update_user(led_state); - if(res) { - // writePin sets the pin high for 1 and low for 0. - // In this example the pins are inverted, setting - // it low/0 turns it on, and high/1 turns the LED off. - // This behavior depends on whether the LED is between the pin - // and VCC or the pin and GND. - writePin(B0, !led_state.num_lock); - writePin(B1, !led_state.caps_lock); - writePin(B2, !led_state.scroll_lock); - writePin(B3, !led_state.compose); - writePin(B4, !led_state.kana); - } - return res; -} -``` - -### Example `led_update_user()` Implementation - -This incomplete example would play a sound if Caps Lock is turned on or off. It returns `true`, because you also want the LEDs to maintain their state. - -```c -#ifdef AUDIO_ENABLE - float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND); - float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND); -#endif - -bool led_update_user(led_t led_state) { - #ifdef AUDIO_ENABLE - static uint8_t caps_state = 0; - if (caps_state != led_state.caps_lock) { - led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off); - caps_state = led_state.caps_lock; - } - #endif - return true; -} -``` - -### `led_update_*` Function Documentation - -* Keyboard/Revision: `bool led_update_kb(led_t led_state)` -* Keymap: `bool led_update_user(led_t led_state)` - -## `host_keyboard_led_state()` - -Call this function to get the last received LED state as a `led_t`. This is useful for reading the LED state outside `led_update_*`, e.g. in [`matrix_scan_user()`](#matrix-scanning-code). - -## Setting Physical LED State - -Some keyboard implementations provide convenience methods for setting the state of the physical LEDs. - -### Ergodox Boards - -The Ergodox implementations provide `ergodox_right_led_1`/`2`/`3_on`/`off()` to turn individual LEDs on or off, as well as `ergodox_right_led_on`/`off(uint8_t led)` to turn them on or off by their index. - -In addition, it is possible to specify the brightness level of all LEDs with `ergodox_led_all_set(uint8_t n)`; of individual LEDs with `ergodox_right_led_1`/`2`/`3_set(uint8_t n)`; or by index with `ergodox_right_led_set(uint8_t led, uint8_t n)`. - -Ergodox boards also define `LED_BRIGHTNESS_LO` for the lowest brightness and `LED_BRIGHTNESS_HI` for the highest brightness (which is the default). - # Keyboard Initialization Code There are several steps in the keyboard initialization process. Depending on what you want to do, it will influence which function you should use. @@ -287,6 +185,14 @@ This function gets called at every matrix scan, which is basically as often as t You should use this function if you need custom matrix scanning code. It can also be used for custom status output (such as LEDs or a display) or other functionality that you want to trigger regularly even when the user isn't typing. +# Keyboard housekeeping + +* Keyboard/Revision: `void housekeeping_task_kb(void)` +* Keymap: `void housekeeping_task_user(void)` + +This function gets called at the end of all QMK processing, before starting the next iteration. You can safely assume that QMK has dealt with the last matrix scan at the time that these functions are invoked -- layer states have been updated, USB reports have been sent, LEDs have been updated, and displays have been drawn. + +Similar to `matrix_scan_*`, these are called as often as the MCU can handle. To keep your board responsive, it's suggested to do as little as possible during these function calls, potentially throtting their behaviour if you do indeed require implementing something special. # Keyboard Idling/Wake Code @@ -313,13 +219,13 @@ void suspend_wakeup_init_user(void) { * Keyboard/Revision: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)` * Keymap: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)` -# Layer Change Code +# Layer Change Code :id=layer-change-code This runs code every time that the layers get changed. This can be useful for layer indication, or custom layer handling. ### Example `layer_state_set_*` Implementation -This example shows how to set the [RGB Underglow](feature_rgblight.md) lights based on the layer, using the Planck as an example +This example shows how to set the [RGB Underglow](feature_rgblight.md) lights based on the layer, using the Planck as an example. ```c layer_state_t layer_state_set_user(layer_state_t state) { @@ -343,6 +249,11 @@ layer_state_t layer_state_set_user(layer_state_t state) { return state; } ``` + +Use the `IS_LAYER_ON_STATE(state, layer)` and `IS_LAYER_OFF_STATE(state, layer)` macros to check the status of a particular layer. + +Outside of `layer_state_set_*` functions, you can use the `IS_LAYER_ON(layer)` and `IS_LAYER_OFF(layer)` macros to check global layer state. + ### `layer_state_set_*` Function Documentation * Keyboard/Revision: `layer_state_t layer_state_set_kb(layer_state_t state)` @@ -438,7 +349,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { case KC_ENTER: // Play a tone when enter is pressed if (record->event.pressed) { - PLAY_NOTE_ARRAY(tone_qwerty); + PLAY_SONG(tone_qwerty); } return true; // Let QMK send the enter press/release events case RGB_LYR: // This allows me to use underglow as layer indication, or as normal @@ -449,7 +360,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { layer_state_set(layer_state); // then immediately update the layer color } } - return false; break; + return false; case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // For any of the RGB codes (see quantum_keycodes.h, L400 for reference) if (record->event.pressed) { //This disables layer indication, as it's assumed that if you're changing this ... you want that disabled if (user_config.rgb_layer_change) { // only if this is enabled @@ -486,31 +397,3 @@ And you're done. The RGB layer indication will only work if you want it to. And * Keymap: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` and `void eeconfig_update_user(uint32_t val)` The `val` is the value of the data that you want to write to EEPROM. And the `eeconfig_read_*` function return a 32 bit (DWORD) value from the EEPROM. - -# Custom Tapping Term - -By default, the tapping term is defined globally, and is not configurable by key. For most users, this is perfectly fine. But in come cases, dual function keys would be greatly improved by different timeouts than `LT` keys, or because some keys may be easier to hold than others. Instead of using custom key codes for each, this allows for per key configurable `TAPPING_TERM`. - -To enable this functionality, you need to add `#define TAPPING_TERM_PER_KEY` to your `config.h`, first. - - -## Example `get_tapping_term` Implementation - -To change the `TAPPING TERM` based on the keycode, you'd want to add something like the following to your `keymap.c` file: - -```c -uint16_t get_tapping_term(uint16_t keycode) { - switch (keycode) { - case SFT_T(KC_SPC): - return TAPPING_TERM + 1250; - case LT(1, KC_GRV): - return 130; - default: - return TAPPING_TERM; - } -} -``` - -### `get_tapping_term` Function Documentation - -Unlike many of the other functions here, there isn't a need (or even reason) to have a quantum or keyboard level function. Only a user level function is useful here, so no need to mark it as such. diff --git a/docs/data_driven_config.md b/docs/data_driven_config.md new file mode 100644 index 00000000000..c2ad4fed8fc --- /dev/null +++ b/docs/data_driven_config.md @@ -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_()` 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_/src/info_config.h` +* `.build/obj_/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()`. diff --git a/docs/de/README.md b/docs/de/README.md index 88239d45d49..5de496a201f 100644 --- a/docs/de/README.md +++ b/docs/de/README.md @@ -9,11 +9,11 @@ ## Was ist QMK Firmware? -QMK (*Quantum Mechanical Keyboard*) ist eine Open-Source-Community, welche die QMK-Firmware, die QMK-Toolbox, [qmk.fm](https://qmk.fm) und diese Dokumententation betreut. QMK-Firmware ist eine Weiterentwicklung der [tmk\_keyboard](http://github.com/tmk/tmk_keyboard)-Tastatur-Firmware mit vielen nützlichen Zusatzfunktionen für Atmel AVR-Prozessoren. Ursprünglich wurde sie für Produkte von [OLKB](http://olkb.com), das [ErgoDox EZ](http://www.ergodox-ez.com) und das [Clueboard](http://clueboard.co/) entwickelt. Im Laufe der Zeit wurde sie mit Hilfe von [ChibiOS](http://chibios.org) auch für die ARM-Architektur angepasst. Außerdem ist es inzwischen möglich, auch handverdrahtete Tastaturen und selbst geätzte PCBs mit QMK zu verwenden. +QMK (*Quantum Mechanical Keyboard*) ist eine Open-Source-Community, welche die QMK-Firmware, die QMK-Toolbox, [qmk.fm](https://qmk.fm) und diese Dokumententation betreut. QMK-Firmware ist eine Weiterentwicklung der [tmk\_keyboard](https://github.com/tmk/tmk_keyboard)-Tastatur-Firmware mit vielen nützlichen Zusatzfunktionen für Atmel AVR-Prozessoren. Ursprünglich wurde sie für Produkte von [OLKB](https://olkb.com), das [ErgoDox EZ](https://www.ergodox-ez.com) und das [Clueboard](https://clueboard.co/) entwickelt. Im Laufe der Zeit wurde sie mit Hilfe von [ChibiOS](https://chibios.org) auch für die ARM-Architektur angepasst. Außerdem ist es inzwischen möglich, auch handverdrahtete Tastaturen und selbst geätzte PCBs mit QMK zu verwenden. ## Bezugsquelle für QMK -Wenn Du vorhast, deine Tastatur, Tastaturbelegung oder Features zu QMK beizusteuern, geht das am einfachsten, indem Du das [Repository auf Github](https://github.com/qmk/qmk_firmware#fork-destination-box) forkst, die Änderungen in deinem lokalen Repo vornimmst und anschließend einen [Pull Request](https://github.com/qmk/qmk_firmware/pulls) einreichst. +Wenn Du vorhast, deine Tastatur, Tastaturbelegung oder Features zu QMK beizusteuern, geht das am einfachsten, indem Du das [Repository auf GitHub](https://github.com/qmk/qmk_firmware#fork-destination-box) forkst, die Änderungen in deinem lokalen Repo vornimmst und anschließend einen [Pull Request](https://github.com/qmk/qmk_firmware/pulls) einreichst. Ansonsten kannst Du es als [zip](https://github.com/qmk/qmk_firmware/zipball/master) oder [tar](https://github.com/qmk/qmk_firmware/tarball/master) herunterladen, oder es direkt via git klonen (`git clone git@github.com:qmk/qmk_firmware.git` bzw. `git clone https://github.com/qmk/qmk_firmware.git`). diff --git a/docs/de/_summary.md b/docs/de/_summary.md index f3ce806baa2..ffbd292bd45 100644 --- a/docs/de/_summary.md +++ b/docs/de/_summary.md @@ -11,7 +11,7 @@ * [QMK CLI](de/cli.md) * [QMK CLI Konfiguration](de/cli_configuration.md) * [Zu QMK beitragen](de/contributing.md) - * [Anleitung für Github](de/getting_started_github.md) + * [Anleitung für GitHub](de/getting_started_github.md) * [Nach Hilfe fragen](de/getting_started_getting_help.md) * [Breaking Changes](de/breaking_changes.md) @@ -77,7 +77,7 @@ * [Macros](de/feature_macros.md) * [Mouse Keys](de/feature_mouse_keys.md) * [OLED Driver](de/feature_oled_driver.md) - * [One Shot Keys](de/feature_advanced_keycodes.md#one-shot-keys) + * [One Shot Keys](de/one_shot_keys.md) * [Pointing Device](de/feature_pointing_device.md) * [PS/2 Mouse](de/feature_ps2_mouse.md) * [RGB Lighting](de/feature_rgblight.md) @@ -98,6 +98,7 @@ * [ISP Flashing Guide](de/isp_flashing_guide.md) * [ARM Debugging Guide](de/arm_debugging.md) * [I2C Driver](de/i2c_driver.md) + * [SPI Driver](de/spi_driver.md) * [GPIO Controls](de/internals_gpio_control.md) * [Proton C Conversion](de/proton_c_conversion.md) @@ -108,7 +109,7 @@ * Andere Themen * [Eclipse mit QMK](de/other_eclipse.md) * [VSCode mit QMK](de/other_vscode.md) - * [Support](de/support.md) + * [Support](de/getting_started_getting_help.md) * [Übersetzungen](de/translating.md) * QMK Internals (In Progress) diff --git a/docs/de/newbs_getting_started.md b/docs/de/newbs_getting_started.md index 8240f2bafa0..188cf97e0a2 100644 --- a/docs/de/newbs_getting_started.md +++ b/docs/de/newbs_getting_started.md @@ -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` diff --git a/docs/de/newbs_learn_more_resources.md b/docs/de/newbs_learn_more_resources.md index 59b72152dd1..ac5adb0c12f 100644 --- a/docs/de/newbs_learn_more_resources.md +++ b/docs/de/newbs_learn_more_resources.md @@ -6,7 +6,7 @@ Git Ressourcen: * [Gutes allgemeines Tutorial](https://www.codecademy.com/learn/learn-git) (auf Englisch) * [Git spielerisch anhand von Beispielen lernen](https://learngitbranching.js.org/) (auf Englisch) -* [Mehr über den allgemeinen Umgang mit Github](getting_started_github.md) +* [Mehr über den allgemeinen Umgang mit GitHub](getting_started_github.md) * [Mehr über Git im Bezug zu QMK](contributing.md) Mehr über die Arbeit mit der Befehlszeile: diff --git a/docs/de/newbs_testing_debugging.md b/docs/de/newbs_testing_debugging.md index acc067e10f9..4d4e7cfee65 100644 --- a/docs/de/newbs_testing_debugging.md +++ b/docs/de/newbs_testing_debugging.md @@ -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 +```c +#include "print.h" +``` Danach stehen dir verschiedene Druck-Funktionen zur Verfügung: diff --git a/docs/documentation_best_practices.md b/docs/documentation_best_practices.md index 77c226117c2..c193fed6b86 100644 --- a/docs/documentation_best_practices.md +++ b/docs/documentation_best_practices.md @@ -61,4 +61,4 @@ This page describes my cool feature. You can use my cool feature to make coffee |KC_SUGAR||Order Sugar| ``` -Place your documentation into `docs/feature_.md`, and add that file to the appropriate place in `docs/_sidebar.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page. +Place your documentation into `docs/feature_.md`, and add that file to the appropriate place in `docs/_summary.md`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page. diff --git a/docs/documentation_templates.md b/docs/documentation_templates.md index 85d3893b71a..e22dbf23874 100644 --- a/docs/documentation_templates.md +++ b/docs/documentation_templates.md @@ -2,14 +2,14 @@ This page documents the templates you should use when submitting new Keymaps and Keyboards to QMK. -## Keymap `readme.md` Template +## 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 diff --git a/docs/driver_installation_zadig.md b/docs/driver_installation_zadig.md index b04a6fbef1b..81b8408868f 100644 --- a/docs/driver_installation_zadig.md +++ b/docs/driver_installation_zadig.md @@ -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 ` Bootloader` and will also have the VID `03EB`. - - For most ARM keyboards, it will be called `STM32 BOOTLOADER`, and have a VID/PID of `0483:DF11`. +Zadig should automatically detect the bootloader device, but you may sometimes need to check **Options → List All Devices** and select the device from the dropdown instead. !> If Zadig lists one or more devices with the `HidUsb` driver, your keyboard is probably not in bootloader mode. The arrow will be colored orange and you will be asked to confirm modifying a system driver. **Do not** proceed if this is the case! -If the arrow appears green, select the driver, and click **Install Driver**. The `libusb-win32` driver will usually work for AVR, and `WinUSB` for ARM, but if you still cannot flash the board, try installing a different driver from the list. For flashing a USBaspLoader device via command line with msys2, the `libusbk` driver is recommended, otherwise `libusb-win32` will work fine if you are using QMK Toolbox for flashing. +If the arrow appears green, select the driver, and click **Install Driver**. See the [list of known bootloaders](#list-of-known-bootloaders) for the correct driver to install. ![Zadig with a bootloader driver correctly installed](https://i.imgur.com/b8VgXzx.png) @@ -43,6 +38,40 @@ Right-click it and hit **Uninstall device**. Make sure to tick **Delete the driv ![The Device Uninstall dialog, with the "delete driver" checkbox ticked](https://i.imgur.com/aEs2RuA.png) -Click **Action → Scan for hardware changes**. At this point, you should be able to type again. Double check in Zadig that the keyboard device(s) are using the `HidUsb` driver. If so, you're all done, and your board should be functional again! +Click **Action → Scan for hardware changes**. At this point, you should be able to type again. Double check in Zadig that the keyboard device(s) are using the `HidUsb` driver. If so, you're all done, and your board should be functional again! Otherwise, repeat the process until Zadig reports the correct driver. ?> A full reboot of your computer may sometimes be necessary at this point, to get Windows to pick up the new driver. + +## List of Known Bootloaders + +This is a list of known bootloader devices and their USB vendor and product IDs, as well as the correct driver to assign for flashing with QMK. Note that the usbser and HidUsb drivers are built in to Windows, and cannot be assigned with Zadig - if your device has an incorrect driver, you must use the Device Manager to uninstall it as described in the previous section. + +The device name here is the name that appears in Zadig, and may not be what the Device Manager or QMK Toolbox displays. + +|Bootloader |Device Name |VID/PID |Driver | +|-------------|------------------------------|--------------|-------| +|`atmel-dfu` |ATmega16u2 DFU |`03EB:2FEF` |libusb0| +|`atmel-dfu` |ATmega32U2 DFU |`03EB:2FF0` |libusb0| +|`atmel-dfu` |ATm16U4 DFU V1.0.2 |`03EB:2FF3` |libusb0| +|`atmel-dfu` |ATm32U4DFU |`03EB:2FF4` |libusb0| +|`atmel-dfu` |*none* (AT90USB64) |`03EB:2FF9` |libusb0| +|`atmel-dfu` |AT90USB128 DFU |`03EB:2FFB` |libusb0| +|`qmk-dfu` |(keyboard name) Bootloader |As `atmel-dfu`|libusb0| +|`halfkay` |*none* |`16C0:0478` |HidUsb | +|`caterina` |Pro Micro 3.3V |`1B4F:9203` |usbser | +|`caterina` |Pro Micro 5V |`1B4F:9205` |usbser | +|`caterina` |LilyPadUSB |`1B4F:9207` |usbser | +|`caterina` |Pololu A-Star 32U4 Bootloader |`1FFB:0101` |usbser | +|`caterina` |Arduino Leonardo |`2341:0036` |usbser | +|`caterina` |Arduino Micro |`2341:0037` |usbser | +|`caterina` |Adafruit Feather 32u4 |`239A:000C` |usbser | +|`caterina` |Adafruit ItsyBitsy 32u4 3V |`239A:000D` |usbser | +|`caterina` |Adafruit ItsyBitsy 32u4 5V |`239A:000E` |usbser | +|`caterina` |Arduino Leonardo |`2A03:0036` |usbser | +|`caterina` |Arduino Micro |`2A03:0037` |usbser | +|`bootloadHID`|HIDBoot |`16C0:05DF` |HidUsb | +|`USBasp` |USBasp |`16C0:05DC` |libusbK| +|`apm32-dfu` |APM32 DFU ISP Mode |`314B:0106` |WinUSB | +|`stm32-dfu` |STM32 BOOTLOADER |`0483:DF11` |WinUSB | +|`kiibohd` |Kiibohd DFU Bootloader |`1C11:B007` |WinUSB | +|`stm32duino` |Maple 003 |`1EAF:0003` |WinUSB | diff --git a/docs/eeprom_driver.md b/docs/eeprom_driver.md new file mode 100644 index 00000000000..e2c262546d9 --- /dev/null +++ b/docs/eeprom_driver.md @@ -0,0 +1,72 @@ +# EEPROM Driver Configuration :id=eeprom-driver-configuration + +The EEPROM driver can be swapped out depending on the needs of the keyboard, or whether extra hardware is present. + +Driver | Description +-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- +`EEPROM_DRIVER = vendor` (default) | Uses the on-chip driver provided by the chip manufacturer. For AVR, this is provided by avr-libc. This is supported on ARM for a subset of chips -- STM32F3xx, STM32F1xx, and STM32F072xB will be emulated by writing to flash. STM32L0xx and STM32L1xx will use the onboard dedicated true EEPROM. Other chips will generally act as "transient" below. +`EEPROM_DRIVER = i2c` | Supports writing to I2C-based 24xx EEPROM chips. See the driver section below. +`EEPROM_DRIVER = spi` | Supports writing to SPI-based 25xx EEPROM chips. See the driver section below. +`EEPROM_DRIVER = transient` | Fake EEPROM driver -- supports reading/writing to RAM, and will be discarded when power is lost. + +## Vendor Driver Configuration :id=vendor-eeprom-driver-configuration + +#### STM32 L0/L1 Configuration :id=stm32l0l1-eeprom-driver-configuration + +!> Resetting EEPROM using an STM32L0/L1 device takes up to 1 second for every 1kB of internal EEPROM used. + +`config.h` override | Description | Default Value +------------------------------------|--------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------- +`#define STM32_ONBOARD_EEPROM_SIZE` | The size of the EEPROM to use, in bytes. Erase times can be high, so it's configurable here, if not using the default value. | Minimum required to cover base _eeconfig_ data, or `1024` if VIA is enabled. + +## I2C Driver Configuration :id=i2c-eeprom-driver-configuration + +Currently QMK supports 24xx-series chips over I2C. As such, requires a working i2c_master driver configuration. You can override the driver configuration via your config.h: + +`config.h` override | Description | Default Value +------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------ +`#define EXTERNAL_EEPROM_I2C_BASE_ADDRESS` | Base I2C address for the EEPROM -- shifted left by 1 as per i2c_master requirements | 0b10100000 +`#define EXTERNAL_EEPROM_I2C_ADDRESS(addr)` | Calculated I2C address for the EEPROM | `(EXTERNAL_EEPROM_I2C_BASE_ADDRESS)` +`#define EXTERNAL_EEPROM_BYTE_COUNT` | Total size of the EEPROM in bytes | 8192 +`#define EXTERNAL_EEPROM_PAGE_SIZE` | Page size of the EEPROM in bytes, as specified in the datasheet | 32 +`#define EXTERNAL_EEPROM_ADDRESS_SIZE` | The number of bytes to transmit for the memory location within the EEPROM | 2 +`#define EXTERNAL_EEPROM_WRITE_TIME` | Write cycle time of the EEPROM, as specified in the datasheet | 5 + +Default values and extended descriptions can be found in `drivers/eeprom/eeprom_i2c.h`. + +Alternatively, there are pre-defined hardware configurations for available chips/modules: + +Module | Equivalent `#define` | Source +-----------------|---------------------------------|------------------------------------------ +CAT24C512 EEPROM | `#define EEPROM_I2C_CAT24C512` | +RM24C512C EEPROM | `#define EEPROM_I2C_RM24C512C` | +24LC64 EEPROM | `#define EEPROM_I2C_24LC64` | +24LC128 EEPROM | `#define EEPROM_I2C_24LC128` | +24LC256 EEPROM | `#define EEPROM_I2C_24LC256` | +MB85RC256V FRAM | `#define EEPROM_I2C_MB85RC256V` | + +?> If you find that the EEPROM is not cooperating, ensure you've correctly shifted up your EEPROM address by 1. For example, the datasheet might state the address as `0b01010000` -- the correct value of `EXTERNAL_EEPROM_I2C_BASE_ADDRESS` needs to be `0b10100000`. + +## SPI Driver Configuration :id=spi-eeprom-driver-configuration + +Currently QMK supports 25xx-series chips over SPI. As such, requires a working spi_master driver configuration. You can override the driver configuration via your config.h: + +`config.h` override | Description | Default Value +-----------------------------------------------|--------------------------------------------------------------------------------------|-------------- +`#define EXTERNAL_EEPROM_SPI_SLAVE_SELECT_PIN` | SPI Slave select pin in order to inform that the EEPROM is currently being addressed | _none_ +`#define EXTERNAL_EEPROM_SPI_CLOCK_DIVISOR` | Clock divisor used to divide the peripheral clock to derive the SPI frequency | `64` +`#define EXTERNAL_EEPROM_BYTE_COUNT` | Total size of the EEPROM in bytes | 8192 +`#define EXTERNAL_EEPROM_PAGE_SIZE` | Page size of the EEPROM in bytes, as specified in the datasheet | 32 +`#define EXTERNAL_EEPROM_ADDRESS_SIZE` | The number of bytes to transmit for the memory location within the EEPROM | 2 + +!> There's no way to determine if there is an SPI EEPROM actually responding. Generally, this will result in reads of nothing but zero. + +## Transient Driver configuration :id=transient-eeprom-driver-configuration + +The only configurable item for the transient EEPROM driver is its size: + +`config.h` override | Description | Default Value +------------------------------- | ----------------------------------------- | ------------- +`#define TRANSIENT_EEPROM_SIZE` | Total size of the EEPROM storage in bytes | 64 + +Default values and extended descriptions can be found in `drivers/eeprom/eeprom_transient.h`. diff --git a/docs/es/README.md b/docs/es/README.md index d39b2780085..be063ad7c01 100644 --- a/docs/es/README.md +++ b/docs/es/README.md @@ -9,11 +9,11 @@ ## ¿Qué es el firmware QMK? -QMK (*Quantum Mechanical Keyboard*) es una comunidad open source que mantiene el firmware QMK, QMK Toolbox, qmk.fm, y estos documentos. El firmware QMK es un firmware para teclados basado en [tmk\_keyboard](http://github.com/tmk/tmk_keyboard) con algunas características útiles para controladores Atmel AVR, y más específicamente, la [línea de productos OLKB](http://olkb.com), el teclado [ErgoDox EZ](http://www.ergodox-ez.com), y la [línea de productos Clueboard](http://clueboard.co/). También ha sido portado a chips ARM chips usando ChibiOS. Lo puedes utilizar para manejar tu propio teclado ya sea cableado a mano o basado en una PCB personalizada. +QMK (*Quantum Mechanical Keyboard*) es una comunidad open source que mantiene el firmware QMK, QMK Toolbox, qmk.fm, y estos documentos. El firmware QMK es un firmware para teclados basado en [tmk\_keyboard](https://github.com/tmk/tmk_keyboard) con algunas características útiles para controladores Atmel AVR, y más específicamente, la [línea de productos OLKB](https://olkb.com), el teclado [ErgoDox EZ](https://www.ergodox-ez.com), y la [línea de productos Clueboard](https://clueboard.co/). También ha sido portado a chips ARM chips usando ChibiOS. Lo puedes utilizar para manejar tu propio teclado ya sea cableado a mano o basado en una PCB personalizada. ## Cómo conseguirlo -Si estás pensando en contribuir con un keymap, teclado, or característica a QMK, la manera más sencilla es hacer un [fork del repositorio en Github](https://github.com/qmk/qmk_firmware#fork-destination-box), y clonar tu repositorio localmente para hacer los cambios, subirlos, y abir un [Pull Request](https://github.com/qmk/qmk_firmware/pulls) desde tu fork. +Si estás pensando en contribuir con un keymap, teclado, or característica a QMK, la manera más sencilla es hacer un [fork del repositorio en GitHub](https://github.com/qmk/qmk_firmware#fork-destination-box), y clonar tu repositorio localmente para hacer los cambios, subirlos, y abir un [Pull Request](https://github.com/qmk/qmk_firmware/pulls) desde tu fork. De cualquier manera, también puedes descargarlo directamente en formatos ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), o clonarlo via git (`git@github.com:qmk/qmk_firmware.git`), o https (`https://github.com/qmk/qmk_firmware.git`). @@ -29,4 +29,4 @@ Este ejemplo compilaría la revisión `rev4` del teclado `planck` con el keymap ## Cómo personalizar -QMK tiene montones de [características](es/features.md) para explorar, y una buena cantidad de [documentación de referencia](http://docs.qmk.fm) en la que sumergirse. Se pueden sacar provecho de la mayoría de las características modificando tu [keymap](es/keymap.md), y cambiando los [keycodes](es/keycodes.md). +QMK tiene montones de [características](es/features.md) para explorar, y una buena cantidad de [documentación de referencia](https://docs.qmk.fm) en la que sumergirse. Se pueden sacar provecho de la mayoría de las características modificando tu [keymap](es/keymap.md), y cambiando los [keycodes](es/keycodes.md). diff --git a/docs/es/_summary.md b/docs/es/_summary.md index 03bf05ba8b5..aa2a0ca5d97 100644 --- a/docs/es/_summary.md +++ b/docs/es/_summary.md @@ -11,7 +11,7 @@ * [QMK CLI](es/cli.md) * [Configuración de QMK CLI](es/cli_configuration.md) * [Contribuyendo a QMK](es/contributing.md) - * [Cómo usar Github](es/getting_started_github.md) + * [Cómo usar GitHub](es/getting_started_github.md) * [Obtener ayuda](es/getting_started_getting_help.md) * [Cambios incompatibles](es/breaking_changes.md) @@ -77,7 +77,7 @@ * [Macros](es/feature_macros.md) * [Teclas del ratón](es/feature_mouse_keys.md) * [Driver OLED](es/feature_oled_driver.md) - * [Teclas One Shot](es/feature_advanced_keycodes.md#one-shot-keys) + * [Teclas One Shot](es/one_shot_keys.md) * [Dispositivo de apuntado](es/feature_pointing_device.md) * [Ratón PS/2](es/feature_ps2_mouse.md) * [Iluminación RGB](es/feature_rgblight.md) @@ -98,6 +98,7 @@ * [Guía de flasheado de ISP](es/isp_flashing_guide.md) * [Guía de depuración de ARM](es/arm_debugging.md) * [Driver I2C](es/i2c_driver.md) + * [Driver SPI](es/spi_driver.md) * [Controles GPIO](es/internals_gpio_control.md) * [Conversión Proton C](es/proton_c_conversion.md) @@ -108,7 +109,7 @@ * Otros temas * [Usando Eclipse con QMK](es/other_eclipse.md) * [Usando VSCode con QMK](es/other_vscode.md) - * [Soporte](es/support.md) + * [Soporte](es/getting_started_getting_help.md) * [Cómo añadir traducciones](es/translating.md) * QMK Internals (En progreso) diff --git a/docs/es/becoming_a_qmk_collaborator.md b/docs/es/becoming_a_qmk_collaborator.md deleted file mode 100644 index f88846df24e..00000000000 --- a/docs/es/becoming_a_qmk_collaborator.md +++ /dev/null @@ -1,9 +0,0 @@ -# Llegar a ser un colaborador QMK - -Un colaborador QMK es un maker o diseñador de teclados que tiene interés en ayudar a QMK a crecer y mantener sus teclado(s), y alentar a los usuarios y clientes a presentar herramientas, ideas, y keymaps. Siempre procuramos agregar más teclados y colaboradores, pero pedimos que cumplan los siguientes requisitos: - -* **Tener un PCB disponible a la venta.** Desafortunadamente, hay demasiada variación y complicaciones con teclados cableados a mano. -* **Realizar el mantenimiento de tu teclado en QMK.** Este podría requirir un setup inicial para hacer que tu teclado funcione, pero también podría incluir adaptarse a cambios hecho al base de QMK que podrían descomponer o rendir código superfluo. -* **Aprobar e incorporar pull requests de keymaps para tu teclado.** Nos gusta alentar a los usuarios a contribuir sus keymaps para que otros los vean y los puedan usar para crear sus propios. - -Si sientes que cumples los requisitos, ¡mándanos un email a hello@qmk.fm con una introducción y algunos enlaces para tu teclado! diff --git a/docs/es/hardware.md b/docs/es/hardware.md index 8d7579c9efe..085c7e67457 100644 --- a/docs/es/hardware.md +++ b/docs/es/hardware.md @@ -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) diff --git a/docs/es/hardware_avr.md b/docs/es/hardware_avr.md index 4236292a12d..f8c426381f2 100644 --- a/docs/es/hardware_avr.md +++ b/docs/es/hardware_avr.md @@ -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. ## `.c` @@ -67,7 +67,7 @@ El archivo `config.h` es donde configuras el hardware y el conjunto de caracter En la parte superior de `config.h` encontrarás ajustes relacionados con USB. Estos controlan la apariencia de tu teclado en el Sistema Operativo. Si no tienes una buena razón para cambiar debes dejar el `VENDOR_ID` como `0xFEED`. Para el `PRODUCT_ID` debes seleccionar un número que todavía no esté en uso. -Cambia las líneas de `MANUFACTURER`, `PRODUCT`, y `DESCRIPTION` para reflejar con precisión tu teclado. +Cambia las líneas de `MANUFACTURER` y `PRODUCT` para reflejar con precisión tu teclado. ```c #define VENDOR_ID 0xFEED @@ -75,7 +75,6 @@ Cambia las líneas de `MANUFACTURER`, `PRODUCT`, y `DESCRIPTION` para reflejar c #define DEVICE_VER 0x0001 #define MANUFACTURER Tú #define PRODUCT mi_teclado_fantastico -#define DESCRIPTION Un teclado personalizado ``` ?> Windows y macOS mostrarán el `MANUFACTURER` y `PRODUCT` en la lista de dispositivos USB. `lsusb` en Linux toma estos de la lista mantenida por el [Repositorio de ID USB](http://www.linux-usb.org/usb-ids.html) por defecto. `lsusb -v` mostrará los valores reportados por el dispositivo, y también están presentes en los registros del núcleo después de conectarlo. diff --git a/docs/es/hardware_drivers.md b/docs/es/hardware_drivers.md index 7b74b34b456..e0a9736068c 100644 --- a/docs/es/hardware_drivers.md +++ b/docs/es/hardware_drivers.md @@ -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). - diff --git a/docs/es/hardware_keyboard_guidelines.md b/docs/es/hardware_keyboard_guidelines.md index 2cde2b39fb7..a505cc5ce13 100644 --- a/docs/es/hardware_keyboard_guidelines.md +++ b/docs/es/hardware_keyboard_guidelines.md @@ -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 ) 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 `//` (nombre sigue el mismo formato que el anterior), se sirven en `http://qmk.fm//`, y se generan páginas de `/_pages//` 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 `//` (nombre sigue el mismo formato que el anterior), se sirven en `https://qmk.fm//`, y se generan páginas de `/_pages//` 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. diff --git a/docs/es/newbs.md b/docs/es/newbs.md index ebb4b6ac2d1..7e08b679c38 100644 --- a/docs/es/newbs.md +++ b/docs/es/newbs.md @@ -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 diff --git a/docs/es/newbs_best_practices.md b/docs/es/newbs_best_practices.md index fc2afb9ed24..2f72eff788c 100644 --- a/docs/es/newbs_best_practices.md +++ b/docs/es/newbs_best_practices.md @@ -6,7 +6,7 @@ Este documento procura instruir a los novatos en las mejores prácticas para ten En este documento suponemos un par de cosas: -1. Tienes una cuenta de Github, y has hecho un [fork del repo qmk_firmware](getting_started_github.md) en tu cuenta. +1. Tienes una cuenta de GitHub, y has hecho un [fork del repo qmk_firmware](getting_started_github.md) en tu cuenta. 2. Has [configurado tu entorno de desarrollo](newbs_getting_started.md?id=environment-setup). diff --git a/docs/es/newbs_building_firmware_configurator.md b/docs/es/newbs_building_firmware_configurator.md index a2573432401..60d67f5fa4f 100644 --- a/docs/es/newbs_building_firmware_configurator.md +++ b/docs/es/newbs_building_firmware_configurator.md @@ -4,7 +4,7 @@ El [Configurador QMK](https://config.qmk.fm) es un entorno gráfico online que g ?> **Por favor sigue estos pasos en orden.** -Ve el [Video tutorial](https://youtu.be/tx54jkRC9ZY) +Ve el [Video tutorial](https://www.youtube.com/watch?v=-imgglzDMdY) El Configurador QMK functiona mejor con Chrome/Firefox. @@ -21,7 +21,7 @@ Lo diré otra vez porque es importante !> **ASEGÚRATE DE QUE SELECCIONAS LA VERSIÓN CORRECTA!** -Si se ha anunciado que tu teclado funciona con QMK pero no está en la lista, es probable que un desarrollador no se haya encargado de él aún o que todavía no hemos tenido la oportunidad de incluirlo. Abre un issue en [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) solicitando soportar ese teclado un particular, si no hay un [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) activo para ello. Hay también teclados que funcionan con QMK que están en las cuentas de github de sus manufacturantes. Acuérdate de comprobar esto también. +Si se ha anunciado que tu teclado funciona con QMK pero no está en la lista, es probable que un desarrollador no se haya encargado de él aún o que todavía no hemos tenido la oportunidad de incluirlo. Abre un issue en [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) solicitando soportar ese teclado un particular, si no hay un [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) activo para ello. Hay también teclados que funcionan con QMK que están en las cuentas de GitHub de sus manufacturantes. Acuérdate de comprobar esto también. ## Eligiendo el layout de tu teclado diff --git a/docs/es/newbs_getting_started.md b/docs/es/newbs_getting_started.md index eb0d6d36fbd..046fdee27ec 100644 --- a/docs/es/newbs_getting_started.md +++ b/docs/es/newbs_getting_started.md @@ -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`. diff --git a/docs/es/newbs_learn_more_resources.md b/docs/es/newbs_learn_more_resources.md index 413b9ffa5ef..34fd7556bf1 100644 --- a/docs/es/newbs_learn_more_resources.md +++ b/docs/es/newbs_learn_more_resources.md @@ -6,7 +6,7 @@ Recursos de Git: * [Excelente tutorial general](https://www.codecademy.com/learn/learn-git) * [Juego de Git para aprender usando ejemplos](https://learngitbranching.js.org/) -* [Recursos de Git para aprender más sobre Github](getting_started_github.md) +* [Recursos de Git para aprender más sobre GitHub](getting_started_github.md) * [Recursos de Git dirigidos específicamente a QMK](contributing.md) diff --git a/docs/es/newbs_testing_debugging.md b/docs/es/newbs_testing_debugging.md index ef7412f15c3..69f6984658e 100644 --- a/docs/es/newbs_testing_debugging.md +++ b/docs/es/newbs_testing_debugging.md @@ -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 +```c +#include "print.h" +``` Después de eso puedes utilzar algunas funciones print diferentes: diff --git a/docs/faq.md b/docs/faq.md deleted file mode 100644 index 506f57a72b4..00000000000 --- a/docs/faq.md +++ /dev/null @@ -1,6 +0,0 @@ -# Frequently Asked Questions - -* [General](faq_general.md) -* [Building or Compiling QMK](faq_build.md) -* [Debugging and Troubleshooting QMK](faq_debug.md) -* [Keymap](faq_keymap.md) diff --git a/docs/faq_build.md b/docs/faq_build.md index 618ae40f3b1..b86f2177a04 100644 --- a/docs/faq_build.md +++ b/docs/faq_build.md @@ -13,68 +13,29 @@ An example of using `sudo`, when your controller is ATMega32u4: or just: - $ sudo make ::dfu + $ sudo make ::flash Note that running `make` with `sudo` is generally ***not*** a good idea, and you should use one of the former methods, if possible. -### Linux `udev` Rules -On Linux, you'll need proper privileges to access the MCU. You can either use -`sudo` when flashing firmware, or place these files in `/etc/udev/rules.d/`. Once added run the following: -```console +### Linux `udev` Rules :id=linux-udev-rules + +On Linux, you'll need proper privileges to communicate with the bootloader device. You can either use `sudo` when flashing firmware (not recommended), or place [this file](https://github.com/qmk/qmk_firmware/tree/master/util/udev/50-qmk.rules) into `/etc/udev/rules.d/`. + +Once added, run the following: + +``` sudo udevadm control --reload-rules sudo udevadm trigger ``` -**/etc/udev/rules.d/50-atmel-dfu.rules:** -``` -# Atmel ATMega32U4 -SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", MODE:="0666" -# Atmel USBKEY AT90USB1287 -SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", MODE:="0666" -# Atmel ATMega32U2 -SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="0666" -``` - -**/etc/udev/rules.d/52-tmk-keyboard.rules:** -``` -# tmk keyboard products https://github.com/tmk/tmk_keyboard -SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666" -``` -**/etc/udev/rules.d/54-input-club-keyboard.rules:** +**Note:** With older versions of ModemManager (< 1.12), filtering only works when not in strict mode. The following commands can update that setting: ``` -# Input Club keyboard bootloader -SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666" -``` - -**/etc/udev/rules.d/55-caterina.rules:** -``` -# ModemManager should ignore the following devices -ATTRS{idVendor}=="2a03", ENV{ID_MM_DEVICE_IGNORE}="1" -ATTRS{idVendor}=="2341", ENV{ID_MM_DEVICE_IGNORE}="1" -``` - -**Note:** ModemManager filtering only works when not in strict mode, the following commands can update that settings: -```console -sudo sed -i 's/--filter-policy=strict/--filter-policy=default/' /lib/systemd/system/ModemManager.service +printf '[Service]\nExecStart=\nExecStart=/usr/sbin/ModemManager --filter-policy=default' | sudo tee /etc/systemd/system/ModemManager.service.d/policy.conf sudo systemctl daemon-reload sudo systemctl restart ModemManager ``` -**/etc/udev/rules.d/56-dfu-util.rules:** -``` -# stm32duino -SUBSYSTEMS=="usb", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0003", MODE:="0666" -# Generic stm32 -SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE:="0666" -``` - -**/etc/udev/rules.d/57-bootloadhid.rules:** -``` -# bootloadHID -SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05df", MODE:="0666" -``` - ### Serial device is not detected in bootloader mode on Linux Make sure your kernel has appropriate support for your device. If your device uses USB ACM, such as Pro Micro (Atmega32u4), make sure to include `CONFIG_USB_ACM=y`. Other devices may require `USB_SERIAL` and any of its sub options. @@ -96,53 +57,8 @@ Also see this. https://github.com/tmk/tmk_keyboard/issues/150 You can buy a really unique VID:PID here. I don't think you need this for personal use. -- http://www.obdev.at/products/vusb/license.html -- http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1 - -## BOOTLOADER_SIZE for AVR -Note that Teensy2.0++ bootloader size is 2048byte. Some Makefiles may have wrong comment. - -``` -# Boot Section Size in *bytes* -# Teensy halfKay 512 -# Teensy++ halfKay 2048 -# Atmel DFU loader 4096 (TMK Alt Controller) -# LUFA bootloader 4096 -# USBaspLoader 2048 -OPT_DEFS += -DBOOTLOADER_SIZE=2048 -``` - -## `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)` on MacOS -This is an issue with updating on brew, causing symlinks that avr-gcc depend on getting mangled. - -The solution is to remove and reinstall all affected modules. - -``` -brew rm avr-gcc -brew rm dfu-programmer -brew rm dfu-util -brew rm gcc-arm-none-eabi -brew rm avrdude -brew install avr-gcc -brew install dfu-programmer -brew install dfu-util -brew install gcc-arm-none-eabi -brew install avrdude -``` - -### avr-gcc 8.1 and LUFA - -If you updated your avr-gcc to above 7 you may see errors involving LUFA. For example: - -`lib/lufa/LUFA/Drivers/USB/Class/Device/AudioClassDevice.h:380:5: error: 'const' attribute on function returning 'void'` - -For now, you need to rollback avr-gcc to 7 in brew. - -``` -brew uninstall --force avr-gcc -brew install avr-gcc@8 -brew link --force avr-gcc@8 -``` +- https://www.obdev.at/products/vusb/license.html +- https://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1 ### I just flashed my keyboard and it does nothing/keypresses don't register - it's also ARM (rev6 planck, clueboard 60, hs60v2, etc...) (Feb 2019) Due to how EEPROM works on ARM based chips, saved settings may no longer be valid. This affects the default layers, and *may*, under certain circumstances we are still figuring out, make the keyboard unusable. Resetting the EEPROM will correct this. diff --git a/docs/faq_debug.md b/docs/faq_debug.md index 6c66defbd44..13a649bfa2f 100644 --- a/docs/faq_debug.md +++ b/docs/faq_debug.md @@ -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,150 +107,25 @@ 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`. + +On many Linux distros you can avoid having to run hid_listen as root +by creating a file called `/etc/udev/rules.d/70-hid-listen.rules` with +the following content: + +``` +SUBSYSTEM=="hidraw", ATTRS{idVendor}=="abcd", ATTRS{idProduct}=="def1", TAG+="uaccess", RUN{builtin}+="uaccess" +``` + +Replace abcd and def1 with your keyboard's vendor and product id, +letters must be lowercase. The `RUN{builtin}+="uaccess"` part is only +needed for older distros. + ## Can't Get Message on Console Check: - *hid_listen* finds your device. See above. -- Enable debug with pressing **Magic**+d. See [Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands). -- set `debug_enable=true`. See [Testing and Debugging](newbs_testing_debugging.md#debugging) -- try using 'print' function instead of debug print. See **common/print.h**. -- disconnect other devices with console function. See [Issue #97](https://github.com/tmk/tmk_keyboard/issues/97). - -## Linux or UNIX Like System Requires Super User Privilege -Just use 'sudo' to execute *hid_listen* with privilege. -``` -$ sudo hid_listen -``` - -Or add an *udev rule* for TMK devices with placing a file in rules directory. The directory may vary on each system. - -File: /etc/udev/rules.d/52-tmk-keyboard.rules(in case of Ubuntu) -``` -# tmk keyboard products https://github.com/tmk/tmk_keyboard -SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666" -``` - -*** - -# Miscellaneous -## Safety Considerations - -You probably don't want to "brick" your keyboard, making it impossible -to rewrite firmware onto it. Here are some of the parameters to show -what things are (and likely aren't) too risky. - -- If your keyboard map does not include RESET, then, to get into DFU - mode, you will need to press the reset button on the PCB, which - requires unscrewing the bottom. -- Messing with tmk_core / common files might make the keyboard - inoperable -- Too large a .hex file is trouble; `make dfu` will erase the block, - test the size (oops, wrong order!), which errors out, failing to - flash the keyboard, leaving it in DFU mode. - - To this end, note that the maximum .hex file size on Planck is - 7000h (28672 decimal) - -``` -Linking: .build/planck_rev4_cbbrowne.elf [OK] -Creating load file for Flash: .build/planck_rev4_cbbrowne.hex [OK] - -Size after: - text data bss dec hex filename - 0 22396 0 22396 577c planck_rev4_cbbrowne.hex -``` - - - The above file is of size 22396/577ch, which is less than - 28672/7000h - - As long as you have a suitable alternative .hex file around, you - can retry, loading that one - - Some of the options you might specify in your keyboard's Makefile - consume extra memory; watch out for BOOTMAGIC_ENABLE, - MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE -- DFU tools do /not/ allow you to write into the bootloader (unless - you throw in extra fruit salad of options), so there is little risk - there. -- EEPROM has around a 100000 write cycle. You shouldn't rewrite the - firmware repeatedly and continually; that'll burn the EEPROM - eventually. - -## NKRO Doesn't work -First you have to compile firmware with this build option `NKRO_ENABLE` in **Makefile**. - -Try `Magic` **N** command(`LShift+RShift+N` by default) when **NKRO** still doesn't work. You can use this command to toggle between **NKRO** and **6KRO** mode temporarily. In some situations **NKRO** doesn't work you need to switch to **6KRO** mode, in particular when you are in BIOS. - -If your firmware built with `BOOTMAGIC_ENABLE` you need to turn its switch on by `BootMagic` **N** command(`Space+N` by default). This setting is stored in EEPROM and kept over power cycles. - -https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch - - -## TrackPoint Needs Reset Circuit (PS/2 Mouse Support) -Without reset circuit you will have inconsistent result due to improper initialize of the hardware. See circuit schematic of TPM754. - -- http://geekhack.org/index.php?topic=50176.msg1127447#msg1127447 -- http://www.mikrocontroller.net/attachment/52583/tpm754.pdf - - -## Can't Read Column of Matrix Beyond 16 -Use `1UL<<16` instead of `1<<16` in `read_cols()` in [matrix.h] when your columns goes beyond 16. - -In C `1` means one of [int] type which is [16 bit] in case of AVR so you can't shift left more than 15. You will get unexpected zero when you say `1<<16`. You have to use [unsigned long] type with `1UL`. - -http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279 - -## Special Extra Key Doesn't Work (System, Audio Control Keys) -You need to define `EXTRAKEY_ENABLE` in `rules.mk` to use them in QMK. - -``` -EXTRAKEY_ENABLE = yes # Audio control and System control -``` - -## Wakeup from Sleep Doesn't Work - -In Windows check `Allow this device to wake the computer` setting in Power **Management property** tab of **Device Manager**. Also check BIOS setting. - -Pressing any key during sleep should wake host. - -## Using Arduino? - -**Note that Arduino pin naming is different from actual chip.** For example, Arduino pin `D0` is not `PD0`. Check circuit with its schematics yourself. - -- http://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf -- http://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf - -Arduino Leonardo and micro have **ATMega32U4** and can be used for TMK, though Arduino bootloader may be a problem. - -## Enabling JTAG - -By default, the JTAG debugging interface is disabled as soon as the keyboard starts up. JTAG-capable MCUs come from the factory with the `JTAGEN` fuse set, and it takes over certain pins of the MCU that the board may be using for the switch matrix, LEDs, etc. - -If you would like to keep JTAG enabled, just add the following to your `config.h`: - -```c -#define NO_JTAG_DISABLE -``` - -## USB 3 Compatibility -I heard some people have a problem with USB 3 port, try USB 2 port. - - -## Mac Compatibility -### OS X 10.11 and Hub -https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034 - - -## Problem on BIOS (UEFI)/Resume (Sleep & Wake)/Power Cycles -Some people reported their keyboard stops working on BIOS and/or after resume(power cycles). - -As of now root of its cause is not clear but some build options seem to be related. In Makefile try to disable those options like `CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE` and/or others. - -https://github.com/tmk/tmk_keyboard/issues/266 -https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778 - - - -## FLIP Doesn't Work -### `AtLibUsbDfu.dll` Not Found -Remove current driver and reinstall one FLIP provides from DeviceManager. -http://imgur.com/a/bnwzy +- 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). diff --git a/docs/faq_general.md b/docs/faq_general.md index f14272ede8f..56b150da29b 100644 --- a/docs/faq_general.md +++ b/docs/faq_general.md @@ -4,6 +4,44 @@ [QMK](https://github.com/qmk), short for Quantum Mechanical Keyboard, is a group of people building tools for custom keyboards. We started with the [QMK firmware](https://github.com/qmk/qmk_firmware), a heavily modified fork of [TMK](https://github.com/tmk/tmk_keyboard). +## I don't know where to start! + +If this is the case, then you should start with our [Newbs Guide](newbs.md). There is a lot of great info there, and that should cover everything you need to get started. + +If that's an issue, hop onto the [QMK Configurator](https://config.qmk.fm), as that will handle a majority of what you need there. + +## How can I flash the firmware I built? + +First, head to the [Compiling/Flashing FAQ Page](faq_build.md). There is a good deal of info there, and you'll find a bunch of solutions to common issues there. + +## What if I have an issue that isn't covered here? + +Okay, that's fine. Then please check the [open issues in our GitHub](https://github.com/qmk/qmk_firmware/issues) to see if somebody is experiencing the same thing (make sure it's not just similar, but actually the same). + +If you can't find anything, then please open a [new issue](https://github.com/qmk/qmk_firmware/issues/new)! + +## What if I found a bug? + +Then please open an [issue](https://github.com/qmk/qmk_firmware/issues/new), and if you know how to fix it, open up a Pull Request on GitHub with the fix. + +## But `git` and `GitHub` are intimidating! + +Don't worry, we have some pretty nice [Guidelines](newbs_git_best_practices.md) on how to start using `git` and GitHub to make things easier to develop. + +Additionally, you can find additional `git` and GitHub related links [here](newbs_learn_more_resources.md). + +## I have a Keyboard that I want to add support for + +Awesome! Open up a Pull Request for it. We'll review the code, and merge it! + +### What if I want to brand it with `QMK`? + +That's amazing! We would love to assist you with that! + +In fact, we have a [whole page](https://qmk.fm/powered/) dedicated to adding QMK Branding to your page and keyboard. This covers pretty much everything you need (knowledge and images) to officially support QMK. + +If you have any questions about this, open an issue or head to [Discord](https://discord.gg/Uq7gcHh). + ## What Differences Are There Between QMK and TMK? TMK was originally designed and implemented by [Jun Wako](https://github.com/tmk). QMK started as [Jack Humbert](https://github.com/jackhumbert)'s fork of TMK for the Planck. After a while Jack's fork had diverged quite a bit from TMK, and in 2015 Jack decided to rename his fork to QMK. diff --git a/docs/faq_keymap.md b/docs/faq_keymap.md index 2d00e8bef95..c30e17990f2 100644 --- a/docs/faq_keymap.md +++ b/docs/faq_keymap.md @@ -11,9 +11,20 @@ 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: - + ![Keyboard Layout Image](https://i.imgur.com/5wsh5wM.png) +## How Can I Make Custom Names For Complex Keycodes? + +Sometimes, for readability's sake, it's useful to define custom names for some keycodes. People often define custom names using `#define`. For example: + +```c +#define FN_CAPS LT(_FL, KC_CAPSLOCK) +#define ALT_TAB LALT(KC_TAB) +``` + +This will allow you to use `FN_CAPS` and `ALT_TAB` in your keymap, keeping it more readable. + ## Some Of My Keys Are Swapped Or Not Working QMK has two features, Bootmagic and Command, which allow you to change the behavior of your keyboard on the fly. This includes, but is not limited to, swapping Ctrl/Caps, disabling Gui, swapping Alt/Gui, swapping Backspace/Backslash, disabling all keys, and other behavioral modifications. @@ -31,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 @@ -49,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 diff --git a/docs/faq_misc.md b/docs/faq_misc.md new file mode 100644 index 00000000000..9ab2b69a809 --- /dev/null +++ b/docs/faq_misc.md @@ -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 diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index ec3807f400e..75b7fef89b5 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -1,328 +1,179 @@ -# Advanced Keycodes - -Your keymap can include keycodes that are more advanced than normal, for example keys that switch layers or send modifiers when held, but send regular keycodes when tapped. This page documents the functions that are available to you. - -## Assigning Custom Names - -People often define custom names using `#define`. For example: - -```c -#define FN_CAPS LT(_FL, KC_CAPSLOCK) -#define ALT_TAB LALT(KC_TAB) -``` - -This will allow you to use `FN_CAPS` and `ALT_TAB` in your keymap, keeping it more readable. - -## Caveats - -Currently, `LT()` and `MT()` are limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. Modifiers specified as part of a Layer Tap or Mod Tap's keycode will be ignored. If you need to apply modifiers to your tapped keycode, [Tap Dance](feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this. - -Additionally, if at least one right-handed modifier is specified in a Mod Tap or Layer Tap, it will cause all modifiers specified to become right-handed, so it is not possible to mix and match the two. - -# Switching and Toggling Layers - -These functions allow you to activate layers in various ways. Note that layers are not generally independent layouts -- multiple layers can be activated at once, and it's typical for layers to use `KC_TRNS` to allow keypresses to pass through to lower layers. For a detailed explanation of layers, see [Keymap Overview](keymap.md#keymap-and-layers). When using momentary layer switching with MO(), LM(), TT(), or LT(), make sure to leave the key on the above layers transparent or it may not work as intended. - -* `DF(layer)` - switches the default layer. The default layer is the always-active base layer that other layers stack on top of. See below for more about the default layer. This might be used to switch from QWERTY to Dvorak layout. (Note that this is a temporary switch that only persists until the keyboard loses power. To modify the default layer in a persistent way requires deeper customization, such as calling the `set_single_persistent_default_layer` function inside of [process_record_user](custom_quantum_functions.md#programming-the-behavior-of-any-keycode).) -* `MO(layer)` - momentarily activates *layer*. As soon as you let go of the key, the layer is deactivated. -* `LM(layer, mod)` - Momentarily activates *layer* (like `MO`), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers: `MOD_LCTL`, `MOD_LSFT`, `MOD_LALT`, `MOD_LGUI` (note the use of `MOD_` constants instead of `KC_`). These modifiers can be combined using bitwise OR, e.g. `LM(_RAISE, MOD_LCTL | MOD_LALT)`. -* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped. Only supports layers 0-15. -* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys](#one-shot-keys) for details and additional functionality. -* `TG(layer)` - toggles *layer*, activating it if it's inactive and vice versa -* `TO(layer)` - activates *layer* and de-activates all other layers (except your default layer). This function is special, because instead of just adding/removing one layer to your active layer stack, it will completely replace your current active layers, uniquely allowing you to replace higher layers with a lower one. This is activated on keydown (as soon as the key is pressed). -* `TT(layer)` - Layer Tap-Toggle. If you hold the key down, *layer* is activated, and then is de-activated when you let go (like `MO`). If you repeatedly tap it, the layer will be toggled on or off (like `TG`). It needs 5 taps by default, but you can change this by defining `TAPPING_TOGGLE` -- for example, `#define TAPPING_TOGGLE 2` to toggle on just two taps. - -# Working with Layers - -Care must be taken when switching layers, it's possible to lock yourself into a layer with no way to deactivate that layer (without unplugging your keyboard.) We've created some guidelines to help users avoid the most common problems. - -## Beginners - -If you are just getting started with QMK you will want to keep everything simple. Follow these guidelines when setting up your layers: - -* Setup layer 0 as your default, "base" layer. This is your normal typing layer, and could be whatever layout you want (qwerty, dvorak, colemak, etc.). It's important to set this as the lowest layer since it will typically have most or all of the keyboard's keys defined, so would block other layers from having any effect if it were above them (i.e., had a higher layer number). -* Arrange your layers in a "tree" layout, with layer 0 as the root. Do not try to enter the same layer from more than one other layer. -* In a layer's keymap, only reference higher-numbered layers. Because layers are processed from the highest-numbered (topmost) active layer down, modifying the state of lower layers can be tricky and error-prone. - -## Intermediate Users - -Sometimes you need more than one base layer. For example, if you want to switch between QWERTY and Dvorak, switch between layouts for different countries, or switch your layout for different videogames. Your base layers should always be the lowest numbered layers. When you have multiple base layers you should always treat them as mutually exclusive. When one base layer is on the others are off. - -## Advanced Users - -Once you have a good feel for how layers work and what you can do, you can get more creative. The rules listed in the beginner section will help you be successful by avoiding some of the tricker details but they can be constraining, especially for ultra-compact keyboard users. Understanding how layers work will allow you to use them in more advanced ways. - -Layers stack on top of each other in numerical order. When determining what a keypress does, QMK scans the layers from the top down, stopping when it reaches the first active layer that is not set to `KC_TRNS`. As a result if you activate a layer that is numerically lower than your current layer, and your current layer (or another layer that is active and higher than your target layer) has something other than `KC_TRNS`, that is the key that will be sent, not the key on the layer you just activated. This is the cause of most people's "why doesn't my layer get switched" problem. - -Sometimes, you might want to switch between layers in a macro or as part of a tap dance routine. `layer_on` activates a layer, and `layer_off` deactivates it. More layer-related functions can be found in [action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action_layer.h). - -# Modifier Keys +# Modifier Keys :id=modifier-keys These allow you to combine a modifier with a keycode. When pressed, the keydown event for the modifier, then `kc` will be sent. On release, the keyup event for `kc`, then the modifier will be sent. -|Key |Aliases |Description | -|----------|-------------------------------|----------------------------------------------------| -|`LCTL(kc)`|`C(kc)` |Hold Left Control and press `kc` | -|`LSFT(kc)`|`S(kc)` |Hold Left Shift and press `kc` | -|`LALT(kc)`|`A(kc)` |Hold Left Alt and press `kc` | -|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc` | -|`RCTL(kc)`| |Hold Right Control and press `kc` | -|`RSFT(kc)`| |Hold Right Shift and press `kc` | -|`RALT(kc)`|`ALGR(kc)` |Hold Right Alt and press `kc` | -|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)` |Hold Right GUI and press `kc` | -|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)` |Hold Left Shift and GUI and press `kc` | -|`LCA(kc)` | |Hold Left Control and Alt and press `kc` | -|`LCAG(kc)`| |Hold Left Control, Alt and GUI and press `kc` | -|`MEH(kc)` | |Hold Left Control, Shift and Alt and press `kc` | -|`HYPR(kc)`| |Hold Left Control, Shift, Alt and GUI and press `kc`| +|Key |Aliases |Description | +|----------|-------------------------------|------------------------------------------------------| +|`LCTL(kc)`|`C(kc)` |Hold Left Control and press `kc` | +|`LSFT(kc)`|`S(kc)` |Hold Left Shift and press `kc` | +|`LALT(kc)`|`A(kc)`, `LOPT(kc)` |Hold Left Alt and press `kc` | +|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc` | +|`RCTL(kc)`| |Hold Right Control and press `kc` | +|`RSFT(kc)`| |Hold Right Shift and press `kc` | +|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)` |Hold Right Alt and press `kc` | +|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)` |Hold Right GUI and press `kc` | +|`SGUI(kc)`|`SCMD(kc)`, `SWIN(kc)` |Hold Left Shift and GUI and press `kc` | +|`LCA(kc)` | |Hold Left Control and Alt and press `kc` | +|`LSA(kc)` | |Hold Left Shift and Left Alt and press `kc` | +|`RSA(kc)` |`SAGR(kc)` |Hold Right Shift and Right Alt (AltGr) and press `kc` | +|`RCS(kc)` | |Hold Right Control and Right Shift and press `kc` | +|`LCAG(kc)`| |Hold Left Control, Alt and GUI and press `kc` | +|`MEH(kc)` | |Hold Left Control, Shift and Alt and press `kc` | +|`HYPR(kc)`| |Hold Left Control, Shift, Alt and GUI and press `kc` | -You can also chain them, for example `LCTL(LALT(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress. +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. -# Mod-Tap +# Checking Modifier State :id=checking-modifier-state -The Mod-Tap key `MT(mod, kc)` acts like a modifier when held, and a regular keycode when tapped. In other words, you can have a key that sends Escape when you tap it, but functions as a Control or Shift key when you hold it down. +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 modifiers this keycode and `OSM()` accept are prefixed with `MOD_`, not `KC_`: +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)R(GASC)L. -|Modifier |Description | -|----------|----------------------------------------| -|`MOD_LCTL`|Left Control | -|`MOD_LSFT`|Left Shift | -|`MOD_LALT`|Left Alt | -|`MOD_LGUI`|Left GUI (Windows/Command/Meta key) | -|`MOD_RCTL`|Right Control | -|`MOD_RSFT`|Right Shift | -|`MOD_RALT`|Right Alt (AltGr) | -|`MOD_RGUI`|Right GUI (Windows/Command/Meta key) | -|`MOD_HYPR`|Hyper (Left Control, Shift, Alt and GUI)| -|`MOD_MEH` |Meh (Left Control, Shift, and Alt) | +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. -You can combine these by ORing them together like so: +In practice, this means that you can check whether a given modifier is active with `get_mods() & MOD_BIT(KC_)` (see the [list of modifier keycodes](keycodes_basic.md#modifiers)) or with `get_mods() & MOD_MASK_` 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() & == `. + +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 -MT(MOD_LCTL | MOD_LSFT, KC_ESC) +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; +}; ``` -This key would activate Left Control and Left Shift when held, and send Escape when tapped. +### Shift + Backspace for Delete :id=shift-backspace-for-delete -For convenience, QMK includes some Mod-Tap shortcuts to make common combinations more compact in your keymap: +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. -|Key |Aliases |Description | -|------------|-----------------------------------------------------------------|-------------------------------------------------------| -|`LCTL_T(kc)`|`CTL_T(kc)` |Left Control when held, `kc` when tapped | -|`LSFT_T(kc)`|`SFT_T(kc)` |Left Shift when held, `kc` when tapped | -|`LALT_T(kc)`|`ALT_T(kc)` |Left Alt when held, `kc` when tapped | -|`LGUI_T(kc)`|`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|Left GUI when held, `kc` when tapped | -|`RCTL_T(kc)`| |Right Control when held, `kc` when tapped | -|`RSFT_T(kc)`| |Right Shift when held, `kc` when tapped | -|`RALT_T(kc)`|`ALGR_T(kc)` |Right Alt when held, `kc` when tapped | -|`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)` |Right GUI when held, `kc` when tapped | -|`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)` |Left Shift and GUI when held, `kc` when tapped | -|`LCA_T(kc)` | |Left Control and Alt when held, `kc` when tapped | -|`LCAG_T(kc)`| |Left Control, Alt and GUI when held, `kc` when tapped | -|`RCAG_T(kc)`| |Right Control, Alt and GUI when held, `kc` when tapped | -|`C_S_T(kc)` | |Left Control and Shift when held, `kc` when tapped | -|`MEH_T(kc)` | |Left Control, Shift and Alt when held, `kc` when tapped| -|`HYPR_T(kc)`|`ALL_T(kc)` |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)| - -## Caveats - -Unfortunately, these keycodes cannot be used in Mod-Taps or Layer-Taps, since any modifiers specified in the keycode are ignored. - -Additionally, you may run into issues when using Remote Desktop Connection on Windows. Because these codes send shift very fast, Remote Desktop may miss the codes. - -To fix this, open Remote Desktop Connection, click on "Show Options", open the the "Local Resources" tab. In the keyboard section, change the drop down to "On this Computer". This will fix the issue, and allow the characters to work correctly. - -# One Shot Keys - -One shot keys are keys that remain active until the next key is pressed, and then are released. This allows you to type keyboard combinations without pressing more than one key at a time. These keys are usually called "Sticky keys" or "Dead keys". - -For example, if you define a key as `OSM(MOD_LSFT)`, you can type a capital A character by first pressing and releasing shift, and then pressing and releasing A. Your computer will see the shift key being held the moment shift is pressed, and it will see the shift key being released immediately after A is released. - -One shot keys also work as normal modifiers. If you hold down a one shot key and type other keys, your one shot will be released immediately after you let go of the key. - -Additionally, hitting keys five times in a short period will lock that key. This applies for both One Shot Modifiers and One Shot Layers, and is controlled by the `ONESHOT_TAP_TOGGLE` define. - -You can control the behavior of one shot keys by defining these in `config.h`: +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 -#define ONESHOT_TAP_TOGGLE 5 /* Tapping this number of times holds the key until tapped once again. */ -#define ONESHOT_TIMEOUT 5000 /* Time (in ms) before the one shot key is released */ +// 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; +}; ``` -* `OSM(mod)` - Momentarily hold down *mod*. You must use the `MOD_*` keycodes as shown in [Mod Tap](#mod-tap), not the `KC_*` codes. -* `OSL(layer)` - momentary switch to *layer*. +# Legacy Content :id=legacy-content -Sometimes, you want to activate a one-shot key as part of a macro or tap dance routine. +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. -For one shot layers, you need to call `set_oneshot_layer(LAYER, ONESHOT_START)` on key down, and `clear_oneshot_layer_state(ONESHOT_OTHER_KEY_PRESSED)` on key up. If you want to cancel the oneshot, call `reset_oneshot_layer()`. +## Layers :id=switching-and-toggling-layers -For one shot mods, you need to call `set_oneshot_mods(MOD)` to set it, or `clear_oneshot_mods()` to cancel it. +* [Layers](feature_layers.md) -!> If you're having issues with OSM translating over Remote Desktop Connection, this can be fixed by opening the settings, going to the "Local Resources" tap, and in the keyboard section, change the drop down to "On this Computer". This will fix the issue and allow OSM to function properly over Remote Desktop. +## Mod-Tap :id=mod-tap -## Callbacks +* [Mod-Tap](mod_tap.md) -When you'd like to perform custom logic when pressing a one shot key, there are several callbacks you can choose to implement. You could indicate changes in one shot keys by flashing an LED or making a sound, for example. +## One Shot Keys :id=one-shot-keys -There is a callback for `OSM(mod)`. It is called whenever the state of any one shot modifier key is changed: when it toggles on, but also when it is toggled off. You can use it like this: +* [One Shot Keys](one_shot_keys.md) -```c -void oneshot_mods_changed_user(uint8_t mods) { - if (mods & MOD_MASK_SHIFT) { - println("Oneshot mods SHIFT"); - } - if (mods & MOD_MASK_CTRL) { - println("Oneshot mods CTRL"); - } - if (mods & MOD_MASK_ALT) { - println("Oneshot mods ALT"); - } - if (mods & MOD_MASK_GUI) { - println("Oneshot mods GUI"); - } - if (!mods) { - println("Oneshot mods off"); - } -} -``` +## Tap-Hold Configuration Options :id=tap-hold-configuration-options -The `mods` argument contains the active mods after the change, so it reflects the current state. - -When you use One Shot Tap Toggle (by adding `#define ONESHOT_TAP_TOGGLE 2` in your `config.h` file), you may lock a modifier key by pressing it the specified amount of times. There's a callback for that, too: - -```c -void oneshot_locked_mods_changed_user(uint8_t mods) { - if (mods & MOD_MASK_SHIFT) { - println("Oneshot locked mods SHIFT"); - } - if (mods & MOD_MASK_CTRL) { - println("Oneshot locked mods CTRL"); - } - if (mods & MOD_MASK_ALT) { - println("Oneshot locked mods ALT"); - } - if (mods & MOD_MASK_GUI) { - println("Oneshot locked mods GUI"); - } - if (!mods) { - println("Oneshot locked mods off"); - } -} -``` - -Last, there is also a callback for the `OSL(layer)` one shot key: - -```c -void oneshot_layer_changed_user(uint8_t layer) { - if (layer == 1) { - println("Oneshot layer 1 on"); - } - if (!layer) { - println("Oneshot layer off"); - } -} -``` - -If any one shot layer is switched off, `layer` will be zero. When you're looking to do something on any layer change instead of one shot layer changes, `layer_state_set_user` is a better callback to use. - -If you are making your own keyboard, there are also `_kb` equivalent functions: - -```c -void oneshot_locked_mods_changed_kb(uint8_t mods); -void oneshot_mods_changed_kb(uint8_t mods); -void oneshot_layer_changed_kb(uint8_t layer); -``` - -As with any callback, be sure to call the `_user` variant to allow for further customizability. - -# Tap-Hold Configuration Options - -While Tap-Hold options are fantastic, they are not without their issues. We have tried to configure them with reasonal defaults, but that may still cause issues for some people. - -These options let you modify the behavior of the Tap-Hold keys. - -## Permissive Hold - -As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new `config.h` option: - -```c -#define PERMISSIVE_HOLD -``` - -This makes tap and hold keys (like Mod Tap) work better for fast typist, or for high `TAPPING_TERM` settings. - -If you press a Mod Tap key, tap another key (press and release) and then release the Mod Tap key, all within the tapping term, it will output the "tapping" function for both keys. - -For Instance: - -- `SFT_T(KC_A)` Down -- `KC_X` Down -- `KC_X` Up -- `SFT_T(KC_A)` Up - -Normally, if you do all this within the `TAPPING_TERM` (default: 200ms) this will be registered as `ax` by the firmware and host system. With permissive hold enabled, this modifies how this is handled by considering the Mod Tap keys as a Mod if another key is tapped, and would registered as `X` (`SHIFT`+`x`). - -?> If you have `Ignore Mod Tap Interrupt` enabled, as well, this will modify how both work. The regular key has the modifier added if the first key is released first or if both keys are held longer than the `TAPPING_TERM`. - -## Ignore Mod Tap Interrupt - -To enable this setting, add this to your `config.h`: - -```c -#define IGNORE_MOD_TAP_INTERRUPT -``` - -Similar to Permissive Hold, this alters how the firmware processes input for fast typist. If you press a Mod Tap key, press another key, release the Mod Tap key, and then release the normal key, it would normally output the "tapping" function for both keys. This may not be desirable for rolling combo keys. - -Setting `Ignore Mod Tap Interrupt` requires holding both keys for the `TAPPING_TERM` to trigger the hold function (the mod). - -For Instance: - -- `SFT_T(KC_A)` Down -- `KC_X` Down -- `SFT_T(KC_A)` Up -- `KC_X` Up - -Normally, this would send `X` (`SHIFT`+`x`). With `Ignore Mod Tap Interrupt` enabled, holding both keys are required for the `TAPPING_TERM` to register the hold action. A quick tap will output `ax` in this case, while a hold on both will still output `X` (`SHIFT`+`x`). - - -?> __Note__: This only concerns modifiers and not layer switching keys. - -?> If you have `Permissive Hold` enabled, as well, this will modify how both work. The regular key has the modifier added if the first key is released first or if both keys are held longer than the `TAPPING_TERM`. - -## Tapping Force Hold - -To enable `tapping force hold`, add the following to your `config.h`: - -```c -#define TAPPING_FORCE_HOLD -``` - -When the user holds a key after tap, this repeats the tapped key rather to hold a modifier key. This allows to use auto repeat for the tapped key. - -Example: - -- SFT_T(KC_A) Down -- SFT_T(KC_A) Up -- SFT_T(KC_A) Down -- wait more than tapping term... -- SFT_T(KC_A) Up - -With default settings, `a` will be sent on the first release, then `a` will be sent on the second press allowing the computer to trigger its auto repeat function. - -With `TAPPING_FORCE_HOLD`, the second press will be interpreted as a Shift, allowing to use it as a modifier shortly after having used it as a tap. - -!> `TAPPING_FORCE_HOLD` will break anything that uses tapping toggles (Such as the `TT` layer keycode, and the One Shot Tapping Toggle). - -## Retro Tapping - -To enable `retro tapping`, add the following to your `config.h`: - -```c -#define RETRO_TAPPING -``` - -Holding and releasing a dual function key without pressing another key will result in nothing happening. With retro tapping enabled, releasing the key without pressing another will send the original keycode even if it is outside the tapping term. - -For instance, holding and releasing `LT(2, KC_SPACE)` without hitting another key will result in nothing happening. With this enabled, it will send `KC_SPACE` instead. +* [Tap-Hold Configuration Options](tap_hold.md) diff --git a/docs/feature_audio.md b/docs/feature_audio.md index 5132dfe9719..9e7ba75f521 100644 --- a/docs/feature_audio.md +++ b/docs/feature_audio.md @@ -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). + + +### 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, diff --git a/docs/feature_auto_shift.md b/docs/feature_auto_shift.md index f0b507bc618..8e04d9dd38c 100644 --- a/docs/feature_auto_shift.md +++ b/docs/feature_auto_shift.md @@ -15,25 +15,31 @@ problem. When you tap a key, it stays depressed for a short period of time before it is then released. This depressed time is a different length for everyone. Auto Shift defines a constant `AUTO_SHIFT_TIMEOUT` which is typically set to twice your -normal pressed state time. When you press a key, a timer starts and then stops -when you release the key. If the time depressed is greater than or equal to the -`AUTO_SHIFT_TIMEOUT`, then a shifted version of the key is emitted. If the time -is less than the `AUTO_SHIFT_TIMEOUT` time, then the normal state is emitted. +normal pressed state time. When you press a key, a timer starts, and if you +have not released the key after the `AUTO_SHIFT_TIMEOUT` period, then a shifted +version of the key is emitted. If the time is less than the `AUTO_SHIFT_TIMEOUT` +time, or you press another key, then the normal state is emitted. + +If `AUTO_SHIFT_REPEAT` is defined, there is keyrepeat support. Holding the key +down will repeat the shifted key, though this can be disabled with +`AUTO_SHIFT_NO_AUTO_REPEAT`. If you want to repeat the normal key, then tap it +once then immediately (within `TAPPING_TERM`) hold it down again (this works +with the shifted value as well if auto-repeat is disabled). ## Are There Limitations to Auto Shift? Yes, unfortunately. -1. Key repeat will cease to work. For example, before if you wanted 20 'a' - characters, you could press and hold the 'a' key for a second or two. This no - longer works with Auto Shift because it is timing your depressed time instead - of emitting a depressed key state to your operating system. -2. You will have characters that are shifted when you did not intend on shifting, and - other characters you wanted shifted, but were not. This simply comes down to - practice. As we get in a hurry, we think we have hit the key long enough - for a shifted version, but we did not. On the other hand, we may think we are - tapping the keys, but really we have held it for a little longer than - anticipated. +You will have characters that are shifted when you did not intend on shifting, and +other characters you wanted shifted, but were not. This simply comes down to +practice. As we get in a hurry, we think we have hit the key long enough for a +shifted version, but we did not. On the other hand, we may think we are tapping +the keys, but really we have held it for a little longer than anticipated. + +Additionally, with keyrepeat the desired shift state can get mixed up. It will +always 'belong' to the last key pressed. For example, keyrepeating a capital +and then tapping something lowercase (whether or not it's an Auto Shift key) +will result in the capital's *key* still being held, but shift not. ## How Do I Enable Auto Shift? @@ -103,6 +109,14 @@ Do not Auto Shift numeric keys, zero through nine. Do not Auto Shift alpha characters, which include A through Z. +### AUTO_SHIFT_REPEAT (simple define) + +Enables keyrepeat. + +### AUTO_SHIFT_NO_AUTO_REPEAT (simple define) + +Disables automatically keyrepeating when `AUTO_SHIFT_TIMEOUT` is exceeded. + ## Using Auto Shift Setup This will enable you to define three keys temporarily to increase, decrease and report your `AUTO_SHIFT_TIMEOUT`. @@ -139,7 +153,7 @@ completely normal and with no intention of shifted keys. `KC_ASRP`. The keyboard will type by itself the value of your `AUTO_SHIFT_TIMEOUT`. 7. Update `AUTO_SHIFT_TIMEOUT` in your `config.h` with the value reported. -8. Remove `AUTO_SHIFT_SETUP` from your `config.h`. +8. Add `AUTO_SHIFT_NO_SETUP` to your `config.h`. 9. Remove the key bindings `KC_ASDN`, `KC_ASUP` and `KC_ASRP`. 10. Compile and upload your new firmware. diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md index 22abaa60a8f..2adb16e4a86 100644 --- a/docs/feature_backlight.md +++ b/docs/feature_backlight.md @@ -1,4 +1,4 @@ -# Backlighting +# Backlighting :id=backlighting Many keyboards support backlit keys by way of individual LEDs placed through or underneath the keyswitches. This feature is distinct from both the [RGB underglow](feature_rgblight.md) and [RGB matrix](feature_rgb_matrix.md) features as it usually allows for only a single colour per switch, though you can obviously install multiple different single coloured LEDs on a keyboard. @@ -6,103 +6,107 @@ QMK is able to control the brightness of these LEDs by switching them on and off The MCU can only supply so much current to its GPIO pins. Instead of powering the backlight directly from the MCU, the backlight pin is connected to a transistor or MOSFET that switches the power to the LEDs. -## Feature Configuration - Most keyboards have backlighting enabled by default if they support it, but if it is not working for you, check that your `rules.mk` includes the following: ```makefile BACKLIGHT_ENABLE = yes ``` -## Keycodes -Once enabled the following keycodes below can be used to change the backlight level. +## Keycodes :id=keycodes -|Key |Description | -|---------|------------------------------------------| -|`BL_TOGG`|Turn the backlight on or off | -|`BL_STEP`|Cycle through backlight levels | -|`BL_ON` |Set the backlight to max brightness | -|`BL_OFF` |Turn the backlight off | -|`BL_INC` |Increase the backlight level | -|`BL_DEC` |Decrease the backlight level | -|`BL_BRTG`|Toggle backlight breathing | +Once enabled, the following keycodes below can be used to change the backlight level. -## Backlight Functions +|Key |Description | +|---------|-----------------------------------| +|`BL_TOGG`|Turn the backlight on or off | +|`BL_STEP`|Cycle through backlight levels | +|`BL_ON` |Set the backlight to max brightness| +|`BL_OFF` |Turn the backlight off | +|`BL_INC` |Increase the backlight level | +|`BL_DEC` |Decrease the backlight level | +|`BL_BRTG`|Toggle backlight breathing | -|Function |Description | -|----------|-----------------------------------------------------------| -|`backlight_toggle()` |Turn the backlight on or off | -|`backlight_enable()` |Turn the backlight on | -|`backlight_disable()` |Turn the backlight off | -|`backlight_step()` |Cycle through backlight levels | -|`backlight_increase()` |Increase the backlight level | -|`backlight_decrease()` |Decrease the backlight level | -|`backlight_level(x)` |Sets the backlight level to specified level | -|`get_backlight_level()` |Return the current backlight level | -|`is_backlight_enabled()`|Return whether the backlight is currently on | +## Functions :id=functions -### Backlight Breathing Functions +These functions can be used to change the backlighting in custom code: -|Function |Description | -|----------|---------------------------------------------------| -|`breathing_toggle()` |Turn the backlight breathing on or off | -|`breathing_enable()` |Turns on backlight breathing | -|`breathing_disable()` |Turns off backlight breathing | +|Function |Description | +|------------------------|--------------------------------------------| +|`backlight_toggle()` |Turn the backlight on or off | +|`backlight_enable()` |Turn the backlight on | +|`backlight_disable()` |Turn the backlight off | +|`backlight_step()` |Cycle through backlight levels | +|`backlight_increase()` |Increase the backlight level | +|`backlight_decrease()` |Decrease the backlight level | +|`backlight_level(x)` |Sets the backlight level to specified level | +|`get_backlight_level()` |Return the current backlight level | +|`is_backlight_enabled()`|Return whether the backlight is currently on| -## Driver Configuration +If backlight breathing is enabled (see below), the following functions are also available: + +|Function |Description | +|---------------------|--------------------------------------| +|`breathing_toggle()` |Turn the backlight breathing on or off| +|`breathing_enable()` |Turns on backlight breathing | +|`breathing_disable()`|Turns off backlight breathing | + +## Configuration :id=configuration To select which driver to use, configure your `rules.mk` with the following: ```makefile -BACKLIGHT_DRIVER = software # Valid driver values are 'pwm,software,no' +BACKLIGHT_DRIVER = software ``` -See below for help on individual drivers. +Valid driver values are `pwm`, `software`, `custom` or `no`. See below for help on individual drivers. -## Common Driver Configuration +To configure the backlighting, `#define` these in your `config.h`: -To change the behavior of the backlighting, `#define` these in your `config.h`: +| Define | Default | Description | +|------------------------|---------------|-------------------------------------------------------------------------------------------------------------------| +| `BACKLIGHT_PIN` | *Not defined* | The pin that controls the LED(s) | +| `BACKLIGHT_LEVELS` | `3` | The number of brightness levels (maximum 31 excluding off) | +| `BACKLIGHT_CAPS_LOCK` | *Not defined* | Enable Caps Lock indicator using backlight (for keyboards without dedicated LED) | +| `BACKLIGHT_BREATHING` | *Not defined* | Enable backlight breathing, if supported | +| `BREATHING_PERIOD` | `6` | The length of one backlight "breath" in seconds | +| `BACKLIGHT_ON_STATE` | `1` | The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low | +| `BACKLIGHT_LIMIT_VAL ` | `255` | The maximum duty cycle of the backlight -- `255` allows for full brightness, any lower will decrease the maximum. | -|Define |Default |Description | -|---------------------|-------------|--------------------------------------------------------------------------------------| -|`BACKLIGHT_LEVELS` |`3` |The number of brightness levels (maximum 31 excluding off) | -|`BACKLIGHT_CAPS_LOCK`|*Not defined*|Enable Caps Lock indicator using backlight (for keyboards without dedicated LED) | -|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported | -|`BREATHING_PERIOD` |`6` |The length of one backlight "breath" in seconds | -|`BACKLIGHT_ON_STATE` |`0` |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low | +Unless you are designing your own keyboard, you generally should not need to change the `BACKLIGHT_PIN` or `BACKLIGHT_ON_STATE`. -### Backlight On State +### Backlight On State :id=backlight-on-state Most backlight circuits are driven by an N-channel MOSFET or NPN transistor. This means that to turn the transistor *on* and light the LEDs, you must drive the backlight pin, connected to the gate or base, *high*. Sometimes, however, a P-channel MOSFET, or a PNP transistor is used. In this case, when the transistor is on, the pin is driven *low* instead. This functionality is configured at the keyboard level with the `BACKLIGHT_ON_STATE` define. -## AVR driver +### AVR Driver :id=avr-driver + +The `pwm` driver is configured by default, however the equivalent setting within `rules.mk` would be: -On AVR boards, the default driver currently sniffs the configuration to pick the best scenario. The driver is configured by default, however the equivalent setting within rules.mk would be: ```makefile BACKLIGHT_DRIVER = pwm ``` -### Caveats +#### Caveats :id=avr-caveats -Hardware PWM is supported according to the following table: +On AVR boards, QMK automatically decides which driver to use according to the following table: -|Backlight Pin|AT90USB64/128|ATmega16/32U4|ATmega16/32U2|ATmega32A|ATmega328P| -|-------------|-------------|-------------|-------------|---------|----------| -|`B1` | | | | |Timer 1 | -|`B2` | | | | |Timer 1 | -|`B5` |Timer 1 |Timer 1 | | | | -|`B6` |Timer 1 |Timer 1 | | | | -|`B7` |Timer 1 |Timer 1 |Timer 1 | | | -|`C4` |Timer 3 | | | | | -|`C5` |Timer 3 | |Timer 1 | | | -|`C6` |Timer 3 |Timer 3 |Timer 1 | | | -|`D4` | | | |Timer 1 | | -|`D5` | | | |Timer 1 | | +|Backlight Pin|AT90USB64/128|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 software PWM. If the [Audio](feature_audio.md) feature is disabled or only using one timer, the backlight PWM can be triggered by a hardware timer: +All other pins will use timer-assisted software PWM: |Audio Pin|Audio Timer|Software PWM Timer| |---------|-----------|------------------| @@ -113,32 +117,9 @@ All other pins will use software PWM. If the [Audio](feature_audio.md) feature i |`B6` |Timer 1 |Timer 3 | |`B7` |Timer 1 |Timer 3 | -When both timers are in use for Audio, the backlight PWM will not use a hardware timer, but will instead be triggered during the matrix scan. In this case, breathing is not supported, and the backlight might flicker, because the PWM computation may not be called with enough timing precision. +When both timers are in use for Audio, the backlight PWM cannot use a hardware timer, and will instead be triggered during the matrix scan. In this case, breathing is not supported, and the backlight might flicker, because the PWM computation may not be called with enough timing precision. -### AVR Configuration - -To change the behavior of the backlighting, `#define` these in your `config.h`: - -|Define |Default |Description | -|---------------------|-------------|--------------------------------------------------------------------------------------------------------------| -|`BACKLIGHT_PIN` |`B7` |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this | -|`BACKLIGHT_PINS` |*Not defined*|experimental: see below for more information | - -### Multiple backlight pins - -Most keyboards have only one backlight pin which control all backlight LEDs (especially if the backlight is connected to an hardware PWM pin). -In software PWM, it is possible to define multiple backlight pins. All those pins will be turned on and off at the same time during the PWM duty cycle. -This feature allows to set for instance the Caps Lock LED (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped LCTRL in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on. - -To activate multiple backlight pins, you need to add something like this to your user `config.h`: - -```c -#define BACKLIGHT_LED_COUNT 2 -#undef BACKLIGHT_PIN -#define BACKLIGHT_PINS { F5, B2 } -``` - -### Hardware PWM Implementation +#### Hardware PWM Implementation :id=hardware-pwm-implementation When using the supported pins for backlighting, QMK will use a hardware timer configured to output a PWM signal. This timer will count up to `ICRx` (by default `0xFFFF`) before resetting to 0. The desired brightness is calculated and stored in the `OCRxx` register. When the counter reaches this value, the backlight pin will go low, and is pulled high again when the counter resets. @@ -147,7 +128,7 @@ In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus th The breathing effect is achieved by registering an interrupt handler for `TIMER1_OVF_vect` that is called whenever the counter resets, roughly 244 times per second. In this handler, the value of an incrementing counter is mapped onto a precomputed brightness curve. To turn off breathing, the interrupt handler is simply disabled, and the brightness reset to the level stored in EEPROM. -### Timer Assisted PWM Implementation +#### Timer Assisted PWM Implementation :id=timer-assisted-implementation When `BACKLIGHT_PIN` is not set to a hardware backlight pin, QMK will use a hardware timer configured to trigger software interrupts. This time will count up to `ICRx` (by default `0xFFFF`) before resetting to 0. When resetting to 0, the CPU will fire an OVF (overflow) interrupt that will turn the LEDs on, starting the duty cycle. @@ -156,81 +137,82 @@ In this way `OCRxx` essentially controls the duty cycle of the LEDs, and thus th The breathing effect is the same as in the hardware PWM implementation. -## ARM Driver +### ARM Driver :id=arm-configuration + +While still in its early stages, ARM backlight support aims to eventually have feature parity with AVR. The `pwm` driver is configured by default, however the equivalent setting within `rules.mk` would be: -While still in its early stages, ARM backlight support aims to eventually have feature parity with AVR. The driver is configured by default, however the equivalent setting within rules.mk would be: ```makefile BACKLIGHT_DRIVER = pwm ``` -### Caveats +#### ChibiOS Configuration :id=arm-configuration + +The following `#define`s apply only to ARM-based keyboards: + +|Define |Default|Description | +|-----------------------|-------|-----------------------------------| +|`BACKLIGHT_PWM_DRIVER` |`PWMD4`|The PWM driver to use | +|`BACKLIGHT_PWM_CHANNEL`|`3` |The PWM channel to use | +|`BACKLIGHT_PAL_MODE` |`2` |The pin alternative function to use| + +See the ST datasheet for your particular MCU to determine these values. Unless you are designing your own keyboard, you generally should not need to change them. + +#### Caveats :id=arm-caveats Currently only hardware PWM is supported, not timer assisted, and does not provide automatic configuration. -?> STMF072 support is being investigated. +### Software PWM Driver :id=software-pwm-driver -### ARM Configuration +In this mode, PWM is "emulated" while running other keyboard tasks. It offers maximum hardware compatibility without extra platform configuration. The tradeoff is the backlight might jitter when the keyboard is busy. To enable, add this to your `rules.mk`: -To change the behavior of the backlighting, `#define` these in your `config.h`: - -|Define |Default |Description | -|------------------------|-------------|-------------------------------------------------------------------------------------------------------------| -|`BACKLIGHT_PIN` |`B7` |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this| -|`BACKLIGHT_PWM_DRIVER` |`PWMD4` |The PWM driver to use, see ST datasheets for pin to PWM timer mapping. Unless you are designing your own keyboard, you shouldn't need to change this| -|`BACKLIGHT_PWM_CHANNEL` |`3` |The PWM channel to use, see ST datasheets for pin to PWM channel mapping. Unless you are designing your own keyboard, you shouldn't need to change this| -|`BACKLIGHT_PAL_MODE` |`2` |The pin alternative function to use, see ST datasheets for pin AF mapping. Unless you are designing your own keyboard, you shouldn't need to change this| - -## Software PWM Driver - -Emulation of PWM while running other keyboard tasks, it offers maximum hardware compatibility without extra platform configuration. The tradeoff is the backlight might jitter when the keyboard is busy. To enable, add this to your rules.mk: ```makefile BACKLIGHT_DRIVER = software ``` -### Software PWM Configuration - -To change the behavior of the backlighting, `#define` these in your `config.h`: - -|Define |Default |Description | -|-----------------|-------------|-------------------------------------------------------------------------------------------------------------| -|`BACKLIGHT_PIN` |`B7` |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this| -|`BACKLIGHT_PINS` |*Not defined*|experimental: see below for more information | - -### Multiple backlight pins +#### Multiple Backlight Pins :id=multiple-backlight-pins Most keyboards have only one backlight pin which control all backlight LEDs (especially if the backlight is connected to an hardware PWM pin). -In software PWM, it is possible to define multiple backlight pins. All those pins will be turned on and off at the same time during the PWM duty cycle. -This feature allows to set for instance the Caps Lock LED (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped LCTRL in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on. +In software PWM, it is possible to define multiple backlight pins, which will be turned on and off at the same time during the PWM duty cycle. -To activate multiple backlight pins, you need to add something like this to your user `config.h`: +This feature allows to set, for instance, the Caps Lock LED's (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped Control in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on, as it is usually wired to a separate pin from the backlight. + +To activate multiple backlight pins, add something like this to your `config.h`, instead of `BACKLIGHT_PIN`: ```c -#undef BACKLIGHT_PIN #define BACKLIGHT_PINS { F5, B2 } ``` -## Custom Driver +### Custom Driver :id=custom-driver -To enable, add this to your rules.mk: +If none of the above drivers apply to your board (for example, you are using a separate IC to control the backlight), you can implement a custom backlight driver using this simple API provided by QMK. To enable, add this to your `rules.mk`: ```makefile BACKLIGHT_DRIVER = custom ``` -When implementing the custom driver API, the provided keyboard hooks are as follows: +Then implement any of these hooks: ```c void backlight_init_ports(void) { - // Optional - Run on startup - // - usually you want to configure pins here + // Optional - runs on startup + // Usually you want to configure pins here } void backlight_set(uint8_t level) { - // Optional - Run on level change - // - usually you want to respond to the new value + // Optional - runs on level change + // Usually you want to respond to the new value } void backlight_task(void) { - // Optional - Run periodically - // - long running actions here can cause performance issues + // Optional - runs periodically + // Note that this is called in the main keyboard loop, + // so long running actions here can cause performance issues } ``` + +## Example Schematic + +In this typical example, the backlight LEDs are all connected in parallel towards an N-channel MOSFET. Its gate pin is wired to one of the microcontroller's GPIO pins through a 470Ω resistor to avoid ringing. +A pulldown resistor is also placed between the gate pin and ground to keep it at a defined state when it is not otherwise being driven by the MCU. +The values of these resistors are not critical - see [this Electronics StackExchange question](https://electronics.stackexchange.com/q/68748) for more information. + +![Backlight example circuit](https://i.imgur.com/BmAvoUC.png) diff --git a/docs/feature_bluetooth.md b/docs/feature_bluetooth.md index 6cd5c3c6cf3..08e5f24ac55 100644 --- a/docs/feature_bluetooth.md +++ b/docs/feature_bluetooth.md @@ -2,11 +2,10 @@ ## Bluetooth Known Supported Hardware -Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1, QMK has support for RN-42 modules and the Bluefruit EZ-Key, the latter of which is not produced anymore. For more recent BLE protocols, currently only the Adafruit Bluefruit SPI Friend is directly supported. BLE is needed to connect to iOS devices. Note iOS does not support mouse input. +Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1, QMK has support for RN-42 modules. For more recent BLE protocols, currently only the Adafruit Bluefruit SPI Friend is directly supported. BLE is needed to connect to iOS devices. Note iOS does not support mouse input. |Board |Bluetooth Protocol |Connection Type |rules.mk |Bluetooth Chip| |----------------------------------------------------------------|----------------------------|----------------|---------------------------|--------------| -|[Adafruit EZ-Key HID](https://www.adafruit.com/product/1535) |Bluetooth Classic | UART |`BLUETOOTH = AdafruitEZKey` | | |Roving Networks RN-42 (Sparkfun Bluesmirf) |Bluetooth Classic | UART |`BLUETOOTH = RN42` | RN-42 | |[Bluefruit LE SPI Friend](https://www.adafruit.com/product/2633)|Bluetooth Low Energy | SPI |`BLUETOOTH = AdafruitBLE` | nRF51822 | @@ -24,16 +23,15 @@ Currently The only bluetooth chipset supported by QMK is the Adafruit Bluefruit A Bluefruit UART friend can be converted to an SPI friend, however this [requires](https://github.com/qmk/qmk_firmware/issues/2274) some reflashing and soldering directly to the MDBT40 chip. -## Adafruit EZ-Key hid -This requires [some hardware changes](https://www.reddit.com/r/MechanicalKeyboards/comments/3psx0q/the_planck_keyboard_with_bluetooth_guide_and/?ref=search_posts), but can be enabled via the Makefile. The firmware will still output characters via USB, so be aware of this when charging via a computer. It would make sense to have a switch on the Bluefruit to turn it off at will. - ## Bluetooth Rules.mk Options -Use only one of these + +The currently supported Bluetooth chipsets do not support [N-Key Rollover (NKRO)](reference_glossary.md#n-key-rollover-nkro), so `rules.mk` must contain `NKRO_ENABLE = no`. + +Use only one of these to enable Bluetooth: * BLUETOOTH_ENABLE = yes (Legacy Option) * BLUETOOTH = RN42 -* BLUETOOTH = AdafruitEZKey * BLUETOOTH = AdafruitBLE ## Bluetooth Keycodes diff --git a/docs/feature_bootmagic.md b/docs/feature_bootmagic.md index a19b5e548d6..f084052cc74 100644 --- a/docs/feature_bootmagic.md +++ b/docs/feature_bootmagic.md @@ -54,7 +54,7 @@ Hold down the Bootmagic key (Space by default) and the desired hotkey while plug |`6` |Make layer 6 the default layer | |`7` |Make layer 7 the default layer | -## Keycodes +## Keycodes :id=keycodes |Key |Aliases |Description | |----------------------------------|---------|--------------------------------------------------------------------------| @@ -121,9 +121,9 @@ If you would like to change the hotkey assignments for Bootmagic, `#define` thes |`BOOTMAGIC_KEY_DEFAULT_LAYER_6` |`KC_6` |Make layer 6 the default layer | |`BOOTMAGIC_KEY_DEFAULT_LAYER_7` |`KC_7` |Make layer 7 the default layer | -# Bootmagic Lite +# Bootmagic Lite :id=bootmagic-lite -In addition to the full blown Bootmagic feature, is the Bootmagic Lite feature that only handles jumping into the bootloader. This is great for boards that don't have a physical reset button but you need a way to jump into the bootloader, and don't want to deal with the headache that Bootmagic can cause. +In addition to the full blown Bootmagic feature, is the Bootmagic Lite feature that only handles jumping into the bootloader. This is great for boards that don't have a physical reset button but you need a way to jump into the bootloader, and don't want to deal with the headache that Bootmagic can cause. To enable this version of Bootmagic, you need to enable it in your `rules.mk` with: @@ -131,7 +131,7 @@ To enable this version of Bootmagic, you need to enable it in your `rules.mk` wi BOOTMAGIC_ENABLE = lite ``` -Additionally, you may want to specify which key to use. This is especially useful for keyboards that have unusual matrices. To do so, you need to specify the row and column of the key that you want to use. Add these entries to your `config.h` file: +Additionally, you may want to specify which key to use. This is especially useful for keyboards that have unusual matrices. To do so, you need to specify the row and column of the key that you want to use. Add these entries to your `config.h` file: ```c #define BOOTMAGIC_LITE_ROW 0 @@ -144,9 +144,20 @@ And to trigger the bootloader, you hold this key down when plugging the keyboard !> Using bootmagic lite will **always reset** the EEPROM, so you will lose any settings that have been saved. +## Split Keyboards + +When handedness is predetermined via an option like `SPLIT_HAND_PIN`, you might need to configure a different key between halves. This To do so, add these entries to your `config.h` file: + +```c +#define BOOTMAGIC_LITE_ROW_RIGHT 4 +#define BOOTMAGIC_LITE_COLUMN_RIGHT 1 +``` + +By default, these values are not set. + ## Advanced Bootmagic Lite -The `bootmagic_lite` function is defined weakly, so that you can replace this in your code, if you need. A great example of this is the Zeal60 boards that have some additional handling needed. +The `bootmagic_lite` function is defined weakly, so that you can replace this in your code, if you need. A great example of this is the Zeal60 boards that have some additional handling needed. To replace the function, all you need to do is add something like this to your code: @@ -163,4 +174,4 @@ void bootmagic_lite(void) { } ``` -You can additional feature here. For instance, resetting the eeprom or requiring additional keys to be pressed to trigger bootmagic. Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware. +You can additional feature here. For instance, resetting the eeprom or requiring additional keys to be pressed to trigger bootmagic. Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware. diff --git a/docs/feature_combo.md b/docs/feature_combo.md index d3eb896b286..d831328f698 100644 --- a/docs/feature_combo.md +++ b/docs/feature_combo.md @@ -55,7 +55,7 @@ combo_t key_combos[COMBO_COUNT] = { [XV_PASTE] = COMBO_ACTION(paste_combo), }; -void process_combo_event(uint8_t combo_index, bool pressed) { +void process_combo_event(uint16_t combo_index, bool pressed) { switch(combo_index) { case ZC_COPY: if (pressed) { diff --git a/docs/feature_debounce_type.md b/docs/feature_debounce_type.md index b5e5b61bb3d..3ad74224c17 100644 --- a/docs/feature_debounce_type.md +++ b/docs/feature_debounce_type.md @@ -1,42 +1,150 @@ -# Debounce algorithm +# Contact bounce / contact chatter + +Mechanical switches often don't have a clean single transition between pressed and unpressed states. + +In an ideal world, when you press a switch, you would expect the digital pin to see something like this: +(X axis showing time +``` +voltage +---------------------- + ^ | + | | + | ------------------+ + ----> time +``` + +However in the real world you will actually see contact bounce, which will look like multiple 1->0 and 0->1 transitions, +until the value finally settles. +``` + +-+ +--+ +------------- + | | | | | + | | | | | ++-----------------+ +-+ +-+ +``` +The time it takes for the switch to settle might vary with switch type, age, and even pressing technique. + +If the device chooses not to mitigate contact bounce, then often actions that happen when the switch is pressed are repeated +multiple times. + +There are many ways to handle contact bounce ("Debouncing"). Some include employing additional hardware, for example an RC filter, +while there are various ways to do debouncing in software too, often called debounce algorithms. This page discusses software +debouncing methods available in QMK. + +While technically not considered contact bounce/contact chatter, some switch technologies are susceptible to noise, meaning, +while the key is not changing state, sometimes short random 0->1 or 1->0 transitions might be read by the digital circuit, for example: +``` + +-+ + | | + | | ++-----------------+ +-------------------- +``` + +Many debounce methods (but not all) will also make the device resistant to noise. If you are working with a technology that is +susceptible to noise, you must choose a debounce method that will also mitigate noise for you. + +## Types of debounce algorithms + +1) Unit of time: Timestamp (milliseconds) vs Cycles (scans) + * Debounce algorithms often have a 'debounce time' parameter, that specifies the maximum settling time of the switch contacts. + This time might be measured in various units: + * Cycles-based debouncing waits n cycles (scans), decreasing count by one each matrix_scan + * Timestamp-based debouncing stores the millisecond timestamp a change occurred, and does substraction to figure out time elapsed. + * Timestamp-based debouncing is usually superior, especially in the case of noise-resistant devices because settling times of physical + switches is specified in units of time, and should not depend on the matrix scan-rate of the keyboard. + * Cycles-based debouncing is sometimes considered inferior, because the settling time that it is able to compensate for depends on the + performance of the matrix scanning code. If you use cycles-based debouncing, and you significantly improve the performance of your scanning + code, you might end up with less effective debouncing. A situation in which cycles-based debouncing might be preferable is when + noise is present, and the scanning algorithm is slow, or variable speed. Even if your debounce algorithm is fundamentally noise-resistant, + if the scanning is slow, and you are using a timestamp-based algorithm, you might end up making a debouncing decision based on only two + sampled values, which will limit the noise-resistance of the algorithm. + * Currently all built-in debounce algorithms support timestamp-based debouncing only. In the future we might + implement cycles-based debouncing, and it will be selectable via a ```config.h``` macro. + +2) Symmetric vs Asymmetric + * Symmetric - apply the same debouncing algorithm, to both key-up and key-down events. + * Recommended naming convention: ```sym_*``` + * Asymmetric - apply different debouncing algorithms to key-down and key-up events. E.g. Eager key-down, Defer key-up. + * Recommended naming convention: ```asym_*``` followed by details of the type of algorithm in use, in order, for key-down and then key-up + +3) Eager vs Defer + * Eager - any key change is reported immediately. All further inputs for DEBOUNCE ms are ignored. + * Eager algorithms are not noise-resistant. + * Recommended naming conventions: + * ```sym_eager_*``` + * ```asym_eager_*_*```: key-down is using eager algorithm + * ```asym_*_eager_*```: key-up is using eager algorithm + * Defer - wait for no changes for DEBOUNCE ms before reporting change. + * Defer algorithms are noise-resistant + * Recommended naming conventions: + * ```sym_defer_*``` + * ```asym_defer_*_*```: key-down is using defer algorithm + * ```asym_*_defer_*```: key-up is using defer algorithm + +4) Global vs Per-Key vs Per-Row + * Global - one timer for all keys. Any key change state affects global timer + * Recommended naming convention: ```*_g``` + * Per-key - one timer per key + * Recommended naming convention: ```*_pk``` + * Per-row - one timer per row + * Recommended naming convention: ```*_pr``` + * Per-key and per-row algorithms consume more resources (in terms of performance, + and ram usage), but fast typists might prefer them over global. + +## Debounce algorithms supported by QMK QMK supports multiple debounce algorithms through its debounce API. - -The logic for which debounce method called is below. It checks various defines that you have set in rules.mk +The logic for which debounce method called is below. It checks various defines that you have set in ```rules.mk``` ``` DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce -DEBOUNCE_TYPE?= sym_g +DEBOUNCE_TYPE?= sym_defer_g ifneq ($(strip $(DEBOUNCE_TYPE)), custom) QUANTUM_SRC += $(DEBOUNCE_DIR)/$(strip $(DEBOUNCE_TYPE)).c endif ``` -# Debounce selection +### Debounce selection | DEBOUNCE_TYPE | Description | What else is needed | | ------------- | --------------------------------------------------- | ----------------------------- | -| Not defined | Use the default algorithm, currently sym_g | Nothing | +| Not defined | Use the default algorithm, currently sym_defer_g | Nothing | | custom | Use your own debounce code | ```SRC += debounce.c``` add your own debounce.c and implement necessary functions | -| anything_else | Use another algorithm from quantum/debounce/* | Nothing | +| Anything Else | Use another algorithm from quantum/debounce/* | Nothing | **Regarding split keyboards**: The debounce code is compatible with split keyboards. -# Use your own debouncing code -* Set ```DEBOUNCE_TYPE = custom```. -* Add ```SRC += debounce.c``` +### Selecting an included debouncing method +Keyboards may select one of the already implemented debounce methods, by adding to ```rules.mk``` the following line: +``` +DEBOUNCE_TYPE = +``` +Where name of algorithm is one of: +* ```sym_defer_g``` - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occurred, all input changes are pushed. + * This is the current default algorithm. This is the highest performance algorithm with lowest memory usage, and it's also noise-resistant. +* ```sym_eager_pr``` - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row. +For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be +appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use. +* ```sym_eager_pk``` - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key +* ```sym_defer_pk``` - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key status change is pushed. + +### A couple algorithms that could be implemented in the future: +* ```sym_defer_pr``` +* ```sym_eager_g``` +* ```asym_eager_defer_pk``` + +### Use your own debouncing code +You have the option to implement you own debouncing algorithm. To do this: +* Set ```DEBOUNCE_TYPE = custom``` in ```rules.mk```. +* Add ```SRC += debounce.c``` in ```rules.mk``` * Add your own ```debounce.c```. Look at current implementations in ```quantum/debounce``` for examples. * Debouncing occurs after every raw matrix scan. * Use num_rows rather than MATRIX_ROWS, so that split keyboards are supported correctly. +* If the algorithm might be applicable to other keyboards, please consider adding it to ```quantum/debounce``` -# Changing between included debouncing methods -You can either use your own code, by including your own debounce.c, or switch to another included one. -Included debounce methods are: -* eager_pr - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row. -For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be -appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use. -* eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key -* sym_g - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occured, all input changes are pushed. - +### Old names +The following old names for existing algorithms will continue to be supported, however it is recommended to use the new names instead. +* sym_g - old name for sym_defer_g +* eager_pk - old name for sym_eager_pk +* sym_pk - old name for sym_defer_pk +* eager_pr - old name for sym_eager_pr diff --git a/docs/feature_dip_switch.md b/docs/feature_dip_switch.md index bce47fed88c..15e449c4c46 100644 --- a/docs/feature_dip_switch.md +++ b/docs/feature_dip_switch.md @@ -7,9 +7,17 @@ DIP switches are supported by adding this to your `rules.mk`: and this to your `config.h`: ```c +// Connects each switch in the dip switch to the GPIO pin of the MCU #define DIP_SWITCH_PINS { B14, A15, A10, B9 } ``` +or + +```c +// Connect each switch in the DIP switch to an unused intersections in the key matrix. +#define DIP_SWITCH_MATRIX_GRID { {0,6}, {1,6}, {2,6} } // List of row and col pairs +``` + ## Callbacks The callback functions can be inserted into your `.c`: @@ -87,4 +95,10 @@ void dip_switch_update_mask_user(uint32_t state) { ## Hardware +### Connects each switch in the dip switch to the GPIO pin of the MCU + One side of the DIP switch should be wired directly to the pin on the MCU, and the other side to ground. It should not matter which side is connected to which, as it should be functionally the same. + +### Connect each switch in the DIP switch to an unused intersections in the key matrix. + +As with the keyswitch, a diode and DIP switch connect the ROW line to the COL line. diff --git a/docs/feature_dynamic_macros.md b/docs/feature_dynamic_macros.md index b86df6c60ff..01f2a0ca407 100644 --- a/docs/feature_dynamic_macros.md +++ b/docs/feature_dynamic_macros.md @@ -18,11 +18,11 @@ That should be everything necessary. To start recording the macro, press either `DYN_REC_START1` or `DYN_REC_START2`. -To finish the recording, press the `DYN_REC_STOP` layer button. +To finish the recording, press the `DYN_REC_STOP` layer button. You can also press `DYN_REC_START1` or `DYN_REC_START2` again to stop the recording. To replay the macro, press either `DYN_MACRO_PLAY1` or `DYN_MACRO_PLAY2`. -It is possible to replay a macro as part of a macro. It's ok to replay macro 2 while recording macro 1 and vice versa but never create recursive macros i.e. macro 1 that replays macro 1. If you do so and the keyboard will get unresponsive, unplug the keyboard and plug it again. You can disable this completly by defining `DYNAMIC_MACRO_NO_NESTING` in your `config.h` file. +It is possible to replay a macro as part of a macro. It's ok to replay macro 2 while recording macro 1 and vice versa but never create recursive macros i.e. macro 1 that replays macro 1. If you do so and the keyboard will get unresponsive, unplug the keyboard and plug it again. You can disable this completely by defining `DYNAMIC_MACRO_NO_NESTING` in your `config.h` file. ?> For the details about the internals of the dynamic macros, please read the comments in the `process_dynamic_macro.h` and `process_dynamic_macro.c` files. diff --git a/docs/feature_encoders.md b/docs/feature_encoders.md index cbf72914e92..e2cafdac48e 100644 --- a/docs/feature_encoders.md +++ b/docs/feature_encoders.md @@ -2,58 +2,81 @@ Basic encoders are supported by adding this to your `rules.mk`: - ENCODER_ENABLE = yes +```make +ENCODER_ENABLE = yes +``` and this to your `config.h`: - #define ENCODERS_PAD_A { B12 } - #define ENCODERS_PAD_B { B13 } +```c +#define ENCODERS_PAD_A { B12 } +#define ENCODERS_PAD_B { B13 } +``` Each PAD_A/B variable defines an array so multiple encoders can be defined, e.g.: - #define ENCODERS_PAD_A { encoder1a, encoder2a } - #define ENCODERS_PAD_B { encoder1b, encoder2b } +```c +#define ENCODERS_PAD_A { encoder1a, encoder2a } +#define ENCODERS_PAD_B { encoder1b, encoder2b } +``` -If your encoder's clockwise directions are incorrect, you can swap the A & B pad definitions. +If your encoder's clockwise directions are incorrect, you can swap the A & B pad definitions. They can also be flipped with a define: -Additionally, the resolution can be specified in the same file (the default & suggested is 4): +```c +#define ENCODER_DIRECTION_FLIP +``` - #define ENCODER_RESOLUTION 4 +Additionally, the resolution, which defines how many pulses the encoder registers between each detent, can be defined with: + +```c +#define ENCODER_RESOLUTION 4 +``` + +It can also be defined per-encoder, by instead defining: + +```c +#define ENCODER_RESOLUTIONS { 4, 2 } +``` ## Split Keyboards -If you are using different pinouts for the encoders on each half of a split keyboard, you can define the pinout for the right half like this: +If you are using different pinouts for the encoders on each half of a split keyboard, you can define the pinout (and optionally, resolutions) for the right half like this: ```c #define ENCODERS_PAD_A_RIGHT { encoder1a, encoder2a } #define ENCODERS_PAD_B_RIGHT { encoder1b, encoder2b } +#define ENCODER_RESOLUTIONS_RIGHT { 2, 4 } ``` ## Callbacks The callback functions can be inserted into your `.c`: - void encoder_update_kb(uint8_t index, bool clockwise) { - encoder_update_user(index, clockwise); - } +```c +void encoder_update_kb(uint8_t index, bool clockwise) { + encoder_update_user(index, clockwise); +} +``` or `keymap.c`: - void encoder_update_user(uint8_t index, bool clockwise) { - if (index == 0) { /* First encoder */ +```c +void encoder_update_user(uint8_t index, bool clockwise) { + if (index == 0) { /* First encoder */ if (clockwise) { - tap_code(KC_PGDN); + tap_code(KC_PGDN); } else { - tap_code(KC_PGUP); + tap_code(KC_PGUP); } - } else if (index == 1) { /* Second encoder */ + } else if (index == 1) { /* Second encoder */ if (clockwise) { - tap_code(KC_UP); + tap_code(KC_DOWN); } else { - tap_code(KC_DOWN); + tap_code(KC_UP); } - } } +} +``` ## Hardware diff --git a/docs/feature_haptic_feedback.md b/docs/feature_haptic_feedback.md index ff7337a51a4..a092e784c77 100644 --- a/docs/feature_haptic_feedback.md +++ b/docs/feature_haptic_feedback.md @@ -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. diff --git a/docs/feature_hd44780.md b/docs/feature_hd44780.md index 0a174035be8..dc476c734f8 100644 --- a/docs/feature_hd44780.md +++ b/docs/feature_hd44780.md @@ -1,6 +1,6 @@ # HD44780 LCD Displays -This is an integration of Peter Fleury's LCD library. This page will explain the basics. [For in depth documentation visit his page.](http://homepage.hispeed.ch/peterfleury/doxygen/avr-gcc-libraries/group__pfleury__lcd.html) +This is an integration of Peter Fleury's LCD library. This page will explain the basics. [For in depth documentation visit his page.](http://www.peterfleury.epizy.com/doxygen/avr-gcc-libraries/group__pfleury__lcd.html) You can enable support for HD44780 Displays by setting the `HD44780_ENABLE` flag in your keyboards `rules.mk` to yes. @@ -50,8 +50,8 @@ LCD_DISP_ON_CURSOR_BLINK : display on, cursor on flashing ```` This is best done in your keyboards `matrix_init_kb` or your keymaps `matrix_init_user`. It is advised to clear the display before use. -To do so call `lcd_clrsrc()`. +To do so call `lcd_clrscr()`. To now print something to your Display you first call `lcd_gotoxy(column, line)`. To go to the start of the first line you would call `lcd_gotoxy(0, 0)` and then print a string with `lcd_puts("example string")`. -There are more methods available to control the display. [For in depth documentation please visit the linked page.](http://homepage.hispeed.ch/peterfleury/doxygen/avr-gcc-libraries/group__pfleury__lcd.html) +There are more methods available to control the display. [For in depth documentation please visit the linked page.](http://www.peterfleury.epizy.com/doxygen/avr-gcc-libraries/group__pfleury__lcd.html) diff --git a/docs/feature_joystick.md b/docs/feature_joystick.md new file mode 100644 index 00000000000..12bbf5b35ef --- /dev/null +++ b/docs/feature_joystick.md @@ -0,0 +1,153 @@ +## Joystick + +The keyboard can be made to be recognized as a joystick HID device by the operating system. + +This is enabled by adding `JOYSTICK_ENABLE` to `rules.mk`. You can set this value to `analog`, `digital`, or `no`. + +!> Joystick support is not currently available on V-USB devices. + +The joystick feature provides two services: + * reading analog input devices (eg. potentiometers) + * sending gamepad HID reports + +Both services can be used without the other, depending on whether you just want to read a device but not send gamepad reports (for volume control for instance) +or send gamepad reports based on values computed by the keyboard. + +### Analog Input + +To use analog input you must first enable it in `rules.mk`: + +```makefile +JOYSTICK_ENABLE = analog +``` + +An analog device such as a potentiometer found on a gamepad's analog axes is based on a [voltage divider](https://en.wikipedia.org/wiki/Voltage_divider). +It is composed of three connectors linked to the ground, the power input and power output (usually the middle one). The power output holds the voltage that varies based on the position of the cursor, +which value will be read using your MCU's [ADC](https://en.wikipedia.org/wiki/Analog-to-digital_converter). +Depending on which pins are already used by your keyboard's matrix, the rest of the circuit can get a little bit more complicated, +feeding the power input and ground connection through pins and using diodes to avoid bad interactions with the matrix scanning procedures. + +### Configuring the Joystick + +By default, two axes and eight buttons are defined. This can be changed in your `config.h`: + +```c +// Max 32 +#define JOYSTICK_BUTTON_COUNT 16 +// Max 6: X, Y, Z, Rx, Ry, Rz +#define JOYSTICK_AXES_COUNT 3 +``` + +When defining axes for your joystick, you have to provide a definition array. You can do this from your keymap.c file. +A joystick will either be read from an input pin that allows the use of the ADC, or can be virtual, so that its value is provided by your code. +You have to define an array of type ''joystick_config_t'' and of proper size. + +There are three ways for your circuit to work with the ADC, that relies on the use of 1, 2 or 3 pins of the MCU: + * 1 pin: your analog device is directly connected to your device GND and VCC. The only pin used is the ADC pin of your choice. + * 2 pins: your analog device is powered through a pin that allows toggling it on or off. The other pin is used to read the input value through the ADC. + * 3 pins: both the power input and ground are connected to pins that must be set to a proper state before reading and restored afterwards. + +The configuration of each axis is performed using one of four macros: + * `JOYSTICK_AXIS_VIRTUAL`: no ADC reading must be performed, that value will be provided by keyboard/keymap-level code + * `JOYSTICK_AXIS_IN(INPUT_PIN, LOW, REST, HIGH)`: a voltage will be read on the provided pin, which must be an ADC-capable pin. + * `JOYSTICK_AXIS_IN_OUT(INPUT_PIN, OUTPUT_PIN, LOW, REST, HIGH)`: the provided `OUTPUT_PIN` will be set high before `INPUT_PIN` is read. + * `JOYSTICK_AXIS_IN_OUT_GROUND(INPUT_PIN, OUTPUT_PIN, GROUND_PIN, LOW, REST, HIGH)`: the `OUTPUT_PIN` will be set high and `GROUND_PIN` will be set low before reading from `INPUT_PIN`. + +In any case where an ADC reading takes place (when `INPUT_PIN` is provided), additional `LOW`, `REST` and `HIGH` parameters are used. +These implement the calibration of the analog device by defining the range of read values that will be mapped to the lowest, resting position and highest possible value for the axis (-127 to 127). +In practice, you have to provide the lowest/highest raw ADC reading, and the raw reading at resting position, when no deflection is applied. You can provide inverted `LOW` and `HIGH` to invert the axis. + +For instance, an axes configuration can be defined in the following way: + +```c +//joystick config +joystick_config_t joystick_axes[JOYSTICK_AXES_COUNT] = { + [0] = JOYSTICK_AXIS_IN_OUT_GROUND(A4, B0, A7, 900, 575, 285), + [1] = JOYSTICK_AXIS_VIRTUAL +}; +``` + +When the ADC reads 900 or higher, the returned axis value will be -127, whereas it will be 127 when the ADC reads 285 or lower. Zero is returned when 575 is read. + +In this example, the first axis will be read from the `A4` pin while `B0` is set high and `A7` is set low, using `analogReadPin()`, whereas the second axis will not be read. + +In order to give a value to the second axis, you can do so in any customizable entry point: as an action, in `process_record_user()` or in `matrix_scan_user()`, or even in `joystick_task()` which is called even when no key has been pressed. +You assign a value by writing to `joystick_status.axes[axis_index]` a signed 8-bit value (ranging from -127 to 127). Then it is necessary to assign the flag `JS_UPDATED` to `joystick_status.status` in order for an updated HID report to be sent. + +The following example writes two axes based on keypad presses, with `KC_P5` as a precision modifier: + +```c +#ifdef ANALOG_JOYSTICK_ENABLE +static uint8_t precision_val = 70; +static uint8_t axesFlags = 0; +enum axes { + Precision = 1, + Axis1High = 2, + Axis1Low = 4, + Axis2High = 8, + Axis2Low = 16 +}; +#endif + +bool process_record_user(uint16_t keycode, keyrecord_t *record) { + switch(keycode) { +#ifdef ANALOG_JOYSTICK_ENABLE + // virtual joystick +# if JOYSTICK_AXES_COUNT > 1 + case KC_P8: + if (record->event.pressed) { + axesFlags |= Axis2Low; + } else { + axesFlags &= ~Axis2Low; + } + joystick_status.status |= JS_UPDATED; + break; + case KC_P2: + if (record->event.pressed) { + axesFlags |= Axis2High; + } else { + axesFlags &= ~Axis2High; + } + joystick_status.status |= JS_UPDATED; + break; +# endif + case KC_P4: + if (record->event.pressed) { + axesFlags |= Axis1Low; + } else { + axesFlags &= ~Axis1Low; + } + joystick_status.status |= JS_UPDATED; + break; + case KC_P6: + if (record->event.pressed) { + axesFlags |= Axis1High; + } else { + axesFlags &= ~Axis1High; + } + joystick_status.status |= JS_UPDATED; + break; + case KC_P5: + if (record->event.pressed) { + axesFlags |= Precision; + } else { + axesFlags &= ~Precision; + } + joystick_status.status |= JS_UPDATED; + break; +#endif + } + return true; +} +``` + +### 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. +To trigger a joystick button, just add the corresponding keycode to your keymap. diff --git a/docs/feature_key_lock.md b/docs/feature_key_lock.md index 46935adda06..8e6e29f0e68 100644 --- a/docs/feature_key_lock.md +++ b/docs/feature_key_lock.md @@ -16,7 +16,7 @@ First, enable Key Lock by setting `KEY_LOCK_ENABLE = yes` in your `rules.mk`. Th ## Caveats -Key Lock is only able to hold standard action keys and [One Shot modifier](feature_advanced_keycodes.md#one-shot-keys) keys (for example, if you have your Shift defined as `OSM(KC_LSFT)`). +Key Lock is only able to hold standard action keys and [One Shot modifier](one_shot_keys.md) keys (for example, if you have your Shift defined as `OSM(KC_LSFT)`). This does not include any of the QMK special functions (except One Shot modifiers), or shifted versions of keys such as `KC_LPRN`. If it's in the [Basic Keycodes](keycodes_basic.md) list, it can be held. Switching layers will not cancel the Key Lock. diff --git a/docs/feature_layers.md b/docs/feature_layers.md new file mode 100644 index 00000000000..3f62cfc805a --- /dev/null +++ b/docs/feature_layers.md @@ -0,0 +1,93 @@ +# Layers :id=layers + +One of the most powerful and well used features of QMK Firmware is the ability to use layers. For most people, this amounts to a function key that allows for different keys, much like what you would see on a laptop or tablet keyboard. + +For a detailed explanation of how the layer stack works, checkout [Keymap Overview](keymap.md#keymap-and-layers). + +## Switching and Toggling Layers :id=switching-and-toggling-layers + +These functions allow you to activate layers in various ways. Note that layers are not generally independent layouts -- multiple layers can be activated at once, and it's typical for layers to use `KC_TRNS` to allow keypresses to pass through to lower layers. When using momentary layer switching with MO(), LM(), TT(), or LT(), make sure to leave the key on the above layers transparent or it may not work as intended. + +* `DF(layer)` - switches the default layer. The default layer is the always-active base layer that other layers stack on top of. See below for more about the default layer. This might be used to switch from QWERTY to Dvorak layout. (Note that this is a temporary switch that only persists until the keyboard loses power. To modify the default layer in a persistent way requires deeper customization, such as calling the `set_single_persistent_default_layer` function inside of [process_record_user](custom_quantum_functions.md#programming-the-behavior-of-any-keycode).) +* `MO(layer)` - momentarily activates *layer*. As soon as you let go of the key, the layer is deactivated. +* `LM(layer, mod)` - Momentarily activates *layer* (like `MO`), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers: `MOD_LCTL`, `MOD_LSFT`, `MOD_LALT`, `MOD_LGUI` (note the use of `MOD_` constants instead of `KC_`). These modifiers can be combined using bitwise OR, e.g. `LM(_RAISE, MOD_LCTL | MOD_LALT)`. +* `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped. Only supports layers 0-15. +* `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys](one_shot_keys.md) for details and additional functionality. +* `TG(layer)` - toggles *layer*, activating it if it's inactive and vice versa +* `TO(layer)` - activates *layer* and de-activates all other layers (except your default layer). This function is special, because instead of just adding/removing one layer to your active layer stack, it will completely replace your current active layers, uniquely allowing you to replace higher layers with a lower one. This is activated on keydown (as soon as the key is pressed). +* `TT(layer)` - Layer Tap-Toggle. If you hold the key down, *layer* is activated, and then is de-activated when you let go (like `MO`). If you repeatedly tap it, the layer will be toggled on or off (like `TG`). It needs 5 taps by default, but you can change this by defining `TAPPING_TOGGLE` -- for example, `#define TAPPING_TOGGLE 2` to toggle on just two taps. + +### Caveats :id=caveats + +Currently, `LT()` and `MT()` are limited to the [Basic Keycode set](keycodes_basic.md), meaning you can't use keycodes like `LCTL()`, `KC_TILD`, or anything greater than `0xFF`. Specifically, dual function keys like `LT` and `MT` use a 16 bit keycode. 4 bits are used for the function identifier, the next 12 are divided into the parameters. Layer Tap uses 4 bits for the layer (and is why it's limited to layers 0-15, actually), while Mod Tap does the same, 4 bits for the identifier, 4 bits for which mods are used, and all of them use 8 bits for the keycode. Because of this, the keycode used is limited to `0xFF` (0-255), which are the basic keycodes only. + +Expanding this would be complicated, at best. Moving to a 32-bit keycode would solve a lot of this, but would double the amount of space that the keymap matrix uses. And it could potentially cause issues, too. If you need to apply modifiers to your tapped keycode, [Tap Dance](feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys) can be used to accomplish this. + +Additionally, if at least one right-handed modifier is specified in a Mod Tap or Layer Tap, it will cause all modifiers specified to become right-handed, so it is not possible to mix and match the two. + +## Working with Layers :id=working-with-layers + +Care must be taken when switching layers, it's possible to lock yourself into a layer with no way to deactivate that layer (without unplugging your keyboard.) We've created some guidelines to help users avoid the most common problems. + +### Beginners :id=beginners + +If you are just getting started with QMK you will want to keep everything simple. Follow these guidelines when setting up your layers: + +* Setup layer 0 as your default, "base" layer. This is your normal typing layer, and could be whatever layout you want (qwerty, dvorak, colemak, etc.). It's important to set this as the lowest layer since it will typically have most or all of the keyboard's keys defined, so would block other layers from having any effect if it were above them (i.e., had a higher layer number). +* Arrange your layers in a "tree" layout, with layer 0 as the root. Do not try to enter the same layer from more than one other layer. +* In a layer's keymap, only reference higher-numbered layers. Because layers are processed from the highest-numbered (topmost) active layer down, modifying the state of lower layers can be tricky and error-prone. + +### Intermediate Users :id=intermediate-users + +Sometimes you need more than one base layer. For example, if you want to switch between QWERTY and Dvorak, switch between layouts for different countries, or switch your layout for different videogames. Your base layers should always be the lowest numbered layers. When you have multiple base layers you should always treat them as mutually exclusive. When one base layer is on the others are off. + +### Advanced Users :id=advanced-users + +Once you have a good feel for how layers work and what you can do, you can get more creative. The rules listed in the beginner section will help you be successful by avoiding some of the tricker details but they can be constraining, especially for ultra-compact keyboard users. Understanding how layers work will allow you to use them in more advanced ways. + +Layers stack on top of each other in numerical order. When determining what a keypress does, QMK scans the layers from the top down, stopping when it reaches the first active layer that is not set to `KC_TRNS`. As a result if you activate a layer that is numerically lower than your current layer, and your current layer (or another layer that is active and higher than your target layer) has something other than `KC_TRNS`, that is the key that will be sent, not the key on the layer you just activated. This is the cause of most people's "why doesn't my layer get switched" problem. + +Sometimes, you might want to switch between layers in a macro or as part of a tap dance routine. `layer_on` activates a layer, and `layer_off` deactivates it. More layer-related functions can be found in [action_layer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/action_layer.h). + +## Functions :id=functions + +There are a number of functions (and variables) related to how you can use or manipulate the layers. + +|Function |Description | +|----------------------------------------------|---------------------------------------------------------------------------------------------------------| +| `layer_state_set(layer_mask)` | Directly sets the layer state (recommended, do not use unless you know what you are doing). | +| `layer_clear()` | Clears all layers (turns them all off). | +| `layer_move(layer)` | Turns specified layer on, and all other layers off. | +| `layer_on(layer)` | Turns specified layer on, leaves all other layers in existing state. | +| `layer_off(layer)` | Turns specified layer off, leaves all other layers in existing state. | +| `layer_invert(layer)` | Interverts/toggles the state of the specified layer | +| `layer_or(layer_mask)` | Turns on layers based on matching bits between specifed layer and existing layer state. | +| `layer_and(layer_mask)` | Turns on layers based on matching enabled bits between specifed layer and existing layer state. | +| `layer_xor(layer_mask)` | Turns on layers based on non-matching bits between specifed layer and existing layer state. | +| `layer_debug(layer_mask)` | Prints out the current bit mask and highest active layer to debugger console. | +| `default_layer_set(layer_mask)` | Directly sets the default layer state (recommended, do not use unless you know what you are doing). | +| `default_layer_or(layer_mask)` | Turns on layers based on matching bits between specifed layer and existing default layer state. | +| `default_layer_and(layer_mask)` | Turns on layers based on matching enabled bits between specifed layer and existing default layer state. | +| `default_layer_xor(layer_mask)` | Turns on layers based on non-matching bits between specifed layer and existing default layer state. | +| `default_layer_debug(layer_mask)` | Prints out the current bit mask and highest active default layer to debugger console. | +| [`set_single_persistent_default_layer(layer)`](ref_functions.md#setting-the-persistent-default-layer) | Sets the default layer and writes it to persistent memory (EEPROM). | +| [`update_tri_layer(x, y, z)`](ref_functions.md#update_tri_layerx-y-z) | Checks if layers `x` and `y` are both on, and sets `z` based on that (on if both on, otherwise off). | +| [`update_tri_layer_state(state, x, y, z)`](ref_functions.md#update_tri_layer_statestate-x-y-z) | Does the same as `update_tri_layer(x, y, z)`, but from `layer_state_set_*` functions. | + +In addition to the functions that you can call, there are a number of callback functions that get called every time the layer changes. This passes the layer state to the function, where it can be read or modified. + +|Callback |Description | +|-----------------------------------------------------|----------------------------------------------------------------------------------------| +| `layer_state_set_kb(layer_state_t state)` | Callback for layer functions, for keyboard. | +| `layer_state_set_user(layer_state_t state)` | Callback for layer functions, for users. | +| `default_layer_state_set_kb(layer_state_t state)` | Callback for default layer functions, for keyboard. Called on keyboard initialization. | +| `default_layer_state_set_user(layer_state_t state)` | Callback for default layer functions, for users. Called on keyboard initialization. | + +?> For additional details on how you can use these callbacks, check out the [Layer Change Code](custom_quantum_functions.md#layer-change-code) document. + +It is also possible to check the state of a particular layer using the following functions and macros. + +|Function |Description |Aliases +|---------------------------------|-------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------| +| `layer_state_is(layer)` | Checks if the specified `layer` is enabled globally. | `IS_LAYER_ON(layer)`, `IS_LAYER_OFF(layer)` | +| `layer_state_cmp(state, layer)` | Checks `state` to see if the specified `layer` is enabled. Intended for use in layer callbacks. | `IS_LAYER_ON_STATE(state, layer)`, `IS_LAYER_OFF_STATE(state, layer)` | diff --git a/docs/feature_leader_key.md b/docs/feature_leader_key.md index 22370bf230e..41ff8f1a4e2 100644 --- a/docs/feature_leader_key.md +++ b/docs/feature_leader_key.md @@ -5,7 +5,7 @@ If you've ever used Vim, you know what a Leader key is. If not, you're about to That's what `KC_LEAD` does. Here's an example: 1. Pick a key on your keyboard you want to use as the Leader key. Assign it the keycode `KC_LEAD`. This key would be dedicated just for this -- it's a single action key, can't be used for anything else. -2. Include the line `#define LEADER_TIMEOUT 300` in your `config.h`. This sets the timeout for the `KC_LEAD` key. Specifically, when you press the `KC_LEAD` key, you only have a certain amount of time to complete the Leader Key sequence. The `300` here sets that to 300ms, and you can increase this value to give you more time to hit the sequence. But any keys pressed during this timeout are intercepted and not sent, so you may want to keep this value low. . +2. Include the line `#define LEADER_TIMEOUT 300` in your `config.h`. This sets the timeout for the `KC_LEAD` key. Specifically, when you press the `KC_LEAD` key, you only have a certain amount of time to complete the Leader Key sequence. The `300` here sets that to 300ms, and you can increase this value to give you more time to hit the sequence. But any keys pressed during this timeout are intercepted and not sent, so you may want to keep this value low. * By default, this timeout is how long after pressing `KC_LEAD` to complete your entire sequence. This may be very low for some people. So you may want to increase this timeout. Optionally, you may want to enable the `LEADER_PER_KEY_TIMING` option, which resets the timeout after each key is tapped. This allows you to maintain a low value here, but still be able to use the longer sequences. To enable this option, add `#define LEADER_PER_KEY_TIMING` to your `config.h`. 3. Within your `matrix_scan_user` function, add something like this: @@ -74,9 +74,9 @@ SEQ_THREE_KEYS(KC_C, KC_C, KC_C) { ## Strict Key Processing -By default, the Leader Key feature will filter the keycode out of [`Mod-Tap`](feature_advanced_keycodes.md#mod-tap) and [`Layer Tap`](feature_advanced_keycodes.md#switching-and-toggling-layers) functions when checking for the Leader sequences. That means if you're using `LT(3, KC_A)`, it will pick this up as `KC_A` for the sequence, rather than `LT(3, KC_A)`, giving a more expected behavior for newer users. +By default, the Leader Key feature will filter the keycode out of [`Mod-Tap`](mod_tap.md) and [`Layer Tap`](feature_layers.md#switching-and-toggling-layers) functions when checking for the Leader sequences. That means if you're using `LT(3, KC_A)`, it will pick this up as `KC_A` for the sequence, rather than `LT(3, KC_A)`, giving a more expected behavior for newer users. -While, this may be fine for most, if you want to specify the whole keycode (eg, `LT(3, KC_A)` from the example above) in the sequence, you can enable this by added `#define LEADER_KEY_STRICT_KEY_PROCESSING` to your `config.h` file. This well then disable the filtering, and you'll need to specify the whole keycode. +While, this may be fine for most, if you want to specify the whole keycode (eg, `LT(3, KC_A)` from the example above) in the sequence, you can enable this by added `#define LEADER_KEY_STRICT_KEY_PROCESSING` to your `config.h` file. This will then disable the filtering, and you'll need to specify the whole keycode. ## Customization @@ -92,7 +92,7 @@ void leader_start(void) { } void leader_end(void) { - // sequence ended (no success/failuer detection) + // sequence ended (no success/failure detection) } ``` diff --git a/docs/feature_led_indicators.md b/docs/feature_led_indicators.md new file mode 100644 index 00000000000..10e095ab155 --- /dev/null +++ b/docs/feature_led_indicators.md @@ -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). diff --git a/docs/feature_led_matrix.md b/docs/feature_led_matrix.md index 372407b90c2..f4a6616340c 100644 --- a/docs/feature_led_matrix.md +++ b/docs/feature_led_matrix.md @@ -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_` 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_ | `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_ 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 `.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 `.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 `.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); +} +``` \ No newline at end of file diff --git a/docs/feature_macros.md b/docs/feature_macros.md index c13ae82061a..3660f377559 100644 --- a/docs/feature_macros.md +++ b/docs/feature_macros.md @@ -4,36 +4,36 @@ 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 just want a key to type out words or phrases. For the most common situations we've provided `SEND_STRING()`, which will type out your string (i.e. a sequence of characters) for you. All ASCII characters that are easily translated to a keycode are supported (e.g. `\n\t`). +Sometimes you want a key to type out words or phrases. For the most common situations, we've provided `SEND_STRING()`, which will type out a string (i.e. a sequence of characters) for you. All ASCII characters that are easily translatable to a keycode are supported (e.g. `qmk 123\n\t`). Here is an example `keymap.c` for a two-key keyboard: ```c enum custom_keycodes { - QMKBEST = SAFE_RANGE, + QMKBEST = SAFE_RANGE, }; bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { + switch (keycode) { case QMKBEST: - if (record->event.pressed) { - // when keycode QMKBEST is pressed - SEND_STRING("QMK is the best thing ever!"); - } else { - // when keycode QMKBEST is released - } - break; - - } - return true; + if (record->event.pressed) { + // when keycode QMKBEST is pressed + SEND_STRING("QMK is the best thing ever!"); + } else { + // when keycode QMKBEST is released + } + break; + } + return true; }; const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - [0] = { - {QMKBEST, KC_ESC} - } + [0] = { + {QMKBEST, KC_ESC}, + // ... + }, }; ``` @@ -49,45 +49,88 @@ You can do that by adding another keycode and adding another case to the switch ```c enum custom_keycodes { - QMKBEST = SAFE_RANGE, - QMKURL, - MY_OTHER_MACRO + QMKBEST = SAFE_RANGE, + QMKURL, + MY_OTHER_MACRO, }; bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { + switch (keycode) { case QMKBEST: - if (record->event.pressed) { - // when keycode QMKBEST is pressed - SEND_STRING("QMK is the best thing ever!"); - } else { - // when keycode QMKBEST is released - } - break; + if (record->event.pressed) { + // when keycode QMKBEST is pressed + SEND_STRING("QMK is the best thing ever!"); + } else { + // when keycode QMKBEST is released + } + break; + case QMKURL: - if (record->event.pressed) { - // when keycode QMKURL is pressed - SEND_STRING("https://qmk.fm/\n"); - } else { - // when keycode QMKURL is released - } - break; + if (record->event.pressed) { + // when keycode QMKURL is pressed + SEND_STRING("https://qmk.fm/\n"); + } else { + // when keycode QMKURL is released + } + break; + case MY_OTHER_MACRO: + if (record->event.pressed) { + SEND_STRING(SS_LCTL("ac")); // selects all and copies + } + break; + } + return true; +}; + +const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { + [0] = { + {MY_CUSTOM_MACRO, MY_OTHER_MACRO}, + // ... + }, +}; +``` + +### Advanced Macros + +In addition to the `process_record_user()` function, is the `post_process_record_user()` function. This runs after `process_record` and can be used to do things after a keystroke has been sent. This is useful if you want to have a key pressed before and released after a normal key, for instance. + +In this example, we modify most normal keypresses so that `F22` is pressed before the keystroke is normally sent, and release it __only after__ it's been released. + +```c +static uint8_t f22_tracker; + +bool process_record_user(uint16_t keycode, keyrecord_t *record) { + switch (keycode) { + case KC_A ... KC_F21: //notice how it skips over F22 + case KC_F23 ... KC_EXSEL: //exsel is the last one before the modifier keys if (record->event.pressed) { - SEND_STRING(SS_LCTL("ac")); // selects all and copies + register_code(KC_F22); //this means to send F22 down + f22_tracker++; + register_code(keycode); + return false; } break; } return true; -}; +} -const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - [0] = { - {MY_CUSTOM_MACRO, MY_OTHER_MACRO} +void post_process_record_user(uint16_t keycode, keyrecord_t *record) { + switch (keycode) { + case KC_A ... KC_F21: //notice how it skips over F22 + case KC_F23 ... KC_EXSEL: //exsel is the last one before the modifier keys + if (!record->event.pressed) { + f22_tracker--; + if (!f22_tracker) { + unregister_code(KC_F22); //this means to send F22 up + } + } + break; } -}; +} ``` + ### TAP, DOWN and UP You may want to use keys in your macros that you can't write down, such as `Ctrl` or `Home`. @@ -107,15 +150,25 @@ Would tap `KC_HOME` - note how the prefix is now `X_`, and not `KC_`. You can al Which would send "VE" followed by a `KC_HOME` tap, and "LO" (spelling "LOVE" if on a newline). +Delays can be also added to the string: + +* `SS_DELAY(msecs)` will delay for the specified number of milliseconds. + +For example: + + SEND_STRING("VE" SS_DELAY(1000) SS_TAP(X_HOME) "LO"); + +Which would send "VE" followed by a 1-second delay, then a `KC_HOME` tap, and "LO" (spelling "LOVE" if on a newline, but delayed in the middle). + There's also a couple of mod shortcuts you can use: * `SS_LCTL(string)` * `SS_LSFT(string)` -* `SS_LALT(string)` +* `SS_LALT(string)` or `SS_LOPT(string)` * `SS_LGUI(string)`, `SS_LCMD(string)` or `SS_LWIN(string)` * `SS_RCTL(string)` * `SS_RSFT(string)` -* `SS_RALT(string)` or `SS_ALGR(string)` +* `SS_RALT(string)`, `SS_ROPT(string)` or `SS_ALGR(string)` * `SS_RGUI(string)`, `SS_RCMD(string)` or `SS_RWIN(string)` These press the respective modifier, send the supplied string and then release the modifier. @@ -129,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 +```c +#include "sendstring_colemak.h" +``` ### Strings in Memory @@ -154,6 +209,8 @@ 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) 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` This is a boolean value that can be tested to see if the switch is being pressed or released. An example of this is @@ -176,9 +233,15 @@ Parallel to `register_code` function, this sends the `` keyup event to the c ### `tap_code();` -This will send `register_code()` and then `unregister_code()`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it). +Sends `register_code()` and then `unregister_code()`. 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()`. 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(, );` + +Like `tap_code()`, but with a `delay` parameter for specifying arbitrary intervals before sending the unregister event. ### `register_code16();`, `unregister_code16();` and `tap_code16();` @@ -198,28 +261,28 @@ This will clear all mods currently pressed. This will clear all keys besides the mods currently pressed. -## Advanced Example: +## Advanced Example: ### Super ALT↯TAB -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. +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) { is_alt_tab_active = true; register_code(KC_LALT); - } + } alt_tab_timer = timer_read(); register_code(KC_TAB); } else { @@ -230,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); @@ -239,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; -}; -``` diff --git a/docs/feature_mouse_keys.md b/docs/feature_mouse_keys.md index 363662f633b..8e2a3a4cd1c 100644 --- a/docs/feature_mouse_keys.md +++ b/docs/feature_mouse_keys.md @@ -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 | @@ -39,10 +42,12 @@ In your keymap you can use the following keycodes to map key presses to mouse ac ## Configuring mouse keys -Mouse keys supports two different modes to move the cursor: +Mouse keys supports three different modes to move the cursor: * **Accelerated (default):** Holding movement keys accelerates the cursor until it reaches its maximum speed. +* **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. The same principle applies to scrolling. @@ -55,9 +60,12 @@ 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 | +|`MOUSEKEY_WHEEL_INTERVAL` |100 |Time between wheel movements | |`MOUSEKEY_WHEEL_MAX_SPEED` |8 |Maximum number of scroll steps per scroll action | |`MOUSEKEY_WHEEL_TIME_TO_MAX`|40 |Time until maximum scroll speed is reached | @@ -66,9 +74,34 @@ Tips: * Setting `MOUSEKEY_DELAY` too low makes the cursor unresponsive. Setting it too high makes small movements difficult. * For smoother cursor movements, lower the value of `MOUSEKEY_INTERVAL`. If the refresh rate of your display is 60Hz, you could set it to `16` (1/60). As this raises the cursor speed significantly, you may want to lower `MOUSEKEY_MAX_SPEED`. * Setting `MOUSEKEY_TIME_TO_MAX` or `MOUSEKEY_WHEEL_TIME_TO_MAX` to `0` will disable acceleration for the cursor or scrolling respectively. This way you can make one of them constant while keeping the other accelerated, which is not possible in constant speed mode. +* Setting `MOUSEKEY_WHEEL_INTERVAL` too low will make scrolling too fast. Setting it too high will make scrolling too slow when the wheel key is held down. 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. @@ -117,3 +150,26 @@ Use the following settings if you want to adjust cursor movement or scrolling: |`MK_W_INTERVAL_1` |120 |Time between scroll steps (`KC_ACL1`) | |`MK_W_OFFSET_2` |1 |Scroll steps per scroll action (`KC_ACL2`) | |`MK_W_INTERVAL_2` |20 |Time between scroll steps (`KC_ACL2`) | + +### Combined mode + +This mode functions like **Accelerated** mode, however, you can hold `KC_ACL0`, `KC_ACL1` and `KC_ACL2` +to momentarily (while held) set the cursor and scroll speeds to constant speeds. When no acceleration +keys are held, this mode is identical to **Accelerated** mode, and can be modified using all of the +relevant settings. + +* **KC_ACL0:** This acceleration sets your cursor to the slowest possible speed. This is useful for very +small and detailed movements of the cursor. +* **KC_ACL1:** This acceleration sets your cursor to half the maximum (user defined) speed. +* **KC_ACL2:** This acceleration sets your cursor to the maximum (computer defined) speed. This is +useful for moving the cursor large distances without much accuracy. + +To use constant speed mode, you must at least define `MK_COMBINED` in your keymap’s `config.h` file: + +```c +#define MK_COMBINED +``` + +## Use with PS/2 Mouse and Pointing Device + +Mouse keys button state is shared with [PS/2 mouse](feature_ps2_mouse.md) and [pointing device](feature_pointing_device.md) so mouse keys button presses can be used for clicks and drags. diff --git a/docs/feature_oled_driver.md b/docs/feature_oled_driver.md index b124ba5a8f5..44202487f15 100644 --- a/docs/feature_oled_driver.md +++ b/docs/feature_oled_driver.md @@ -1,139 +1,181 @@ # OLED Driver -## OLED Supported Hardware +## Supported Hardware OLED modules using SSD1306 or SH1106 driver ICs, communicating over I2C. Tested combinations: -| IC driver | Size | Keyboard Platform | Notes | -|-----------|--------|-------------------|--------------------------| -| SSD1306 | 128x32 | AVR | Primary support | -| SSD1306 | 128x64 | AVR | Verified working | -| SSD1306 | 128x32 | ARM | | -| SH1106 | 128x64 | AVR | No rotation or scrolling | +|IC |Size |Platform|Notes | +|---------|------|--------|------------------------| +|SSD1306 |128x32|AVR |Primary support | +|SSD1306 |128x64|AVR |Verified working | +|SSD1306 |128x32|Arm | | +|SH1106 |128x64|AVR |No rotation or scrolling| -Hardware configurations using ARM-based microcontrollers or different sizes of OLED modules may be compatible, but are untested. +Hardware configurations using Arm-based microcontrollers or different sizes of OLED modules may be compatible, but are untested. -!> Warning: This OLED Driver currently uses the new i2c_master driver from split common code. If your split keyboard uses I2C to communicate between sides, this driver could cause an address conflict (serial is fine). Please contact your keyboard vendor and ask them to migrate to the latest split common code to fix this. In addition, the display timeout system to reduce OLED burn-in also uses split common to detect keypresses, so you will need to implement custom timeout logic for non-split common keyboards. +!> Warning: This OLED driver currently uses the new i2c_master driver from Split Common code. If your split keyboard uses I2C to communicate between sides, this driver could cause an address conflict (serial is fine). Please contact your keyboard vendor and ask them to migrate to the latest Split Common code to fix this. In addition, the display timeout system to reduce OLED burn-in also uses Split Common to detect keypresses, so you will need to implement custom timeout logic for non-Split Common keyboards. ## Usage -To enable the OLED feature, there are three steps. First, when compiling your keyboard, you'll need to set `OLED_DRIVER_ENABLE=yes` in `rules.mk`, e.g.: +To enable the OLED feature, there are three steps. First, when compiling your keyboard, you'll need to add the following to your `rules.mk`: -``` +```make OLED_DRIVER_ENABLE = yes ``` -This enables the feature and the `OLED_DRIVER_ENABLE` define. Then in your `keymap.c` file, you will need to implement the user task call, e.g: +Then in your `keymap.c` file, implement the OLED task call. This example assumes your keymap has three layers named `_QWERTY`, `_FN` and `_ADJ`: -```C++ +```c #ifdef OLED_DRIVER_ENABLE void oled_task_user(void) { - // Host Keyboard Layer Status - oled_write_P(PSTR("Layer: "), false); - switch (get_highest_layer(layer_state)) { - case _QWERTY: - oled_write_P(PSTR("Default\n"), false); - break; - case _FN: - oled_write_P(PSTR("FN\n"), false); - break; - case _ADJ: - oled_write_P(PSTR("ADJ\n"), false); - break; - default: - // Or use the write_ln shortcut over adding '\n' to the end of your string - oled_write_ln_P(PSTR("Undefined"), false); - } + // Host Keyboard Layer Status + oled_write_P(PSTR("Layer: "), false); - // Host Keyboard LED Status - uint8_t led_usb_state = host_keyboard_leds(); - oled_write_P(led_usb_state & (1<Useful for 128x64 displays centered on a 132x64 SH1106 IC. | +|Define |Default |Description | +|---------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------| +|`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 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. | +|`OLED_SCROLL_TIMEOUT` |`0` |Scrolls the OLED screen after 0ms of OLED inactivity. Helps reduce OLED Burn-in. Set to 0 to disable. | +|`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.
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 The default display size for this feature is 128x32 and all necessary defines are precalculated with that in mind. We have added a define, `OLED_DISPLAY_128X64`, to switch all the values to be used in a 128x64 display, as well as added a custom define, `OLED_DISPLAY_CUSTOM`, that allows you to provide the necessary values to the driver. -|Define |Default |Description | -|-----------------------|---------------|-----------------------------------------------------------------| -|`OLED_DISPLAY_128X64` |*Not defined* |Changes the display defines for use with 128x64 displays. | -|`OLED_DISPLAY_CUSTOM` |*Not defined* |Changes the display defines for use with custom displays.
Requires user to implement the below defines. | -|`OLED_DISPLAY_WIDTH` |`128` |The width of the OLED display. | -|`OLED_DISPLAY_HEIGHT` |`32` |The height of the OLED display. | -|`OLED_MATRIX_SIZE` |`512` |The local buffer size to allocate.
`(OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH)`. | -|`OLED_BLOCK_TYPE` |`uint16_t` |The unsigned integer type to use for dirty rendering. | -|`OLED_BLOCK_COUNT` |`16` |The number of blocks the display is divided into for dirty rendering.
`(sizeof(OLED_BLOCK_TYPE) * 8)`. | -|`OLED_BLOCK_SIZE` |`32` |The size of each block for dirty rendering
`(OLED_MATRIX_SIZE / OLED_BLOCK_COUNT)`. | -|`OLED_COM_PINS` |`COM_PINS_SEQ` |How the SSD1306 chip maps it's memory to display.
Options are `COM_PINS_SEQ`, `COM_PINS_ALT`, `COM_PINS_SEQ_LR`, & `COM_PINS_ALT_LR`. | -|`OLED_SOURCE_MAP` |`{ 0, ... N }` |Precalculated source array to use for mapping source buffer to target OLED memory in 90 degree rendering. | -|`OLED_TARGET_MAP` |`{ 24, ... N }`|Precalculated target array to use for mapping source buffer to target OLED memory in 90 degree rendering. | +|Define |Default |Description | +|---------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------| +|`OLED_DISPLAY_128X64`|*Not defined* |Changes the display defines for use with 128x64 displays. | +|`OLED_DISPLAY_CUSTOM`|*Not defined* |Changes the display defines for use with custom displays.
Requires user to implement the below defines. | +|`OLED_DISPLAY_WIDTH` |`128` |The width of the OLED display. | +|`OLED_DISPLAY_HEIGHT`|`32` |The height of the OLED display. | +|`OLED_MATRIX_SIZE` |`512` |The local buffer size to allocate.
`(OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH)`. | +|`OLED_BLOCK_TYPE` |`uint16_t` |The unsigned integer type to use for dirty rendering. | +|`OLED_BLOCK_COUNT` |`16` |The number of blocks the display is divided into for dirty rendering.
`(sizeof(OLED_BLOCK_TYPE) * 8)`. | +|`OLED_BLOCK_SIZE` |`32` |The size of each block for dirty rendering
`(OLED_MATRIX_SIZE / OLED_BLOCK_COUNT)`. | +|`OLED_COM_PINS` |`COM_PINS_SEQ` |How the SSD1306 chip maps it's memory to display.
Options are `COM_PINS_SEQ`, `COM_PINS_ALT`, `COM_PINS_SEQ_LR`, & `COM_PINS_ALT_LR`.| +|`OLED_SOURCE_MAP` |`{ 0, ... N }` |Precalculated source array to use for mapping source buffer to target OLED memory in 90 degree rendering. | +|`OLED_TARGET_MAP` |`{ 24, ... N }`|Precalculated target array to use for mapping source buffer to target OLED memory in 90 degree rendering. | -### 90 Degree Rotation - Technical Mumbo Jumbo +### 90 Degree Rotation - Technical Mumbo Jumbo !> Rotation is unsupported on the SH1106. -```C +```c // OLED Rotation enum values are flags typedef enum { OLED_ROTATION_0 = 0, @@ -143,9 +185,9 @@ typedef enum { } oled_rotation_t; ``` - OLED displays driven by SSD1306 drivers only natively support in hard ware 0 degree and 180 degree rendering. This feature is done in software and not free. Using this feature will increase the time to calculate what data to send over i2c to the OLED. If you are strapped for cycles, this can cause keycodes to not register. In testing however, the rendering time on an `atmega32u4` board only went from 2ms to 5ms and keycodes not registering was only noticed once we hit 15ms. - - 90 Degree Rotated Rendering is achieved by using bitwise operations to rotate each 8 block of memory and uses two precalculated arrays to remap buffer memory to OLED memory. The memory map defines are precalculated for remap performance and are calculated based on the OLED Height, Width, and Block Size. For example, in the 128x32 implementation with a `uint8_t` block type, we have a 64 byte block size. This gives us eight 8 byte blocks that need to be rotated and rendered. The OLED renders horizontally two 8 byte blocks before moving down a page, e.g: +OLED displays driven by SSD1306 drivers only natively support in hardware 0 degree and 180 degree rendering. This feature is done in software and not free. Using this feature will increase the time to calculate what data to send over i2c to the OLED. If you are strapped for cycles, this can cause keycodes to not register. In testing however, the rendering time on an ATmega32U4 board only went from 2ms to 5ms and keycodes not registering was only noticed once we hit 15ms. + +90 degree rotation is achieved by using bitwise operations to rotate each 8 block of memory and uses two precalculated arrays to remap buffer memory to OLED memory. The memory map defines are precalculated for remap performance and are calculated based on the display height, width, and block size. For example, in the 128x32 implementation with a `uint8_t` block type, we have a 64 byte block size. This gives us eight 8 byte blocks that need to be rotated and rendered. The OLED renders horizontally two 8 byte blocks before moving down a page, e.g: | | | | | | | |---|---|---|---|---|---| @@ -167,8 +209,8 @@ So those precalculated arrays just index the memory offsets in the order in whic ## OLED API -```C++ -// OLED Rotation enum values are flags +```c +// OLED rotation enum values are flags typedef enum { OLED_ROTATION_0 = 0, OLED_ROTATION_90 = 1, @@ -218,6 +260,12 @@ void oled_write(const char *data, bool invert); // Advances the cursor to the next page, wiring ' ' to the remainder of the current page void oled_write_ln(const char *data, bool invert); +// Pans the buffer to the right (or left by passing true) by moving contents of the buffer +// Useful for moving the screen in preparation for new drawing +// oled_scroll_left or oled_scroll_right should be preferred for all cases of moving a static +// image such as a logo or to avoid burn-in as it's much, much less cpu intensive +void oled_pan(bool left); + // Writes a PROGMEM string to the buffer at current cursor position // Advances the cursor while writing, inverts the pixels if true // Remapped to call 'void oled_write(const char *data, bool invert);' on ARM @@ -229,12 +277,23 @@ void oled_write_P(const char *data, bool invert); // Remapped to call 'void oled_write_ln(const char *data, bool invert);' on ARM void oled_write_ln_P(const char *data, bool invert); +// Returns a pointer to the requested start index in the buffer plus remaining +// buffer length as struct +oled_buffer_reader_t oled_read_raw(uint16_t start_index); + // Writes a string to the buffer at current cursor position void oled_write_raw(const char *data, uint16_t size); +// Writes a single byte into the buffer at the specified index +void oled_write_raw_byte(const char data, uint16_t index); + // Writes a PROGMEM string to the buffer at current cursor position void oled_write_raw_P(const char *data, uint16_t size); +// Sets a specific pixel on or off +// Coordinates start at top-left and go right and down for positive x and y +void oled_write_pixel(uint8_t x, uint8_t y, bool on); + // Can be used to manually turn on the screen if it is off // Returns true if the screen was on or turns on bool oled_on(void); @@ -243,18 +302,40 @@ bool oled_on(void); // Returns true if the screen was off or turns off bool oled_off(void); +// Returns true if the oled is currently on, false if it is +// not +bool is_oled_on(void); + +// Sets the brightness level of the display +uint8_t oled_set_brightness(uint8_t level); + +// Gets the current brightness level of the display +uint8_t oled_get_brightness(void); + // Basically it's oled_render, but with timeout management and oled_task_user calling! void oled_task(void); // Called at the start of oled_task, weak function overridable by the user void oled_task_user(void); -// Scrolls the entire display right +// Set the specific 8 lines rows of the screen to scroll. +// 0 is the default for start, and 7 for end, which is the entire +// height of the screen. For 128x32 screens, rows 4-7 are not used. +void oled_scroll_set_area(uint8_t start_line, uint8_t end_line); + +// Sets scroll speed, 0-7, fastest to slowest. Default is three. +// Does not take effect until scrolling is either started or restarted +// the ssd1306 supports 8 speeds with the delay +// listed below betwen each frame of the scrolling effect +// 0=2, 1=3, 2=4, 3=5, 4=25, 5=64, 6=128, 7=256 +void oled_scroll_set_speed(uint8_t speed); + +// Begin scrolling the entire display right // Returns true if the screen was scrolling or starts scrolling // NOTE: display contents cannot be changed while scrolling bool oled_scroll_right(void); -// Scrolls the entire display left +// Begin scrolling the entire display left // Returns true if the screen was scrolling or starts scrolling // NOTE: display contents cannot be changed while scrolling bool oled_scroll_left(void); @@ -272,26 +353,26 @@ uint8_t oled_max_lines(void); !> Scrolling and rotation are unsupported on the SH1106. -## SSD1306.h driver conversion guide +## SSD1306.h Driver Conversion Guide -|Old API |Recommended New API | -|---------------------------|-----------------------------------| -|`struct CharacterMatrix` |*removed - delete all references* | -|`iota_gfx_init` |`oled_init` | -|`iota_gfx_on` |`oled_on` | -|`iota_gfx_off` |`oled_off` | -|`iota_gfx_flush` |`oled_render` | -|`iota_gfx_write_char` |`oled_write_char` | -|`iota_gfx_write` |`oled_write` | -|`iota_gfx_write_P` |`oled_write_P` | -|`iota_gfx_clear_screen` |`oled_clear` | -|`matrix_clear` |*removed - delete all references* | -|`matrix_write_char_inner` |`oled_write_char` | -|`matrix_write_char` |`oled_write_char` | -|`matrix_write` |`oled_write` | -|`matrix_write_ln` |`oled_write_ln` | -|`matrix_write_P` |`oled_write_P` | -|`matrix_write_ln_P` |`oled_write_ln_P` | -|`matrix_render` |`oled_render` | -|`iota_gfx_task` |`oled_task` | -|`iota_gfx_task_user` |`oled_task_user` | +|Old API |Recommended New API | +|-------------------------|---------------------------------| +|`struct CharacterMatrix` |*removed - delete all references*| +|`iota_gfx_init` |`oled_init` | +|`iota_gfx_on` |`oled_on` | +|`iota_gfx_off` |`oled_off` | +|`iota_gfx_flush` |`oled_render` | +|`iota_gfx_write_char` |`oled_write_char` | +|`iota_gfx_write` |`oled_write` | +|`iota_gfx_write_P` |`oled_write_P` | +|`iota_gfx_clear_screen` |`oled_clear` | +|`matrix_clear` |*removed - delete all references*| +|`matrix_write_char_inner`|`oled_write_char` | +|`matrix_write_char` |`oled_write_char` | +|`matrix_write` |`oled_write` | +|`matrix_write_ln` |`oled_write_ln` | +|`matrix_write_P` |`oled_write_P` | +|`matrix_write_ln_P` |`oled_write_ln_P` | +|`matrix_render` |`oled_render` | +|`iota_gfx_task` |`oled_task` | +|`iota_gfx_task_user` |`oled_task_user` | diff --git a/docs/feature_pointing_device.md b/docs/feature_pointing_device.md index 8ad428939a0..905c2a8f95a 100644 --- a/docs/feature_pointing_device.md +++ b/docs/feature_pointing_device.md @@ -1,10 +1,10 @@ -## Pointing Device +# Pointing Device :id=pointing-device Pointing Device is a generic name for a feature intended to be generic: moving the system pointer around. There are certainly other options for it - like mousekeys - but this aims to be easily modifiable and lightweight. You can implement custom keys to control functionality, or you can gather information from other peripherals and insert it directly here - let QMK handle the processing for you. To enable Pointing Device, uncomment the following line in your rules.mk: -``` +```makefile POINTING_DEVICE_ENABLE = yes ``` @@ -19,28 +19,34 @@ 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. -When the mouse report is sent, the x, y, v, and h values are set to 0 (this is done in "pointing_device_send()", which can be overridden to avoid this behavior). This way, button states persist, but movement will only occur once. For further customization, both `pointing_device_init` and `pointing_device_task` can be overridden. +Once you have made the necessary changes to the mouse report, you need to send it: + +* `pointing_device_send()` - Sends the mouse report to the host and zeroes out the report. + +When the mouse report is sent, the x, y, v, and h values are set to 0 (this is done in `pointing_device_send()`, which can be overridden to avoid this behavior). This way, button states persist, but movement will only occur once. For further customization, both `pointing_device_init` and `pointing_device_task` can be overridden. + +Additionally, by default, `pointing_device_send()` will only send a report when the report has actually changed. This prevents it from continuously sending mouse reports, which will keep the host system awake. This behavior can be changed by creating your own `pointing_device_send()` function. + +Also, you use the `has_mouse_report_changed(new, old)` function to check to see if the report has changed. In the following example, a custom key is used to click the mouse and scroll 127 units vertically and horizontally, then undo all of that when released - because that's a totally useful function. Listen, this is an example: -``` +```c case MS_SPECIAL: - report_mouse_t currentReport = pointing_device_get_report(); - if (record->event.pressed) - { + report_mouse_t currentReport = pointing_device_get_report(); + if (record->event.pressed) { currentReport.v = 127; - currentReport.h = 127; - currentReport.buttons |= MOUSE_BTN1; //this is defined in report.h - } - else - { + currentReport.h = 127; + currentReport.buttons |= MOUSE_BTN1; // this is defined in report.h + } else { currentReport.v = -127; currentReport.h = -127; currentReport.buttons &= ~MOUSE_BTN1; } - pointing_device_set_report(currentReport); + pointing_device_set_report(currentReport); + pointing_device_send(); break; ``` diff --git a/docs/feature_ps2_mouse.md b/docs/feature_ps2_mouse.md index d138967991f..8e84e22d8a7 100644 --- a/docs/feature_ps2_mouse.md +++ b/docs/feature_ps2_mouse.md @@ -1,4 +1,4 @@ -## PS/2 Mouse Support +# PS/2 Mouse Support :id=ps2-mouse-support Its possible to hook up a PS/2 mouse (for example touchpads or trackpoints) to your keyboard as a composite device. @@ -6,7 +6,7 @@ To hook up a Trackpoint, you need to obtain a Trackpoint module (i.e. harvest fr There are three available modes for hooking up PS/2 devices: USART (best), interrupts (better) or busywait (not recommended). -### The Cirtuitry between Trackpoint and Controller +## The Circuitry between Trackpoint and Controller :id=the-circuitry-between-trackpoint-and-controller To get the things working, a 4.7K drag is needed between the two lines DATA and CLK and the line 5+. @@ -24,20 +24,20 @@ MODULE 5+ --------+--+--------- PWR CONTROLLER ``` -### Busywait Version +## Busywait Version :id=busywait-version Note: This is not recommended, you may encounter jerky movement or unsent inputs. Please use interrupt or USART version if possible. In rules.mk: -``` +```makefile PS2_MOUSE_ENABLE = yes PS2_USE_BUSYWAIT = yes ``` In your keyboard config.h: -``` +```c #ifdef PS2_USE_BUSYWAIT # define PS2_CLOCK_PORT PORTD # define PS2_CLOCK_PIN PIND @@ -50,20 +50,20 @@ In your keyboard config.h: #endif ``` -### Interrupt Version +## Interrupt Version :id=interrupt-version The following example uses D2 for clock and D5 for data. You can use any INT or PCINT pin for clock, and any pin for data. In rules.mk: -``` +```makefile PS2_MOUSE_ENABLE = yes PS2_USE_INT = yes ``` In your keyboard config.h: -``` +```c #ifdef PS2_USE_INT #define PS2_CLOCK_PORT PORTD #define PS2_CLOCK_PIN PIND @@ -88,20 +88,20 @@ In your keyboard config.h: #endif ``` -### USART Version +## USART Version :id=usart-version To use USART on the ATMega32u4, you have to use PD5 for clock and PD2 for data. If one of those are unavailable, you need to use interrupt version. In rules.mk: -``` +```makefile PS2_MOUSE_ENABLE = yes PS2_USE_USART = yes ``` In your keyboard config.h: -``` +```c #ifdef PS2_USE_USART #define PS2_CLOCK_PORT PORTD #define PS2_CLOCK_PIN PIND @@ -145,13 +145,13 @@ In your keyboard config.h: #endif ``` -### Additional Settings +## Additional Settings :id=additional-settings -#### PS/2 Mouse Features +### PS/2 Mouse Features :id=ps2-mouse-features These enable settings supported by the PS/2 mouse protocol. -``` +```c /* Use remote mode instead of the default stream mode (see link) */ #define PS2_MOUSE_USE_REMOTE_MODE @@ -170,7 +170,7 @@ These enable settings supported by the PS/2 mouse protocol. You can also call the following functions from ps2_mouse.h -``` +```c void ps2_mouse_disable_data_reporting(void); void ps2_mouse_enable_data_reporting(void); @@ -188,36 +188,36 @@ void ps2_mouse_set_resolution(ps2_mouse_resolution_t resolution); void ps2_mouse_set_sample_rate(ps2_mouse_sample_rate_t sample_rate); ``` -#### Fine Control +### Fine Control :id=fine-control Use the following defines to change the sensitivity and speed of the mouse. Note: you can also use `ps2_mouse_set_resolution` for the same effect (not supported on most touchpads). -``` +```c #define PS2_MOUSE_X_MULTIPLIER 3 #define PS2_MOUSE_Y_MULTIPLIER 3 #define PS2_MOUSE_V_MULTIPLIER 1 ``` -#### Scroll Button +### Scroll Button :id=scroll-button If you're using a trackpoint, you will likely want to be able to use it for scrolling. It's possible to enable a "scroll button/s" that when pressed will cause the mouse to scroll instead of moving. To enable the feature, you must set a scroll button mask as follows: -``` -#define PS2_MOUSE_SCROLL_BTN_MASK (1<.c`: -```C +```c const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { /* Refer to IS31 manual for these locations * driver @@ -52,22 +53,23 @@ 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 +### IS31FL3733/IS31FL3737 :id=is31fl3733is31fl3737 !> For the IS31FL3737, replace all instances of `IS31FL3733` below with `IS31FL3737`. There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`: -```C -RGB_MATRIX_ENABLE = IS31FL3733 +```makefile +RGB_MATRIX_ENABLE = yes +RGB_MATRIX_DRIVER = IS31FL3733 ``` Configure the hardware via your `config.h`: -```C +```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: @@ -90,7 +92,7 @@ Currently only a single drivers is supported, but it would be trivial to support Define these arrays listing all the LEDs in your `.c`: -```C +```c const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { /* Refer to IS31 manual for these locations * driver @@ -103,21 +105,22 @@ 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). --- -### WS2812 +### WS2812 :id=ws2812 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`: -```C -RGB_MATRIX_ENABLE = WS2812 +```makefile +RGB_MATRIX_ENABLE = yes +RGB_MATRIX_DRIVER = WS2812 ``` Configure the hardware via your `config.h`: -```C +```c // The pin connected to the data pin of the LEDs #define RGB_DI_PIN D7 // The number of LEDs connected @@ -126,10 +129,32 @@ 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 -const led_config_t g_led_config = { { +```c +led_config_t g_led_config = { { // Key Matrix to LED Index { 5, NO_LED, NO_LED, 0 }, { NO_LED, NO_LED, NO_LED, NO_LED }, @@ -146,7 +171,7 @@ const led_config_t g_led_config = { { The first part, `// Key Matrix to LED Index`, tells the system what key this LED represents by using the key's electrical matrix row & col. The second part, `// LED Index to Physical Position` represents the LED's physical `{ x, y }` position on the keyboard. The default expected range of values for `{ x, y }` is the inclusive range `{ 0..224, 0..64 }`. This default expected range is due to effects that calculate the center of the keyboard for their animations. The easiest way to calculate these positions is imagine your keyboard is a grid, and the top left of the keyboard represents `{ x, y }` coordinate `{ 0, 0 }` and the bottom right of your keyboard represents `{ 224, 64 }`. Using this as a basis, you can use the following formula to calculate the physical position: -```C +```c x = 224 / (NUMBER_OF_COLS - 1) * COL_POSITION y = 64 / (NUMBER_OF_ROWS - 1) * ROW_POSITION ``` @@ -157,19 +182,20 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{ `// LED Index to Flag` is a bitmask, whether or not a certain LEDs is of a certain type. It is recommended that LEDs are set to only 1 type. -## Flags +## Flags :id=flags -|Define |Description | -|------------------------------------|-------------------------------------------| -|`#define HAS_FLAGS(bits, flags)` |Returns true if `bits` has all `flags` set.| -|`#define HAS_ANY_FLAGS(bits, flags)`|Returns true if `bits` has any `flags` set.| -|`#define LED_FLAG_NONE 0x00` |If this LED has no flags. | -|`#define LED_FLAG_ALL 0xFF` |If this LED has all flags. | -|`#define LED_FLAG_MODIFIER 0x01` |If the Key for this LED is a modifier. | -|`#define LED_FLAG_UNDERGLOW 0x02` |If the LED is for underglow. | -|`#define LED_FLAG_KEYLIGHT 0x04` |If the LED is for key backlight. | +|Define |Value |Description | +|----------------------------|------|-------------------------------------------------| +|`HAS_FLAGS(bits, flags)` |*n/a* |Evaluates to `true` if `bits` has all `flags` set| +|`HAS_ANY_FLAGS(bits, flags)`|*n/a* |Evaluates to `true` if `bits` has any `flags` set| +|`LED_FLAG_NONE` |`0x00`|If this LED has no flags | +|`LED_FLAG_ALL` |`0xFF`|If this LED has all flags | +|`LED_FLAG_MODIFIER` |`0x01`|If the LED is on a modifier key | +|`LED_FLAG_UNDERGLOW` |`0x02`|If the LED is for underglow | +|`LED_FLAG_KEYLIGHT` |`0x04`|If the LED is for key backlight | +|`LED_FLAG_INDICATOR` |`0x08`|If the LED is for keyboard state indication | -## Keycodes +## Keycodes :id=keycodes All RGB keycodes are currently shared with the RGBLIGHT system: @@ -186,19 +212,28 @@ All RGB keycodes are currently shared with the RGBLIGHT system: |`RGB_VAD` | |Decrease value (brightness), increase value when Shift is held | |`RGB_SPI` | |Increase effect speed (does not support eeprom yet), decrease speed when Shift is held| |`RGB_SPD` | |Decrease effect speed (does not support eeprom yet), increase speed when Shift is held| +|`RGB_MODE_PLAIN` |`RGB_M_P `|Static (no animation) mode | +|`RGB_MODE_BREATHE` |`RGB_M_B` |Breathing animation mode | +|`RGB_MODE_RAINBOW` |`RGB_M_R` |Full gradient scrolling left to right (uses the `RGB_MATRIX_CYCLE_LEFT_RIGHT` mode) | +|`RGB_MODE_SWIRL` |`RGB_M_SW`|Full gradient spinning pinwheel around center of keyboard (uses `RGB_MATRIX_CYCLE_PINWHEEL` mode) | -* `RGB_MODE_*` keycodes will generally work, but are not currently mapped to the correct effects for the RGB Matrix system +* `RGB_MODE_*` keycodes will generally work, but not all of the modes are currently mapped to the correct effects for the RGB Matrix system. -## RGB Matrix Effects +`RGB_MODE_PLAIN`, `RGB_MODE_BREATHE`, `RGB_MODE_RAINBOW`, and `RGB_MATRIX_SWIRL` are the only ones that are mapped properly. The rest don't have a direct equivalent, and are not mapped. + +!> By default, if you have both the [RGB Light](feature_rgblight.md) and the RGB Matrix feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature. + +## RGB Matrix Effects :id=rgb-matrix-effects All effects have been configured to support current configuration values (Hue, Saturation, Value, & Speed) unless otherwise noted below. These are the effects that are currently available: -```C +```c enum rgb_matrix_effects { RGB_MATRIX_NONE = 0, RGB_MATRIX_SOLID_COLOR = 1, // Static single hue, no speed support RGB_MATRIX_ALPHAS_MODS, // Static dual hue, speed is hue for secondary hue RGB_MATRIX_GRADIENT_UP_DOWN, // Static gradient top to bottom, speed controls how much gradient changes + RGB_MATRIX_GRADIENT_LEFT_RIGHT, // Static gradient left to right, speed controls how much gradient changes RGB_MATRIX_BREATHING, // Single hue brightness cycling animation RGB_MATRIX_BAND_SAT, // Single hue band fading saturation scrolling left to right RGB_MATRIX_BAND_VAL, // Single hue band fading brightness scrolling left to right @@ -246,8 +281,10 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con |Define |Description | |-------------------------------------------------------|-----------------------------------------------| +|`#define DISABLE_RGB_MATRIX_SOLID_COLOR` |Disables `RGB_MATRIX_SOLID_COLOR` | |`#define DISABLE_RGB_MATRIX_ALPHAS_MODS` |Disables `RGB_MATRIX_ALPHAS_MODS` | |`#define DISABLE_RGB_MATRIX_GRADIENT_UP_DOWN` |Disables `RGB_MATRIX_GRADIENT_UP_DOWN` | +|`#define DISABLE_RGB_MATRIX_GRADIENT_LEFT_RIGHT` |Disables `MATRIX_GRADIENT_LEFT_RIGHT` | |`#define DISABLE_RGB_MATRIX_BREATHING` |Disables `RGB_MATRIX_BREATHING` | |`#define DISABLE_RGB_MATRIX_BAND_SAT` |Disables `RGB_MATRIX_BAND_SAT` | |`#define DISABLE_RGB_MATRIX_BAND_VAL` |Disables `RGB_MATRIX_BAND_VAL` | @@ -258,20 +295,20 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con |`#define DISABLE_RGB_MATRIX_CYCLE_ALL` |Disables `RGB_MATRIX_CYCLE_ALL` | |`#define DISABLE_RGB_MATRIX_CYCLE_LEFT_RIGHT` |Disables `RGB_MATRIX_CYCLE_LEFT_RIGHT` | |`#define DISABLE_RGB_MATRIX_CYCLE_UP_DOWN` |Disables `RGB_MATRIX_CYCLE_UP_DOWN` | +|`#define DISABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON` |Disables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON` | |`#define DISABLE_RGB_MATRIX_CYCLE_OUT_IN` |Disables `RGB_MATRIX_CYCLE_OUT_IN` | |`#define DISABLE_RGB_MATRIX_CYCLE_OUT_IN_DUAL` |Disables `RGB_MATRIX_CYCLE_OUT_IN_DUAL` | -|`#define DISABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON` |Disables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON` | -|`#define DISABLE_RGB_MATRIX_DUAL_BEACON` |Disables `RGB_MATRIX_DUAL_BEACON` | |`#define DISABLE_RGB_MATRIX_CYCLE_PINWHEEL` |Disables `RGB_MATRIX_CYCLE_PINWHEEL` | |`#define DISABLE_RGB_MATRIX_CYCLE_SPIRAL` |Disables `RGB_MATRIX_CYCLE_SPIRAL` | +|`#define DISABLE_RGB_MATRIX_DUAL_BEACON` |Disables `RGB_MATRIX_DUAL_BEACON` | |`#define DISABLE_RGB_MATRIX_RAINBOW_BEACON` |Disables `RGB_MATRIX_RAINBOW_BEACON` | |`#define DISABLE_RGB_MATRIX_RAINBOW_PINWHEELS` |Disables `RGB_MATRIX_RAINBOW_PINWHEELS` | |`#define DISABLE_RGB_MATRIX_RAINDROPS` |Disables `RGB_MATRIX_RAINDROPS` | |`#define DISABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS` |Disables `RGB_MATRIX_JELLYBEAN_RAINDROPS` | |`#define DISABLE_RGB_MATRIX_TYPING_HEATMAP` |Disables `RGB_MATRIX_TYPING_HEATMAP` | |`#define DISABLE_RGB_MATRIX_DIGITAL_RAIN` |Disables `RGB_MATRIX_DIGITAL_RAIN` | -|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE` |Disables `RGB_MATRIX_SOLID_REACTIVE` | |`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_SIMPLE` |Disables `RGB_MATRIX_SOLID_REACTIVE_SIMPLE` | +|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE` |Disables `RGB_MATRIX_SOLID_REACTIVE` | |`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_WIDE` |Disables `RGB_MATRIX_SOLID_REACTIVE_WIDE` | |`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` | |`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_CROSS` |Disables `RGB_MATRIX_SOLID_REACTIVE_CROSS` | @@ -283,8 +320,21 @@ 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 -## Custom RGB Matrix Effects +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 By setting `RGB_MATRIX_CUSTOM_USER` (and/or `RGB_MATRIX_CUSTOM_KB`) in `rules.mk`, new effects can be defined directly from userspace, without having to edit any QMK core files. @@ -293,7 +343,13 @@ 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. -```C +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 !!! // // Step 1. @@ -340,7 +396,7 @@ static bool my_cool_effect2(effect_params_t* params) { For inspiration and examples, check out the built-in effects under `quantum/rgb_matrix_animation/` -## Colors +## Colors :id=colors These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions. @@ -368,12 +424,13 @@ These are shorthands to popular colors. The `RGB` ones can be passed to the `set These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight_list.h). Feel free to add to this list! -## Additional `config.h` Options +## Additional `config.h` Options :id=additional-configh-options -```C +```c #define RGB_MATRIX_KEYPRESSES // reacts to keypresses #define RGB_MATRIX_KEYRELEASES // reacts to keyreleases (instead of keypresses) -#define RGB_DISABLE_AFTER_TIMEOUT 0 // number of ticks to wait until disabling effects +#define RGB_DISABLE_TIMEOUT 0 // number of milliseconds to wait until rgb automatically turns off +#define RGB_DISABLE_AFTER_TIMEOUT 0 // OBSOLETE: number of ticks to wait until disabling effects #define RGB_DISABLE_WHEN_USB_SUSPENDED false // turn off effects when suspended #define RGB_MATRIX_LED_PROCESS_LIMIT (DRIVER_LED_TOTAL + 4) / 5 // limits the number of LEDs to process in an animation per task run (increases keyboard responsiveness) #define RGB_MATRIX_LED_FLUSH_LIMIT 16 // limits in milliseconds how frequently an animation will update the LEDs. 16 (16ms) is equivalent to limiting to 60fps (increases keyboard responsiveness) @@ -383,30 +440,125 @@ These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blo #define RGB_MATRIX_STARTUP_SAT 255 // Sets the default saturation value, if none has been set #define RGB_MATRIX_STARTUP_VAL RGB_MATRIX_MAXIMUM_BRIGHTNESS // Sets the default brightness value, if none has been set #define RGB_MATRIX_STARTUP_SPD 127 // Sets the default animation speed, if none has been set +#define RGB_MATRIX_DISABLE_KEYCODES // disables control of rgb matrix by keycodes (must use code functions to control the feature) ``` -## EEPROM storage +## EEPROM storage :id=eeprom-storage The EEPROM for it is currently shared with the RGBLIGHT system (it's generally assumed only one RGB would be used at a time), but could be configured to use its own 32bit address with: -```C +```c #define EECONFIG_RGB_MATRIX (uint32_t *)28 ``` Where `28` is an unused index from `eeconfig.h`. -## Suspended state +## Functions :id=functions -To use the suspend feature, add this to your `.c`: +### Direct Operation :id=direct-operation +|Function |Description | +|--------------------------------------------|-------------| +|`rgb_matrix_set_color_all(r, g, b)` |Set all of the LEDs to the given RGB value, where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) | +|`rgb_matrix_set_color(index, r, g, b)` |Set a single LED to the given RGB value, where `r`/`g`/`b` are between 0 and 255, and `index` is between 0 and `DRIVER_LED_TOTAL` (not written to EEPROM) | -```C -void suspend_power_down_kb(void) -{ +### Disable/Enable Effects :id=disable-enable-effects +|Function |Description | +|--------------------------------------------|-------------| +|`rgb_matrix_toggle()` |Toggle effect range LEDs between on and off | +|`rgb_matrix_toggle_noeeprom()` |Toggle effect range LEDs between on and off (not written to EEPROM) | +|`rgb_matrix_enable()` |Turn effect range LEDs on, based on their previous state | +|`rgb_matrix_enable_noeeprom()` |Turn effect range LEDs on, based on their previous state (not written to EEPROM) | +|`rgb_matrix_disable()` |Turn effect range LEDs off, based on their previous state | +|`rgb_matrix_disable_noeeprom()` |Turn effect range LEDs off, based on their previous state (not written to EEPROM) | + +### Change Effect Mode :id=change-effect-mode +|Function |Description | +|--------------------------------------------|-------------| +|`rgb_matrix_mode(mode)` |Set the mode, if RGB animations are enabled | +|`rgb_matrix_mode_noeeprom(mode)` |Set the mode, if RGB animations are enabled (not written to EEPROM) | +|`rgb_matrix_step()` |Change the mode to the next RGB animation in the list of enabled RGB animations | +|`rgb_matrix_step_noeeprom()` |Change the mode to the next RGB animation in the list of enabled RGB animations (not written to EEPROM) | +|`rgb_matrix_step_reverse()` |Change the mode to the previous RGB animation in the list of enabled RGB animations | +|`rgb_matrix_step_reverse_noeeprom()` |Change the mode to the previous RGB animation in the list of enabled RGB animations (not written to EEPROM) | +|`rgb_matrix_increase_speed()` |Increase the speed of the animations | +|`rgb_matrix_increase_speed_noeeprom()` |Increase the speed of the animations (not written to EEPROM) | +|`rgb_matrix_decrease_speed()` |Decrease the speed of the animations | +|`rgb_matrix_decrease_speed_noeeprom()` |Decrease the speed of the animations (not written to EEPROM) | +|`rgb_matrix_set_speed(speed)` |Set the speed of the animations to the given value where `speed` is between 0 and 255 | +|`rgb_matrix_set_speed_noeeprom(speed)` |Set the speed of the animations to the given value where `speed` is between 0 and 255 (not written to EEPROM) | + +### Change Color :id=change-color +|Function |Description | +|--------------------------------------------|-------------| +|`rgb_matrix_increase_hue()` |Increase the hue for effect range LEDs. This wraps around at maximum hue | +|`rgb_matrix_increase_hue_noeeprom()` |Increase the hue for effect range LEDs. This wraps around at maximum hue (not written to EEPROM) | +|`rgb_matrix_decrease_hue()` |Decrease the hue for effect range LEDs. This wraps around at minimum hue | +|`rgb_matrix_decrease_hue_noeeprom()` |Decrease the hue for effect range LEDs. This wraps around at minimum hue (not written to EEPROM) | +|`rgb_matrix_increase_sat()` |Increase the saturation for effect range LEDs. This wraps around at maximum saturation | +|`rgb_matrix_increase_sat_noeeprom()` |Increase the saturation for effect range LEDs. This wraps around at maximum saturation (not written to EEPROM) | +|`rgb_matrix_decrease_sat()` |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation | +|`rgb_matrix_decrease_sat_noeeprom()` |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation (not written to EEPROM) | +|`rgb_matrix_increase_val()` |Increase the value for effect range LEDs. This wraps around at maximum value | +|`rgb_matrix_increase_val_noeeprom()` |Increase the value for effect range LEDs. This wraps around at maximum value (not written to EEPROM) | +|`rgb_matrix_decrease_val()` |Decrease the value for effect range LEDs. This wraps around at minimum value | +|`rgb_matrix_decrease_val_noeeprom()` |Decrease the value for effect range LEDs. This wraps around at minimum value (not written to EEPROM) | +|`rgb_matrix_sethsv(h, s, v)` |Set LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 | +|`rgb_matrix_sethsv_noeeprom(h, s, v)` |Set LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) | + +### Query Current Status :id=query-current-status +|Function |Description | +|---------------------------------|---------------------------| +|`rgb_matrix_is_enabled()` |Gets current on/off status | +|`rgb_matrix_get_mode()` |Gets current mode | +|`rgb_matrix_get_hue()` |Gets current hue | +|`rgb_matrix_get_sat()` |Gets current sat | +|`rgb_matrix_get_val()` |Gets current val | +|`rgb_matrix_get_hsv()` |Gets hue, sat, and val and returns a [`HSV` structure](https://github.com/qmk/qmk_firmware/blob/7ba6456c0b2e041bb9f97dbed265c5b8b4b12192/quantum/color.h#L56-L61)| +|`rgb_matrix_get_speed()` |Gets current speed | +|`rgb_matrix_get_suspend_state()` |Gets current suspend state | + +## Callbacks :id=callbacks + +### Indicators :id=indicators + +If you want to set custom indicators, such as an LED for Caps Lock, or layer indication, you can use the `rgb_matrix_indicators_kb` or `rgb_matrix_indicators_user` function for that: +```c +void rgb_matrix_indicators_kb(void) { + rgb_matrix_set_color(index, red, green, blue); +} +``` + +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. + +Additionally add this to your `.c`: + +```c +void suspend_power_down_kb(void) { + rgb_matrix_set_suspend_state(true); + suspend_power_down_user(); +} + +void suspend_wakeup_init_kb(void) { + rgb_matrix_set_suspend_state(false); + suspend_wakeup_init_user(); +} +``` +or add this to your `keymap.c`: +```c +void suspend_power_down_user(void) { rgb_matrix_set_suspend_state(true); } -void suspend_wakeup_init_kb(void) -{ +void suspend_wakeup_init_user(void) { rgb_matrix_set_suspend_state(false); } ``` diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index 69a6aaaed6b..d2612a6d1bb 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -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.
Changing the **Saturation** moves between the inner and outer sections of the wheel, affecting the intensity of the color.
Changing the **Value** sets the overall brightness.
+![QMK Color Wheel with HSV Values](https://i.imgur.com/vkYVo66.jpg) + ## Keycodes |Key |Aliases |Description | @@ -64,18 +75,27 @@ Changing the **Value** sets the overall brightness.
|`RGB_MODE_GRADIENT`|`RGB_M_G` |Static gradient animation mode | |`RGB_MODE_RGBTEST` |`RGB_M_T` |Red, Green, Blue test animation mode | +!> By default, if you have both the RGB Light and the [RGB Matrix](feature_rgb_matrix.md) feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature. + + ## Configuration Your RGB lighting can be configured by placing these `#define`s in your `config.h`: -|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| +|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 @@ -94,6 +114,7 @@ if `RGBLIGHT_EFFECT_xxxx` or `RGBLIGHT_ANIMATIONS` is defined, you also have a n |`RGBLIGHT_MODE_STATIC_GRADIENT`| 0,1,..,9 |Static gradient | |`RGBLIGHT_MODE_RGB_TEST` | *None* |RGB Test | |`RGBLIGHT_MODE_ALTERNATING` | *None* |Alternating | +|`RGBLIGHT_MODE_TWINKLE` | 0,1,2,3,4,5 |Twinkle | Check out [this video](https://youtube.com/watch?v=VKrpPAHlisY) for a demonstration. @@ -103,8 +124,8 @@ Note: For versions older than 0.6.117, The mode numbers were written directly. I Use these defines to add or remove animations from the firmware. When you are running low on flash space, it can be helpful to disable animations you are not using. -|Define |Default |Description | -|------------------------------------|-------------|-------------------------------------------------------------------------------------| +|Define |Default |Description | +|------------------------------------|-------------|-------------------------------------------------------------------------| |`RGBLIGHT_ANIMATIONS` |*Not defined*|Enable all additional animation modes. | |`RGBLIGHT_EFFECT_ALTERNATING` |*Not defined*|Enable alternating animation mode. | |`RGBLIGHT_EFFECT_BREATHING` |*Not defined*|Enable breathing animation mode. | @@ -115,22 +136,25 @@ Use these defines to add or remove animations from the firmware. When you are ru |`RGBLIGHT_EFFECT_RGB_TEST` |*Not defined*|Enable RGB test animation mode. | |`RGBLIGHT_EFFECT_SNAKE` |*Not defined*|Enable snake animation mode. | |`RGBLIGHT_EFFECT_STATIC_GRADIENT` |*Not defined*|Enable static gradient mode. | +|`RGBLIGHT_EFFECT_TWINKLE` |*Not defined*|Enable twinkle animation mode. | ### Effect and Animation Settings The following options are used to tweak the various animations: -|Define |Default |Description | -|------------------------------------|-------------|-------------------------------------------------------------------------------------| +|Define |Default |Description | +|------------------------------------|-------------|-----------------------------------------------------------------------------------------------| |`RGBLIGHT_EFFECT_BREATHE_CENTER` |*Not defined*|If defined, used to calculate the curve for the breathing animation. Valid values are 1.0 to 2.7 | -|`RGBLIGHT_EFFECT_BREATHE_MAX` |`255` |The maximum brightness for the breathing mode. Valid values are 1 to 255 | -|`RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL`|`1000` |How long to wait between light changes for the "Christmas" animation, in milliseconds| -|`RGBLIGHT_EFFECT_CHRISTMAS_STEP` |`2` |The number of LEDs to group the red/green colors by for the "Christmas" animation | -|`RGBLIGHT_EFFECT_KNIGHT_LED_NUM` |`RGBLED_NUM` |The number of LEDs to have the "Knight" animation travel | -|`RGBLIGHT_EFFECT_KNIGHT_LENGTH` |`3` |The number of LEDs to light up for the "Knight" animation | -|`RGBLIGHT_EFFECT_KNIGHT_OFFSET` |`0` |The number of LEDs to start the "Knight" animation from the start of the strip by | -|`RGBLIGHT_RAINBOW_SWIRL_RANGE` |`255` |Range adjustment for the rainbow swirl effect to get different swirls | -|`RGBLIGHT_EFFECT_SNAKE_LENGTH` |`4` |The number of LEDs to light up for the "Snake" animation | +|`RGBLIGHT_EFFECT_BREATHE_MAX` |`255` |The maximum brightness for the breathing mode. Valid values are 1 to 255 | +|`RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL`|`40` |How long (in milliseconds) to wait between animation steps for the "Christmas" animation | +|`RGBLIGHT_EFFECT_CHRISTMAS_STEP` |`2` |The number of LEDs to group the red/green colors by for the "Christmas" animation | +|`RGBLIGHT_EFFECT_KNIGHT_LED_NUM` |`RGBLED_NUM` |The number of LEDs to have the "Knight" animation travel | +|`RGBLIGHT_EFFECT_KNIGHT_LENGTH` |`3` |The number of LEDs to light up for the "Knight" animation | +|`RGBLIGHT_EFFECT_KNIGHT_OFFSET` |`0` |The number of LEDs to start the "Knight" animation from the start of the strip by | +|`RGBLIGHT_RAINBOW_SWIRL_RANGE` |`255` |Range adjustment for the rainbow swirl effect to get different swirls | +|`RGBLIGHT_EFFECT_SNAKE_LENGTH` |`4` |The number of LEDs to light up for the "Snake" animation | +|`RGBLIGHT_EFFECT_TWINKLE_LIFE` |`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 1. Remove `RGBLIGHT_ANIMATIONS` from `config.h`. @@ -168,10 +192,127 @@ const uint8_t RGBLED_SNAKE_INTERVALS[] PROGMEM = {100, 50, 20}; // How long (in milliseconds) to wait between animation steps for each of the "Knight" animations const uint8_t RGBLED_KNIGHT_INTERVALS[] PROGMEM = {127, 63, 31}; +// How long (in milliseconds) to wait between animation steps for each of the "Twinkle" animations +const uint8_t RGBLED_TWINKLE_INTERVALS[] PROGMEM = {50, 25, 10}; + // These control which hues are selected for each of the "Static gradient" modes const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64}; ``` +## Lighting Layers + +?> **Note:** Lighting Layers is an RGB Light feature, it will not work for RGB Matrix. See [RGB Matrix Indicators](feature_rgb_matrix.md?indicators) for details on how to do so. + +By including `#define RGBLIGHT_LAYERS` in your `config.h` file you can enable lighting layers. These make +it easy to use your underglow LEDs as status indicators to show which keyboard layer is currently active, or the state of caps lock, all without disrupting any animations. [Here's a video](https://youtu.be/uLGE1epbmdY) showing an example of what you can do. + +### Defining Lighting Layers :id=defining-lighting-layers + +By default, 8 layers are possible. This can be expanded to as many as 32 by overriding the definition of `RGBLIGHT_MAX_LAYERS` in `config.h` (e.g. `#define RGBLIGHT_MAX_LAYERS 32`). Please note, if you use a split keyboard, you will need to flash both sides of the split after changing this. Also, increasing the maximum will increase the firmware size, and will slow sync on split keyboards. + +To define a layer, we modify `keymap.c` to list the LED ranges and the colors we want to overlay on them using an array of `rgblight_segment_t` using the `RGBLIGHT_LAYER_SEGMENTS` macro. We can define multiple layers and enable/disable them independently: + +```c +// Light LEDs 6 to 9 and 12 to 15 red when caps lock is active. Hard to ignore! +const rgblight_segment_t PROGMEM my_capslock_layer[] = RGBLIGHT_LAYER_SEGMENTS( + {6, 4, HSV_RED}, // Light 4 LEDs, starting with LED 6 + {12, 4, HSV_RED} // Light 4 LEDs, starting with LED 12 +); +// Light LEDs 9 & 10 in cyan when keyboard layer 1 is active +const rgblight_segment_t PROGMEM my_layer1_layer[] = RGBLIGHT_LAYER_SEGMENTS( + {9, 2, HSV_CYAN} +); +// Light LEDs 11 & 12 in purple when keyboard layer 2 is active +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.. +``` + +We combine these layers into an array using the `RGBLIGHT_LAYERS_LIST` macro, and assign it to the `rgblight_layers` variable during keyboard setup. Note that you can only define up to 8 lighting layers. Any extra layers will be ignored. Since the different lighting layers overlap, the order matters in the array, with later layers taking precedence: + +```c +// Now define the array of layers. Later layers take precedence +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_layer3_layer // Overrides other layers +); + +void keyboard_post_init_user(void) { + // Enable the LED layers + rgblight_layers = my_rgb_layers; +} +``` +Note: For split keyboards with two controllers, both sides need to be flashed when updating the contents of rgblight_layers. + +### Enabling and disabling lighting layers :id=enabling-lighting-layers + +Everything above just configured the definition of each lighting layer. +We can now enable and disable the lighting layers whenever the state of the keyboard changes: + +```c +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 + +By including `#define RGBLIGHT_LAYER_BLINK` in your `config.h` file you can turn a lighting +layer on for a specified duration. Once the specified number of milliseconds has elapsed +the layer will be turned off. This is useful, e.g., if you want to acknowledge some +action (e.g. toggling some setting): + +```c +const rgblight_segment_t PROGMEM _yes_layer[] = RGBLIGHT_LAYER_SEGMENTS( {9, 6, HSV_GREEN} ); +const rgblight_segment_t PROGMEM _no_layer[] = RGBLIGHT_LAYER_SEGMENTS( {9, 6, HSV_RED} ); + +const rgblight_segment_t* const PROGMEM _rgb_layers[] = + RGBLIGHT_LAYERS_LIST( _yes_layer, _no_layer ); + +void keyboard_post_init_user(void) { + rgblight_layers = _rgb_layers; +} + +// Note we user post_process_record_user because we want the state +// after the flag has been flipped... +void post_process_record_user(uint16_t keycode, keyrecord_t *record) { + switch (keycode) { + case DEBUG: + rgblight_blink_layer(debug_enable ? 0 : 1, 500); + break; + + case NK_TOGG: + case NK_ON: + case NK_OFF: + rgblight_blink_layer(keymap_config.nkro ? 0 : 1, 500); + break; + } +} +``` + +### Overriding RGB Lighting on/off status + +Normally lighting layers are not shown when RGB Lighting is disabled (e.g. with `RGB_TOG` keycode). If you would like lighting layers to work even when the RGB Lighting is otherwise off, add `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF` to your `config.h`. + ## Functions If you need to change your RGB lighting in code, for example in a macro to change the color whenever you switch layers, QMK provides a set of functions to assist you. See [`rgblight.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight.h) for the full list, but the most commonly used functions include: @@ -234,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 | @@ -252,24 +394,43 @@ rgblight_sethsv(HSV_GREEN, 2); // led 2 |`rgblight_increase_hue_noeeprom()` |Increase the hue for effect range LEDs. This wraps around at maximum hue (not written to EEPROM) | |`rgblight_decrease_hue()` |Decrease the hue for effect range LEDs. This wraps around at minimum hue | |`rgblight_decrease_hue_noeeprom()` |Decrease the hue for effect range LEDs. This wraps around at minimum hue (not written to EEPROM) | -|`rgblight_increase_sat()` |Increase the saturation for effect range LEDs. This wraps around at maximum saturation | -|`rgblight_increase_sat_noeeprom()` |Increase the saturation for effect range LEDs. This wraps around at maximum saturation (not written to EEPROM) | -|`rgblight_decrease_sat()` |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation | -|`rgblight_decrease_sat_noeeprom()` |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation (not written to EEPROM) | -|`rgblight_increase_val()` |Increase the value for effect range LEDs. This wraps around at maximum value | -|`rgblight_increase_val_noeeprom()` |Increase the value for effect range LEDs. This wraps around at maximum value (not written to EEPROM) | -|`rgblight_decrease_val()` |Decrease the value for effect range LEDs. This wraps around at minimum value | -|`rgblight_decrease_val_noeeprom()` |Decrease the value for effect range LEDs. This wraps around at minimum value (not written to EEPROM) | +|`rgblight_increase_sat()` |Increase the saturation for effect range LEDs. This stops at maximum saturation | +|`rgblight_increase_sat_noeeprom()` |Increase the saturation for effect range LEDs. This stops at maximum saturation (not written to EEPROM) | +|`rgblight_decrease_sat()` |Decrease the saturation for effect range LEDs. This stops at minimum saturation | +|`rgblight_decrease_sat_noeeprom()` |Decrease the saturation for effect range LEDs. This stops at minimum saturation (not written to EEPROM) | +|`rgblight_increase_val()` |Increase the value for effect range LEDs. This stops at maximum value | +|`rgblight_increase_val_noeeprom()` |Increase the value for effect range LEDs. This stops at maximum value (not written to EEPROM) | +|`rgblight_decrease_val()` |Decrease the value for effect range LEDs. This stops at minimum value | +|`rgblight_decrease_val_noeeprom()` |Decrease the value for effect range LEDs. This stops at minimum value (not written to EEPROM) | |`rgblight_sethsv(h, s, v)` |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 | |`rgblight_sethsv_noeeprom(h, s, v)` |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) | +#### Speed functions +|Function |Description | +|--------------------------------------------|-------------| +|`rgblight_increase_speed()` |Increases the animation speed | +|`rgblight_increase_speed_noeeprom()` |Increases the animation speed (not written to EEPROM) | +|`rgblight_decrease_speed()` |Decreases the animation speed | +|`rgblight_decrease_speed_noeeprom()` |Decreases the animation speed (not written to EEPROM) | +|`rgblight_set_speed()` |Sets the speed. Value is between 0 and 255 | +|`rgblight_set_speed_noeeprom()` |Sets the speed. Value is between 0 and 255 (not written to EEPROM) | + + +#### layer functions +|Function |Description | +|--------------------------------------------|-------------| +|`rgblight_get_layer_state(i)` |Returns `true` if lighting layer `i` is enabled | +|`rgblight_set_layer_state(i, is_on)` |Enable or disable lighting layer `i` based on value of `bool is_on` | + #### query -|Function |Description | -|-----------------------|-----------------| -|`rgblight_get_mode()` |Get current mode | -|`rgblight_get_hue()` |Get current hue | -|`rgblight_get_sat()` |Get current sat | -|`rgblight_get_val()` |Get current val | +|Function |Description | +|-----------------------|---------------------------| +|`rgblight_is_enabled()`|Gets current on/off status | +|`rgblight_get_mode()` |Gets current mode | +|`rgblight_get_hue()` |Gets current hue | +|`rgblight_get_sat()` |Gets current sat | +|`rgblight_get_val()` |Gets current val | +|`rgblight_get_speed()` |Gets current speed | ## Colors diff --git a/docs/feature_sequencer.md b/docs/feature_sequencer.md new file mode 100644 index 00000000000..76b4db5cf6c --- /dev/null +++ b/docs/feature_sequencer.md @@ -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 | diff --git a/docs/feature_space_cadet.md b/docs/feature_space_cadet.md index 41a44627e3c..e2909642419 100644 --- a/docs/feature_space_cadet.md +++ b/docs/feature_space_cadet.md @@ -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 diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md index affce342934..3613775d720 100644 --- a/docs/feature_split_keyboard.md +++ b/docs/feature_split_keyboard.md @@ -8,9 +8,20 @@ QMK Firmware has a generic implementation that is usable by any board, as well a For this, we will mostly be talking about the generic implementation used by the Let's Split and other keyboards. -!> ARM is not yet supported for Split Keyboards. Progress is being made, but we are not quite there, yet. +!> ARM is not yet fully supported for Split Keyboards and has many limitations. Progress is being made, but we have not yet reached 100% feature parity. +## Compatibility Overview + +| Transport | AVR | ARM | +|------------------------------|--------------------|--------------------| +| ['serial'](serial_driver.md) | :heavy_check_mark: | :white_check_mark: 1 | +| I2C | :heavy_check_mark: | | + +Notes: + +1. Both hardware and software limitations are detailed within the [driver documentation](serial_driver.md). + ## Hardware Configuration This assumes that you're using two Pro Micro-compatible controllers, and are using TRRS jacks to connect to two halves. @@ -37,11 +48,12 @@ However, USB cables, SATA cables, and even just 4 wires have been known to be us ### Serial Wiring -The 3 wires of the TRS/TRRS cable need to connect GND, VCC, and D0 (aka PDO or pin 3) between the two Pro Micros. +The 3 wires of the TRS/TRRS cable need to connect GND, VCC, and D0/D1/D2/D3 (aka PD0/PD1/PD2/PD3) between the two Pro Micros. ?> Note that the pin used here is actually set by `SOFT_SERIAL_PIN` below. -![serial wiring](https://i.imgur.com/C3D1GAQ.png) +sk-pd0-connection-mono +sk-pd2-connection-mono ### I2C Wiring @@ -49,7 +61,7 @@ The 4 wires of the TRRS cable need to connect GND, VCC, and SCL and SDA (aka PD0 The pull-up resistors may be placed on either half. If you wish to use the halves independently, it is also possible to use 4 resistors and have the pull-ups in both halves. -![I2C wiring](https://i.imgur.com/Hbzhc6E.png) +sk-i2c-connection-mono ## Firmware Configuration @@ -79,6 +91,28 @@ You can configure the firmware to read a pin on the controller to determine hand This will read the specified pin. If it's high, then the controller assumes it is the left hand, and if it's low, it's assumed to be the right side. +#### Handedness by Matrix Pin + +You can configure the firmware to read key matrix pins on the controller to determine handedness. To do this, add the following to your `config.h` file: + +```c +#define SPLIT_HAND_MATRIX_GRID D0, F1 +``` + +The first pin is the output pin and the second is the input pin. + +Some keyboards have unused intersections in the key matrix. This setting uses one of these unused intersections to determine the handness. + +Normally, when a diode is connected to an intersection, it is judged to be left. If you add the following definition, it will be judged to be right. + +```c +#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. @@ -151,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. @@ -193,15 +243,49 @@ This sets how many LEDs are directly connected to each controller. The first nu ```c #define SPLIT_USB_DETECT ``` -This option changes the startup behavior to detect an active USB connection when delegating master/slave. If this operation times out, then the half is assume to be a slave. This is the default behavior for ARM, and required for AVR Teensy boards (due to hardware limitations). + +Enabling this option changes the startup behavior to listen for an active USB communication to delegate which part is master and which is slave. With this option enabled and theres's USB communication, then that half assumes it is the master, otherwise it assumes it is the slave. + +Without this option, the master is the half that can detect voltage on the physical USB connection (VBUS detection). + +Enabled by default on ChibiOS/ARM. ?> This setting will stop the ability to demo using battery packs. ```c -#define SPLIT_USB_TIMEOUT 2500 +#define SPLIT_USB_TIMEOUT 2000 ``` This sets the maximum timeout when detecting master/slave when using `SPLIT_USB_DETECT`. +```c +#define SPLIT_USB_TIMEOUT_POLL 10 +``` +This sets the poll frequency when detecting master/slave when using `SPLIT_USB_DETECT` + +## Hardware Considerations and Mods + +Master/slave delegation is made either by detecting voltage on VBUS connection or waiting for USB communication (`SPLIT_USB_DETECT`). Pro Micro boards can use VBUS detection out of the box and be used with or without `SPLIT_USB_DETECT`. + +Many ARM boards, but not all, do not support VBUS detection. Because it is common that ARM boards lack VBUS detection, `SPLIT_USB_DETECT` is automatically defined on ARM targets (technically when ChibiOS is targetted). + +### Teensy boards + +Teensy boards lack VBUS detection out of the box and must have `SPLIT_USB_DETECT` defined. 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_DETECT` 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. diff --git a/docs/feature_stenography.md b/docs/feature_stenography.md index 0b2c82422b6..bf4bd39db97 100644 --- a/docs/feature_stenography.md +++ b/docs/feature_stenography.md @@ -1,16 +1,16 @@ -# Stenography in QMK +# Stenography in QMK :id=stenography-in-qmk [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 +## Plover with QWERTY Keyboard :id=plover-with-qwerty-keyboard Plover can work with any standard QWERTY keyboard, although it is more efficient if the keyboard supports NKRO (n-key rollover) to allow Plover to see all the pressed keys at once. An example keymap for Plover can be found in `planck/keymaps/default`. Switching to the `PLOVER` layer adjusts the position of the keyboard to support the number bar. To use Plover with QMK just enable NKRO and optionally adjust your layout if you have anything other than a standard layout. You may also want to purchase some steno-friendly keycaps to make it easier to hit multiple keys. -## Plover with Steno Protocol +## Plover with Steno Protocol :id=plover-with-steno-protocol Plover also understands the language of several steno machines. QMK can speak a couple of these languages, TX Bolt and GeminiPR. An example layout can be found in `planck/keymaps/steno`. @@ -20,26 +20,26 @@ In this mode Plover expects to speak with a steno machine over a serial port so > Note: Due to hardware limitations you may not be able to run both a virtual serial port and mouse emulation at the same time. -### TX Bolt +### TX Bolt :id=tx-bolt TX Bolt communicates the status of 24 keys over a very simple protocol in variable-sized (1-5 byte) packets. -### GeminiPR +### GeminiPR :id=geminipr GeminiPR encodes 42 keys into a 6-byte packet. While TX Bolt contains everything that is necessary for standard stenography, GeminiPR opens up many more options, including supporting non-English theories. -## Configuring QMK for Steno +## Configuring QMK for Steno :id=configuring-qmk-for-steno Firstly, enable steno in your keymap's Makefile. You may also need disable mousekeys, extra keys, or another USB endpoint to prevent conflicts. The builtin USB stack for some processors only supports a certain number of USB endpoints and the virtual serial port needed for steno fills 3 of them. -```Makefile +```makefile STENO_ENABLE = yes MOUSEKEY_ENABLE = no ``` In your keymap create a new layer for Plover. You will need to include `keymap_steno.h`. See `planck/keymaps/steno/keymap.c` for an example. Remember to create a key to switch to the layer as well as a key for exiting the layer. If you would like to switch modes on the fly you can use the keycodes `QK_STENO_BOLT` and `QK_STENO_GEMINI`. If you only want to use one of the protocols you may set it up in your initialization function: -```C +```c void matrix_init_user() { steno_set_mode(STENO_MODE_GEMINI); // or STENO_MODE_BOLT } @@ -49,37 +49,36 @@ Once you have your keyboard flashed launch Plover. Click the 'Configure...' butt On the display tab click 'Open stroke display'. With Plover disabled you should be able to hit keys on your keyboard and see them show up in the stroke display window. Use this to make sure you have set up your keymap correctly. You are now ready to steno! -## Learning Stenography +## Learning Stenography :id=learning-stenography -* [Learn Plover!](https://sites.google.com/site/ploverdoc/) -* [QWERTY Steno](http://qwertysteno.com/Home/) +* [Learn Plover!](https://sites.google.com/site/learnplover/) * [Steno Jig](https://joshuagrams.github.io/steno-jig/) * More resources at the Plover [Learning Stenography](https://github.com/openstenoproject/plover/wiki/Learning-Stenography) wiki -## Interfacing with the code +## Interfacing with the code :id=interfacing-with-the-code -The steno code has three interceptible hooks. If you define these functions, they will be called at certain points in processing; if they return true, processing continues, otherwise it's assumed you handled things. +The steno code has three interceptable hooks. If you define these functions, they will be called at certain points in processing; if they return true, processing continues, otherwise it's assumed you handled things. -```C +```c bool send_steno_chord_user(steno_mode_t mode, uint8_t chord[6]); ``` This function is called when a chord is about to be sent. Mode will be one of `STENO_MODE_BOLT` or `STENO_MODE_GEMINI`. This represents the actual chord that would be sent via whichever protocol. You can modify the chord provided to alter what gets sent. Remember to return true if you want the regular sending process to happen. -```C +```c bool process_steno_user(uint16_t keycode, keyrecord_t *record) { return true; } ``` This function is called when a keypress has come in, before it is processed. The keycode should be one of `QK_STENO_BOLT`, `QK_STENO_GEMINI`, or one of the `STN_*` key values. -```C +```c bool postprocess_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t mode, uint8_t chord[6], int8_t pressed); ``` This function is called after a key has been processed, but before any decision about whether or not to send a chord. If `IS_PRESSED(record->event)` is false, and `pressed` is 0 or 1, the chord will be sent shortly, but has not yet been sent. This is where to put hooks for things like, say, live displays of steno chords or keys. -## Keycode Reference +## Keycode Reference :id=keycode-reference As defined in `keymap_steno.h`. @@ -129,4 +128,3 @@ As defined in `keymap_steno.h`. |`STN_RES1`||(GeminiPR only)| |`STN_RES2`||(GeminiPR only)| |`STN_PWR`||(GeminiPR only)| - diff --git a/docs/feature_swap_hands.md b/docs/feature_swap_hands.md index 09e01d50d3c..009477d2033 100644 --- a/docs/feature_swap_hands.md +++ b/docs/feature_swap_hands.md @@ -28,3 +28,4 @@ Note that the array indices are reversed same as the matrix and the values are o |`SH_MOFF` |Momentarily turns off swap. | |`SH_TG` |Toggles swap on and off with every key press. | |`SH_TT` |Toggles with a tap; momentary when held. | +|`SH_OS` |One shot swap hands: toggles while pressed or until next key press. | diff --git a/docs/feature_tap_dance.md b/docs/feature_tap_dance.md index f48f11b1cb1..d2da39ad2b7 100644 --- a/docs/feature_tap_dance.md +++ b/docs/feature_tap_dance.md @@ -1,31 +1,24 @@ # Tap Dance: A Single Key Can Do 3, 5, or 100 Different Things -## Introduction +## Introduction :id=introduction + Hit the semicolon key once, send a semicolon. Hit it twice, rapidly -- send a colon. Hit it three times, and your keyboard's LEDs do a wild dance. That's just one example of what Tap Dance can do. It's one of the nicest community-contributed features in the firmware, conceived and created by [algernon](https://github.com/algernon) in [#451](https://github.com/qmk/qmk_firmware/pull/451). Here's how algernon describes the feature: With this feature one can specify keys that behave differently, based on the amount of times they have been tapped, and when interrupted, they get handled before the interrupter. -## Explanatory Comparison with `ACTION_FUNCTION_TAP` -`ACTION_FUNCTION_TAP` can offer similar functionality to Tap Dance, but it's worth noting some important differences. To do this, let's explore a certain setup! We want one key to send `Space` on single-tap, but `Enter` on double-tap. +## How to Use Tap Dance :id=how-to-use -With `ACTION_FUNCTION_TAP`, it is quite a rain-dance to set this up, and has the problem that when the sequence is interrupted, the interrupting key will be sent first. Thus, `SPC a` will result in `a SPC` being sent, if `SPC` and `a` are both typed within `TAPPING_TERM`. With the Tap Dance feature, that'll come out correctly as `SPC a` (even if both `SPC` and `a` are typed within the `TAPPING_TERM`. - -To achieve this correct handling of interrupts, the implementation of Tap Dance hooks into two parts of the system: `process_record_quantum()`, and the matrix scan. These two parts are explained below, but for now the point to note is that we need the latter to be able to time out a tap sequence even when a key is not being pressed. That way, `SPC` alone will time out and register after `TAPPING_TERM` time. - -## How to Use Tap Dance -But enough of the generalities; lets look at how to actually use Tap Dance! - -First, you will need `TAP_DANCE_ENABLE=yes` in your `rules.mk`, because the feature is disabled by default. This adds a little less than 1k to the firmware size. +First, you will need `TAP_DANCE_ENABLE = yes` in your `rules.mk`, because the feature is disabled by default. This adds a little less than 1k to the firmware size. Optionally, you might want to set a custom `TAPPING_TERM` time by adding something like this in you `config.h`: -``` +```c #define TAPPING_TERM 175 ``` -The `TAPPING_TERM` time is the maximum time allowed between taps of your Tap Dance key, and is measured in milliseconds. For example, if you used the above `#define` statement and set up a Tap Dance key that sends `Space` on single-tap and `Enter` on double-tap, then this key will send `ENT` only if you tap this key twice in less than 175ms. If you tap the key, wait more than 175ms, and tap the key again you'll end up sending `SPC SPC` instead. +The `TAPPING_TERM` time is the maximum time allowed between taps of your Tap Dance key, and is measured in milliseconds. For example, if you used the above `#define` statement and set up a Tap Dance key that sends `Space` on single-tap and `Enter` on double-tap, then this key will send `ENT` only if you tap this key twice in less than 175ms. If you tap the key, wait more than 175ms, and tap the key again you'll end up sending `SPC SPC` instead. -Next, you will want to define some tap-dance keys, which is easiest to do with the `TD()` macro, that - similar to `F()` - takes a number, which will later be used as an index into the `tap_dance_actions` array. +Next, you will want to define some tap-dance keys, which is easiest to do with the `TD()` macro, that takes a number which will later be used as an index into the `tap_dance_actions` array. After this, you'll want to use the `tap_dance_actions` array to specify what actions shall be taken when a tap-dance key is in action. Currently, there are five possible options: @@ -35,7 +28,9 @@ After this, you'll want to use the `tap_dance_actions` array to specify what act * `ACTION_TAP_DANCE_LAYER_TOGGLE(kc, layer)`: Sends the `kc` keycode when tapped once, or toggles the state of `layer`. (this functions like the `TG` layer keycode). * `ACTION_TAP_DANCE_FN(fn)`: Calls the specified function - defined in the user keymap - with the final tap count of the tap dance action. * `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn)`: Calls the first specified function - defined in the user keymap - on every tap, the second function when the dance action finishes (like the previous option), and the last function when the tap dance action resets. -* `ACTION_TAP_DANCE_FN_ADVANCED_TIME(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn, tap_specific_tapping_term)`: This functions identically to the `ACTION_TAP_DANCE_FN_ADVANCED` function, but uses a custom tapping term for it, instead of the predefined `TAPPING_TERM`. +* ~~`ACTION_TAP_DANCE_FN_ADVANCED_TIME(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn, tap_specific_tapping_term)`~~: This functions identically to the `ACTION_TAP_DANCE_FN_ADVANCED` function, but uses a custom tapping term for it, instead of the predefined `TAPPING_TERM`. + * This is deprecated in favor of the Per Key Tapping Term functionality, as outlined [here](custom_quantum_functions.md#Custom_Tapping_Term). You'd want to check for the specific `TD()` macro that you want to use (such as `TD(TD_ESC_CAPS)`) instead of using this specific Tap Dance function. + The first option is enough for a lot of cases, that just want dual roles. For example, `ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT)` will result in `Space` being sent on single-tap, `Enter` otherwise. @@ -43,11 +38,12 @@ The first option is enough for a lot of cases, that just want dual roles. For ex Similar to the first option, the second option is good for simple layer-switching cases. -For more complicated cases, use the third or fourth options (examples of each are listed below). +For more complicated cases, use the third or fourth options (examples of each are listed below). Finally, the fifth option is particularly useful if your non-Tap-Dance keys start behaving weirdly after adding the code for your Tap Dance keys. The likely problem is that you changed the `TAPPING_TERM` time to make your Tap Dance keys easier for you to use, and that this has changed the way your other keys handle interrupts. -## Implementation Details +## Implementation Details :id=implementation + Well, that's the bulk of it! You should now be able to work through the examples below, and to develop your own Tap Dance functionality. But if you want a deeper understanding of what's going on behind the scenes, then read on for the explanation of how it all works! The main entry point is `process_tap_dance()`, called from `process_record_quantum()`, which is run for every keypress, and our handler gets to run early. This function checks whether the key pressed is a tap-dance key. If it is not, and a tap-dance was in action, we handle that first, and enqueue the newly pressed key. If it is a tap-dance key, then we check if it is the same as the already active one (if there's one active, that is). If it is not, we fire off the old one first, then register the new one. If it was the same, we increment the counter and reset the timer. @@ -58,9 +54,9 @@ Our next stop is `matrix_scan_tap_dance()`. This handles the timeout of tap-danc For the sake of flexibility, tap-dance actions can be either a pair of keycodes, or a user function. The latter allows one to handle higher tap counts, or do extra things, like blink the LEDs, fiddle with the backlighting, and so on. This is accomplished by using an union, and some clever macros. -# Examples +## Examples :id=examples -## Simple Example +### Simple Example :id=simple-example Here's a simple example for a single definition: @@ -69,23 +65,26 @@ Here's a simple example for a single definition: 3. In your `keymap.c` file, define the variables and definitions, then add to your keymap: ```c -//Tap Dance Declarations +// Tap Dance declarations enum { - TD_ESC_CAPS = 0 + TD_ESC_CAPS, }; -//Tap Dance Definitions +// Tap Dance definitions qk_tap_dance_action_t tap_dance_actions[] = { - //Tap once for Esc, twice for Caps Lock - [TD_ESC_CAPS] = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS) -// Other declarations would go here, separated by commas, if you have them + // Tap once for Escape, twice for Caps Lock + [TD_ESC_CAPS] = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS), }; -//In Layer declaration, add tap dance item in place of a key code -TD(TD_ESC_CAPS) +// Add tap dance item in place of a key code +const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { + // ... + TD(TD_ESC_CAPS) + // ... +}; ``` -## Complex Examples +### Complex Examples :id=complex-examples This section details several complex tap dance examples. All the enums used in the examples are declared like this: @@ -93,104 +92,105 @@ All the enums used in the examples are declared like this: ```c // Enums defined for all examples: enum { - CT_SE = 0, - CT_CLN, - CT_EGG, - CT_FLSH, - X_TAP_DANCE + CT_SE, + CT_CLN, + CT_EGG, + CT_FLSH, + X_TAP_DANCE }; ``` -### Example 1: Send `:` on Single Tap, `;` on Double Tap + +#### Example 1: Send `:` on Single Tap, `;` on Double Tap :id=example-1 + ```c -void dance_cln_finished (qk_tap_dance_state_t *state, void *user_data) { - if (state->count == 1) { - register_code (KC_RSFT); - register_code (KC_SCLN); - } else { - register_code (KC_SCLN); - } +void dance_cln_finished(qk_tap_dance_state_t *state, void *user_data) { + if (state->count == 1) { + register_code16(KC_COLN); + } else { + register_code(KC_SCLN); + } } -void dance_cln_reset (qk_tap_dance_state_t *state, void *user_data) { - if (state->count == 1) { - unregister_code (KC_RSFT); - unregister_code (KC_SCLN); - } else { - unregister_code (KC_SCLN); - } +void dance_cln_reset(qk_tap_dance_state_t *state, void *user_data) { + if (state->count == 1) { + unregister_code16(KC_COLN); + } else { + unregister_code(KC_SCLN); + } } -//All tap dance functions would go here. Only showing this one. +// All tap dance functions would go here. Only showing this one. qk_tap_dance_action_t tap_dance_actions[] = { - [CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset) + [CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, dance_cln_finished, dance_cln_reset), }; ``` -### Example 2: Send "Safety Dance!" After 100 Taps + +#### Example 2: Send "Safety Dance!" After 100 Taps :id=example-2 + ```c -void dance_egg (qk_tap_dance_state_t *state, void *user_data) { - if (state->count >= 100) { - SEND_STRING ("Safety dance!"); - reset_tap_dance (state); - } +void dance_egg(qk_tap_dance_state_t *state, void *user_data) { + if (state->count >= 100) { + SEND_STRING("Safety dance!"); + reset_tap_dance(state); + } } qk_tap_dance_action_t tap_dance_actions[] = { - [CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg) + [CT_EGG] = ACTION_TAP_DANCE_FN(dance_egg), }; ``` -### Example 3: Turn LED Lights On Then Off, One at a Time +#### Example 3: Turn LED Lights On Then Off, One at a Time :id=example-3 ```c -// on each tap, light up one led, from right to left -// on the forth tap, turn them off from right to left +// On each tap, light up one LED, from right to left +// On the fourth tap, turn them off from right to left void dance_flsh_each(qk_tap_dance_state_t *state, void *user_data) { - switch (state->count) { - case 1: - ergodox_right_led_3_on(); - break; - case 2: - ergodox_right_led_2_on(); - break; - case 3: - ergodox_right_led_1_on(); - break; - case 4: - ergodox_right_led_3_off(); - _delay_ms(50); - ergodox_right_led_2_off(); - _delay_ms(50); - ergodox_right_led_1_off(); - } + switch (state->count) { + case 1: + ergodox_right_led_3_on(); + break; + case 2: + ergodox_right_led_2_on(); + break; + case 3: + ergodox_right_led_1_on(); + break; + case 4: + ergodox_right_led_3_off(); + wait_ms(50); + ergodox_right_led_2_off(); + wait_ms(50); + ergodox_right_led_1_off(); + } } -// on the fourth tap, set the keyboard on flash state +// On the fourth tap, set the keyboard on flash state void dance_flsh_finished(qk_tap_dance_state_t *state, void *user_data) { - if (state->count >= 4) { - reset_keyboard(); - reset_tap_dance(state); - } + if (state->count >= 4) { + reset_keyboard(); + } } -// if the flash state didn't happen, then turn off LEDs, left to right +// If the flash state didn't happen, then turn off LEDs, left to right void dance_flsh_reset(qk_tap_dance_state_t *state, void *user_data) { - ergodox_right_led_1_off(); - _delay_ms(50); - ergodox_right_led_2_off(); - _delay_ms(50); - ergodox_right_led_3_off(); + ergodox_right_led_1_off(); + wait_ms(50); + ergodox_right_led_2_off(); + wait_ms(50); + ergodox_right_led_3_off(); } -//All tap dances now put together. Example 3 is "CT_FLASH" +// All tap dances now put together. Example 3 is "CT_FLASH" qk_tap_dance_action_t tap_dance_actions[] = { - [CT_SE] = ACTION_TAP_DANCE_DOUBLE (KC_SPC, KC_ENT) - ,[CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED (NULL, dance_cln_finished, dance_cln_reset) - ,[CT_EGG] = ACTION_TAP_DANCE_FN (dance_egg) - ,[CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED (dance_flsh_each, dance_flsh_finished, dance_flsh_reset) + [CT_SE] = ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT), + [CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, dance_cln_finished, dance_cln_reset), + [CT_EGG] = ACTION_TAP_DANCE_FN(dance_egg), + [CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED(dance_flsh_each, dance_flsh_finished, dance_flsh_reset) }; ``` -### Example 4: 'Quad Function Tap-Dance' +#### Example 4: 'Quad Function Tap-Dance' :id=example-4 By [DanielGGordon](https://github.com/danielggordon) @@ -201,40 +201,37 @@ Below is a specific example: * Double Tap = Send `Escape` * Double Tap and Hold = Send `Alt` -## Setup - You will need a few things that can be used for 'Quad Function Tap-Dance'. You'll need to add these to the top of your `keymap.c` file, before your keymap. ```c typedef struct { - bool is_press_action; - int state; + bool is_press_action; + uint8_t state; } tap; enum { - SINGLE_TAP = 1, - SINGLE_HOLD = 2, - DOUBLE_TAP = 3, - DOUBLE_HOLD = 4, - DOUBLE_SINGLE_TAP = 5, //send two single taps - TRIPLE_TAP = 6, - TRIPLE_HOLD = 7 + SINGLE_TAP = 1, + SINGLE_HOLD, + DOUBLE_TAP, + DOUBLE_HOLD, + DOUBLE_SINGLE_TAP, // Send two single taps + TRIPLE_TAP, + TRIPLE_HOLD }; -//Tap dance enums +// Tap dance enums enum { - X_CTL = 0, - SOME_OTHER_DANCE + X_CTL, + SOME_OTHER_DANCE }; -int cur_dance (qk_tap_dance_state_t *state); - -//for the x tap dance. Put it here so it can be used in any keymap -void x_finished (qk_tap_dance_state_t *state, void *user_data); -void x_reset (qk_tap_dance_state_t *state, void *user_data); +uint8_t cur_dance(qk_tap_dance_state_t *state); +// For the x tap dance. Put it here so it can be used in any keymap +void x_finished(qk_tap_dance_state_t *state, void *user_data); +void x_reset(qk_tap_dance_state_t *state, void *user_data); ``` Now, at the bottom of your `keymap.c` file, you'll need to add the following: @@ -267,65 +264,62 @@ Now, at the bottom of your `keymap.c` file, you'll need to add the following: * For the third point, there does exist the 'DOUBLE_SINGLE_TAP', however this is not fully tested * */ -int cur_dance (qk_tap_dance_state_t *state) { - if (state->count == 1) { - if (state->interrupted || !state->pressed) return SINGLE_TAP; - //key has not been interrupted, but they key is still held. Means you want to send a 'HOLD'. - else return SINGLE_HOLD; - } - else if (state->count == 2) { - /* - * DOUBLE_SINGLE_TAP is to distinguish between typing "pepper", and actually wanting a double tap - * action when hitting 'pp'. Suggested use case for this return value is when you want to send two - * keystrokes of the key, and not the 'double tap' action/macro. - */ - if (state->interrupted) return DOUBLE_SINGLE_TAP; - else if (state->pressed) return DOUBLE_HOLD; - else return DOUBLE_TAP; - } - //Assumes no one is trying to type the same letter three times (at least not quickly). - //If your tap dance key is 'KC_W', and you want to type "www." quickly - then you will need to add - //an exception here to return a 'TRIPLE_SINGLE_TAP', and define that enum just like 'DOUBLE_SINGLE_TAP' - if (state->count == 3) { - if (state->interrupted || !state->pressed) return TRIPLE_TAP; - else return TRIPLE_HOLD; - } - else return 8; //magic number. At some point this method will expand to work for more presses +uint8_t cur_dance(qk_tap_dance_state_t *state) { + if (state->count == 1) { + if (state->interrupted || !state->pressed) return SINGLE_TAP; + // Key has not been interrupted, but the key is still held. Means you want to send a 'HOLD'. + else return SINGLE_HOLD; + } else if (state->count == 2) { + // DOUBLE_SINGLE_TAP is to distinguish between typing "pepper", and actually wanting a double tap + // action when hitting 'pp'. Suggested use case for this return value is when you want to send two + // keystrokes of the key, and not the 'double tap' action/macro. + if (state->interrupted) return DOUBLE_SINGLE_TAP; + else if (state->pressed) return DOUBLE_HOLD; + else return DOUBLE_TAP; + } + + // Assumes no one is trying to type the same letter three times (at least not quickly). + // If your tap dance key is 'KC_W', and you want to type "www." quickly - then you will need to add + // an exception here to return a 'TRIPLE_SINGLE_TAP', and define that enum just like 'DOUBLE_SINGLE_TAP' + if (state->count == 3) { + if (state->interrupted || !state->pressed) return TRIPLE_TAP; + else return TRIPLE_HOLD; + } else return 8; // Magic number. At some point this method will expand to work for more presses } -//instanalize an instance of 'tap' for the 'x' tap dance. +// Create an instance of 'tap' for the 'x' tap dance. static tap xtap_state = { - .is_press_action = true, - .state = 0 + .is_press_action = true, + .state = 0 }; -void x_finished (qk_tap_dance_state_t *state, void *user_data) { - xtap_state.state = cur_dance(state); - switch (xtap_state.state) { - case SINGLE_TAP: register_code(KC_X); break; - case SINGLE_HOLD: register_code(KC_LCTRL); break; - case DOUBLE_TAP: register_code(KC_ESC); break; - case DOUBLE_HOLD: register_code(KC_LALT); break; - case DOUBLE_SINGLE_TAP: register_code(KC_X); unregister_code(KC_X); register_code(KC_X); - //Last case is for fast typing. Assuming your key is `f`: - //For example, when typing the word `buffer`, and you want to make sure that you send `ff` and not `Esc`. - //In order to type `ff` when typing fast, the next character will have to be hit within the `TAPPING_TERM`, which by default is 200ms. - } +void x_finished(qk_tap_dance_state_t *state, void *user_data) { + xtap_state.state = cur_dance(state); + switch (xtap_state.state) { + case SINGLE_TAP: register_code(KC_X); break; + case SINGLE_HOLD: register_code(KC_LCTRL); break; + case DOUBLE_TAP: register_code(KC_ESC); break; + case DOUBLE_HOLD: register_code(KC_LALT); break; + // Last case is for fast typing. Assuming your key is `f`: + // For example, when typing the word `buffer`, and you want to make sure that you send `ff` and not `Esc`. + // In order to type `ff` when typing fast, the next character will have to be hit within the `TAPPING_TERM`, which by default is 200ms. + case DOUBLE_SINGLE_TAP: tap_code(KC_X); register_code(KC_X); + } } -void x_reset (qk_tap_dance_state_t *state, void *user_data) { - switch (xtap_state.state) { - case SINGLE_TAP: unregister_code(KC_X); break; - case SINGLE_HOLD: unregister_code(KC_LCTRL); break; - case DOUBLE_TAP: unregister_code(KC_ESC); break; - case DOUBLE_HOLD: unregister_code(KC_LALT); - case DOUBLE_SINGLE_TAP: unregister_code(KC_X); - } - xtap_state.state = 0; +void x_reset(qk_tap_dance_state_t *state, void *user_data) { + switch (xtap_state.state) { + case SINGLE_TAP: unregister_code(KC_X); break; + case SINGLE_HOLD: unregister_code(KC_LCTRL); break; + case DOUBLE_TAP: unregister_code(KC_ESC); break; + case DOUBLE_HOLD: unregister_code(KC_LALT); + case DOUBLE_SINGLE_TAP: unregister_code(KC_X); + } + xtap_state.state = 0; } qk_tap_dance_action_t tap_dance_actions[] = { - [X_CTL] = ACTION_TAP_DANCE_FN_ADVANCED(NULL,x_finished, x_reset) + [X_CTL] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, x_finished, x_reset) }; ``` @@ -335,90 +329,91 @@ If you want to implement this in your userspace, then you may want to check out > In this configuration "hold" takes place **after** tap dance timeout (see `ACTION_TAP_DANCE_FN_ADVANCED_TIME`). To achieve instant hold, remove `state->interrupted` checks in conditions. As a result you may use comfortable longer tapping periods to have more time for taps and not to wait too long for holds (try starting with doubled `TAPPING_TERM`). -### Example 5: Using tap dance for advanced mod-tap and layer-tap keys +#### Example 5: Using tap dance for advanced mod-tap and layer-tap keys :id=example-5 Tap dance can be used to emulate `MT()` and `LT()` behavior when the tapped code is not a basic keycode. This is useful to send tapped keycodes that normally require `Shift`, such as parentheses or curly braces—or other modified keycodes, such as `Control + X`. Below your layers and custom keycodes, add the following: ```c -// tapdance keycodes +// Tap Dance keycodes enum td_keycodes { - ALT_LP // Our example key: `LALT` when held, `(` when tapped. Add additional keycodes for each tapdance. + ALT_LP // Our example key: `LALT` when held, `(` when tapped. Add additional keycodes for each tapdance. }; -// define a type containing as many tapdance states as you need +// Define a type containing as many tapdance states as you need typedef enum { - SINGLE_TAP, - SINGLE_HOLD, - DOUBLE_SINGLE_TAP + SINGLE_TAP, + SINGLE_HOLD, + DOUBLE_SINGLE_TAP } td_state_t; -// create a global instance of the tapdance state type +// Create a global instance of the tapdance state type static td_state_t td_state; -// declare your tapdance functions: +// Declare your tapdance functions: -// function to determine the current tapdance state -int cur_dance (qk_tap_dance_state_t *state); +// Function to determine the current tapdance state +uint8_t cur_dance(qk_tap_dance_state_t *state); // `finished` and `reset` functions for each tapdance keycode -void altlp_finished (qk_tap_dance_state_t *state, void *user_data); -void altlp_reset (qk_tap_dance_state_t *state, void *user_data); +void altlp_finished(qk_tap_dance_state_t *state, void *user_data); +void altlp_reset(qk_tap_dance_state_t *state, void *user_data); ``` Below your `LAYOUT`, define each of the tapdance functions: ```c -// determine the tapdance state to return -int cur_dance (qk_tap_dance_state_t *state) { - if (state->count == 1) { - if (state->interrupted || !state->pressed) { return SINGLE_TAP; } - else { return SINGLE_HOLD; } - } - if (state->count == 2) { return DOUBLE_SINGLE_TAP; } - else { return 3; } // any number higher than the maximum state value you return above -} - -// handle the possible states for each tapdance keycode you define: +// Determine the tapdance state to return +uint8_t cur_dance(qk_tap_dance_state_t *state) { + if (state->count == 1) { + if (state->interrupted || !state->pressed) return SINGLE_TAP; + else return SINGLE_HOLD; + } -void altlp_finished (qk_tap_dance_state_t *state, void *user_data) { - td_state = cur_dance(state); - switch (td_state) { - case SINGLE_TAP: - register_code16(KC_LPRN); - break; - case SINGLE_HOLD: - register_mods(MOD_BIT(KC_LALT)); // for a layer-tap key, use `layer_on(_MY_LAYER)` here - break; - case DOUBLE_SINGLE_TAP: // allow nesting of 2 parens `((` within tapping term - tap_code16(KC_LPRN); - register_code16(KC_LPRN); - } + if (state->count == 2) return DOUBLE_SINGLE_TAP; + else return 3; // Any number higher than the maximum state value you return above } -void altlp_reset (qk_tap_dance_state_t *state, void *user_data) { - switch (td_state) { - case SINGLE_TAP: - unregister_code16(KC_LPRN); - break; - case SINGLE_HOLD: - unregister_mods(MOD_BIT(KC_LALT)); // for a layer-tap key, use `layer_off(_MY_LAYER)` here - break; - case DOUBLE_SINGLE_TAP: - unregister_code16(KC_LPRN); - } +// Handle the possible states for each tapdance keycode you define: + +void altlp_finished(qk_tap_dance_state_t *state, void *user_data) { + td_state = cur_dance(state); + switch (td_state) { + case SINGLE_TAP: + register_code16(KC_LPRN); + break; + case SINGLE_HOLD: + register_mods(MOD_BIT(KC_LALT)); // For a layer-tap key, use `layer_on(_MY_LAYER)` here + break; + case DOUBLE_SINGLE_TAP: // Allow nesting of 2 parens `((` within tapping term + tap_code16(KC_LPRN); + register_code16(KC_LPRN); + } } -// define `ACTION_TAP_DANCE_FN_ADVANCED()` for each tapdance keycode, passing in `finished` and `reset` functions +void altlp_reset(qk_tap_dance_state_t *state, void *user_data) { + switch (td_state) { + case SINGLE_TAP: + unregister_code16(KC_LPRN); + break; + case SINGLE_HOLD: + unregister_mods(MOD_BIT(KC_LALT)); // For a layer-tap key, use `layer_off(_MY_LAYER)` here + break; + case DOUBLE_SINGLE_TAP: + unregister_code16(KC_LPRN); + } +} + +// Define `ACTION_TAP_DANCE_FN_ADVANCED()` for each tapdance keycode, passing in `finished` and `reset` functions qk_tap_dance_action_t tap_dance_actions[] = { - [ALT_LP] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, altlp_finished, altlp_reset) + [ALT_LP] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, altlp_finished, altlp_reset) }; ``` Wrap each tapdance keycode in `TD()` when including it in your keymap, e.g. `TD(ALT_LP)`. -### Example 6: Using tap dance for momentary-layer-switch and layer-toggle keys +#### Example 6: Using tap dance for momentary-layer-switch and layer-toggle keys :id=example-6 Tap Dance can be used to mimic MO(layer) and TG(layer) functionality. For this example, we will set up a key to function as `KC_QUOT` on single-tap, as `MO(_MY_LAYER)` on single-hold, and `TG(_MY_LAYER)` on double-tap. @@ -426,97 +421,92 @@ The first step is to include the following code towards the beginning of your `k ```c typedef struct { - bool is_press_action; - int state; + bool is_press_action; + uint8_t state; } tap; -//Define a type for as many tap dance states as you need +// Define a type for as many tap dance states as you need enum { - SINGLE_TAP = 1, - SINGLE_HOLD = 2, - DOUBLE_TAP = 3 + SINGLE_TAP = 1, + SINGLE_HOLD, + DOUBLE_TAP }; enum { - QUOT_LAYR = 0 //Our custom tap dance key; add any other tap dance keys to this enum + QUOT_LAYR, // Our custom tap dance key; add any other tap dance keys to this enum }; -//Declare the functions to be used with your tap dance key(s) +// Declare the functions to be used with your tap dance key(s) -//Function associated with all tap dances -int cur_dance (qk_tap_dance_state_t *state); +// Function associated with all tap dances +uint8_t cur_dance(qk_tap_dance_state_t *state); -//Functions associated with individual tap dances -void ql_finished (qk_tap_dance_state_t *state, void *user_data); -void ql_reset (qk_tap_dance_state_t *state, void *user_data); +// Functions associated with individual tap dances +void ql_finished(qk_tap_dance_state_t *state, void *user_data); +void ql_reset(qk_tap_dance_state_t *state, void *user_data); ``` Towards the bottom of your `keymap.c`, include the following code: ```c -//Determine the current tap dance state -int cur_dance (qk_tap_dance_state_t *state) { - if (state->count == 1) { - if (!state->pressed) { - return SINGLE_TAP; - } else { - return SINGLE_HOLD; - } - } else if (state->count == 2) { - return DOUBLE_TAP; - } - else return 8; +// Determine the current tap dance state +uint8_t cur_dance(qk_tap_dance_state_t *state) { + if (state->count == 1) { + if (!state->pressed) return SINGLE_TAP; + else return SINGLE_HOLD; + } else if (state->count == 2) return DOUBLE_TAP; + else return 8; } -//Initialize tap structure associated with example tap dance key +// Initialize tap structure associated with example tap dance key static tap ql_tap_state = { - .is_press_action = true, - .state = 0 + .is_press_action = true, + .state = 0 }; -//Functions that control what our tap dance key does -void ql_finished (qk_tap_dance_state_t *state, void *user_data) { - ql_tap_state.state = cur_dance(state); - switch (ql_tap_state.state) { - case SINGLE_TAP: - tap_code(KC_QUOT); - break; - case SINGLE_HOLD: - layer_on(_MY_LAYER); - break; - case DOUBLE_TAP: - //check to see if the layer is already set - if (layer_state_is(_MY_LAYER)) { - //if already set, then switch it off +// Functions that control what our tap dance key does +void ql_finished(qk_tap_dance_state_t *state, void *user_data) { + ql_tap_state.state = cur_dance(state); + switch (ql_tap_state.state) { + case SINGLE_TAP: + tap_code(KC_QUOT); + break; + case SINGLE_HOLD: + layer_on(_MY_LAYER); + break; + case DOUBLE_TAP: + // Check to see if the layer is already set + if (layer_state_is(_MY_LAYER)) { + // If already set, then switch it off + layer_off(_MY_LAYER); + } else { + // If not already set, then switch the layer on + layer_on(_MY_LAYER); + } + break; + } +} + +void ql_reset(qk_tap_dance_state_t *state, void *user_data) { + // If the key was held down and now is released then switch off the layer + if (ql_tap_state.state == SINGLE_HOLD) { layer_off(_MY_LAYER); - } else { - //if not already set, then switch the layer on - layer_on(_MY_LAYER); - } - break; - } + } + ql_tap_state.state = 0; } -void ql_reset (qk_tap_dance_state_t *state, void *user_data) { - //if the key was held down and now is released then switch off the layer - if (ql_tap_state.state==SINGLE_HOLD) { - layer_off(_MY_LAYER); - } - ql_tap_state.state = 0; -} - -//Associate our tap dance key with its functionality +// Associate our tap dance key with its functionality qk_tap_dance_action_t tap_dance_actions[] = { - [QUOT_LAYR] = ACTION_TAP_DANCE_FN_ADVANCED_TIME(NULL, ql_finished, ql_reset, 275) + [QUOT_LAYR] = ACTION_TAP_DANCE_FN_ADVANCED_TIME(NULL, ql_finished, ql_reset, 275) }; ``` -The above code is similar to that used in previous examples. The one point to note is that we need to be able to check which layers are active at any time so we can toggle them if needed. To do this we use the `layer_state_is( layer )` function which returns `true` if the given `layer` is active. +The above code is similar to that used in previous examples. The one point to note is that we need to be able to check which layers are active at any time so we can toggle them if needed. To do this we use the `layer_state_is(layer)` function which returns `true` if the given `layer` is active. The use of `cur_dance()` and `ql_tap_state` mirrors the above examples. -The `case:SINGLE_TAP` in `ql_finished` is similar to the above examples. The `case:SINGLE_HOLD` works in conjunction with `ql_reset()` to switch to `_MY_LAYER` while the tap dance key is held, and to switch away from `_MY_LAYER` when the key is released. This mirrors the use of `MO(_MY_LAYER)`. The `case:DOUBLE_TAP` works by checking whether `_MY_LAYER` is the active layer, and toggling it on or off accordingly. This mirrors the use of `TG(_MY_LAYER)`. +The `case:SINGLE_TAP` in `ql_finished` is similar to the above examples. The `SINGLE_HOLD` case works in conjunction with `ql_reset()` to switch to `_MY_LAYER` while the tap dance key is held, and to switch away from `_MY_LAYER` when the key is released. This mirrors the use of `MO(_MY_LAYER)`. The `DOUBLE_TAP` case works by checking whether `_MY_LAYER` is the active layer, and toggling it on or off accordingly. This mirrors the use of `TG(_MY_LAYER)`. -`tap_dance_actions[]` works similar to the above examples. Note that I used `ACTION_TAP_DANCE_FN_ADVANCED_TIME()` instead of `ACTION_TAP_DANCE_FN_ADVANCED()`. This is because I like my `TAPPING_TERM` to be short (~175ms) for my non-tap-dance keys but find that this is too quick for me to reliably complete tap dance actions - thus the increased time of 275ms here. +`tap_dance_actions[]` works similar to the above examples. Note that I used `ACTION_TAP_DANCE_FN_ADVANCED_TIME()` instead of `ACTION_TAP_DANCE_FN_ADVANCED()`. This is because I like my `TAPPING_TERM` to be short (\~175ms) for my non-tap-dance keys but find that this is too quick for me to reliably complete tap dance actions - thus the increased time of 275ms here. Finally, to get this tap dance key working, be sure to include `TD(QUOT_LAYR)` in your `keymaps[]`. diff --git a/docs/feature_unicode.md b/docs/feature_unicode.md index bd1f4fa5ae0..1208ac0064d 100644 --- a/docs/feature_unicode.md +++ b/docs/feature_unicode.md @@ -2,11 +2,25 @@ Unicode characters can be input straight from your keyboard! There are some limitations, however. -QMK has three different methods for enabling Unicode input and defining keycodes: +In order to enable Unicode support on your keyboard, you will need to do the following: -## Basic Unicode +1. Choose one of three supported Unicode implementations: [Basic Unicode](#basic-unicode), [Unicode Map](#unicode-map), [UCIS](#ucis). +2. Find which [input mode](#input-modes) is the best match for your operating system and setup. +3. [Set](#setting-the-input-mode) the appropriate input mode (or modes) in your configuration. +4. Add Unicode keycodes to your keymap. -This method supports Unicode code points up to `0x7FFF`. This covers characters for most modern languages, as well as symbols, but it doesn't cover emoji. + +## 1. Methods :id=methods + +QMK supports three different methods for enabling Unicode input and adding Unicode characters to your keymap. Each has its pros and cons in terms of flexibility and ease of use. Choose the one that best fits your use case. + +The Basic method should be enough for most users. However, if you need a wider range of supported characters (including emoji, rare symbols etc.), you should use Unicode Map. + +
+ +### 1.1. Basic Unicode :id=basic-unicode + +The easiest to use method, albeit somewhat limited. It stores Unicode characters as keycodes in the keymap itself, so it only supports code points up to `0x7FFF`. This covers characters for most modern languages (including East Asian), as well as symbols, but it doesn't cover emoji. Add the following to your `rules.mk`: @@ -14,11 +28,13 @@ Add the following to your `rules.mk`: UNICODE_ENABLE = yes ``` -Then add `UC(c)` keycodes to your keymap, where _c_ is the code point (preferably in hexadecimal, up to 4 digits long). For example: `UC(0x45B)`, `UC(0x30C4)`. +Then add `UC(c)` keycodes to your keymap, where _c_ is the code point of the desired character (preferably in hexadecimal, up to 4 digits long). For example, `UC(0x40B)` will output [Ћ](https://unicode-table.com/en/040B/), and `UC(0x30C4)` will output [ツ](https://unicode-table.com/en/30C4). -## Unicode Map +
-This method supports all possible code points (up to `0x10FFFF`); however, you need to maintain a separate mapping table in your keymap file, which may contain at most 16384 entries. +### 1.2. Unicode Map :id=unicode-map + +In addition to standard character ranges, this method also covers emoji, ancient scripts, rare symbols etc. In fact, all possible code points (up to `0x10FFFF`) are supported. Here, Unicode characters are stored in a separate mapping table. You need to maintain a `unicode_map` array in your keymap file, which may contain at most 16384 entries. Add the following to your `rules.mk`: @@ -26,7 +42,7 @@ Add the following to your `rules.mk`: UNICODEMAP_ENABLE = yes ``` -Then add `X(i)` keycodes to your keymap, where _i_ is an array index into the mapping table: +Then add `X(i)` keycodes to your keymap, where _i_ is the desired character's index in the mapping table. This can be a numeric value, but it's recommended to keep the indices in an enum and access them by name. ```c enum unicode_names { @@ -44,15 +60,17 @@ const uint32_t PROGMEM unicode_map[] = { Then you can use `X(BANG)`, `X(SNEK)` etc. in your keymap. -### Lower and Upper Case +#### Lower and Upper Case Characters often come in lower and upper case pairs, such as å and Å. To make inputting these characters easier, you can use `XP(i, j)` in your keymap, where _i_ and _j_ are the mapping table indices of the lower and upper case character, respectively. If you're holding down Shift or have Caps Lock turned on when you press the key, the second (upper case) character will be inserted; otherwise, the first (lower case) version will appear. This is most useful when creating a keymap for an international layout with special characters. Instead of having to put the lower and upper case versions of a character on separate keys, you can have them both on the same key by using `XP()`. This helps blend Unicode keys in with regular alphas. -Due to keycode size constraints, _i_ and _j_ can each only refer to one of the first 128 characters in your `unicode_map`. In other words, 0 ≤ _i_ ≤ 127 and 0 ≤ _j_ ≤ 127. This is enough for most use cases, but if you'd like to customize the index calculation, you can override the [`unicodemap_index()`](https://github.com/qmk/qmk_firmware/blob/71f640d47ee12c862c798e1f56392853c7b1c1a8/quantum/process_keycode/process_unicodemap.c#L40) function. This also allows you to, say, check Ctrl instead of Shift/Caps. +Due to keycode size constraints, _i_ and _j_ can each only refer to one of the first 128 characters in your `unicode_map`. In other words, 0 ≤ _i_ ≤ 127 and 0 ≤ _j_ ≤ 127. This is enough for most use cases, but if you'd like to customize the index calculation, you can override the [`unicodemap_index()`](https://github.com/qmk/qmk_firmware/blob/71f640d47ee12c862c798e1f56392853c7b1c1a8/quantum/process_keycode/process_unicodemap.c#L36) function. This also allows you to, say, check Ctrl instead of Shift/Caps. -## UCIS +
+ +### 1.3. UCIS :id=ucis This method also supports all possible code points. As with the Unicode Map method, you need to maintain a mapping table in your keymap file. However, there are no built-in keycodes for this feature — you have to create a custom keycode or function that invokes this functionality. @@ -66,15 +84,18 @@ Then define a table like this in your keymap file: ```c const qk_ucis_symbol_t ucis_symbol_table[] = UCIS_TABLE( - UCIS_SYM("poop", 0x1F4A9), // 💩 - UCIS_SYM("rofl", 0x1F923), // 🤣 - UCIS_SYM("kiss", 0x1F619) // 😙 + UCIS_SYM("poop", 0x1F4A9), // 💩 + UCIS_SYM("rofl", 0x1F923), // 🤣 + UCIS_SYM("cuba", 0x1F1E8, 0x1F1FA), // 🇨🇺 + UCIS_SYM("look", 0x0CA0, 0x005F, 0x0CA0) // ಠ_ಠ ); ``` -To use it, call `qk_ucis_start()`. Then, type the mnemonic for the character (such as "rofl"), and hit Space or Enter. QMK should erase the "rofl" text and insert the laughing emoji. +By default, each table entry may be up to 3 code points long. This number can be changed by adding `#define UCIS_MAX_CODE_POINTS n` to your `config.h` file. -### Customization +To use UCIS input, call `qk_ucis_start()`. Then, type the mnemonic for the character (such as "rofl") and hit Space, Enter or Esc. QMK should erase the "rofl" text and insert the laughing emoji. + +#### Customization There are several functions that you can define in your keymap to customize the functionality of this feature. @@ -84,134 +105,157 @@ There are several functions that you can define in your keymap to customize the You can find the default implementations of these functions in [`process_ucis.c`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_ucis.c). -## Input Modes + +## 2. Input Modes :id=input-modes Unicode input in QMK works by inputting a sequence of characters to the OS, sort of like a macro. Unfortunately, the way this is done differs for each platform. Specifically, each platform requires a different combination of keys to trigger Unicode input. Therefore, a corresponding input mode has to be set in QMK. The following input modes are available: -* **`UC_OSX`**: macOS built-in Unicode hex input. Supports code points up to `0xFFFF` (`0x10FFFF` with Unicode Map). +* **`UC_MAC`**: macOS built-in Unicode hex input. Supports code points up to `0x10FFFF` (all possible code points). To enable, go to _System Preferences > Keyboard > Input Sources_, add _Unicode Hex Input_ to the list (it's under _Other_), then activate it from the input dropdown in the Menu Bar. - By default, this mode uses the left Option key (`KC_LALT`) for Unicode input, but this can be changed by defining [`UNICODE_KEY_OSX`](#input-key-configuration) with another keycode. + By default, this mode uses the left Option key (`KC_LALT`) for Unicode input, but this can be changed by defining [`UNICODE_KEY_MAC`](#input-key-configuration) with a different keycode. - !> Using the _Unicode Hex Input_ input source may disable some Option based shortcuts, such as Option + Left Arrow and Option + Right Arrow. + !> Using the _Unicode Hex Input_ input source may disable some Option-based shortcuts, such as Option+Left and Option+Right. + + !> `UC_OSX` is a deprecated alias of `UC_MAC` that will be removed in future versions of QMK. All new keymaps should use `UC_MAC`. * **`UC_LNX`**: Linux built-in IBus Unicode input. Supports code points up to `0x10FFFF` (all possible code points). 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 another keycode. This might be required for IBus versions ≥1.5.15, where Ctrl+Shift+U behavior is consolidated into Ctrl+Shift+E. + 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\EnableHexNumpad` 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. + 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. This mode is not recommended because of reliability and compatibility issues; use the `UC_WINC` mode instead. * **`UC_BSD`**: _(non implemented)_ Unicode input under BSD. Not implemented at this time. If you're a BSD user and want to help add support for it, please [open an issue on GitHub](https://github.com/qmk/qmk_firmware/issues). * **`UC_WINC`**: Windows Unicode input using [WinCompose](https://github.com/samhocevar/wincompose). As of v0.9.0, supports code points up to `0x10FFFF` (all possible code points). - To enable, install the [latest release](https://github.com/samhocevar/wincompose/releases/latest). Once installed, WinCompose will automatically run on startup. Works reliably under all version of Windows supported by the app. - By default, this mode uses right Alt (`KC_RALT`) as the Compose key, but this can be changed in the WinCompose settings and by defining [`UNICODE_KEY_WINC`](#input-key-configuration) with another keycode. + To enable, install the [latest release](https://github.com/samhocevar/wincompose/releases/latest). Once installed, WinCompose will automatically run on startup. This mode works reliably under all version of Windows supported by the app. + By default, this mode uses right Alt (`KC_RALT`) as the Compose key, but this can be changed in the WinCompose settings and by defining [`UNICODE_KEY_WINC`](#input-key-configuration) with a different keycode. -### Switching Input Modes -There are two ways to set the input mode for Unicode: by keycode or by function. Keep in mind that both methods write to persistent storage (EEPROM), and are loaded each time the keyboard starts. So once you've set it the first time, you don't need to set it again unless you want to change it, or you've reset the EEPROM settings. +## 3. Setting the Input Mode :id=setting-the-input-mode -You can switch the input mode at any time by using one of the following keycodes. The easiest way is to add the ones you use to your keymap. - -|Keycode |Alias |Input Mode |Description | -|----------------------|---------|------------|--------------------------------------------------------------| -|`UNICODE_MODE_FORWARD`|`UC_MOD` |Next in list|[Cycle](#input-mode-cycling) through selected modes | -|`UNICODE_MODE_REVERSE`|`UC_RMOD`|Prev in list|[Cycle](#input-mode-cycling) through selected modes in reverse| -|`UNICODE_MODE_OSX` |`UC_M_OS`|`UC_OSX` |Switch to macOS input | -|`UNICODE_MODE_LNX` |`UC_M_LN`|`UC_LNX` |Switch to Linux input | -|`UNICODE_MODE_WIN` |`UC_M_WI`|`UC_WIN` |Switch to Windows input | -|`UNICODE_MODE_BSD` |`UC_M_BS`|`UC_BSD` |Switch to BSD input (not implemented) | -|`UNICODE_MODE_WINC` |`UC_M_WC`|`UC_WINC` |Switch to Windows input using WinCompose | - -You can also switch the input mode by calling `set_unicode_input_mode(x)` in your code, where _x_ is one of the above input mode constants (e.g. `UC_LNX`). Since the function only needs to be called once, it's recommended that you do it in `eeconfig_init_user()` (or a similar function). For example: +To set your desired input mode, add the following define to your `config.h`: ```c -void eeconfig_init_user(void) { - set_unicode_input_mode(UC_LNX); -} +#define UNICODE_SELECTED_MODES UC_LNX ``` -### Audio Feedback +This example sets the board's default input mode to `UC_LNX`. You can replace this with `UC_MAC`, `UC_WINC`, or any of the other modes listed [above](#input-modes). The board will automatically use the selected mode on startup, unless you manually switch to another mode (see [below](#keycodes)). + +You can also select multiple input modes, which allows you to easily cycle through them using the `UC_MOD`/`UC_RMOD` keycodes. + +```c +#define UNICODE_SELECTED_MODES UC_MAC, UC_LNX, UC_WINC +``` + +Note that the values are separated by commas. The board will remember the last used input mode and will continue using it on next power-up. You can disable this and force it to always start with the first mode in the list by adding `#define UNICODE_CYCLE_PERSIST false` to your `config.h`. + +#### Keycodes + +You can switch the input mode at any time by using the following keycodes. Adding these to your keymap allows you to quickly switch to a specific input mode, including modes not listed in `UNICODE_SELECTED_MODES`. + +|Keycode |Alias |Input Mode |Description | +|----------------------|---------|------------|-----------------------------------------------------------------------------| +|`UNICODE_MODE_FORWARD`|`UC_MOD` |Next in list|Cycle through selected modes, reverse direction when Shift is held | +|`UNICODE_MODE_REVERSE`|`UC_RMOD`|Prev in list|Cycle through selected modes in reverse, forward direction when Shift is held| +|`UNICODE_MODE_MAC` |`UC_M_MA`|`UC_MAC` |Switch to macOS input | +|`UNICODE_MODE_LNX` |`UC_M_LN`|`UC_LNX` |Switch to Linux input | +|`UNICODE_MODE_WIN` |`UC_M_WI`|`UC_WIN` |Switch to Windows input | +|`UNICODE_MODE_BSD` |`UC_M_BS`|`UC_BSD` |Switch to BSD input _(not implemented)_ | +|`UNICODE_MODE_WINC` |`UC_M_WC`|`UC_WINC` |Switch to Windows input using WinCompose | + +You can also switch the input mode by calling `set_unicode_input_mode(x)` in your code, where _x_ is one of the above input mode constants (e.g. `UC_LNX`). + +?> Using `UNICODE_SELECTED_MODES` is preferable to calling `set_unicode_input_mode()` in `matrix_init_user()` or similar functions, since it's better integrated into the Unicode system and has the added benefit of avoiding unnecessary writes to EEPROM. + +#### Audio Feedback If you have the [Audio feature](feature_audio.md) enabled on the board, you can set melodies to be played when you press the above keys. That way you can have some audio feedback when switching input modes. For instance, you can add these definitions to your `config.h` file: ```c -#define UNICODE_SONG_OSX COIN_SOUND +#define UNICODE_SONG_MAC AUDIO_ON_SOUND #define UNICODE_SONG_LNX UNICODE_LINUX -#define UNICODE_SONG_BSD MARIO_GAMEOVER +#define UNICODE_SONG_BSD TERMINAL_SOUND #define UNICODE_SONG_WIN UNICODE_WINDOWS #define UNICODE_SONG_WINC UNICODE_WINDOWS ``` -### Additional Customization + +## Additional Customization Because Unicode is a large and versatile feature, there are a number of options you can customize to make it work better on your system. -#### Start and Finish Input Functions +### Start and Finish Input Functions The functions for starting and finishing Unicode input on your platform can be overridden locally. Possible uses include customizing input mode behavior if you don't use the default keys, or adding extra visual/audio feedback to Unicode input. -* `void unicode_input_start(void)` – This sends the initial sequence that tells your platform to enter Unicode input mode. For example, it presses Ctrl+Shift+U on Linux and holds the Option key on macOS. -* `void unicode_input_finish(void)` – This is called to exit Unicode input mode, for example by pressing Space or releasing the Option key. +* `void unicode_input_start(void)` – This sends the initial sequence that tells your platform to enter Unicode input mode. For example, it holds the left Alt key followed by Num+ on Windows, and presses the `UNICODE_KEY_LNX` combination (default: Ctrl+Shift+U) on Linux. +* `void unicode_input_finish(void)` – This is called to exit Unicode input mode, for example by pressing Space or releasing the Alt key. You can find the default implementations of these functions in [`process_unicode_common.c`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_unicode_common.c). -#### Input Key Configuration +### Input Key Configuration You can customize the keys used to trigger Unicode input for macOS, Linux and WinCompose by adding corresponding defines to your `config.h`. The default values match the platforms' default settings, so you shouldn't need to change this unless Unicode input isn't working, or you want to use a different key (e.g. in order to free up left or right Alt). |Define |Type |Default |Example | |------------------|----------|------------------|-------------------------------------------| -|`UNICODE_KEY_OSX` |`uint8_t` |`KC_LALT` |`#define UNICODE_KEY_OSX KC_RALT` | +|`UNICODE_KEY_MAC` |`uint8_t` |`KC_LALT` |`#define UNICODE_KEY_MAC KC_RALT` | |`UNICODE_KEY_LNX` |`uint16_t`|`LCTL(LSFT(KC_U))`|`#define UNICODE_KEY_LNX LCTL(LSFT(KC_E))`| |`UNICODE_KEY_WINC`|`uint8_t` |`KC_RALT` |`#define UNICODE_KEY_WINC KC_RGUI` | -#### Input Mode Cycling -You can choose which input modes are available for cycling through. By default, this is disabled. If you want to enable it, limiting it to just the modes you use makes sense. Note that the values in the list are comma-delimited. +## Sending Unicode Strings + +QMK provides several functions that allow you to send Unicode input to the host programmatically: + +### `send_unicode_string()` + +This function is much like `send_string()`, but it allows you to input UTF-8 characters directly. It supports all code points, provided the selected input mode also supports it. Make sure your `keymap.c` file is formatted using UTF-8 encoding. ```c -#define UNICODE_SELECTED_MODES UC_OSX, UC_LNX, UC_WIN, UC_WINC +send_unicode_string("(ノಠ痊ಠ)ノ彡┻━┻"); ``` -You can cycle through the selected modes by using the `UC_MOD`/`UC_RMOD` keycodes, or by calling `cycle_unicode_input_mode(offset)` in your code (`offset` is how many modes to move forward by, so +1 corresponds to `UC_MOD`). +Example uses include sending Unicode strings when a key is pressed, as described in [Macros](feature_macros.md). -By default, when the keyboard boots, it will initialize the input mode to the last one you used. You can disable this and make it start with the first mode in the list every time by adding the following to your `config.h`: +### `send_unicode_hex_string()` + +Similar to `send_unicode_string()`, but the characters are represented by their Unicode code points, written in hexadecimal and separated by spaces. For example, the table flip above would be achieved with: ```c -#define UNICODE_CYCLE_PERSIST false +send_unicode_hex_string("0028 30CE 0CA0 75CA 0CA0 0029 30CE 5F61 253B 2501 253B"); ``` -!> Using `UNICODE_SELECTED_MODES` means you don't have to initially set the input mode in `matrix_init_user()` (or a similar function); the Unicode system will do that for you on startup. This has the added benefit of avoiding unnecessary writes to EEPROM. +An easy way to convert your Unicode string to this format is to use [this site](https://r12a.github.io/app-conversion/) and take the result in the "Hex/UTF-32" section. -## `send_unicode_hex_string` - -To type multiple characters for things like (ノಠ痊ಠ)ノ彡┻━┻, you can use `send_unicode_hex_string()` much like `SEND_STRING()` except you would use hex values separate by spaces. -For example, the table flip seen above would be `send_unicode_hex_string("0028 30CE 0CA0 75CA 0CA0 0029 30CE 5F61 253B 2501 253B")` - -There are many ways to get a hex code, but an easy one is [this site](https://r12a.github.io/app-conversion/). Just make sure to convert to hexadecimal, and that is your string. ## Additional Language Support -In `quantum/keymap_extras/`, you'll see various language files - these work the same way as the alternative layout ones do. Most are defined by their two letter country/language code followed by an underscore and a 4-letter abbreviation of its name. `FR_UGRV` which will result in a `ù` when using a software-implemented AZERTY layout. It's currently difficult to send such characters in just the firmware. +In `quantum/keymap_extras`, you'll see various language files — these work the same way as the ones for alternative layouts such as Colemak or BÉPO. When you include one of these language headers, you gain access to keycodes specific to that language / national layout. Such keycodes are defined by a 2-letter country/language code, followed by an underscore and a 4-letter abbreviation of the character to which the key corresponds. For example, including `keymap_french.h` and using `FR_UGRV` in your keymap will output `ù` when typed on a system with a native French AZERTY layout. + +If the primary system layout you use on your machine is different from US ANSI, using these language-specific keycodes can help your QMK keymaps better match what will actually be output on the screen. However, keep in mind that these keycodes are just aliases for the corresponding default US keycodes under the hood, and that the HID protocol used by keyboards is itself inherently based on US ANSI. + ## International Characters on Windows -### AutoHotkey allows Windows users to create custom hotkeys among others. +### AutoHotkey -The method does not require Unicode support in the keyboard itself but depends instead of [AutoHotkey](https://autohotkey.com) running in the background. +The method does not require Unicode support in the keyboard itself but instead depends on [AutoHotkey](https://autohotkey.com) running in the background. First you need to select a modifier combination that is not in use by any of your programs. -CtrlAltWin is not used very widely and should therefore be perfect for this. +Ctrl+Alt+Win is not used very widely and should therefore be perfect for this. There is a macro defined for a mod-tab combo `LCAG_T`. Add this mod-tab combo to a key on your keyboard, e.g.: `LCAG_T(KC_TAB)`. This makes the key behave like a tab key if pressed and released immediately but changes it to the modifier if used with another key. @@ -226,8 +270,24 @@ AutoHotkey inserts the Text right of `Send, ` when this combination is pressed. ### US International -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 à. - +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 { [ 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. diff --git a/docs/feature_userspace.md b/docs/feature_userspace.md index a2657c1f606..8b001e3ce21 100644 --- a/docs/feature_userspace.md +++ b/docs/feature_userspace.md @@ -1,6 +1,6 @@ # Userspace: Sharing Code Between Keymaps -If you use more than one keyboard with a similar keymap, you might see the benefit in being able to share code between them. Create your own folder in `users/` named the same as your keymap (ideally your github username, ``) with the following structure: +If you use more than one keyboard with a similar keymap, you might see the benefit in being able to share code between them. Create your own folder in `users/` named the same as your keymap (ideally your GitHub username, ``) with the following structure: * `/users//` (added to the path automatically) * `readme.md` (optional, recommended) @@ -73,7 +73,7 @@ The reason for this, is that `.h` won't be added in time to add settings ( ## Readme (`readme.md`) -Please include authorship (your name, github username, email), and optionally [a license that's GPL compatible](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses). +Please include authorship (your name, GitHub username, email), and optionally [a license that's GPL compatible](https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses). You can use this as a template: ``` @@ -93,17 +93,29 @@ You should have received a copy of the GNU General Public License along with this program. If not, see . ``` -You'd want to replace the year, name, email and github username with your info. +You'd want to replace the year, name, email and GitHub username with your info. Additionally, this is a good place to document your code, if you wish to share it with others. -# Examples +## Build All Keyboards That Support a Specific Keymap -For a brief example, checkout [`/users/_example/`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna). +Want to check all your keymaps build in a single command? You can run: + + make all: + +For example, + + make all:jack + +This is ideal for when you want ensure everything compiles successfully when preparing a [_Pull request_](https://github.com/qmk/qmk_firmware/pulls). + +## Examples + +For a brief example, checkout [`/users/_example/`](https://github.com/qmk/qmk_firmware/tree/master/users/_example). For a more complicated example, checkout [`/users/drashna/`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna)'s userspace. -## Customized Functions +### Customized Functions QMK has a bunch of [functions](custom_quantum_functions.md) that have [`_quantum`, `_kb`, and `_user` versions](custom_quantum_functions.md#a-word-on-core-vs-keyboards-vs-keymap) that you can use. You will pretty much always want to use the user version of these functions. But the problem is that if you use them in your userspace, then you don't have a version that you can use in your keymap. @@ -130,7 +142,7 @@ The `_keymap` part here doesn't matter, it just needs to be something other than You can see a list of this and other common functions in [`template.c`](https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.c) in [`users/drashna`](https://github.com/qmk/qmk_firmware/tree/master/users/drashna). -## Custom Features +### Custom Features Since the Userspace feature can support a staggering number of boards, you may have boards that you want to enable certain functionality for, but not for others. And you can actually create "features" that you can enable or disable in your own userspace. @@ -166,13 +178,13 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { ``` -## Consolidated Macros +### Consolidated Macros If you wanted to consolidate macros and other functions into your userspace for all of your keymaps, you can do that. This builds upon the [Customized Functions](#customized-functions) example above. This lets you maintain a bunch of macros that are shared between the different keyboards, and allow for keyboard specific macros, too. 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 ` 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 ".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 `.h` file. For instance: ```c diff --git a/docs/feature_wpm.md b/docs/feature_wpm.md new file mode 100644 index 00000000000..12dd0805798 --- /dev/null +++ b/docs/feature_wpm.md @@ -0,0 +1,25 @@ +# Word Per Minute (WPM) Calculcation + +The WPM feature uses time between keystrokes to compute a rolling average words +per minute rate and makes this available for various uses. + +Enable the WPM system by adding this to your `rules.mk`: + + WPM_ENABLE = yes + +For split keyboards using soft serial, the computed WPM +score will be available on the master AND slave half. + +## Public Functions + +`uint8_t get_current_wpm(void);` +This function returns the current WPM as an unsigned integer. + + +## Customized keys for WPM calc + +By default, the WPM score only includes letters, numbers, space and some +punctuation. If you want to change the set of characters considered as part of +the WPM calculation, you can implement `wpm_keycode_user(uint16_t keycode)` +and return true for any characters you would like included in the calculation, +or false to not count that particular keycode. diff --git a/docs/features.md b/docs/features.md deleted file mode 100644 index 44299bf10dc..00000000000 --- a/docs/features.md +++ /dev/null @@ -1,42 +0,0 @@ -# QMK Features - -QMK has a staggering number of features for building your keyboard. It can take some time to understand all of them and determine which one will achieve your goal. - - -* [Advanced Keycodes](feature_advanced_keycodes.md) - Change layers, dual-action keys, and more. Go beyond typing simple characters. -* [Audio](feature_audio.md) - Connect a speaker to your keyboard for audio feedback, midi support, and music mode. -* [Auto Shift](feature_auto_shift.md) - Tap for the normal key, hold slightly longer for its shifted state. -* [Backlight](feature_backlight.md) - LED lighting support for your keyboard. -* [Bluetooth](feature_bluetooth.md) - BlueTooth support for your keyboard. -* [Bootmagic](feature_bootmagic.md) - Adjust the behavior of your keyboard using hotkeys. -* [Combos](feature_combo.md) - Custom actions for multiple key holds. -* [Command](feature_command.md) - Runtime version of bootmagic (Formerly known as "Magic"). -* [Debounce API](feature_debounce_type.md) - Customization of debouncing algorithms, and the ability to add more/custom debouncing. -* [DIP Switch](feature_dip_switch.md) - Toggle switches for customizing board function. -* [Dynamic Macros](feature_dynamic_macros.md) - Record and playback macros from the keyboard itself. -* [Encoders](feature_encoders.md) - Rotary encoders! -* [Grave Escape](feature_grave_esc.md) - Lets you use a single key for Esc and Grave. -* [Haptic Feedback](feature_haptic_feedback.md) - Add haptic feedback drivers to your board. -* [HD44780 LCD Display](feature_hd44780.md) - Support for LCD character displays using the HD44780 standard. -* [Key Lock](feature_key_lock.md) - Lock a key in the "down" state. -* [Layouts](feature_layouts.md) - Use one keymap with any keyboard that supports your layout. -* [Leader Key](feature_leader_key.md) - Tap the leader key followed by a sequence to trigger custom behavior. -* [LED Matrix](feature_led_matrix.md) - LED Matrix single color lights for per key lighting (Single Color, not RGB). -* [Macros](feature_macros.md) - Send multiple key presses when pressing only one physical key. -* [Mouse keys](feature_mouse_keys.md) - Control your mouse pointer from your keyboard. -* [OLED Driver](feature_oled_driver.md) - Add OLED screens to your keyboard. -* [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys) - Sticky Keys, lets you hit a key rather than holding it. -* [Pointing Device](feature_pointing_device.md) - Framework for connecting your custom pointing device to your keyboard. -* [PS2 Mouse](feature_ps2_mouse.md) - Driver for connecting a PS/2 mouse directly to your keyboard. -* [RGB Light](feature_rgblight.md) - RGB lighting for your keyboard. -* [RGB Matrix](feature_rgb_matrix.md) - RGB Matrix lights for per key lighting. -* [Space Cadet](feature_space_cadet.md) - Use your left/right shift keys to type parenthesis and brackets. -* [Split Keyboard](feature_split_keyboard.md) -* [Stenography](feature_stenography.md) - Put your keyboard into Plover mode for stenography use. -* [Swap Hands](feature_swap_hands.md) - Mirror your keyboard for one handed usage. -* [Tap Dance](feature_tap_dance.md) - Make a single key do as many things as you want. -* [Terminal](feature_terminal.md) - CLI interface to the internals of your keyboard. -* [Thermal Printer](feature_thermal_printer.md) - Connect a thermal printer to your keyboard to be able to toggle on a printed log of everything you type. -* [Unicode](feature_unicode.md) - Unicode input support. -* [Userspace](feature_userspace.md) - Share code between different keymaps and keyboards. -* [Velocikey](feature_velocikey.md) - Allows changes in RGB animation speed based on WPM/Typing speed. diff --git a/docs/flashing.md b/docs/flashing.md index 98841c1aacd..7804a6bad8d 100644 --- a/docs/flashing.md +++ b/docs/flashing.md @@ -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 the 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). To run this process manually, compile with the target `check-size`, eg `make planck/rev4:default:check-size`. +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 -km +``` +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) -* [Atmel's Flip](http://www.microchip.com/developmenttools/productdetails.aspx?partno=flip) (not recommended) +* [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 ::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 ::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 come 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 ::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. +## 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) diff --git a/docs/fr-fr/README.md b/docs/fr-fr/README.md index 4527ec4b423..df4627c4929 100644 --- a/docs/fr-fr/README.md +++ b/docs/fr-fr/README.md @@ -4,16 +4,16 @@ [![Statut du build](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) [![Statut de la doc](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm) -[![Contributeurs Github](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly) -[![Forks Github](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/) +[![Contributeurs GitHub](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly) +[![Forks GitHub](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/) ## 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 -Si vous souhaitez contribuer à une disposition de clavier (keymap), ou à des fonctionnalités de QMK alors le plus simple est de [forker le dépôt avec Github](https://github.com/qmk/qmk_firmware#fork-destination-box) puis cloner le dépôt localement pour y faire des changements. Vous pourrez pousser vos changements sur github puis ouvrir un [Pull Request](https://github.com/qmk/qmk_firmware/pulls) depuis votre fork Github. +Si vous souhaitez contribuer à une disposition de clavier (keymap), ou à des fonctionnalités de QMK alors le plus simple est de [forker le dépôt avec GitHub](https://github.com/qmk/qmk_firmware#fork-destination-box) puis cloner le dépôt localement pour y faire des changements. Vous pourrez pousser vos changements sur GitHub puis ouvrir un [Pull Request](https://github.com/qmk/qmk_firmware/pulls) depuis votre fork GitHub. Sinon, vous pouvez aussi le télécharger directement en ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), ou le cloner avec git en ssh (`git@github.com:qmk/qmk_firmware.git`), ou https (`https://github.com/qmk/qmk_firmware.git`). @@ -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). diff --git a/docs/fr-fr/_summary.md b/docs/fr-fr/_summary.md index 38e3abe7c7d..25a593b2ec2 100644 --- a/docs/fr-fr/_summary.md +++ b/docs/fr-fr/_summary.md @@ -81,7 +81,7 @@ * [Macros](fr-fr/feature_macros.md) * [Boutons de souris](fr-fr/feature_mouse_keys.md) * [Pilotes / Drivers OLED](fr-fr/feature_oled_driver.md) - * [Touche one-shot](fr-fr/feature_advanced_keycodes.md#one-shot-keys) + * [Touche one-shot](fr-fr/one_shot_keys.md) * [Périphériques de pointage](fr-fr/feature_pointing_device.md) * [Souris PS/2](fr-fr/feature_ps2_mouse.md) * [Éclairage RGB](fr-fr/feature_rgblight.md) @@ -101,7 +101,8 @@ * [Guide des claviers soudés à la main](fr-fr/hand_wire.md) * [Guide de flash de l’ISP](fr-fr/isp_flashing_guide.md) * [Guide du débogage ARM](fr-fr/arm_debugging.md) - * [Drivers i2c](fr-fr/i2c_driver.md) + * [Drivers I2C](fr-fr/i2c_driver.md) + * [Drivers SPI](fr-fr/spi_driver.md) * [Contrôles des GPIO](fr-fr/internals_gpio_control.md) * [Conversion en Proton C](fr-fr/proton_c_conversion.md) @@ -112,7 +113,7 @@ * Autres sujets * [Utiliser Eclipse avec QMK](fr-fr/other_eclipse.md) * [Utiliser VSCode avec QMK](fr-fr/other_vscode.md) - * [Support](fr-fr/support.md) + * [Support](fr-fr/getting_started_getting_help.md) * [Comment ajouter des traductions](fr-fr/translating.md) * À l’intérieur de QMK (En cours de documentation) diff --git a/docs/fr-fr/breaking_changes.md b/docs/fr-fr/breaking_changes.md index 53bbb2212aa..2dbb26e5a5b 100644 --- a/docs/fr-fr/breaking_changes.md +++ b/docs/fr-fr/breaking_changes.md @@ -101,7 +101,7 @@ Ceci est fait immédiatement après la fusion de la branche `future` précédent * [ ] Regroupe ChangeLog dans un fichier. * [ ] `git commit -m 'Merge point for Breaking Change'` * [ ] `git push origin future` -* Actions sur Github +* Actions sur GitHub * [ ] Crée un PR pour `future` * [ ] S'assurer que Travis ne relève aucun problème * [ ] Fusion le PR `future` diff --git a/docs/fr-fr/contributing.md b/docs/fr-fr/contributing.md index 0092d664efb..58931cf1f63 100644 --- a/docs/fr-fr/contributing.md +++ b/docs/fr-fr/contributing.md @@ -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. @@ -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: diff --git a/docs/fr-fr/faq_build.md b/docs/fr-fr/faq_build.md index 84d88afcd8b..b8d09ef7718 100644 --- a/docs/fr-fr/faq_build.md +++ b/docs/fr-fr/faq_build.md @@ -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 diff --git a/docs/fr-fr/faq_debug.md b/docs/fr-fr/faq_debug.md index 754c79921cb..344776ebb92 100644 --- a/docs/fr-fr/faq_debug.md +++ b/docs/fr-fr/faq_debug.md @@ -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. @@ -155,11 +155,3 @@ Pour le moment, l'origine du problème n'est pas comprise, mais certaines option https://github.com/tmk/tmk_keyboard/issues/266 https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778 - -## FLIP ne marche pas - -### `AtLibUsbDfu.dll` Not Found - -Supprimez le pilote actuel et réinstallez celui donné par FLIP dans le gestionnaire de périphériques. - -http://imgur.com/a/bnwzy diff --git a/docs/fr-fr/faq_keymap.md b/docs/fr-fr/faq_keymap.md index 2cbbe930829..b6e29aede8b 100644 --- a/docs/fr-fr/faq_keymap.md +++ b/docs/fr-fr/faq_keymap.md @@ -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 : - + ![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 diff --git a/docs/fr-fr/flashing.md b/docs/fr-fr/flashing.md index c380614a5de..4d6655c817c 100644 --- a/docs/fr-fr/flashing.md +++ b/docs/fr-fr/flashing.md @@ -26,7 +26,6 @@ Méthodes de flash compatibles : * [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (interface graphique recommandé) * [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` avec QMK (outil en ligne de commande recommandé) -* [Atmel's Flip](http://www.microchip.com/developmenttools/productdetails.aspx?partno=flip) (non recommandé) Ordre des actions : @@ -85,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 :  @@ -160,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 : diff --git a/docs/fr-fr/getting_started_github.md b/docs/fr-fr/getting_started_github.md index 22c6ee749ba..0f3982ea290 100644 --- a/docs/fr-fr/getting_started_github.md +++ b/docs/fr-fr/getting_started_github.md @@ -6,27 +6,33 @@ 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` dans la ligne de commande, et collez votre lien: +Ensuite, entrez `git clone --recurse-submodules ` dans la ligne de commande, et collez votre lien: ``` -user@computer:~$ git clone https://github.com/whoeveryouare/qmk_firmware.git +user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git Cloning into 'qmk_firmware'... -remote: Counting objects: 46625, done. -remote: Compressing objects: 100% (2/2), done. -remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623 -Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done. -Resolving deltas: 100% (29362/29362), done. -Checking out files: 100% (2799/2799), done. +remote: Enumerating objects: 9, done. +remote: Counting objects: 100% (9/9), done. +remote: Compressing objects: 100% (5/5), done. +remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874 +Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done. +Resolving deltas: 100% (119972/119972), done. +... +Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b' +Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486' +Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780' +Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d' +Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2' ``` Vous avez maintenant votre fork QMK sur votre machine locale, vous pouvez ajouter votre keymap, la compiler et la flasher sur votre board. Une fois heureux avec vos changements, vous pouvez les ajouter, commit, et pousser vers votre fork comme suit: @@ -50,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//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! diff --git a/docs/fr-fr/getting_started_introduction.md b/docs/fr-fr/getting_started_introduction.md index a7f0ff96af4..b2711a1671e 100644 --- a/docs/fr-fr/getting_started_introduction.md +++ b/docs/fr-fr/getting_started_introduction.md @@ -4,7 +4,7 @@ Le but de cette page est d'expliquer les informations de base qui vous serons n ## Structure de base de QMK -QMK est un fork du projet [tmk_keyboard](https://github.com/tmk/tmk_keyboard) créé par [Jun Wako](https://github.com/tmk). Le code originel de TMK, avec quelques modifications, se trouve dans le dossier `tmk`. Les additions que QMK amène au projet se trouvent dans le dossier `quantum`. Les projets de clavier se trouvent dans les dossiers `handwired` et `keyboard`. +QMK est un fork du projet [tmk_keyboard](https://github.com/tmk/tmk_keyboard) créé par [Jun Wako](https://github.com/tmk). Le code originel de TMK, avec quelques modifications, se trouve dans le dossier `tmk_core`. Les additions que QMK amène au projet se trouvent dans le dossier `quantum`. Les projets de clavier se trouvent dans les dossiers `handwired` et `keyboard`. ### Structure du Userspace diff --git a/docs/fr-fr/newbs.md b/docs/fr-fr/newbs.md index 13b06b429e3..6d848b11f8f 100644 --- a/docs/fr-fr/newbs.md +++ b/docs/fr-fr/newbs.md @@ -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 diff --git a/docs/fr-fr/newbs_best_practices.md b/docs/fr-fr/newbs_best_practices.md index 14910131475..ec68a5e3e52 100644 --- a/docs/fr-fr/newbs_best_practices.md +++ b/docs/fr-fr/newbs_best_practices.md @@ -44,7 +44,7 @@ git pull upstream master git push origin master ``` -Cela vous change la branche courante en master, synchronise les données de références du dépôt QMK vers votre ordinateur. La commande pull tire les données de références vers votre branche courante puis les y téleverse. La commande push permet de pousser la branche courante (master) vers votre fork github. +Cela vous change la branche courante en master, synchronise les données de références du dépôt QMK vers votre ordinateur. La commande pull tire les données de références vers votre branche courante puis les y téleverse. La commande push permet de pousser la branche courante (master) vers votre fork GitHub. ### Faire des changements diff --git a/docs/fr-fr/newbs_building_firmware_configurator.md b/docs/fr-fr/newbs_building_firmware_configurator.md index 577e5c80e9d..d06242f3927 100644 --- a/docs/fr-fr/newbs_building_firmware_configurator.md +++ b/docs/fr-fr/newbs_building_firmware_configurator.md @@ -4,7 +4,7 @@ Le [Configurateur de QMK](https://config.qmk.fm) est une interface graphique en ?> **S'il vous plaît, suivez les étapes suivantes dans l'ordre.** -Regardez le [Tutoriel vidéo](https://youtu.be/tx54jkRC9ZY) +Regardez le [Tutoriel vidéo](https://youtu.be/tx54jkRC9ZY)https://www.youtube.com/watch?v=-imgglzDMdY) Le configurateur de QMK fonctionne mieux avec Chrome et Firefox. diff --git a/docs/fr-fr/newbs_getting_started.md b/docs/fr-fr/newbs_getting_started.md index 8a8029fd145..1a5740185ca 100644 --- a/docs/fr-fr/newbs_getting_started.md +++ b/docs/fr-fr/newbs_getting_started.md @@ -41,7 +41,7 @@ Nous avons essayé de rendre QMK aussi simple que possible à configurer. Vous a Vous devez installer MSYS2 et Git. -* Suivez les instructions d'installation sur la [page de MSYS2](http://www.msys2.org). +* Suivez les instructions d'installation sur la [page de MSYS2](https://www.msys2.org). * Fermez tous les terminaux MSYS2 éventuellement ouverts et ouvrez un nouveau terminal MSYS2 MinGW 64-bit. * Installez Git en lançant la commande: `pacman -S git`. diff --git a/docs/fr-fr/newbs_testing_debugging.md b/docs/fr-fr/newbs_testing_debugging.md index 680d7644ed2..85a7fb9f13a 100644 --- a/docs/fr-fr/newbs_testing_debugging.md +++ b/docs/fr-fr/newbs_testing_debugging.md @@ -11,8 +11,8 @@ Note: ces programmes ne sont ni fournis ni approuvés par QMK. * [QMK Configurator](https://config.qmk.fm/#/test/) (Web) * [Switch Hitter](https://web.archive.org/web/20190413233743/https://elitekeyboards.com/switchhitter.php) (Windows seulement) * [Keyboard Viewer](https://www.imore.com/how-use-keyboard-viewer-your-mac) (Mac seulement) -* [Keyboard Tester](http://www.keyboardtester.com) (Web) -* [Keyboard Checker](http://keyboardchecker.com) (Web) +* [Keyboard Tester](https://www.keyboardtester.com) (Web) +* [Keyboard Checker](https://keyboardchecker.com) (Web) ## Débuguer @@ -42,7 +42,9 @@ Vous préférez une solution basée sur le terminal? [hid_listen](https://www.pj Parfois, il est utile d'afficher des messages de débugage depuis votre [code custom](custom_quantum_functions.md). Le faire est assez simple. Commencez par ajouter `print.h` au début de votre fichier: - #include +```c +#include "print.h" +``` Une fois fait, vous pouvez utiliser les fonctions print suivantes: diff --git a/docs/fuse.txt b/docs/fuse.txt index 99ddd2d1868..ceb588be3d2 100644 --- a/docs/fuse.txt +++ b/docs/fuse.txt @@ -47,4 +47,3 @@ This configuration is from usbasploader's Makefile. # | | +----- LB 2..1 (No memory lock features enabled) # | +--------- BLB0 2..1 (No restrictions for SPM or LPM accessing the Application section) # +--------------- BLB1 2..1 (No restrictions for SPM or LPM accessing the Boot Loader section) - diff --git a/docs/getting_started_build_tools.md b/docs/getting_started_build_tools.md deleted file mode 100644 index 2721a9a0313..00000000000 --- a/docs/getting_started_build_tools.md +++ /dev/null @@ -1,140 +0,0 @@ -# Installing Build Tools - -This page describes setting up the build environment for QMK. These instructions cover AVR processors (such as the atmega32u4). - - - -**Note:** If this is your first time here, check out the [Complete Newbs Guide](newbs.md) page. - -Before continuing, double check that your submodules (third-party libraries) are up to date by running `make git-submodule`. - -## Linux - -To ensure you are always up to date, you can just run `sudo util/qmk_install.sh`. That should always install all the dependencies needed. **This will run `apt-get upgrade`.** - -You can also install things manually, but this documentation might not be always up to date with all requirements. - -The current requirements are the following, but not all might be needed depending on what you do. Also note that some systems might not have all the dependencies available as packages, or they might be named differently. - -``` -build-essential -gcc -unzip -wget -zip -gcc-avr -binutils-avr -avr-libc -dfu-programmer -dfu-util -gcc-arm-none-eabi -binutils-arm-none-eabi -libnewlib-arm-none-eabi -git -``` - -Install the dependencies with your favorite package manager. - -Debian / Ubuntu example: - - sudo apt-get update - sudo apt-get install gcc unzip wget zip gcc-avr binutils-avr avr-libc dfu-programmer dfu-util gcc-arm-none-eabi binutils-arm-none-eabi libnewlib-arm-none-eabi - -Fedora / Red Hat example: - - sudo dnf install gcc unzip wget zip dfu-util dfu-programmer avr-gcc avr-libc binutils-avr32-linux-gnu arm-none-eabi-gcc-cs arm-none-eabi-binutils-cs arm-none-eabi-newlib - -Arch / Manjaro example: - - pacman -S base-devel gcc unzip wget zip avr-gcc avr-binutils avr-libc dfu-util arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib git dfu-programmer dfu-util - -## Nix - -If you're on [NixOS](https://nixos.org/), or have Nix installed on Linux or macOS, run `nix-shell` from the repository root to get a build environment. - -By default, this will download compilers for both AVR and ARM. If you don't need both, disable the `avr` or `arm` arguments, e.g.: - - nix-shell --arg arm false - -## macOS -If you're using [homebrew,](http://brew.sh/) you can use the following commands: - - brew tap osx-cross/avr - brew tap PX4/homebrew-px4 - brew update - brew install avr-gcc@8 - brew link --force avr-gcc@8 - brew install dfu-programmer - brew install dfu-util - brew install gcc-arm-none-eabi - brew install avrdude - -This is the recommended method. If you don't have homebrew, [install it!](http://brew.sh/) It's very much worth it for anyone who works in the command line. Note that the `make` and `make install` portion during the homebrew installation of `avr-gcc@8` can take over 20 minutes and exhibit high CPU usage. - -## Windows with msys2 (recommended) - -The best environment to use, for Windows Vista through any later version (tested on 7 and 10), is [msys2](http://www.msys2.org). - -* Install msys2 by downloading it and following the instructions here: http://www.msys2.org -* Open the ``MSYS2 MingGW 64-bit`` shortcut -* Navigate to your QMK repository. For example, if it's in the root of your c drive: - * `$ cd /c/qmk_firmware` -* Run `util/qmk_install.sh` and follow the prompts - -## Windows 10 (deprecated) -These are the old instructions for Windows 10. We recommend you use [MSYS2 as outlined above](#windows-with-msys2-recommended). - -### Creators Update -If you have Windows 10 with Creators Update or later, you can build and flash the firmware directly. Before the Creators Update, only building was possible. If you don't have it yet or if are unsure, follow [these instructions](https://support.microsoft.com/en-us/instantanswers/d4efb316-79f0-1aa1-9ef3-dcada78f3fa0/get-the-windows-10-creators-update). - -### Windows Subsystem for Linux -In addition to the Creators Update, you need Windows 10 Subystem for Linux, so install it following [these instructions](http://www.howtogeek.com/249966/how-to-install-and-use-the-linux-bash-shell-on-windows-10/). If you already have the Windows 10 Subsystem for Linux from the Anniversary update it's recommended that you [upgrade](https://betanews.com/2017/04/14/upgrade-windows-subsystem-for-linux/) it to 16.04LTS, because some keyboards don't compile with the toolchains included in 14.04LTS. Note that you need to know what your are doing if you chose the `sudo do-release-upgrade` method. - -### Git -If you already have cloned the repository on your Windows file system you can ignore this section. - -You will need to clone the repository to your Windows file system using the normal Git for Windows and **not** the WSL Git. So if you haven't installed Git before, [download](https://git-scm.com/download/win) and install it. Then [set it up](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup), it's important that you setup the e-mail and user name, especially if you are planning to contribute. - -Once Git is installed, open the Git Bash command and change the directory to where you want to clone QMK; note that you have to use forward slashes, and that your c drive is accessed like this `/c/path/to/where/you/want/to/go`. Then run `git clone --recurse-submodules https://github.com/qmk/qmk_firmware`, this will create a new folder `qmk_firmware` as a subfolder of the current one. - -### Toolchain Setup -The Toolchain setup is done through the Windows Subsystem for Linux, and the process is fully automated. If you want to do everything manually, there are no other instructions than the scripts themselves, but you can always open issues and ask for more information. - -1. Open "Bash On Ubuntu On Windows" from the start menu. -2. Go to the directory where you cloned `qmk_firmware`. Note that the paths start with `/mnt/` in the WSL, so you have to write for example `cd /mnt/c/path/to/qmk_firmware`. -3. Run `util/wsl_install.sh` and follow the on-screen instructions. -4. Close the Bash command window, and re-open it. -5. You are ready to compile and flash the firmware! - -### Some Important Things to Keep in Mind -* You can run `util/wsl_install.sh` again to get all the newest updates. -* Your QMK repository need to be on a Windows file system path, since WSL can't run executables outside it. -* The WSL Git is **not** compatible with the Windows Git, so use the Windows Git Bash or a windows Git GUI for all Git operations -* You can edit files either inside WSL or normally using Windows, but note that if you edit makefiles or shell scripts, make sure you are using an editor that saves the files with Unix line endings. Otherwise the compilation might not work. - -## Docker - -If this is a bit complex for you, Docker might be the turnkey solution you need. After installing [Docker CE](https://docs.docker.com/install/#supported-platforms), run the following command from the `qmk_firmware` directory to build a keyboard/keymap: -```bash -util/docker_build.sh keyboard:keymap -# For example: util/docker_build.sh ergodox_ez:steno -``` -This will compile the desired keyboard/keymap and leave the resulting `.hex` or `.bin` file in the QMK directory for you to flash. If `:keymap` is omitted, the `default` keymap is used. Note that the parameter format is the same as when building with `make`. - -You can also start the script without any parameters, in which case it will ask you to input the build parameters one by one, which you may find easier to use: -```bash -util/docker_build.sh -# Reads parameters as input (leave blank for defaults) -``` - -There is also support for building _and_ flashing the keyboard straight from Docker by specifying the `target` as well: -```bash -util/docker_build.sh keyboard:keymap:target -# For example: util/docker_build.sh planck/rev6:default:flash -``` -If you're on Linux, this should work out of the box. On Windows and macOS, it requires [Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/) to be running. This is tedious to set up, so it's not recommended; use [QMK Toolbox](https://github.com/qmk/qmk_toolbox) instead. - -!> Docker for Windows requires [Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v) to be enabled. This means that it cannot work on versions of Windows which don't have Hyper-V, such as Windows 7, Windows 8 and **Windows 10 Home**. - -## Vagrant -If you have any problems building the firmware, you can try using a tool called Vagrant. It will set up a virtual computer with a known configuration that's ready-to-go for firmware building. OLKB does NOT host the files for this virtual computer. Details on how to set up Vagrant are in the [vagrant guide](getting_started_vagrant.md). diff --git a/docs/getting_started_docker.md b/docs/getting_started_docker.md new file mode 100644 index 00000000000..f9c3b366a4f --- /dev/null +++ b/docs/getting_started_docker.md @@ -0,0 +1,55 @@ +# Docker Quick Start + +This project includes a Docker workflow that will allow you to build a new firmware for your keyboard very easily without major changes to your primary operating system. This also ensures that when you clone the project and perform a build, you have the exact same environment as anyone else and the QMK build infrastructure. This makes it much easier for people to help you troubleshoot any issues you encounter. + +## Requirements + +The main prerequisite is a working `docker` or `podman` install. +* [Docker CE](https://docs.docker.com/install/#supported-platforms) +* [Podman](https://podman.io/getting-started/installation) + +## Usage + +Acquire a local copy of the QMK's repository (including submodules): + +```bash +git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git +cd qmk_firmware +``` + +Run the following command to build a keymap: +```bash +util/docker_build.sh : +# For example: util/docker_build.sh planck/rev6:default +``` + +This will compile the desired keyboard/keymap and leave the resulting `.hex` or `.bin` file in the QMK directory for you to flash. If `:keymap` is omitted, all keymaps are used. Note that the parameter format is the same as when building with `make`. + +There is also support for building _and_ flashing the keyboard straight from Docker by specifying the `target` as well: + +```bash +util/docker_build.sh keyboard:keymap:target +# For example: util/docker_build.sh planck/rev6:default:flash +``` + +You can also start the script without any parameters, in which case it will ask you to input the build parameters one by one, which you may find easier to use: + +```bash +util/docker_build.sh +# Reads parameters as input (leave blank for all keyboards/keymaps) +``` + +You can manually set which container runtime you want to use by setting the `RUNTIME` environment variable to it's name or path. +By default docker or podman are automatically detected and docker is preferred over podman. + +```bash +RUNTIME="podman" util/docker_build.sh keyboard:keymap:target +``` + +## FAQ + +### Why can't I flash on Windows/macOS + +On Windows and macOS, it requires [Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/) to be running. This is tedious to set up, so it's not recommended; use [QMK Toolbox](https://github.com/qmk/qmk_toolbox) instead. + +!> Docker for Windows requires [Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v) to be enabled. This means that it cannot work on versions of Windows which don't have Hyper-V, such as Windows 7, Windows 8 and **Windows 10 Home**. diff --git a/docs/getting_started_getting_help.md b/docs/getting_started_getting_help.md deleted file mode 100644 index 9788ad38e8c..00000000000 --- a/docs/getting_started_getting_help.md +++ /dev/null @@ -1,15 +0,0 @@ -# Getting Help - -There are a lot of resources for getting help with QMK. - -## Realtime Chat - -You can find QMK developers and users on our main [Discord server](https://discord.gg/Uq7gcHh). There are specific channels in the server for chatting about the firmware, Toolbox, hardware, and configurator. - -## OLKB Subreddit - -The official QMK forum is [/r/olkb](https://reddit.com/r/olkb) on [reddit.com](https://reddit.com). - -## Github Issues - -You can open an [issue on GitHub](https://github.com/qmk/qmk_firmware/issues). This is especially handy when your issue will require long-term discussion or debugging. diff --git a/docs/getting_started_github.md b/docs/getting_started_github.md index 629f4ece26a..e3720b88696 100644 --- a/docs/getting_started_github.md +++ b/docs/getting_started_github.md @@ -1,32 +1,38 @@ -# How to Use Github with QMK +# How to Use GitHub with QMK -Github can be a little tricky to those that aren't familiar with it - this guide will walk through each step of forking, cloning, and submitting a pull request with QMK. +GitHub can be a little tricky to those that aren't familiar with it - this guide will walk through each step of forking, cloning, and submitting a pull request with QMK. ?> This guide assumes you're somewhat comfortable with running things at the command line, and have git installed on your system. -Start on the [QMK Github page](https://github.com/qmk/qmk_firmware), and you'll see a button in the upper right that says "Fork": +Start on the [QMK GitHub page](https://github.com/qmk/qmk_firmware), and you'll see a button in the upper right that says "Fork": -![Fork on Github](http://i.imgur.com/8Toomz4.jpg) +![Fork on GitHub](https://i.imgur.com/8Toomz4.jpg) If you're a part of an organization, you'll need to choose which account to fork it to. In most circumstances, you'll want to fork it to your personal account. Once your fork is completed (sometimes this takes a little while), click the "Clone or Download" button: -![Download from Github](http://i.imgur.com/N1NYcSz.jpg) +![Download from GitHub](https://i.imgur.com/N1NYcSz.jpg) And be sure to select "HTTPS", and select the link and copy it: -![HTTPS link](http://i.imgur.com/eGO0ohO.jpg) +![HTTPS link](https://i.imgur.com/eGO0ohO.jpg) -From here, enter `git clone ` into the command line, and then paste your link: +From here, enter `git clone --recurse-submodules ` into the command line, and then paste your link: ``` user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git Cloning into 'qmk_firmware'... -remote: Counting objects: 46625, done. -remote: Compressing objects: 100% (2/2), done. -remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623 -Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done. -Resolving deltas: 100% (29362/29362), done. -Checking out files: 100% (2799/2799), done. +remote: Enumerating objects: 9, done. +remote: Counting objects: 100% (9/9), done. +remote: Compressing objects: 100% (5/5), done. +remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874 +Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done. +Resolving deltas: 100% (119972/119972), done. +... +Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b' +Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486' +Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780' +Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d' +Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2' ``` You now have your QMK fork on your local machine, and you can add your keymap, compile it and flash it to your board. Once you're happy with your changes, you can add, commit, and push them to your fork like this: @@ -48,12 +54,12 @@ To https://github.com/whoeveryouare/qmk_firmware.git + 20043e64...7da94ac5 master -> master ``` -Your changes now exist on your fork on Github - if you go back there (`https://github.com//qmk_firmware`), you can create a "New Pull Request" by clicking this button: +Your changes now exist on your fork on GitHub - if you go back there (`https://github.com//qmk_firmware`), you can create a "New Pull Request" by clicking this button: -![New Pull Request](http://i.imgur.com/DxMHpJ8.jpg) +![New Pull Request](https://i.imgur.com/DxMHpJ8.jpg) Here you'll be able to see exactly what you've committed - if it all looks good, you can finalize it by clicking "Create Pull Request": -![Create Pull Request](http://i.imgur.com/Ojydlaj.jpg) +![Create Pull Request](https://i.imgur.com/Ojydlaj.jpg) After submitting, we may talk to you about your changes, ask that you make changes, and eventually accept it! Thanks for contributing to QMK :) diff --git a/docs/getting_started_make_guide.md b/docs/getting_started_make_guide.md index bf8d472d0e7..7198576e3ad 100644 --- a/docs/getting_started_make_guide.md +++ b/docs/getting_started_make_guide.md @@ -14,16 +14,32 @@ The full syntax of the `make` command is `::`, The `` means the following * If no target is given, then it's the same as `all` below * `all` compiles as many keyboard/revision/keymap combinations as specified. For example, `make planck/rev4:default` will generate a single .hex, while `make planck/rev4:all` will generate a hex for every keymap available to the planck. -* `flash`, `dfu`, `teensy`, `avrdude`, `dfu-util`, or `bootloadHID` compile and upload the firmware to the keyboard. If the compilation fails, then nothing will be uploaded. The programmer to use depends on the keyboard. For most keyboards it's `dfu`, but for ChibiOS keyboards you should use `dfu-util`, and `teensy` for standard Teensys. To find out which command you should use for your keyboard, check the keyboard specific readme. - * **Note**: some operating systems need root access for these commands to work, so in that case you need to run for example `sudo make planck/rev4:default:flash`. +* `flash`, `dfu`, `teensy`, `avrdude`, `dfu-util`, or `bootloadHID` compile and upload the firmware to the keyboard. If the compilation fails, then nothing will be uploaded. The programmer to use depends on the keyboard. For most keyboards it's `dfu`, but for ChibiOS keyboards you should use `dfu-util`, and `teensy` for standard Teensys. To find out which command you should use for your keyboard, check the keyboard specific readme. + Visit the [Flashing Firmware](flashing.md) guide for more details of the available bootloaders. + * **Note**: some operating systems need privileged access for these commands to work. This means that you may need to setup [`udev rules`](faq_build.md#linux-udev-rules) to access these without root access, or to run the command with root access (`sudo make planck/rev4:default:flash`). * `clean`, cleans the build output folders to make sure that everything is built from scratch. Run this before normal compilation if you have some unexplainable problems. +* `distclean` removes .hex files and .bin files. + +The following targets are for developers: + +* `show-path` shows the path of the source and object files. +* `dump-vars` dumps the makefile variable. +* `objs-size` displays the size of individual object files. +* `show_build_options` shows the options set in 'rules.mk'. +* `check-md5` displays the md5 checksum of the generated binary file. You can also add extra options at the end of the make command line, after the target * `make COLOR=false` - turns off color output * `make SILENT=true` - turns off output besides errors/warnings * `make VERBOSE=true` - outputs all of the gcc stuff (not interesting, unless you need to debug) -* `make EXTRAFLAGS=-E` - Preprocess the code without doing any compiling (useful if you are trying to debug #define commands) +* `make VERBOSE_LD_CMD=yes` - execute the ld command with the -v option. +* `make VERBOSE_AS_CMD=yes` - execute the as command with the -v option. +* `make VERBOSE_C_CMD=` - add the -v option when compiling the specified C source file. +* `make DUMP_C_MACROS=` - dump preprocessor macros when compiling the specified C source file. +* `make DUMP_C_MACROS= > ` - dump preprocessor macros to `` when compiling the specified C source file. +* `make VERBOSE_C_INCLUDE=` - dumps the file names to be included when compiling the specified C source file. +* `make VERBOSE_C_INCLUDE= 2> ` - dumps the file names to be included to `` when compiling the specified C source file. The make command itself also has some additional options, type `make --help` for more information. The most useful is probably `-jx`, which specifies that you want to compile using more than one CPU, the `x` represents the number of CPUs that you want to use. Setting that can greatly reduce the compile times, especially if you are compiling many keyboards/keymaps. I usually set it to one less than the number of CPUs that I have, so that I have some left for doing other things while it's compiling. Note that not all operating systems and make versions supports that option. @@ -101,18 +117,10 @@ This allows you to send Unicode characters by inputting a mnemonic corresponding For further details, as well as limitations, see the [Unicode page](feature_unicode.md). -`BLUETOOTH_ENABLE` - -This allows you to interface with a Bluefruit EZ-key to send keycodes wirelessly. It uses the D2 and D3 pins. - `AUDIO_ENABLE` This allows you output audio on the C6 pin (needs abstracting). See the [audio page](feature_audio.md) for more information. -`FAUXCLICKY_ENABLE` - -Uses buzzer to emulate clicky switches. A cheap imitation of the Cherry blue switches. By default, uses the C6 pin, same as `AUDIO_ENABLE`. - `VARIABLE_TRACE` Use this to debug changes to variable values, see the [tracing variables](unit_testing.md#tracing-variables) section of the Unit Testing page for more information. @@ -135,7 +143,7 @@ As there is no standard split communication driver for ARM-based split keyboards `CUSTOM_MATRIX` -Lets you replace the default matrix scanning routine with your own code. You will need to provide your own implementations of matrix_init() and matrix_scan(). +Lets you replace the default matrix scanning routine with your own code. For further details, see the [Custom Matrix page](custom_matrix.md). `DEBOUNCE_TYPE` diff --git a/docs/getting_started_vagrant.md b/docs/getting_started_vagrant.md index da26682d7f3..b71f8908b9c 100644 --- a/docs/getting_started_vagrant.md +++ b/docs/getting_started_vagrant.md @@ -4,11 +4,11 @@ This project includes a `Vagrantfile` that will allow you to build a new firmwar ## Requirements -Using the `Vagrantfile` in this repository requires you have [Vagrant](http://www.vagrantup.com/) as well as a supported provider installed: +Using the `Vagrantfile` in this repository requires you have [Vagrant](https://www.vagrantup.com/) as well as a supported provider installed: * [VirtualBox](https://www.virtualbox.org/) (Version at least 5.0.12) * Sold as 'the most accessible platform to use Vagrant' -* [VMware Workstation](https://www.vmware.com/products/workstation) and [Vagrant VMware plugin](http://www.vagrantup.com/vmware) +* [VMware Workstation](https://www.vmware.com/products/workstation) and [Vagrant VMware plugin](https://www.vagrantup.com/vmware) * The (paid) VMware plugin requires a licensed copy of VMware Workstation/Fusion * [Docker](https://www.docker.com/) @@ -20,7 +20,6 @@ The "easy" way to flash the firmware is using a tool from your host OS: * [QMK Toolbox](https://github.com/qmk/qmk_toolbox) (recommended) * [Teensy Loader](https://www.pjrc.com/teensy/loader.html) -* [Atmel FLIP](http://www.atmel.com/tools/flip.aspx) If you want to program via the command line you can uncomment the ['modifyvm'] lines in the Vagrantfile to enable the USB passthrough into Linux and then program using the command line tools like dfu-util/dfu-programmer or you can install the Teensy CLI version. diff --git a/docs/hand_wire.md b/docs/hand_wire.md index 0e750f160a9..05d3af340b5 100644 --- a/docs/hand_wire.md +++ b/docs/hand_wire.md @@ -1,114 +1,5 @@ # Hand-Wiring Guide -## Preamble: How a Keyboard Matrix Works (and why we need diodes) - -The collapsible section below covers why keyboards are wired the way they are, as outlined in this guide. It isn't required reading to make your own hand wired keyboard, but provides background information. - -
- -Click for details - -Without a matrix circuit each switch would require its own wire directly to the controller. - -Simply put, when the circuit is arranged in rows and columns, if a key is pressed, a column wire makes contact with a row wire and completes a circuit. The keyboard controller detects this closed circuit and registers it as a key press. - -The microcontroller will be setup up via the firmware to send a logical 1 to the columns, one at a time, and read from the rows, all at once - this process is called matrix scanning. The matrix is a bunch of open switches that, by default, don't allow any current to pass through - the firmware will read this as no keys being pressed. As soon as you press one key down, the logical 1 that was coming from the column the keyswitch is attached to gets passed through the switch and to the corresponding row - check out the following 2x2 example: - - Column 0 being scanned Column 1 being scanned - x x - col0 col1 col0 col1 - | | | | - row0 ---(key0)---(key1) row0 ---(key0)---(key1) - | | | | - row1 ---(key2)---(key3) row1 ---(key2)---(key3) - -The `x` represents that the column/row associated has a value of 1, or is HIGH. Here, we see that no keys are being pressed, so no rows get an `x`. For one keyswitch, keep in mind that one side of the contacts is connected to its row, and the other, its column. - -When we press `key0`, `col0` gets connected to `row0`, so the values that the firmware receives for that row is `0b01` (the `0b` here means that this is a bit value, meaning all of the following digits are bits - 0 or 1 - and represent the keys in that column). We'll use this notation to show when a keyswitch has been pressed, to show that the column and row are being connected: - - Column 0 being scanned Column 1 being scanned - x x - col0 col1 col0 col1 - | | | | - x row0 ---(-+-0)---(key1) row0 ---(-+-0)---(key1) - | | | | - row1 ---(key2)---(key3) row1 ---(key2)---(key3) - -We can now see that `row0` has an `x`, so has the value of 1. As a whole, the data the firmware receives when `key0` is pressed is - - col0: 0b01 - col1: 0b00 - │└row0 - └row1 - -A problem arises when you start pressing more than one key at a time. Looking at our matrix again, it should become pretty obvious: - - Column 0 being scanned Column 1 being scanned - x x - col0 col1 col0 col1 - | | | | - x row0 ---(-+-0)---(-+-1) x row0 ---(-+-0)---(-+-1) - | | | | - x row1 ---(key2)---(-+-3) x row1 ---(key2)---(-+-3) - - Remember that this ^ is still connected to row1 - -The data we get from that is: - - col0: 0b11 - col1: 0b11 - │└row0 - └row1 - -Which isn't accurate, since we only have 3 keys pressed down, not all 4. This behavior is called ghosting, and only happens in odd scenarios like this, but can be much more common on a bigger keyboard. The way we can get around this is by placing a diode after the keyswitch, but before it connects to its row. A diode only allows current to pass through one way, which will protect our other columns/rows from being activated in the previous example. We'll represent a dioded matrix like this; - - Column 0 being scanned Column 1 being scanned - x x - col0 col1 col0 col1 - │ │ | │ - (key0) (key1) (key0) (key1) - ! │ ! │ ! | ! │ - row0 ─────┴────────┘ │ row0 ─────┴────────┘ │ - │ │ | │ - (key2) (key3) (key2) (key3) - ! ! ! ! - row1 ─────┴────────┘ row1 ─────┴────────┘ - -In practical applications, the black line of the diode will be placed facing the row, and away from the keyswitch - the `!` in this case is the diode, where the gap represents the black line. A good way to remember this is to think of this symbol: `>|` - -Now when we press the three keys, invoking what would be a ghosting scenario: - - Column 0 being scanned Column 1 being scanned - x x - col0 col1 col0 col1 - │ │ │ │ - (┌─┤0) (┌─┤1) (┌─┤0) (┌─┤1) - ! │ ! │ ! │ ! │ - x row0 ─────┴────────┘ │ x row0 ─────┴────────┘ │ - │ │ │ │ - (key2) (┌─┘3) (key2) (┌─┘3) - ! ! ! ! - row1 ─────┴────────┘ x row1 ─────┴────────┘ - -Things act as they should! Which will get us the following data: - - col0: 0b01 - col1: 0b11 - │└row0 - └row1 - -The firmware can then use this correct data to detect what it should do, and eventually, what signals it needs to send to the OS. - -Further reading: -- [Wikipedia article](https://en.wikipedia.org/wiki/Keyboard_matrix_circuit) -- [Deskthority article](https://deskthority.net/wiki/Keyboard_matrix) -- [Keyboard Matrix Help by Dave Dribin (2000)](https://www.dribin.org/dave/keyboard/one_html/) -- [How Key Matrices Works by PCBheaven](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/) (animated examples) -- [How keyboards work - QMK documentation](how_keyboards_work.md) - -
- - ## Parts list You will need: (where *x* is the number of keys on your planned keyboard) @@ -141,29 +32,29 @@ Start by installing the switches and stabilisers in the plate. Depending on the If you are following a pre-existing handwire guide (e.g. for the keyboards in the [handwire firmware section](https://github.com/qmk/qmk_firmware/tree/master/keyboards/handwired) you can skip this step, just ensure you wire the matrix as described. -What you want to achieve is one leg from each switch being attached to the corresponding switches next to it (rows) and the other leg being attached to the switches above and below it (columns) and a diode to one of the legs, mosy commonly this will be the leg attached to the rows, and the diode will face away from it (Column to Row) i.e. with the wire furthest from the black line on the diode connected to the switch (as current will only travel in one direction through a diode) +What you want to achieve is one leg from each switch being attached to the corresponding switches next to it (rows) and the other leg being attached to the switches above and below it (columns) and a diode to one of the legs, mosy commonly this will be the leg attached to the rows, and the diode will face away from it (Column to Row) i.e. with the wire furthest from the black line on the diode connected to the switch (as current will only travel in one direction through a diode). It is fairly simple to plan for an ortholinear keyboard (like a Planck). -![Example planck matrix](https://i.imgur.com/FRShcLD.png) +![Example Planck matrix](https://i.imgur.com/FRShcLD.png) Image from [RoastPotatoes' "How to hand wire a Planck"](https://blog.roastpotatoes.co/guide/2015/11/04/how-to-handwire-a-planck/) -But the larger and more complicated your keyboard, the more complex the matrix. [Keyboard Firmware Builder](https://kbfirmware.com/) can help you plan your matrix layout (shown here with a basic fullsize ISO keyboard imported from [Keyboard Layout Editor](http://www.keyboard-layout-editor.com). +But the larger and more complicated your keyboard, the more complex the matrix. [Keyboard Firmware Builder](https://kbfirmware.com/) can help you plan your matrix layout (shown here with a basic fullsize ISO keyboard imported from [Keyboard Layout Editor](https://www.keyboard-layout-editor.com). ![Example ISO matrix](https://i.imgur.com/UlJ4ZDP.png) - Bear in mind that the number of rows plus the number of columns can not exceed the number of I/O pins on your controller. So the fullsize matrix shown above would be possible on a Proton C or Teensy++, but not on a regular Teensy or Pro Micro +Bear in mind that the number of rows plus the number of columns can not exceed the number of I/O pins on your controller. So the fullsize matrix shown above would be possible on a Proton C or Teensy++, but not on a regular Teensy or Pro Micro. -#### Common Microcontroller Boards +### Common Microcontroller Boards | Board | Controller | # I/O | Pinout | | :------------ |:-------------:| ------:| ------ | -| Pro Micro* | ATmega32u4 | 20 | [link](https://learn.sparkfun.com/tutorials/pro-micro--fio-v3-hookup-guide/hardware-overview-pro-micro#Teensy++_2.0) | +| Pro Micro* | ATmega32u4 | 20 | [link](https://learn.sparkfun.com/tutorials/pro-micro--fio-v3-hookup-guide/hardware-overview-pro-micro#Teensy++_2.0) | | Teensy 2.0 | ATmega32u4 | 25 | [link](https://www.pjrc.com/teensy/pinout.html) | | [QMK Proton C](https://qmk.fm/proton-c/) | STM32F303xC | 36 | [link 1](https://i.imgur.com/RhtrAlc.png), [2](https://deskthority.net/wiki/QMK_Proton_C) | | Teensy++ 2.0 | AT90USB1286 | 46 | [link](https://www.pjrc.com/teensy/pinout.html#Teensy_2.0) | -*Elite C is essentially the same as a pro micro with a USB-C instead of Micro-USB +*Elite C is essentially the same as a Pro Micro with a USB-C instead of Micro-USB There are also a number of boards designed specifically for handwiring that mount directly to a small number of switches and offer pinouts for the rest. Though these are generally more expensive and may be more difficult to get hold of. @@ -185,9 +76,9 @@ Established materials and techniques include: | :-----------| :------- | :------ | :--- | :--- | Lengths of wire with stripped segments | [Sasha Solomon's Dactyl](https://medium.com/@sachee/building-my-first-keyboard-and-you-can-too-512c0f8a4c5f) and [Cribbit's modern hand wire](https://geekhack.org/index.php?topic=87689.0) | Neat and tidy | Some effort in stripping the wire | ![Stripped wire](https://i.imgur.com/0GNIYY0.jpg) | Short lengths of wire | [u/xicolinguada's ortho build](https://www.reddit.com/r/MechanicalKeyboards/comments/c39k4f/my_first_hand_wired_keyboard_its_not_perfect_but/) | Easier to strip the wire | More difficult to place | ![individual wire lengths](https://i.imgur.com/mBe5vkL.jpg) -| Magnet/Enamelled wire | [Brett Kosinski's handwired alpha](http://blog.b-ark.ca/Blog-2019-01-27) and [fknraiden's custom board](https://geekhack.org/index.php?topic=74223.0) | Can be directly soldered onto (insulation burns off with heat) | Appearance? | ![Magnet wire](https://i.imgur.com/b4b7KDb.jpg) +| Magnet/Enamelled wire | [fknraiden's custom board](https://geekhack.org/index.php?topic=74223.0) | Can be directly soldered onto (insulation burns off with heat) | Appearance? | ![Magnet wire](https://i.imgur.com/b4b7KDb.jpg) | Bending the legs of the diodes for the rows | [Matt3o's Brownfox](https://deskthority.net/viewtopic.php?f=7&t=6050) | Fewer solder joints required | Uninsulated | ![Bent diode legs](https://i.imgur.com/aTnG8TV.jpg) -| Using ridid wiring (e.g. brass tube) | [u/d_stilgar's invisible hardline](https://www.reddit.com/r/MechanicalKeyboards/comments/8aw5j2/invisible_hardline_keyboard_progress_update_april/) and [u/jonasfasler's first attempt](https://www.reddit.com/r/MechanicalKeyboards/comments/de1jyv/my_first_attempt_at_handwiring_a_keyboard/) | Very pretty | More difficult. No physical insulation | ![Hardline hand wire](https://i.imgur.com/CnASmPo.jpg) +| Using rigid wiring (e.g. brass tube) | [u/d_stilgar's invisible hardline](https://www.reddit.com/r/MechanicalKeyboards/comments/8aw5j2/invisible_hardline_keyboard_progress_update_april/) and [u/jonasfasler's first attempt](https://www.reddit.com/r/MechanicalKeyboards/comments/de1jyv/my_first_attempt_at_handwiring_a_keyboard/) | Very pretty | More difficult. No physical insulation | ![Hardline hand wire](https://i.imgur.com/CnASmPo.jpg) | Bare wire with insulation added after (e.g. kapton tape) | [Matt3o's 65% on his website](https://matt3o.com/hand-wiring-a-custom-keyboard/) | Easier (no wire stripping required) | Not as attractive | ![Bare wire](https://i.imgur.com/AvXZShD.jpg) | Copper tape | [ManuForm Dactyl](https://github.com/tshort/dactyl-keyboard) | Very easy | Only really works when your plate/case aligns with the bottom of your switches | ![Copper tape](https://i.imgur.com/RFyNMlL.jpg) @@ -204,7 +95,7 @@ If you are planning a split keyboard (e.g. Dactyl) each half will require a cont There are a lot of soldering guides and tips available elsewhere but here are some of the most useful and relevant for hand wiring: -To ensure a strong solder joint you want a good amount of contact between the solder and the 2 peices of metal you are connecting, a good way of doing this (though not required) is looping around pins or twisting wires together before applying solder. +To ensure a strong solder joint you want a good amount of contact between the solder and the two pieces of metal you are connecting. A good way of doing this (though not required) is looping around pins or twisting wires together before applying solder. Looped around rod Looped diode leg @@ -220,47 +111,27 @@ When you come to apply the solder, hold the soldering iron against the two surfa Don't hold the iron on the solder/joint longer than necessary. Heat will be conducted through the surfaces and can damage components (melt switch housings etc.). Also, solder contains flux, which aids in ["wetting"](https://en.m.wikipedia.org/wiki/Wetting). The longer heat is applied to the solder the more flux will evaporate meaning you may end up with a bad solder joint with peaks which, apart from looking bad, may also increase the risk of electrical shorts. -The following collapsible section describes in detail how to solder rows using the bent diode technique and columns using short lengths of wire. +#### Soldering the Diodes -
+Starting at the top-left switch, place the diode (with tweezers if you have them) on the switch so that the diode itself is vertically aligned, and the black line is facing toward you. The input lead of the diode should be touching the left contact on the switch, and the bent, output end should be facing to the right and resting on the switch there, like this: -Click for details - -## Soldering the Diodes - -Starting at the top-left switch, place the diode (with tweezers if you have them) on the switch so that the diode itself is vertically aligned, and the black line is facing toward you. The straight end of the diode should be touching the left contact on the switch, and the bent end should be facing to the right and resting on the switch there, like this: - -``` - │o - ┌┴┐ o - │ │ O - ├─┤ - └┬┘ - └───────────── -``` +![soldering-diodes-01.png](https://raw.githubusercontent.com/noroadsleft/qmk_images/master/docs/hand_wire/soldering-diodes-01.png) Letting the diode rest, grab your solder, and touch both it and the soldering iron to the left contact at the same time - the rosin in the solder should make it easy for the solder to flow over both the diode and the keyswitch contact. The diode may move a little, and if it does, carefully position it back it place by grabbing the bent end of the diode - the other end will become hot very quickly. If you find that it's moving too much, using needle-nose pliers of some sort may help to keep the diode still when soldering. The smoke that the rosin releases is harmful, so be careful not to breath it or get it in your eyes/face. -After soldering things in place, it may be helpful to blow on the joint to push the smoke away from your face, and cool the solder quicker. You should see the solder develop a matte (not shiny) surface as it solidifies. Keep in mind that it will still be very hot afterwards, and will take a couple minutes to be cool to touch. Blow on it will accelerate this process. +After soldering things in place, it may be helpful to blow on the joint to push the smoke away from your face, and cool the solder quicker. You should see the solder develop a matte (not shiny) surface as it solidifies. Keep in mind that it will still be very hot afterwards, and will take a couple minutes to be cool to touch. Blowing on it will accelerate this process. When the first diode is complete, the next one will need to be soldered to both the keyswitch, and the previous diode at the new elbow. That will look something like this: -``` - │o │o - ┌┴┐ o ┌┴┐ o - │ │ O │ │ O - ├─┤ ├─┤ - └┬┘ └┬┘ - └────────────────┴───────────── -``` +![soldering-diodes-02.png](https://raw.githubusercontent.com/noroadsleft/qmk_images/master/docs/hand_wire/soldering-diodes-02.png) After completing a row, use the wire cutters to trim the excess wire from the tops of the diodes, and from the right side on the final switch. This process will need to completed for each row you have. When all of the diodes are completely soldered, it's a good idea to quickly inspect each one to ensure that your solder joints are solid and sturdy - repairing things after this is possible, but more difficult. -## Soldering the Columns +#### Soldering the Columns You'll have some options in the next process - it's a good idea to insulate the column wires (since the diodes aren't), but if you're careful enough, you can use exposed wires for the columns - it's not recommended, though. If you're using single-cored wire, stripping the plastic off of the whole wire and feeding it back on is probably the best option, but can be difficult depending on the size and materials. You'll want to leave parts of the wire exposed where you're going to be solder it onto the keyswitch. @@ -270,9 +141,7 @@ Before beginning to solder, it helps to have your wire pre-bent (if using single If you're not using any insulation, you can try to keep the column wires elevated, and solder them near the tips of the keyswitch contacts - if the wires are sturdy enough, they won't short out to the row wiring an diodes. -
- -# Wiring up the controller +## Wiring up the controller Now that the matrix itself is complete, it's time to connect what you've done to the microcontroller board. @@ -280,15 +149,16 @@ Place the microcontroller where you want it to be located, give thought to mount Find the pinout/documentation for your microcontroller board ([links here](#common-microcontroller-boards)) and make a note of all the digital I/O pins on it (note that on some controllers, like the teensy, analogue I/O can double as digital) as these are the pins you want to connect your wires to. -
+---- -Specific instructions for the Teensy 2.0 +### Specific instructions for the Teensy 2.0 - There are some pins on the Teensy that are special, like D6 (the LED on the chip), or some of the UART, SPI, I2C, or PWM channels, but only avoid those if you're planning something in addition to a keyboard. If you're unsure about wanting to add something later, you should have enough pins in total to avoid a couple. +There are some pins on the Teensy that are special, like D6 (the LED on the chip), or some of the UART, SPI, I2C, or PWM channels, but only avoid those if you're planning something in addition to a keyboard. If you're unsure about wanting to add something later, you should have enough pins in total to avoid a couple. The pins you'll absolutely have to avoid, as with any controller, are: GND, VCC, AREF, and RST - all the others are usable and accessible in the firmware. -
+---- + Cut wires to the length of the distance from the a point on each column/row to the controller. You can solder anywhere along the row, as long as it's after the diode - soldering before the diode (on the keyswitch side) will cause that row not to work. @@ -301,150 +171,32 @@ As you solder the wires to the controller make a note of which row/column is goi As you move along, be sure that the controller is staying in place - recutting and soldering the wires is a pain! - -# Getting Some Basic Firmware Set Up +## Getting Some Basic Firmware Set Up From here, you should have a working keyboard once you program a firmware. -Simple firmware can be created easily using the [Keyboard Firmware Builder](https://kbfirmware.com/) website. Recreate your layout using [Keyboard Layout Editor](http://www.keyboard-layout-editor.com), import it and recreate the matrix (if not already done as part of [planning the matrix](#planning-the-matrix). +Simple firmware can be created easily using the [Keyboard Firmware Builder](https://kbfirmware.com/) website. Recreate your layout using [Keyboard Layout Editor](https://www.keyboard-layout-editor.com), import it and recreate the matrix (if not already done as part of [planning the matrix](#planning-the-matrix). -Go through the rest of the tabs, assigning keys until you get to the last one where you can compile and download your firmware. The .hex file can be flashed straight onto your keyboard, and the .zip of source files can be modified for advanced functionality and compiled locally using the method described in the collapsable section below, or using the more comprehensive [getting started guide.](newbs_getting_started) +Go through the rest of the tabs, assigning keys until you get to the last one where you can compile and download your firmware. The .hex file can be flashed straight onto your keyboard, and the .zip of source files can be modified for advanced functionality and compiled locally using the method described in [Building Your First Firmware](newbs_building_firmware?id=build-your-firmware). +The source given by Keyboard Firmware Builder is QMK, but is based on a version of QMK from early 2017. To compile the code from your .zip file in a modern version of QMK Firmware, you'll need to open the .zip and follow these instructions: -
- -Creating and compiling your firmware locally (command line method) - -To start out, download [the firmware](https://github.com/qmk/qmk_firmware/) - We'll be doing a lot from the Terminal/command prompt, so get that open, along with a decent text editor like [Sublime Text](http://www.sublimetext.com/) (paid) or [Visual Studio Code](https://code.visualstudio.com) (free). - -The first thing we're going to do is create a new keyboard. In your terminal, run this command, which will ask you some questions and generate a basic keyboard project: - -``` -./util/new_keyboard.sh -``` - -You'll want to navigate to the `keyboards//` folder by typing, like the print-out from the script specifies: - -``` -cd keyboards/ -``` - -### `config.h` - -The first thing you're going to want to modify is the `config.h` file. Find `MATRIX_ROWS` and `MATRIX_COLS` and change their definitions to match the dimensions of your keyboard's matrix. - -Farther down are `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`. Change their definitions to match how you wired up your matrix (looking from the top of the keyboard, the rows run top-to-bottom and the columns run left-to-right). Likewise, change the definition of `UNUSED_PINS` to match the pins you did not use (this will save power). - -### `.h` - -The next file you'll want to look at is `.h`. You're going to want to rewrite the `LAYOUT` definition - the format and syntax here is extremely important, so pay attention to how things are setup. The first half of the definition are considered the arguments - this is the format that you'll be following in your keymap later on, so you'll want to have as many k*xy* variables here as you do keys. The second half is the part that the firmware actually looks at, and will contain gaps depending on how you wired your matrix. - -We'll dive into how this will work with the following example. Say we have a keyboard like this: - -``` - ┌───┬───┬───┐ - │ │ │ │ - ├───┴─┬─┴───┤ - │ │ │ - └─────┴─────┘ -``` - -This can be described by saying the top row is 3 1u keys, and the bottom row is 2 1.5u keys. The difference between the two rows is important, because the bottom row has an unused column spot (3 v 2). Let's say that this is how we wired the columns: - -``` - ┌───┬───┬───┐ - │ ┋ │ ┋ │ ┋ │ - ├─┋─┴─┬─┴─┋─┤ - │ ┋ │ ┋ │ - └─────┴─────┘ -``` - -The middle column is unused on the bottom row in this example. Our `LAYOUT` definition would look like this: - -``` - #define LAYOUT( \ - k00, k01, k02, \ - k10, k11, \ - ) \ - { \ - { k00, k01, k02 }, \ - { k10, KC_NO, k11 }, \ +1. Extract the `kb` folder to `qmk_firmware/keyboards/handwired/`. +2. Open the extracted `kb` folder, then proceed to the `keymaps/default/` folder, and open `keymap.c`. +3. Locate and delete the `action_get_macro` code block: + ``` + const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) { + ... + return MACRO_NONE; } -``` - -Notice how the top half is spaced to resemble our physical layout - this helps us understand which keys are associated with which columns. The bottom half uses the keycode `KC_NO` where there is no keyswitch wired in. It's easiest to keep the bottom half aligned in a grid to help us make sense of how the firmware actually sees the wiring. - -Let's say that instead, we wired our keyboard like this (a fair thing to do): - -``` - ┌───┬───┬───┐ - │ ┋ │ ┋│ ┋ │ - ├─┋─┴─┬┋┴───┤ - │ ┋ │┋ │ - └─────┴─────┘ -``` - -This would require our `LAYOUT` definition to look like this: - -``` - #define LAYOUT( \ - k00, k01, k02, \ - k10, k11, \ - ) \ - { \ - { k00, k01, k02 }, \ - { k10, k11, KC_NO }, \ - } -``` - -Notice how the `k11` and `KC_NO` switched places to represent the wiring, and the unused final column on the bottom row. Sometimes it'll make more sense to put a keyswitch on a particular column, but in the end, it won't matter, as long as all of them are accounted for. You can use this process to write out the `LAYOUT` for your entire keyboard - be sure to remember that your keyboard is actually backwards when looking at the underside of it. - -### `keymaps//default.c` - -This is the actual keymap for your keyboard, and the main place you'll make changes as you perfect your layout. `default.c` is the file that gets pull by default when typing `make`, but you can make other files as well, and specify them by typing `make handwired/:`, which will pull `keymaps//keymap.c`. - -The basis of a keymap is its layers - by default, layer 0 is active. You can activate other layers, the highest of which will be referenced first. Let's start with our base layer. - -Using our previous example, let's say we want to create the following layout: - -``` - ┌───┬───┬───┐ - │ A │ 1 │ H │ - ├───┴─┬─┴───┤ - │ TAB │ SPC │ - └─────┴─────┘ -``` - -This can be accomplished by using the following `keymaps` definition: - -``` -const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - [0] = LAYOUT( /* Base */ - KC_A, KC_1, KC_H, \ - KC_TAB, KC_SPC \ - ), -}; -``` - -Note that the layout of the keycodes is similar to the physical layout of our keyboard - this make it much easier to see what's going on. A lot of the keycodes should be fairly obvious, but for a full list of them, check out [Keycodes](keycodes.md) - there are also a lot of aliases to condense your keymap file. - -It's also important to use the `LAYOUT` function we defined earlier - this is what allows the firmware to associate our intended readable keymap with the actual wiring. - -## Compiling Your Firmware - -After you've written out your entire keymap, you're ready to get the firmware compiled and onto your Teensy. Before compiling, you'll need to get your [development environment set-up](getting_started_build_tools.md) - you can skip the dfu-programmer instructions, but you'll need to download and install the [Teensy Loader](https://www.pjrc.com/teensy/loader.html) to get the firmware on your Teensy. - -Once everything is installed, running `make` in the terminal should get you some output, and eventually a `.hex` file in that folder. If you're having trouble with this step, see the end of the guide for the trouble-shooting section. - -Once you have your `.hex` file, open up the Teensy loader application, and click the file icon. From here, navigate to your `QMK/keyboards//` folder, and select the `.hex` file. Plug in your keyboard and press the button on the Teensy - you should see the LED on the device turn off once you do. The Teensy Loader app will change a little, and the buttons should be clickable - click the download button (down arrow), and then the reset button (right arrow), and your keyboard should be ready to go! - -
+ ``` +4. Save and close `keymap.c`. ## Flashing the Firmware -Install [QMK toolbox](https://github.com/qmk/qmk_toolbox). +Install [QMK Toolbox](https://github.com/qmk/qmk_toolbox). -![QMK Toolbox](https://i.imgur.com/86Cz30H.png) +![QMK Toolbox](https://raw.githubusercontent.com/noroadsleft/qmk_images/master/docs/hand_wire/qmk_toolbox.png "QMK Toolbox 0.0.16 on Windows 8.1") Under "Local File" navigate to your newly created .hex file. Under "Microcontroller", select the corresponding one for your controller board (common ones available [here](#common-microcontroller-boards)). @@ -453,34 +205,40 @@ Plug in your keyboard and press the reset button (or short the Reset and Ground ## Testing Your Firmware -Use a website such as [keyboard tester](https://www.keyboardtester.com/tester.html)/[keyboard checker](http://keyboardchecker.com/) or just open a text editor and try typing - you should get the characters that you put into your keymap. Test each key, and make a note of the ones that aren't working. Here's a quick trouble-shooting guide for non-working keys: +Use a website such as [QMK Configurator's Keyboard Tester](https://config.qmk.fm/#/test), [Keyboard Tester](https://www.keyboardtester.com/tester.html), or [Keyboard Checker](https://keyboardchecker.com/) or just open a text editor and try typing - you should get the characters that you put into your keymap. Test each key, and make a note of the ones that aren't working. Here's a quick trouble-shooting guide for non-working keys: -0. Flip the keyboard back over and short the keyswitch's contacts with a piece wire - this will eliminate the possibility of the keyswitch being bad and needing to be replaced. -1. Check the solder points on the keyswitch - these need to be plump and whole. If you touch it with a moderate amount of force and it comes apart, it's not strong enough. -2. Check the solder joints on the diode - if the diode is loose, part of your row may register, while the other may not. -3. Check the solder joints on the columns - if your column wiring is loose, part or all of the column may not work. -4. Check the solder joints on both sides of the wires going to/from the Teensy - the wires need to be fully soldered and connect to both sides. -5. Check the `.h` file for errors and incorrectly placed `KC_NO`s - if you're unsure where they should be, instead duplicate a k*xy* variable. -6. Check to make sure you actually compiled the firmware and flashed the Teensy correctly. Unless you got error messages in the terminal, or a pop-up during flashing, you probably did everything correctly. -7. Use a multimeter to check that the switch is actually closing when actuated (completing the circuit when pressed down). +1. Flip the keyboard back over and short the keyswitch's contacts with a piece wire - this will eliminate the possibility of the keyswitch being bad and needing to be replaced. +2. Check the solder points on the keyswitch - these need to be plump and whole. If you touch it with a moderate amount of force and it comes apart, it's not strong enough. +3. Check the solder joints on the diode - if the diode is loose, part of your row may register, while the other may not. +4. Check the solder joints on the columns - if your column wiring is loose, part or all of the column may not work. +5. Check the solder joints on both sides of the wires going to/from the Teensy - the wires need to be fully soldered and connect to both sides. +6. Check the `.h` file for errors and incorrectly placed `KC_NO`s - if you're unsure where they should be, instead duplicate a k*xy* variable. +7. Check to make sure you actually compiled the firmware and flashed the Teensy correctly. Unless you got error messages in the terminal, or a pop-up during flashing, you probably did everything correctly. +8. Use a multimeter to check that the switch is actually closing when actuated (completing the circuit when pressed down). If you've done all of these things, keep in mind that sometimes you might have had multiple things affecting the keyswitch, so it doesn't hurt to test the keyswitch by shorting it out at the end. -# Finishing up +## Finishing up Once you have confirmed that the keyboard is working, if you have used a seperate (non handwire specific) controller you will want to secure it in place. This can be done in many different ways e.g. hot glue, double sided sticky tape, 3D printed caddy, electrical tape. If you found this fullfilling you could experiment by adding additional features such as [in switch LEDs](https://geekhack.org/index.php?topic=94258.0), [in switch RGB](https://www.reddit.com/r/MechanicalKeyboards/comments/5s1l5u/photoskeyboard_science_i_made_a_handwired_rgb/), [RGB underglow](https://medium.com/@DavidNZ/hand-wired-custom-keyboard-cdd14429c7b3#.7a1ovebsk) or even an [OLED display!](https://www.reddit.com/r/olkb/comments/5zy7og/adding_ssd1306_oled_display_to_your_build/) -There are a lot of possibilities inside the firmware - explore [docs.qmk.fm](http://docs.qmk.fm) for a full feature list, and dive into the different keyboards to see how people use all of them. You can always stop by [the OLKB subreddit](http://reddit.com/r/olkb) or [QMK Discord](https://discord.gg/Uq7gcHh) for help! +There are a lot of possibilities inside the firmware - explore [docs.qmk.fm](https://docs.qmk.fm) for a full feature list, and dive into the different keyboards to see how people use all of them. You can always stop by [the OLKB subreddit](https://reddit.com/r/olkb) or [QMK Discord](https://discord.gg/Uq7gcHh) for help! -# Links to other guides: +## Links to Other Guides - [matt3o's step by step guide (BrownFox build)](https://deskthority.net/viewtopic.php?f=7&t=6050) also his [website](https://matt3o.com/hand-wiring-a-custom-keyboard/) and [video guide](https://www.youtube.com/watch?v=LVzpsjFWPP4) - [Cribbit's "Modern hand wiring guide - stronger, cleaner, easier"](https://geekhack.org/index.php?topic=87689.0) - [Sasha Solomon's "Building my first Keyboard"](https://medium.com/@sachee/building-my-first-keyboard-and-you-can-too-512c0f8a4c5f) - [RoastPotatoes' "How to hand wire a Planck"](https://blog.roastpotatoes.co/guide/2015/11/04/how-to-handwire-a-planck/) -- [Masterzen's "Handwired keyboard build log"](http://www.masterzen.fr/2018/12/16/handwired-keyboard-build-log-part-1/) +- [Masterzen's "Handwired keyboard build log"](https://www.masterzen.fr/2018/12/16/handwired-keyboard-build-log-part-1/) +# Legacy Content +This page used to include more content. We have moved a section that used to be part of this page its own page. Everything below this point is simply a redirect so that people following old links on the web find what they're looking for. + +## Preamble: How a Keyboard Matrix Works (and why we need diodes) :id=preamble-how-a-keyboard-matrix-works-and-why-we-need-diodes + +* [How a Keyboard Matrix Works](how_a_matrix_works.md) diff --git a/docs/hardware.md b/docs/hardware.md deleted file mode 100644 index c3cc0e591ea..00000000000 --- a/docs/hardware.md +++ /dev/null @@ -1,8 +0,0 @@ -# Hardware - -QMK runs on a variety of hardware. If your processor can be targeted by [LUFA](http://www.fourwalledcubicle.com/LUFA.php) or [ChibiOS](http://www.chibios.com) you can probably get QMK running on it. This section explores getting QMK running on, and communicating with, hardware of all kinds. - -* [Keyboard Guidelines](hardware_keyboard_guidelines.md) -* [AVR Processors](hardware_avr.md) -* ARM Processors (TBD) -* [Drivers](hardware_drivers.md) diff --git a/docs/hardware_avr.md b/docs/hardware_avr.md index 697c55d2a8b..eb536ca961a 100644 --- a/docs/hardware_avr.md +++ b/docs/hardware_avr.md @@ -32,7 +32,7 @@ This will create all the files needed to support your new keyboard, and populate ## `readme.md` -This is where you'll describe your keyboard. Please follow the [Keyboard Readme Template](documentation_templates.md#keyboard-readmemd-template) when writing your `readme.md`. You're encouraged to place an image at the top of your `readme.md`, please use an external service such as [Imgur](http://imgur.com) to host the images. +This is where you'll describe your keyboard. Please follow the [Keyboard Readme Template](documentation_templates.md#keyboard-readmemd-template) when writing your `readme.md`. You're encouraged to place an image at the top of your `readme.md`, please use an external service such as [Imgur](https://imgur.com) to host the images. ## `.c` @@ -67,7 +67,7 @@ The `config.h` file is where you configure the hardware and feature set for your At the top of the `config.h` you'll find USB related settings. These control how your keyboard appears to the Operating System. If you don't have a good reason to change you should leave the `VENDOR_ID` as `0xFEED`. For the `PRODUCT_ID` you should pick a number that is not yet in use. -Do change the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` lines to accurately reflect your keyboard. +Do change the `MANUFACTURER` and `PRODUCT` lines to accurately reflect your keyboard. ```c #define VENDOR_ID 0xFEED @@ -75,10 +75,9 @@ Do change the `MANUFACTURER`, `PRODUCT`, and `DESCRIPTION` lines to accurately r #define DEVICE_VER 0x0001 #define MANUFACTURER You #define PRODUCT my_awesome_keyboard -#define DESCRIPTION A custom keyboard ``` -?> Windows and macOS will display the `MANUFACTURER` and `PRODUCT` in the list of USB devices. `lsusb` on Linux instead takes these from the list maintained by the [USB ID Repository](http://www.linux-usb.org/usb-ids.html) by default. `lsusb -v` will show the values reported by the device, and they are also present in kernel logs after plugging it in. +?> Windows and macOS will display the `MANUFACTURER` and `PRODUCT` in the list of USB devices. `lsusb` on Linux instead prefers the values in the list maintained by the [USB ID Repository](http://www.linux-usb.org/usb-ids.html). By default, it will only use `MANUFACTURER` and `PRODUCT` if the list does not contain that `VENDOR_ID` / `PRODUCT_ID`. `sudo lsusb -v` will show the values reported by the device, and they are also present in kernel logs after plugging it in. ### Keyboard Matrix Configuration diff --git a/docs/hardware_drivers.md b/docs/hardware_drivers.md index 16518779570..7e89c0d2b9a 100644 --- a/docs/hardware_drivers.md +++ b/docs/hardware_drivers.md @@ -33,3 +33,7 @@ Support for up to 2 drivers. Each driver impliments 2 charlieplex matrices to in ## IS31FL3733 Support for up to a single driver with room for expansion. Each driver can control 192 individual LEDs or 64 RGB LEDs. For more information on how to setup the driver see the [RGB Matrix](feature_rgb_matrix.md) page. + +## 24xx series external I2C EEPROM + +Support for an external I2C-based EEPROM instead of using the on-chip EEPROM. For more information on how to setup the driver see the [EEPROM Driver](eeprom_driver.md) page. diff --git a/docs/hardware_keyboard_guidelines.md b/docs/hardware_keyboard_guidelines.md index 5d9968f6d72..4f32715046a 100644 --- a/docs/hardware_keyboard_guidelines.md +++ b/docs/hardware_keyboard_guidelines.md @@ -3,6 +3,25 @@ Since starting, QMK has grown by leaps and bounds thanks to people like you who contribute to creating and maintaining our community keyboards. As we've grown we've discovered some patterns that work well, and ask that you conform to them to make it easier for other people to benefit from your hard work. +## Use QMK Lint + +We have provided a tool, `qmk lint`, which will let you check over your keyboard for problems. We suggest using it frequently while working on your keyboard and keymap. + +Example passing check: + +``` +$ qmk lint -kb rominronin/katana60/rev2 +Ψ Lint check passed! +``` + +Example failing check: + +``` +$ qmk lint -kb clueboard/66/rev3 +☒ Missing keyboards/clueboard/66/rev3/readme.md +☒ Lint check failed! +``` + ## Naming Your Keyboard/Project All keyboard names are in lower case, consisting only of letters, numbers, and underscore (`_`). Names may not begin with an underscore. Forward slash (`/`) is used as a sub-folder separation character. @@ -61,10 +80,76 @@ This file is used by the [QMK API](https://github.com/qmk/qmk_api). It contains All projects need to have a `config.h` file that sets things like the matrix size, product name, USB VID/PID, description and other settings. In general, use this file to set essential information and defaults for your keyboard that will always work. +The `config.h` files can also be placed in sub-folders, and the order in which they are read is as follows: + +* `keyboards/top_folder/config.h` + * `keyboards/top_folder/sub_1/config.h` + * `keyboards/top_folder/sub_1/sub_2/config.h` + * `keyboards/top_folder/sub_1/sub_2/sub_3/config.h` + * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/config.h` + * `users/a_user_folder/config.h` + * `keyboards/top_folder/keymaps/a_keymap/config.h` + * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/post_config.h` + * `keyboards/top_folder/sub_1/sub_2/sub_3/post_config.h` + * `keyboards/top_folder/sub_1/sub_2/post_config.h` + * `keyboards/top_folder/sub_1/post_config.h` +* `keyboards/top_folder/post_config.h` + +The `post_config.h` file can be used for additional post-processing, depending on what is specified in the `config.h` file. For example, if you define the `IOS_DEVICE_ENABLE` macro in your keymap-level `config.h` file as follows, you can configure more detailed settings accordingly in the `post_config.h` file: + +* `keyboards/top_folder/keymaps/a_keymap/config.h` + ```c + #define IOS_DEVICE_ENABLE + ``` +* `keyboards/top_folder/post_config.h` + ```c + #ifndef IOS_DEVICE_ENABLE + // USB_MAX_POWER_CONSUMPTION value for this keyboard + #define USB_MAX_POWER_CONSUMPTION 400 + #else + // fix iPhone and iPad power adapter issue + // iOS device need lessthan 100 + #define USB_MAX_POWER_CONSUMPTION 100 + #endif + + #ifdef RGBLIGHT_ENABLE + #ifndef IOS_DEVICE_ENABLE + #define RGBLIGHT_LIMIT_VAL 200 + #define RGBLIGHT_VAL_STEP 17 + #else + #define RGBLIGHT_LIMIT_VAL 35 + #define RGBLIGHT_VAL_STEP 4 + #endif + #ifndef RGBLIGHT_HUE_STEP + #define RGBLIGHT_HUE_STEP 10 + #endif + #ifndef RGBLIGHT_SAT_STEP + #define RGBLIGHT_SAT_STEP 17 + #endif + #endif + ``` + +?> If you define options using `post_config.h` as in the above example, you should not define the same options in the keyboard- or user-level `config.h`. + ### `rules.mk` The presence of this file means that the folder is a keyboard target and can be used in `make` commands. This is where you setup the build environment for your keyboard and configure the default set of features. +The `rules.mk` file can also be placed in a sub-folder, and its reading order is as follows: + +* `keyboards/top_folder/rules.mk` + * `keyboards/top_folder/sub_1/rules.mk` + * `keyboards/top_folder/sub_1/sub_2/rules.mk` + * `keyboards/top_folder/sub_1/sub_2/sub_3/rules.mk` + * `keyboards/top_folder/sub_1/sub_2/sub_3/sub_4/rules.mk` + * `keyboards/top_folder/keymaps/a_keymap/rules.mk` + * `users/a_user_folder/rules.mk` +* `common_features.mk` + +Many of the settings written in the `rules.mk` file are interpreted by `common_features.mk`, which sets the necessary source files and compiler options. + +?> See `build_keyboard.mk` and `common_features.mk` for more details. + ### `` This is where you will write custom code for your keyboard. Typically you will write code to initialize and interface with the hardware in your keyboard. If your keyboard consists of only a key matrix with no LEDs, speakers, or other auxiliary hardware this file can be blank. @@ -98,7 +183,7 @@ As an example, if you have a 60% PCB that supports ANSI and ISO you might define In an effort to keep the repo size down we're no longer accepting binary files of any format, with few exceptions. Hosting them elsewhere (such as ) and linking them in the `readme.md` is preferred. -Hardware files (such as plates, cases, pcb) can be contributed to the [qmk.fm repo](https://github.com/qmk/qmk.fm) and they will be made available on [qmk.fm](http://qmk.fm). Downloadable files are stored in `//` (name follows the same format as above) which are served at `http://qmk.fm//`, and pages are generated from `/_pages//` which are served at the same location (.md files are generated into .html files through Jekyll). Check out the `lets_split` folder for an example. +Hardware files (such as plates, cases, pcb) can be contributed to the [qmk.fm repo](https://github.com/qmk/qmk.fm) and they will be made available on [qmk.fm](https://qmk.fm). Downloadable files are stored in `//` (name follows the same format as above) which are served at `https://qmk.fm//`, and pages are generated from `/_pages//` which are served at the same location (.md files are generated into .html files through Jekyll). Check out the `lets_split` folder for an example. ## Keyboard Defaults @@ -126,7 +211,7 @@ When developing your keyboard, keep in mind that all warnings will be treated as ## Copyright Blurb -If you're adapting your keyboard's setup from another project, but not using the same code, but sure to update the copyright header at the top of the files to show your name, in this format: +If you're adapting your keyboard's setup from another project, but not using the same code, be sure to update the copyright header at the top of the files to show your name, in this format: Copyright 2017 Your Name @@ -140,7 +225,7 @@ The year should be the first year the file is created. If work was done to that ## License -The core of QMK is licensed under the [GNU General Public License](https://www.gnu.org/licenses/licenses.en.html). If you are shipping binaries for AVR processors you may choose either [GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) or [GPLv3](https://www.gnu.org/licenses/gpl.html). If you are shipping binaries for ARM processors you must choose [GPL Version 3](https://www.gnu.org/licenses/gpl.html) to comply with the [ChibiOS](http://www.chibios.org) GPLv3 license. +The core of QMK is licensed under the [GNU General Public License](https://www.gnu.org/licenses/licenses.en.html). If you are shipping binaries for AVR processors you may choose either [GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) or [GPLv3](https://www.gnu.org/licenses/gpl.html). If you are shipping binaries for ARM processors you must choose [GPL Version 3](https://www.gnu.org/licenses/gpl.html) to comply with the [ChibiOS](https://www.chibios.org) GPLv3 license. If your keyboard makes use of the [uGFX](https://ugfx.io) features within QMK you must comply with the [uGFX License](https://ugfx.io/license.html), which requires a separate commercial license before selling a device containing uGFX. diff --git a/docs/he-il/README.md b/docs/he-il/README.md index 8e0c470b442..3b0ff146185 100644 --- a/docs/he-il/README.md +++ b/docs/he-il/README.md @@ -10,11 +10,11 @@ ## מה היא קושחת QMK? -QMK (*Quantum Mechanical Keyboard*) היא קהילת קוד פתוח (open source) שמתחזקת את קושחת QMK, QMK Toolbox, qmk.fm, והמסמכים המתאימים. קושחת QMK היא קושחה עבור מקלדות המבוססת על [tmk\_keyboard](http://github.com/tmk/tmk_keyboard) עם כמה תוספות עבור בקרי Atmel AVR ובאופן ספציפי יותר - [מוצרי OLKB](http://olkb.com), מקלדת [ErgoDox EZ](http://www.ergodox-ez.com), וגם [מוצרי Clueboard](http://clueboard.co/). בנוסף, הקושחה עברה פורט עבור שבבי ARM באמצעות ChibiOS. ניתן להשתמש בה על מנת להפעיל את מקלדות ה PCB המקוסטמות שלך. +QMK (*Quantum Mechanical Keyboard*) היא קהילת קוד פתוח (open source) שמתחזקת את קושחת QMK, QMK Toolbox, qmk.fm, והמסמכים המתאימים. קושחת QMK היא קושחה עבור מקלדות המבוססת על [tmk\_keyboard](https://github.com/tmk/tmk_keyboard) עם כמה תוספות עבור בקרי Atmel AVR ובאופן ספציפי יותר - [מוצרי OLKB](https://olkb.com), מקלדת [ErgoDox EZ](https://www.ergodox-ez.com), וגם [מוצרי Clueboard](https://clueboard.co/). בנוסף, הקושחה עברה פורט עבור שבבי ARM באמצעות ChibiOS. ניתן להשתמש בה על מנת להפעיל את מקלדות ה PCB המקוסטמות שלך. ## איך להשיג אותה -אם אתם מתכננים לתרום מיפוי מקשים, מקלדת או יכולת ל QMK, הדבר הקל ביותר הוא [לעשות פורק לריפו בGithub](https://github.com/qmk/qmk_firmware#fork-destination-box), ולעשות קלון לריפו בסביבה המקומית ושם לבצע את השינויים שלכם, לדחוף אותם ולפתוח [Pull Request](https://github.com/qmk/qmk_firmware/pulls) מהפורק שלך. +אם אתם מתכננים לתרום מיפוי מקשים, מקלדת או יכולת ל QMK, הדבר הקל ביותר הוא [לעשות פורק לריפו בGitHub](https://github.com/qmk/qmk_firmware#fork-destination-box), ולעשות קלון לריפו בסביבה המקומית ושם לבצע את השינויים שלכם, לדחוף אותם ולפתוח [Pull Request](https://github.com/qmk/qmk_firmware/pulls) מהפורק שלך. אחרת, אפשר להוריד את הקושחה באופן ישיר ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), או לשכפל אותה באמצעות git (`git@github.com:qmk/qmk_firmware.git`), או https (`https://github.com/qmk/qmk_firmware.git`). @@ -30,5 +30,5 @@ QMK (*Quantum Mechanical Keyboard*) היא קהילת קוד פתוח (open sour ## איך להתאים -לQMK יש המון [יכולות](he-il/features.md) שאפשר לנווט בהן, וכמות נכבדת של [תיעוד ודוקומנטציה](http://docs.qmk.fm) בה אפשר לנבור. רוב הפיצ׳רים באים לידי ביטוי על ידי שינוי [מיפוי המקלדת](he-il/keymap.md) ושינוי [קודי המקשים](he-il/keycodes.md). +לQMK יש המון [יכולות](he-il/features.md) שאפשר לנווט בהן, וכמות נכבדת של [תיעוד ודוקומנטציה](https://docs.qmk.fm) בה אפשר לנבור. רוב הפיצ׳רים באים לידי ביטוי על ידי שינוי [מיפוי המקלדת](he-il/keymap.md) ושינוי [קודי המקשים](he-il/keycodes.md). diff --git a/docs/he-il/_summary.md b/docs/he-il/_summary.md index 804db534a34..148eb6400d8 100644 --- a/docs/he-il/_summary.md +++ b/docs/he-il/_summary.md @@ -5,7 +5,7 @@ * [מקורות ללמידה](he-il/newbs_learn_more_resources.md) * [בסיס QMK](he-il/README.md) * [מבוא לQMK](he-il/getting_started_introduction.md) - * [איך להשתמש בGithub](he-il/getting_started_github.md) + * [איך להשתמש בGitHub](he-il/getting_started_github.md) * [קבלת עזרה](he-il/getting_started_getting_help.md) * [שאלות נפוצות](he-il/faq.md) * [שאלות נפוצות כלליות](he-il/faq_general.md) @@ -27,7 +27,7 @@ * [QMK CLI](he-il/cli.md) * [QMK CLI Config](he-il/cli_configuration.md) * [תרומה ל QMK](he-il/contributing.md) - * [איך להשתמש בGithub](he-il/getting_started_github.md) + * [איך להשתמש בGitHub](he-il/getting_started_github.md) * [קבלת עזרה](he-il/getting_started_getting_help.md) * [שינויים משמעותיים](he-il/breaking_changes.md) @@ -93,7 +93,7 @@ * [Macros](he-il/feature_macros.md) * [Mouse Keys](he-il/feature_mouse_keys.md) * [OLED Driver](he-il/feature_oled_driver.md) - * [One Shot Keys](he-il/feature_advanced_keycodes.md#one-shot-keys) + * [One Shot Keys](he-il/one_shot_keys.md) * [Pointing Device](he-il/feature_pointing_device.md) * [PS/2 Mouse](he-il/feature_ps2_mouse.md) * [RGB Lighting](he-il/feature_rgblight.md) @@ -114,6 +114,7 @@ * [מדריך לצריבת ISP](he-il/isp_flashing_guide.md) * [מדריך לדיבאגינג ARM](he-il/arm_debugging.md) * [מנהל התקן I2C](he-il/i2c_driver.md) + * [מנהל התקן SPI](he-il/spi_driver.md) * [בקרת GPIO](he-il/internals_gpio_control.md) * [המרת Proton C](he-il/proton_c_conversion.md) @@ -124,7 +125,7 @@ * נושאים נוספים * [שימוש ב - Eclipse עם QMK](he-il/other_eclipse.md) * [שימוש ב - VSCode עם QMK](he-il/other_vscode.md) - * [תמיכה](he-il/support.md) + * [תמיכה](he-il/getting_started_getting_help.md) * [כיצד להוסיף תרגום](he-il/translating.md) * QMK מבפנים (בתהליך) diff --git a/docs/he-il/becoming_a_qmk_collaborator.md b/docs/he-il/becoming_a_qmk_collaborator.md deleted file mode 100644 index 4c14441bdb2..00000000000 --- a/docs/he-il/becoming_a_qmk_collaborator.md +++ /dev/null @@ -1,11 +0,0 @@ -
-# איך להפוך לשותף של QMK - -שותף של QMK הוא יצרן מקלדות או מעצב שמעוניין בלעזור ל-QMK לגדול ולתמוך במקלד(ו)ת שלהם, ולעודד את המשתמשים והצרכנים להוסיף יכולות, רעיונות ומיפויים. אנחנו תמיד מחפשים עוד מקלדות ומשתפי פעולה, אבל אנחנו מבקשים שיעמדו בדרישות הבאות: - -* **קיום לוח PCB למכירה.** לצערינו, יש יותר מידי הסתבכויות ובעיות עם מקלדות המחווטות ידנית. -* **תחזוק המקלדת ב-QMK.** זה אולי רק ידרוש הגדרה בסיסית כדי לגרום למקלדת לעבוד, אבל זה גם יכול לכלול התאמה של שינויים בקוד הליבה של QMK שיכול לשבור קוד ייחודי שלכם. -* **אישור ומיזוג Pull Requests של מיפויי מקלדת עבור המקלדת** אנחנו רוצים לעודד משתמשים לתרום את מיפויי המקלדת שלהם לאחרים כדי לעזור לאחרים להתחיל ליצור את שלהם. - -אם אתם עומדים בדרישות הללו, שלחו לנו מייל לכתובת hello@qmk.fm עם מבוא וקישורים עבור המקלדת שלכם. -
\ No newline at end of file diff --git a/docs/he-il/documentation_best_practices.md b/docs/he-il/documentation_best_practices.md index 90c4a137a04..bba9d886ab5 100644 --- a/docs/he-il/documentation_best_practices.md +++ b/docs/he-il/documentation_best_practices.md @@ -64,4 +64,4 @@ ``` מקמו את התיעוד שלכם בתוך `docs/feature_.md`, והוסיפו קישור לקובץ זה במקום המתאים ב `docs/_sidebar.md`. אם הוספתם קודי מקשים נוספים, תקפידו להוסיף אותם ל- `docs/keycodes.md` עם לינק לעמוד היכולת שלכם. - \ No newline at end of file + diff --git a/docs/he-il/faq.md b/docs/he-il/faq.md index 88ea07fbe71..0a783eb8cac 100644 --- a/docs/he-il/faq.md +++ b/docs/he-il/faq.md @@ -5,4 +5,4 @@ * [בנייה או קומפילציה של QMK](faq_build.md) * [דיבאגינג ופתרון בעיות של QMK](faq_debug.md) * [מיפוי מקשים](faq_keymap.md) - \ No newline at end of file + diff --git a/docs/he-il/faq_general.md b/docs/he-il/faq_general.md index 26286d552f0..fc102d6c6a6 100644 --- a/docs/he-il/faq_general.md +++ b/docs/he-il/faq_general.md @@ -14,4 +14,4 @@ TMK עוצב ומומש במקור ע״י [Jun Wako](https://github.com/tmk). QM מנק׳ מבט של הפרוייקט וניהול הקהילה, TMK מנהל את כל המקלדות הנתמכות בעצמו, עם מעט תמיכה מהקהילה. כל אחד יכול לעשות פורק מהפרוייקט עבור מקלדות אחרות. רק מס׳ מיפויי מקשים נמצאים בברירת המחדל כך שאנשים בד״כ לא משתפים מיפויי מקשים זה עם זה. QMK מעודד את השיתוף של המקלדות וקודי המקשים דרך רפוזיטורי בניהול מרכזי, אשר מקבל את כל בקשות ה- Pull Requests שעומדות בסטנדרט האיכות. רובם מנוהלות ע״י הקהילה, אבל הצוות של QMK עוזר כשנדרש. לשתי הגישות יש יתרונות וחסרונות וקוד עובר בחופשיות בין TMK ל- QMK כשצריך. - \ No newline at end of file + diff --git a/docs/he-il/getting_started_getting_help.md b/docs/he-il/getting_started_getting_help.md index 1a2edc3133f..7dec3e87d6e 100644 --- a/docs/he-il/getting_started_getting_help.md +++ b/docs/he-il/getting_started_getting_help.md @@ -11,7 +11,7 @@ הפורום הרשמי של QMK נמצא ב - [/r/olkb](https://reddit.com/r/olkb) באתר [reddit.com](https://reddit.com). -## סוגיות Github +## סוגיות GitHub ניתן לפתוח [סוגייה ב-GitHub](https://github.com/qmk/qmk_firmware/issues). הדבר שימושי במיוחד כאשר הסוגיה דורשת דיון עמוק וארוך או דיבאגינג. - \ No newline at end of file + diff --git a/docs/he-il/getting_started_github.md b/docs/he-il/getting_started_github.md index 55602c81426..900852effd0 100644 --- a/docs/he-il/getting_started_github.md +++ b/docs/he-il/getting_started_github.md @@ -1,35 +1,41 @@
-# איך להשתמש ב-Github עם QMK +# איך להשתמש ב-GitHub עם QMK -Github עלול להיות קצת טריקי למי שלא מכיר את העבודה איתו - מדריך זה ילווה אתכם שלב אחר שלב דרך ביצוע פעולות fork, clone ו-pull request עם QMK. +GitHub עלול להיות קצת טריקי למי שלא מכיר את העבודה איתו - מדריך זה ילווה אתכם שלב אחר שלב דרך ביצוע פעולות fork, clone ו-pull request עם QMK. ?> מדריך זה מניח שאתם מרגישים בנוח עם הרצה של פקודות בסביבת command line (שורת הפקודה) ו-git מותקן במערכת שלכם. -התחילו ב- [עמוד של QMK ב-Github](https://github.com/qmk/qmk_firmware), ותצמאו כפתור בחלק העליון מימין עם התיכוב "Fork": +התחילו ב- [עמוד של QMK ב-GitHub](https://github.com/qmk/qmk_firmware), ותצמאו כפתור בחלק העליון מימין עם התיכוב "Fork": -![Fork ב-Github](http://i.imgur.com/8Toomz4.jpg) +![Fork ב-GitHub](https://i.imgur.com/8Toomz4.jpg) אם אתם חלק מארגון, תצטרכו לבחור לאיזה חשבון לבצע פעולת fork. ברוב המבקרים, תרצו לבצע fork לתוך החשבון הפרטי שלכם. ברגע שה-fork הסתיים (לפעמים זה יכול לקחת קצת זמן) הקליקו על כפתור ה-"Clone or Download": -![הורדה מ-Github](http://i.imgur.com/N1NYcSz.jpg) +![הורדה מ-GitHub](https://i.imgur.com/N1NYcSz.jpg) תוודאו שאתם בוחרים באופצייה של "HTTPS", בחרו את הקישור והעתיקו אותו: -![קישור HTTPS](http://i.imgur.com/eGO0ohO.jpg) +![קישור HTTPS](https://i.imgur.com/eGO0ohO.jpg) -מכאן והלאה, הקיש `git clone ` בשורת הפקודה והדביקו את הלינק שלכם: +מכאן והלאה, הקיש `git clone --recurse-submodules ` בשורת הפקודה והדביקו את הלינק שלכם:
``` -user@computer:~$ git clone https://github.com/whoeveryouare/qmk_firmware.git +user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git Cloning into 'qmk_firmware'... -remote: Counting objects: 46625, done. -remote: Compressing objects: 100% (2/2), done. -remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623 -Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done. -Resolving deltas: 100% (29362/29362), done. -Checking out files: 100% (2799/2799), done. +remote: Enumerating objects: 9, done. +remote: Counting objects: 100% (9/9), done. +remote: Compressing objects: 100% (5/5), done. +remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874 +Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done. +Resolving deltas: 100% (119972/119972), done. +... +Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b' +Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486' +Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780' +Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d' +Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2' ```
@@ -59,11 +65,11 @@ To https://github.com/whoeveryouare/qmk_firmware.git השינויים שלכם יופיעו ב-fork שלכם ב-GitHub - אם תחזרו לשם (`https://github.com//qmk_firmware`), תוכלו ליצור "Pull Request חדש" ע״י הקשה על הכפתור הבא: -![Pull Request חדש](http://i.imgur.com/DxMHpJ8.jpg) +![Pull Request חדש](https://i.imgur.com/DxMHpJ8.jpg) כאן תוכלו לראות בדיוק למה עשיתם commit - אם הכל נראה תקין, תוכלו להשלים את הפעולה ע״י הקשה על "Create Pull Request": -![צרו Pull Request](http://i.imgur.com/Ojydlaj.jpg) +![צרו Pull Request](https://i.imgur.com/Ojydlaj.jpg) אחרי שהגשתם, אנו עלולים לפנות אליכם לגבי השינויים שהצעתם, נבקש שתבצעו שינויים ובסופו של דבר נקבל את השינויים! תודה שתרמתם לפרוייקט QMK :) -
\ No newline at end of file + diff --git a/docs/he-il/getting_started_introduction.md b/docs/he-il/getting_started_introduction.md index 4b7f56b2a7e..fca86bdaaf4 100644 --- a/docs/he-il/getting_started_introduction.md +++ b/docs/he-il/getting_started_introduction.md @@ -5,7 +5,7 @@ ## מבנה QMK בסיסי -QMK הוא פורק של הפרוייקט [tmk_keyboard](https://github.com/tmk/tmk_keyboard) של [Jun Wako](https://github.com/tmk). קוד הTMK המקורי, עם התאמות, יכול להמצא בתיקיית `tmk`. התוספות של QMK לפרוייקט יכולות להמצא בתיקיית `quantum`. פרוייקטי מקלדות יכולות להמצא בתיקיות `handwired` ו- `keyboard`. +QMK הוא פורק של הפרוייקט [tmk_keyboard](https://github.com/tmk/tmk_keyboard) של [Jun Wako](https://github.com/tmk). קוד הTMK המקורי, עם התאמות, יכול להמצא בתיקיית `tmk_core`. התוספות של QMK לפרוייקט יכולות להמצא בתיקיית `quantum`. פרוייקטי מקלדות יכולות להמצא בתיקיות `handwired` ו- `keyboard`. ### מבנה אחסון המשתמש @@ -69,4 +69,4 @@ In every keymap folder, the following files may be found. Only `keymap.c` is req ``` - \ No newline at end of file + diff --git a/docs/he-il/hardware.md b/docs/he-il/hardware.md index 441792e031b..fca03bd64b8 100644 --- a/docs/he-il/hardware.md +++ b/docs/he-il/hardware.md @@ -1,10 +1,10 @@
# חומרה -QMK רצה על מגוון של חומרות. אם המעבד שלך יכול להיות ממוקד (מטורגט) ע״י [LUFA](http://www.fourwalledcubicle.com/LUFA.php) או [ChibiOS](http://www.chibios.com) כנראה שתוכל לגרום ל QMK לרוץ על המעבד. קטע זה מדבר על הרצת QMK, ותקשורת עם, סוגים שונים של חומרות. +QMK רצה על מגוון של חומרות. אם המעבד שלך יכול להיות ממוקד (מטורגט) ע״י [LUFA](https://www.fourwalledcubicle.com/LUFA.php) או [ChibiOS](https://www.chibios.org) כנראה שתוכל לגרום ל QMK לרוץ על המעבד. קטע זה מדבר על הרצת QMK, ותקשורת עם, סוגים שונים של חומרות. * [מדריך למקלדת](hardware_keyboard_guidelines.md) * [מעבדי AVR](hardware_avr.md) * מעבדי ARM (TBD) * [מנהלי התקנים](hardware_drivers.md) -
\ No newline at end of file + diff --git a/docs/he-il/newbs_learn_more_resources.md b/docs/he-il/newbs_learn_more_resources.md index 8792a9de0a7..4127c387ff0 100644 --- a/docs/he-il/newbs_learn_more_resources.md +++ b/docs/he-il/newbs_learn_more_resources.md @@ -13,4 +13,4 @@ מקורות לפקודות שורה (Command Line): * [מדריך טוב על Command Line](https://www.codecademy.com/learn/learn-the-command-line) - \ No newline at end of file + diff --git a/docs/he-il/quantum_keycodes.md b/docs/he-il/quantum_keycodes.md index 3ca545e9774..5374fd47ad4 100644 --- a/docs/he-il/quantum_keycodes.md +++ b/docs/he-il/quantum_keycodes.md @@ -17,18 +17,8 @@ |`DEBUG` | |Toggle debug mode | |`EEPROM_RESET` |`EEP_RST` |Resets EEPROM state by reinitializing it | |`KC_GESC` |`GRAVE_ESC`|Escape when tapped, ` when pressed with Shift or GUI| -|`KC_LSPO` | |Left Shift when held, `(` when tapped | -|`KC_RSPC` | |Right Shift when held, `)` when tapped | -|`KC_LCPO` | |Left Control when held, `(` when tapped | -|`KC_RCPC` | |Right Control when held, `)` when tapped | -|`KC_LAPO` | |Left Alt when held, `(` when tapped | -|`KC_RAPC` | |Right Alt when held, `)` when tapped | -|`KC_SFTENT` | |Right Shift when held, Enter when tapped | |`KC_LEAD` | |The [Leader key](feature_leader_key.md) | |`KC_LOCK` | |The [Lock key](feature_key_lock.md) | -|`FUNC(n)` |`F(n)` |Call `fn_action(n)` (deprecated) | -|`M(n)` | |Call macro `n` | -|`MACROTAP(n)` | |Macro-tap `n` idk FIXME | ``` diff --git a/docs/how_a_matrix_works.md b/docs/how_a_matrix_works.md new file mode 100644 index 00000000000..48e41e5c7de --- /dev/null +++ b/docs/how_a_matrix_works.md @@ -0,0 +1,99 @@ +# How a Keyboard Matrix Works + +Keyboard switch matrices are arranged in rows and columns. Without a matrix circuit, each switch would require its own wire directly to the controller. + +When the circuit is arranged in rows and columns, if a key is pressed, a column wire makes contact with a row wire and completes a circuit. The keyboard controller detects this closed circuit and registers it as a key press. + +The microcontroller will be set up via the firmware to send a logical 1 to the columns, one at a time, and read from the rows, all at once - this process is called matrix scanning. The matrix is a bunch of open switches that, by default, don't allow any current to pass through - the firmware will read this as no keys being pressed. As soon as you press one key down, the logical 1 that was coming from the column the keyswitch is attached to gets passed through the switch and to the corresponding row - check out the following 2x2 example: + + Column 0 being scanned Column 1 being scanned + x x + col0 col1 col0 col1 + | | | | + row0 ---(key0)---(key1) row0 ---(key0)---(key1) + | | | | + row1 ---(key2)---(key3) row1 ---(key2)---(key3) + +The `x` represents that the column/row associated has a value of 1, or is HIGH. Here, we see that no keys are being pressed, so no rows get an `x`. For one keyswitch, keep in mind that one side of the contacts is connected to its row, and the other, its column. + +When we press `key0`, `col0` gets connected to `row0`, so the values that the firmware receives for that row is `0b01` (the `0b` here means that this is a bit value, meaning all of the following digits are bits - 0 or 1 - and represent the keys in that column). We'll use this notation to show when a keyswitch has been pressed, to show that the column and row are being connected: + + Column 0 being scanned Column 1 being scanned + x x + col0 col1 col0 col1 + | | | | + x row0 ---(-+-0)---(key1) row0 ---(-+-0)---(key1) + | | | | + row1 ---(key2)---(key3) row1 ---(key2)---(key3) + +We can now see that `row0` has an `x`, so has the value of 1. As a whole, the data the firmware receives when `key0` is pressed is: + + col0: 0b01 + col1: 0b00 + │└row0 + └row1 + +A problem arises when you start pressing more than one key at a time. Looking at our matrix again, it should become pretty obvious: + + Column 0 being scanned Column 1 being scanned + x x + col0 col1 col0 col1 + | | | | + x row0 ---(-+-0)---(-+-1) x row0 ---(-+-0)---(-+-1) + | | | | + x row1 ---(key2)---(-+-3) x row1 ---(key2)---(-+-3) + + Remember that this ^ is still connected to row1 + +The data we get from that is: + + col0: 0b11 + col1: 0b11 + │└row0 + └row1 + +Which isn't accurate, since we only have 3 keys pressed down, not all 4. This behavior is called ghosting, and only happens in odd scenarios like this, but can be much more common on a bigger keyboard. The way we can get around this is by placing a diode after the keyswitch, but before it connects to its row. A diode only allows current to pass through one way, which will protect our other columns/rows from being activated in the previous example. We'll represent a dioded matrix like this; + + Column 0 being scanned Column 1 being scanned + x x + col0 col1 col0 col1 + │ │ | │ + (key0) (key1) (key0) (key1) + ! │ ! │ ! | ! │ + row0 ─────┴────────┘ │ row0 ─────┴────────┘ │ + │ │ | │ + (key2) (key3) (key2) (key3) + ! ! ! ! + row1 ─────┴────────┘ row1 ─────┴────────┘ + +In practical applications, the black line of the diode will be placed facing the row, and away from the keyswitch - the `!` in this case is the diode, where the gap represents the black line. A good way to remember this is to think of this symbol: `>|` + +Now when we press the three keys, invoking what would be a ghosting scenario: + + Column 0 being scanned Column 1 being scanned + x x + col0 col1 col0 col1 + │ │ │ │ + (┌─┤0) (┌─┤1) (┌─┤0) (┌─┤1) + ! │ ! │ ! │ ! │ + x row0 ─────┴────────┘ │ x row0 ─────┴────────┘ │ + │ │ │ │ + (key2) (┌─┘3) (key2) (┌─┘3) + ! ! ! ! + row1 ─────┴────────┘ x row1 ─────┴────────┘ + +Things act as they should! Which will get us the following data: + + col0: 0b01 + col1: 0b11 + │└row0 + └row1 + +The firmware can then use this correct data to detect what it should do, and eventually, what signals it needs to send to the OS. + +Further reading: +- [Wikipedia article](https://en.wikipedia.org/wiki/Keyboard_matrix_circuit) +- [Deskthority article](https://deskthority.net/wiki/Keyboard_matrix) +- [Keyboard Matrix Help by Dave Dribin (2000)](https://www.dribin.org/dave/keyboard/one_html/) +- [How Key Matrices Works by PCBheaven](https://pcbheaven.com/wikipages/How_Key_Matrices_Works/) (animated examples) +- [How keyboards work - QMK documentation](how_keyboards_work.md) diff --git a/docs/i2c_driver.md b/docs/i2c_driver.md index d5c340edce7..3ec34a0f87f 100644 --- a/docs/i2c_driver.md +++ b/docs/i2c_driver.md @@ -1,120 +1,237 @@ -# I2C Master Driver +# I2C Master Driver :id=i2c-master-driver The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs. -## Available functions +## I2C Addressing :id=note-on-i2c-addresses -|Function |Description | -|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|`void i2c_init(void);` |Initializes the I2C driver. This function should be called once before any transaction is initiated. | -|`uint8_t i2c_start(uint8_t address, uint16_t timeout);` |Starts an I2C transaction. Address is the 7-bit slave address without the direction bit. | -|`uint8_t i2c_transmit(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);` |Transmit data over I2C. Address is the 7-bit slave address without the direction. Returns status of transaction. | -|`uint8_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout);` |Receive data over I2C. Address is the 7-bit slave address without the direction. Saves number of bytes specified by `length` in `data` array. Returns status of transaction. | -|`uint8_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` |Same as the `i2c_transmit` function but `regaddr` sets where in the slave the data will be written. | -|`uint8_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout);` |Same as the `i2c_receive` function but `regaddr` sets from where in the slave the data will be read. | -|`uint8_t i2c_stop(void);` |Ends an I2C transaction. | +All of the addresses expected by this driver should be pushed to the upper 7 bits of the address byte. Setting +the lower bit (indicating read/write) will be done by the respective functions. Almost all I2C addresses listed +on datasheets and the internet will be represented as 7 bits occupying the lower 7 bits and will need to be +shifted to the left (more significant) by one bit. This is easy to do via the bitwise shift operator `<< 1`. -### Function Return +You can either do this on each call to the functions below, or once in your definition of the address. For example, if your device has an address of `0x18`: -All the above functions, except `void i2c_init(void);` return the following truth table: +```c +#define MY_I2C_ADDRESS (0x18 << 1) +``` -|Return Value |Description | -|---------------|---------------------------------------------------| -|0 |Operation executed successfully. | -|-1 |Operation failed. | -|-2 |Operation timed out. | +See https://www.robot-electronics.co.uk/i2c-tutorial for more information about I2C addressing and other technical details. +## AVR Configuration :id=avr-configuration -## AVR +The following defines can be used to configure the I2C master driver: -### Configuration +|`config.h` Override|Description |Default | +|-------------------|---------------------|--------| +|`F_SCL` |Clock frequency in Hz|`400000`| -The following defines can be used to configure the I2C master driver. +No further setup is required - just connect the `SDA` and `SCL` pins of your I2C devices to the matching pins on the MCU: -|Variable |Description |Default| -|------------------|---------------------------------------------------|-------| -|`F_SCL` |Clock frequency in Hz |400KHz | +|MCU |`SCL`|`SDA`| +|------------------|-----|-----| +|ATmega16/32U4 |`D0` |`D1` | +|AT90USB64/128 |`D0` |`D1` | +|ATmega32A |`C0` |`C1` | +|ATmega328/P |`C5` |`C4` | -AVRs usually have set GPIO which turn into I2C pins, therefore no further configuration is required. +?> The ATmega16/32U2 does not possess I2C functionality, and so cannot use this driver. -## ARM +## ChibiOS/ARM Configuration :id=arm-configuration -For ARM the Chibios I2C HAL driver is under the hood. -This section assumes an STM32 MCU. +You'll need to determine which pins can be used for I2C -- a an example, STM32 parts generally have multiple I2C peripherals, labeled I2C1, I2C2, I2C3 etc. -### Configuration +To enable I2C, modify your board's `halconf.h` to enable I2C: -The configuration for ARM MCUs can be quite complex as often there are multiple I2C drivers which can be assigned to a variety of ports. +```c +#define HAL_USE_I2C TRUE +``` -Firstly the `mcuconf.h` file must be setup to enable the necessary hardware drivers. +Then, modify your board's `mcuconf.h` to enable the peripheral you've chosen, for example: -|Variable |Description |Default| -|------------------------------|------------------------------------------------------------------------------------|-------| -|`#STM32_I2C_USE_XXX` |Enable/Disable the hardware driver XXX (each driver should be explicitly listed) |FALSE | -|`#STM32_I2C_BUSY_TIMEOUT` |Time in ms until the I2C command is aborted if no response is received |50 | -|`#STM32_I2C_XXX_IRQ_PRIORITY` |Interrupt priority for hardware driver XXX (THIS IS AN EXPERT SETTING) |10 | -|`#STM32_I2C_USE_DMA` |Enable/Disable the ability of the MCU to offload the data transfer to the DMA unit |TRUE | -|`#STM32_I2C_XXX_DMA_PRIORITY` |Priority of DMA unit for hardware driver XXX (THIS IS AN EXPERT SETTING) |1 | +```c +#undef STM32_I2C_USE_I2C2 +#define STM32_I2C_USE_I2C2 TRUE +``` -Secondly, in the `halconf.h` file, `#define HAL_USE_I2C` must be set to `TRUE`. This allows ChibiOS to load its I2C driver. +|`mcuconf.h` Setting |Description |Default| +|----------------------------|----------------------------------------------------------------------------------|-------| +|`STM32_I2C_BUSY_TIMEOUT` |Time in milliseconds until the I2C command is aborted if no response is received |`50` | +|`STM32_I2C_XXX_IRQ_PRIORITY`|Interrupt priority for hardware driver XXX (THIS IS AN EXPERT SETTING) |`10` | +|`STM32_I2C_USE_DMA` |Enable/Disable the ability of the MCU to offload the data transfer to the DMA unit|`TRUE` | +|`STM32_I2C_XXX_DMA_PRIORITY`|Priority of DMA unit for hardware driver XXX (THIS IS AN EXPERT SETTING) |`1` | -Lastly, we need to assign the correct GPIO pins depending on the I2C hardware driver we want to use. +Configuration-wise, you'll need to set up the peripheral as per your MCU's datasheet -- the defaults match the pins for a Proton-C, i.e. STM32F303. -By default the I2C1 hardware driver is assumed to be used. If another hardware driver is used, `#define I2C_DRIVER I2CDX` should be added to the `config.h` file with X being the number of hardware driver used. For example is I2C3 is enabled, the `config.h` file should contain `#define I2C_DRIVER I2CD3`. This aligns the QMK I2C driver with the Chibios I2C driver. +|`config.h` Overrride |Description |Default| +|------------------------|-------------------------------------------------------------------------------------------|-------| +|`I2C_DRIVER` |I2C peripheral to use - I2C1 -> `I2CD1`, I2C2 -> `I2CD2` etc. |`I2CD1`| +|`I2C1_BANK` (deprecated)|The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`), superseded by `I2C1_SCL_BANK`/`I2C1_SDA_BANK`|`GPIOB`| +|`I2C1_SCL_BANK` |The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) to use for SCL |`GPIOB`| +|`I2C1_SCL` |The pin number for SCL (0-15) |`6` | +|`I2C1_SCL_PAL_MODE` |The alternate function mode for SCL |`4` | +|`I2C1_SDA_BANK` |The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) to use for SDA |`GPIOB`| +|`I2C1_SDA` |The pin number for SDA (0-15) |`7` | +|`I2C1_SDA_PAL_MODE` |The alternate function mode for SDA |`4` | -STM32 MCUs allows a variety of pins to be configured as I2C pins depending on the hardware driver used. By default B6 and B7 are set to I2C. You can use these defines to set your i2c pins: +The following configuration values depend on the specific MCU in use. -| Variable | Description | Default | -|--------------------------|----------------------------------------------------------------------------------------------|---------| -| `I2C1_SCL_BANK` | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) to use for SCL | `GPIOB` | -| `I2C1_SDA_BANK` | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`) to use for SDA | `GPIOB` | -| `I2C1_SCL` | The pin number for the SCL pin (0-9) | `6` | -| `I2C1_SDA` | The pin number for the SDA pin (0-9) | `7` | -| `I2C1_BANK` (deprecated) | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`), superceded by `I2C1_SCL_BANK`, `I2C1_SDA_BANK` | `GPIOB` | +### I2Cv1 :id=i2cv1 -The ChibiOS I2C driver configuration depends on STM32 MCU: +* STM32F1xx +* STM32F2xx +* STM32F4xx +* STM32L0xx +* STM32L1xx - STM32F1xx, STM32F2xx, STM32F4xx, STM32L0xx and STM32L1xx use I2Cv1; - STM32F0xx, STM32F3xx, STM32F7xx and STM32L4xx use I2Cv2; +See [this page](https://www.playembedded.org/blog/stm32-i2c-chibios/#7_I2Cv1_configuration_structure) for the I2Cv1 configuration structure. -#### I2Cv1 -STM32 MCUs allow for different clock and duty parameters when configuring I2Cv1. These can be modified using the following parameters, using as a reference: +|`config.h` Override|Default | +|-------------------|----------------| +|`I2C1_OPMODE` |`OPMODE_I2C` | +|`I2C1_CLOCK_SPEED` |`100000` | +|`I2C1_DUTY_CYCLE` |`STD_DUTY_CYCLE`| -| Variable | Default | -|--------------------|------------------| -| `I2C1_OPMODE` | `OPMODE_I2C` | -| `I2C1_CLOCK_SPEED` | `100000` | -| `I2C1_DUTY_CYCLE` | `STD_DUTY_CYCLE` | +### I2Cv2 :id=i2cv2 -#### I2Cv2 -STM32 MCUs allow for different timing parameters when configuring I2Cv2. These can be modified using the following parameters, using as a reference: +* STM32F0xx +* STM32F3xx +* STM32F7xx +* STM32L4xx -| Variable | Default | -|-----------------------|---------| -| `I2C1_TIMINGR_PRESC` | `15U` | -| `I2C1_TIMINGR_SCLDEL` | `4U` | -| `I2C1_TIMINGR_SDADEL` | `2U` | -| `I2C1_TIMINGR_SCLH` | `15U` | -| `I2C1_TIMINGR_SCLL` | `21U` | +See [this page](https://www.playembedded.org/blog/stm32-i2c-chibios/#8_I2Cv2_I2Cv3_configuration_structure) for the I2Cv2 configuration structure. -STM32 MCUs allow for different "alternate function" modes when configuring GPIO pins. These are required to switch the pins used to I2Cv2 mode. See the respective datasheet for the appropriate values for your MCU. +|`config.h` Override |Default| +|---------------------|-------| +|`I2C1_TIMINGR_PRESC` |`0U` | +|`I2C1_TIMINGR_SCLDEL`|`7U` | +|`I2C1_TIMINGR_SDADEL`|`0U` | +|`I2C1_TIMINGR_SCLH` |`38U` | +|`I2C1_TIMINGR_SCLL` |`129U` | -| Variable | Default | -|---------------------|---------| -| `I2C1_SCL_PAL_MODE` | `4` | -| `I2C1_SDA_PAL_MODE` | `4` | +## Functions :id=functions -#### Other -You can also overload the `void i2c_init(void)` function, which has a weak attribute. If you do this the configuration variables above will not be used. Please consult the datasheet of your MCU for the available GPIO configurations. The following is an example initialization function: +### `void i2c_init(void)` -```C -void i2c_init(void) -{ - setPinInput(B6); // Try releasing special pins for a short time - setPinInput(B7); - wait_ms(10); // Wait for the release to happen +Initialize the I2C driver. This function must be called only once, before any of the below functions can be called. - palSetPadMode(GPIOB, 6, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B6 to I2C function - palSetPadMode(GPIOB, 7, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B7 to I2C function +This function is weakly defined, meaning it can be overridden if necessary for your particular use case: + +```c +void i2c_init(void) { + setPinInput(B6); // Try releasing special pins for a short time + setPinInput(B7); + wait_ms(10); // Wait for the release to happen + + palSetPadMode(GPIOB, 6, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B6 to I2C function + palSetPadMode(GPIOB, 7, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B7 to I2C function } ``` + +--- + +### `i2c_status_t i2c_start(uint8_t address, uint16_t timeout)` + +Start an I2C transaction. + +#### Arguments + + - `uint8_t address` + The 7-bit I2C address of the device (ie. without the read/write bit - this will be set automatically). + - `uint16_t timeout` + The time in milliseconds to wait for a response from the target device. + +#### Return Value + +`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`. + +--- + +### `i2c_status_t i2c_transmit(uint8_t address, uint8_t *data, uint16_t length, uint16_t timeout)` + +Send multiple bytes to the selected I2C device. + +#### Arguments + + - `uint8_t address` + The 7-bit I2C address of the device. + - `uint8_t *data` + A pointer to the data to transmit. + - `uint16_t length` + The number of bytes to write. Take care not to overrun the length of `data`. + - `uint16_t timeout` + The time in milliseconds to wait for a response from the target device. + +#### Return Value + +`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`. + +--- + +### `i2c_status_t i2c_receive(uint8_t address, uint8_t* data, uint16_t length, uint16_t timeout)` + +Receive multiple bytes from the selected SPI device. + +#### Arguments + + - `uint8_t address` + The 7-bit I2C address of the device. + - `uint8_t *data` + A pointer to the buffer to read into. + - `uint16_t length` + The number of bytes to read. Take care not to overrun the length of `data`. + - `uint16_t timeout` + The time in milliseconds to wait for a response from the target device. + +#### Return Value + +`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`. + +--- + +### `i2c_status_t i2c_writeReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)` + +Writes to a register on the I2C device. + +#### Arguments + + - `uint8_t devaddr` + The 7-bit I2C address of the device. + - `uint8_t regaddr` + The register address to write to. + - `uint8_t *data` + A pointer to the data to transmit. + - `uint16_t length` + The number of bytes to write. Take care not to overrun the length of `data`. + - `uint16_t timeout` + The time in milliseconds to wait for a response from the target device. + +#### Return Value + +`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`. + +--- + +### `i2c_status_t i2c_readReg(uint8_t devaddr, uint8_t regaddr, uint8_t* data, uint16_t length, uint16_t timeout)` + +Reads from a register on the I2C device. + +#### Arguments + + - `uint8_t devaddr` + The 7-bit I2C address of the device. + - `uint8_t regaddr` + The register address to read from. + - `uint16_t length` + The number of bytes to read. Take care not to overrun the length of `data`. + - `uint16_t timeout` + The time in milliseconds to wait for a response from the target device. + +#### Return Value + +`I2C_STATUS_TIMEOUT` if the timeout period elapses, `I2C_STATUS_ERROR` if some other error occurs, otherwise `I2C_STATUS_SUCCESS`. + +--- + +### `i2c_status_t i2c_stop(void)` + +Stop the current I2C transaction. diff --git a/docs/index.html b/docs/index.html index 9b33cd263a4..5312b9105dd 100644 --- a/docs/index.html +++ b/docs/index.html @@ -13,19 +13,40 @@ - - - + + + + +
+ + +