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/blank.md deleted file mode 100644 index 50a32034d6e..00000000000 --- a/.github/ISSUE_TEMPLATE/blank.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -name: Blank issue -about: If you're 100% sure that you don't need one of the other issue templates, use this one instead. - ---- diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 3c35416e043..57b415f7b34 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,7 +1,12 @@ --- name: Bug report -about: Create a report to help us improve the QMK Firmware +about: Create a report to help us improve QMK Firmware. +title: "[Bug] " +labels: bug, help wanted +assignees: '' + --- + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000000..0d4ca035c8e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: QMK Discord + url: https://discord.gg/Uq7gcHh + about: Ask questions, discuss issues and features. Chill. + - name: OLKB Subreddit + url: https://www.reddit.com/r/olkb + about: All things OLKB and QMK. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 01aeb26cec3..18768342473 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,7 +1,12 @@ --- name: Feature request -about: Suggest a new feature or changes to existing features +about: Suggest a new feature or changes to existing features. +title: "[Feature Request] " +labels: enhancement, help wanted +assignees: '' + --- + diff --git a/.github/ISSUE_TEMPLATE/other_issues.md b/.github/ISSUE_TEMPLATE/other_issues.md index 7c4891ac31d..befeeb165a2 100644 --- a/.github/ISSUE_TEMPLATE/other_issues.md +++ b/.github/ISSUE_TEMPLATE/other_issues.md @@ -1,7 +1,12 @@ --- name: Other issues -about: Anything else that doesn't fall into the above categories. +about: Anything else that doesn't fall into the above categories. +title: '' +labels: help wanted, question +assignees: '' + --- + diff --git a/.github/ISSUE_TEMPLATE/zzz_blank.md b/.github/ISSUE_TEMPLATE/zzz_blank.md new file mode 100644 index 00000000000..5644802ef53 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/zzz_blank.md @@ -0,0 +1,11 @@ +--- +name: Blank issue +about: If you're 100% sure that you don't need one of the other issue templates, use + this one instead. +title: '' +labels: help wanted, question +assignees: '' + +--- + + 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/stale.yml b/.github/stale.yml new file mode 100644 index 00000000000..eb498881915 --- /dev/null +++ b/.github/stale.yml @@ -0,0 +1,58 @@ +# Configuration for probot-stale - https://github.com/probot/stale + +# General configuration + +# Pull request specific configuration +pulls: + staleLabel: awaiting changes + # Number of days of inactivity before an Issue or Pull Request becomes stale + daysUntilStale: 45 + # Number of days of inactivity before a stale Issue or Pull Request is closed. + # Set to false to disable. If disabled, issues still need to be closed manually, but will remain marked as stale. + daysUntilClose: 30 + # Comment to post when marking as stale. Set to `false` to disable + markComment: > + Thank you for your contribution! + + This pull request has been automatically marked as stale because it has not had + activity in the last 45 days. It will be closed in 30 days if no further activity occurs. + Please feel free to give a status update now, or re-open when it's ready. + + For maintainers: Please label with `awaiting review`, `breaking_change`, `in progress`, or `on hold` to prevent + the issue from being re-flagged. + # Comment to post when closing a stale Issue or Pull Request. + closeComment: > + Thank you for your contribution! + + This pull request has been automatically closed because it has not had activity in the last 30 days. + Please feel free to give a status update now, ping for review, or re-open when it's ready. + # Limit the number of actions per hour, from 1-30. Default is 30 + limitPerRun: 30 + exemptLabels: + - awaiting review + - breaking_change + - in progress + - on hold + +# Issue specific configuration +issues: + staleLabel: stale + limitPerRun: 10 + daysUntilStale: 90 + daysUntilClose: 30 + markComment: > + This issue has been automatically marked as stale because it has not had activity in the + last 90 days. It will be closed in the next 30 days unless it is tagged properly or other activity + occurs. + + For maintainers: Please label with `bug`, `in progress`, `on hold`, `discussion` or `to do` to prevent + the issue from being re-flagged. + closeComment: > + This issue has been automatically closed because it has not had activity in the last 30 days. + If this issue is still valid, re-open the issue and let us know. + exemptLabels: + - bug + - in progress + - on hold + - discussion + - to do 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/info.yml b/.github/workflows/info.yml new file mode 100644 index 00000000000..7551c127e0a --- /dev/null +++ b/.github/workflows/info.yml @@ -0,0 +1,54 @@ +name: PR Lint keyboards + +on: + pull_request: + paths: + - 'keyboards/**' + +jobs: + info: + runs-on: ubuntu-latest + + container: qmkfm/base_container + + steps: + - uses: actions/checkout@v2 + with: + fetch-depth: 0 + + - uses: trilom/file-changes-action@v1.2.3 + id: file_changes + with: + output: '\n' + + - name: Print info + run: | + git rev-parse --short HEAD + echo ${{ github.event.pull_request.base.sha }} + echo '${{ steps.file_changes.outputs.files}}' + + - name: Run qmk info + shell: 'bash {0}' + run: | + QMK_CHANGES=$(echo -e '${{ steps.file_changes.outputs.files}}') + QMK_KEYBOARDS=$(qmk list-keyboards) + + exit_code=0 + for KB in $QMK_KEYBOARDS; do + KEYBOARD_CHANGES=$(echo "$QMK_CHANGES" | grep -E '^(keyboards/'${KB}'/)') + if [[ -z "$KEYBOARD_CHANGES" ]]; then + # skip as no changes for this keyboard + continue + fi + + KEYMAP_ONLY=$(echo "$KEYBOARD_CHANGES" | grep -cv /keymaps/) + if [[ $KEYMAP_ONLY -gt 0 ]]; then + echo "linting ${KB}" + + # TODO: info info always returns 0 - right now the only way to know failure is to inspect log lines + qmk info -l -kb ${KB} 2>&1 | tee /tmp/$$ + !(grep -cq ☒ /tmp/$$) + : $((exit_code = $exit_code + $?)) + fi + done + exit $exit_code diff --git a/.gitignore b/.gitignore index 1f8f9dc74b0..91d283e69ba 100644 --- a/.gitignore +++ b/.gitignore @@ -24,6 +24,7 @@ quantum/version.h .idea/ CMakeLists.txt cmake-build-debug +.clang_complete doxygen/ .DS_Store /util/wsl_downloaded @@ -47,7 +48,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 @@ -60,11 +60,8 @@ util/Win_Check_Output.txt # ignore image files *.png -*.jpg *.gif - -# Do not ignore MiniDox left/right hand eeprom files -!keyboards/minidox/*.eep +*.jpg # things travis sees secrets.tar @@ -73,3 +70,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 84fa63faf3d..d137a420960 100644 --- a/.travis.yml +++ b/.travis.yml @@ -12,20 +12,26 @@ env: - MAKEFLAGS="-j3 --output-sync" services: - docker -install: - - npm install -g moxygen -script: - - git rev-parse --short HEAD - - bash util/travis_test.sh - - bash util/travis_build.sh - - bash util/travis_docs.sh addons: apt: + sources: + - ubuntu-toolchain-r-test + - llvm-toolchain-trusty-7 packages: - pandoc - diffutils - dos2unix - doxygen + - clang-format-7 + - libstdc++-7-dev +install: + - npm install -g moxygen +script: + - git rev-parse --short HEAD + - git diff --name-only HEAD $TRAVIS_BRANCH + - bash util/travis_test.sh + - bash util/travis_build.sh + - bash util/travis_docs.sh after_script: bash util/travis_compiled_push.sh notifications: diff --git a/.vscode/settings.json b/.vscode/settings.json index e5089a55bad..9aa546a7877 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -5,15 +5,21 @@ // 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" + }, + "[markdown]": { + "editor.trimAutoWhitespace": false, + "files.trimTrailingWhitespace": false } } diff --git a/Makefile b/Makefile index 508691f45f1..c851e01e731 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 @@ -272,12 +275,14 @@ define PARSE_RULE # 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,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) + KEYBOARD_RULE=$$(MATCHED_ITEM) $$(eval $$(call PARSE_KEYBOARD,$$(MATCHED_ITEM))) # Otherwise use the KEYBOARD variable, which is determined either by # the current directory you run make from, or passed in as an argument @@ -289,8 +294,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 @@ -380,6 +385,9 @@ define PARSE_KEYBOARD # Otherwise try to match the keymap from the current folder, or arguments to the make command else ifneq ($$(KEYMAP),) $$(eval $$(call PARSE_KEYMAP,$$(KEYMAP))) + # Otherwise if we are running make all: just skip + else ifeq ($$(KEYBOARD_RULE),all) + # $$(info Skipping: No user keymap for $$(CURRENT_KB)) # Otherwise, make all keymaps, again this is consistent with how it works without # any arguments else @@ -554,14 +562,16 @@ endef %: # Check if we have the CMP tool installed cmp $(ROOT_DIR)/Makefile $(ROOT_DIR)/Makefile >/dev/null 2>&1; if [ $$? -gt 0 ]; then printf "$(MSG_NO_CMP)"; exit 1; fi; - # Ensure that python3 is installed. This check can be removed after python is used in more places. - if ! python3 --version 1> /dev/null 2>&1; then printf "$(MSG_PYTHON_MISSING)"; fi + # Ensure that bin/qmk works. This will be a failing check after the next develop merge on 2020 Aug 29. + if ! bin/qmk hello 1> /dev/null 2>&1; then printf "$(MSG_PYTHON_MISSING)"; fi # Check if the submodules are dirty, and display a warning if they are ifndef SKIP_GIT - if [ ! -e lib/chibios ]; then git submodule sync lib/chibios && git submodule update --depth 1 --init lib/chibios; fi - if [ ! -e lib/chibios-contrib ]; then git submodule sync lib/chibios-contrib && git submodule update --depth 1 --init lib/chibios-contrib; fi - if [ ! -e lib/ugfx ]; then git submodule sync lib/ugfx && git submodule update --depth 1 --init lib/ugfx; fi - if [ ! -e lib/lufa ]; then git submodule sync lib/lufa && git submodule update --depth 1 --init lib/lufa; fi + 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 \ @@ -618,13 +628,19 @@ 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) +$(shell echo '#define CHIBIOS_VERSION "$(CHIBIOS_VERSION)"' >> $(ROOT_DIR)/quantum/version.h) +$(shell echo '#define CHIBIOS_CONTRIB_VERSION "$(CHIBIOS_CONTRIB_VERSION)"' >> $(ROOT_DIR)/quantum/version.h) else BUILD_DATE := NA endif 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/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 876473fa43b..801852d4e8d 100755 --- a/bin/qmk +++ b/bin/qmk @@ -2,46 +2,60 @@ """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)) + +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 len(line) == 0 or line[0] == '#' or line.startswith('-r'): + continue + + if '#' in line: + line = line.split('#')[0] + + module = dict() + module['name'] = module['import'] = line.split('=')[0] if '=' in line else line + + # Not every module is importable by its own name. + if module['name'] == "pep8-naming": + module['import'] = "pep8ext_naming" + + 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) + + +developer = False # 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 - - if '#' in line: - line = line.split('#')[0] - - module = line.split('=')[0] if '=' in line else line - 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) - -# 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' +_check_modules('requirements.txt') # Setup the CLI -import milc +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}' @@ -61,7 +75,7 @@ def main(): os.chdir(qmk_dir) # Import the subcommands - import qmk.cli + import qmk.cli # noqa # Execute return_code = milc.cli() diff --git a/bootloader.mk b/bootloader.mk index d615533947b..e516e9ff9fd 100644 --- a/bootloader.mk +++ b/bootloader.mk @@ -82,6 +82,13 @@ 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)) diff --git a/build_json.mk b/build_json.mk index e2a33e3b6a5..6e2f9c4c8f2 100644 --- a/build_json.mk +++ b/build_json.mk @@ -21,7 +21,11 @@ else ifneq ("$(wildcard $(MAIN_KEYMAP_PATH_1)/keymap.json)","") KEYMAP_PATH := $(MAIN_KEYMAP_PATH_1) endif -# Generate the keymap.c -ifneq ("$(KEYMAP_JSON)","") - _ = $(shell test -e $(KEYMAP_C) || bin/qmk json-keymap $(KEYMAP_JSON) -o $(KEYMAP_C)) +# 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 json2c --quiet --output $(KEYMAP_C) $(KEYMAP_JSON) diff --git a/build_keyboard.mk b/build_keyboard.mk index b086420653f..4108704875d 100644 --- a/build_keyboard.mk +++ b/build_keyboard.mk @@ -231,44 +231,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,11 +279,6 @@ 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) - # Userspace setup and definitions ifeq ("$(USER_NAME)","") USER_NAME := $(KEYMAP) @@ -354,23 +324,17 @@ 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 +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 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..d13d9a515b8 100644 --- a/build_test.mk +++ b/build_test.mk @@ -41,6 +41,7 @@ all: elf VPATH += $(COMMON_VPATH) PLATFORM:=TEST +PLATFORM_KEY:=test ifneq ($(filter $(FULL_TESTS),$(TEST)),) include tests/$(TEST)/rules.mk diff --git a/common_features.mk b/common_features.mk index 83b2b51aed8..8443a759b3a 100644 --- a/common_features.mk +++ b/common_features.mk @@ -13,55 +13,45 @@ # 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)/keymap_common.c \ + $(QUANTUM_DIR)/keycode_config.c 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 $(AUDIO_ENABLE)), yes) 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_$(PLATFORM_KEY).c SRC += $(QUANTUM_DIR)/audio/voices.c SRC += $(QUANTUM_DIR)/audio/luts.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 @@ -80,26 +70,64 @@ 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 -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 +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 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 $(RGBLIGHT_ENABLE)), yes) @@ -107,23 +135,25 @@ ifeq ($(strip $(RGBLIGHT_ENABLE)), yes) OPT_DEFS += -DRGBLIGHT_ENABLE SRC += $(QUANTUM_DIR)/color.c SRC += $(QUANTUM_DIR)/rgblight.c - CIE1931_CURVE = yes - LED_BREATHING_TABLE = yes + CIE1931_CURVE := yes + RGB_KEYCODES_ENABLE := yes ifeq ($(strip $(RGBLIGHT_CUSTOM_DRIVER)), yes) OPT_DEFS += -DRGBLIGHT_CUSTOM_DRIVER else - SRC += ws2812.c + WS2812_DRIVER_REQUIRED := yes endif endif -VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 IS31FL3737 WS2812 custom +VALID_MATRIX_TYPES := yes IS31FL3731 IS31FL3733 IS31FL3737 IS31FL3741 WS2812 custom LED_MATRIX_ENABLE ?= no ifneq ($(strip $(LED_MATRIX_ENABLE)), no) ifeq ($(filter $(LED_MATRIX_ENABLE),$(VALID_MATRIX_TYPES)),) $(error LED_MATRIX_ENABLE="$(LED_MATRIX_ENABLE)" is not a valid matrix type) 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 @@ -146,11 +176,12 @@ endif SRC += $(QUANTUM_DIR)/color.c SRC += $(QUANTUM_DIR)/rgb_matrix.c SRC += $(QUANTUM_DIR)/rgb_matrix_drivers.c - CIE1931_CURVE = yes + CIE1931_CURVE := yes + RGB_KEYCODES_ENABLE := yes endif ifeq ($(strip $(RGB_MATRIX_ENABLE)), yes) - RGB_MATRIX_ENABLE = IS31FL3731 + RGB_MATRIX_ENABLE := IS31FL3731 endif ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3731) @@ -174,9 +205,16 @@ ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3737) QUANTUM_LIB_SRC += i2c_master.c endif +ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3741) + OPT_DEFS += -DIS31FL3741 -DSTM32_I2C -DHAL_USE_I2C=TRUE + COMMON_VPATH += $(DRIVER_PATH)/issi + SRC += is31fl3741.c + QUANTUM_LIB_SRC += i2c_master.c +endif + ifeq ($(strip $(RGB_MATRIX_ENABLE)), WS2812) OPT_DEFS += -DWS2812 - SRC += ws2812.c + WS2812_DRIVER_REQUIRED := yes endif ifeq ($(strip $(RGB_MATRIX_CUSTOM_KB)), yes) @@ -187,14 +225,8 @@ ifeq ($(strip $(RGB_MATRIX_CUSTOM_USER)), yes) OPT_DEFS += -DRGB_MATRIX_CUSTOM_USER 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 +ifeq ($(strip $(RGB_KEYCODES_ENABLE)), yes) + SRC += $(QUANTUM_DIR)/process_keycode/process_rgb.c endif ifeq ($(strip $(PRINTING_ENABLE)), yes) @@ -203,73 +235,90 @@ ifeq ($(strip $(PRINTING_ENABLE)), yes) 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_ENABLE = custom + BACKLIGHT_DRIVER := custom endif -VALID_BACKLIGHT_TYPES := yes custom +VALID_BACKLIGHT_TYPES := pwm software custom BACKLIGHT_ENABLE ?= no -ifneq ($(strip $(BACKLIGHT_ENABLE)), no) - ifeq ($(filter $(BACKLIGHT_ENABLE),$(VALID_BACKLIGHT_TYPES)),) - $(error BACKLIGHT_ENABLE="$(BACKLIGHT_ENABLE)" is not a valid backlight type) +BACKLIGHT_DRIVER ?= pwm +ifeq ($(strip $(BACKLIGHT_ENABLE)), yes) + ifeq ($(filter $(BACKLIGHT_DRIVER),$(VALID_BACKLIGHT_TYPES)),) + $(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_ENABLE)), custom) + ifeq ($(strip $(BACKLIGHT_DRIVER)), custom) OPT_DEFS += -DBACKLIGHT_CUSTOM_DRIVER + else + 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_$(strip $(BACKLIGHT_DRIVER)).c + endif + endif +endif + +VALID_WS2812_DRIVER_TYPES := bitbang pwm spi i2c + +WS2812_DRIVER ?= bitbang +ifeq ($(strip $(WS2812_DRIVER_REQUIRED)), yes) + ifeq ($(filter $(WS2812_DRIVER),$(VALID_WS2812_DRIVER_TYPES)),) + $(error WS2812_DRIVER="$(WS2812_DRIVER)" is not a valid WS2812 driver) endif - ifeq ($(PLATFORM),AVR) - SRC += $(QUANTUM_DIR)/backlight/backlight_avr.c + OPT_DEFS += -DWS2812_DRIVER_$(strip $(shell echo $(WS2812_DRIVER) | tr '[:lower:]' '[:upper:]')) + + ifeq ($(strip $(WS2812_DRIVER)), bitbang) + SRC += ws2812.c else - SRC += $(QUANTUM_DIR)/backlight/backlight_arm.c + SRC += ws2812_$(strip $(WS2812_DRIVER)).c endif + + # add extra deps + ifeq ($(strip $(WS2812_DRIVER)), i2c) + QUANTUM_LIB_SRC += i2c_master.c + endif +endif + +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_BREATHING_TABLE)), yes) - OPT_DEFS += -DUSE_LED_BREATHING_TABLE - LED_TABLES = yes + LED_TABLES := yes endif ifeq ($(strip $(LED_TABLES)), yes) @@ -286,62 +335,59 @@ 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 -HAPTIC_ENABLE ?= no -ifneq ($(strip $(HAPTIC_ENABLE)),no) - COMMON_VPATH += $(DRIVER_PATH)/haptic - SRC += haptic.c - OPT_DEFS += -DHAPTIC_ENABLE -endif - -ifneq ($(filter DRV2605L, $(HAPTIC_ENABLE)), ) - SRC += DRV2605L.c - QUANTUM_LIB_SRC += i2c_master.c - OPT_DEFS += -DDRV2605L -endif - -ifneq ($(filter SOLENOID, $(HAPTIC_ENABLE)), ) - SRC += solenoid.c - OPT_DEFS += -DSOLENOID_ENABLE -endif - -ifeq ($(strip $(HD44780_ENABLE)), yes) - SRC += drivers/avr/hd44780.c - OPT_DEFS += -DHD44780_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 $(LEADER_ENABLE)), yes) - SRC += $(QUANTUM_DIR)/process_keycode/process_leader.c - OPT_DEFS += -DLEADER_ENABLE +ifeq ($(strip $(DIP_SWITCH_ENABLE)), yes) + OPT_DEFS += -DDIP_SWITCH_ENABLE + SRC += $(QUANTUM_DIR)/dip_switch.c endif -include $(DRIVER_PATH)/qwiic/qwiic.mk +VALID_CUSTOM_MATRIX_TYPES:= yes lite no -QUANTUM_SRC:= \ - $(QUANTUM_DIR)/quantum.c \ - $(QUANTUM_DIR)/keymap_common.c \ - $(QUANTUM_DIR)/keycode_config.c +CUSTOM_MATRIX ?= no -# 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 + 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 @@ -364,13 +410,44 @@ ifeq ($(strip $(SPLIT_KEYBOARD)), yes) 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 + ifeq ($(PLATFORM),AVR) + QUANTUM_LIB_SRC += i2c_master.c \ + i2c_slave.c + endif + + SERIAL_DRIVER ?= bitbang + 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 +endif + +ifneq ($(filter DRV2605L, $(HAPTIC_ENABLE)), ) + SRC += DRV2605L.c + QUANTUM_LIB_SRC += i2c_master.c + OPT_DEFS += -DDRV2605L +endif + +ifneq ($(filter SOLENOID, $(HAPTIC_ENABLE)), ) + SRC += solenoid.c + OPT_DEFS += -DSOLENOID_ENABLE +endif + +ifeq ($(strip $(HD44780_ENABLE)), yes) + SRC += drivers/avr/hd44780.c + OPT_DEFS += -DHD44780_ENABLE +endif + ifeq ($(strip $(OLED_DRIVER_ENABLE)), yes) OPT_DEFS += -DOLED_DRIVER_ENABLE COMMON_VPATH += $(DRIVER_PATH)/oled @@ -378,14 +455,77 @@ 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 - -ifeq ($(strip $(DIP_SWITCH_ENABLE)), yes) - SRC += $(QUANTUM_DIR)/dip_switch.c - OPT_DEFS += -DDIP_SWITCH_ENABLE +MAGIC_ENABLE ?= yes +ifeq ($(strip $(MAGIC_ENABLE)), yes) + SRC += $(QUANTUM_DIR)/process_keycode/process_magic.c + 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 $(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 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/README.md b/docs/README.md index 22ab243cd25..4fd87268858 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,24 +9,35 @@ ## 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. +Totally new to QMK? There are two ways to get started: -Otherwise, you can either download it directly ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), or clone it via git (`git@github.com:qmk/qmk_firmware.git`), or https (`https://github.com/qmk/qmk_firmware.git`). +* Basic: [QMK Configurator](https://config.qmk.fm) + * Just select your keyboard from the dropdown and program your keyboard. + * We have an [introductory video](https://www.youtube.com/watch?v=-imgglzDMdY) you can watch. + * There is also an overview [document you can read](newbs_building_firmware_configurator.md). +* Advanced: [Use The Source](newbs.md) + * More powerful, but harder to use -## How to Compile +## Make It Yours -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: +QMK has lots of [features](features.md) to explore, and a good deal of reference documentation to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md). - make planck/rev4:default +## Need help? -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: +Check out the [support page](support.md) to see how you can get help using QMK. - make preonic:default +## Give Back -## How to Customize +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. -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). +* 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/_langs.md b/docs/_langs.md index c91e0d93fc5..f7b375fb945 100644 --- a/docs/_langs.md +++ b/docs/_langs.md @@ -1,4 +1,9 @@ - Translations - [:uk: English](/) - [:cn: 中文](/zh-cn/) + - [:es: Español](/es/) - [:fr: Français](/fr-fr/) + - [:he: עברית](/he-il/) + - [:brazil: Português](/pt-br/) + - [:ru: Русский](/ru-ru/) + - [:jp: 日本語](/ja/) diff --git a/docs/_summary.md b/docs/_summary.md index 65bfa11f09c..9ed55a3d062 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -1,121 +1,176 @@ -* [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) - * [Git Best Practices](newbs_best_practices.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) - * [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) + * [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) -* For Makers and Modders - * [Hand Wiring Guide](hand_wire.md) - * [ISP Flashing Guide](isp_flashing_guide.md) - * [ARM Debugging Guide](arm_debugging.md) - * [I2C Driver](i2c_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) - * [How to add translations](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) + * [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) + * [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) + * History + * [2020 May 30](ChangeLog/20200530.md) + * [2020 Feb 29](ChangeLog/20200229.md) + * [2019 Aug 30](ChangeLog/20190830.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) + * [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) + * [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) + * [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 new file mode 100644 index 00000000000..f8fb94094e8 --- /dev/null +++ b/docs/adc_driver.md @@ -0,0 +1,153 @@ +# ADC Driver + +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 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 + +To use this driver, add the following to your `rules.mk`: + +```make +SRC += analog.c +``` + +Then place this include at the top of your code: + +```c +#include "analog.h" +``` + +## Channels + +### AVR + +|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328/P| +|-------|-------------|-------------|---------|----------| +|0 |`F0` |`F0` |`A0` |`C0` | +|1 |`F1` |`F1` |`A1` |`C1` | +|2 |`F2` | |`A2` |`C2` | +|3 |`F3` | |`A3` |`C3` | +|4 |`F4` |`F4` |`A4` |`C4` | +|5 |`F5` |`F5` |`A5` |`C5` | +|6 |`F6` |`F6` |`A6` |* | +|7 |`F7` |`F7` |`A7` |* | +|8 | |`D4` | | | +|9 | |`D6` | | | +|10 | |`D7` | | | +|11 | |`B4` | | | +|12 | |`B5` | | | +|13 | |`B6` | | | + +\* 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-based, whereas the F3 has 4 ADCs and the channels are 1 based. This is because the F0 uses the `ADCv1` implementation of the ADC, whereas the F3 uses the `ADCv3` implementation. + +|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)". | +|`adc_read(mux)` |Reads the value from the ADC according to the specified mux. See your MCU's datasheet for more information. | + +### ARM + +Note that care was taken to match all of the functions used for AVR devices, however complications in the ARM platform prevent that from always being possible. For example, the `STM32` chips do not have assigned Arduino pins. We could use the default pin numbers, but those numbers change based on the package type of the device. For this reason, please specify your target pins with their identifiers (`A0`, `F3`, etc.). Also note that there are some variants of functions that accept the target ADC for the pin. Some pins can be used for multiple ADCs, and this specified can help you pick which ADC will be used to interact with that pin. + +|Function |Description | +|----------------------------|--------------------------------------------------------------------------------------------------------------------| +|`analogReadPin(pin)` |Reads the value from the specified QMK pin, eg. `A0` for channel 0 on the STM32F0 and ADC1 channel 1 on the STM32F3. Note that if a pin can be used for multiple ADCs, it will pick the lower numbered ADC for this function. eg. `C0` will be channel 6 of ADC 1 when it could be used for ADC 2 as well.| +|`analogReadPinAdc(pin, adc)`|Reads the value from the specified QMK pin and ADC, eg. `C0, 1` will read from channel 6, ADC 2 instead of ADC 1. Note that the ADCs are 0-indexed for this function.| +|`pinToMux(pin)` |Translates a given QMK pin to a channel and ADC combination. If an unsupported pin is given, returns the mux value for "0V (GND)".| +|`adc_read(mux)` |Reads the value from the ADC according to the specified pin and adc combination. See your MCU's datasheet for more information.| + +## 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. + +|`#define` |Type |Default |Description| +|-------------------|------|---------------------|-----------| +|ADC_CIRCULAR_BUFFER|`bool`|`false` |If `TRUE`, then the implementation will use a circular buffer.| +|ADC_NUM_CHANNELS |`int` |`1` |Sets the number of channels that will be scanned as part of an ADC operation. The current implementation only supports `1`.| +|ADC_BUFFER_DEPTH |`int` |`2` |Sets the depth of each result. Since we are only getting a 12-bit result by default, we set this to `2` bytes so we can contain our one value. This could be set to 1 if you opt for a 8-bit or lower result.| +|ADC_SAMPLING_RATE |`int` |`ADC_SMPR_SMP_1P5` |Sets the sampling rate of the ADC. By default, it is set to the fastest setting. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.| +|ADC_RESOLUTION |`int` |`ADC_CFGR1_RES_12BIT`|The resolution of your result. We choose 12 bit by default, but you can opt for 12, 10, 8, or 6 bit. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.| 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..28a7dd71da1 --- /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)" http://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 http://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..91d317f06bc --- /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](http://qmk.fm/). The stock keymap template supports all QMK keycodes that do not require supporting C code. Keyboard maintainers can supply their own custom templates to enable more functionality. + +## 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/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..154695ddacb 100644 --- a/docs/breaking_changes.md +++ b/docs/breaking_changes.md @@ -6,26 +6,28 @@ The breaking change period is when we will merge PR's that change QMK in dangero ## What has been included in past Breaking Changes? +* [2020 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 Aug 29, 2020. ### 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] 2020 May 30 - `develop` is created. It will be rebased weekly. +* [ ] 2020 Aug 1 - `develop` closed to new PR's. +* [ ] 2020 Aug 1 - Call for testers. +* [ ] 2020 Aug 27 - `master` is locked, no PR's merged. +* [ ] 2020 Aug 29 - Merge `develop` to `master`. +* [ ] 2020 Aug 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,9 +38,9 @@ Criteria for acceptance: This section documents various processes we use when running the Breaking Changes process. -## Rebase `future` from `master` +## Rebase `develop` from `master` -This is run every Friday while `future` is open. +This is run every Friday while `develop` is open. Process: @@ -46,31 +48,31 @@ Process: cd qmk_firmware git checkout master git pull --ff-only -git checkout future +git checkout develop git rebase master git push --force ``` -## Creating the `future` branch +## Creating the `develop` 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 +95,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_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 d150ee917de..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,120 +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 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 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 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 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..bb0de3c0db5 --- /dev/null +++ b/docs/cli_commands.md @@ -0,0 +1,291 @@ +# 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 +``` + +**Usage for Keymaps**: + +``` +qmk compile -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 +``` + +**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 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 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] +``` + +--- + +# 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 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 f5c7ad139a4..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`. @@ -173,3 +185,35 @@ You will only be able to access these arguments using `cli.args`. For example: ``` cli.log.info('Reading from %s and writing to %s', cli.args.filename, cli.args.output) ``` + +# Testing, and Linting, and Formatting (oh my!) + +We use nose2, flake8, and yapf to test, lint, and format code. You can use the `pytest` and `pyformat` subcommands to run these tests: + +### Testing and Linting + + qmk pytest + +### Formatting + + qmk pyformat + +## Formatting Details + +We use [yapf](https://github.com/google/yapf) to automatically format code. Our configuration is in the `[yapf]` section of `setup.cfg`. + +?> Tip- Many editors can use yapf as a plugin to automatically format code as you type. + +## Testing Details + +Our tests can be found in `lib/python/qmk/tests/`. You will find both unit and integration tests in this directory. We hope you will write both unit and integration tests for your code, but if you do not please favor integration tests. + +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 + +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. + +## Linting Details + +We use flake8 to lint our code. Your code should pass flake8 before you open a PR. This will be checked when you run `qmk pytest` and by CI when you submit a PR. diff --git a/docs/coding_conventions_c.md b/docs/coding_conventions_c.md index 08994bfbb74..f4e359611b7 100644 --- a/docs/coding_conventions_c.md +++ b/docs/coding_conventions_c.md @@ -14,17 +14,17 @@ Most of our style is pretty easy to pick up on, but right now it's not entirely * Think of them as a story describing the feature * Use them liberally to explain why particular decisions were made. * Do not write obvious comments - * If you not sure if a comment is obvious, go ahead and include it. + * If you're not sure if a comment is obvious, go ahead and include it. * In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns. * We use `#pragma once` at the start of header files rather than old-style include guards (`#ifndef THIS_FILE_H`, `#define THIS_FILE_H`, ..., `#endif`) * 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: diff --git a/docs/coding_conventions_python.md b/docs/coding_conventions_python.md index c7743050e20..47dff7f8eea 100644 --- a/docs/coding_conventions_python.md +++ b/docs/coding_conventions_python.md @@ -2,13 +2,13 @@ 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 * Use them liberally to explain why particular decisions were made. * Do not write obvious comments - * If you not sure if a comment is obvious, go ahead and include it. + * If you're not sure if a comment is obvious, go ahead and include it. * We require useful docstrings for all functions. * In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns. * Some of our practices conflict with the wider python community to make our codebase more approachable to non-pythonistas. @@ -77,9 +77,9 @@ Always use a .py filename extension. Never use dashes. ## Names to Avoid -* single character names except for counters or iterators. You may use "e" as an exception identifier in try/except statements. -* dashes (-) in any package/module name -* __double_leading_and_trailing_underscore__ names (reserved by Python) +* single character names except for counters or iterators. You may use `e` as an exception identifier in try/except statements. +* dashes (`-`) in any package/module name +* `__double_leading_and_trailing_underscore__` names (reserved by Python) # Docstrings @@ -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 6e3f8372c9b..ac90ed7464f 100644 --- a/docs/compatible_microcontrollers.md +++ b/docs/compatible_microcontrollers.md @@ -1,25 +1,37 @@ -# Atmel AVR +# Compatible Microcontrollers -QMK should run on any Atmel AVR processor with enough Flash. It has been tested on the following: +QMK runs on any USB-capable AVR or ARM microcontroller with enough flash space - generally 32kB or more, though it will *just* squeeze into 16kB with most features disabled. -* ATmega32U4 ([PJRC Teensy 2.0](http://www.pjrc.com/teensy/)) -* AT90USB1286 ([PJRC Teensy++ 2.0](http://www.pjrc.com/teensy/)) -* AT90USB1287 ([Atmel USBKEY](http://www.atmel.com/tools/AT90USBKEY.aspx)) -* ATmega168P with using [V-USB](http://www.obdev.at/products/vusb/index.html) -* ATmega328P with using [V-USB](http://www.obdev.at/products/vusb/index.html) -* ATmega32U2 -* AT90USB1286, 646, 647 should work -* AT90USB162 testing... +## Atmel AVR -NOTE: To enable full features of firmware you'll need 32KB flash size. +The following use [LUFA](https://www.fourwalledcubicle.com/LUFA.php) as the USB stack: -Please add any tested microcontrollers to this list. +* [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) -# ARM +Certain MCUs which do not have native USB will use [V-USB](https://www.obdev.at/products/vusb/index.html) instead: -You can also use any ARM processor that [ChibiOS](http://www.chibios.org) supports. The following processors have been tested: +* [ATmega32A](https://www.microchip.com/wwwproducts/en/ATmega32A) +* [ATmega328P](https://www.microchip.com/wwwproducts/en/ATmega328P) +* [ATmega328](https://www.microchip.com/wwwproducts/en/ATmega328) -* [Kinetis MKL26Z64](http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/kinetis-cortex-m-mcus/l-series-ultra-low-power-m0-plus/kinetis-kl2x-48-mhz-usb-ultra-low-power-microcontrollers-mcus-based-on-arm-cortex-m0-plus-core:KL2x) -* [Kinetis MK20DX128](http://www.nxp.com/assets/documents/data/en/data-sheets/K20P64M50SF0.pdf) -* [Kinetis MK20DX128](http://www.nxp.com/assets/documents/data/en/data-sheets/K20P64M50SF0.pdf) -* [Kinetis MK20DX256](http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/kinetis-cortex-m-mcus/k-series-performance-m4/k2x-usb/kinetis-k20-72-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-mcus-based-on-arm-cortex-m4-core:K20_72) +## 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: + +### 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) + +### NXP (Kinetis) + + * [MKL26Z64](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/kl-series-cortex-m0-plus/kinetis-kl2x-72-96-mhz-usb-ultra-low-power-microcontrollers-mcus-based-on-arm-cortex-m0-plus-core:KL2x) + * [MK20DX128](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k2x-usb/kinetis-k20-50-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-based-on-arm-cortex-m4-core:K20_50) + * [MK20DX256](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k2x-usb/kinetis-k20-72-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-mcus-based-on-arm-cortex-m4-core:K20_72) + +## Atmel ATSAM + +There is limited support for one of Atmel's ATSAM microcontrollers, that being the [ATSAMD51J18A](https://www.microchip.com/wwwproducts/en/ATSAMD51J18A) used by the [Massdrop keyboards](https://github.com/qmk/qmk_firmware/tree/master/keyboards/massdrop). diff --git a/docs/config_options.md b/docs/config_options.md index abd98ec8a80..81a3b4b61c9 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -43,8 +43,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 +51,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` @@ -78,7 +78,7 @@ This is a C header file that is one of the first things included, and will persi * `#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` @@ -113,9 +113,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 +134,25 @@ 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 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 +188,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` @@ -196,8 +211,8 @@ If you define these options you will enable the associated feature, which may in * units to step when in/decreasing saturation * `#define RGBLIGHT_VAL_STEP 12` * units to step when in/decreasing value (brightness) -* `#define RGBW_BB_TWI` - * bit-bangs TWI to EZ RGBW LEDs (only required for Ergodox EZ) +* `#define RGBW` + * Enables RGBW LED support ## Mouse Key Options @@ -233,7 +248,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 +290,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 +308,27 @@ 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. +* `LINK_TIME_OPTIMIZATION_ENABLE` + * Enables Link Time Optimization (LTO) when compiling the keyboard. This makes the process take longer, but it can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable). +However, this will automatically disable the legacy TMK Macros and Functions features, as these break when LTO is enabled. It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION`. (Note: This does not affect QMK [Macros](feature_macros.md) and [Layers](feature_layers.md).) +* `LTO_ENABLE` + * Has the same meaning as `LINK_TIME_OPTIMIZATION_ENABLE`. You can use `LTO_ENABLE` instead of `LINK_TIME_OPTIMIZATION_ENABLE`. ## AVR MCU Options * `MCU = atmega32u4` @@ -305,7 +345,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. @@ -347,8 +387,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 noticable). 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` ## USB Endpoint Limitations 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 04dc0da20fd..f325566fd06 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -85,7 +85,7 @@ Limited experimentation on the devices I have available shows that 7 is high eno Documentation is one of the easiest ways to get started contributing to QMK. Finding places where the documentation is wrong or incomplete and fixing those is easy! We also very badly need someone to edit our documentation, so if you have editing skills but aren't sure where or how to jump in please [reach out for help](#where-can-i-go-for-help)! -You'll find all our documentation in the `qmk_firmware/docs` directory, or if you'd rather use a web based workflow you can click "Suggest An Edit" at the top of each page on http://docs.qmk.fm/. +You'll find all our documentation in the `qmk_firmware/docs` directory, or if you'd rather use a web based workflow you can click the "Edit this page" link at the bottom of each page on https://docs.qmk.fm/. When providing code examples in your documentation, try to observe naming conventions used elsewhere in the docs. For example, standardizing enums as `my_layers` or `my_keycodes` for consistency: @@ -101,6 +101,18 @@ enum my_keycodes { }; ``` +### 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: + + ./bin/qmk docs + +or if you only have Python 3 installed: + + python3 -m http.server 8936 + +and navigating to `http://localhost:8936/`. + ## Keymaps Most first-time QMK contributors start with their personal keymaps. We try to keep keymap standards pretty casual (keymaps, after all, reflect the personality of their creators) but we do ask that you follow these guidelines to make it easier for others to discover and learn from your keymap. 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 839d49ca056..bf3a60377cd 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: @@ -90,68 +90,93 @@ keyrecord_t record { # LED Control -QMK provides methods to read the 5 LEDs defined as part of the HID spec: +QMK provides methods to read 5 of the LEDs defined in the HID spec: -* `USB_LED_NUM_LOCK` -* `USB_LED_CAPS_LOCK` -* `USB_LED_SCROLL_LOCK` -* `USB_LED_COMPOSE` -* `USB_LED_KANA` +* Num Lock +* Caps Lock +* Scroll Lock +* Compose +* Kana -These five constants correspond to the positional bits of the host LED state. -There are two ways to get the host LED state: +There are two ways to get the lock LED state: -* by implementing `led_set_user()` -* by calling `host_keyboard_leds()` +* 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()` -## `led_set_user()` +!> `host_keyboard_led_state()` may already reflect a new value before `led_update_user()` is called. -This function will be called when the state of one of those 5 LEDs changes. It receives the LED state as a parameter. -Use the `IS_LED_ON(usb_led, led_name)` and `IS_LED_OFF(usb_led, led_name)` macros to check the LED status. +Two more deprecated functions exist that provide the LED state as a `uint8_t`: -!> `host_keyboard_leds()` may already reflect a new value before `led_set_user()` is called. +* `uint8_t led_set_kb(uint8_t usb_led)` and `_user(uint8_t usb_led)` +* `uint8_t host_keyboard_leds()` -### Example `led_set_user()` Implementation +## `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 -void led_set_user(uint8_t usb_led) { - if (IS_LED_ON(usb_led, USB_LED_NUM_LOCK)) { - writePinLow(B0); - } else { - writePinHigh(B0); - } - if (IS_LED_ON(usb_led, USB_LED_CAPS_LOCK)) { - writePinLow(B1); - } else { - writePinHigh(B1); - } - if (IS_LED_ON(usb_led, USB_LED_SCROLL_LOCK)) { - writePinLow(B2); - } else { - writePinHigh(B2); - } - if (IS_LED_ON(usb_led, USB_LED_COMPOSE)) { - writePinLow(B3); - } else { - writePinHigh(B3); - } - if (IS_LED_ON(usb_led, USB_LED_KANA)) { - writePinLow(B4); - } else { - writePinHigh(B4); +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; } ``` -### `led_set_*` Function Documentation +### Example `led_update_user()` Implementation -* Keyboard/Revision: `void led_set_kb(uint8_t usb_led)` -* Keymap: `void led_set_user(uint8_t usb_led)` +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. -## `host_keyboard_leds()` +```c +#ifdef AUDIO_ENABLE + float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND); + float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND); +#endif -Call this function to get the last received LED state. This is useful for reading the LED state outside `led_set_*`, e.g. in [`matrix_scan_user()`](#matrix-scanning-code). -For convenience, you can use the `IS_HOST_LED_ON(led_name)` and `IS_HOST_LED_OFF(led_name)` macros instead of calling and checking `host_keyboard_leds()` directly. +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 @@ -288,13 +313,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) { @@ -318,6 +343,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)` @@ -369,7 +399,7 @@ void keyboard_post_init_user(void) { // Set default layer, if enabled if (user_config.rgb_layer_change) { rgblight_enable_noeeprom(); - rgblight_sethsv_noeeprom_cyan(); + rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); } } @@ -413,22 +443,22 @@ 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 - if (record->event.pressed) { + if (record->event.pressed) { user_config.rgb_layer_change ^= 1; // Toggles the status eeconfig_update_user(user_config.raw); // Writes the new status to EEPROM - if (user_config.rgb_layer_change) { // if layer state indication is enabled, + if (user_config.rgb_layer_change) { // if layer state indication is enabled, 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 - user_config.rgb_layer_change = false; // disable it, and + if (user_config.rgb_layer_change) { // only if this is enabled + user_config.rgb_layer_change = false; // disable it, and eeconfig_update_user(user_config.raw); // write the setings to EEPROM } } @@ -441,7 +471,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { And lastly, you want to add the `eeconfig_init_user` function, so that when the EEPROM is reset, you can specify default values, and even custom actions. To force an EEPROM reset, use the `EEP_RST` keycode or [Bootmagic](feature_bootmagic.md) functionallity. For example, if you want to set rgb layer indication by default, and save the default valued. ```c -void eeconfig_init_user(void) { // EEPROM is getting reset! +void eeconfig_init_user(void) { // EEPROM is getting reset! user_config.raw = 0; user_config.rgb_layer_change = true; // We want this enabled by default eeconfig_update_user(user_config.raw); // Write default value to EEPROM now @@ -461,31 +491,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/de/README.md b/docs/de/README.md new file mode 100644 index 00000000000..bf8fbac57a9 --- /dev/null +++ b/docs/de/README.md @@ -0,0 +1,33 @@ +# Quantum Mechanical Keyboard Firmware + +[![Aktuelle 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/) + +## 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. + +## 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. + +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`). + + +## Anleitung fürs Kompilieren + +Bevor Du in der Lage bist, die Firmware zu kompilieren, musst Du eine [Entwicklungsumgebung](de/getting_started_build_tools.md) für AVR und/oder ARM aufsetzen. Danach kannst Du mit dem `make` Befehl eine Keymap für deine Tastatur erzeugen. Die Notation dafür ist: + + make planck/rev4:default + +Dies generiert die Revision `rev4` für eine Tastatur vom Type `planck` mit der `default` Tastaturbelegung. Nicht alle Tastaturen haben Revisionen (auch bekannt als Subprojekt oder Unterordner) weswegen dies auch ausgelassen werden kann: + + make preonic:default + +## Möglichkeiten der Anpassung + +QMK hat viele [Features](de/features.md), die es zu entdecken gibt. In der [Dokumentation](https://docs.qmk.fmk) kannst Du Dir einen Überblick verschaffen. Die meisten Features basieren darauf, die [Tastaturbelegung](de/keymap.md) anzupassen und das Verhalten der [Keycodes](de/keycodes.md) zu verändern. diff --git a/docs/de/_summary.md b/docs/de/_summary.md new file mode 100644 index 00000000000..ffbd292bd45 --- /dev/null +++ b/docs/de/_summary.md @@ -0,0 +1,122 @@ +* [Anleitung für Anfänger](de/newbs.md) + * [Erste Schritte](de/newbs_getting_started.md) + * [Die erste Firmware](de/newbs_building_firmware.md) + * [Firmware flashen](de/newbs_flashing.md) + * [Testen und Debuggen](de/newbs_testing_debugging.md) + * [Git Tips und Tricks](de/newbs_best_practices.md) + * [Hilfreiche Ressourcen](de/newbs_learn_more_resources.md) + +* [QMK Basics](de/README.md) + * [QMK Einführung](de/getting_started_introduction.md) + * [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) + * [Nach Hilfe fragen](de/getting_started_getting_help.md) + +* [Breaking Changes](de/breaking_changes.md) + * [2019 Aug 30](de/ChangeLog/20190830.md) + +* [FAQ](de/faq.md) + * [Häufige Fragen](de/faq_general.md) + * [Build/Kompilieren](de/faq_build.md) + * [Debugging/Troubleshooting](de/faq_debug.md) + * [Keymap](de/faq_keymap.md) + * [Treiber Installation mit Zadig](de/driver_installation_zadig.md) + +* Detailierte Guides + * [Build Tools installieren](de/getting_started_build_tools.md) + * [Vagrant Guide](de/getting_started_vagrant.md) + * [Build/Compile Anleitung](de/getting_started_make_guide.md) + * [Firmware flashen](de/flashing.md) + * [Funktionalität anpassen](de/custom_quantum_functions.md) + * [Keymap Überblick](de/keymap.md) + +* [Hardware](de/hardware.md) + * [AVR Prozessoren](de/hardware_avr.md) + * [Treiber](de/hardware_drivers.md) + +* Referenz + * [Tastatur Richtlinien](de/hardware_keyboard_guidelines.md) + * [Konfigurations Optionen](de/config_options.md) + * [Keycodes](de/keycodes.md) + * [Coding Konventionen - C](de/coding_conventions_c.md) + * [Coding Konventionen - Python](de/coding_conventions_python.md) + * [Dokumentations Best Practices](de/documentation_best_practices.md) + * [Dokumentations Templates](de/documentation_templates.md) + * [Glossar](de/reference_glossary.md) + * [Unit Testing](de/unit_testing.md) + * [Nützliche Funktionen](de/ref_functions.md) + * [Configurator Support](de/reference_configurator_support.md) + * [info.json Format](de/reference_info_json.md) + * [Python CLI Development](de/cli_development.md) + +* [Features](de/features.md) + * [Basic Keycodes](de/keycodes_basic.md) + * [US ANSI Shifted Keys](de/keycodes_us_ansi_shifted.md) + * [Quantum Keycodes](de/quantum_keycodes.md) + * [Advanced Keycodes](de/feature_advanced_keycodes.md) + * [Audio](de/feature_audio.md) + * [Auto Shift](de/feature_auto_shift.md) + * [Backlight](de/feature_backlight.md) + * [Bluetooth](de/feature_bluetooth.md) + * [Bootmagic](de/feature_bootmagic.md) + * [Combos](de/feature_combo.md) + * [Command](de/feature_command.md) + * [Debounce API](de/feature_debounce_type.md) + * [DIP Switch](de/feature_dip_switch.md) + * [Dynamic Macros](de/feature_dynamic_macros.md) + * [Encoders](de/feature_encoders.md) + * [Grave Escape](de/feature_grave_esc.md) + * [Haptic Feedback](de/feature_haptic_feedback.md) + * [HD44780 LCD Controller](de/feature_hd44780.md) + * [Key Lock](de/feature_key_lock.md) + * [Layouts](de/feature_layouts.md) + * [Leader Key](de/feature_leader_key.md) + * [LED Matrix](de/feature_led_matrix.md) + * [Macros](de/feature_macros.md) + * [Mouse Keys](de/feature_mouse_keys.md) + * [OLED Driver](de/feature_oled_driver.md) + * [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) + * [RGB Matrix](de/feature_rgb_matrix.md) + * [Space Cadet](de/feature_space_cadet.md) + * [Split Keyboard](de/feature_split_keyboard.md) + * [Stenography](de/feature_stenography.md) + * [Swap Hands](de/feature_swap_hands.md) + * [Tap Dance](de/feature_tap_dance.md) + * [Terminal](de/feature_terminal.md) + * [Thermal Printer](de/feature_thermal_printer.md) + * [Unicode](de/feature_unicode.md) + * [Userspace](de/feature_userspace.md) + * [Velocikey](de/feature_velocikey.md) + +* Für Maker und Modder + * [Hand Wiring Guide](de/hand_wire.md) + * [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) + +* Für ein tieferes Verständnis + * [Wie Tastaturen funktionieren](de/how_keyboards_work.md) + * [QMK verstehen](de/understanding_qmk.md) + +* Andere Themen + * [Eclipse mit QMK](de/other_eclipse.md) + * [VSCode mit QMK](de/other_vscode.md) + * [Support](de/getting_started_getting_help.md) + * [Übersetzungen](de/translating.md) + +* QMK Internals (In Progress) + * [Defines](de/internals_defines.md) + * [Input Callback Reg](de/internals_input_callback_reg.md) + * [Midi Device](de/internals_midi_device.md) + * [Midi Device Setup Process](de/internals_midi_device_setup_process.md) + * [Midi Util](de/internals_midi_util.md) + * [Send Functions](de/internals_send_functions.md) + * [Sysex Tools](de/internals_sysex_tools.md) diff --git a/docs/de/cli.md b/docs/de/cli.md new file mode 100644 index 00000000000..437062ad667 --- /dev/null +++ b/docs/de/cli.md @@ -0,0 +1,169 @@ +# QMK CLI (Kommandozeile) + +Diese Seite beschreibt die Einrichtung und den Umgang mit dem QMK CLI (Kommandozeile). + +# Übersicht + +Die QMK CLI vereinfacht das Zusammenbauen und Arbeiten mit QMK Tastaturen. Hier findest Du wichtige Befehle, um beispielsweise das Herunterladen und Kompilieren der QMK Firmware oder das Erstellen von Tastaturbelegungen (und vieles mehr) zu erleichtern. + +* [Globale CLI](#globale-cli) +* [Lokale CLI](#lokale-cli) +* [CLI-Befehle](#cli-befehle) + +# System-Anforderungen + +Die CLI benötigt Python 3.5 oder höher. Außerdem ist es nötig, die Packages laut [`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt) zu installieren. + +# Globale CLI + +QMK bietet ein installierbares CLI, das Du zum Einrichten Deiner QMK Build-Umgebung verwenden kannst. Dieses ermöglicht Dir das Arbeiten mit QMK, und erleichtert das Arbeiten mit mehreren Kopien der `qmk_firmware`. Wir empfehlen, dieses CLI zu installieren und regelmäßig upzudaten. + +## Installation mit Homebrew (macOS, manche Linux) + +Solltest Du [Homebrew](https://brew.sh) installiert haben, kannst Du QMK per tap installieren: + +``` +brew tap qmk/qmk +brew install qmk +export QMK_HOME='~/qmk_firmware' # Optional: setzt den Installationsort für `qmk_firmware` +qmk setup # Dies klont `qmk/qmk_firmware` und richtet optional auch Deine Build-Umgebung ein +``` + +## Installation mit easy_install oder pip + +Falls Du kein Homebrew hast, kannst Du QMK auch manuell installieren. Zuerst musst Du sicherstellen, dass Python 3.5 (oder höher) und pip installiert ist. Dann installiere QMK mit diesem Befehl: + +``` +pip3 install qmk +export QMK_HOME='~/qmk_firmware' # Optional: setzt den Installationsort für `qmk_firmware` +qmk setup # Dies klont `qmk/qmk_firmware` und richtet optional auch Deine Build-Umgebung ein +``` +## Installation mit git Repo + +`git clone https://github.com/qmk/qmk_cli.git && cd qmk_cli && python3 setup.py install` + +## Packaging für andere Betriebssysteme + +Wir suchen nach Freiwilligen, die ein `qmk`-Package für weitere Betriebssysteme erstellen und pflegen. Falls Du ein Package für Dein OS erstellen möchtest, bitte befolge diese Richtlinien: + +* Verwende "Best Practices" für Dein OS, sollten sie mit diesen Richtlinien in Konflikt stehen. + * Dokumentiere den Grund in einem Kommentar, wenn Du abweichen musstest. +* Installiere mit einem [virtualenv](https://virtualenv.pypa.io/en/latest/). +* Weise den User an, die Umgebungs-Variable `QMK_HOME` zu setzen, um die Firmware-Quelle anders einzustellen als `~/qmk_firmware`. + +# Lokale CLI + +Wenn Du die globale CLI nicht verwenden möchtest, beinhaltet `qmk_firmware` auch eine lokale CLI. Du kannst sie hier finden: `qmk_firmware/bin/qmk`. Du kannst den `qmk`-Befehl aus irgendeinem Datei-Verzeichnis ausführen und es wird immer auf dieser Kopie von `qmk_firmware` arbeiten. + +**Beispiel**: + +``` +$ ~/qmk_firmware/bin/qmk hello +Ψ Hello, World! +``` + +## Einschränkungen der lokalen CLI + +Hier ein Vergleich mit der globalen CLI: + +* Die lokale CLI unterstützt kein `qmk setup` oder `qmk clone`. +* Die lokale CLI arbeitet immer innerhalb der selben `qmk_firmware`-Verzeichnisstruktur, auch wenn Du mehrere Repositories geklont hast. +* Die lokale CLI läuft nicht in einer virtualenv. Daher ist es möglich, dass Abhängigkeiten (dependencies) miteinander in Konflikt kommen/stehen. + +# CLI-Befehle + +## `qmk compile` + +Dieser Befehl erlaubt es dir, die Firmware - aus egal welchem Datei-Verzeichnis - zu compilen. Du kannst JSON-Exporte von oder Keymaps in der Repo kompilen. + +**Anwendung für Konfigurations-Exports**: + +``` +qmk compile +``` + +**Anwendung für Keymaps**: + +``` +qmk compile -kb -km +``` + +## `qmk cformat` + +Dieser Befehl formatiert C-Code im clang-Format. Benutze ihn ohne Argumente, um den core-Code zu formatieren, oder benutze Namen von Dateien in der CLI, um den Befehl auf bestimmte Dateien anzuwenden. + +**Anwendung**: + +``` +qmk cformat [file1] [file2] [...] [fileN] +``` + +## `qmk config` + +Dieser Befehl konfiguriert das Verhalten von QMK. Für die volle `qmk config`-Dokumentation gehe zu [CLI-Konfiguration](cli_configuration.md). + +**Anwendung**: + +``` +qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN] +``` + +## `qmk docs` + +Dieser Befehl startet einen lokalen HTTP-Server, den Du zum Browsen oder Verbessern der Dokumentation verwenden kannst. Der Default-Port ist 8936. + +**Anwendung**: + +``` +qmk docs [-p PORT] +``` + +## `qmk doctor` + +Dieser Befehl untersucht Deine Umgebung und warnt Dich vor potentiellen Build- oder Flash-Problemen. + +**Anwendung**: + +``` +qmk doctor +``` + +## `qmk list-keyboards` + +Dieser Befehl listet alle zurzeit in `qmk_firmware` definierten Tastaturen/Keyboards auf. + +**Anwendung**: + +``` +qmk list-keyboards +``` + +## `qmk new-keymap` + +Dieser Befehl erstellt eine neue Keymap basierend auf einer existierenden Standard-Keymap eines bestimmten Keyboards. + +**Anwendung**: + +``` +qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] +``` + +## `qmk pyformat` + +Dieser Befehl formatiert Python-Code in `qmk_firmware`. + +**Anwendung**: + +``` +qmk pyformat +``` + +## `qmk pytest` + +Dieser Befehl führt die Python Test Suite aus. Wenn Du Python-Code veränderst, solltest Du sicherstellen, dass der Test erfolgreich ausgeführt wurde. + +**Anwendung**: + +``` +qmk pytest +``` diff --git a/docs/de/driver_installation_zadig.md b/docs/de/driver_installation_zadig.md new file mode 100644 index 00000000000..bd04e05430b --- /dev/null +++ b/docs/de/driver_installation_zadig.md @@ -0,0 +1,47 @@ +# Bootloader Treiber Installation mit Zadig + +QMK erscheint für den Host als normales HID Eingabegerät und benötigt deshalb keine zusätzlichen Treiber. Der Bootloader, den Du für das Flashen der Firmware benötigst, jedoch meistens schon. + +Hierzu gibt es zwei Ausnahmen: den Caterina Bootloader, meistens auf Pro Micros, sowie den HalfKay Bootloader auf PJRC Teensys. Diese erscheinen als serieller Port und als generisches HID Gerät und benötigen keine Treiber. + +Wir empfehlen deshalb [Zadig](https://zadig.akeo.ie/). Wenn Du die Entwicklungsumgebung mit MSYS2 oder WSL installiert hast, wird dich dass `qmk_install.sh` Skript gefragt haben, ob es die Treiber für dich installieren sollte. + +## Installation + +Versetze deine Tastatur in den Bootloader-Modus, entweder durch Betätigung des physischen `RESET` Schalters - meist auf der Unterseite der Platine - oder durch das Auslösen des Key-Codes `RESET` bzw. `KC_RESET` (sollte in der zur Tastatur gehörigen `keycode.c` zu entnehmen sein). Sollte deine Tastatur weder noch besitzen, versuche es damit die `Escape`-Taste oder `Leertaste + B` zu halten während Du die Tastatur mit dem PC verbindest (Siehe auch [Bootmagic](de/feature_bootmagic.md) für weitere Details). Ein paar Tastaturen benutzen das [Command](de/feature_command.md)-Feature an Stelle von Bootmagic; in diesem Fall kannst du mit den Tastenkombinationen `linkes Shift + rechtes Shift + B` oder `linkes Shift + rechtes Shift + Escape` zu jeder Zeit in den Bootloader wechseln solange die Tastatur verbunden ist. + +Eingie Tastaturen haben u.U. spezielle Anweisungen um in den Bootloader-Modus zu gelangen. Zum Beispiel kann die [Bootmagic-Lite](de/feature_bootmagic.md#bootmagic-lite)-Taste (default: Escape) auf eine andere Taste gemappt sein; oder die magische Kombination (default: linkes Shift+rechtes Shift) verwendet anstatt Shift die STRG-Tasten. Die zur Tastatur gehörige README sollte dir Aufschluss darüber geben wie der Bootloader-Modus ausgelöst werden kann wenn Du unsicher bist. + +Um ein Gerät mit USBaspLoader in den Bootloader-Modus zu versetzen, halte `BOOT` gedrückt während Du den `RESET`-Knopf drückst. +Alternativ, halte `BOOT` gedrückt während Du das USB-Kabel einsteckst. + +Zadig sollte das Bootloader-Gerät automatisch erkennen. Manchmal musst Du zusätzlich noch **Options → List All Devices** auswählen. + + - Tastaturen mit Atmel AVR MCUs sollten als `ATm32U4DFU` (oder ähnlich) angezeigt werden, mit der Vendor ID `03EB`. + - USBasp werden als `USBasp` angezeigt, mit VID/PID `16C0:05DC`. + - Tastaturen AVR controller und dem QMK-DFU Bootloader haben den namen ` Bootloader` und die VID `03EB`. + - Die meisten ARM Tastaturen werden als `STM32 BOOTLOADER` angezeigt, mit VID/PID `0483:DF11`. + +!> Sollte Zadig ein oder mehrere Geräte mit `HidUsb`-Treiber anzeigen, dann ist deine Tastatur wahrscheinlich nicht im Bootloader-Modus. Der Pfeil wird orange eingefärbt sein und Du wirst nach einer Bestätigung gefragt um Veränderungen am System vorzunehmen. In diesem Fall **fahre nicht fort**! + +Wenn der Pfeil grün angezeigt wird, wähle den Treiber aus und klicke auf **Treiber installieren**. Der `libusb-win32`-Treiber sollte gewöhnlich für AVR verwendet werden und `WinUSB` für ARM. Sollte es danach noch nicht möglich sein die Tastatur zu flashen, versuche es mit einem anderen Treiber. Für USBaspLoader Geräte, die über die Befehlszeile mit MSYS2 geflasht werden, wird der `libusbk`-Treiber empfohlen. Ansonsten sollte `libusb-win32` funktionieren wenn die QMK Toolbox verwendet wird. + +![Zadig mit Bootloader-Treiber korrekt installiert](https://i.imgur.com/b8VgXzx.png) + +Entferne nun deine Tastatur und verbinde sie erneut um sicherzugehen dass der neue Treiber erfolgreich installiert wurde. Wenn Du QMK Toolbox benutzt, starte die Anwendung zur Sicherheit einmal neu, da Veränderungen am Treiber manchmal nicht richtig erkannt werden. Wenn dies immer noch nicht erfolgreich war hilft es an dieser Stelle manchmal ein Neustart des Computers. + +## Wiederherstellung einer Installation für ein falsches Gerät + +Wenn Du feststellst dass Du anschließend auf deiner Tastatur nicht mehr tippen kannst, ist etwas bei der Installation schief gelaufen. Ein häufiger Fehler ist es dass die Tastatur nicht im Bootloader-Modus war und stattdessen der Treiber für das HID-Gerät ersetzt wurde. Dies kannst Du einfach mit Zadig überprüfen, eine funktionierende Tastatur verwendet als Treiber `HidUsb` auf allen Interfaces . + +![Eine funktionierende Tastatur aus Zadigs Sicht](https://i.imgur.com/Hx0E5kC.png) + +Öffne den Geräte-Manager und suche nach einem Gerät das wie deine Tastatur aussieht. + +![Die Tastatur mit dem falschen Treiber installiert, im Geräte-Manager](https://i.imgur.com/L3wvX8f.png) + +Rechtsklick und **Gerät deinstallieren** anklicken. Bitte gehe sicher dass in diesem Schritt auch **Treibersoftware für dieses Gerät löschen** markiert ist. + +![Der "Gerät deinstallieren"-Dialog, mit "Treibersoftware für dieses Gerät entfernen" markiert](https://i.imgur.com/aEs2RuA.png) + +Klick **Aktion → Suche nach veränderter Hardware**. Nun solltest Du wieder in der Lage sein normal zu tippen. Vergewissere dich mit Hilfe von Zadig dass die Tastatur nun `HidUsb` als Treiber verwendet. Wenn dies der Fall ist sollte wieder alles funktionieren. diff --git a/docs/de/newbs.md b/docs/de/newbs.md new file mode 100644 index 00000000000..61139a99e1b --- /dev/null +++ b/docs/de/newbs.md @@ -0,0 +1,22 @@ +# Anleitung für absolute Beginner +QMK ist eine mächtige Open Source Firmware für mechanische Tastaturen. Mit QMK kannst Du deine Tastatur sowohl sehr einfach als auch sehr umfangreich anpassen. Menschen unterschiedlichen Wissensstandes - vom kompletten Anfänger bis zum erfahrenen Programmierer - haben ihre Tastaturen mit QMK erfolgreich auf ihre persönlichen Bedürfnisse angepasst. Diese Anleitung soll Dir unabhängig von deinen Vorkenntnissen dabei helfen dies ebenfalls zu bewältigen. + +Bist Du unsicher ob deine Tastatur QMK unterstützt? Wenn es eine mechanische Tastatur ist, die Du selbst gebaut hast, stehen deine Chancen gut. Wir unterstützen eine [Vielzahl](https://qmk.fm/keyboards/) selbst gebauter Tastaturen, sodass selbst wenn deine jetzige Tastatur nicht unterstützt wird Du keine Probleme haben solltest eine für deine Anforderungen zu finden. + +## Übersicht + +Diese Anleitung ist in 7 Abschnitte unterteilt: + +* [Die ersten Schritte](newbs_getting_started.md) +* [Die erste Firmware auf der Kommandozeile erzeugen](newbs_building_firmware.md) +* [Die erste Firmware mit der Online GUI erzeugen](newbs_building_firmware_configurator.md) +* [Firmware flashen](newbs_flashing.md) +* [Testen und Debuggen](newbs_testing_debugging.md) +* [Git Leitfaden](newbs_best_practices.md) +* [Weitere hilfreiche Ressourcen für Anfänger](newbs_learn_more_resources.md) + +Diese Anleitung richtet sich an Personen, die vorher noch nie Software kompiliert haben. Die Entscheidungen und Empfehlungen basieren auf dieser Grundannahme. Es gibt unterschiedliche Herangehensweisen für viele der Prozeduren und wir unterstützen die meisten Alternativen. Wenn Du mal nicht weiter weißt oder Dir nicht sicher bist, wie Du an ein Problem herangehen sollst, kannst Du uns gerne [um Hilfe bitten](getting_started_getting_help.md). + +## Weitere Ressourcen + +* [Thomas Baart's QMK Basics Blog](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – Ein äußerst hilfreicher Blog eines Community-Mitglieds, der einige Grundlagen der QMK-Firmware aus der Sicht des Benutzers erklärt (auf Englisch). diff --git a/docs/de/newbs_building_firmware.md b/docs/de/newbs_building_firmware.md new file mode 100644 index 00000000000..b6d48402499 --- /dev/null +++ b/docs/de/newbs_building_firmware.md @@ -0,0 +1,78 @@ +# Eine eigene Firmware erstellen + +Nachdem Du nun eine funktionierende Entwicklungsumgebung aufgesetzt hast, bist Du nun bereit, deine eigene Firmware zu erstellen. Dieses Sektion des Guides wird zwischen drei Programmen hin- und herwechseln: deinem Dateimanager, deinem Texteditor und der Befehlszeile. Lasse diese drei Fenster geöffnet, bis Du fertig und zufrieden mit deiner Tastatur-Firmware bist. + +Solltest Du die Befehlszeile zwischenzeitlich geschlossen haben, vergiss nicht wieder in das richtige Verzeichnis zu navigieren, benutze dazu den Befehl `cd qmk_firmware`. + +## Navigiere in deinen Keymap Ordner + +Beginne damit, in das `keymaps` Verzeichnis für deine Tastatur zu navigieren. + +Wenn Du macOS oder Windows benutzt, kannst Du einfach in das keymaps Verzeichnis wechseln. + +?> macOS:
+ open keyboards//keymaps + +?> Windows:
+ start .\\keyboards\\\\keymaps + +## Eine Kopie der `default` Tastaturbelegung erstellen + +Wenn Du den `keymaps` Ordner geöffnet hast, solltest Du zuerst eine Kopie des `default` Verzeichnisses erstellen. Wir empfehlen dafür deinen GitHub Benutzernamen zu verweden, aber Du kannst auch jeden anderen Namen verwenden solange er nur aus Kleinbuchstaben, Zahlen und Unterstrichen besteht. + +Um den Prozess zu automatisieren kannst Du dazu auch das Skript `new_keymap.sh` verwenden. + +Navigiere dazu in das `qmk_firmware/util` Verzeichnis und gib folgenden Befehl ein: + +``` +./new_keymap.sh +``` + +Um zum Beispiel den Benutzernamen John für die Tastaturbelegung eines 1up60hse zu verwenden, würdest Du Folgendes eingeben: + +``` +./new_keymap.sh 1upkeyboards/1up60hse john +``` + +## Öffne `keymap.c` in deinem bevorzugtem Text Editor + +Öffne deine `keymap.c`. In dieser Datei findest Du die Strukturen, die das Verhalten deiner Tastatur bestimmen. Oben in der `keymap.c` befinden sich Definitionen (defines) und Aufzählungen (enums), die die Tastaturbelegung leserlicher machen sollen. Weiter unten wirst Du eine Zeile finden, die wie folgt aussieht: + + const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { + +Diese Zeile markiert den Anfang der Liste der Ebenen (Layers). Darunter befinden sich Zeilen die entweder `LAYOUT` oder `KEYMAP` enthalten, das deutet auf den Start einer Ebene hin. Danach folgt eine Liste von Tasten, die dieser Ebene zugewiesen sind. + +!> Beim Bearbeiten einer Tastaturbelegung solltest Du darauf achten, keine Kommata hinzuzufügen oder zu entfernen. Ansonsten kann dies dazu führen, dass deine Firmware nicht mehr kompiliert und es ist nicht immer einfach festzustellen, wo genau ein Komma zuviel oder zu wenig ist. Die letzte Zeile hat am Ende kein Komma, die Zeilen davor jedoch schon. + +## Personalisiere die Tastaturbelegung nach deinen Wünschen + +Wie Du diesen Schritt abschließt ist vollkommen Dir überlassen. Ändere die eine Sache die Dich stört oder verändere alles von Grund auf. Du kannst Ebenen entfernen die Du nicht brauchst oder Neue hinzufügen, bis zu 32 Stück. Die folgende Dokumentation verrät Dir was Du hier alles definieren kannst: + +* [Keycodes](de/keycodes.md) +* [Features](de/features.md) +* [FAQ](de/faq.md) + +?> Während Du langsam ein Gefühl dafür kriegst wie Keymaps funktionieren, solltest Du darauf achten nicht zuviel auf einmal zu verändern. Größere Änderungen machen es schwieriger, Probleme zu debuggen. + +## Deine Firmware erzeugen + +Wenn Du damit fertig bist, deine Tastaturbelegung anzupassen, musst Du noch die Firmware erzeugen. Öffne dazu wieder die Befehlszeile und führe folgenden Befehl aus: + + make : + +Wenn deine Tastaturbelegung z.B. "xyverz" heißt und Du die Belegung für ein rev5 planck erzeugen möchtest, lautet der Befehl: + + make planck/rev5:xyverz + +Während des Kompiliervorgangs wird viel Text auf dem Bildschirm ausgegeben. Es sollte am Ende mit etwas enden das ungefähr so aussieht: + +``` +Linking: .build/planck_rev5_xyverz.elf [OK] +Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK] +Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK] +Checking file size of planck_rev5_xyverz.hex [OK] + * File size is fine - 18392/28672 +``` + +## Deine Firmware flashen +Bitte fahre mit [Firmware flashen](de/newbs_flashing.md) fort, um zu erfahren, wie Du deine neue Firmware auf deine Tastatur flashen kannst. diff --git a/docs/de/newbs_flashing.md b/docs/de/newbs_flashing.md new file mode 100644 index 00000000000..940438669e8 --- /dev/null +++ b/docs/de/newbs_flashing.md @@ -0,0 +1,369 @@ +# Deine Tastatur flashen + +Nachdem deine Firmware nun fertig ist musst Du Sie noch auf deine Tastatur flashen. + +## Flash-Vorgang mit QMK Toolbox + +Der einfachste Weg deine Tastatur zu flashen ist mit Hilfe der [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) + +Leider ist die QMK Toolbox derzeit nur für Windows und macOS verfügbar. Wenn Du Linux benutzt (oder es vorziehst die Firmware mit der Kommandozeile zu flashen) solltest Du die Methode benutzen die [hier](de/newbs_flashing.md#tastatur-mit-der-befehlszeile-flashen) beschrieben wird. + +### Lade die Datei in QMK Toolbox + +Beginne damit die Datei in der QMK Toolbox Anwendung zu laden. Versichere dich dass Du die Firmware-Datei im Finder oder Explorer findest. Deine Tastatur-Firmware sollte entweder vom Typ `.hex` oder `.bin` sein sein. QMK sollte die für deine Tastatur entsprechende Datei automatisch in das Root-Verzeichnis (normalerweise `qmk_firmware`) kopieren. + +?> Wenn Du Windows oder macOS benutzt kannst Du mit folgenden Befehlen ganz einfach das aktuelle Firmware-Verzeichnis im Explorer oder Finder öffnen. + +#### Windows: + +``` start . ``` + +#### macOS: + +``` open . ``` + +Die Firmware-Dateien folgen dabei immer folgendem Schema: + + _.{bin,hex} + +Zum Beispiel würde ein `planck/rev5` mit der `default` Tastaturbelegung folgenden Dateinamen haben: + + planck_rev5_default.hex + +Wenn Du die Firmware-Datei gefunden hast kannst Du sie in das "Local file" ("Lokale Datei") Feld in der QMK Toolbox ziehen, alternativ kannst Du auf "Öffnen" klicken und in das Verzeichnis navigieren indem sich die Firmware-Datei befindet. + +### Die Tastatur in den DFU (Bootloader) Modus versetzen + +Um deine angepasste Firmware auf deine Tastatur zu flashen musst Du diese erst in einen speziellen "flashing"-Modus versetzen. Während die Tastatur in diesem Modus ist kannst Du nicht auf ihr tippen oder sie wie gewohnt als Tastatur benutzen. Es ist wichtig dass der flashing-Prozesses nicht unterbrochen oder die Tastatur ausstöpselst wird, da der Vorgang ansonst wiederholt werden muss. + +Verschiedene Tastaturen verwenden unterschiedliche Methoden um in den Bootloader-Modus zu gelangen. Wenn dein PCB im Moment QMK oder TMK verwendet und Du keine spezifischen Anweisungen erhalten hast probiere die folgenden Methoden in dieser Reihenfolge: + +* Halte beide Shift-Tasten und drücke `Pause` +* Halte beide Shift-Tasten und drücke `B` +* Entferne deine Tastatur vom Computer, drücke gleichzeitig `Leertaste` und `B`, verbinde die Tastatur wieder mit dem Computer und warte eine Sekunde bevor Du die Tasten wieder loslässt. +* Drücke den physischen `RESET`-Knopf auf der Unterseite des PCBs +* Suche auf dem PCB den Pin mit dem Label `RESET`, verbinde diesen mit deinem GND-Pin +* Suche auf dem PCB den Pin mit dem Label `BOOT0`, verbinde diesen mit GND und schließe die Tastatur wieder an den PC an TODO: DIS IS DANGEROUS!! + +Wenn Du damit erfolgreich warst solltest Du in der QMK Toolbox eine Nachricht sehen die ungefähr so aussieht: + +``` +*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 +*** DFU device connected +``` + +### Tastatur flashen + +Klicke auf den `Flash`-Knopf in der QMK Toolbox. Die Ausgabe wird ungefähr so aussehen: + +``` +*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 +*** DFU device connected +*** Attempting to flash, please don't remove device +>>> dfu-programmer atmega32u4 erase --force + Erasing flash... Success + Checking memory from 0x0 to 0x6FFF... Empty. +>>> dfu-programmer atmega32u4 flash qmk_firmware/clueboard_66_hotswap_skully.hex + Checking memory from 0x0 to 0x55FF... Empty. + 0% 100% Programming 0x5600 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + 0% 100% Reading 0x7000 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + Validating... Success + 0x5600 bytes written into 0x7000 bytes memory (76.79%). +>>> dfu-programmer atmega32u4 reset + +*** DFU device disconnected +*** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390 +``` + +## Tastatur mit der Befehlszeile flashen + +Zunächst solltest Du versuchen herauszufinden welchen Bootlader deine Tastatur benutzt. Diese vier Bootloader sind am Weitesten verbreitet: + +| MCU | Bootloader | +| --- | --- | +| Pro-Micro und Klone | CATERINA | +| Teensy | Halfkay | +| OLKB Boards | QMK-DFU | +| sonstige atmega32u4 | DFU | + +Auf der Seite [Flash Anleitung und Bootloader Informationen](de/flashing.md) kannst Du mehr über das Thema erfahren. + +Wenn Du weißt welchen Bootloader deine Tastaur verwendet, kannst Du diese Information bei der Kompilation hinzufügen um den Flash-Vorgang mit dem `make`-Befehl zu automatisieren. +```rules.mk +... +BOOTLOADER = caterina +... +``` + +### DFU + +Wenn Du den DFU-Bootloader verwendest und Du bereit bist deine Firmware zu kompilieren und zu flashen, öffne ein Befehlszeile und führe folgenden Befehl aus: + + make ::dfu + +Wenn deine Tastaturbelegung z.B den Namen "xzverz" trägt und Du ein rev5 planck flashen möchtest sähe der Befehl wie folgt aus: + + make planck/rev5:xyverz:dfu + + +Nachdem der Vorgang abgeschlossen ist sollte die Ausgabe ungefähr so aussehen: + +``` +Linking: .build/planck_rev5_xyverz.elf [OK] +Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK] +Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK] +Checking file size of planck_rev5_xyverz.hex + * File size is fine - 18574/28672 + ``` + +Wenn dieser Punkt erreicht ist wird das Build-Skript alle 5 Sekunden nach einem DFU Bootloader suchen. Dieser Vorgang wird wiederholt bis er erfolgreich ist oder abgebrochen wird. + + dfu-programmer: no device present. + Error: Bootloader not found. Trying again in 5s. + +Wenn diese Nachricht erscheint konnte das Build-Skript den Controller nicht eigenständig in den DFU Modus versetzen (z.B. weil der Modus in rules.mk falsch gesetzt wurde oder ein Problem mit der Hardware besteht), wenn dies eintritt musst Du die oben beschrieben Schritte benutzen um den Controller in den DFU Modus zu versetzen. Danach sollte die Ausgabe ungefähr so aussehen: + +``` +*** Attempting to flash, please don't remove device +>>> dfu-programmer atmega32u4 erase --force + Erasing flash... Success + Checking memory from 0x0 to 0x6FFF... Empty. +>>> dfu-programmer atmega32u4 flash qmk_firmware/clueboard_66_hotswap_skully.hex + Checking memory from 0x0 to 0x55FF... Empty. + 0% 100% Programming 0x5600 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + 0% 100% Reading 0x7000 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + Validating... Success + 0x5600 bytes written into 0x7000 bytes memory (76.79%). +>>> dfu-programmer atmega32u4 reset +``` + +?> Wenn Du mit diesem Schritt Probleme hast (z.B. `dfu-programmer: no device present`) hilft dir hoffentlich der Abschnitt [Häufig gestellte Fragen (Build/Kompilieren)](de/faq_build.md). + +#### DFU Befehle + +Es gibt verschiedene DFU Befehle um die Firmware auf ein DFU Gerät zu flashen: + +* `:dfu` - Dies ist die default Option. Es wird gecheckt ob ein DFU Gerät verfügbar ist, ist dies der Fall wird die Firmware geflasht. Dieser Check wird alle 5 Sekunden ausgeführt bis ein DFU Gerät erkannt wird. +* `:dfu-ee` - Der Flash-Vorgang benutzt eine `.eep` Datei anstatt einer `.hex` Datei. Dies ist eher unüblich. +* `:dfu-split-left` - Dies flasht die Firmware wie gewohnt (`:dfu`). Allerdings nur die "linke Seite" der EEPROM für geteilte Tastaturen. _Dies ist ideal für auf Elite C basierenden geteilten Tastaturen._ +* `:dfu-split-right` - Dies flasht die Firmware wie gewohnt (`:dfu`). Allerdings nur die "rechte Seite" der EEPROM für geteilte Tastaturen. _Dies ist ideal für auf Elite C basierenden geteilten Tastaturen._ + + +### Caterina +Für Arduinos und andere ProMicro Klone (z.B. SparkFun ProMicro), wenn Du bereit bist zu kompilieren und die Tastatur zu flashen, öffne ein Befehlszeilen-Fenster und führe den Build-Befehl aus: + + make ::avrdude + +Wenn deine Tastaturbelegung zum Beispiel den Namen "xyverz" hat und Du eine Tastaturbelegung für ein "rev2 Lets Split" erzeugen möchtest, lautet der Befehl dafür: + + make lets_split/rev2:xyverz:avrdude + +Nachdem die Kompilation abgeschlossen ist sollte die Ausgabe ungefähr so aussehen: + +``` +Linking: .build/lets_split_rev2_xyverz.elf [OK] +Creating load file for flashing: .build/lets_split_rev2_xyverz.hex [OK] +Checking file size of lets_split_rev2_xyverz.hex [OK] + * File size is fine - 27938/28672 +Detecting USB port, reset your controller now.............. +``` + +Nun wird die Tastatur automatisch zurückgesetzt und das Skript wird die Firmware flashen sobald es den Bootloader erkennt. Die Ausgabe sollte ungefähr so aussehen: + +``` +Detected controller on USB port at /dev/ttyS15 + +Connecting to programmer: . +Found programmer: Id = "CATERIN"; type = S + Software Version = 1.0; No Hardware Version given. +Programmer supports auto addr increment. +Programmer supports buffered memory access with buffersize=128 bytes. + +Programmer supports the following devices: + Device code: 0x44 + +avrdude.exe: AVR device initialized and ready to accept instructions + +Reading | ################################################## | 100% 0.00s + +avrdude.exe: Device signature = 0x1e9587 (probably m32u4) +avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed + To disable this feature, specify the -D option. +avrdude.exe: erasing chip +avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex" +avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex +avrdude.exe: writing flash (27938 bytes): + +Writing | ################################################## | 100% 2.40s + +avrdude.exe: 27938 bytes of flash written +avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex: +avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex: +avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex +avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes +avrdude.exe: reading on-chip flash data: + +Reading | ################################################## | 100% 0.43s + +avrdude.exe: verifying ... +avrdude.exe: 27938 bytes of flash verified + +avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF) + +avrdude.exe done. Thank you. +``` +Sollten dabei Probleme auftreten (z.B. "Zugriff verweigert" / "Permission denied") muss der Make-Befehl mit privilegierten Berechtigungen ausgeführt werden: + + sudo make ::avrdude + +Zusätzlich ist es möglich mehrere Tastaturen in einem Vorgang zu flashen: + + make ::avrdude-loop + +Du kannst den Loop mit STRG + C unterbrechen sobald der Vorgang abgeschlossen ist. Die korrekte Tastenkombination kann abweichen und hängt vom Betriebssystem ab. + + +### HalfKay + +Für Tastaturen mit PJRC Controllern (Teensy's), wenn Du bereit bist zu kompilieren und die Tastatur zu flashen, öffne ein Befehlszeilen-Fenster und führe den Build-Befehl aus: + + make ::teensy + +Wenn deine Tastaturbelegung zum Beispiel den Namen "xyverz" hat und Du eine Tastaturbelegung für ein Ergodox oder Ergodox EZ erzeugen möchtest, lautet der Befehl dafür: + + make ergodox_ez:xyverz:teensy + +Nachdem die Kompilation abgeschlossen ist sollte die Ausgabe ungefähr so aussehen: + +``` +Linking: .build/ergodox_ez_xyverz.elf [OK] +Creating load file for flashing: .build/ergodox_ez_xyverz.hex [OK] +Checking file size of ergodox_ez_xyverz.hex [OK] + * File size is fine - 25584/32256 + Teensy Loader, Command Line, Version 2.1 +Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage +Waiting for Teensy device... + (hint: press the reset button) + ``` + +An diesem Punkt solltest Du die Tastatur zurücksetzen um den Flash-Vorgang auszulösen. Wenn dies abgeschlossen ist sollte die Ausgabe ungefähr so aussehen: + + ``` +Found HalfKay Bootloader +Read "./.build/ergodox_ez_xyverz.hex": 28532 bytes, 88.5% usage +Programming............................................................. +................................................... +Booting +``` + +### BootloadHID + +Für auf Bootmapper Client(BMC)/bootloaderHID/ATmega32A basierende Tastaturen, wenn Du bereit bist zu kompilieren und die Tastatur zu flashen, öffne ein Befehlszeilen-Fenster und führe den Build-Befehl aus: + + make ::bootloaderHID + +Wenn deine Tastaturbelegung zum Beispiel den Namen "xyverz" hat und Du eine Tastaturbelegung für ein jj40 erzeugen möchtest, lautet der Befehl dafür: + + make jj40:xyverz:bootloaderHID + +Nachdem die Kompilation abgeschlossen ist sollte die Ausgabe ungefähr so aussehen: + +``` +Linking: .build/jj40_default.elf [OK] +Creating load file for flashing: .build/jj40_default.hex [OK] +Copying jj40_default.hex to qmk_firmware folder [OK] +Checking file size of jj40_default.hex [OK] + * The firmware size is fine - 21920/28672 (6752 bytes free) +``` + +Wenn dieser Punkt erreicht ist wird das Build-Skript alle 5 Sekunden nach einem DFU Bootloader suchen. Dieser Vorgang wird wiederholt bis er erfolgreich ist oder abgebrochen wird. + +``` +Error opening HIDBoot device: The specified device was not found +Trying again in 5s. +``` + +An diesem Punkt solltest Du die Tastatur zurücksetzen um den Flash-Vorgang auszulösen. Wenn dies abgeschlossen ist sollte die Ausgabe ungefähr so aussehen: + +``` +Page size = 128 (0x80) +Device size = 32768 (0x8000); 30720 bytes remaining +Uploading 22016 (0x5600) bytes starting at 0 (0x0) +0x05580 ... 0x05600 +``` + +### STM32 (ARM) + +Für die meisten ARM Tastaturen (inkl. Proton C, Planck Rev 6 und Preonic Rev 3), wenn Du bereit bist zu kompilieren und die Tastatur zu flashen, öffne ein Befehlszeilen-Fenster und führe den Build-Befehl aus: + + make ::dfu-util + +Wenn deine Tastaturbelegung zum Beispiel den Namen "xyverz" hat und Du eine Tastaturbelegung für ein Planck Revision 6 erzeugen möchtest, benutze dafür den folgenden Befehl und reboote die Tastatur in den Bootloader (kurz bevor der Kompiliervorgang abgeschlossen ist): + + make planck/rev6:xyverz:dfu-util + +Nachdem der Kompiliervorgang abgeschlossen ist sollte die Ausgabe ungefähr so aussehen: + +Für auf Bootmapper Client(BMC)/bootloaderHID/ATmega32A basierende Tastaturen, wenn Du bereit bist zu kompilieren und die Tastatur zu flashen, öffne ein Befehlszeilen-Fenster und führe den Build-Befehl aus: + + make ::bootloaderHID + +Wenn deine Tastaturbelegung zum Beispiel den Namen "xyverz" hat und Du eine Tastaturbelegung für ein jj40 erzeugen möchtest, lautet der Befehl dafür: +``` +Linking: .build/planck_rev6_xyverz.elf [OK] +Creating binary load file for flashing: .build/planck_rev6_xyverz.bin [OK] +Creating load file for flashing: .build/planck_rev6_xyverz.hex [OK] + +Size after: + text data bss dec hex filename + 0 41820 0 41820 a35c .build/planck_rev6_xyverz.hex + +Copying planck_rev6_xyverz.bin to qmk_firmware folder [OK] +dfu-util 0.9 + +Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. +Copyright 2010-2016 Tormod Volden and Stefan Schmidt +This program is Free Software and has ABSOLUTELY NO WARRANTY +Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ + +Invalid DFU suffix signature +A valid DFU suffix will be required in a future dfu-util release!!! +Opening DFU capable USB device... +ID 0483:df11 +Run-time device DFU version 011a +Claiming USB DFU Interface... +Setting Alternate Setting #0 ... +Determining device status: state = dfuERROR, status = 10 +dfuERROR, clearing status +Determining device status: state = dfuIDLE, status = 0 +dfuIDLE, continuing +DFU mode device DFU version 011a +Device returned transfer size 2048 +DfuSe interface name: "Internal Flash " +Downloading to address = 0x08000000, size = 41824 +Download [=========================] 100% 41824 bytes +Download done. +File downloaded successfully +Transitioning to dfuMANIFEST state +``` + +#### STM32 Befehle + +Für Tastaturen mit STM32 Controller sind die DFU Befehle wie folgt: + +* `:dfu-util` - The default command for flashing to STM32 devices. +* `:dfu-util` - Der Standard-Befehl für STM32 Geräte. +* `:dfu-util-wait` - Funktioniert wie der Standard-Befehl, aber mit einem 10 Sekunden Timeout bevor erneut versucht wird die Firmware zu flashen. Mit dem Parameter `TIME_DELAY=20` auf der Befehlszeile kann der Timeout beeinflusst werden. + * z.B.: `make ::dfu-util TIME_DELAY=5` +* `:dfu-util-split-left` - Gleiche Funktionsweise wie `dfu-util`, jedoch wird zusätzlich das EEPROM Setting "linke Seite" für geteilte Tastaturen gesetzt. +* `:dfu-util-split-right` - Gleiche Funktionsweise wie `dfu-util`, jedoch wird zusätzlich das EEPROM Setting "rechte Seite" für geteilte Tastaturen gesetzt. + +## Probier's aus! + +Herzlichen Glückwunsch! Deine individuell angepasst Firmware wurde auf deine Tastatur übertragen! + + Probiere deine neue Tastatur aus und gehe sicher dass alles wie gewünscht funktioniert. Wir haben einen weiteren Artikel zum Thema [Testen und Debuggen](de/newbs_testing_debugging.md) verfasst der sich mit Problembeseitigung beschäftigt um den Beginnger-Guide abzuschließen. diff --git a/docs/de/newbs_getting_started.md b/docs/de/newbs_getting_started.md new file mode 100644 index 00000000000..8240f2bafa0 --- /dev/null +++ b/docs/de/newbs_getting_started.md @@ -0,0 +1,101 @@ +# Einleitung +Genau wie in einem Computer befindet sich auch in einer Tastatur ein Prozessor. + +Dieser Prozessor führt Software aus, die registriert wenn Tasten gedrückt bzw. wieder losgelassen werden und leitet die entsprechenden Signale an den Computer weiter. + +QMK übernimmt die Rolle dieser Software und teilt dem Host-Computer den aktuellen Zustand der Tastatur mit. Wenn Du eine Tastaturbelegung definierst, ist dies äquivalent zu einem ausführbarem Programm, das auf deiner Tastatur läuft. + +QMK möchte seine BenutzerInnen in die Lage versetzen, simple Aufgaben möglichst einfach zu gestalten und gleichzeitig komplexe Dinge zu ermöglichen, die mit normalen Tastaturen ohne zusätzliche Software undenkbar wären. Du musst nicht programmieren können, um abgefahrene Tastaturbelegungen zu gestalten - es reicht wenn Du eine Idee hast und ein paar einfache syntaktische Regeln verstehen kannst. + +# Los geht's! +Bevor Du damit loslegen kannst, deine Tastaturbelegung zu erstellen, musst Du ein wenig Software installieren und Dir eine Entwicklungsumgebung aufsetzen. Die gute Nachricht ist, dass das nur einmal erledigt werden muss, egal für wie viele verschiedene Tastaturen Du hinterher Firmware entwickeln willst. + +Wenn Du es vorziehst mit einer grafischen Oberfläche zu entwickeln kannst Du auch dazu gerne direkt mit dem online [QMK Konfigurator](https://config.qmk.fm) loslegen. Siehe auch: [Firmware mit der Online GUI erzeugen](de/newbs_building_firmware_configurator.md) + +## Software herunterladen + +### Text Editor + +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/). + +?> 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). + +### QMK Toolbox + +QMK Toolbox ist ein optionales grafisches Programm für Windows und macOS, das es erleichtern soll, deine Tastatur zu programmieren und zu debuggen. Du wirst es höchstwahrscheinlich früher oder später als unverzichtbar ansehen, wenn es darum geht eine Tastatur einfach zu flashen oder zu debuggen, da es ermöglicht, sich debug-Nachrichten direkt anzeigen zu lassen. + +[Hier kannst Du die aktuelle Version herunterladen.](https://github.com/qmk/qmk_toolbox/releases/latest) + +* Für Windows: `qmk_toolbox.exe` (portable) oder `qmk_toolbox_install.exe` (installer) +* Für macOS: `QMK.Toolbox.app.zip` (portable) oder `QMK.Toolbox.pkg` (installer) + +## Die Entwicklungsumgebung aufsetzen + + +Wir haben versucht, die Installation der Entwicklungsumgebung für QMK so einfach wie möglich zu gestalten. Alles, was Du tun musst, ist eine Linux oder Unix Umgebung aufzusetzen, danach macht QMK den Rest. + +?> Wenn Du das erste Mal mit der Linux/Unix Befehlszeile arbeitest, schadet es nicht, sich mit ein paar Grundlagen und Befehlen vertraut zu machen. Diese Ressourcen sollten ausreichen, um sich das Nötigste anzueignen um mit QMK arbeiten zu können:
+[Erforderliche Linux Grundlagen](https://www.guru99.com/must-know-linux-commands.html)
+[Noch ein paar Linux Befehle](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html) + +### Windows + +Du wirst MSYS2 (o.Ä.) und Git benötigen. + +* Befolge die Installationsanleitung auf der [MSYS2 Homepage](http://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` + +### macOS + +Du wirst Homebrew benötigen. Folge dafür den Anweisungen auf der [Homebrew homepage](https://brew.sh). + +Nachdem Homebrew erfolgreich installiert ist, kannst Du mit _QMK aufsetzen_ fortfahren. + +### Linux + +Du benötigst Git, aber es ist ziemlich wahrscheinlich, dass es bereits installiert ist. Sollte dies nicht der Fall sein, kannst Du es mit dem folgenden Aufruf installieren: + +* Debian / Ubuntu / Devuan: `apt-get install git` +* Fedora / Red Hat / CentOS: `yum install git` +* Arch Linux: `pacman -S git` + +?> Docker ist ebenfalls eine Option für alle Plattformen. [Hier](de/getting_started_build_tools.md#docker) kannst Du dazu weitere Informationen finden. + +## QMK aufsetzen +Wenn Du damit fertig bist, deine Linux/Unix Umgebung zu installieren, kannst Du damit fortfahren QMK herunterzuladen. Dafür werden wir mit Git das QMK Repository "klonen". Öffne ein Terminal oder ein MSYS2 MinGW Fenster, dies wirst Du für den Rest der Anleitung benötigen. In diesem Fenster rufst Du nun die beiden folgenden Kommandos auf: + +```shell +git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git +cd qmk_firmware +``` +?> Wenn Du bereits weißt, [wie man GitHub benutzt](de/getting_started_github.md), empfehlen wir, dass Du Dir ein eigenen Fork erstellst. Wenn Du nicht weißt, was das bedeuten soll, kannst Du diesen Ratschlag getrost ignorieren. + +QMK liefert ein Script mit, das helfen soll, Dir alles Weitere abzunehmen. Du kannst es mit dem folgenden Befehl aufrufen: + + util/qmk_install.sh + +## Die Build-Umgebung testen + +Nun sollte hoffentlich alles Nötige für eine funktionierende QMK Build-Umgebung installiert sein und Du solltest in der Lage sein, die QMK-Firmware zu kompilieren. Um dies mit einer `default` Tastaturbelegung zu testen, kannst Du den folgenden Befehl ausprobieren: + + make :default + +Der Befehl um z.B. die Firmware für ein _Clueboard 66%_ zu erzeugen lautet: + + make clueboard/66/rev3:default + +Wenn es fertig ist, sollte der Output ungefähr so ähnlich wie das Folgende aussehen: + +``` +Linking: .build/clueboard_66_rev3_default.elf [OK] +Creating load file for flashing: .build/clueboard_66_rev3_default.hex [OK] +Copying clueboard_66_rev3_default.hex to qmk_firmware folder [OK] +Checking file size of clueboard_66_rev3_default.hex [OK] + * The firmware size is fine - 26356/28672 (2316 bytes free) +``` + +# Eine eigene Tastaturbelegung erstellen +Du bist nun fertig mit dem Setup der Entwicklungsumgebung und solltest somit in der Lage sein, deine eigenen Tastaturbelegungen zu erstellen. Um fortzufahren, folge bitte der nächsten Anleitung unter [Die erste Firmware](de/newbs_building_firmware.md). diff --git a/docs/de/newbs_learn_more_resources.md b/docs/de/newbs_learn_more_resources.md new file mode 100644 index 00000000000..ac5adb0c12f --- /dev/null +++ b/docs/de/newbs_learn_more_resources.md @@ -0,0 +1,14 @@ +# Lernmaterial + +Diese weiterführenden Ressourcen sind darauf ausgerichtet, Neulingen der QMK Commmunity mehr Informationen und ein besseres Verständnis zu einzelnen Themen zu bieten. + +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 Git im Bezug zu QMK](contributing.md) + +Mehr über die Arbeit mit der Befehlszeile: + +* [Gutes allgemeines Tutorial über die Arbeit mit der Befehlszeile](https://www.codecademy.com/learn/learn-the-command-line) (auf Englisch) diff --git a/docs/de/newbs_testing_debugging.md b/docs/de/newbs_testing_debugging.md new file mode 100644 index 00000000000..acc067e10f9 --- /dev/null +++ b/docs/de/newbs_testing_debugging.md @@ -0,0 +1,100 @@ +# Testen und Debuggen + +Nachdem Du deine Tastatur mit deiner angepassten Firmware geflasht hast, ist es nun an der Zeit sie auszuprobieren. Mit ein bisschen Glück sollte alles ohne Probleme funktionieren, wenn dies nicht der Fall ist, soll dieses Dokument dir dabei helfen, herauszufinden wo das Problem liegt. + +## Testen + +Die Tastatur zu testen ist relativ selbsterklärend. Drücke jede der Tasten um dich zu versichern, dass der gesendete Keyode der ist, den du erwarten würdest. Dafür gibt es sogar ein paar Programme die helfen sollen, dass keine Taste ausgelassen wurde. + +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) + +## Debuggen + +Deine Tastatur wird Debug Informationen liefern wenn Du `CONSOLE_ENABLE = yes` in deiner `rules.mk` gesetzt hast. Die default-Ausgabe ist sehr beschränkt und kann wenn nötig durch die Aktivierung des Debug-Modes erhöht werden. Benutze dafür entweder den `DEBUG` Keycode in deiner Tastaturbelegung, das [Command](de/feature_command.md)-Feature oder füge den folgenden Code zu deiner Tastaturbelegung hinzu. + +```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; +} +``` + +### Debuggen mit der QMK Toolbox + +Für kompatible Plattformen kann die [QMK Toolbox](https://github.com/qmk/qmk_toolbox) benutzt werden um Debug-Nachrichten deiner Tastatur anzuzeigen. + +### Debuggen mit hid_listen + +Bevorzugst Du es lieber auf der Befehlszeile zu debuggen? Dafür eignet sich das Programm [hid_listen](https://www.pjrc.com/teensy/hid_listen.html) von PJRC. Binaries sind für Windows, Linux und MacOS verfügbar. + + + +## Eigene Debug-Nachrichten senden + +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 + +Danach stehen dir verschiedene Druck-Funktionen zur Verfügung: + +* `print("string")`: Druckt einen simplen String +* `uprintf("%s string", var)`: Druckt einen formatierten String +* `dprint("string")` Druckt einen simplen String, aber nur wenn der Debug-Mode aktiviert ist +* `dprintf("%s string", var)`: Druckt einen formatierten String, aber nur wenn der Debug-Mode aktiviert ist + +## Debug Beispiele + +Anbei findest Du eine Sammlung von hilfreichen Beispielen. Für weitere Informationen Informationen sei an dieser Stelle auf [Debugging/Troubleshooting QMK](de/faq_debug.md) verwiesen. + +### Which matrix position is this keypress? +### Welche Matrix Position hat dieser Tastenanschlag + +Beim Portieren, oder bei der Fehlerdiagnose von PCB Problemen, ist es nützlich sich anzeigen zu lassen ob ein Tastenanschlag richtig erkannt wurde. Um die Protokollierung für diesen Fall zu aktivieren, füge bitte folgenden Code zu deiner Tastaturbelegung `keymap.c` hinzu. + +```c +bool process_record_user(uint16_t keycode, keyrecord_t *record) { + // Wenn 'console' aktiviert ist wird die Matrix-Position und der Status jedes Tastenanschlags ausgegeben +#ifdef CONSOLE_ENABLE + uprintf("KL: kc: %u, col: %u, row: %u, pressed: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed); +#endif + return true; +} +``` + +Beispiel Ausgabe: +```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 +``` + +### Wieviel Zeit wurde benötigt um einen Tastenanschlag zu detektieren? + +Wenn Performance-Probleme auftreten ist es hilfreich die Frequenz, mit der die Matrix gescannt wird, zu wissen. Um dies in diesem Fall zu aktiveren füge, den folgenden Code zu deiner Tastaturbelegung in `config.h` hinzu. + +```c +#define DEBUG_MATRIX_SCAN_RATE +``` + +Beispiel Ausgabe +```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 +``` 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 ba3830b64c7..8df25590c4f 100644 --- a/docs/documentation_templates.md +++ b/docs/documentation_templates.md @@ -2,7 +2,7 @@ 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. @@ -28,9 +28,9 @@ the Ctrl, Alt, or GUI modifiers are held down. A compact 40% (12x4) ortholinear keyboard kit made and sold by OLKB and Massdrop. [More info on qmk.fm](http://qmk.fm/planck/) -Keyboard Maintainer: [Jack Humbert](https://github.com/jackhumbert) -Hardware Supported: Planck PCB rev1, rev2, rev3, rev4, Teensy 2.0 -Hardware Availability: [OLKB.com](https://olkb.com), [Massdrop](https://www.massdrop.com/buy/planck-mechanical-keyboard?mode=guest_open) +* Keyboard Maintainer: [Jack Humbert](https://github.com/jackhumbert) +* Hardware Supported: Planck PCB rev1, rev2, rev3, rev4, Teensy 2.0 +* Hardware Availability: [OLKB.com](https://olkb.com), [Massdrop](https://www.massdrop.com/buy/planck-mechanical-keyboard?mode=guest_open) Make example for this keyboard (after setting up your build environment): @@ -38,5 +38,3 @@ Make example for this keyboard (after setting up your build environment): See the [build environment setup](https://docs.qmk.fm/#/getting_started_build_tools) and the [make instructions](https://docs.qmk.fm/#/getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](https://docs.qmk.fm/#/newbs). ``` - -There needs to be two spaces at the end of the `Keyboard Maintainer` and `Hardware Supported` lines for it to render correctly with Markdown. diff --git a/docs/driver_installation_zadig.md b/docs/driver_installation_zadig.md index 71e4cc440f8..403b78da0ce 100644 --- a/docs/driver_installation_zadig.md +++ b/docs/driver_installation_zadig.md @@ -2,9 +2,9 @@ QMK presents itself to the host as a regular HID keyboard device, and as such requires no special drivers. However, in order to flash your keyboard on Windows, the bootloader device that appears when you reset the board often *does*. -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. +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 or WSL, the `qmk_install.sh` script will have asked if you want it to install the drivers for you. ## Installation @@ -23,7 +23,7 @@ Zadig will automatically detect the bootloader device. You may sometimes need to !> 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**. The `libusb-win32` driver will usually work for AVR, and `WinUSB` for ARM, but if you still cannot flash the board, try installing a different driver from the list. USBAspLoader devices must use the `libusbK` driver. ![Zadig with a bootloader driver correctly installed](https://i.imgur.com/b8VgXzx.png) @@ -31,7 +31,7 @@ Finally, unplug and replug the keyboard to make sure the new driver has been loa ## Recovering from Installation to Wrong Device -If you find that you can no longer type with the keyboard, you may have installed the driver onto the keyboard itself instead of the bootloader. You can easily confirm this in Zadig - a healthy keyboard has the `HidUsb` driver installed on all of its interfaces: +If you find that you can no longer type with the keyboard, you may have accidentally replaced the driver for the keyboard itself instead of for the bootloader. This can happen when the keyboard is not in the bootloader mode. You can easily confirm this in Zadig - a healthy keyboard has the `HidUsb` driver installed on all of its interfaces: ![A healthy keyboard as seen by Zadig](https://i.imgur.com/Hx0E5kC.png) @@ -44,3 +44,5 @@ 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! + +?> A full reboot of your computer may sometimes be necessary at this point, to get Windows to pick up the new driver. diff --git a/docs/eeprom_driver.md b/docs/eeprom_driver.md new file mode 100644 index 00000000000..188b95caa76 --- /dev/null +++ b/docs/eeprom_driver.md @@ -0,0 +1,71 @@ +# 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` | +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 new file mode 100644 index 00000000000..75fd3cb64e0 --- /dev/null +++ b/docs/es/README.md @@ -0,0 +1,32 @@ +# Firmware Quantum Mechanical Keyboard + +[![Versión actual](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags) +[![Estado de 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) +[![Estado de la documentación](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm) +[![Contribuyentes en GitHub](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly) +[![Forks en GitHub](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/) + +## ¿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. + +## 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. + +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`). + +## Cómo compilar + +Antes de poder compilar, necesitarás [instalar un entorno](es/getting_started_build_tools.md) para el desarrollo de AVR y/o ARM. Una vez hayas completado este paso, usarás el comando `make` para compilar un teclado y keymap con la siguiente notación: + + make planck/rev4:default + +Este ejemplo compilaría la revisión `rev4` del teclado `planck` con el keymap `default`. No todos los teclados tienen revisiones (también llamados subproyectos o carpetas), en ese caso, se puede omitir: + + make preonic:default + +## 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). diff --git a/docs/es/_summary.md b/docs/es/_summary.md new file mode 100644 index 00000000000..aa2a0ca5d97 --- /dev/null +++ b/docs/es/_summary.md @@ -0,0 +1,122 @@ +* [Guía completa para novatos](es/newbs.md) + * [Empezando](es/newbs_getting_started.md) + * [Construyendo tu primer firmare](es/newbs_building_firmware.md) + * [Flasheando el firmware](es/newbs_flashing.md) + * [Testeando y depurando ](es/newbs_testing_debugging.md) + * [Mejores práticas](es/newbs_best_practices.md) + * [Recursos de aprendizaje](es/newbs_learn_more_resources.md) + +* [QMK Basics](es/README.md) + * [Introducción a QMK](es/getting_started_introduction.md) + * [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) + * [Obtener ayuda](es/getting_started_getting_help.md) + +* [Cambios incompatibles](es/breaking_changes.md) + * [30 Ago 2019](es/ChangeLog/20190830.md) + +* [Preguntas frecuentes](es/faq.md) + * [General](es/faq_general.md) + * [Construir/Compilar QMK](es/faq_build.md) + * [Depurando/Encontrando problemas en QMK](es/faq_debug.md) + * [Keymap](es/faq_keymap.md) + * [Instalación de drivers con Zadig](es/driver_installation_zadig.md) + +* Guías detalladas + * [Instalar herramientas construcción](es/getting_started_build_tools.md) + * [Guía Vagrant](es/getting_started_vagrant.md) + * [Instrucciones de Construcción/Compilado](es/getting_started_make_guide.md) + * [Flasheando Firmware](es/flashing.md) + * [Personalizando funcionalidad](es/custom_quantum_functions.md) + * [Visión general del Keymap](es/keymap.md) + +* [Hardware](es/hardware.md) + * [Procesadores AVR](es/hardware_avr.md) + * [Drivers](es/hardware_drivers.md) + +* Referencia + * [Pautas de teclados](es/hardware_keyboard_guidelines.md) + * [Opciones de configuración](es/config_options.md) + * [Keycodes](es/keycodes.md) + * [Convenciones de código - C](es/coding_conventions_c.md) + * [Convenciones de código - Python](es/coding_conventions_python.md) + * [Mejores prácticas de documentación](es/documentation_best_practices.md) + * [Plantillas de documentación](es/documentation_templates.md) + * [Glosario](es/reference_glossary.md) + * [Tests unitarios](es/unit_testing.md) + * [Funciones útiles](es/ref_functions.md) + * [Sporte configurador](es/reference_configurator_support.md) + * [Formato info.json](es/reference_info_json.md) + * [Desarrollo Python CLI](es/cli_development.md) + +* [Características](es/features.md) + * [Keycodes Básicos](es/keycodes_basic.md) + * [Teclas US ANSI Shifted](es/keycodes_us_ansi_shifted.md) + * [Keycodes Quantum](es/quantum_keycodes.md) + * [Keycodes Avanzados](es/feature_advanced_keycodes.md) + * [Audio](es/feature_audio.md) + * [Auto Shift](es/feature_auto_shift.md) + * [Retroiluminación](es/feature_backlight.md) + * [Bluetooth](es/feature_bluetooth.md) + * [Bootmagic](es/feature_bootmagic.md) + * [Combos](es/feature_combo.md) + * [Comando](es/feature_command.md) + * [API Debounce](es/feature_debounce_type.md) + * [Switch DIP](es/feature_dip_switch.md) + * [Macros Dinámicas](es/feature_dynamic_macros.md) + * [Encoders](es/feature_encoders.md) + * [Grave Escape](es/feature_grave_esc.md) + * [Feedback Háptico](es/feature_haptic_feedback.md) + * [Controlador LCD HD44780](es/feature_hd44780.md) + * [Key Lock](es/feature_key_lock.md) + * [Layouts](es/feature_layouts.md) + * [Tecla Leader](es/feature_leader_key.md) + * [Matriz LED](es/feature_led_matrix.md) + * [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/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) + * [Matriz RGB](es/feature_rgb_matrix.md) + * [Cadete espacial](es/feature_space_cadet.md) + * [Teclado dividido](es/feature_split_keyboard.md) + * [Stenografía](es/feature_stenography.md) + * [Swap Hands](es/feature_swap_hands.md) + * [Tap Dance](es/feature_tap_dance.md) + * [Terminal](es/feature_terminal.md) + * [Impresora Térmica](es/feature_thermal_printer.md) + * [Unicode](es/feature_unicode.md) + * [Userspace](es/feature_userspace.md) + * [Velocikey](es/feature_velocikey.md) + +* Para Makers y Modders + * [Guía de cableado a mano](es/hand_wire.md) + * [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) + +* Para entender en profundidad + * [Cómo funcionan los teclados](es/how_keyboards_work.md) + * [Entendiendo QMK](es/understanding_qmk.md) + +* Otros temas + * [Usando Eclipse con QMK](es/other_eclipse.md) + * [Usando VSCode con QMK](es/other_vscode.md) + * [Soporte](es/getting_started_getting_help.md) + * [Cómo añadir traducciones](es/translating.md) + +* QMK Internals (En progreso) + * [Defines](es/internals_defines.md) + * [Input Callback Reg](es/internals_input_callback_reg.md) + * [Dispositivo Midi](es/internals_midi_device.md) + * [Proceso de configuración de un dispositivo Midi](es/internals_midi_device_setup_process.md) + * [Utilidad Midi](es/internals_midi_util.md) + * [Funciones Send](es/internals_send_functions.md) + * [Herramientas Sysex](es/internals_sysex_tools.md) diff --git a/docs/es/hardware.md b/docs/es/hardware.md new file mode 100644 index 00000000000..8d7579c9efe --- /dev/null +++ b/docs/es/hardware.md @@ -0,0 +1,8 @@ +# 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. + +* [Pautas de teclados](hardware_keyboard_guidelines.md) +* [Procesadores AVR](hardware_avr.md) +* Procesadores ARM (TBD) +* [Drivers](hardware_drivers.md) diff --git a/docs/es/hardware_avr.md b/docs/es/hardware_avr.md new file mode 100644 index 00000000000..2ecf78d662f --- /dev/null +++ b/docs/es/hardware_avr.md @@ -0,0 +1,180 @@ +# Teclados con Procesadores AVR + +Esta página describe el soporte para procesadores AVR en QMK. Los procesadores AVR incluyen el atmega32u4, atmega32u2, at90usb1286, y otros procesadores de la Corporación Atmel. Los procesadores AVR son MCUs de 8-bit que son diseñados para ser fáciles de trabajar. Los procesadores AVR más comunes en los teclados tienen USB y un montón de GPIO para permitir grandes matrices de teclado. Son los MCUs más populares para el uso en los teclados hoy en día. + +Si aún no lo has hecho, debes leer las [Pautas de teclados](hardware_keyboard_guidelines.md) para tener una idea de cómo los teclados encajan en QMK. + +## Añadir tu Teclado AVR a QMK + +QMK tiene varias características para simplificar el trabajo con teclados AVR. Para la mayoría de los teclados no tienes que escribir ni una sola línea de código. Para empezar, ejecuta el archivo `util/new_keyboard.sh`: + +``` +$ ./util/new_keyboard.sh +Generating a new QMK keyboard directory + +Keyboard Name: mycoolkb +Keyboard Type [avr]: +Your Name [John Smith]: + +Copying base template files... done +Copying avr template files... done +Renaming keyboard files... done +Replacing %KEYBOARD% with mycoolkb... done +Replacing %YOUR_NAME% with John Smith... done + +Created a new keyboard called mycoolkb. + +To start working on things, cd into keyboards/mycoolkb, +or open the directory in your favourite text editor. +``` + +Esto creará todos los archivos necesarios para tu nuevo teclado, y rellenará la configuración con valores predeterminados. Ahora sólo tienes que personalizarlo para tu teclado. + +## `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. + +## `.c` + +Aquí es donde pondrás toda la lógica personalizada para tu teclado. Muchos teclados no necesitan nada aquí. Puedes aprender más sobre cómo escribir lógica personalizada en [Funciones Quantum Personalizadas](custom_quantum_functions.md). + +## `.h` + +Este es el archivo en el que defines tu(s) [Macro(s) de Layout](feature_layouts.md). Por lo menos deberías tener un `#define LAYOUT` para tu teclado que se ve algo así: + +```c +#define LAYOUT( \ + k00, k01, k02, \ + k10, k11 \ +) { \ + { k00, k01, k02 }, \ + { k10, KC_NO, k11 }, \ +} +``` + +La primera mitad de la macro pre-procesador `LAYOUT` define la disposición física de las llaves. La segunda mitad de la macro define la matriz a la que están conectados los interruptores. Esto te permite tener una disposición física de las llaves que difiere de la matriz de cableado. + +Cada una de las variables `k__` tiene que ser única, y normalmente sigue el formato `k`. + +La matriz física (la segunda mitad) debe tener un número de filas igualando `MATRIX_ROWS`, y cada fila debe tener exactamente `MATRIX_COLS` elementos. Si no tienes tantas teclas físicas puedes usar `KC_NO` para rellenar los espacios en blanco. + +## `config.h` + +El archivo `config.h` es donde configuras el hardware y el conjunto de características para tu teclado. Hay un montón de opciones que se pueden colocar en ese archivo, demasiadas para listar allí. Para obtener una visión de conjunto completa de las opciones disponibles consulta la página de [Opciones de Configuración](config_options.md). + +### Configuración de hardware + + +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` y `PRODUCT` para reflejar con precisión tu teclado. + +```c +#define VENDOR_ID 0xFEED +#define PRODUCT_ID 0x6060 +#define DEVICE_VER 0x0001 +#define MANUFACTURER Tú +#define PRODUCT mi_teclado_fantastico +``` + +?> 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. + +### Configuración de la matriz del teclado + +La siguiente sección del archivo `config.h` trata de la matriz de tu teclado. Lo primero que debes establecer es el tamaño de la matriz. Esto es generalmente, pero no siempre, el mismo número de filas y columnas como la disposición física de las teclas. + +```c +#define MATRIX_ROWS 2 +#define MATRIX_COLS 3 +``` + +Una vez que hayas definido el tamaño de tu matriz, necesitas definir qué pines en tu MCU están conectados a filas y columnas. Para hacerlo simplemente especifica los nombres de esos pines: + +```c +#define MATRIX_ROW_PINS { D0, D5 } +#define MATRIX_COL_PINS { F1, F0, B0 } +#define UNUSED_PINS +``` + +El número de entradas debe ser el mismo que el número que asignaste a `MATRIX_ROWS`, y del mismo modo para `MATRIX_COL_PINS` y `MATRIX_COLS`. No tienes que especificar `UNUSED_PINS`, pero puedes si deseas documentar qué pines están abiertos. + +Finalmente, puedes especificar la dirección en la que apuntan tus diodos. Esto puede ser `COL2ROW` o `ROW2COL`. + +```c +#define DIODE_DIRECTION COL2ROW +``` + +#### Matriz de patas directas +Para configurar un teclado en el que cada interruptor está conectado a un pin y tierra separados en lugar de compartir los pines de fila y columna, usa `DIRECT_PINS`. La asignación define los pines de cada interruptor en filas y columnas, de izquierda a derecha. Debe ajustarse a los tamaños dentro de `MATRIX_ROWS` y `MATRIX_COLS`. Usa `NO_PIN` para rellenar espacios en blanco. Sobreescribe el comportamiento de `DIODE_DIRECTION`, `MATRIX_ROW_PINS` y `MATRIX_COL_PINS`. + +```c +// #define MATRIX_ROW_PINS { D0, D5 } +// #define MATRIX_COL_PINS { F1, F0, B0 } +#define DIRECT_PINS { \ + { F1, E6, B0, B2, B3 }, \ + { F5, F0, B1, B7, D2 }, \ + { F6, F7, C7, D5, D3 }, \ + { B5, C6, B6, NO_PIN, NO_PIN } \ +} +#define UNUSED_PINS + +/* COL2ROW, ROW2COL */ +//#define DIODE_DIRECTION +``` + +### Configuración de retroiluminación + +QMK soporta retroiluminación en la mayoría de los pines GPIO. Algunos de ellos pueden ser manejados por el MCU en hardware. Para más detalles, consulta la [Documentación de Retroiluminación](feature_backlight.md). + +```c +#define BACKLIGHT_PIN B7 +#define BACKLIGHT_LEVELS 3 +#define BACKLIGHT_BREATHING +#define BREATHING_PERIOD 6 +``` + +### Otras opciones de configuración + +Hay un montón de características que se pueden configurar o ajustar en `config.h`. Debes consultar la página de [Opciones de Configuración](config_options.md) para más detalles. + +## `rules.mk` + +Usa el archivo `rules.mk` para decirle a QMK qué archivos construir y qué características habilitar. Si estás construyendo sobre un atmega32u4 deberías poder dejar mayormente los valores predeterminados. Si estás usando otro MCU es posible que tengas que ajustar algunos parámetros. + +### Opciones MCU + +Estas opciones le indican al sistema de compilación para qué CPU construir. Ten mucho cuidado si cambias cualquiera de estos ajustes. Puedes inutilizar tu teclado. + +```make +MCU = atmega32u4 +F_CPU = 16000000 +ARCH = AVR8 +F_USB = $(F_CPU) +OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT +``` + +### Gestores de arranque + +El gestor de arranque es una sección especial de tu MCU que te permite actualizar el código almacenado en el MCU. Piensa en ello como una partición de rescate para tu teclado. + +#### Ejemplo de gestor de arranque + +```make +BOOTLOADER = halfkay +``` + +#### Ejemplo de cargador DFU Atmel + +```make +BOOTLOADER = atmel-dfu +``` + +#### Ejemplo de gestor de arranque Pro Micro + +```make +BOOTLOADER = caterina +``` + +### Opciones de construcción + +Hay un serie de características que se pueden activar o desactivar en `rules.mk`. Consulta la página de [Opciones de Configuración](config_options.md#feature-options) para obtener una lista detallada y una descripción. diff --git a/docs/es/hardware_drivers.md b/docs/es/hardware_drivers.md new file mode 100644 index 00000000000..7b74b34b456 --- /dev/null +++ b/docs/es/hardware_drivers.md @@ -0,0 +1,36 @@ +# Controladores de hardware QMK + +QMK se utiliza en un montón de hardware diferente. Mientras que el soporte para los MCUs y las configuraciones de matriz más comunes está integrado, hay una serie de controladores que se pueden añadir para soportar hardware adicional al teclado. Los ejemplos incluyen ratones y otros dispositivos de apuntamiento, extensores de i/o para teclados divididos, modúlos Bluetooth, y pantallas LCD, OLED y TFT. + + + +# Controladores disponibles + +## ProMicro (Solo AVR) + +Soporte para direccionar pines en el ProMicro por su nombre Arduino en lugar de su nombre AVR. Esto necesita ser mejor documentado. Si estás tratando de hacer esto y leer el código no ayuda por favor [abre una issue](https://github.com/qmk/qmk_firmware/issues/new) y podemos ayudarte por el proceso. + +## Controlador OLED SSD1306 + +Soporte para pantallas OLED basadas en SSD1306. Para obtener más información consulta la página de [Característica de Controlador OLED](feature_oled_driver.md). + +## uGFX + +Puedes hacer uso de uGFX dentro de QMK para manejar LCDs de caracteres y gráficos, matrices de LED, OLED, TFT, y otras tecnologías de visualización. Esto necesita ser mejor documentado. Si estás tratando de hacer esto y leer el código no ayuda por favor [abre una issue](https://github.com/qmk/qmk_firmware/issues/new) y podemos ayudarte por el proceso. + +## WS2812 (Solo AVR) + +Soporte para LEDs WS2811/WS2812{a,b,c}. Para obtener más información consulta la página de [Luz RGB](feature_rgblight.md). + +## IS31FL3731 + +Soporte para hasta 2 controladores. Cada controlador implementa 2 matrices charlieplex para direccionar LEDs individualmente usando I2C. Esto permite hasta 144 LEDs del mismo color o 32 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). + +## 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 new file mode 100644 index 00000000000..2cde2b39fb7 --- /dev/null +++ b/docs/es/hardware_keyboard_guidelines.md @@ -0,0 +1,149 @@ +# Pautas del teclado QMK + +Desde sus inicios, QMK ha crecido a pasos agigantados gracias a personas como tú que contribuyes a la creación y mantenimiento de nuestros teclados comunitarios. A medida que hemos crecido hemos descubierto algunos patrones que funcionan bien, y pedimos que te ajustes a ellos para que sea más fácil para que otras personas se beneficien de tu duro trabajo. + + +## Nombrar tu Teclado/Proyecto + +Todos los nombres de teclado están en minúsculas, consistiendo sólo de letras, números y guiones bajos (`_`). Los nombres no pueden comenzar con un guión bajo. La barra de desplazamiento (`/`) se utiliza como un carácter de separación de subcarpetas. + +Los nombres `test`, `keyboard`, y `all` están reservados para las órdenes de make y no pueden ser usados como un nombre de teclado o subcarpeta. + +Ejemplos Válidos: + +* `412_64` +* `chimera_ortho` +* `clueboard/66/rev3` +* `planck` +* `v60_type_r` + +## Subcarpetas + +QMK utiliza subcarpetas tanto para organización como para compartir código entre las revisiones del mismo teclado. Puedes anidar carpetas hasta 4 niveles de profundidad: + + qmk_firmware/keyboards/top_folder/sub_1/sub_2/sub_3/sub_4 + +Si una subcarpeta tiene un archivo `rules.mk` será considerado un teclado compilable. Estará disponible en el configurador de QMK y se probará con `make all`. Si estás utilizando una carpeta para organizar varios teclados del mismo fabricante no debes tener un archivo `rules.mk`. + +Ejemplo: + +Clueboard utiliza subcarpetas para ambos propósitos: organización y revisiones de teclado. + +* [`qmk_firmware`](https://github.com/qmk/qmk_firmware/tree/master) + * [`keyboards`](https://github.com/qmk/qmk_firmware/tree/master/keyboards) + * [`clueboard`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard) ← This is the organization folder, there's no `rules.mk` file + * [`60`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/60) ← This is a compilable keyboard, it has a `rules.mk` file + * [`66`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66) ← This is also compilable- it uses `DEFAULT_FOLDER` to specify `rev3` as the default revision + * [`rev1`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev1) ← compilable: `make clueboard/66/rev1` + * [`rev2`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev2) ← compilable: `make clueboard/66/rev2` + * [`rev3`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev3) ← compilable: `make clueboard/66/rev3` or `make clueboard/66` + +## Estructura de carpetas de teclado + +Su teclado debe estar ubicado en `qmk_firm cuidada/keyboards/` y el nombre de la carpeta debe ser el nombre de su teclado como se describe en la sección anterior. Dentro de esta carpeta debe haber varios archivos: + +* `readme.md` +* `info.json` +* `config.h` +* `rules.mk` +* `.c` +* `.h` + +### `readme.md` + +Todos los proyectos necesitan tener un archivo `readme.md` que explica lo que es el teclado, quién lo hizo y dónde está disponible. Si es aplicable, también debe contener enlaces a más información, como el sitio web del fabricante. Por favor, sigue la [plantilla publicada](documentation_templates.md#keyboard-readmemd-template). + +### `info.json` + +Este archivo es utilizado por la [API de QMK](https://github.com/qmk/qmk_api). Contiene la información que [configurador de QMK](https://config.qmk.fm/) necesita mostrar en una representación de su teclado. También puede establecer metadatos aquí. Para más información, consulta la [página de referencia](reference_info_json.md). + +### `config.h` + +Todos los proyectos necesitan tener un archivo `config.h` que establece cosas como el tamaño de la matriz, nombre del producto, USB VID/PID, descripción y otros ajustes. En general, usa este archivo para establecer la información esencial y los valores predeterminados para tu teclado que siempre funcionarán. + +### `rules.mk` + +La presencia de este archivo indica que la carpeta es un destino de teclado y se puede utilizar en las órdenes `make`. Aquí es donde estableces el entorno de compilación para tu teclado y configuras el conjunto predeterminado de características. + +### `` + +Aquí es donde escribirás código personalizado para tu teclado. Típicamente escribirás código para inicializar e interactuar con el hardware de tu teclado. Si tu teclado se compone de sólo una matriz de teclas sin LEDs, altavoces u otro hardware auxiliar este archivo puede estar en blanco. + +Las funciones siguientes se definen típicamente en este archivo: + +* `void matrix_init_kb(void)` +* `void matrix_scan_kb(void)` +* `bool process_record_kb(uint16_t keycode, keyrecord_t *record)` +* `void led_set_kb(uint8_t usb_led)` + +### `` + +Este archivo se utiliza para definir la matriz para tu teclado. Debes definir al menos un macro de C que traduce una serie en una matriz que representa la matriz de interruptor físico para tu teclado. Si es posible construir tu teclado con múltiples diseños debes definir macros adicionales. + +Si solo tienes un diseño debes llamar a esta macro `LAYOUT`. + +Al definir diseños múltiples debes tener un diseño base, llamado `LAYOUT_all`, que soporte todas las posibles posiciones de switch en tu matriz, incluso si ese diseño es imposible de construir físicamente. Esta es la macro que deberías usar en tu keymap `predeterminado`. Debes tener keymaps adicionales llamados `default_ término layout>` que usen tus otras macros de diseño. Esto hará que sea más fácil para las personas utilizar los diseños que defines. + +Los nombres de las macros de diseño son completamente minúsculas, excepto por la palabra `LAYOUT` en el frente. + +Por ejemplo, si tienes un PCB de 60% que soporta ANSI e ISO podría definir los siguientes diseños y keymaps: + +| Nombre de diseño | Nombre de keymap | Descripción | +|-------------|-------------|-------------| +| LAYOUT_all | default | Un diseño que soporta tanto ISO como ANSI | +| LAYOUT_ansi | default_ansi | Un diseño ANSI | +| LAYOUT_iso | default_iso | Un diseño ISO | + +## Archivos de Imagen/Hardware + +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. + +## Predeterminados de teclado + +Dada la cantidad de funcionalidad que expone QMK, es muy fácil confundir a los nuevos usuarios. Al armar el firmware predeterminado para tu teclado, te recomendamos limitar tus funciones y opciones habilitadas al conjunto mínimo necesario para soportar tu hardware. A continuación se formulan recomendaciones sobre características específicas. + +### Bootmagic y Command + +[Bootmagic](feature_bootmagic.md) and [Command](feature_command.md) son dos características relacionadas que permiten a un usuario controlar su teclado de manera no obvia. Te recomendamos que piense largo y tendido acerca de si vas a habilitar cualquiera de las características, y cómo vas a exponer esta funcionalidad. Tengas en cuenta que los usuarios que quieren esta funcionalidad puede habilitarla en sus keymaps personales sin afectar a todos los usuarios novatos que pueden estar usando tu teclado como su primera tarjeta programable. + +De lejos el problema más común con el que se encuentran los nuevos usuarios es la activación accidental de Bootmagic mientras están conectando su teclado. Están sosteniendo el teclado por la parte inferior, presionando sin saberlo en alt y barra espaciadora, y luego se dan cuenta de que estas teclas han sido intercambiadas en ellos. Recomendamos dejar esta característica deshabilitada de forma predeterminada, pero si la activas consideres establecer la opción `BOOTMAGIC_KEY_SALT` a una tecla que es difícil de presionar al conectar el teclado. + +Si tu teclado no tiene 2 teclas de cambio debes proporcionar un predeterminado de trabajo para `IS_COMMAND`, incluso cuando haya definido `COMMAND_ENABLE = no`. Esto dará a sus usuarios un valor predeterminado para ajustarse a si lo hacen enable Command. + +## Programación de teclado personalizado + +Como se documenta en [Funcionalidad de Adaptación](custom_quantum_functions.md) puedes definir funciones personalizadas para tu teclado. Por favor, tengas en cuenta que sus usuarios pueden querer personalizar ese comportamiento así, y hacer que sea posible para que puedan hacer eso. Si está proporcionando una función personalizada, por ejemplo `process_record_kb()`, asegúrese de que su función también llame a la versión` `_user()` de la llamada. También debes tener en cuenta el valor de retorno de la versión `_user()`, y ejecutar sólo tu código personalizado si el usuario devuelve `true`. + +## Proyectos Sin Producción/Conectados A Mano + +Estamos encantados de aceptar cualquier proyecto que utilice QMK, incluidos los prototipos y los cableados de mano, pero tenemos una carpeta `/keyboards/handwired/` separada para ellos, por lo que la carpeta `/keyboards/` principal no se llena. Si un proyecto prototipo se convierte en un proyecto de producción en algún momento en el futuro, ¡estaremos encantados de moverlo a la carpeta `/keyboards/` principal! + +## Advertencias como errores + +Al desarrollar su teclado, tengas en cuenta que todas las advertencias serán tratadas como errores - estas pequeñas advertencias pueden acumularse y causar errores más grandes en el camino (y pierdan es generalmente una mala práctica). + +## Derechos de autor + +Si estás adaptando la configuración de tu teclado de otro proyecto, pero no utilizando el mismo código, asegúrese de actualizar la cabecera de derechos de autor en la parte superior de los archivos para mostrar tu nombre, en este formato: + + Copyright 2017 Tu nombre + +Si estás modificando el código de otra persona y sólo ha hecho cambios triviales debes dejar su nombre en la declaración de derechos de autor. Si has hecho un trabajo significativo en el archivo debe agregar tu nombre a la de ellos, así: + + Copyright 2017 Su nombre Tu nombre + +El año debe ser el primer año en que se crea el archivo. Si el trabajo se hizo a ese archivo en años posteriores puedes reflejar que mediante la adición del segundo año a la primera, como así: + + Copyright 2015-2017 Tu nombre + +## 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. + +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. + +## Detalles técnicos + +Si estás buscando más información sobre cómo hacer que su teclado funcione con QMK, [echa un vistazo a la sección hardware](hardware.md)! diff --git a/docs/es/newbs.md b/docs/es/newbs.md new file mode 100644 index 00000000000..ebb4b6ac2d1 --- /dev/null +++ b/docs/es/newbs.md @@ -0,0 +1,23 @@ +# La guía completa de QMK para novatos + +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. + +## Visión general + +Hay 7 secciones principales en esta guía: + +* [Empezando](newbs_getting_started.md) +* [Construyendo tu primer firmware](newbs_building_firmware.md) +* [Construyendo tu primer firmware usando la GUI](newbs_building_firmware_configurator.md) +* [Flasheando el firmware](newbs_flashing.md) +* [Testeando y depurando](newbs_testing_debugging.md) +* [Mejores práticas](newbs_best_practices.md) +* [Recursos de aprendizaje](newbs_learn_more_resources.md) + +Esta guía está enfocada en ayudar a alguien que nunca ha compilado software con anterioridad. Toma decisiones y hace recomendaciones teniendo en cuenta este punto de vista. Hay métodos alternativos para muchos de estos procedimientos, y soportamos la mayoría de esas alternativas. Si tienes alguna duda sobre cómo llevar a cabo una tarea nos puedes [preguntar para que te guiemos](getting_started_getting_help.md). + +## Recursos adicionales + +* [Blog de Básicos de Thomas Baart's QMK](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – Un blog creado por un usuario que cubre lo básico sobre cómo usar el firmware QMK Firmware, visto desde la perspectiva de un usuario nuevo. diff --git a/docs/es/newbs_best_practices.md b/docs/es/newbs_best_practices.md new file mode 100644 index 00000000000..2f72eff788c --- /dev/null +++ b/docs/es/newbs_best_practices.md @@ -0,0 +1,159 @@ +# Mejores prácticas + +## O, "Cómo aprendí a dejar de preocuparme y amarle a Git." + +Este documento procura instruir a los novatos en las mejores prácticas para tener una experiencia más fácil en contribuir a QMK. Te guiaremos por el proceso de contribuir a QMK, explicando algunas maneras de hacerlo más fácilmente, y luego romperemos algunas cosas para enseñarte cómo arreglarlas. + +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. +2. Has [configurado tu entorno de desarrollo](newbs_getting_started.md?id=environment-setup). + + +## La rama master de tu fork: Actualizar a menudo, nunca commit + +Se recomienda que para desarrollo con QMK, lo que sea que estés haciendo, mantener tu rama `master` actualizada, pero **nunca** commit en ella. Mejor, haz todos tus cambios en una rama de desarrollo y manda pull requests de tus ramas mientras programas. + +Para evitar los conflictos de merge — cuando dos o más usuarios han editado la misma parte de un archivo al mismo tiempo — mantén tu rama `master` actualizada, y empieza desarrollo nuevo creando una nueva rama. + +### Actualizando tu rama master + +Para mantener tu rama `master` actualizada, se recomienda agregar el repository ("repo") de Firmware QMK como un repo remoto en git. Para hacer esto, abre tu interfaz de línea de mandatos y ingresa: +``` +git remote add upstream https://github.com/qmk/qmk_firmware.git +``` + +Para verificar que el repo ha sido agregado, ejecuta `git remote -v`, y lo siguiente debe aparecer: + +``` +$ git remote -v +origin https://github.com//qmk_firmware.git (fetch) +origin https://github.com//qmk_firmware.git (push) +upstream https://github.com/qmk/qmk_firmware.git (fetch) +upstream https://github.com/qmk/qmk_firmware.git (push) +``` + +Ya que has hecho esto, puedes buscar actualizaciones del repo ejecutando `git fetch upstream`. Esto busca las ramas y etiquetas — juntos conocidos como "refs" — del repo QMK, que ahora tiene el apodo `upstream`. Ahora podemos comparar los archivos en nuestro fork `origin` con los de QMK. + +Para actualizar la rama master de tu fork, ejecuta lo siguiente, pulsando Intro después de cada línea: + +``` +git checkout master +git fetch upstream +git pull upstream master +git push origin master +``` + +Esto te coloca en tu rama master, busca los refs del repo de QMK, descarga la rama `master` actual a tu computadora, y después lo sube a tu fork. + +### Hacer cambios + +Para hacer cambios, crea una nueva rama ejecutando: + +``` +git checkout -b dev_branch +git push --set-upstream origin dev_branch +``` + +Esto crea una nueva rama llamada `dev_branch`, te coloca en ella, y después guarda la nueva rama a tu fork. El parámetro `--set-upstream` le dice a git que use tu fork y la rama `dev_branch` cada vez que uses `git push` o `git pull` en esta rama. Solo necesitas usarlo la primera que que subes cambios; ya después, puedes usar `git push` o `git pull`, sin usar los demás parámetros. + +!> Con `git push`, puedes usar `-u` en vez de `--set-upstream` — `-u` es un alias de `--set-upstream`. + +Puedes nombrar tu rama casi cualquier cosa, pero se recomienda ponerle algo con relación a los cambios que vas a hacer. + +Por defecto `git checkout -b` se basará tu nueva rama en la rama en la cual estás actualmente. Puedes basar tu rama en otra rama existente agregando el nombre de la rama al comando: + +``` +git checkout -b dev_branch master +``` + +Ahora que tienes una rama development, abre tu editor de texto y haz los cambios que quieres. Se recomienda hacer varios commits pequeños a tu rama; de este modo cualquier cambio que causa problemas puede ser rastreado y deshecho si fuera necesario. Para hacer tus cambios, edita y guarda los archivos que necesitas actualizar, agrégalos al *staging area* de Git, y luego haz un commit a tu rama: + +``` +git add path/to/updated_file +git commit -m "My commit message." +``` +`git add` agrega los archivos que han sido cambiados al *staging area* de Git, lo cual es la "zona de preparación"de Git. Este contiene los cambios que vas a *commit* usando `git commit`, que guarda los cambios en el repo. Usa un mensaje de commit descriptivo para que puedas saber que ha cambiado fácilmente. + +!> Si has cambiado muchos archivos, pero todos los archivos son parte del mismo cambio, puedes usar `git add .` para agregar todos los archivos cambiados que están en tu directiro actual, en vez de agregar cada archivo manualmente. + +### Publicar tus cambios + +El útimo paso es subir tus cambios a tu fork. Para hacerlo, ejecuta `git push`. Ahora Git publicará el estado actual de `dev_branch` a tu fork. + + +## Resolver los conflictos del merge + +A veces cuando el trabajo en una rama tarda mucho tiempo en completarse, los cambios que han sido hechos por otros chocan con los cambios que has hecho en tu rama cuando abres un pull request. Esto se llama un *merge conflict*, y es algo que ocurre cuando varias personas editan las mismas partes de los mismos archivos. + +### Rebase tus cambios + +Un *rebase* es la manera de Git de tomar los cambios que se aplicaron en un punto, deshacerlos, y aplicar estos mismos cambios en otro punto. En el caso de un conflicto de merge, puedes hacer un rebase de tu rama para recoger los cambios que has hecho. + +Para empezar, ejecuta lo siguiente: + +``` +git fetch upstream +git rev-list --left-right --count HEAD...upstream/master +``` + +El comando `git rev-list` ejecutado aquí muestra el número de commits que difieren entre la rama actual y la rama master de QMK. Ejecutamos `git fetch` primero para asegurarnos de que tenemos los refs que representan es estado actual del repo upstream. El output del comando `git rev-list` muestra dos números: + +``` +$ git rev-list --left-right --count HEAD...upstream/master +7 35 +``` + +El primer número representa el número de commits en la rama actual desde que fue creada, y el segundo número es el número de commits hecho a `upstream/master` desde que la rama actual fue creada, o sea los cambios que no están registrados en la rama actual. + +Ahora que sabemos el estado actual de la rama actual y el del repo upstream, podemos empezar una operación rebase: + +``` +git rebase upstream/master +``` +Esto le dice a Git que deshaga los commits en la rama actual, y después los re-aplica en la rama master de QMK. + +``` +$ git rebase upstream/master +First, rewinding head to replay your work on top of it... +Applying: Commit #1 +Using index info to reconstruct a base tree... +M conflicting_file_1.txt +Falling back to patching base and 3-way merge... +Auto-merging conflicting_file_1.txt +CONFLICT (content): Merge conflict in conflicting_file_1.txt +error: Failed to merge in the changes. +hint: Use 'git am --show-current-patch' to see the failed patch +Patch failed at 0001 Commit #1 + +Resolve all conflicts manually, mark them as resolved with +"git add/rm ", then run "git rebase --continue". +You can instead skip this commit: run "git rebase --skip". +To abort and get back to the state before "git rebase", run "git rebase --abort". +``` + +Esto nos dice que tenemos un conflicto de merge, y nos dice el nombre del archivo con el conflict. Abre el archivo en tu editor de texto, y en alguna parte del archivo verás algo así: + +``` +<<<<<<< HEAD +

For help with any issues, email us at support@webhost.us.

+======= +

Need help? Email support@webhost.us.

+>>>>>>> Commit #1 +``` +La línea `<<<<<<< HEAD` marca el principio de un conflicto de merge, y la línea `>>>>>>> Commit #1` marca el final, con las secciones de conflicto separadas por `=======`. La parte del lado `HEAD` is de la versión de QMK master del archivo, y la parte marcada con el mensaje de commit es de la rama actual. + +Ya que Git rastrea *cambios de archivos* en vez del contenido de los archivos directamente, si Git no puede encontrar el texto que estaba en el archivo antes del último commit, no sabrá cómo editar el archivo. El editar el archivo de nuevo resolverá este conflicto. Haz tus cambios, y guarda el archivo. + +``` +

Need help? Email support@webhost.us.

+``` + +Ahora ejecuta: + +``` +git add conflicting_file_1.txt +git rebase --continue +``` + +Git registra los cambios al archivo con conflictos, y sigue aplicando los commits de nuestra rama hasta llegar al final. diff --git a/docs/es/newbs_building_firmware.md b/docs/es/newbs_building_firmware.md new file mode 100644 index 00000000000..ff9873c785e --- /dev/null +++ b/docs/es/newbs_building_firmware.md @@ -0,0 +1,81 @@ +# Construyendo tu primer firmware + +Ahora que has configurado tu entorno de construcción estas listo para empezar a construir firmwares personalizados. Para esta sección de la guía alternaremos entre 3 programas - tu gestor de ficheros, tu editor de texto , y tu ventana de terminal. Manten los 3 abiertos hasta que hayas acabado y estés contento con el firmware de tu teclado. + +Si has cerrado y reabierto la ventana de tu terminal después de seguir el primero paso de esta guía, no olvides hacer `cd qmk_firmware` para que tu terminal esté en el directorio correcto. + +## Navega a tu carpeta de keymaps + +Comienza navegando a la carpeta `keymaps` correspondiente a tu teclado. + +?> Si estás en macOS o Windows hay comandos que puedes utilizar fácilmente para abrir la carpeta keymaps. + +?> macOS: + + abre keyboards//keymaps + +?> Windows: + + inicia .\\keyboards\\\\keymaps + +## Crea una copia del keymap `default` + +Una vez que tengas la carpeta `keymaps` abierta querrás crear una copia de la carpeta `default`. Recomendamos encarecidamente que nombres la carpeta igual que tu nombre de usuario de GitHub, pero puedes utilizar el nombre que quieras siempre que contenga sólo letras en minúscula, números y el caracter de guión bajo. + +Para automatizar el proceso, también tienes la opción de ejecutar el script `new_keymap.sh`. + +Navega a la carpeta `qmk_firmware/util` e introduce lo siguiente: + +``` +./new_keymap.sh +``` + +Por ejemplo, para un usuario llamado John, intentando hacer un keymap nuevo para el 1up60hse, tendría que teclear + +``` +./new_keymap.sh 1upkeyboards/1up60hse john +``` + +## Abre `keymap.c` con tu editor de texto favorito + +Abre tu `keymap.c`. Dentro de este fichero encontrarás la estructura que controla cómo se comporta tu teclado. En lo alto de `keymap.c` puede haber distintos defines y enums que hacen el keymap más fácil de leer. Continuando por abajo encontrarás una línea con este aspecto: + + const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { + +Esta línea indica el comienzo del listado de Capas. Debajo encontrarás líneas que contienen o bien `LAYOUT` o `KEYMAP`, y estas líneas indican el comienzo de una capa. Debajo de esa línea está la lista de teclas que pertenecen a esa capa concreta. + +!> Cuando estés editando tu fichero de keymap ten cuidado con no añadir ni eliminar ninguna coma. Si lo haces el firmware dejará de compilar y puede no ser fácil averiguar dónde está la coma faltante o sobrante. + +## Personaliza el Layout a tu gusto + +Cómo completar esta paso depende enteramente de ti. Haz ese pequeño cambio que querías o rehaz completamente todo. Puedes eliminar capas si no las necesitas todas, o añadir nuevas hasta un total de 32. Comprueba la siguiente documentación para descubrir qué es lo que puedes definir aquí: + +* [Keycodes](keycodes.md) +* [Características](features.md) +* [Preguntas frecuentes](faq.md) + +?> Mientras estás descubriendo cómo funcionan los keymaps, haz pequeños cambios. Cambios mayores pueden hacer difícil la depuración de problemas que puedan aparecer. + +## Construye tu firmware + +Cuando los cambios a tu keymap están completos necesitarás construir el firmware. Para hacerlo vuelve a la ventana de tu terminal y ejecuta el siguiente comando: + + make : + +Por ejemplo, si tu keymap se llama "xyverz" y estás construyendo un keymap para un planck rev5, utilizarás el siguiente comando: + + make planck/rev5:xyverz + +Mientras compila, recibirás un montón de información de salida en la pantalla informándote de qué ficheros están siendo compilados. Debería acabar con una información similar a esta: + +``` +Linking: .build/planck_rev5_xyverz.elf [OK] +Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK] +Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK] +Checking file size of planck_rev5_xyverz.hex [OK] + * File size is fine - 18392/28672 +``` + +## Flashea tu firmware + +Continua con [Flasheando el firmware](newbs_flashing.md) para aprender cómo escribir tu firmware nuevo en tu teclado. diff --git a/docs/es/newbs_building_firmware_configurator.md b/docs/es/newbs_building_firmware_configurator.md new file mode 100644 index 00000000000..60d67f5fa4f --- /dev/null +++ b/docs/es/newbs_building_firmware_configurator.md @@ -0,0 +1,105 @@ +# Configurador QMK + +El [Configurador QMK](https://config.qmk.fm) es un entorno gráfico online que genera ficheros hexadecimales de Firmware QMK. + +?> **Por favor sigue estos pasos en orden.** + +Ve el [Video tutorial](https://www.youtube.com/watch?v=-imgglzDMdY) + +El Configurador QMK functiona mejor con Chrome/Firefox. + + +!> **Ficheros de otras herramientas como KLE, o kbfirmware no serán compatibles con el Configurador QMK. No las cargues, no las importes. El configurador Configurador QMK es una herramienta DIFERENTE. ** + +## Seleccionando tu teclado + +Haz click en el desplegable y selecciona el teclado para el que quieres crear el keymap. + +?> Si tu teclado tiene varias versiones, asegúrate de que seleccionas la correcta.** + +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. + +## Eligiendo el layout de tu teclado + +Elige el layout que mejor represente el keymap que quieres crear. Algunos teclados no tienen suficientes layouts o layouts correctos definidos aún. Serán soportados en el futuro. + +## Nombre del keymap + +Llama a este keymap como quieras. + +?> Si estás teniendo problemas para compilar, puede merecer la pena probar un cambio de nombre, ya que puede que ya exista en el repositorio de QMK Firmware. + +## Creando Tu keymap + +La adición de keycodes se puede hacer de 3 maneras. +1. Arrastrando y soltando +2. Clickando en un hueco vacío en el layout y haciendo click en el keycode que deseas +3. Clickando en un hueco vacío en el layout, presionando la tecla física en tu teclado. + +Mueve el puntero de tu ratón sobre una tecla y un pequeño extracto te dirá que es lo que hace la tecla. Para una descripción más detallada por favor, mira + +[Referencia básica de keycodes](https://docs.qmk.fm/#/keycodes_basic) +[Referencia avanzada de keycodes](https://docs.qmk.fm/#/feature_advanced_keycodes) + +En el caso de que no puedas encontrar un layout que suporte tu keymap, por ejemplo, tres huecos para la barra espaciadora, dos huecos para el retroceso o dos huecos para shift etc etc, rellènalos TODOS. + +### Ejemplo: + +3 huecos para barra espaciadora: Rellena TODOS con barra espaciadora + +2 huecos para retroceso: Rellena AMBOS con retroceso + +2 huecos para el shift derecho: Rellena AMBOS con shift derecho + +1 hueco para el shift izquierdo y 1 hueco para soporte iso: Rellena ambos con el shift izquierdo + +5 huecos , pero sólo 4 teclas: Intuye y comprueba o pregunta a alguien que lo haya hecho anteriormente. + +## Guardando tu keymap para ediciones futuras + +Cuando estés satisfecho con un teclado o quieres trabajar en el después, pulsa el botón `Exportar Keymap`. Guardára tu keymap con el nombre que elijas seguido de .json. + +Entonces podrás cargar este fichero .json en el futuro pulsando el botón `Importar Keymap`. + +!> **PRECAUCIÓN:** No es el mismo tipo de fichero .json usado en kbfirmware.com ni ninguna otra herramienta. Si intentas utilizar un fichero .json de alguna de estas herramientas con el Configurador QMK, existe la posibilidad de que tu teclado **explote**. + +## Generando tu fichero de firmware + +Pulsa el botón verde `Compilar`. + +Cuando la compilación haya acabado, podrás presionar el botón verde `Descargar Firmware`. + +## Flasheando tu teclado + +Por favor, dirígete a la sección de [Flashear firmware](newbs_flashing.md) + +## Problemas comunes + +#### Mi fichero .json no funciona + +Si el fichero .json fue generado con el Configurador QMK, enhorabuena, has dado con un bug. Abre una issue en [qmk_configurator](https://github.com/qmk/qmk_configurator/issues) + +Si no....cómo no viste el mensaje en negrita que puse arriba diciendo que no hay que utilizar otros ficheros .json? + +#### Hay espacios extra en mi layout ¿Qué hago? + +Si te refieres a tener tres espacios para la barra espaciadora, la mejor decisión es rellenar los tres con la barra espaciadora. También se puede hacer lo mismo con las teclas retroceso y las de shift + +#### Para qué sirve el keycode....... + +Por favor, mira + +[Referencia básica de keycodes](https://docs.qmk.fm/#/keycodes_basic) +[Referencia avanzada de keycodes](https://docs.qmk.fm/#/feature_advanced_keycodes) + +#### No compila + +Por favor, revisa las otras capas de tu keymap para asegurarte de que no hay teclas aleatorias presentes. + +## Problemas y bugs + +Siempre aceptamos peticiones de clientes y reportes de bug. Por favor, indícalos en [qmk_configurator](https://github.com/qmk/qmk_configurator/issues) diff --git a/docs/es/newbs_flashing.md b/docs/es/newbs_flashing.md new file mode 100644 index 00000000000..066715c4830 --- /dev/null +++ b/docs/es/newbs_flashing.md @@ -0,0 +1,351 @@ +# Flasheando tu teclado + +Ahora que has construido tu fichero de firmware personalizado querrás flashear tu teclado. + +## Flasheando tu teclado con QMK Toolbox + +La manera más simple de flashear tu teclado sería con [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases). + +De todos modos, QMK Toolbox actualmente sólo está disponible para Windows y macOS. Si estás usando Linux (o sólo quisieras flashear el firmware desde la línea de comandos), tendrás que utilizar el [método indicado abajo](newbs_flashing.md#flash-your-keyboard-from-the-command-line). + +### Cargar el fichero en QMK Toolbox + +Empieza abriendo la aplicación QMK Toolbox. Tendrás que buscar el fichero de firmware usando Finder o Explorer. El firmware de teclado puede estar en uno de estos dos formatos- `.hex` o `.bin`. QMK intenta copiar el apropiado para tu teclado en el fichero raíz `qmk_firmware`. + +?> Si tu estás on Windows o macOS hay comandos que puedes usar para abrir fácilmente la carpeta del firmware actual en Explorer o Finder. + +?> Windows: + + start . + +?> macOS: + + open . + +El fichero de firmware sempre sigue el siguiente formato de nombre: + + _.{bin,hex} + +Por ejemplo, un `plank/rev5` con un keymap `default` tendrá este nombre de fichero: + + planck_rev5_default.hex + +Una vez que hayas localizado el fichero de tu firmware arrástralo a la caja "Fichero local" en QMK Toolbox, o haz click en "Abrir" y navega allí donde tengas almacenado tu fichero de firmware. + +### Pon tu teclado en modo DFU (Bootloader) + +Para poder flashear tu firmware personalizado tienes que poner tu teclado en un modo especial que permite flasheado. Cuando está en este modo no podrás teclear o utilizarlo para ninguna otra cosa. Es muy importante que no desconectes tu teclado, de lo contrario interrumpirás el proceso de flasheo mientras el firmware se está escribiendo. + +Diferentes teclados tienen diferentes maneras de entrar en este modo especial. Si tu PCB actualmente ejecuta QMK o TMK y no has recibido instrucciones específicas, intenta los siguientes pasos en orden: + +* Manten pulsadas ambas teclas shift y pulsa `Pause` +* Manten pulsadas ambas teclas shift y pulsa `B` +* Desconecta tu teclado, mantén pulsada la barra espaciadora y `B` al mismo tiempo, conecta tu teclado y espera un segundo antes de dejar de pulsar las teclas +* Pulsa el botón físico `RESET` situado en el fondo de la PCB +* Localiza los pines en la PCB etiquetados on `BOOT0` o `RESET`, puentea estos dos juntos cuando enchufes la PCB + +Si has tenido éxito verás un mensaje similar a este en QMK Toolbox: + +``` +*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 +*** DFU device connected +``` + +### Flashea tu teclado + +Haz click en el botón `Flash` de QMK Toolbox. Verás una información de salida similar a esta: + +``` +*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 +*** DFU device connected +*** Attempting to flash, please don't remove device +>>> dfu-programmer atmega32u4 erase --force + Erasing flash... Success + Checking memory from 0x0 to 0x6FFF... Empty. +>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex + Checking memory from 0x0 to 0x55FF... Empty. + 0% 100% Programming 0x5600 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + 0% 100% Reading 0x7000 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + Validating... Success + 0x5600 bytes written into 0x7000 bytes memory (76.79%). +>>> dfu-programmer atmega32u4 reset + +*** DFU device disconnected +*** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390 +``` + +## Flashea tu teclado desde la línea de comandos + +Lo primero que tienes que saber es qué bootloader utiliza tu teclado. Hay cuatro bootloaders pincipales que se usan habitualmente . Pro-Micro y sus clones usan CATERINA, Teensy's usa Halfkay, las placas OLKB usan QMK-DFU, y otros chips atmega32u4 usan DFU. + +Puedes encontrar más información sobre bootloaders en la página [Instrucciones de flasheado e información de Bootloader](flashing.md). + +Si sabes qué bootloader estás usando, en el momento de compilar el firmware, podrás añadir algún texto extra al comando `make` para automatizar el proceso de flasheado. + +### DFU + +Para eo bootloader DFU, cuando estés listo para compilar y flashear tu firmware, abre tu ventana de terminal y ejecuta el siguiente comando de construcción: + + make ::dfu + +Por ejemplo, si tu keymap se llama "xyverz" y estás construyendo un keymap para un planck rev5, utilizarás este comando: + + make planck/rev5:xyverz:dfu + +Una vez que finalice de compilar, deberá aparecer lo siguiente: + +``` +Linking: .build/planck_rev5_xyverz.elf [OK] +Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK] +Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK] +Checking file size of planck_rev5_xyverz.hex + * File size is fine - 18574/28672 + ``` + +Después de llegar a este punto, el script de construcción buscará el bootloader DFU cada 5 segundos. Repetirá lo siguiente hasta que se encuentre el dispositivo o lo canceles: + + dfu-programmer: no device present. + Error: Bootloader not found. Trying again in 5s. + +Una vez haya hecho esto, tendrás que reiniciar el controlador. Debería mostrar una información de salida similar a esta: + +``` +*** Attempting to flash, please don't remove device +>>> dfu-programmer atmega32u4 erase --force + Erasing flash... Success + Checking memory from 0x0 to 0x6FFF... Empty. +>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex + Checking memory from 0x0 to 0x55FF... Empty. + 0% 100% Programming 0x5600 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + 0% 100% Reading 0x7000 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + Validating... Success + 0x5600 bytes written into 0x7000 bytes memory (76.79%). +>>> dfu-programmer atmega32u4 reset +``` + +?> Si tienes problemas con esto- del estilo de `dfu-programmer: no device present` - por favor consulta las [Preguntas frecuentes de construcción](faq_build.md). + +#### Comandos DFU + +Hay un número de comandos DFU que puedes usar para flashear firmware a un dispositivo DFU: + +* `:dfu` - Esta es la opción normal y espera hasta que un dispositivo DFU esté disponible, entonces flashea el firmware. Esperará reintentando cada 5 segundos, para ver si un dispositivo DFU ha aparecido. +* `:dfu-ee` - Esta flashea un fichero `eep` en vez del hex normal. Esto no es lo común. +* `:dfu-split-left` - Esta flashea el firmware normal, igual que la opción por defecto (`:dfu`). Sin embargo, también flashea el fichero EEPROM "Lado Izquierdo" para teclados divididos. _Esto es ideal para los ficheros divididos basados en Elite C._ +* `:dfu-split-right` - Esto flashea el firmware normal, igual que la opción por defecto (`:dfu`). Sin embargo, también flashea el fichero EEPROM "Lado Derecho" para teclados divididos. _Esto es ideal para los ficheros divididos basados en Elite C._ + + +### Caterina + +Para placas Arduino y sus clones (como la SparkFun ProMicro), cuando estés listo para compilar y flashear tu firmware, abre tu ventana de terminal y ejecuta el siguiente comando de construcción: + + make ::avrdude + +Por ejemplo, si tu keymap se llama "xyverz" y estás construyendo un keymap para un Lets Split rev2, usarás este comando: + + make lets_split/rev2:xyverz:avrdude + +Una vez que finalice de compilar, deberá aparecer lo siguiente: + +``` +Linking: .build/lets_split_rev2_xyverz.elf [OK] +Creating load file for flashing: .build/lets_split_rev2_xyverz.hex [OK] +Checking file size of lets_split_rev2_xyverz.hex [OK] + * File size is fine - 27938/28672 +Detecting USB port, reset your controller now.............. +``` + +En este punto, reinicia la placa y entonces el script detectará el bootloader y procederá a flashear la placa. La información de salida deber ser algo similar a esto: + +``` +Detected controller on USB port at /dev/ttyS15 + +Connecting to programmer: . +Found programmer: Id = "CATERIN"; type = S + Software Version = 1.0; No Hardware Version given. +Programmer supports auto addr increment. +Programmer supports buffered memory access with buffersize=128 bytes. + +Programmer supports the following devices: + Device code: 0x44 + +avrdude.exe: AVR device initialized and ready to accept instructions + +Reading | ################################################## | 100% 0.00s + +avrdude.exe: Device signature = 0x1e9587 (probably m32u4) +avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed + To disable this feature, specify the -D option. +avrdude.exe: erasing chip +avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex" +avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex +avrdude.exe: writing flash (27938 bytes): + +Writing | ################################################## | 100% 2.40s + +avrdude.exe: 27938 bytes of flash written +avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex: +avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex: +avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex +avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes +avrdude.exe: reading on-chip flash data: + +Reading | ################################################## | 100% 0.43s + +avrdude.exe: verifying ... +avrdude.exe: 27938 bytes of flash verified + +avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF) + +avrdude.exe done. Thank you. +``` +Si tienes problemas con esto, puede ser necesario que hagas esto: + + sudo make ::avrdude + + +Adicionalmente, si quisieras flashear múltiples placas, usa el siguiente comando: + + make ::avrdude-loop + +Cuando hayas acabado de flashear placas, necesitarás pulsar Ctrl + C o cualquier combinación que esté definida en tu sistema operativo para finalizar el bucle. + + +### HalfKay + +Para dispositivos PJRC (Teensy's), cuando estés listo para compilar y flashear tu firmware, abre tu ventana de terminal y ejecuta el siguiente comando de construcción: + + make ::teensy + +Por ejemplo, si tu keymap se llama "xyverz" y estás construyendo un keymap para un Ergodox o un Ergodox EZ, usarás este comando: + + make ergodox_ez:xyverz:teensy + +Una vez que el firmware acabe de compilar, deberá mostrar una información de salida como esta: + +``` +Linking: .build/ergodox_ez_xyverz.elf [OK] +Creating load file for flashing: .build/ergodox_ez_xyverz.hex [OK] +Checking file size of ergodox_ez_xyverz.hex [OK] + * File size is fine - 25584/32256 + Teensy Loader, Command Line, Version 2.1 +Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage +Waiting for Teensy device... + (hint: press the reset button) + ``` + +En este punto, reinicia tu placa. Una vez que lo hayas hecho, deberás ver una información de salida como esta: + + ``` + Found HalfKay Bootloader +Read "./.build/ergodox_ez_xyverz.hex": 28532 bytes, 88.5% usage +Programming............................................................................................................................................................................ +................................................... +Booting +``` + +### BootloadHID + +Para placas basadas en Bootmapper Client(BMC)/bootloadHID/ATmega32A, cuando estés listo para compilar y flashear tu firmware, abre tu ventana de terminal y ejecuta el comando de construcción: + + make ::bootloaderHID + +Por ejemplo, si tu keymap se llama "xyverz" y estás construyendo un keymap para un jj40, usarás esté comando: + + make jj40:xyverz:bootloaderHID + +Una vez que el firmware acaba de compilar, mostrará una información de salida como esta: + +``` +Linking: .build/jj40_default.elf [OK] +Creating load file for flashing: .build/jj40_default.hex [OK] +Copying jj40_default.hex to qmk_firmware folder [OK] +Checking file size of jj40_default.hex [OK] + * The firmware size is fine - 21920/28672 (6752 bytes free) +``` + +Después de llegar a este punto, el script de construcción buscará el bootloader DFU cada 5 segundos. Repetirá lo siguiente hasta que se encuentre el dispositivo o hasta que lo canceles. + +``` +Error opening HIDBoot device: The specified device was not found +Trying again in 5s. +``` + +Una vez que lo haga, querrás reinicar el controlador. Debería entonces mostrar una información de salida similar a esta: + +``` +Page size = 128 (0x80) +Device size = 32768 (0x8000); 30720 bytes remaining +Uploading 22016 (0x5600) bytes starting at 0 (0x0) +0x05580 ... 0x05600 +``` + +### STM32 (ARM) + +Para la mayoría de placas ARM (incluyendo la Proton C, Planck Rev 6, y Preonic Rev 3), cuando estés listo para compilar y flashear tu firmware, abre tu ventana de terminal y ejecuta el siguiente comando de construcción: + + make ::dfu-util + +Por ejemplo, si tu keymap se llama "xyverz" y estás construyendo un keymap para un teclado Planck Revision 6, utilizarás este comando y a continuación reiniciarás el teclado con el bootloader (antes de que acabe de compilar): + + make planck/rev6:xyverz:dfu-util + +Una vez que el firmware acaba de compilar, mostrará una información de salida similar a esta: + +``` +Linking: .build/planck_rev6_xyverz.elf [OK] +Creating binary load file for flashing: .build/planck_rev6_xyverz.bin [OK] +Creating load file for flashing: .build/planck_rev6_xyverz.hex [OK] + +Size after: + text data bss dec hex filename + 0 41820 0 41820 a35c .build/planck_rev6_xyverz.hex + +Copying planck_rev6_xyverz.bin to qmk_firmware folder [OK] +dfu-util 0.9 + +Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. +Copyright 2010-2016 Tormod Volden and Stefan Schmidt +This program is Free Software and has ABSOLUTELY NO WARRANTY +Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ + +Invalid DFU suffix signature +A valid DFU suffix will be required in a future dfu-util release!!! +Opening DFU capable USB device... +ID 0483:df11 +Run-time device DFU version 011a +Claiming USB DFU Interface... +Setting Alternate Setting #0 ... +Determining device status: state = dfuERROR, status = 10 +dfuERROR, clearing status +Determining device status: state = dfuIDLE, status = 0 +dfuIDLE, continuing +DFU mode device DFU version 011a +Device returned transfer size 2048 +DfuSe interface name: "Internal Flash " +Downloading to address = 0x08000000, size = 41824 +Download [=========================] 100% 41824 bytes +Download done. +File downloaded successfully +Transitioning to dfuMANIFEST state +``` + +#### STM32 Commands + +Hay un número de comandos DFU que puedes usar para flashear firmware a un dispositivo DFU: + +* `:dfu-util` - El comando por defecto para flashing en dispositivos STM32. +* `:dfu-util-wait` - Esto funciona como el comando por defecto, pero te da (configurable) 10 segundos de tiempo antes de que intente flashear el firmware. Puedes usar `TIME_DELAY=20` desde la líena de comandos para cambiar este tiempo de retardo. + * Eg: `make ::dfu-util TIME_DELAY=5` +* `:dfu-util-split-left` - Flashea el firmware normal, igual que la opción por defecto (`:dfu-util`). Sin embargo, también flashea el fichero EEPROM "Lado Izquierdo" para teclados divididos. +* `:dfu-util-split-right` - Flashea el firmware normal, igual que la opción por defecto (`:dfu-util`). Sin embargo, también flashea el fichero EEPROM "Lado Derecho" para teclados divididos. + +## ¡Pruébalo! + +¡Felicidades! ¡Tu firmware personalizado ha sido programado en tu teclado! + +Pruébalo y asegúrate de que todo funciona de la manera que tu quieres. Hemos escrito [Testeando y depurando](newbs_testing_debugging.md) para redondear esta guía de novatos, así que pásate por allí para aprender cómo resolver problemas con tu funcionalidad personalizada. diff --git a/docs/es/newbs_getting_started.md b/docs/es/newbs_getting_started.md new file mode 100644 index 00000000000..eb0d6d36fbd --- /dev/null +++ b/docs/es/newbs_getting_started.md @@ -0,0 +1,103 @@ +# Introducción + +El teclado de tu computador tiene un procesador dentro de él, no muy distinto del que está dentro de tu ordenador. Este procesador ejecuta software que es responsable de detectar la pulsación de las teclas y enviar informes sobre el estado del teclado cuando las teclas son pulsadas y liberadas. QMK ocupa el rol de ese software. Cuando construyes un keymap personalizado , estas creando el equivalente de un programa ejecutable en tu teclado. + +QMK intenta poner un montón de poder en tus manos haciendo que las cosas fáciles sean fáciles, y las cosas difíciles posibles. No tienes que saber cómo programar para crear keymaps potentes — sólo tienes que seguir un conjunto simple de reglas sintácticas. + +# Comenzando + +Antes de que puedas construir keymaps, necesitarás instalar algun software y configurar tu entorno de construcción. Esto sólo hay que hacerlo una vez sin importar en cuántos teclados planeas configurar el software. + +Si prefieres hacerlo mediante un interfaz gráfico , por favor, considera utilizar el [Configurador QMK](https://config.qmk.fm). En ese caso dirígete a [Construyendo tu primer firmware usando la GUI](newbs_building_firmware_configurator.md). + + +## Descarga el software + +### Editor de texto + +Necesitarás un programa con el que puedas editar y guardar archivos de **texto plano**, en windows puedes utilizar Notepad y en tu Linux puedes utilizar gedit. Estos dos programas son editores simples y funcionales. En macOS ten cuidado con la aplicación de edición de texto por defecto TextEdit: no guardará texto plano a menos de que se le seleccione explícitamente _Make Plain Text_ desde el menú _Format_. + +También puedes descargar e instalar un editor de texto dedicado como [Sublime Text](https://www.sublimetext.com/) o [VS Code](https://code.visualstudio.com/). Esta es probablemente la mejor manera independientemente de la plataforma, ya que estos programas fueron creados específicamente para editar código. + +?> ¿No estás seguro de qué editor de texto utilizar? Laurence Bradford escribió una [estupenda introducción](https://learntocodewith.me/programming/basics/text-editors/) al tema. + +### QMK Toolbox + +QMK Toolbox is an optional graphical program for Windows and macOS that allows you to both program and debug your custom keyboard. You will likely find it invaluable for easily flashing your keyboard and viewing debug messages that it prints. + +[Download the latest release here.](https://github.com/qmk/qmk_toolbox/releases/latest) + +* For Windows: `qmk_toolbox.exe` (portable) or `qmk_toolbox_install.exe` (installer) +* For macOS: `QMK.Toolbox.app.zip` (portable) or `QMK.Toolbox.pkg` (installer) + +## Configura tu entorno + +Hemos intentado hacer QMK lo más fácil de configurar posible. Sólo tienes que preparar tu entorno Linux o Unix, y luego dejar que QMK +instale el resto. + +?> Si no has trabajado con la línea de comandos de Linux/Unix con anterioridad, hay algunos conceptos y comandos básicos que deberías aprender. Estos recursos te enseñarán lo suficiente para poder trabajar con QMK:
+[Comandos de Linux que debería saber](https://www.guru99.com/must-know-linux-commands.html)
+[Algunos comandos básicos de Unix](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html) + +### Windows + +Necesitarás instalar MSYS2 y Git. + +* Sigue las instrucciones de instalación en la [página de MSYS2](http://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`. + +### macOS + +Necesitarás instalar Homebrew. Sigue las instrucciones que encontrarás en la [página de Homebrew](https://brew.sh). + +Despueś de que se haya inastalado Homebrew, continúa con _Set Up QMK_. En ese paso ejecutará un script que instalará el resto de paquetes. + +### Linux + +Necesitarás instalar Git. Es bastante probable que ya lo tengas, pero si no, uno de los siguientes comandos debería instalarlo: + +* Debian / Ubuntu / Devuan: `apt-get install git` +* Fedora / Red Hat / CentOS: `yum install git` +* Arch: `pacman -S git` + +?> Docker es también una opción en todas las plataformas. [Haz click aquí si quieres detalles.](getting_started_build_tools.md#docker) + +## Configura QMK + +Una vez que hayas configurado tu entorno Linux/Unix, estarás listo para descargar QMK. Haremos esto utilizando Git para "clonar" el respositorio de QMK. Abre una ventana de Terminal o MSYS2 MinGW y mantenla abierta mientras sigues esta guía. Dentro de esa ventana ejecuta estos dos comandos: + +```shell +git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git +cd qmk_firmware +``` + +?> Si ya sabes [cómo usar GitHub](getting_started_github.md), te recomendamos en vez de eso, crees y clones tu propio fork. Si no sabes lo que significa, puedes ignorar este mensaje sin problemas. + +QMK viene con un script para ayudarte a configurar el resto de cosas que necesitarás. Deberías ejecutarlo introduciendo este comando: + + util/qmk_install.sh + +## Prueba tu entorno de construcción + +Ahora que tu entorno de construcción de QMK está configurado, puedes construcir un firmware para tu teclado. Comienza intentado construir el keymap por defecto del teclado. Deberías ser capaz de hacerlo con un comando con este formato: + + make :default + +Por ejemplo, para construir el firmware para un Clueboard 66% deberías usar: + + make clueboard/66/rev3:default + +Cuando esté hecho, deberías tener un montón de información de salida similar a esta: + +``` +Linking: .build/clueboard_66_rev3_default.elf [OK] +Creating load file for flashing: .build/clueboard_66_rev3_default.hex [OK] +Copying clueboard_66_rev3_default.hex to qmk_firmware folder [OK] +Checking file size of clueboard_66_rev3_default.hex [OK] + * The firmware size is fine - 26356/28672 (2316 bytes free) +``` + +# Creando tu keymap + +Ya estás listo para crear tu propio keymap personal! Para hacerlo continua con [Construyendo tu primer firmware](newbs_building_firmware.md). diff --git a/docs/es/newbs_learn_more_resources.md b/docs/es/newbs_learn_more_resources.md new file mode 100644 index 00000000000..34fd7556bf1 --- /dev/null +++ b/docs/es/newbs_learn_more_resources.md @@ -0,0 +1,15 @@ +# Recursos de aprendizaje + +Estos recursos procuran dar miembros nuevos en la communidad QMK un mayor entendimiento de la información proporcionada en la documentación para novatos. + +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 dirigidos específicamente a QMK](contributing.md) + + +Recursos para línea de mandatos: + +* [Excelente tutorial general sobre la línea de mandatos](https://www.codecademy.com/learn/learn-the-command-line) diff --git a/docs/es/newbs_testing_debugging.md b/docs/es/newbs_testing_debugging.md new file mode 100644 index 00000000000..ef7412f15c3 --- /dev/null +++ b/docs/es/newbs_testing_debugging.md @@ -0,0 +1,99 @@ +# Testeando y depurando + +Una vez que hayas flasheado tu teclado con un firmware personalizado estarás listo para probarlo. Con un poco de suerte todo funcionará a la primera, pero si no es así, este documento te ayudará a averiguar qué está mal. + +## Probando + +Probar tu teclado es generalmente bastante sencillo. Persiona cada una de las teclas y asegúrate de que envía la tecla correcta. Existen incluso programas que te ayudarán a asegurarte de que no te dejas ninguna tecla sin comprobar. + +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) + +## Depurando + +Tu teclado mostrará información de depuración si tienes `CONSOLE_ENABLE = yes` en tu `rules.mk`. Por defecto la información de salida es muy limitada, pero puedes encender el modo de depuración para incrementar la información de salida. Utiliza el keycode `DEBUG` de tu keymap, usa la característica [Comando](feature_command.md) para activar el modo depuración, o añade el siguiente código a tu 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; +} +``` + +### Depurando con QMK Toolbox + +Para plataformas compatibles, [QMK Toolbox](https://github.com/qmk/qmk_toolbox) se puede usar para mostrar mensajes de depuración de tu teclado. + +### Depurando con hid_listen + +¿Prefieres una solución basada en una terminal? [hid_listen](https://www.pjrc.com/teensy/hid_listen.html), provista por PJRC, se puede usar también para mostrar mensajes de depuración. Hay binarios preconstruídos para Windows,Linux,y MacOS. + + + +## Enviando tus propios mensajes de depuración + +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 + +Después de eso puedes utilzar algunas funciones print diferentes: + +* `print("string")`: Imprime un string simple +* `uprintf("%s string", var)`: Imprime un string formateado +* `dprint("string")` Imprime un string simple, pero sólo cuando el modo de depuración está activo +* `dprintf("%s string", var)`: Imprime un string formateado, pero sólo cuando el modo de depuración está activo + +## Ejemplos de depuración + +Debajo hay una colección de ejemplos de depuración del mundo real. Para información adicional, Dirígete a [Depurando/Encontrando problemas en QMK](faq_debug.md). + +### ¿Que posición en la matriz tiene esta pulsación de tecla? + +Cuando estés portando, o intentando diagnosticar problemas en la pcb, puede ser útil saber si la pulsación de una tecla es escaneada correctamente. Para hablitar la información de registro en este escenario, añade el siguiente código al `keymap.c` de tus keymaps + +```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: %u, col: %u, row: %u, pressed: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed); +#endif + return true; +} +``` + +Ejemplo de salida +```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 +``` + +### ¿Cuanto tiempo tardó en escanear la pulsación de una tecla? + +Cuando estés probando problemas en el rendimiento, puede ser útil saber la frecuenta a la cual la matríz de pulsadores se está escaneando. Para hablitar la información de registro en este escenario, añade el siguiente código al `config.h` de tus keymaps + +```c +#define DEBUG_MATRIX_SCAN_RATE +``` + +Ejemplo de salida +```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 +``` 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 f11cb76aa2b..e2d0f9b27a5 100644 --- a/docs/faq_build.md +++ b/docs/faq_build.md @@ -28,35 +28,32 @@ sudo udevadm trigger **/etc/udev/rules.d/50-atmel-dfu.rules:** ``` # Atmel ATMega32U4 -SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", MODE:="0666" +SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", TAG+="uaccess", RUN{builtin}+="uaccess" # Atmel USBKEY AT90USB1287 -SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", MODE:="0666" +SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", TAG+="uaccess", RUN{builtin}+="uaccess" # Atmel ATMega32U2 -SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="0666" +SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", TAG+="uaccess", RUN{builtin}+="uaccess" ``` -**/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:** ``` # Input Club keyboard bootloader -SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666" +SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", ATTRS{idProduct}=="b007", TAG+="uaccess", RUN{builtin}+="uaccess" ``` -**/etc/udev/rules.d/55-catalina.rules:** +**/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" +SUBSYSTEMS=="usb", ATTRS{idVendor}=="2a03", ATTRS{idProduct}=="0036", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" +SUBSYSTEMS=="usb", ATTRS{idVendor}=="2341", ATTRS{idProduct}=="0036", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" +SUBSYSTEMS=="usb", ATTRS{idVendor}=="1b4f", ATTRS{idProduct}=="9205", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" +SUBSYSTEMS=="usb", ATTRS{idVendor}=="1b4f", ATTRS{idProduct}=="9203", TAG+="uaccess", RUN{builtin}+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" ``` -**Note:** ModemManager filtering only works when not in strict mode, the following commands can update that settings: +**Note:** With older (before 1.12) 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 ``` @@ -64,9 +61,15 @@ sudo systemctl restart ModemManager **/etc/udev/rules.d/56-dfu-util.rules:** ``` # stm32duino -SUBSYSTEMS=="usb", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0003", MODE:="0666" +SUBSYSTEMS=="usb", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0003", TAG+="uaccess", RUN{builtin}+="uaccess" # Generic stm32 -SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE:="0666" +SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", TAG+="uaccess", RUN{builtin}+="uaccess" +``` + +**/etc/udev/rules.d/57-bootloadhid.rules:** +``` +# bootloadHID +SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05df", TAG+="uaccess", RUN{builtin}+="uaccess" ``` ### Serial device is not detected in bootloader mode on Linux @@ -81,10 +84,6 @@ Re-running the QMK installation script (`./util/qmk_install.sh` from the `qmk_fi If that doesn't work, then you may need to download and run Zadig. See [Bootloader Driver Installation with Zadig](driver_installation_zadig.md) for more detailed information. -## WINAVR is Obsolete -It is no longer recommended and may cause some problem. -See [TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99). - ## USB VID and PID You can use any ID you want with editing `config.h`. Using any presumably unused ID will be no problem in fact except for very low chance of collision with other product. @@ -97,29 +96,6 @@ You can buy a really unique VID:PID here. I don't think you need this for person - 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 -## Cortex: `cstddef: No such file or directory` -GCC 4.8 of Ubuntu 14.04 had this problem and had to update to 4.9 with this PPA. -https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded - -https://github.com/tmk/tmk_keyboard/issues/212 -https://github.com/tmk/tmk_keyboard/wiki/mbed-cortex-porting#compile-error-cstddef -https://developer.mbed.org/forum/mbed/topic/5205/ - -## `clock_prescale_set` and `clock_div_1` Not Available -Your toolchain is too old to support the MCU. For example WinAVR 20100110 doesn't support ATMega32u2. - -``` -Compiling C: ../../tmk_core/protocol/lufa/lufa.c -avr-gcc -c -mmcu=atmega32u2 -gdwarf-2 -DF_CPU=16000000UL -DINTERRUPT_CONTROL_ENDPOINT -DBOOTLOADER_SIZE=4096 -DF_USB=16000000UL -DARCH=ARCH_AVR8 -DUSB_DEVICE_ONLY -DUSE_FLASH_DESCRIPTORS -DUSE_STATIC_OPTIONS="(USB_DEVICE_OPT_FULLSPEED | USB_OPT_REG_ENABLED | USB_OPT_AUTO_PLL)" -DFIXED_CONTROL_ENDPOINT_SIZE=8 -DFIXED_NUM_CONFIGURATIONS=1 -DPROTOCOL_LUFA -DEXTRAKEY_ENABLE -DCONSOLE_ENABLE -DCOMMAND_ENABLE -DVERSION=unknown -Os -funsigned-char -funsigned-bitfields -ffunction-sections -fdata-sections -fno-inline-small-functions -fpack-struct -fshort-enums -fno-strict-aliasing -Wall -Wstrict-prototypes -Wa,-adhlns=obj_alps64/protocol/lufa/lufa.lst -I. -I../../tmk_core -I../../tmk_core/protocol/lufa -I../../tmk_core/protocol/lufa/LUFA-git -I../../tmk_core/common -std=gnu99 -include config.h -MMD -MP -MF .dep/obj_alps64_protocol_lufa_lufa.o.d ../../tmk_core/protocol/lufa/lufa.c -o obj_alps64/protocol/lufa/lufa.o -../../tmk_core/protocol/lufa/lufa.c: In function 'setup_mcu': -../../tmk_core/protocol/lufa/lufa.c:575: warning: implicit declaration of function 'clock_prescale_set' -../../tmk_core/protocol/lufa/lufa.c:575: error: 'clock_div_1' undeclared (first use in this function) -../../tmk_core/protocol/lufa/lufa.c:575: error: (Each undeclared identifier is reported only once -../../tmk_core/protocol/lufa/lufa.c:575: error: for each function it appears in.) -make: *** [obj_alps64/protocol/lufa/lufa.o] Error 1 -``` - - ## BOOTLOADER_SIZE for AVR Note that Teensy2.0++ bootloader size is 2048byte. Some Makefiles may have wrong comment. @@ -134,30 +110,25 @@ 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 +brew rm avr-gcc avr-gcc@8 dfu-programmer dfu-util gcc-arm-none-eabi arm-gcc-bin@8 avrdude qmk +brew install qmk/qmk/qmk +brew link --force avr-gcc@8 +brew link --force arm-gcc-bin@8 ``` -### avr-gcc 8.1 and LUFA +### `avr-gcc` and LUFA -If you updated your avr-gcc to above 7 you may see errors involving LUFA. For example: +If you updated your `avr-gcc` and you see errors involving LUFA, for example: `lib/lufa/LUFA/Drivers/USB/Class/Device/AudioClassDevice.h:380:5: error: 'const' attribute on function returning 'void'` -For now, you need to rollback avr-gcc to 7 in brew. +For now, you need to rollback `avr-gcc` to 8 in Homebrew. ``` brew uninstall --force avr-gcc diff --git a/docs/faq_debug.md b/docs/faq_debug.md index 5cc20251d30..08c84fe4fd3 100644 --- a/docs/faq_debug.md +++ b/docs/faq_debug.md @@ -27,7 +27,7 @@ You may need privilege to access the device on OS like Linux. 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` usually in `matrix_init()` in **matrix.c**. +- 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). @@ -112,56 +112,6 @@ In C `1` means one of [int] type which is [16 bit] in case of AVR so you can't s http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279 - -## Bootloader Jump Doesn't Work -Properly configure bootloader size in **Makefile**. With wrong section size bootloader won't probably start with **Magic command** and **Boot Magic**. -``` -# Size of Bootloaders in bytes: -# Atmel DFU loader(ATmega32U4) 4096 -# Atmel DFU loader(AT90USB128) 8192 -# LUFA bootloader(ATmega32U4) 4096 -# Arduino Caterina(ATmega32U4) 4096 -# USBaspLoader(ATmega***) 2048 -# Teensy halfKay(ATmega32U4) 512 -# Teensy++ halfKay(AT90USB128) 2048 -OPT_DEFS += -DBOOTLOADER_SIZE=4096 -``` -AVR Boot section size are defined by setting **BOOTSZ** fuse in fact. Consult with your MCU datasheet. -Note that **Word**(2 bytes) size and address are used in datasheet while TMK uses **Byte**. - -AVR Boot section is located at end of Flash memory like the followings. -``` -byte Atmel/LUFA(ATMega32u4) byte Atmel(AT90SUB1286) -0x0000 +---------------+ 0x00000 +---------------+ - | | | | - | | | | - | Application | | Application | - | | | | - = = = = - | | 32KB-4KB | | 128KB-8KB -0x6000 +---------------+ 0x1E000 +---------------+ - | Bootloader | 4KB | Bootloader | 8KB -0x7FFF +---------------+ 0x1FFFF +---------------+ - - -byte Teensy(ATMega32u4) byte Teensy++(AT90SUB1286) -0x0000 +---------------+ 0x00000 +---------------+ - | | | | - | | | | - | Application | | Application | - | | | | - = = = = - | | 32KB-512B | | 128KB-2KB -0x7E00 +---------------+ 0x1FC00 +---------------+ - | Bootloader | 512B | Bootloader | 2KB -0x7FFF +---------------+ 0x1FFFF +---------------+ -``` - -And see this discussion for further reference. -https://github.com/tmk/tmk_keyboard/issues/179 - -If you are using a TeensyUSB, there is a [known bug](https://github.com/qmk/qmk_firmware/issues/164) in which the hardware reset button prevents the RESET key from working. Unplugging the keyboard and plugging it back in should resolve the problem. - ## Special Extra Key Doesn't Work (System, Audio Control Keys) You need to define `EXTRAKEY_ENABLE` in `rules.mk` to use them in QMK. @@ -194,24 +144,6 @@ If you would like to keep JTAG enabled, just add the following to your `config.h #define NO_JTAG_DISABLE ``` -## Adding LED Indicators of Lock Keys -You need your own LED indicators for CapsLock, ScrollLock and NumLock? See this post. - -http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p191560 - -## Program Arduino Micro/Leonardo -Push reset button and then run command like this within 8 seconds. - -``` -avrdude -patmega32u4 -cavr109 -b57600 -Uflash:w:adb_usb.hex -P/dev/ttyACM0 -``` - -Device name will vary depending on your system. - -http://arduino.cc/en/Main/ArduinoBoardMicro -https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867 - - ## USB 3 Compatibility I heard some people have a problem with USB 3 port, try USB 2 port. @@ -228,10 +160,3 @@ As of now root of its cause is not clear but some build options seem to be relat 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 diff --git a/docs/faq_general.md b/docs/faq_general.md index f14272ede8f..8e9771cbcd6 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 do 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 0a627469e75..d1d9b919649 100644 --- a/docs/faq_keymap.md +++ b/docs/faq_keymap.md @@ -14,6 +14,17 @@ There are 3 standard keyboard layouts in use around the world- ANSI, ISO, and JI ![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. @@ -67,24 +78,8 @@ After enabling this feature use keycodes `KC_LCAP`, `KC_LNUM` and `KC_LSCR` in y Old vintage mechanical keyboards occasionally have lock switches but modern ones don't have. ***You don't need this feature in most case and just use keycodes `KC_CAPS`, `KC_NLCK` and `KC_SLCK`.*** ## Input Special Characters Other Than ASCII like Cédille 'Ç' -NO UNIVERSAL METHOD TO INPUT THOSE WORKS OVER ALL SYSTEMS. You have to define **MACRO** in way specific to your OS or layout. -See this post for example **MACRO** code. - -http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620 - -On **Windows** you can use `AltGr` key or **Alt code**. -* http://en.wikipedia.org/wiki/AltGr_key -* http://en.wikipedia.org/wiki/Alt_code - -On **Mac** OS defines `Option` key combinations. -* http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input - -On **Xorg** you can use `compose` key, instead. -* http://en.wikipedia.org/wiki/Compose_key - -And see this for **Unicode** input. -* http://en.wikipedia.org/wiki/Unicode_input +See the [Unicode](feature_unicode.md) feature. ## `Fn` Key on macOS @@ -95,13 +90,6 @@ Even worse, it is not recognized unless the keyboard's VID and PID match that of See [this issue](https://github.com/qmk/qmk_firmware/issues/2179) for detailed information. - -## Media Control Keys in Mac OSX -#### KC_MNXT and KC_MPRV Does Not Work on Mac -Use `KC_MFFD`(`KC_MEDIA_FAST_FORWARD`) and `KC_MRWD`(`KC_MEDIA_REWIND`) instead of `KC_MNXT` and `KC_MPRV`. -See https://github.com/tmk/tmk_keyboard/issues/195 - - ## Keys Supported in Mac OSX? You can know which keycodes are supported in OSX from this source code. @@ -137,51 +125,6 @@ https://github.com/tekezo/Karabiner/issues/403 See the [Grave Escape](feature_grave_esc.md) feature. -## Arrow on Right Modifier Keys with Dual-Role -This turns right modifier keys into arrow keys when the keys are tapped while still modifiers when the keys are hold. In TMK the dual-role function is dubbed **TAP**. -``` - -#include "keymap_common.h" - - -/* Arrow keys on right modifier keys with TMK dual role feature - * - * https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role - * https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys - */ -const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - /* 0: qwerty */ - [0] = LAYOUT( \ - ESC, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, MINS,EQL, NUHS,BSPC, \ - TAB, Q, W, E, R, T, Y, U, I, O, P, LBRC,RBRC,BSLS, \ - LCTL,A, S, D, F, G, H, J, K, L, SCLN,QUOT,ENT, \ - LSFT,NUBS,Z, X, C, V, B, N, M, COMM,DOT, SLSH,FN0, ESC, \ - FN4, LGUI,LALT, SPC, APP, FN2, FN1, FN3), - [1] = LAYOUT( \ - GRV, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, TRNS,TRNS, \ - TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\ - TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \ - TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,FN5, TRNS, \ - TRNS,TRNS,TRNS, TRNS, TRNS,FN7, FN6, FN8), -}; - -const uint16_t PROGMEM fn_actions[] = { - [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP), - [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN), - [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT), - [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT), - [4] = ACTION_LAYER_MOMENTARY(1), - [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP), - [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN), - [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME), - [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END), -}; - -``` - -Dual-role key: https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys - - ## Eject on Mac OSX `KC_EJCT` keycode works on OSX. https://github.com/tmk/tmk_keyboard/issues/250 It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default. diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index f748ccd70c2..b8664074a7c 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -1,62 +1,4 @@ -# 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](https://github.com/qmk/qmk_firmware/blob/master/docs/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. @@ -64,11 +6,11 @@ These allow you to combine a modifier with a keycode. When pressed, the keydown |----------|-------------------------------|----------------------------------------------------| |`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` | +|`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)`|`ALGR(kc)` |Hold Right Alt 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` | @@ -76,253 +18,24 @@ These allow you to combine a modifier with a keycode. When pressed, the keydown |`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 +# Legacy Content :id=legacy-content -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. +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. -The modifiers this keycode and `OSM()` accept are prefixed with `MOD_`, not `KC_`: +## Layers :id=switching-and-toggling-layers -|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) | +* [Layers](feature_layers.md) -You can combine these by ORing them together like so: +## Mod-Tap :id=mod-tap -```c -MT(MOD_LCTL | MOD_LSFT, KC_ESC) -``` +* [Mod-Tap](mod_tap.md) -This key would activate Left Control and Left Shift when held, and send Escape when tapped. +## One Shot Keys :id=one-shot-keys -For convenience, QMK includes some Mod-Tap shortcuts to make common combinations more compact in your keymap: +* [One Shot Keys](one_shot_keys.md) -|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/)| +## Tap-Hold Configuration Options :id=tap-hold-configuration-options -## 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`: - -```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 */ -``` - -* `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*. - -Sometimes, you want to activate a one-shot key as part of a macro or tap dance routine. - -For one shot layers, you need to call `set_oneshot_layer(LAYER, ONESHOT_START)` on key down, and `set_oneshot_layer(ONESHOT_PRESSED)` on key up. If you want to cancel the oneshot, call `reset_oneshot_layer()`. - -For one shot mods, you need to call `set_oneshot_mods(MOD)` to set it, or `clear_oneshot_mods()` to cancel it. - -!> 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. - -## Callbacks - -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. - -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: - -```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"); - } -} -``` - -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_auto_shift.md b/docs/feature_auto_shift.md index 9b4b2962490..f0b507bc618 100644 --- a/docs/feature_auto_shift.md +++ b/docs/feature_auto_shift.md @@ -51,12 +51,15 @@ By default, Auto Shift is disabled for any key press that is accompanied by one modifiers. Thus, Ctrl+A that you hold for a really long time is not the same as Ctrl+Shift+A. -You can re-enable Auto Shift for modifiers by adding another rule to your `rules.mk` +You can re-enable Auto Shift for modifiers by adding a define to your `config.h` - AUTO_SHIFT_MODIFIERS = yes +```c +#define AUTO_SHIFT_MODIFIERS +``` In which case, Ctrl+A held past the `AUTO_SHIFT_TIMEOUT` will be sent as Ctrl+Shift+A + ## Configuring Auto Shift If desired, there is some configuration that can be done to change the @@ -65,15 +68,12 @@ behavior of Auto Shift. This is done by setting various variables the A sample is - #ifndef CONFIG_USER_H - #define CONFIG_USER_H +```c +#pragma once - #include "../../config.h" - - #define AUTO_SHIFT_TIMEOUT 150 - #define NO_AUTO_SHIFT_SPECIAL - - #endif +#define AUTO_SHIFT_TIMEOUT 150 +#define NO_AUTO_SHIFT_SPECIAL +``` ### AUTO_SHIFT_TIMEOUT (Value in ms) diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md index 6a2946fd6df..9e467c708a2 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,47 +6,106 @@ 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. -## Usage - 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: -```make +```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. -## AVR driver +|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 | -### Caveats +## Functions :id=functions -Hardware PWM is supported according to the following table: +These functions can be used to change the backlighting in custom code: -|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 | | +|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| -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: +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`, `custom` or `no`. See below for help on individual drivers. + +To configure the backlighting, `#define` these in your `config.h`: + +|Define |Default |Description | +|---------------------|-------------|-------------------------------------------------------------------------------------| +|`BACKLIGHT_PIN` |*Not defined*|The pin that controls the LED(s) | +|`BACKLIGHT_LEVELS` |`3` |The number of brightness levels (maximum 31 excluding off) | +|`BACKLIGHT_CAPS_LOCK`|*Not defined*|Enable Caps Lock indicator using backlight (for keyboards without dedicated LED) | +|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported | +|`BREATHING_PERIOD` |`6` |The length of one backlight "breath" in seconds | +|`BACKLIGHT_ON_STATE` |`1` |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low| + +Unless you are designing your own keyboard, you generally should not need to change the `BACKLIGHT_PIN` or `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 :id=avr-driver + +The `pwm` driver is configured by default, however the equivalent setting within `rules.mk` would be: + +```makefile +BACKLIGHT_DRIVER = pwm +``` + +#### Caveats :id=avr-caveats + +On AVR boards, QMK automatically decides which driver to use according to the following table: + +|Backlight Pin|AT90USB64/128|ATmega16/32U4|ATmega16/32U2|ATmega32A|ATmega328/P| +|-------------|-------------|-------------|-------------|---------|-----------| +|`B1` | | | | |Timer 1 | +|`B2` | | | | |Timer 1 | +|`B5` |Timer 1 |Timer 1 | | | | +|`B6` |Timer 1 |Timer 1 | | | | +|`B7` |Timer 1 |Timer 1 |Timer 1 | | | +|`C4` |Timer 3 | | | | | +|`C5` |Timer 3 | |Timer 1 | | | +|`C6` |Timer 3 |Timer 3 |Timer 1 | | | +|`D4` | | | |Timer 1 | | +|`D5` | | | |Timer 1 | | + +All other pins will use timer-assisted software PWM: |Audio Pin|Audio Timer|Software PWM Timer| |---------|-----------|------------------| @@ -57,44 +116,9 @@ All other pins will use software PWM. If the [Audio](feature_audio.md) feature i |`B6` |Timer 1 |Timer 3 | |`B7` |Timer 1 |Timer 3 | -When both timers are in use for Audio, the backlight PWM will not use a hardware timer, but will instead be triggered during the matrix scan. In this case, breathing is not supported, and the backlight might flicker, because the PWM computation may not be called with enough timing precision. +When both timers are in use for Audio, the backlight PWM cannot use a hardware timer, and will instead be triggered during the matrix scan. In this case, breathing is not supported, and the backlight might flicker, because the PWM computation may not be called with enough timing precision. -### AVR Configuration - -To change the behavior of the backlighting, `#define` these in your `config.h`: - -|Define |Default |Description | -|---------------------|-------------|-------------------------------------------------------------------------------------------------------------| -|`BACKLIGHT_PIN` |`B7` |The pin that controls the LEDs. Unless you are designing your own keyboard, you shouldn't need to change this| -|`BACKLIGHT_PINS` |*Not defined*|experimental: see below for more information | -|`BACKLIGHT_LEVELS` |`3` |The number of brightness levels (maximum 31 excluding off) | -|`BACKLIGHT_CAPS_LOCK`|*Not defined*|Enable Caps Lock indicator using backlight (for keyboards without dedicated LED) | -|`BACKLIGHT_BREATHING`|*Not defined*|Enable backlight breathing, if supported | -|`BREATHING_PERIOD` |`6` |The length of one backlight "breath" in seconds | -|`BACKLIGHT_ON_STATE` |`0` |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low | - -### Backlight On State - -Most backlight circuits are driven by an N-channel MOSFET or NPN transistor. This means that to turn the transistor *on* and light the LEDs, you must drive the backlight pin, connected to the gate or base, *high*. -Sometimes, however, a P-channel MOSFET, or a PNP transistor is used. In this case, when the transistor is on, the pin is driven *low* instead. - -This functionality is configured at the keyboard level with the `BACKLIGHT_ON_STATE` define. - -### Multiple backlight pins - -Most keyboards have only one backlight pin which control all backlight LEDs (especially if the backlight is connected to an hardware PWM pin). -In software PWM, it is possible to define multiple backlight pins. All those pins will be turned on and off at the same time during the PWM duty cycle. -This feature allows to set for instance the Caps Lock LED (or any other controllable LED) brightness at the same level as the other LEDs of the backlight. This is useful if you have mapped LCTRL in place of Caps Lock and you need the Caps Lock LED to be part of the backlight instead of being activated when Caps Lock is on. - -To activate multiple backlight pins, you need to add something like this to your user `config.h`: - -```c -#define BACKLIGHT_LED_COUNT 2 -#undef BACKLIGHT_PIN -#define BACKLIGHT_PINS { F5, B2 } -``` - -### Hardware PWM Implementation +#### Hardware PWM Implementation :id=hardware-pwm-implementation When using the supported pins for backlighting, QMK will use a hardware timer configured to output a PWM signal. This timer will count up to `ICRx` (by default `0xFFFF`) before resetting to 0. The desired brightness is calculated and stored in the `OCRxx` register. When the counter reaches this value, the backlight pin will go low, and is pulled high again when the counter resets. @@ -103,7 +127,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. -### Software 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. @@ -112,48 +136,84 @@ 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 -### Caveats +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: -Currently only hardware PWM is supported, and does not provide automatic configuration. +```makefile +BACKLIGHT_DRIVER = pwm +``` -?> STMF072 support is being investigated. +#### ChibiOS Configuration :id=arm-configuration -### ARM Configuration +The following `#define`s apply only to ARM-based keyboards: -To change the behavior of the backlighting, `#define` these in your `config.h`: +|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| -|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| -|`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 | +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. -## Backlight Functions +#### Caveats :id=arm-caveats -|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, from 0 to | -| |`BACKLIGHT_LEVELS` | -|`get_backlight_level()` |Return the current backlight level | -|`is_backlight_enabled()`|Return whether the backlight is currently on | +Currently only hardware PWM is supported, not timer assisted, and does not provide automatic configuration. -### Backlight Breathing Functions +?> Backlight support for STM32F072 has had limited testing, so YMMV. If unsure, set `BACKLIGHT_ENABLE = no` in your `rules.mk`. -|Function |Description | -|----------|----------------------------------------------------------| -|`breathing_toggle()` |Turn the backlight breathing on or off | -|`breathing_enable()` |Turns on backlight breathing | -|`breathing_disable()` |Turns off backlight breathing | +### Software PWM Driver :id=software-pwm-driver + +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`: + +```makefile +BACKLIGHT_DRIVER = software +``` + +#### 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, which 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'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 +#define BACKLIGHT_PINS { F5, B2 } +``` + +### Custom Driver :id=custom-driver + +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 +``` + +Then implement any of these hooks: + +```c +void backlight_init_ports(void) { + // Optional - runs on startup + // Usually you want to configure pins here +} +void backlight_set(uint8_t level) { + // Optional - runs on level change + // Usually you want to respond to the new value +} + +void backlight_task(void) { + // 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 3ffbfa06804..6cd5c3c6cf3 100644 --- a/docs/feature_bluetooth.md +++ b/docs/feature_bluetooth.md @@ -2,18 +2,18 @@ ## Bluetooth Known Supported Hardware -Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1 Qmk has support for RN-42 HID Firmware and Bluefruit EZ Key the later 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 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. -|Board |Bluetooth Protocol |Connection Type |Rules.mk |Bluetooth Chip| +|Board |Bluetooth Protocol |Connection Type |rules.mk |Bluetooth Chip| |----------------------------------------------------------------|----------------------------|----------------|---------------------------|--------------| -|[Adafruit EzKey HID]("https://www.adafruit.com/product/1535") |Bluetooth Classic | UART | BLUETOOTH = AdafruitEZKey | | -|Rover 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 | nRF5182 | +|[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 | Not Supported Yet but possible: * [Bluefruit LE UART Friend](https://www.adafruit.com/product/2479). [Possible tmk implementation found in](https://github.com/tmk/tmk_keyboard/issues/514) * HC-05 boards flashed with RN-42 firmware. They apparently both use the CSR BC417 Chip. Flashing it with RN-42 firmware gives it HID capability. -* [Sparkfun Bluetooth mate](https://www.sparkfun.com/products/14839) +* Sparkfun Bluetooth Mate * HM-13 based boards ### Adafruit BLE SPI Friend diff --git a/docs/feature_bootmagic.md b/docs/feature_bootmagic.md index ed00d512957..f084052cc74 100644 --- a/docs/feature_bootmagic.md +++ b/docs/feature_bootmagic.md @@ -54,39 +54,39 @@ 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 -|Keycode |Aliases |Description | -|----------------------------------|---------|------------------------------------------| -|`MAGIC_CAPSLOCK_TO_CONTROL` | |Treat Caps Lock as Left Control | -|`MAGIC_UNCAPSLOCK_TO_CONTROL` | |Stop treating Caps Lock as Left Control | -|`MAGIC_HOST_NKRO` | |Force N-Key Rollover (NKRO) on | -|`MAGIC_UNHOST_NKRO` | |Force NKRO off | -|`MAGIC_TOGGLE_NKRO` | |Turn NKRO on or off | -|`MAGIC_NO_GUI` | |Disable the GUI keys (useful when gaming) | -|`MAGIC_UNNO_GUI` | |Enable the GUI keys | -|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides (for macOS)| -|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Alt and GUI | -|`MAGIC_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Alt and GUI swap | -|`MAGIC_SWAP_CTL_GUI` |`CG_SWAP`|Swap Ctrl and GUI on both sides (for macOS)| -|`MAGIC_UNSWAP_CTL_GUI` |`CG_NORM`|Unswap Ctrl and GUI | -|`MAGIC_TOGGLE_CTL_GUI` |`CG_TOGG`|Toggle Ctrl and GUI swap | -|`MAGIC_SWAP_BACKSLASH_BACKSPACE` | |Swap `\` and Backspace | -|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`| |Unswap `\` and Backspace | -|`MAGIC_SWAP_CONTROL_CAPSLOCK` | |Swap Left Control and Caps Lock | -|`MAGIC_UNSWAP_CONTROL_CAPSLOCK` | |Unswap Left Control and Caps Lock | -|`MAGIC_SWAP_GRAVE_ESC` | |Swap ` and Escape | -|`MAGIC_UNSWAP_GRAVE_ESC` | |Unswap ` and Escape | -|`MAGIC_SWAP_LALT_LGUI` | |Swap Left Alt and Left GUI | -|`MAGIC_UNSWAP_LALT_LGUI` | |Unswap Left Alt and Left GUI | -|`MAGIC_SWAP_RALT_RGUI` | |Swap Right Alt and Right GUI | -|`MAGIC_UNSWAP_RALT_RGUI` | |Unswap Right Alt and Right GUI | -|`MAGIC_SWAP_LCTL_LGUI` | |Swap Left Control and Left GUI | -|`MAGIC_UNSWAP_LCTL_LGUI` | |Unswap Left Control and Left GUI | -|`MAGIC_SWAP_RCTL_RGUI` | |Swap Right Control and Right GUI | -|`MAGIC_UNSWAP_RCTL_RGUI` | |Unswap Right Control and Right GUI | -|`MAGIC_EE_HANDS_LEFT` | |Set "Left Hand" for EE_HANDS handedness | -|`MAGIC_EE_HANDS_RIGHT` | |Set "Right Hand" for EE_HANDS handedness | +|Key |Aliases |Description | +|----------------------------------|---------|--------------------------------------------------------------------------| +|`MAGIC_SWAP_CONTROL_CAPSLOCK` |`CL_SWAP`|Swap Caps Lock and Left Control | +|`MAGIC_UNSWAP_CONTROL_CAPSLOCK` |`CL_NORM`|Unswap Caps Lock and Left Control | +|`MAGIC_CAPSLOCK_TO_CONTROL` |`CL_CTRL`|Treat Caps Lock as Control | +|`MAGIC_UNCAPSLOCK_TO_CONTROL` |`CL_CAPS`|Stop treating Caps Lock as Control | +|`MAGIC_SWAP_LCTL_LGUI` |`LCG_SWP`|Swap Left Control and GUI | +|`MAGIC_UNSWAP_LCTL_LGUI` |`LCG_NRM`|Unswap Left Control and GUI | +|`MAGIC_SWAP_RCTL_RGUI` |`RCG_SWP`|Swap Right Control and GUI | +|`MAGIC_UNSWAP_RCTL_RGUI` |`RCG_NRM`|Unswap Right Control and GUI | +|`MAGIC_SWAP_CTL_GUI` |`CG_SWAP`|Swap Control and GUI on both sides | +|`MAGIC_UNSWAP_CTL_GUI` |`CG_NORM`|Unswap Control and GUI on both sides | +|`MAGIC_TOGGLE_CTL_GUI` |`CG_TOGG`|Toggle Control and GUI swap on both sides | +|`MAGIC_SWAP_LALT_LGUI` |`LAG_SWP`|Swap Left Alt and GUI | +|`MAGIC_UNSWAP_LALT_LGUI` |`LAG_NRM`|Unswap Left Alt and GUI | +|`MAGIC_SWAP_RALT_RGUI` |`RAG_SWP`|Swap Right Alt and GUI | +|`MAGIC_UNSWAP_RALT_RGUI` |`RAG_NRM`|Unswap Right Alt and GUI | +|`MAGIC_SWAP_ALT_GUI` |`AG_SWAP`|Swap Alt and GUI on both sides | +|`MAGIC_UNSWAP_ALT_GUI` |`AG_NORM`|Unswap Alt and GUI on both sides | +|`MAGIC_TOGGLE_ALT_GUI` |`AG_TOGG`|Toggle Alt and GUI swap on both sides | +|`MAGIC_NO_GUI` |`GUI_OFF`|Disable the GUI keys | +|`MAGIC_UNNO_GUI` |`GUI_ON` |Enable the GUI keys | +|`MAGIC_SWAP_GRAVE_ESC` |`GE_SWAP`|Swap ` and Escape | +|`MAGIC_UNSWAP_GRAVE_ESC` |`GE_NORM`|Unswap ` and Escape | +|`MAGIC_SWAP_BACKSLASH_BACKSPACE` |`BS_SWAP`|Swap `\` and Backspace | +|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|`BS_NORM`|Unswap `\` and Backspace | +|`MAGIC_HOST_NKRO` |`NK_ON` |Enable N-key rollover | +|`MAGIC_UNHOST_NKRO` |`NK_OFF` |Disable N-key rollover | +|`MAGIC_TOGGLE_NKRO` |`NK_TOGG`|Toggle N-key rollover | +|`MAGIC_EE_HANDS_LEFT` |`EH_LEFT`|Set the master half of a split keyboard as the left hand (for `EE_HANDS`) | +|`MAGIC_EE_HANDS_RIGHT` |`EH_RGHT`|Set the master half of a split keyboard as the right hand (for `EE_HANDS`)| ## Configuration @@ -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_debounce_type.md b/docs/feature_debounce_type.md index 38eca3f37c8..65b4ea1e535 100644 --- a/docs/feature_debounce_type.md +++ b/docs/feature_debounce_type.md @@ -17,14 +17,14 @@ endif | DEBOUNCE_TYPE | Description | What else is needed | | ------------- | --------------------------------------------------- | ----------------------------- | | Not defined | Use the default algorithm, currently sym_g | Nothing | -| custom | Use your own debounce.c | ```SRC += debounce.c``` add your own debounce.c and implement necessary functions | +| 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 | **Regarding split keyboards**: The debounce code is compatible with split keyboards. # Use your own debouncing code -* Set ```DEBOUNCE_TYPE = custom ```. +* Set ```DEBOUNCE_TYPE = custom```. * Add ```SRC += debounce.c``` * Add your own ```debounce.c```. Look at current implementations in ```quantum/debounce``` for examples. * Debouncing occurs after every raw matrix scan. @@ -33,10 +33,11 @@ The debounce code is compatible with split keyboards. # 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_DELAY``` milliseconds of no further input for that row. +* 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_DELAY``` milliseconds of no further input for that key -* sym_g - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE_DELAY``` milliseconds of no changes has occured, all input changes are pushed. +* eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key +* sym_g - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occured, all input changes are pushed. +* sym_pk - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occured on that key, the key status change is pushed. 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 0d11a28641a..01f2a0ca407 100644 --- a/docs/feature_dynamic_macros.md +++ b/docs/feature_dynamic_macros.md @@ -4,51 +4,45 @@ QMK supports temporary macros created on the fly. We call these Dynamic Macros. You can store one or two macros and they may have a combined total of 128 keypresses. You can increase this size at the cost of RAM. -To enable them, first add a new element to the end of your `keycodes` enum — `DYNAMIC_MACRO_RANGE`: +To enable them, first include `DYNAMIC_MACRO_ENABLE = yes` in your `rules.mk`. Then, add the following keys to your keymap: -```c -enum keycodes { - QWERTY = SAFE_RANGE, - COLEMAK, - DVORAK, - PLOVER, - LOWER, - RAISE, - BACKLIT, - EXT_PLV, - DYNAMIC_MACRO_RANGE, -}; -``` +|Key |Alias |Description | +|------------------|----------|---------------------------------------------------| +|`DYN_REC_START1` |`DM_REC1` |Start recording Macro 1 | +|`DYN_REC_START2` |`DM_REC2` |Start recording Macro 2 | +|`DYN_MACRO_PLAY1` |`DM_PLY1` |Replay Macro 1 | +|`DYN_MACRO_PLAY2` |`DM_PLY2` |Replay Macro 2 | +|`DYN_REC_STOP` |`DM_RSTP` |Finish the macro that is currently being recorded. | -Your `keycodes` enum may have a slightly different name. You must add `DYNAMIC_MACRO_RANGE` as the last element because `dynamic_macros.h` will add some more keycodes after it. +That should be everything necessary. -Below it, include the `dynamic_macro.h` header: +To start recording the macro, press either `DYN_REC_START1` or `DYN_REC_START2`. -```c - #include "dynamic_macro.h"` -``` +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. -Add the following keys to your keymap: +To replay the macro, press either `DYN_MACRO_PLAY1` or `DYN_MACRO_PLAY2`. -* `DYN_REC_START1` — start recording the macro 1, -* `DYN_REC_START2` — start recording the macro 2, -* `DYN_MACRO_PLAY1` — replay the macro 1, -* `DYN_MACRO_PLAY2` — replay the macro 2, -* `DYN_REC_STOP` — finish the macro that is currently being recorded. +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. -Add the following code to the very beginning of your `process_record_user()` function: +?> 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. -```c - if (!process_record_dynamic_macro(keycode, record)) { - return false; - } -``` +## Customization -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 replay the macro, press either `DYN_MACRO_PLAY1` or `DYN_MACRO_PLAY2`. +There are a number of options added that should allow some additional degree of customization -Note that it's 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. +|Define |Default |Description | +|----------------------------|----------------|-----------------------------------------------------------------------------------------------------------------| +|`DYNAMIC_MACRO_SIZE` |128 |Sets the amount of memory that Dynamic Macros can use. This is a limited resource, dependent on the controller. | +|`DYNAMIC_MACRO_USER_CALL` |*Not defined* |Defining this falls back to using the user `keymap.c` file to trigger the macro behavior. | +|`DYNAMIC_MACRO_NO_NESTING` |*Not Defined* |Defining this disables the ability to call a macro from another macro (nested macros). | -For users of the earlier versions of dynamic macros: It is still possible to finish the macro recording using just the layer modifier used to access the dynamic macro keys, without a dedicated `DYN_REC_STOP` key. If you want this behavior back, use the following snippet instead of the one above: + +If the LEDs start blinking during the recording with each keypress, it means there is no more space for the macro in the macro buffer. To fit the macro in, either make the other macro shorter (they share the same buffer) or increase the buffer size by adding the `DYNAMIC_MACRO_SIZE` define in your `config.h` (default value: 128; please read the comments for it in the header). + + +### DYNAMIC_MACRO_USER_CALL + +For users of the earlier versions of dynamic macros: It is still possible to finish the macro recording using just the layer modifier used to access the dynamic macro keys, without a dedicated `DYN_REC_STOP` key. If you want this behavior back, add `#define DYNAMIC_MACRO_USER_CALL` to your `config.h` and insert the following snippet at the beginning of your `process_record_user()` function: ```c uint16_t macro_kc = (keycode == MO(_DYN) ? DYN_REC_STOP : keycode); @@ -58,6 +52,15 @@ For users of the earlier versions of dynamic macros: It is still possible to fin } ``` -If the LEDs start blinking during the recording with each keypress, it means there is no more space for the macro in the macro buffer. To fit the macro in, either make the other macro shorter (they share the same buffer) or increase the buffer size by setting the `DYNAMIC_MACRO_SIZE` preprocessor macro (default value: 128; please read the comments for it in the header). +### User Hooks -For the details about the internals of the dynamic macros, please read the comments in the `dynamic_macro.h` header. +There are a number of hooks that you can use to add custom functionality and feedback options to Dynamic Macro feature. This allows for some additional degree of customization. + +Note, that direction indicates which macro it is, with `1` being Macro 1, `-1` being Macro 2, and 0 being no macro. + +* `dynamic_macro_record_start_user(void)` - Triggered when you start recording a macro. +* `dynamic_macro_play_user(int8_t direction)` - Triggered when you play back a macro. +* `dynamic_macro_record_key_user(int8_t direction, keyrecord_t *record)` - Triggered on each keypress while recording a macro. +* `dynamic_macro_record_end_user(int8_t direction)` - Triggered when the macro recording is stopped. + +Additionally, you can call `dynamic_macro_led_blink()` to flash the backlights if that feature is enabled. diff --git a/docs/feature_encoders.md b/docs/feature_encoders.md index cbf72914e92..8f9ba1a80a7 100644 --- a/docs/feature_encoders.md +++ b/docs/feature_encoders.md @@ -2,23 +2,35 @@ 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 +``` ## Split Keyboards @@ -33,27 +45,31 @@ If you are using different pinouts for the encoders on each half of a split keyb 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 acd156a27aa..ff7337a51a4 100644 --- a/docs/feature_haptic_feedback.md +++ b/docs/feature_haptic_feedback.md @@ -2,7 +2,7 @@ ## Haptic feedback rules.mk options -The following options are currently available for haptic feedback in `rule.mk`: +The following options are currently available for haptic feedback in `rules.mk`: `HAPTIC_ENABLE += DRV2605L` @@ -22,7 +22,7 @@ Not all keycodes below will work depending on which haptic mechanism you have ch | Name | Description | |-----------|-------------------------------------------------------| |`HPT_ON` | Turn haptic feedback on | -|`HPT_OFF` | Turn haptic feedback on | +|`HPT_OFF` | Turn haptic feedback off | |`HPT_TOG` | Toggle haptic feedback on/off | |`HPT_RST` | Reset haptic feedback config to default | |`HPT_FBK` | Toggle feedback to occur on keypress, release or both | @@ -41,11 +41,15 @@ First you will need a build a circuit to drive the solenoid through a mosfet as [Wiring diagram provided by Adafruit](https://playground.arduino.cc/uploads/Learning/solenoid_driver.pdf) -Select a pin that has PWM for the signal pin -``` -#define SOLENOID_PIN *pin* -``` +| 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. | + +?> Dwell time is how long the "plunger" stays activated. The dwell time changes how the solenoid sounds. 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. @@ -151,4 +155,4 @@ This will set what sequence HPT_RST will set as the active mode. If not defined, ### DRV2605L Continuous Haptic Mode -This mode sets continuous haptic feedback with the option to increase or decrease strength. \ No newline at end of file +This mode sets continuous haptic feedback with the option to increase or decrease strength. 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_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 82cf789017d..0803a411c6c 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: @@ -22,10 +22,10 @@ void matrix_scan_user(void) { SEND_STRING("QMK is awesome."); } SEQ_TWO_KEYS(KC_D, KC_D) { - SEND_STRING(SS_LCTRL("a")SS_LCTRL("c")); + SEND_STRING(SS_LCTL("a") SS_LCTL("c")); } SEQ_THREE_KEYS(KC_D, KC_D, KC_S) { - SEND_STRING("https://start.duckduckgo.com"SS_TAP(X_ENTER)); + SEND_STRING("https://start.duckduckgo.com\n"); } SEQ_TWO_KEYS(KC_A, KC_S) { register_code(KC_LGUI); @@ -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 @@ -115,11 +115,11 @@ void matrix_scan_user(void) { SEQ_ONE_KEY(KC_E) { // Anything you can do in a macro. - SEND_STRING(SS_LCTRL(SS_LSFT("t"))); + SEND_STRING(SS_LCTL(SS_LSFT("t"))); did_leader_succeed = true; } else SEQ_TWO_KEYS(KC_E, KC_D) { - SEND_STRING(SS_LGUI("r")"cmd"SS_TAP(KC_ENTER)SS_LCTRL("c")); + SEND_STRING(SS_LGUI("r") "cmd\n" SS_LCTL("c")); did_leader_succeed = true; } leader_end(); diff --git a/docs/feature_macros.md b/docs/feature_macros.md index d81c3c65597..acd40d1bf34 100644 --- a/docs/feature_macros.md +++ b/docs/feature_macros.md @@ -6,34 +6,34 @@ Macros allow you to send multiple keystrokes when pressing just one key. QMK has ## The New Way: `SEND_STRING()` & `process_record_user` -Sometimes you just want a key to type out words or phrases. For the most common situations we've provided `SEND_STRING()`, which will type out your string (i.e. a sequence of characters) for you. All ASCII characters that are easily translated to a keycode are supported (e.g. `\n\t`). +Sometimes you want a key to type out words or phrases. For the most common situations, we've provided `SEND_STRING()`, which will type out a string (i.e. a sequence of characters) for you. All ASCII characters that are easily translatable to a keycode are supported (e.g. `qmk 123\n\t`). Here is an example `keymap.c` for a two-key keyboard: ```c enum custom_keycodes { - QMKBEST = SAFE_RANGE, + QMKBEST = SAFE_RANGE, }; bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { + switch (keycode) { case QMKBEST: - if (record->event.pressed) { - // when keycode QMKBEST is pressed - SEND_STRING("QMK is the best thing ever!"); - } else { - // when keycode QMKBEST is released - } - break; - - } - return true; + if (record->event.pressed) { + // when keycode QMKBEST is pressed + SEND_STRING("QMK is the best thing ever!"); + } else { + // when keycode QMKBEST is released + } + break; + } + return true; }; const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - [0] = { - {QMKBEST, KC_ESC} - } + [0] = { + {QMKBEST, KC_ESC}, + // ... + }, }; ``` @@ -49,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/" SS_TAP(X_ENTER)); - } 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_LCTRL("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,20 +150,33 @@ 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_LCTRL(string)` -* `SS_LGUI(string)` -* `SS_LALT(string)` +* `SS_LCTL(string)` * `SS_LSFT(string)` -* `SS_RALT(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)`, `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. They can be used like this: - SEND_STRING(SS_LCTRL("a")); + SEND_STRING(SS_LCTL("a")); -Which would send LCTRL+a (LCTRL down, a, LCTRL up) - notice that they take strings (eg `"k"`), and not the `X_K` keycodes. +Which would send Left Control+`a` (Left Control down, `a`, Left Control up) - notice that they take strings (eg `"k"`), and not the `X_K` keycodes. ### Alternative Keymaps @@ -151,6 +207,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) for additional functionality. For example `reset_keyboard()` allows you to reset the keyboard as part of a macro. + ### `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 @@ -195,11 +253,11 @@ 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 @@ -216,7 +274,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { if (!is_alt_tab_active) { is_alt_tab_active = true; register_code(KC_LALT); - } + } alt_tab_timer = timer_read(); register_code(KC_TAB); } else { @@ -227,7 +285,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); @@ -316,7 +374,7 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { ``` -## Advanced Example: +## Advanced Example: ### Single-Key Copy/Paste diff --git a/docs/feature_mouse_keys.md b/docs/feature_mouse_keys.md index 363662f633b..a6b46bc151f 100644 --- a/docs/feature_mouse_keys.md +++ b/docs/feature_mouse_keys.md @@ -39,10 +39,11 @@ In your keymap you can use the following keycodes to map key presses to mouse ac ## Configuring mouse keys -Mouse keys supports two different modes to move the cursor: +Mouse keys supports three different modes to move the cursor: * **Accelerated (default):** Holding movement keys accelerates the cursor until it reaches its maximum speed. * **Constant:** Holding movement keys moves the cursor at constant speeds. +* **Combined:** Holding movement keys accelerates the cursor until it reaches its maximum speed, but holding acceleration and movement keys simultaneously moves the cursor at constant speeds. The same principle applies to scrolling. @@ -58,6 +59,8 @@ This is the default mode. You can adjust the cursor and scrolling acceleration u |`MOUSEKEY_INTERVAL` |50 |Time between cursor movements | |`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,6 +69,7 @@ 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). @@ -117,3 +121,22 @@ 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 +``` diff --git a/docs/feature_oled_driver.md b/docs/feature_oled_driver.md index 623f1816ac1..5f3095198fb 100644 --- a/docs/feature_oled_driver.md +++ b/docs/feature_oled_driver.md @@ -1,139 +1,142 @@ # 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 characer index for custom fonts | +|`OLED_FONT_END` |`223` |The ending characer 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.| ## 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 +146,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 +170,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 +221,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,6 +238,19 @@ 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); +// 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,12 +265,24 @@ 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); @@ -266,26 +300,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..c9309d6975d 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 ``` @@ -21,26 +21,28 @@ Keep in mind that a report_mouse_t (here "mouseReport") has the following proper * `mouseReport.h` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing horizontal scrolling (+ right, - left). * `mouseReport.buttons` - this is a uint8_t in which the last 5 bits are used. These bits represent the mouse button state - bit 3 is mouse button 5, and bit 7 is mouse button 1. -When the mouse report is sent, the x, y, v, and h values are set to 0 (this is done in "pointing_device_send()", which can be overridden to avoid this behavior). This way, button states persist, but movement will only occur once. For further customization, both `pointing_device_init` and `pointing_device_task` can be overridden. +Once you have made the necessary changes to the mouse report, you need to send it: + +* `pointing_device_send()` - Sends the mouse report to the host and zeroes out the report. + +When the mouse report is sent, the x, y, v, and h values are set to 0 (this is done in `pointing_device_send()`, which can be overridden to avoid this behavior). This way, button states persist, but movement will only occur once. For further customization, both `pointing_device_init` and `pointing_device_task` can be overridden. 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..e549810855a 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: -``` +```c #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 @@ -55,19 +55,19 @@ 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). --- -### 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 +```makefile RGB_MATRIX_ENABLE = 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 +90,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 @@ -107,17 +107,17 @@ Where `X_Y` is the location of the LED in the matrix defined by [the datasheet]( --- -### WS2812 (AVR only) +### 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 +```makefile RGB_MATRIX_ENABLE = 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 @@ -128,7 +128,7 @@ Configure the hardware via your `config.h`: From this point forward the configuration is the same for all the drivers. The `led_config_t` struct provides a key electrical matrix to led index lookup table, what the physical position of each LED is on the board, and what type of key or usage the LED if the LED represents. Here is a brief example: -```C +```c const led_config_t g_led_config = { { // Key Matrix to LED Index { 5, NO_LED, NO_LED, 0 }, @@ -146,7 +146,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,44 +157,58 @@ 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: -* `RGB_TOG` - toggle -* `RGB_MOD` - cycle through modes -* `RGB_HUI` - increase hue -* `RGB_HUD` - decrease hue -* `RGB_SAI` - increase saturation -* `RGB_SAD` - decrease saturation -* `RGB_VAI` - increase value -* `RGB_VAD` - decrease value -* `RGB_SPI` - increase speed effect (no EEPROM support) -* `RGB_SPD` - decrease speed effect (no EEPROM support) -* `RGB_MODE_*` keycodes will generally work, but are not currently mapped to the correct effects for the RGB Matrix system +|Key |Aliases |Description | +|-------------------|----------|--------------------------------------------------------------------------------------| +|`RGB_TOG` | |Toggle RGB lighting on or off | +|`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held | +|`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held | +|`RGB_HUI` | |Increase hue, decrease hue when Shift is held | +|`RGB_HUD` | |Decrease hue, increase hue when Shift is held | +|`RGB_SAI` | |Increase saturation, decrease saturation when Shift is held | +|`RGB_SAD` | |Decrease saturation, increase saturation when Shift is held | +|`RGB_VAI` | |Increase value (brightness), decrease value when Shift is held | +|`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 Matrix Effects +* `RGB_MODE_*` keycodes will generally work, but not all of the modes are currently mapped to the correct effects for the RGB Matrix system. + +`RGB_MODE_PLAIN`, `RGB_MODE_BREATHE`, `RGB_MODE_RAINBOW`, and `RGB_MATRIX_SWIRL` are the only ones that are mapped properly. The rest don't have a direct equivalent, and are not mapped. + +!> By default, if you have both the [RGB Light](feature_rgblight.md) and the RGB Matrix feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature. + +## RGB Matrix Effects :id=rgb-matrix-effects 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 @@ -280,16 +294,16 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con |`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH` |Disables `RGB_MATRIX_SOLID_MULTISPLASH` | -## Custom RGB Matrix Effects +## Custom RGB Matrix Effects :id=custom-rgb-matrix-effects -By setting `RGB_MATRIX_CUSTOM_USER` (and/or `RGB_MATRIX_CUSTOM_KB`) in `rule.mk`, new effects can be defined directly from userspace, without having to edit any QMK core files. +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. To declare new effects, create a new `rgb_matrix_user/kb.inc` that looks something like this: `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 +```c // !!! DO NOT ADD #pragma once !!! // // Step 1. @@ -336,7 +350,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. @@ -364,41 +378,121 @@ 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) #define RGB_MATRIX_MAXIMUM_BRIGHTNESS 200 // limits maximum brightness of LEDs to 200 out of 255. If not defined maximum brightness is set to 255 #define RGB_MATRIX_STARTUP_MODE RGB_MATRIX_CYCLE_LEFT_RIGHT // Sets the default mode, if none has been set +#define RGB_MATRIX_STARTUP_HUE 0 // Sets the default hue value, if none has been set +#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 | +|`rgb_matrix_disable_noeeprom()` |Turn effect range LEDs off (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_reverse()` |Change the mode to the previous RGB animation in the list of enabled RGB animations | +|`rgb_matrix_increase_speed()` |Increases the speed of the animations | +|`rgb_matrix_decrease_speed()` |Decreases the speed of the animations | + +### 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_decrease_hue()` |Decrease the hue for effect range LEDs. This wraps around at minimum hue | +|`rgb_matrix_increase_sat()` |Increase the saturation for effect range LEDs. This wraps around at maximum saturation | +|`rgb_matrix_decrease_sat()` |Decrease the saturation for effect range LEDs. This wraps around at minimum saturation | +|`rgb_matrix_increase_val()` |Increase the value for effect range LEDs. This wraps around at maximum value | +|`rgb_matrix_decrease_val()` |Decrease the value for effect range LEDs. This wraps around at minimum value | +|`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); +} +``` + +### 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 be4ddfa7295..a81b50e828a 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -6,7 +6,7 @@ QMK has the ability to control RGB LEDs attached to your keyboard. This is commo Some keyboards come with RGB LEDs preinstalled. Others must have them installed after the fact. See the [Hardware Modification](#hardware-modification) section for information on adding RGB lighting to your keyboard. -Currently QMK supports the following addressable LEDs on AVR microcontrollers (however, the white LED in RGBW variants is not supported): +Currently QMK supports the following addressable LEDs (however, the white LED in RGBW variants is not supported): * WS2811, WS2812, WS2812B, WS2812C, etc. * SK6812, SK6812MINI, SK6805 @@ -48,12 +48,12 @@ Changing the **Value** sets the overall brightness.
|`RGB_TOG` | |Toggle RGB lighting on or off | |`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held | |`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held| -|`RGB_HUI` | |Increase hue | -|`RGB_HUD` | |Decrease hue | -|`RGB_SAI` | |Increase saturation | -|`RGB_SAD` | |Decrease saturation | -|`RGB_VAI` | |Increase value (brightness) | -|`RGB_VAD` | |Decrease value (brightness) | +|`RGB_HUI` | |Increase hue, decrease hue when Shift is held | +|`RGB_HUD` | |Decrease hue, increase hue when Shift is held | +|`RGB_SAI` | |Increase saturation, decrease saturation when Shift is held | +|`RGB_SAD` | |Decrease saturation, increase saturation when Shift is held | +|`RGB_VAI` | |Increase value (brightness), decrease value when Shift is held | +|`RGB_VAD` | |Decrease value (brightness), increase value 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` |Rainbow animation mode | @@ -64,6 +64,9 @@ 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`: @@ -76,6 +79,7 @@ Your RGB lighting can be configured by placing these `#define`s in your `config. |`RGBLIGHT_LIMIT_VAL` |`255` |The maximum brightness level | |`RGBLIGHT_SLEEP` |*Not defined*|If defined, the RGB lighting will be switched off when the host goes to sleep| |`RGBLIGHT_SPLIT` |*Not defined*|If defined, synchronization functionality for split keyboards is added| +|`RGBLIGHT_DISABLE_KEYCODES`|*not defined*|If defined, disables the ability to control RGB Light from the keycodes. You must use code functions to control the feature| ## Effects and Animations @@ -94,6 +98,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 +108,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,6 +120,7 @@ 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 @@ -131,6 +137,8 @@ The following options are used to tweak the various animations: |`RGBLIGHT_EFFECT_KNIGHT_OFFSET` |`0` |The number of LEDs to start the "Knight" animation from the start of the strip by | |`RGBLIGHT_RAINBOW_SWIRL_RANGE` |`255` |Range adjustment for the rainbow swirl effect to get different swirls | |`RGBLIGHT_EFFECT_SNAKE_LENGTH` |`4` |The number of LEDs to light up for the "Snake" animation | +|`RGBLIGHT_EFFECT_TWINKLE_LIFE` |`75` |Adjusts how quickly each LED brightens and dims when twinkling (in animation steps) | +|`RGBLIGHT_EFFECT_TWINKLE_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 +176,116 @@ 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 + +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 out LED ranges and the colors we want to overlay on them using an array of `rgblight_segment_t` using the `RGBLIGHT_LAYER_SEGMENTS` macro. We can define multiple layers and enable/disable them independently: + +```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} +); +// 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 +); + +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 +layer_state_t layer_state_set_user(layer_state_t state) { + // Both layers will light up if both kb layers are active + rgblight_set_layer_state(1, layer_state_cmp(state, 1)); + rgblight_set_layer_state(2, layer_state_cmp(state, 2)); + return state; +} + +bool led_update_user(led_t led_state) { + rgblight_set_layer_state(0, led_state.caps_lock); + return true; +} +``` + +### 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: @@ -263,13 +377,21 @@ rgblight_sethsv(HSV_GREEN, 2); // led 2 |`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) | +#### 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 @@ -363,8 +485,8 @@ Using the `rgblight_set_clipping_range()` function, you can prepare more buffers You can set the Clipping Range by executing the following code. ```c -// some soruce - rgblight_set_clipping_range(3, 4); +// some source +rgblight_set_clipping_range(3, 4); ``` clip direct diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md index efc65a4c700..ce470b99647 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. @@ -47,7 +58,7 @@ The 3 wires of the TRS/TRRS cable need to connect GND, VCC, and D0 (aka PDO or p The 4 wires of the TRRS cable need to connect GND, VCC, and SCL and SDA (aka PD0/pin 3 and PD1/pin 2, respectively) between the two Pro Micros. -The pull-up resistors may be placed on either half. It is also possible to use 4 resistors and have the pull-ups in both halves, but this is unnecessary in simple use cases. +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) @@ -79,6 +90,24 @@ 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 +``` + #### 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. @@ -198,10 +227,15 @@ This option changes the startup behavior to detect an active USB connection when ?> 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` + ## 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..148d61b0442 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 -## 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,37 @@ 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/) +* [Learn Plover!](https://sites.google.com/site/learnplover/) * [QWERTY Steno](http://qwertysteno.com/Home/) * [Steno Jig](https://joshuagrams.github.io/steno-jig/) * More resources at the Plover [Learning Stenography](https://github.com/openstenoproject/plover/wiki/Learning-Stenography) wiki -## 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`. 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 7427a77146b..877c37336ec 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: @@ -43,11 +36,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 +52,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 +63,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 +90,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 +199,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 +262,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) }; ``` @@ -333,90 +325,93 @@ And then simply use `TD(X_CTL)` anywhere in your keymap. If you want to implement this in your userspace, then you may want to check out how [DanielGGordon](https://github.com/qmk/qmk_firmware/tree/master/users/gordon) has implemented this in their userspace. -### Example 5: Using tap dance for advanced mod-tap and layer-tap keys +> 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 :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. @@ -424,97 +419,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..02a7bea5dab 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,155 @@ 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. * **`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 +268,5 @@ 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). diff --git a/docs/feature_userspace.md b/docs/feature_userspace.md index 1cc8ca7425c..77a6c8d7621 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,7 +178,7 @@ 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. @@ -208,23 +220,15 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { clear_mods(); clear_oneshot_mods(); SEND_STRING("make " QMK_KEYBOARD ":" QMK_KEYMAP); #ifndef FLASH_BOOTLOADER - if ( (temp_mod | temp_osm) & MOD_MASK_SHIFT ) + if ((temp_mod | temp_osm) & MOD_MASK_SHIFT) #endif - { // - #if defined(__arm__) // only run for ARM boards - SEND_STRING(":dfu-util"); - #elif defined(BOOTLOADER_DFU) // only run for DFU boards - SEND_STRING(":dfu"); - #elif defined(BOOTLOADER_HALFKAY) // only run for teensy boards - SEND_STRING(":teensy"); - #elif defined(BOOTLOADER_CATERINA) // only run for Pro Micros - SEND_STRING(":avrdude"); - #endif // bootloader options + { + SEND_STRING(":flash"); } - if ( (temp_mod | temp_osm) & MOD_MASK_CTRL) { - SEND_STRING(" -j8 --output-sync"); + if ((temp_mod | temp_osm) & MOD_MASK_CTRL) { + SEND_STRING(" -j8 --output-sync"); } - SEND_STRING(SS_TAP(X_ENTER)); + tap_code(KC_ENT); set_mods(temp_mod); } break; @@ -244,7 +248,7 @@ endif This will add a new `KC_MAKE` keycode that can be used in any of your keymaps. And this keycode will output `make :`, making frequent compiling easier. And this will work with any keyboard and any keymap as it will output the current boards info, so that you don't have to type this out every time. -Also, holding `shift` will add the appropriate flashing command (`:dfu`, `:teensy`, `:avrdude`, `:dfu-util`) for a majority of keyboards. Holding `control` will add some commands that will speed up compiling time by processing multiple files at once. +Also, holding Shift will add the flash target (`:flash`) to the command. Holding Control will add some commands that will speed up compiling time by processing multiple files at once. And for the boards that lack a shift key, or that you want to always attempt the flashing part, you can add `FLASH_BOOTLOADER = yes` to the `rules.mk` of that keymap. 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 18ae6364d42..1f71c253c3a 100644 --- a/docs/flashing.md +++ b/docs/flashing.md @@ -1,8 +1,8 @@ # 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 just about all of them use a different flashing method. Luckily, projects like the [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) aim to be compatible with all the different types without having to think about it much, but this article will describe the different types of bootloaders, and available methods for flashing them. -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`. +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). ## DFU @@ -26,7 +26,6 @@ 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) Flashing sequence: @@ -99,16 +98,21 @@ or make ::avrdude -or if you want to flash multiple boards, use the following command - make ::avrdude-loop +### Caterina commands + +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._ -When you're done flashing boards, you'll need to hit Ctrl + C or whatever the correct keystroke is for your operating system to break the loop. ## Halfkay -Halfkay is a super-slim protocol developed by PJRC that uses HID, and come on all Teensys (namely the 2.0). +Halfkay is a super-slim protocol developed by PJRC that uses HID, and comes on all Teensys (namely the 2.0). To ensure compatibility with the Halfkay bootloader, make sure this block is present your `rules.mk`: @@ -231,7 +235,7 @@ Flashing sequence: There are a number of DFU commands that you can use to flash firmware to a STM32 device: -* `:dfu-util` - The default command for flashing to STM32 devices. +* `: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. diff --git a/docs/flashing_bootloadhid.md b/docs/flashing_bootloadhid.md index c51d8ce4b8f..731d9277273 100644 --- a/docs/flashing_bootloadhid.md +++ b/docs/flashing_bootloadhid.md @@ -13,7 +13,7 @@ General flashing sequence: ## bootloadHID Flashing Target -Using the QMK installation script, detailed [here](newbs_getting_started.md), the required bootloadHID tools should be automatically installed. +?> Using the QMK installation script, detailed [here](newbs_getting_started.md), the required bootloadHID tools should be automatically installed. To flash via the command line, use the target `:bootloadHID` by executing the following command: diff --git a/docs/fr-FR/README.md b/docs/fr-FR/README.md deleted file mode 100644 index 5bbe353b48c..00000000000 --- a/docs/fr-FR/README.md +++ /dev/null @@ -1,32 +0,0 @@ -# Quantum Mechanical Keyboard Firmware - -[![Version courante](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags) -[![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/) - -## 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é. - -## 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. - -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`). - -## Comment le compiler - -Avant d'être prêt à compiler vous allez devoir [installer un environnement](getting_started_build_tools.md) pour les développements AVR et/ou ARM. Une fois ceci fait, vous pourrez utiliser la commande `make` pour compiler le clavier et la disposition avec une commande de ce type : - - make planck/rev4:default - -Cette commande compilera la révision `rev4` du clavier `planck` avec la disposition `default`. Notez que tous les claviers n'ont pas forcément de révisions (aussi appelées sous-projects ou dossiers, ou en en Anglais « subprojects » ou « folder »). Cette option peut donc être omise : - - make preonic:default - -## Comment le personnaliser - -QMK a beaucoup de [fonctionnalités](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](keymap.md) (keymaps) et de changer [les codes de caractères](keycodes.md) (keycodes). diff --git a/docs/fr-FR/_summary.md b/docs/fr-FR/_summary.md deleted file mode 100644 index 16ae82d0632..00000000000 --- a/docs/fr-FR/_summary.md +++ /dev/null @@ -1,125 +0,0 @@ -**En Français** - -* [Guide pour débutant complet](fr-FR/newbs.md) - * [Pour débuter](fr-FR/newbs_getting_started.md) - * [Compiler son premier firmware](fr-FR/newbs_building_firmware.md) - * [Flasher le Firmware](fr-FR/newbs_flashing.md) - * [Test et Débuggage](fr-FR/newbs_testing_debugging.md) - * [Bonnes pratiques Git](fr-FR/newbs_best_practices.md) - * [Ressources d'apprentissage](fr-FR/newbs_learn_more_resources.md) - -* [Les bases de QMK](fr-FR/README.md) - * [Indroduction à QMK](fr-FR/getting_started_introduction.md) - * [QMK CLI](fr-FR/cli.md) - * [Configuration de la CLI QMK](fr-FR/cli_configuration.md) - * [Contribuer à QMK](fr-FR/contributing.md) - * [Comment utiliser GitHub](fr-FR/getting_started_github.md) - * [Trouver de l'aide](fr-FR/getting_started_getting_help.md) - -* [Breaking changes](fr-FR/breaking_changes.md) - * [30 août 2019](fr-FR/ChangeLog/20190830.md) - -**En Anglais** - -* [FAQ](faq.md) - * [FAQ Générale](faq_general.md) - * [Compiler QMK](faq_build.md) - * [Débugguer / Dépanner QMK](faq_debug.md) - * [Keymap / Disposition](faq_keymap.md) - * [Installer les drivers avec Zadig](driver_installation_zadig.md) - -* Guides détaillés - * [Installation des outils de compilation](getting_started_build_tools.md) - * [Guide Vagrant](getting_started_vagrant.md) - * [Commandes de compilations](getting_started_make_guide.md) - * [Flasher les firmwares](fr-fr/flashing.md) - * [Personnaliser les fonctionnalités](custom_quantum_functions.md) - * [Aperçu des fonctionnalités des dispositions](keymap.md) - -* [Hardware](hardware.md) - * [Processeurs AVR](hardware_avr.md) - * [Pilotes / Drivers](hardware_drivers.md) - -* Réferences - * [Lignes de conduite des claviers](hardware_keyboard_guidelines.md) - * [Options de configurations](config_options.md) - * [Keycodes / Codes des caractères](keycodes.md) - * [Conventions de codage - C](coding_conventions_c.md) - * [Conventions de codage - Python](coding_conventions_python.md) - * [Meilleurs pratiques sur la documentation](documentation_best_practices.md) - * [Modèles de documentation](documentation_templates.md) - * [Glossaire](reference_glossary.md) - * [Tests unitaires](unit_testing.md) - * [Fonctions utiles](ref_functions.md) - * [Support de configuration](reference_configurator_support.md) - * [Format du fichier info.json](reference_info_json.md) - * [Développer la CLI en Python](cli_development.md) - -* [Fonctionnalités](features.md) - * [Keycodes basiques](keycodes_basic.md) - * [Touches utilisées avec Shift (US ANSI)](keycodes_us_ansi_shifted.md) - * [Keycodes quantiques](quantum_keycodes.md) - * [Keycodes avancés](feature_advanced_keycodes.md) - * [Fonctionnalités audio](feature_audio.md) - * [Majuscule automatique](feature_auto_shift.md) - * [Rétroéclairage](feature_backlight.md) - * [Bluetooth](feature_bluetooth.md) - * [Bootmagic](feature_bootmagic.md) - * [Combos](feature_combo.md) - * [Commande](feature_command.md) - * [API anti-rebond](feature_debounce_type.md) - * [DIP Switch](feature_dip_switch.md) - * [Macros dynamiques](feature_dynamic_macros.md) - * [Interrupteurs rotatifs](feature_encoders.md) - * [Grave Escape](feature_grave_esc.md) - * [Retour haptique](feature_haptic_feedback.md) - * [Contrôleur LCD HD44780](feature_hd44780.md) - * [Touche à verrou / Lock-key](feature_key_lock.md) - * [Dispositions / layouts](feature_layouts.md) - * [Touche leader](feature_leader_key.md) - * [Matrice LED](feature_led_matrix.md) - * [Macros](feature_macros.md) - * [Boutons de souris](feature_mouse_keys.md) - * [Pilotes / Drivers OLED](feature_oled_driver.md) - * [Touche one-shot](feature_advanced_keycodes.md#one-shot-keys) - * [Périphériques de pointage](feature_pointing_device.md) - * [Souris PS/2](feature_ps2_mouse.md) - * [Éclairage RGB](feature_rgblight.md) - * [Matrice RGB](feature_rgb_matrix.md) - * [Space Cadet](feature_space_cadet.md) - * [Claviers scindés / splittés](feature_split_keyboard.md) - * [Stenographie](feature_stenography.md) - * [Inversion des mains](feature_swap_hands.md) - * [Tap Dance](feature_tap_dance.md) - * [Terminale](feature_terminal.md) - * [Imprimante thermique](feature_thermal_printer.md) - * [Caractères unicodes](feature_unicode.md) - * [Dossier utilisateur](feature_userspace.md) - * [Velocikey](feature_velocikey.md) - -* Pour les makers et les bricoleurs - * [Guide des claviers soudés à la main](hand_wire.md) - * [Guide de flash de l’ISP](isp_flashing_guide.md) - * [Guide du débogage ARM](arm_debugging.md) - * [Drivers i2c](i2c_driver.md) - * [Contrôles des GPIO](internals_gpio_control.md) - * [Conversion en Proton C](proton_c_conversion.md) - -* Pour aller plus loin - * [Comment fonctionnent les claviers](how_keyboards_work.md) - * [Comprendre QMK](understanding_qmk.md) - -* Autres sujets - * [Utiliser Eclipse avec QMK](other_eclipse.md) - * [Utiliser VSCode avec QMK](other_vscode.md) - * [Support](support.md) - * [Comment ajouter des traductions](translating.md) - -* À l’intérieur de QMK (En cours de documentation) - * [Définitions](internals_defines.md) - * [Input Callback Reg](internals_input_callback_reg.md) - * [Appareils Midi](internals_midi_device.md) - * [Installation d’un appareil Midi](internals_midi_device_setup_process.md) - * [Utilitaires Midi](internals_midi_util.md) - * [Fonctions Midi](internals_send_functions.md) - * [Outils Sysex](internals_sysex_tools.md) diff --git a/docs/fr-FR/breaking_changes.md b/docs/fr-FR/breaking_changes.md deleted file mode 100644 index 6913dbd3f11..00000000000 --- a/docs/fr-FR/breaking_changes.md +++ /dev/null @@ -1,107 +0,0 @@ -# Breaking changes - -Ce document décrit le processus de QMK pour la gestion des breaking changes. Un breaking change est un changement qui modifie la manière dont QMK fonctionne introduisant des incompatibilités ou des comportements dangereux. Nous limitons ces changements afin que les utilisateurs n'aient pas peur de casser leurs keymaps en mettant à jour leur version de QMK. - -La période de breaking change est quand nous allons fusionner un PR qui change QMK d'une manière dangereuse ou inattendue. Il y a une période interne de test afin de nous assurer que les problèmes résiduels sont rares ou impossible à prévoir. - -## Qu'est-ce qui a été inclus dans des Breaking Changes précédents? - -* [30 août 2019](ChangeLog/20190830.md) - -## Quand va être le prochain Breaking Change? - -Le prochain Breaking Change est planifié pour le 29 novembre. - -### Dates importantes - -* [x] 21 septembre 2019 - `future` est créé. Il va être rebasé de manière hebdomadaire. -* [ ] 01 novembre 2019 - `future` fermé aux nouveaux PRs. -* [ ] 01 novembre 2019 - Appel aux testeurs. -* [ ] 27 novembre 2019 - `master` est bloqué, pas de PRs fusionnés. -* [ ] 29 novembre 2019 - `future` est fusionné dans `master`. -* [ ] 30 novembre 2019 - `master` est débloqué. Les PRs peuvent à nouveau être fusionnés. - -## Quels changements seront inclus? - -Pour voir une liste de candidats de breaking changes, vous pouvez regardez la liste des [labels `breaking_change`](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr). De nouveaux changements peuvent être ajoutés entre maintenant et lorsque `future` est fermée, et un PR avec ce label n'est pas garanti d'être fusionné. - -Si vous souhaitez que votre breaking change soit inclus dans ce tour, vous devez créer un PR avec le label `breaking_change` et faire en sorte qu'il soit accepté avant que `future` ne soit fermé. Une fois `future` fermé, aucun nouveau breaking change sera accepté. - -Critère d'acceptation: - -* Le PR est complété et prêt à fusionner -* Le PR a un ChangeLog - -# Checklists - -Cette section documente plusieurs processus que nous utilisons en lançant le processus de Breaking Change. - -## Rebase `future` de `master` - -Ceci est lancé chaque vendredi tant que `future` est ouvert. - -Processus: - -``` -cd qmk_firmware -git checkout master -git pull --ff-only -git checkout future -git rebase master -git push --force -``` - -## Créer la branche `future` - -Ceci est fait immédiatement après la fusion de la branche `future` précédente. - -* `qmk_firmware` git commands - * [ ] `git checkout master` - * [ ] `git pull --ff-only` - * [ ] `git checkout -b future` - * [ ] Modifie `readme.md` - * [ ] Ajoute un message en haut qui indique que c'est une branche de test. - * [ ] Ajoute un lien vers ce document - * [ ] `git commit -m 'Branch point for Breaking Change'` - * [ ] `git tag breakpoint___
` - * [ ] `git tag ` # Evite que le label point d'arrêt soit confondu par un incrément de version - * [ ] `git push origin future` - * [ ] `git push --tags` - -## 4 Semaines Avant la Fusion - -* `future` est maintenant fermé aux nouveaux PRs, seul des correctifs pour les PRs courants peuvent être mergés -* Envoi de l'appel aux testeurs - * [ ] Discord - * [ ] GitHub PR - * [ ] https://reddit.com/r/olkb - -## 1 Semaine Avant la Fusion - -* Annonce que master sera fermée entre <2 jours avant> à - * [ ] Discord - * [ ] GitHub PR - * [ ] https://reddit.com/r/olkb - -## 2 Jours Avant la Fusion - -* Annonce que master est fermé pour 2 jours - * [ ] Discord - * [ ] GitHub PR - * [ ] https://reddit.com/r/olkb - -## Jour de la fusion - -* `qmk_firmware` git commands - * [ ] `git checkout future` - * [ ] `git pull --ff-only` - * [ ] `git rebase origin/master` - * [ ] Modifie `readme.md` - * [ ] Supprimer les notes à propos de `future` - * [ ] Regroupe ChangeLog dans un fichier. - * [ ] `git commit -m 'Merge point for Breaking Change'` - * [ ] `git push origin future` -* 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/cli.md b/docs/fr-FR/cli.md deleted file mode 100644 index 176ee90da45..00000000000 --- a/docs/fr-FR/cli.md +++ /dev/null @@ -1,146 +0,0 @@ -# La CLI de QMK - -Cette page décrit comment configurer et utiliser la CLI QMK. - -# Vue d'ensemble - -La CLI de QMK permet de simplifier la compilation et l'intéraction avec les clavier QMK. Nous avons définis plusieurs commandes pour simplifier et rationaliser les tâches telles qu'obtenir et compiler le firmware QMK, créer de nouvelles keymaps, et plus. - -* [CLI globale](#global-cli) -* [CLI locale](#local-cli) -* [Les commandes CLI](#cli-commands) - -# Pré-requis - -La CLI nécessite Python 3.5 ou plus récent. Nous essayons de limiter le nombre de pré-requis, mais vous allez aussi devoir installer les paquets listés dans le fichier [`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt). - -# CLI globale - -QMK met à disposition une CLI installable qui peut être utilisée pour configurer votre environnement de compilation QMK, fonctionne avec QMK, et qui rend l'utilisation de plusieurs copies de `qmk_firmware` plus simple. Nous recommandons d'installer et de mettre à jour ceci régulièrement. - -## Installer en utilisant Homebrew (macOS, quelques Linux) - -Si vous avez installé [Homebrew](https://brew.sh) vous pouvez entrer ce qui suit et installer QMK: - -``` -brew tap qmk/qmk -brew 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 -``` - -## Installer en utilisant easy_install ou pip - -Si votre système n'est pas listé ci-dessus, vous pouvez installer QMK manuellement. Premièrement, vérifiez que vous avez bien installé Python 3.5 (ou plus récent) et pip. Ensuite, installez QMK avec cette commande: - -``` -pip3 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 -``` - -## Paquets pour d'autres systèmes d'exploitation - -Nous recherchons des gens pour créer et maintenir un paquet `qmk` pour plus de systèmes d'exploitation. Si vous voulez créer un paquet pour votre système d'exploitation, suivez ces directives: - -* Suivez les bonnes pratiques pour votre système d'exploitation lorsqu'elles entrent en conflit avec ces directives - * Documentez pourquoi dans un commentaire lorsque vous ne les suivez pas -* Installez en utilisant un virtualenv -* Expliquez à l'utilisateur de définir la variable d'environnement `QMK_Home` pour "check out" les sources du firmware à un autre endroit que `~/qmk_firmware`. - -# CLI locale - -Si vous ne voulez pas utiliser la CLI globale, il y a une CLI locale empaquetée avec `qmk_firmware`. Vous pouvez le trouver dans `qmk_firmware/bin/qmk`. Vous pouvez lancer la commande `qmk` depuis n'importe quel répertoire et elle fonctionnera toujours sur cette copie de `qmk_firmware`. - -**Exemple**: - -``` -$ ~/qmk_firmware/bin/qmk hello -Ψ Hello, World! -``` - -## Limitations de la CLI locale - -Il y a quelques limitations à la CLI locale comparé à la globale: - -* La CLI locale ne supporte pas `qmk setup` ou `qmk clone` -* La CLI locale n'opère pas sur le même arbre `qmk_firmware`, même si vous avez plusieurs dépôts clonés. -* La CLI locale ne s'exécute pas dans un virtualenv, donc il y a des risques que des dépendances seront en conflit - -# Les commandes CLI - -## `qmk compile` - -Cette commande permet de compiler le firmware de n'importe quel répertoire. Vous pouvez compiler des exports JSON de ou compiler des keymaps du dépôt. - -**Utilisation pour les exports de configuration**: - -``` -qmk compile -``` - -**Utilisation pour les Keymaps**: - -``` -qmk compile -kb -km -``` - -## `qmk cformat` - -Cette commande formatte le code C en utilisant clang-format. Lancez-la sans arguments pour formatter tout le code core, ou passez les noms de fichiers à la ligne de commande pour la lancer sur des fichiers spécifiques. - -**Utilisation**: - -``` -qmk cformat [file1] [file2] [...] [fileN] -``` - -## `qmk config` - -Cette commande vous permet de configurer le comportement de QMK. Pour la documentation complète de `qmk config`, regardez [Configuration de CLI](cli_configuration.md). - -**Utilisation**: - -``` -qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN] -``` - -## `qmk doctor` - -Cette commande examine votre environnement et vous alertes des potentiels problèmes de compilation ou de flash. - -**Utilisation**: - -``` -qmk doctor -``` - -## `qmk new-keymap` - -Cette commande crée une nouvelle keymap basée sur une keymap par défaut d'un clavier existant. - -**Utilisation**: - -``` -qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] -``` - -## `qmk pyformat` - -Cette commande formatte le code python dans `qmk_firmware`. - -**Utilisation**: - -``` -qmk pyformat -``` - -## `qmk pytest` - -Cette commande démarre la suite de test python. Si vous faites des changements dans le code Python, assurez vous que les tests se lancent avec succès. - -**Utilisation**: - -``` -qmk pytest -``` diff --git a/docs/fr-FR/cli_configuration.md b/docs/fr-FR/cli_configuration.md deleted file mode 100644 index dcd197f8521..00000000000 --- a/docs/fr-FR/cli_configuration.md +++ /dev/null @@ -1,121 +0,0 @@ -# Configuration de QMK CLI - -Ce document explique comment fonctionne la commande `qmk config`. - -# Introduction - -La configuration pour QMK CLI est un système clé/valeur. Chaque clé est composée d'une sous-commande et d'un argument séparé par une virgule. Cela permet une traduction simple et directe entre les clés de configuration et l'argument qu'elle définit. - -## Exemple simple - -Comme exemple, regardons la commande `qmk compile --keyboard clueboard/66/rev4 --keymap default`. - -Il y a deux arguments de ligne de commande qui peuvent être lu de la configuration: - -* `compile.keyboard` -* `compile.keymap` - -Essayons de les définir: - -```shell -$ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default -compile.keyboard: None -> clueboard/66/rev4 -compile.keymap: None -> default -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -Maintenant, je peux lancer la commande `qmk compile` sans avoir à spécifier mon clavier et keymap à chaque fois. - -## Définir les options par défaut - -Parfois, il est utile de partager une configuration entre plusieurs commandes. Par exemple, plusieurs commandes prennent un argument `--keyboard`. Plutôt que de devoir définir cette valeur pour chaque commande, vous pouvez définir une valeur d'utilisateur qui sera utilisée par toutes les commandes qui prennent cet argument. - -Exemple: - -``` -$ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default -user.keyboard: None -> clueboard/66/rev4 -user.keymap: None -> default -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -# CLI Documentation (`qmk config`) - -La commande `qmk config` est utilisée pour intéragir avec la configuration sous-jacente. Lancée sans argument, elle affiche la configuration courante. Lorsque des arguments sont définis, ils sont considérés comme étant des jetons de configuration, qui sont des chaînes de caractère ne contenant aucun espace avec le format suivant: - - [.][=] - -## Définir des valeurs de configuration - -Vous pouvez définir des valeurs de configuration en mettant le caractère égal (=) dans votre clé de configuration. La clé doit toujours être dans le format complet `
.`. - -Exemple: - -``` -$ qmk config default.keymap=default -default.keymap: None -> default -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -## Lire des valeurs de configuration - -Vous pouvez lire les valeurs de configuration pour la totalité de la configuration, une seule clé, ou une section entière. Vous pouvez aussi spécifier plusieurs clés pour afficher plus d'une valeur. - -### Exemple avec la totalité de la configuration - - qmk config - -### Exemple avec une section entière - - qmk config compile - -### Exemple avec une clé unique - - qmk config compile.keyboard - -### Exemple avec plusieurs clés - - qmk config user compile.keyboard compile.keymap - -## Supprimer des valeurs de configuration - -Vous pouvez supprimer une valeur de configuration en la définissant avec la chaîne spéciale `None`. - -Exemple: - -``` -$ qmk config default.keymap=None -default.keymap: default -> None -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -## Plusieurs opérations - -Vous pouvez combiner plusieures opérations d'écriture et de lecture en une seule commande. Elle seront exécutées et affichées dans l'ordre: - -``` -$ qmk config compile default.keymap=default compile.keymap=None -compile.keymap=skully -compile.keyboard=clueboard/66_hotswap/gen1 -default.keymap: None -> default -compile.keymap: skully -> None -Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' -``` - -# Options de configuration utilisateur - -| Clé | Valeur par défaut | Description | -|-----|---------------|-------------| -| user.keyboard | None | Le chemin d'accès vers le clavier (Exemple: `clueboard/66/rev4`) | -| user.keymap | None | Le nom de la keymap (Exemple: `default`) | -| user.name | None | Le nom d'utilisateur GitHub de l'utilisateur. | - -# Toutes les options de configuration - -| Clé | Valeur par défaut | Description | -|-----|---------------|-------------| -| compile.keyboard | None | Le chemin d'accès vers le clavier (Exemple: `clueboard/66/rev4`) | -| compile.keymap | None | Le nom de la keymap (Exemple: `default`) | -| hello.name | None | Le nom à saluer lorsque démarré. | -| new_keyboard.keyboard | None | Le chemin d'accès vers le clavier (Exemple: `clueboard/66/rev4`) | -| new_keyboard.keymap | None | Le nom de la keymap (Example: `default`) | diff --git a/docs/fr-FR/contributing.md b/docs/fr-FR/contributing.md deleted file mode 100644 index 6d6889b018b..00000000000 --- a/docs/fr-FR/contributing.md +++ /dev/null @@ -1,154 +0,0 @@ -# Comment contribuer - -👍🎉 Premièrement, merci de prendre le temps de lire ceci et de contribuer! 🎉👍 - -Les contributions de tiers nous aide à améliorer et faire grandir QMK. Nous voulons rendre les pull requests et le processus de contribution utile et simple à la fois pour les contributeurs et les mainteneurs. C'est pourquoi nous avons mis en places des directives pour les contibuteurs afin que votre pull request puisse être accepté sans changement majeur. - -* [Aperçu du projet](#project-overview) -* [Conventions de codage](#coding-conventions) -* [Directives générales](#general-guidelines) -* [Que veut dire le code de conduite pour moi?](#what-does-the-code-of-conduct-mean-for-me) - -## Je ne veux pas lire tout ce pavé! J'ai juste une question! - -Si vous voulez poser une question sur QMK, vous pouvez le faire sur le [sous-reddit OLKB](https://reddit.com/r/olkb) ou sur [Discord](https://discord.gg/Uq7gcHh). - -Merci de garder ceci en tête: - -* Cela peut prendre plusieurs heures pour que quelqu'un réponde à votre question. Merci d'être patient! -* Tous ceux impliqués avec QMK fait don de son temps et de son énergie. Nous ne sommes pas payés pour travailler sur ou répondre aux questions concernant QMK. -* Essayez de poser vos questions de manière à ce qu'elles soient le plus simple à répondre possible. Si vous n'êtes pas sûrs de savoir comment faire, voici quelques bon guides (en anglais): - * https://opensource.com/life/16/10/how-ask-technical-questions - * http://www.catb.org/esr/faqs/smart-questions.html - -# 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. - - - -# Où trouver de l'aide? - -Si vous avez besoin d'aide, vous pouvez [ouvrir une issue](https://github.com/qmk/qmk_firmware/issues) ou [un chat sur Discord](https://discord.gg/Uq7gcHh). - -# Comment contribuer? - -Vous n'avez encore jamais contribué à un projet open source? Vous vous demandez comment les contributions dans QMK fonctionnent? Voici un aperçu rapide! - -0. Enregistrez-vous sur [GitHub](https://github.com). -1. Définissez une keymap à contribuer, [trouvez une issue](https://github.com/qmk/qmk_firmware/issues) que vous souhaitez corriger, ou [une fonction](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature) que vous voulez ajouter. -2. Créez un fork sur le dépôt associé avec une issue sur votre compte GitHub. Cela veut dire que vous allez avoir une copie du dépôt sous `votre-login-GitHub/qmk_firmware`. -3. Clonez le dépôt sur votre macine locale en utilisant `git clone https://github.com/login-github/repository-name.git`. -4. Si vous travaillez sur une nouvelle fonctionnalité, pensez à ouvrir une issue pour parler avec nous du travail que vous souhaitez démarrer. -5. Créez une nouvelle branche pour votre correctif en utilisant `git checkout -b nom-de-branche`. -6. Faites les changements nécessaires pour corriger le problème ou ajouter la fonctionnalité. -7. Utilisez `git add chemin-de-fichier` pour ajouter les contenus des fichiers modifiés au "snapshot" que git utilise pour gérer l'état du projet, appelé aussi l'index. -8. Utilisez `git commit -m "Insérez une description courte des changements (en anglais)"` pour enregistrer le contenu de l'index avec un message descriptif. -9. Poussez les changements vers votre dépôt sur GitHub en utilisant `git push origin nom-de-branche`. -10. Créez un pull request sur [QMK Firmware](https://github.com/qmk/qmk_firmware/pull/new/master). -11. Donnez un titre à votre pull request en utilisant une description courte des changements que vous avez fait et ajoutez le numéro de l'issue ou du bug associé avec votre changement. Les commentaires de PR devraient se faire en anglais de préférence. Par exemple, vous pouvez utiliser un titre tel que celui-là: "Added more log outputting to resolve #4352". -12. Dans la description du pull request, expliquez les changements que vous avez fait et tous les problèmes qui existent, selon vous, sur le pull request que vous avez fait. Vous pouvez aussi utiliser la description pour poser des questions au mainteneur. Il n'est pas nécessaire que votre pull request soit parfait (aucun pull request ne l'est), le reviewer sera là pour vous aider à résoudre les problèmes et l'améliorer! -13. Attendez que le pull request soit revu par un mainteneur. -14. Faites des changements au pull request si le mainteneur le recommande. -15. Célébrez votre succès une fois votre pull request fusionné! - -# Conventions de codage - -La grande majorité de notre style est plutôt simple à comprendre. Si vous connaissez C ou Python, vous ne devriez pas avoir trop de difficulté avec notre style. - -* [Conventions de codage - C](coding_conventions_c.md) -* [Conventions de codage - Python](coding_conventions_python.md) - -# Directives générales - -Nous avons un certain nombre de type de changements dans QMK, chacun nécessitant un niveau de rigueur différent. Nous voulons que vous gardiez les directives suivantes en tête quel que soit le changement que vous êtes en train de faire. - -* Séparez les PR dans des unités logiques. Par exemple, ne soumettez pas un PR qui couvre deux fonctionnalités séparées, soumettez plutôt un PR pour chaque fonctionnalité. -* Vérifiez les espaces blancs non nécessaires avec `git diff --check` avant de commit. -* Assurez-vous que votre code compile. - * Keymaps: Assurez-vous que `make keyboard:your_new_keymap` ne renvoie pas d'erreur. - * Claviers: Assurez-vous que `make keyboard:all` ne renvoie pas d'erreur. - * Core: Assurez-vous que `make all` ne renvoie pas d'erreur. -* Assurez-vous que les messages de commit soient compréhensibles d'eux-même. Vous devriez écrire une description simple (pas plus de 70 caractères) sur la première ligne, suivi d'une ligne vide, suivi d'un détail de votre commit, si nécessaire. Exemple: - -``` -Adjust the fronzlebop for the kerpleplork - -The kerpleplork was intermittently failing with error code 23. The root cause was the fronzlebop setting, which causes the kerpleplork to activate every N iterations. - -Limited experimentation on the devices I have available shows that 7 is high enough to avoid confusing the kerpleplork, but I'd like to get some feedback from people with ARM devices to be sure. -``` - -## Documentation - -La documentation est l'une des manière 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/. - -Lorsque vous donnez des exemples de code dans la documentation, essayez de suivre les conventions de nommage utilisées ailleurs dnas la documentation. Par exemple, standardisez les enums en utilisant `my_layers` ou `my_keycodes` afin de garder une consistance: - -```c -enum my_layers { - _FIRST_LAYER, - _SECOND_LAYER -}; - -enum my_keycodes { - FIRST_LAYER = SAFE_RANGE, - SECOND_LAYER -}; -``` - -## Keymaps - -La plupart des contributeurs débutants démarrent avec leurs keymaps personnelles. Nous essayons de garder les standards pour les keymaps pluôt simple (les keymaps reflètent, après tout, la personnalité de leurs créateurs) mais nous demandons que vous suiviez les directives suivantes afin que d'autres puissent découvrir et apprendre de votre keymap. - -* Ecrivez un fichier `readme.md` en utilisant [la template](documentation_templates.md). -* Tous les PR de keymaps doivent être "squashés", donc si la manière dont vos commits sont squashés vous est important, vous devez le faire vous-même. -* Ne regroupez pas des fonctionnalités avec votre PR de keymap. Envoyez d'abord votre fonctionnalité, puis créez un second PR pour la keymap. -* N'incluez pas de fichier `Makefile` dans votre dossier de keymap (ils ne sont plus utilisés) -* Mettez à jour les copyrights dans les en-têtes de fichiers (cherchez `%YOUR_NAME%`) - -## Claviers - -Les claviers sont la raison d'être de QMK. Certains claviers sont maintenus par la communauté, alors que d'autre sont maintenus par les gens responsables de la création du clavier. Le fichier `readme.md` devrait vous informer de qui maintient le clavier. Si vous avez des questions concernant un clavier en particulier, vous pouvez [Ouvrir une issue](https://github.com/qmk/qmk_firmware/issues) et tagger le mainteneur dans votre question. - -Nous vous demandons aussi que vous suiviez ces directives: - -* Ecrivez un fichier `readme.md` en utilisant [le template](documentation_templates.md). -* Gardez un nombre de commits raisonnable, ou nous squasherons votre PR. -* Ne regroupez pas des fonctionnalités avec le PR pour votre clavier. Envoyez d'abord votre fonctionnalité, puis créez un second PR pour le clavier. -* Appelez les fichiers `.c`/`.h` du nom du dossier parent, par exemple `/keyboards///.[ch]` -* N'incluez pas de fichier `Makefile` dans votre dossier de keymap (ils ne sont plus utilisés) -* Mettez à jour les copyrights dans les en-têtes de fichiers (cherchez `%YOUR_NAME%`) - -## Quantum/TMK Core - -Faites attention d'être sûr d'implémenter votre nouvelle fonctionnalité de la meilleure manière qu'il soit avant d'investir beaucoup de travail à son développement. Vous pouvez apprendre les bases de QMK en lisant [Comprendre QMK](understanding_qmk.md), qui vous donnera une idée du flux du programme QMK. A partir de là, parlez nous afin de définir la meilleure façon d'implémenter votre idée. Il y a deux façons principale de le faire: - -* [Chat sur Discord](https://discord.gg/Uq7gcHh) -* [Ouvrir une Issue](https://github.com/qmk/qmk_firmware/issues/new) - -Les PR de nouvelles fonctionnalités de de correction de bug affectent tous les claviers. Nous sommes aussi dans un processus de restructuration de QMK. Pour cette raison, il est absolument nécessaire que tout changement important ou significatif soit discuté avant que l'implémentation soit faite. Si vous ouvrez un PR sans nous avoir parlé, préparez vous à faire des refontes significatives si vous changements ne sont pas compatibles avec ce que nous avons planifié. - -Voici quelques choses à garder en tête lorsque vous travaillez sur une fonctionnalité ou un bug fix. - -* **Désactivé par défaut** - la mémoire est plutôt limitée sur la plupart des puces que QMK supporte, et il est important que les keymaps courantes ne soient pas cassées. S'il vous plaît faites que vos features doivent être **activées** plutôt que désactivées. Si vous pensez qu'elle devrait être activée par défaut, ou que cela réduit la taille du code, parlez-nous en. -* **Compilez localement avant de soumettre** - Cela devrait aller sans dire, mais votre code doit compiler! Notre système Travis devrait relever les problèmes, mais il est généralement plus rapide de compiler quelques claviers en local plutôt que d'attendre le retour des résultats -* **Faites attention aux révisions et différentes bases de puces** - beaucoup de claviers ont des révisions qui permettent des changements de configuration mineurs, voir des bases de chip différentes. Essayez de faire que votre fonctionnalité soit supportée à la fois sur ARM et AVR, ou désactivez-là automatiquement sur les plateformes non supportées. -* **Expliquez votre fonctionnalité** - Documentez-là dans `docs/`, soit dans un nouveau fichier, ou dans une partie d'un fichier existant. Si vous ne la documentez pas, personne ne pourra bénéficier de votre dur labeur. - -Nous vous demandons aussi de suivre ces ces directives: - -* Gardez un nombre de commits raisonnable, ou nous squasherons votre PR. -* Ne regroupez pas des claviers ou des keymaps avec des changements core. Soumettez vos changements core en premier. -* Ecrivez des [Tests Unitaires](unit_testing.md) pour votre fonctionnalité. -* Suivez le style du fichier que vous modifiez. Si le style n'est pas clair ou qu'il y a un mélange de fichiers, vous devriez vous conformer aux [conventions de codage](#coding-conventions) au dessus. - -## Refactoriser - -Afin de maintenir une vision claire sur comment les choses sont architectuées dans QMK, nous essayons de planifier des refactorisations en profondeur et qu'un collaborateur fasse le changement. Si vous avez une idée de refactorisation, ou une suggestion, [ouvrez une issue] [open an issue](https://github.com/qmk/qmk_firmware/issues), nous adorons discuter de comment améliorer QMK. - -# Que veut dire le code de conduite pour moi? - -Note [Code De Conduite](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md) veut dire que vous avez la responsabilité de traiter tout le monde dans le projet avec respect et courtoisie, peut importe leur identité. Si vous êtes victime d'une attitude ou de commentaires inapropriés, tels que décrit dans notre Code de Conduite, nous sommes là pour vous et nous ferons de notre mieux pour nous assurer que le fautif soit réprimandé, tel que décrit dans notre code. diff --git a/docs/fr-FR/flashing.md b/docs/fr-FR/flashing.md deleted file mode 100644 index f4379189a71..00000000000 --- a/docs/fr-FR/flashing.md +++ /dev/null @@ -1,236 +0,0 @@ -# Instructions pour flasher et informations sur les bootloader - -Les claviers utilisent différents types de bootloaders et certains doivent être flashés différement. Heureusement, certains projets comme la [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) ont pour objectifs de permettre de flasher les différents bootloader sans trop se faire de soucis et ça peut importe les manières de les flasher. - -Si vous avez un bootloader sélectionné avec la variable `BOOTLOADER` dans votre fichier `rules.mk` alors QMK vas automatiquement calculer si votre fichier .hex n'est pas trop grand pour être flashé sur votre appareil, et il affichera la taille finale du firmware. Pour vérifier la taille manuellement, vous pouvez aussi compiler le firmware avec l'option `check-size`. Exemple : `make planck/rev4:default:check-size`. - -## DFU - -Le bootloader pour les processeurs Atmel DFU est fourni par défaut sur tous les processeurs atmega32u4. Celui-ci est utilisé par beaucoup de claviers plus vieux que les OLKB et Clueboard qui ont leur propre ICs sur leurs PCBs. D'autres claviers utilisent le bootloader DFU de LUFA (ou son fork QMK), notamment les nouveaux claviers OLKB. Ce dernier ajoute des fonctionnalités spécifiques sur le matériel. - -Pour vérifier la compatibilité avec le bootloader DFU, vérifiez que ce bloc de code est présent dans votre fichier `rules.mk`. Parfois il peut être inscrit `lufa-dfu` ou `qmk-dfu` à la place. - -```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 -``` - -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 : - -1. Pressez le keycode `RESET`, ou appuyez sur le bouton physique RESET ou alors créez un contact entre RST et GND. -2. Attendez que l'OS detecte l'appareil. -3. Éffacez la mémoire, cela peut être fait automatiquement. -4. Flasher le fichier .hex. -5. Redémarrez l'appareil en mode « application », cela peut être fait automatiquement. - -Alternativement : - - make ::dfu - -### DFU QMK - -QMK a un fork du bootloader LUFA DFU qui vous permet de faire un simple scan de la matrice pour quitter le bootloader et retourner à l'application. En même temps que le flash se produira, il est possible de faire flasher un led ou de produire un son via un haut parleur. Pour activer ces fonctionnalités, vous pouvez utiliser ce bloc dans votre fichier `config.h` (La touche permettant de quitter le bootloader a besoin d'être reliée entre les ports définis en INPUT et OUTPUT ici): - - #define QMK_ESC_OUTPUT F1 // usually COL - #define QMK_ESC_INPUT D5 // usually ROW - #define QMK_LED E6 - #define QMK_SPEAKER C6 - -Le fabriquant et le nom du produit proviennent de vos définitions dans fichier `config.h`, et la chaîne de caractère « bootloader » est ajoutée au nom du prodruit. - -Pour génerer le bootloader, utilisez la cible `bootloader`. Exemple : `make planck/rev4:default:bootloader`. - -Pour génerer un fichier .hex prêt pour la production qui contiendra tant l'application que le bootloader, utilisez la cible `production`. Exemple : `make planck/rev4:default:production`. - -### Commandes DFU - -Il y a plusieurs commandes DFU que vous pouvez utiliser pour flasher le firmware sur un appareil DFU. - -* `:dfu` - C'est l'option normale qui attend qu'un appareil DFU soit disponible et qui flashe le firmware dès que c'est le cas. La vérification sera faite toutes les 5 secondes. -* `:dfu-ee` - Cette option flash un fichier `.eep` à la place d'un fichier `.hex`. Ce cas est plutôt rare. -* `:dfu-split-left` - Cette option flashe le firmware normal comme avec l'option (`:dfu`). Mais cela aussi flash le coté gauche du fichier EEPROM pour les claviers scindés. _C'est l'option idéale pour un clavier scindé basé sur le Elite C_ -* `:dfu-split-right` - Cette option flashe le firmware normal comme avec l'option (`:dfu`). Mais cela aussi flash le coté droite du fichier EEPROM pour les claviers scindés. _C'est l'option idéale pour un clavier scindé basé sur le Elite C_ - -## Caterina - -Les cartes arduinos et leurs clones utilisent le [bootloader Caterina](https://github.com/arduino/ArduinoCore-avr/tree/master/bootloaders/caterina) (tous les claviers utilisant un Pro Micro, ou un clone). Ils utilisent aussi le protocole avr109 pour communiquer en virtuellement en série (serial en Anglais). Les bootloaders comme le [A-Star](https://www.pololu.com/docs/0J61/9) sont basés sur Caterina. - -Pour vérifier la compatibilité avec un bootloader Caterina, vérifiez que ce bloc est présent dans votre fichier `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 -``` - -Flashers compatibles : - -* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (Interface graphique recomandée) -* [avrdude](http://www.nongnu.org/avrdude/) avec avr109 / `:avrdude` (Outil en ligne de commande recomandé) -* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS) - -Séquence de flash :  - -1. Pressez la touche avec le keycode `RESET`, ou reliez les ports GND et RST. Vous n'avez que 7 secondes pour flasher une fois que l'opération a été faite. -2. Attendez que l'OS détecte l'appareil. -3. Flasher le fichier .hex. -4. Attendez que l'appareil redémarre automatiquement. - -ou, utilisez : - - make ::avrdude - -ou, si vous vous voulez flasher plusieurs claviers, utilisez la commande suivante : - - make ::avrdude-loop - -Quand vous avez fini de flasher vos claviers, vous aurez besoin d'utiliser Ctrl + C ou alors la touche ayant la fonction similaire sur votre OS pour sortir de la boucle. - -## Halfkay - -Halfkay est un protocole ultra-simple développé par PJRC qui utilise HID et qui est fourni avec tous les Teensys après le modèle 2.0. - -Pour vérifier la compatibilité avec le booloader Halfkay, vérifiez que ce bloc est présent dans votre fichier `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 -``` - -Flasher compatibles : - -* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (Interface graphique recomandée) -* [Teensy Loader](https://www.pjrc.com/teensy/loader.html) (petit utilitaire ultra simple) - [Teensy Loader en ligne de commande](https://www.pjrc.com/teensy/loader_cli.html) (Outil en ligne de commande recommandé) - -Séquence de flash : - -1. Pressez la touche du keycode `RESET`, ou reliez les ports RST et GND rapidement. Vous avez ensuite 7 secondes pour réaliser le flash. -2. Attendez que l'OS détecte l'appareil. -3. Flasher le fichier .hex. -4. Redémarrez l'appareil en mode « application ». Cela peut être fait automatiquement. - -## USBasploader - -USBasploader est un bootloader développé par matrixstorm. Il est utilisé sur des processeurs AVR non-USB comme le ATmega328P, qui fonctionne grâce à V-USB. - -Pour vérifier la compatibilité avec le booloader USBasploader, vérifiez que ce bloc est présent dans votre fichier `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 -``` - -Flashers compatibles : - -* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (Interface graphique recommandé) -* [avrdude](http://www.nongnu.org/avrdude/) avec le programmeur `usbasp`. -* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS) - -Séquence de flash : - -1. Pressez la touche du keycode `RESET`, ou reliez le port de boot pendant que RST et GND snt reliés. Cela doit être fait très rapidement. -2. Attendez que l'OS détecte l'appareil. -3. Flasher le fichier .hex. -4. Redémarrez l'appareil en mode « application ». Cela peut être fait automatiquement. - -## BootloadHID - -BootloadHID est un bootloader pour les microcontroleurs AVR. L'utilitaire de téleversement ne demande pas de drivers au niveau du kernel et peut être lancé sans installer aucune DLLs. - -Pour vérifier la compatibilité avec le bootloader bootloadHID, vérifiez que ce bloc existe dans votre fichier `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 -``` - -Utilitaires de flash compatibles : - -* [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) (Utilitaire avec interface graphique recommandé) -* [bootloadhid Command Line](https://www.obdev.at/products/vusb/bootloadhid.html) / `:BootloadHID` avec QMK (utilitaire en ligne de commande recommandé) - -Séquence de flash - -1. Entrez dans le bootloader en utilisant l'une de ces méthodes : - * Pressez la touche du keycode `RESET` (Cela ne fonctionnera pas sur certains appareils). - * Verouillez la touche « Salt » tout en branchant le clavier (Géneralement ce principe est documenté dans le fichier readme du clavier) -2. Attendez que l'OS détecte l'appareil. -3. Flasher le fichier .hex. -4. Redémarrez l'appareil en mode « application ». Cela peut être fait automatiquement. - -Ou alors : - - make ::bootloadHID - -## STM32 - -Tous les processeurs STM32 contiennent un bootloader installé en usine qui ne peut pas être modifié ou supprimé. Certains processeurs STM32 ont des bootloaders qui ne peuvent pas être programmés par USB (ex : STM32F103) mais le processus reste le même. - -Pour le moment, aucune variable `BOOTLOADER` n'est nécessaire dans le fichier `rules.mk`. - -Flashers compatibles : - -* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (interface graphique recommandé) -* [dfu-util](https://github.com/Stefan-Schmidt/dfu-util) / `:dfu-util` (utilitaire en ligne de commande recommandé) - -Séquence pour flasher: - -1. Entrez dans le bootloader en utilisant l'une de ces méthodes : - * Utilisez une touche sur laquelle le keycode `RESET` (Cela peut ne pas fonctionner sur les appareils STM32F042) - * Si un circuit de réinitialisation (Reset) est présent alors utilisé le bouton qui lui est dédié. - * Autrement, vous devez réaliser une liaison entre BOOT0 et VCC (en appuyant sur le bouton ou à l'aide d'un pont) puis faire un pont entre RESET et GND et enfin relacher le pont BOOT0. -2. Attendre que l'os détecte l'appareil. -3. Flasher un fichier `.bin`.h - * Vous allez recevoir un avertissement à propos de la signature DFU. Ignorez-la. -4. Réinitialisez l'appareil en mode « application ». Cela peut être fait automatiquement. - * Si vous êtes en train de travailler en ligne de commande, par exemple avec un `make planck/rev6:default:dfu-util` alors soyez bien sur que l'argument `:leave` est passé aux argument DFU grâce à la variable `DFU_ARGS` à l'intérieur de votre fichier `rules.mk` (Ex : `DFU_ARGS = -d 0483:df11 -a 0 -s 0x08000000:leave`) afin que votre appareil redémarre après avoir été flashé. - -### Commandes STM32 - -Il y a différentes commandes que vous pouvez utiliser pour flasher un firmware dans un appareil STM32  : - -* `:dfu-util` - La commande par défaut pour flasher un appareil STM32. -* `:dfu-util-split-left` - Permet de flasher un firmware normalement, tout comme l'option précedente mais permet de configurer le coté gauche des paramètres EEPROM sur un clavier scindé. -* `:dfu-util-split-right` - Permet de flasher un firmware normalement, tout comme l'option précedente mais permet de configurer le coté droit des paramètres EEPROM sur un clavier scindé. -* `:st-link-cli` - Cela permet de flasher le firmware avec l'utilitaire en ligne de commande ST-LINK's plutôt que d'utiliser dfu-util. diff --git a/docs/fr-FR/getting_started_getting_help.md b/docs/fr-FR/getting_started_getting_help.md deleted file mode 100644 index 5eaf5197518..00000000000 --- a/docs/fr-FR/getting_started_getting_help.md +++ /dev/null @@ -1,15 +0,0 @@ -# Trouver de l'aide - -Il y a beaucoup de ressources pour trouver de l'aide avec QMK. - -## Chat temps-réel - -Vous trouverez des développeurs QMK et des utilisateurs sur notre [Serveur Discord](https://discord.gg/Uq7gcHh) principal. Il y a des canaux spécifiques dans le serveurs pour discuter des firmware, toolbox, hardware et configurateurs. - -## Sous-Reddit OLKB - -Le forum officiel de QMK est [/r/olkb](https://reddit.com/r/olkb) sur [reddit.com](https://reddit.com). - -## Tickets GitHub - -Vous pouvez ouvrir un [ticket sur GitHub](https://github.com/qmk/qmk_firmware/issues). Ceci est spécialement pratique lorsque votre problème demande une discussion long terme ou un débugage. diff --git a/docs/fr-FR/getting_started_github.md b/docs/fr-FR/getting_started_github.md deleted file mode 100644 index 32a68d0cab9..00000000000 --- a/docs/fr-FR/getting_started_github.md +++ /dev/null @@ -1,61 +0,0 @@ -# Comment utiliser GitHub avec QMK - -GitHub peut être un peu compliqué pour ceux qui n'y sont pas familier. Ce guide va vous expliquer chaque étape de "fork", clone et envoi d'un pull request avec QMK. - -?> Ce guide part du principe que vous êtes suffisamment à l'aise pour envoyer commandes sur la ligne de commande et que vous avez Git installé sur votre système. - -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) - -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 quelque fois prendre un peu de temps), appuyez sur le bouton "Clone or download": - -![Download from Github](http://i.imgur.com/N1NYcSz.jpg) - -Faites attention à sélectionner "HTTPS", et sélectionnez le liens et copiez-le: - -![HTTPS link](http://i.imgur.com/eGO0ohO.jpg) - -Ensuite, entrez `git clone` dans la ligne de commande, et collez votre lien: - -``` -user@computer:~$ git clone 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. -``` - -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: - -``` -user@computer:~$ git add . -user@computer:~$ git commit -m "adding my keymap" -[master cccb1608] adding my keymap - 1 file changed, 1 insertion(+) - create mode 100644 keyboards/planck/keymaps/mine/keymap.c -user@computer:~$ git push -Counting objects: 1, done. -Delta compression using up to 4 threads. -Compressing objects: 100% (1/1), done. -Writing objects: 100% (1/1), 1.64 KiB | 0 bytes/s, done. -Total 1 (delta 1), reused 0 (delta 0) -remote: Resolving deltas: 100% (1/1), completed with 1 local objects. -To https://github.com/whoeveryouare/qmk_firmware.git - + 20043e64...7da94ac5 master -> master -``` - -Vos changements existent maintenant dans votre fork sur GitHub. Si vous allez à cete 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) - -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) - -Une fois transmis, nous pourrons vous parler de vos changements, vous demander de faire des changements, et éventuellement de les accepter! - -Merci de contribuer à QMK :) diff --git a/docs/fr-FR/getting_started_introduction.md b/docs/fr-FR/getting_started_introduction.md deleted file mode 100644 index b64a7728f60..00000000000 --- a/docs/fr-FR/getting_started_introduction.md +++ /dev/null @@ -1,62 +0,0 @@ -# Introduction - -Le but de cette page est d'expliquer les informations de base qui vous serons nécessaire pour travailler sur le projet QMK. Il a pour pré-requis que vous soyez familier à la navigation à l'aide d'un shell Unix, mais ne s'attend pas à ce que vous soyez familier avec C ou la compilation en utilisant make. - -## 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`. - -### Structure du Userspace - -Dans le dossier `users` se trouve un répertoire pour chaque utilisateur. C'est un endroit où les utilisateurs peuvent mettre du code qui serait partagé entre plusieurs claviers. Merci de lire la documentation [Fonctionnalité Userspace](feature_userspace.md) pour plus d'information. - -### Structure du projet clavier - -Dans le dossier `keyboards`, son sous-dossier `handwired` et ses sous-dossiers pour les revendeurs et fabriquants (par exemple `clueboard`) se trouve un répertoire pour chaque projet clavier. Par exemple `qmk_firmware/keyboards/clueboard/2x1800`. - -A l'intérieur, vous trouverez la structure suivante: - -* `keymaps/`: différentes keymaps qui peuvent être compilées -* `rules.mk`: Ce fichier définit les options "make" par défaut. Ne modifiez pas ce fichier directement, utilisez à la place un `rules.mk` spécifique à la keymap. -* `config.h`: Ce fichier définit les options de compilation par défaut. Ne modifiez pas ce fichier directement, utilisez à la place un `config.h` spécifique à la keymap. -* `info.json`: Le fichier utilisé pour définir les options de layout de QMK Configurator. Voyez [Support Configurator](reference_configurator_support.md) pour plus d'information. -* `readme.md`: une brève description du clavier. -* `.h`: Ce fichier définit le layout du fichier par rapport à la matrice de commutation. -* `.c`: Ce fichier définit du code custom pour le clavier. - -Pour plus d'information sur la structure du projet, voyez [Directives clavier QMK](hardware_keyboard_guidelines.md). - -### Structure d'une Keymap - -Dans chaque dossier keymap, vous allez trouver les fichiers suivants. Seul le fichier `keymap.c` est nécessaire, et si le reste des fichiers n'existent pas, les options par défaut seront choisies. - -* `config.h`: les options de configuration de votre keymap -* `keymap.c`: tout le code de votre keymap, requis -* `rules.mk`: les features de QMK qui sont activées -* `readme.md`: une description de votre keymap, comment d'autres l'utiliseront, et des explications des fonctionnalités. Uploadez les images vers un service comme imgur. - -# Le fichier `config.h` - -Le fichier `config.h` peut être mis à 3 endroits: - -* keyboard (`/keyboards//config.h`) -* userspace (`/users//config.h`) -* keymap (`/keyboards//keymaps//config.h`) - -Le système de compilation cherche automatiquement les fichiers de configuration dans l'ordre au dessus. Si vous souhaitez surcharger une configuration définie par un `config.h` précédent, vous devrez d'abord ajouter le code suivant. - -``` -#pragma once -``` - -Ensuite, pour surcharger l'option du fichier `config.h` précédent, vous devez `#undef` puis `#define` l'option à nouveau. - -Voici à quoi l'ensemble du code resemble une fois regroupé: - -``` -#pragma once - -// overrides go here! -#undef MY_SETTING -#define MY_SETTING 4 -``` diff --git a/docs/fr-FR/newbs_best_practices.md b/docs/fr-FR/newbs_best_practices.md deleted file mode 100644 index c0e76b1c966..00000000000 --- a/docs/fr-FR/newbs_best_practices.md +++ /dev/null @@ -1,161 +0,0 @@ -# Bonnes Pratiques - -## Ou, "Comment j'ai appris à ne plus m'en faire et aimer Git." - -Ce document a pour but d'apprendre aux novices les meilleures solutions pour faciliter la contribution à QMK. Nous allons étudier le processus de contribution à QMK, détaillant quelques moyens de rendre cette tâche plus simple. Nous allons faire quelques erreurs afin de vous apprendre à les résoudre. - -Ce document suppose les choses suivantes: - -1. Vous avez un compte GitHub, et avez [créé un "fork" pour le dépôt qmk_firmware](fr-FR/getting_started_github.md) avec votre compte. -2. Vous avez [configuré votre environnement de compilation](fr-FR/newbs_getting_started.md?id=environment-setup). - -## La branche master de votre fork: Mettre à jour souvent, ne jamais commit - -Il est hautement recommandé pour le développement de QMK, peu importe ce qui est fait ou où, de garder votre branche `master` à jour, mais de ne ***jamais*** commit dessus. A la place, faites tous vos changement dans une branche de développement et crééz des "pull requests" de votre branche lorsque vous développez. - -Pour réduire les chances de conflits de fusion (merge) — des cas où deux ou plus d'utilisateurs ont édité la même section d'un fichier en parallèle — gardez votre branche `master` relativement à jour et démarrez chaque nouveau développement en créant une nouvelle branche. - -### Mettre à jour votre branche master - -Pour garder votre branche `master` à jour, il est recommandé d'ajouter le dépôt du firmware QMK comme un dépôt distant (remote) dans git. pour se faire, ouvrez votre interface de ligne de commande Git et entrez: - -```bash -git remote add upstream https://github.com/qmk/qmk_firmware.git -``` - -Pour vérifier que le dépôt a bien été ajouté, lancez la commande `git remote -v`, qui devrait retourner le résultat suivant: - -```bash -$ git remote -v -origin https://github.com//qmk_firmware.git (fetch) -origin https://github.com//qmk_firmware.git (push) -upstream https://github.com/qmk/qmk_firmware.git (fetch) -upstream https://github.com/qmk/qmk_firmware.git (push) -``` - -Maintenant que c'est fait, vous pouvez vérifier les mises à jour au dépôt en lançant `git fetch upstream`. Cela récupère les branches et les tags — appelé de manière générale "refs" — du dépôt QMK, qui a maintenant le surnom `upstream`. Nous pouvons maintenant comparer les données sur notre "fork" `origin` à celles contenues par QMK. - -Pour mettre à jour la branche master de votre "fork", lancez les commandes suivantes (en appuyant sur Enter après chaque ligne): - -```bash -git checkout master -git fetch upstream -git pull upstream master -git push origin master -``` - -Cela vous change la branche courante en master, synchronise les données de réferences du dépôt QMK vers votre ordinateur. La commande pull tire les données de réferences 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 - -Pour faire des changements, créez une nouvelle branche en entrant: - -```bash -git checkout -b dev_branch -git push --set-upstream origin dev_branch -``` - -Ceci crée une branche nommée `dev_branch`, bascule vers cette branche, et ensuite sauvegarde cette nouvelle branche vers votre fork. L'argument `--set-upstream` demande à git d'utiliser votre fork et la branche `dev_branch` à chaque fois que vous utilisez `git push` ou `git pull` depuis cette branche. Vous ne devez l'utiliser que pour le premier "push", après celà, vous pouvez utiliser simplement `git push` ou `git pull`, sans le reste des arguments. - -!> Avec `git push`, vous pouvez utiliser `-u` à la place de `--set-upstream` — `-u` est un alias pour `--set-upstream`. - -Vous pouvez appeler votre branche à peu prêt comme vous voulez, toutefois il est recommandé d'utiliser un nom qui est lié aux changements que vous allez faire. - -Par défaut, `git checkout -b` va faire de la branche actuelle la branche de base de votre nouvelle branche. Vous pouvez définir la base de votre nouvelle branche comme étant n'importe quelle branche existante qui n'est pas la courante en utilisant la commande: - -```bash -git checkout -b dev_branch master -``` - -Maintenant que vous avez une branche de développement, ouvrez votre éditeur de texte et faites vos changements. Il est recommandé de faire beaucoup de petits commits dans votre branche. Ainsi, un changement qui crée un problème peut être plus facilement retracé et annulé si nécessaire. Pour faire un changement, éditez et sauvez n'importe quel fichier qui doit être mis à jour, ajoutez les à la *zone de staging* de Git, et commitez les vers votre branche: - -```bash -git add path/to/updated_file -git commit -m "My commit message." -``` - -`git add` ajoute les fichiers qui ont été changés dans la *zone de staging* de Git, qui est sa "zone de chargement". Elle contient tous les changements qui vont être *validés* (committed) par `git commit`, qui sauvegarde les changements vers le dépôt. Utilisez des messages de validation descriptifs afin que vous puissiez savoir ce qui a changé d'un coup d'oeil. - -!> Si vous changez beaucoup de fichiers, mais tous les fichiers font partie du même changement, vous pouvez utiliser `git add .` pour ajouter tous les fichiers changés dans le répertoire courant, plutôt que d'avoir à ajouter chaque fichiers individuellement. - -### Publier Vos Changements - -La dernière étape est de pousser vos changements vers votre fork. pour se faire, entrez `git push`. Git publie maintenant l'état courant de `dev_branch` vers votre fork. - -## Résoudre Les Conflits De Merge - -Parfois, lorsque votre travail sur une branche met beaucoup de temps à se compléter, des changements réalisés par d'autres peuvent entrer en conflit avec les changements que vous avez fait sur votre branche au moment où vous avez ouvert un pull request. Ceci est appelé un *conflit de merge*, et c'est ce qui arrive lorsque plusieurs personnes modifient les mêmes parties de mêmes fichiers. - -### Rebaser Vos Changements - -Un *rebase* est la manière pour Git de prendre les changements qui ont été faits à un point, les annuler, et les réappliquer sur un autre point. Dans le cas d'un conflit de merge, vous pouvez rebaser votre branche pour récupérer les changements qui ont été faits entre le moment où vous avez créé votre branche et le présent. - -Pour démarrer, lancez les commandes suivantes: - -```bash -git fetch upstream -git rev-list --left-right --count HEAD...upstream/master -``` - -La commande `git rev-list` retourne le nombre de commits qui diffère entre la branche courante et la branche master de QMK. Nous lançons `git fetch` en premier afin d'être sûr que les refs qui représentent l'état courant du dépôt upstream soient à jour. Le résultat de la commande `git rev-list` retourne deux nombres: - -```bash -$ git rev-list --left-right --count HEAD...upstream/master -7 35 -``` - -Le premier nombre représente combien il y a eu de commits sur la branche courante depuis qu'elle a été créée, et le second nombre est combien de commits ont été faits sur la branche `upstream/master` depuis que la branche a été créée et, ainsi, les changements qui ne sont pas enregistrés sur la branche courante. - -Maintenant que l'état actuel de la branche courante et la branche upstream sont connus, nous pouvons maintenant démarrer une opération de rebase: - -```bash -git rebase upstream/master -``` - -Ceci dit à Git d'annuler les commits de la branche courrante puis de les réappliquer sur la branche master de QMK. - -```bash -$ git rebase upstream/master -First, rewinding head to replay your work on top of it... -Applying: Commit #1 -Using index info to reconstruct a base tree... -M conflicting_file_1.txt -Falling back to patching base and 3-way merge... -Auto-merging conflicting_file_1.txt -CONFLICT (content): Merge conflict in conflicting_file_1.txt -error: Failed to merge in the changes. -hint: Use 'git am --show-current-patch' to see the failed patch -Patch failed at 0001 Commit #1 - -Resolve all conflicts manually, mark them as resolved with -"git add/rm ", then run "git rebase --continue". -You can instead skip this commit: run "git rebase --skip". -To abort and get back to the state before "git rebase", run "git rebase --abort". -``` - -Ceci nous dit que nous avons un conflit de merge, et nous donne le nom du fichier en conflit. Ouvez le fichier conflictuel dans votre éditeur de texte et, quelque part dans le fichier, vous trouverez quelque chose comme ça: - -```bash -<<<<<<< HEAD -

For help with any issues, email us at support@webhost.us.

-======= -

Need help? Email support@webhost.us.

->>>>>>> Commit #1 -``` - -La ligne `<<<<<<< HEAD` montre le début d'un conflit de merge et la ligne `>>>>>>> Commit #1` indique la fin, avec les sections conflictuelles séparées par `=======`. La partie du côté `HEAD` vient de la version du fichier provenant de la branche master de QMK, et la partie marquée avec le numéro du commit provient de la branche courrante. - -Parce que Git suis *les changements des fichiers*, plutôt que les contenus des fichiers directement, si Git ne peut pas trouver le texte qu'il y avait dans le fichier avant que le commit soit fait, il ne saura pas comment modifier le fichier. Modifier le fichier à nouveau va résoudre le conflit. Faites votre changement, et sauvez le fichier. - -```bash -

Need help? Email support@webhost.us.

-``` - -Maintenant, lancez: - -```bash -git add conflicting_file_1.txt -git rebase --continue -``` - -Git enregistre le changement dans le fichier conflictuel, et continue à appliquer les commits depuis votre branche jusqu'à ce qu'il arrive à la fin. diff --git a/docs/fr-FR/newbs_building_firmware_configurator.md b/docs/fr-FR/newbs_building_firmware_configurator.md deleted file mode 100644 index ea284c50595..00000000000 --- a/docs/fr-FR/newbs_building_firmware_configurator.md +++ /dev/null @@ -1,105 +0,0 @@ -# Configurateur de QMK - -Le [Configurateur de QMK](https://config.qmk.fm) est une interface graphique en ligne permettant de générer des fichiers "hex" du firmware de QMK. - -?> **S'il vous plaît, suivez les étapes suivantes dans l'ordre.** - -Regardez le [Tutoriel vidéo](https://youtu.be/tx54jkRC9ZY) - -Le configurateur de QMK fonctionne mieux avec Chrome et Firefox. - -!> **Les fichiers d'autres outils, tels que KLE ou kbfirmware ne seront pas compatibles avec le configurateur QMK. Ne les chargez pas, ne les importez pas. Le configurateur QMK est un outil DIFFERENT.** - -## Sélectionner votre clavier - -Cliquez la boîte déroulante et sélectionnez le clavier pour lequel vous voulez créer une keymap. - -?> Si votre clavier a plusieurs versions, faites attention à utiliser la bonne. - -Je vais le répéter, parce que c'est important - -!> **FAITES ATTENTION A UTILISER LA BONNE VERSION !** - -Si votre clavier est annoncé comme fonctionnant grâce à QMK mais n'est pas dans la liste, il y a des chances que le développeur ne l'ait pas encore fait, ou que nous n'avons pas encore eu le temps de le merger. Ajoutez un problème (issue) sur [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) demandant le support de votre clavier, s'il n'y a pas de [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) ouvert pour lui. Il y a aussi des clavier alimentés par QMK qui sont sur le compte GitHub du fabriquant, il est bon de le vérifier aussi. - -## Sélectionner la disposition de votre clavier - -Choisissez la disposition (layout) qui représente le mieux la keymap que vous voulez créer. Certains clavier n'ont pas encore assez de dispositions ou des dispositions incorrectes. Ils seront supportés dans le future. - -## Nom de la Keymap - -Appelez cette keymap comme vous voulez. - -?> Si vous rencontrez des problèmes lors de la compilation, il peut être utile de changer ce nom, il peut déjà exister dans le dépôt du firmware QMK. - -## Créer votre keymap - -Entrer un keycode peut s'accomplir de 3 façons différentes. - -1. Glisser déposer -2. Cliquer sur un endroit vide sur le layout et cliquer sur le keycode souhaité -3. Cliquer sur un endroit vide sur le layout et appuyer sur une touche physique de votre clavier. - -Passez votre souris au dessus d'une touche et un affichage vous dira quel est le rôle du keycode. Pour une version plus verbeuse suivre: - -[Référence Keycode basique](https://docs.qmk.fm/#/keycodes_basic) -[Référence Keycode avancé](https://docs.qmk.fm/#/feature_advanced_keycodes) - -Dans le cas où vous ne trouvez pas une disposition qui supporte votre keymap, par exemple trois places pour une barre d'espace, ou deux places pour retour clavier, ou deux places pour shift, etc. etc. remplissez les TOUTES. - -### Exemples - -3 places pour la barre d'espace: Remplissez les TOUTES avec la barre d'espace - -2 places pour un retour clavier: Remplissez les DEUX avec un retour clavier - -2 places pour un shift droit: Remplissez les DEUX avec un shift droit - -1 place pour un shift gauche et 1 place pour le support ISO: Remplissez les deux avec un shift gauche - -5 places, mais seulement 4 touches: Deviner et vérifier, ou demander à quelqu'un qui l'a déjà fait. - -## Sauvez votre keymap pour des éditions futures - -Une fois satisfait de votre keymap, ou si vous souhaitez revenir travailler dessus plus tard, appuyez sur le bouton `Export Keymap`. Il vous permettra de sauvegarder votre keymap avec le nom choisi au dessus suivi de .json. - -Vous pouvez ensuite charger ce fichier .json à nouveau en appuxant sur le bouton `Import Keymap`. - -!> **ATTENTION** Ce n'est pas le même type de fichier .json utilisé pour kbfirmware.com ou n'importe quel autre outil. Si vous essayez d'utiliser ce fichier pour d'autres outil, ou le fichier .json d'autres outils avec le configurateur QMK, il y a des chances que votre clavier **explose**. - -## Générer votre fichier firmware - -Appuyez sur le bouton `Compile`. - -Une fois la compilation terminée, vous pourrez appuyer sur le bouton vert `Download Firmware`. - -## Ecrire votre firmware sur votre clavier - -Merci de vous référer à [Flasher le Firmware](fr-FR/newbs_flashing.md) - -## Dépannage - -#### Mon fichier json ne fonctionne pas - -Si le fichier .json a été généré par le configurateur QMK, bravo vous avez trouvé un bug. Merci d'ouvrir une issue sur [qmk_configurator](https://github.com/qmk/qmk_configurator/issues) - -Sinon... vous avez raté mon message écris en gras qui dit de ne pas utiliser d'autres fichiers .json? - -#### Il y a des espaces en trop dans mon alyout? Qu'est-ce que je fais? - -Si vous voulez dire que vous avez trois places pour une barre d'espace, le mieux est de les remplir tous avec une barre d'espace. Vous pouvez faire de même avec les retour clavier et les shift. - -#### C'est quoi le keycode pour ....... - -Merci de regarder - -[Référence keycode basique](https://docs.qmk.fm/#/keycodes_basic) -[Référence keycode avancé](https://docs.qmk.fm/#/feature_advanced_keycodes) - -#### Ca ne compile pas? - -Merci de vérifier les autres dispositions de votre keymap afin d'être sûr qu'il n'y a pas de touches aléatoires. - -## Problèmes et Bugs - -Nous acceptons toujours les demandes des clients et les rapports de bugs. Merci de les remplirs sur [qmk_configurator](https://github.com/qmk/qmk_configurator/issues) diff --git a/docs/fr-FR/newbs_flashing.md b/docs/fr-FR/newbs_flashing.md deleted file mode 100644 index 401c524acab..00000000000 --- a/docs/fr-FR/newbs_flashing.md +++ /dev/null @@ -1,348 +0,0 @@ -# Flasher votre clavier - -Maintenant que vous avez compilé un firmware custom, vous allez vouloir le flasher dans votre clavier. - -## Flasher votre clavier avec QMK Toolbox - -La manière la plus simple de flasher votre clavier est avec [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases). - -Toutefois, la QMK Toolbox n'est actuellement disponible que pour Windows et macOS. Si vous utilisez Linux (ou préférez flasher le firmware depuis la ligne de commande), vous devrez utiliser [la métode décrite ci-dessous](newbs_flashing.md#flash-your-keyboard-from-the-command-line). - -### Charger le fichier dans QMK Toolbox - -Démarrez en ouvrant l'application QMK Toolbox. Cherchez le fichier de firmware dans Finder ou Explorer. Vore firmware de clavier peut être dans un de deux formats `.hex` ou `.bin`. QMK essaye de copier le bon format pour votre clavier du répertoire racine `qmk_firmware`. - -?> Si vous êtes sous Windows ou macOS il y a des commandes que vous pouvez utiliser pour facilement ouvrir le répertoire firmware dans Explorer ou Finder. - -?> Windows: - - start . - -?> macOS: - - open . - -Le fichier firmware suit toujours ce format de nommage: - - _.{bin,hex} - -Par exemple, le `plank/rev5` avec une keymap `default` aura ce nom de fichier: - - planck_rev5_default.hex - -Une fois que vous aurez trouvé votre fichier de firmware, glissez le dans la boîte "Local file" sur QMK Toolbox, ou cliquez sur "Open" et naviguez où votre firmware est enregistré. - -### Mettez votre clavier en mode DFU (Bootloader) - -Afin de flasher votre firmware custom, vous devez mettre votre clavier dans un mode spécial. Lorsqu'il sera dans ce mode, vous ne pourrez pas taper ou utiliser votre clavier. Il est très important que vous ne débranchiez pas votre clavier ou n'arrêtiez pas le processus d'écriture du firmware. - -Chaque clavier a une manière différente d'entrer dans ce mode spécial. Si votre clavier tourne actuellement QMK ou TMK et vous n'avez pas reçu d'instruction spécifiques, essayez, dans cet ordre: - -* Enfoncez les deux touches shift et appuyez sur `Pause` -* Enfoncez les deux touches shift et appuyez sur `B` -* Débranchez votre clavier, gardez shift la barre d'espace et `B` en même temps, branchez votre clavier et attendez une seconde avant de relâcher les touches. -* Appuyez la touche physique `RESET` en bas du PCB -* Trouvez les pins sur le PCB marquées `BOOT0` ou `RESET`, court circuitez ces pins en branchant votre PCB - -Lorsque vous aurez réussi, vous verrez le message suivant dans QMK Toolbox: - -``` -*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 -*** DFU device connected -``` - -### Flasher votre clavier - -Appuyez sur le boutton `Flash` dans QMK Toolbox. Vous verrez un résultat similaire à ce qui suit: - -``` -*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 -*** DFU device connected -*** Attempting to flash, please don't remove device ->>> dfu-programmer atmega32u4 erase --force - Erasing flash... Success - Checking memory from 0x0 to 0x6FFF... Empty. ->>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex - Checking memory from 0x0 to 0x55FF... Empty. - 0% 100% Programming 0x5600 bytes... - [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success - 0% 100% Reading 0x7000 bytes... - [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success - Validating... Success - 0x5600 bytes written into 0x7000 bytes memory (76.79%). ->>> dfu-programmer atmega32u4 reset - -*** DFU device disconnected -*** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390 -``` - -## Flashez votre clavier à l'aide de la ligne de commande - -La première chose que vous devez savoir c'est quel bootloader utilise votre clavier. Il y a quatre bootloaders principaux. Pro-Micro et les clones, utilisent CATERINA, les Teensy utilisent Halfkay, les OLKB utilisent QMK-DFU et les autres chips atmega32u4 utilisent DFU. - -Vous pouvez trouver plus d'information à propos des bootloaders sur la page [Instructions de flash et information sur le Bootloader](flashing.md). - -Si vous savez quel bootloader vous utilisez, lorsque vous compilez le firmware, vous pouvez ajouter quelques options à la commande `make` pour automatiser le processus de flash. - -### DFU - -Pour le bootloader DFU, lorsque vous êtes prêts à compiler et flasher votre firmware, ouvrez votre fenêtre de terminal et lancez la commande de compilation: - - make ::dfu - -Par exemple, si vous keymap s'appelle "xyverz" et vous compilez une keymap pour une plank rev5, vous utiliserez cette commande: - - make planck/rev5:xyverz:dfu - -Une fois la compilation terminée, le résultat devrait être le suivant: - -``` -Linking: .build/planck_rev5_xyverz.elf [OK] -Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK] -Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK] -Checking file size of planck_rev5_xyverz.hex - * File size is fine - 18574/28672 - ``` - -Une fois arrivé à ce stade, le script de compilation va checher le bootloader DFU toutes les 5 secondes. Il va répéter les messages suivants jusqu'à ce que l'appareil soit trouvé ou que vous l'annuliez. - - dfu-programmer: no device present. - Error: Bootloader not found. Trying again in 5s. - -Une fois terminé, vous devrez mettre à zéro le contrôleur. Vous allez voir un résultat similaire à ceci: - -``` -*** Attempting to flash, please don't remove device ->>> dfu-programmer atmega32u4 erase --force - Erasing flash... Success - Checking memory from 0x0 to 0x6FFF... Empty. ->>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex - Checking memory from 0x0 to 0x55FF... Empty. - 0% 100% Programming 0x5600 bytes... - [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success - 0% 100% Reading 0x7000 bytes... - [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success - Validating... Success - 0x5600 bytes written into 0x7000 bytes memory (76.79%). ->>> dfu-programmer atmega32u4 reset -``` - -?> Si vous avez des soucis concerant ceci - comme par exemple `dfu-programmer: no device present` - merci de regarder [Foires Aux Questions de Compilation](faq_build.md). - -#### Commandes DFU - -Il y aun certain nombre de commandes du DFU que vous pouvez utiliser pour flasher un firmware sur un device DFU: - -* `:dfu` - C'est l'option standard qui attends jusqu'à e qu'un appareil DFU soit disponible, puis flash le firmware. Il va vérifier toutes les 5 secondes, afin de voir si un appareil DFU est apparu. -* `:dfu-ee` - Ceci flash un fichier `eep` à la place du standard hex, peu commun. -* `:dfu-split-left` - Ceci flash le firmware standard, comme la commande standard (`:dfu`). Toutefois, elle flash aussi les fichiers EEPROM du "côté gauche" pour les claviers scindés. _C'est l'option idéale pour les claviers scindés basés sur Elite C._ -* `:dfu-split-right` - Ceci flash le firmware standard, comme la commande standard (`:dfu`). Toutefois, elle flash aussi les fichiers EEPROM du "côté droit" pour les claviers scindés. _C'est l'option idéale pour les claviers scindés basés sur Elite C._ - -### Caterina - -Pour les boards Arduino et leurs clones (tel que le SparkFun ProMicro), lorsque vous êtes prêt à compiler et flasher votre firmware, ouvrez votre terminal et lancer la commande de compilation: - - make ::avrdude - -Par exemple, si votre keymap se nomme "xyverz" et que vous compilez une keymap pour un Lets Split rev2, vous utiliserez la commande suivante: - - make lets_split/rev2:xyverz:avrdude - -Une fois le firmware compilé, vous aurez le résultat suivant: - -``` -Linking: .build/lets_split_rev2_xyverz.elf [OK] -Creating load file for flashing: .build/lets_split_rev2_xyverz.hex [OK] -Checking file size of lets_split_rev2_xyverz.hex [OK] - * File size is fine - 27938/28672 -Detecting USB port, reset your controller now.............. -``` - -Une fois ceci fait, réinitialisez votre board et le script va détecter et flasher le firmware. La sortie devrait ressember à quelque chose comme ça: - -``` -Detected controller on USB port at /dev/ttyS15 - -Connecting to programmer: . -Found programmer: Id = "CATERIN"; type = S - Software Version = 1.0; No Hardware Version given. -Programmer supports auto addr increment. -Programmer supports buffered memory access with buffersize=128 bytes. - -Programmer supports the following devices: - Device code: 0x44 - -avrdude.exe: AVR device initialized and ready to accept instructions - -Reading | ################################################## | 100% 0.00s - -avrdude.exe: Device signature = 0x1e9587 (probably m32u4) -avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed - To disable this feature, specify the -D option. -avrdude.exe: erasing chip -avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex" -avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex -avrdude.exe: writing flash (27938 bytes): - -Writing | ################################################## | 100% 2.40s - -avrdude.exe: 27938 bytes of flash written -avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex: -avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex: -avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex -avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes -avrdude.exe: reading on-chip flash data: - -Reading | ################################################## | 100% 0.43s - -avrdude.exe: verifying ... -avrdude.exe: 27938 bytes of flash verified - -avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF) - -avrdude.exe done. Thank you. -``` - -Si vous avez un soucis, essayez de faire ceci: - - sudo make ::avrdude - -En addition, si vous voulez flasher plusieurs boards, utilisez la commande suivante: - - make ::avrdude-loop - -Une fois que vous avez terminé de flasher des boards, vous devrez appuyer sur Ctrl + C, ou les touches correspondantes pour votre système d'exploitation pour arrêter la boucle. - -### HalfKay - -Pour les composants PJRC (les Teensy), lorsque vous êtes prêts à compiler et flasher votre firmware, ouvrez votre fenêtre de terminal et lancez la commande de compilation suivante: - - make ::teensy - -Par exemple, si vous keymap s'appelle "xyverz" et vous compilez une keymap pour un Ergodox ou un Ergodox EZ, vous utiliserez cette commande: - - make ergodox_ez:xyverz:teensy - -Une fois la compilation du firmware terminée, votre sortie devrait ressembler à ça: - -``` -Linking: .build/ergodox_ez_xyverz.elf [OK] -Creating load file for flashing: .build/ergodox_ez_xyverz.hex [OK] -Checking file size of ergodox_ez_xyverz.hex [OK] - * File size is fine - 25584/32256 - Teensy Loader, Command Line, Version 2.1 -Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage -Waiting for Teensy device... - (hint: press the reset button) - ``` - -Une fois terminé, réinitialisez votre board. Une fois fait, vous verrez une sortie comme ça: - - ``` - Found HalfKay Bootloader -Read "./.build/ergodox_ez_xyverz.hex": 28532 bytes, 88.5% usage -Programming............................................................................................................................................................................ -................................................... -Booting -``` - -### BootloadHID - -Pour les boards basée sur Bootmapper Client(BMC)/bootloadHID/ATmega32A, une fois prêt à compiler et flasher le firmware, ouvrez votre fenêtre de terminal et lancez la commande suivante: - - make ::bootloaderHID - -Par exemple, si votre keymap s'appelle "xyverz" et que vous compilez une keymap pour un jj40, vous utilisez cette commande: - - make jj40:xyverz:bootloaderHID - -Une fois le firmware compilé, vous aurez cette sortie: - -``` -Linking: .build/jj40_default.elf [OK] -Creating load file for flashing: .build/jj40_default.hex [OK] -Copying jj40_default.hex to qmk_firmware folder [OK] -Checking file size of jj40_default.hex [OK] - * The firmware size is fine - 21920/28672 (6752 bytes free) -``` - -A ce stade, le script de build va chercher le bootloader DFU toutes les 5 secondes. Il va répéter la sortie suivante jusqu'à ce que le dispositif soit trouvé ou que vous l'annuliez. - -``` -Error opening HIDBoot device: The specified device was not found -Trying again in 5s. -``` - -Une fois ce résultat atteint, réinitialisez le contrôleur. Il devrait afficher le résultat suivant: - -``` -Page size = 128 (0x80) -Device size = 32768 (0x8000); 30720 bytes remaining -Uploading 22016 (0x5600) bytes starting at 0 (0x0) -0x05580 ... 0x05600 -``` - -### STM32 (ARM) - -Pour la majorité des boards ARM (incluant les Proton C, Planck Rev 6, et Preonic Rev 3), lorsque vous êtes prêt à compiler et flasher votre firmware,ouvrez la fenêtre de terminal et lancez la commande de compilation: - - make ::dfu-util - -Par exemple, si votre keymap s'appelle "xyverz" et vous compilez une keymap pour le clavier Plank Revision 6, vous utiliserez cette commande et redémarrerez le clavier vers le bootloader (avant que la compilation soit terminée): - - make planck/rev6:xyverz:dfu-util - -Une fois le firmware compilé, il va afficher quelque chose comme ça: - -``` -Linking: .build/planck_rev6_xyverz.elf [OK] -Creating binary load file for flashing: .build/planck_rev6_xyverz.bin [OK] -Creating load file for flashing: .build/planck_rev6_xyverz.hex [OK] - -Size after: - text data bss dec hex filename - 0 41820 0 41820 a35c .build/planck_rev6_xyverz.hex - -Copying planck_rev6_xyverz.bin to qmk_firmware folder [OK] -dfu-util 0.9 - -Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. -Copyright 2010-2016 Tormod Volden and Stefan Schmidt -This program is Free Software and has ABSOLUTELY NO WARRANTY -Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ - -Invalid DFU suffix signature -A valid DFU suffix will be required in a future dfu-util release!!! -Opening DFU capable USB device... -ID 0483:df11 -Run-time device DFU version 011a -Claiming USB DFU Interface... -Setting Alternate Setting #0 ... -Determining device status: state = dfuERROR, status = 10 -dfuERROR, clearing status -Determining device status: state = dfuIDLE, status = 0 -dfuIDLE, continuing -DFU mode device DFU version 011a -Device returned transfer size 2048 -DfuSe interface name: "Internal Flash " -Downloading to address = 0x08000000, size = 41824 -Download [=========================] 100% 41824 bytes -Download done. -File downloaded successfully -Transitioning to dfuMANIFEST state -``` - -#### Commandes STM32 - -Il y aun certain nombre de commandes du DFU que vous pouvez utiliser pour flasher un firmware sur un device STM32: - -* `:dfu-util` - C'est l'option standard pour flasher un appareil STM32. -* `:dfu-util-wait` - Ceci fonctionne comme la commande standard, mais permet de d'avoir une pause (configurable( de 10 secondes avant de flasher le fimrware. Vous pouvez utiliser `TIME_DELAY=20` à la ligne de commande pour changer le délai. -* `:dfu-util-left` - Ceci flasher le firmware standard, comme la commande standard (`:dfu-util`). Toutefois, elle flasher aussi les fichiers EEPROM du "côté gauche" pour les claviers scindés. -* `:dfu-util-right` - Ceci flash le firmware standard, comme la commande standard (`:dfu-util`). Toutefois, elle flash aussi les fichiers EEPROM du "côté droit" pour les claviers scindés. - -## Faites l'essai! - -Bravo! Votre firmware customisé a été programmé sur votre clavier! - -Essayez-le et vérifiez qu'il fonctionne comme vous le souhaitez. Nous avons écrit [Tester et débugger](newbs_testing_debugging.md) pour compléter le guide du débutant, alors allez voir là-bas pour apprendre comment dépanner vos fonctionnalités custom. diff --git a/docs/fr-FR/newbs_getting_started.md b/docs/fr-FR/newbs_getting_started.md deleted file mode 100644 index 751fd0563ac..00000000000 --- a/docs/fr-FR/newbs_getting_started.md +++ /dev/null @@ -1,101 +0,0 @@ -# Introduction - -Votre clavier d'ordinateur contient un processeur, proche de celui dans votre ordinateur. Ce processeur exécute un logiciel responsable de détecter les touches appuyées et envoie des rapports à propos de l'état du clavier lorsque les touches sont appuyées et relâchées. QMK prend le rôle de ce logiciel, détectant les appuis des boutons et passant cette information à l'ordinateur hôte. Lorsque vous construisez votre keymap customisée, vous créez l'équivalent d'un programme exécutable pour votre clavier. - -QMK essaie de rendre les choses simples faciles, et les choses difficiles possibles. Vous n'avez pas à savoir programmer pour créer des keymaps puissantes - vous devez seulement suivre quelques rêgles de syntaxe simples. - -# Guide de démarrage - -Avant de pouvoir construire des keymaps, vous devez installer quelques logiciels et configurer votre environnement de compilation. Ceci n'a besoin d'être fait seulement une fois, peu importe le nombre de clavier pour lesquels vous compter compiler un firmware. - -Si vous préférez une approche plus proche d'une interface graphique, considérez utiliser l'outil en ligne [QMK Configurator](https://config.qmk.fm). Référez vous à [Construire votre premier firmware en utilisant l'interface graphique en ligne](newbs_building_firmware_configurator.md). - -## Logiciels à télécharger - -### Editeur de texte - -Vous allez avoir besoin d'un programme qui peut éditer et sauvegarder des fichier **plain text**. Si vous êtes sur Windows, vous pouvez utiliser notepad et sur Linux vous pouvez utiliser gedit. Ces deux options sont des éditeurs de texte simples mais fonctionnels. Sur macOS, faites attention avec l'application par défaut TextEdit: elle ne sauvegardera pas les fichiers en mode "plain text" sauf si vous sélectionnez explicitement _Make Plain Text_ à partir du menu _Format_. - -Vous pouvez aussi télécharger et installer un éditeur de texte dédié comme [Sublime Text](https://www.sublimetext.com/) ou [VS Code](https://code.visualstudio.com/). C'est probablement la meilleure solution peu importe la plateforme car ce sont des programmes conçus spécifiquement pour éditer du code. - -?> Pas sûr de quel éditeur de texte utiliser? Laurence Bradford a écrit une [excellente introduction](https://learntocodewith.me/programming/basics/text-editors/) au sujet. - -### QMK Toolbox - -QMK Toolbox est un programme graphique optionnel pour Windows et macOS qui permet à la fois de programmer et débugger votre clavier customisé. Il vous sera probablement très utile pour facilement flasher votre clavier et analyser ses messages de débugage. - -[Télécharger la dernière version ici.](https://github.com/qmk/qmk_toolbox/releases/latest) - -* Pour Windows: `qmk_toolbox.exe` (portable) or `qmk_toolbox_install.exe` (installeur) -* Pour macOS: `QMK.Toolbox.app.zip` (portable) or `QMK.Toolbox.pkg` (installeur) - -## Configurez votre environnement - -Nous avons essayé de rendre QMK aussi simple que possible à configurer. Vous avez uniquement à préparer votre environnment Linux ou Unix et laisser QMK installer le reste. - -?> Si vous n'avez jamais travailé avec la lignde commande Linux/Unix, il y a un certain nombre de concepts basiques et de commandes que vous devriez apprendre. Ces ressources vous apprendrons suffisemment pour travailler avec QMK:
-[Commandes Linux à savoir](https://www.guru99.com/must-know-linux-commands.html)
-[Commandes Unix de base](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html) - -### Windows - -Vous devez installer MSYS2 et Git. - -* Suivez les instructions d'installation sur la [page de MSYS2](http://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`. - -### macOS - -Vous devez installer Homebew. Suivez les instructions sur la [page de Homebrew](https://brew.sh). - -Une fois Homebrew installé, continuez avec _Configurer QMK_. Dans cete étape, nous lancerons un script qui va installer d'autres paquets. - -### Linux - -Vous devez installer Git. Il est très probable que vous l'ayez déjà installé, mais sinon, une des commandes suivantes devrait l'installer: - -* Debian / Ubuntu / Devuan: `apt-get install git` -* Fedora / Red Hat / CentOS: `yum install git` -* Arch: `pacman -S git` - -?> Docker est aussi une option sur toutes les plateformes. [Appuyez ici pour plus de détail.](getting_started_build_tools.md#docker) - -## Configurer QMK - -Une fois votre environnement Linux/Unix configuré, vous êtes prêt à télécharger QMK. Nous allons le faire en utilisant Git pour "cloner" le dépôt de QMK. Ouvrez un terminal ou une fenêtre MSYS2 MinGW et gardez le ouvert pour le reste de ce guide. Dans ce terminal, lancez ces deux commandes: - -```shell -git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git -cd qmk_firmware -``` - -?> Si vous savez déjà [comment utiliser GitHub](getting_started_github.md), nous recommandons que vous créez et clonez votre propre fork. Si vous ne savez pas ce que cela veut dire, vous pouvez sans problème ignorer ce message. - -QMK vient avec un script pour vous aider à configurer le reste de ce que vous aurez besoin. Vous devez le lancer en tapant la ligne de commande suivante: - - util/qmk_install.sh - -## Testez votre environnement de compilation - -Maintenant que votre environnement de compilation de QMK est configuré, vous pouvez compiler un firmware pour votre clavier. Démarrez en compilant la keymap par défaut du clavier. Vous devriez pouvoir le faire avec une commande de ce format: - - make :default - -Par exemple, pour compiler un firmware pour une Clueboard 66%, vous utiliserez: - - make clueboard/66/rev3:default - -Une fois ceci fait, vous devriez avoir beaucoup d'information dans votre sortie qui devrait se terminer par quelque chose de similaire à ça: - -``` -Linking: .build/clueboard_66_rev3_default.elf [OK] -Creating load file for flashing: .build/clueboard_66_rev3_default.hex [OK] -Copying clueboard_66_rev3_default.hex to qmk_firmware folder [OK] -Checking file size of clueboard_66_rev3_default.hex [OK] - * The firmware size is fine - 26356/28672 (2316 bytes free) -``` - -# Créer votre Keymap - -Vous êtes maintenant prêt à créer votre propre keymap! Passez à l'étape [Compiler votre premier firmware](newbs_building_firmware.md) pour ce faire. diff --git a/docs/fr-FR/newbs_testing_debugging.md b/docs/fr-FR/newbs_testing_debugging.md deleted file mode 100644 index bc6aec668da..00000000000 --- a/docs/fr-FR/newbs_testing_debugging.md +++ /dev/null @@ -1,102 +0,0 @@ -# Test et débugage - -Une fois votre clavier configuré avec un firmware custom, vous êtes prêt à le tester. Avec un peu de chance, tout fonctionne parfaitement bien, dans le cas contraire, ce document vous aidera à trouver où se trouve le problème. - -## Tester - -Tester votre clavier est normalement assez simple. Appuyez chaque touche de votre clavier et assurez vous qu'il envoie les touches auquel vous vous attendiez. Il existe même des programmes qui vous aideront à vérifier qu'aucune touche ne soit oubliée. - -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) - -## Débuguer - -Votre clavier va envoyer des informations de débugage si vous avez `CONSOLE_ENABLE = yes` dans votre fichier `rules.mk`. Par défaut, la sortie est très limitée, mais vous pouvez activer le mode debug pour augmenter la quantité de sortie de débugage. Utilisez le keycode `DEBUG` dans votre keymap, utilisez la fonction [Commande](feature_command.md) pour activer le mode debug ou ajoutez le code suivant à votre 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; -} -``` - -### Débuguer avec QMK Toolbox - -Pour les plateformes compatibles, [QMK Toolbox](https://github.com/qmk/qmk_toolbox) peut être utilisé pour afficher les message de débugage pour votre clavier. - -### Débuguer avec hid_listen - -Vous préférez une solution basée sur le terminal? [hid_listen](https://www.pjrc.com/teensy/hid_listen.html), fourni par PJRC, peut aussi être utilisé pour afficher des messages de débugage. Des versions compilées pour Windows, Linux et MacOS sont disponibles. - - - -## Envoyer vos propres messages de débugage - -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 - -Une fois fait, vous pouvez utiliser les fonctions print suivantes: - -* `print("string")`: Affiche une simple chaîne de caractères. -* `uprintf("%s string", var)`: Affiche une chaîne de caractères formattée. -* `dprint("string")` Affiche une chaîne de caractère simple, mais uniquement lorsque le mode debug est activé. -* `dprintf("%s string", var)`: Affiche une chaîne de caractère formattée, mais uniquement lorsque le mode debug est activé. - -## Exemples de debugage - -Si dessous se trouve une liste d'exemples réels de débugage. Pour plus d'information, référez-vous à [Débuguer/Dépanner QMK](faq_debug.md). - -### A quelle position de la matrice se trouve cette activation de touche? - -Lors du portage ou lorsque vous essayez de diagnostiquer un problème de PCB, il est utile de savoir si une activation de touche est enregistrée correctement. Pour activer le log de ce scénario, ajoutez le code suivant à votre fichier 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: %u, col: %u, row: %u, pressed: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed); -#endif - return true; -} -``` - -Exemple de sortie - -```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 -``` - -### Combien de temps cela a pris pour une activation de touche? - -Lorsque vous testez des problèmes de performance, il peut être utile de savoir à quelle fréquence la matrice est scannée. Pour activer le log dans ce scénario, ajoutez la ligne suivante à votre fichier `config.h` de votre keymaps. - -```c -#define DEBUG_MATRIX_SCAN_RATE -``` - -Exemple de sortie - -```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 -``` diff --git a/docs/fr-FR/ChangeLog/20190830.md b/docs/fr-fr/ChangeLog/20190830.md similarity index 97% rename from docs/fr-FR/ChangeLog/20190830.md rename to docs/fr-fr/ChangeLog/20190830.md index 4ce1b086315..cb223be31ab 100644 --- a/docs/fr-FR/ChangeLog/20190830.md +++ b/docs/fr-fr/ChangeLog/20190830.md @@ -6,9 +6,9 @@ Ce document présente les fusions de Breaking Change. Voici la liste des changem ## Formattage de code Core avec clang-format -* Tous les fichiers core (`drivers/`, `quantum/`, `tests/`, et `tmk_core/`) seront formattés avec clang-format +* Tous les fichiers core (`drivers/`, `quantum/`, `tests/`, et `tmk_core/`) seront formatés avec clang-format * Un processus travis pour reformatter les PRs lors de la fusion a été mis en place -* Vous pouvez utiliser la nouvelle commande CLI `qmk cformat` afin de formatter avant de soumettre votre PR si vous le souhaitez. +* Vous pouvez utiliser la nouvelle commande CLI `qmk cformat` afin de formater avant de soumettre votre PR si vous le souhaitez. ## Nettoyage des descripteurs LUFA USB diff --git a/docs/fr-fr/README.md b/docs/fr-fr/README.md new file mode 100644 index 00000000000..3743bedc97d --- /dev/null +++ b/docs/fr-fr/README.md @@ -0,0 +1,32 @@ +# Quantum Mechanical Keyboard Firmware + +[![Version courante](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags) +[![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/) + +## 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é. + +## 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. + +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`). + +## Comment le compiler + +Avant d'être prêt à compiler vous allez devoir [installer un environnement](fr-fr/getting_started_build_tools.md) pour les développements AVR et/ou ARM. Une fois ceci fait, vous pourrez utiliser la commande `make` pour compiler le clavier et la disposition avec une commande de ce type : + + make planck/rev4:default + +Cette commande compilera la révision `rev4` du clavier `planck` avec la disposition `default`. Notez que tous les claviers n'ont pas forcément de révisions (aussi appelées sous-projects ou dossiers, ou en anglais « subprojects » ou « folder »). Cette option peut donc être omise : + + make preonic:default + +## 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). diff --git a/docs/fr-fr/_summary.md b/docs/fr-fr/_summary.md new file mode 100644 index 00000000000..25a593b2ec2 --- /dev/null +++ b/docs/fr-fr/_summary.md @@ -0,0 +1,126 @@ +**En Français** + +* [Guide pour débutant complet](fr-fr/newbs.md) + * [Pour débuter](fr-fr/newbs_getting_started.md) + * [Compiler son premier firmware](fr-fr/newbs_building_firmware.md) + * [Flasher le Firmware](fr-fr/newbs_flashing.md) + * [Test et Débuggage](fr-fr/newbs_testing_debugging.md) + * [Bonnes pratiques Git](fr-fr/newbs_best_practices.md) + * [Ressources d'apprentissage](fr-fr/newbs_learn_more_resources.md) + +* [Les bases de QMK](fr-fr/README.md) + * [Indroduction à QMK](fr-fr/getting_started_introduction.md) + * [QMK CLI](fr-fr/cli.md) + * [Configuration de la CLI QMK](fr-fr/cli_configuration.md) + * [Contribuer à QMK](fr-fr/contributing.md) + * [Comment utiliser GitHub](fr-fr/getting_started_github.md) + * [Trouver de l'aide](fr-fr/getting_started_getting_help.md) + +* [Breaking changes](fr-fr/breaking_changes.md) + * [30 août 2019](fr-fr/ChangeLog/20190830.md) + +* [FAQ](fr-fr/faq.md) + * [FAQ Générale](fr-fr/faq_general.md) + * [Compiler QMK](fr-fr/faq_build.md) + * [Débugguer / Dépanner QMK](fr-fr/faq_debug.md) + * [Keymap / Disposition](fr-fr/faq_keymap.md) + * [Installer les drivers avec Zadig](fr-fr/driver_installation_zadig.md) + +**En Anglais** + +* Guides détaillés + * [Installation des outils de compilation](fr-fr/getting_started_build_tools.md) + * [Guide Vagrant](fr-fr/getting_started_vagrant.md) + * [Commandes de compilations](fr-fr/getting_started_make_guide.md) + * [Flasher les firmwares](fr-fr/flashing.md) + * [Personnaliser les fonctionnalités](fr-fr/custom_quantum_functions.md) + * [Aperçu des fonctionnalités des dispositions](fr-fr/keymap.md) + +* [Hardware](fr-fr/hardware.md) + * [Processeurs AVR](fr-fr/hardware_avr.md) + * [Pilotes / Drivers](fr-fr/hardware_drivers.md) + +* Réferences + * [Lignes de conduite des claviers](fr-fr/hardware_keyboard_guidelines.md) + * [Options de configurations](fr-fr/config_options.md) + * [Keycodes / Codes des caractères](fr-fr/keycodes.md) + * [Conventions de codage - C](fr-fr/coding_conventions_c.md) + * [Conventions de codage - Python](fr-fr/coding_conventions_python.md) + * [Meilleurs pratiques sur la documentation](fr-fr/documentation_best_practices.md) + * [Modèles de documentation](fr-fr/documentation_templates.md) + * [Glossaire](fr-fr/reference_glossary.md) + * [Tests unitaires](fr-fr/unit_testing.md) + * [Fonctions utiles](fr-fr/ref_functions.md) + * [Support de configuration](fr-fr/reference_configurator_support.md) + * [Format du fichier info.json](fr-fr/reference_info_json.md) + * [Développer la CLI en Python](fr-fr/cli_development.md) + +* [Fonctionnalités](fr-fr/features.md) + * [Keycodes basiques](fr-fr/keycodes_basic.md) + * [Touches utilisées avec Shift (US ANSI)](fr-fr/keycodes_us_ansi_shifted.md) + * [Keycodes quantiques](fr-fr/quantum_keycodes.md) + * [Keycodes avancés](fr-fr/feature_advanced_keycodes.md) + * [Fonctionnalités audio](fr-fr/feature_audio.md) + * [Majuscule automatique](fr-fr/feature_auto_shift.md) + * [Rétroéclairage](fr-fr/feature_backlight.md) + * [Bluetooth](fr-fr/feature_bluetooth.md) + * [Bootmagic](fr-fr/feature_bootmagic.md) + * [Combos](fr-fr/feature_combo.md) + * [Commande](fr-fr/feature_command.md) + * [API anti-rebond](fr-fr/feature_debounce_type.md) + * [DIP Switch](fr-fr/feature_dip_switch.md) + * [Macros dynamiques](fr-fr/feature_dynamic_macros.md) + * [Interrupteurs rotatifs](fr-fr/feature_encoders.md) + * [Grave Escape](fr-fr/feature_grave_esc.md) + * [Retour haptique](fr-fr/feature_haptic_feedback.md) + * [Contrôleur LCD HD44780](fr-fr/feature_hd44780.md) + * [Touche à verrou / Lock-key](fr-fr/feature_key_lock.md) + * [Dispositions / layouts](fr-fr/feature_layouts.md) + * [Touche leader](fr-fr/feature_leader_key.md) + * [Matrice LED](fr-fr/feature_led_matrix.md) + * [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/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) + * [Matrice RGB](fr-fr/feature_rgb_matrix.md) + * [Space Cadet](fr-fr/feature_space_cadet.md) + * [Claviers scindés / splittés](fr-fr/feature_split_keyboard.md) + * [Stenographie](fr-fr/feature_stenography.md) + * [Inversion des mains](fr-fr/feature_swap_hands.md) + * [Tap Dance](fr-fr/feature_tap_dance.md) + * [Terminale](fr-fr/feature_terminal.md) + * [Imprimante thermique](fr-fr/feature_thermal_printer.md) + * [Caractères unicodes](fr-fr/feature_unicode.md) + * [Dossier utilisateur](fr-fr/feature_userspace.md) + * [Velocikey](fr-fr/feature_velocikey.md) + +* Pour les makers et les bricoleurs + * [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 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) + +* Pour aller plus loin + * [Comment fonctionnent les claviers](fr-fr/how_keyboards_work.md) + * [Comprendre QMK](fr-fr/understanding_qmk.md) + +* Autres sujets + * [Utiliser Eclipse avec QMK](fr-fr/other_eclipse.md) + * [Utiliser VSCode avec QMK](fr-fr/other_vscode.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) + * [Définitions](fr-fr/internals_defines.md) + * [Input Callback Reg](fr-fr/internals_input_callback_reg.md) + * [Appareils Midi](fr-fr/internals_midi_device.md) + * [Installation d’un appareil Midi](fr-fr/internals_midi_device_setup_process.md) + * [Utilitaires Midi](fr-fr/internals_midi_util.md) + * [Fonctions Midi](fr-fr/internals_send_functions.md) + * [Outils Sysex](fr-fr/internals_sysex_tools.md) diff --git a/docs/fr-fr/breaking_changes.md b/docs/fr-fr/breaking_changes.md new file mode 100644 index 00000000000..2dbb26e5a5b --- /dev/null +++ b/docs/fr-fr/breaking_changes.md @@ -0,0 +1,107 @@ +# Breaking changes + +Ce document décrit le processus de QMK pour la gestion des breaking changes. Un breaking change est un changement qui modifie la manière dont QMK fonctionne introduisant des incompatibilités ou des comportements dangereux. Nous limitons ces changements afin que les utilisateurs n'aient pas peur de casser leurs keymaps en mettant à jour leur version de QMK. + +La période de breaking change est quand nous allons fusionner un PR qui change QMK d'une manière dangereuse ou inattendue. Il y a une période interne de test afin de nous assurer que les problèmes résiduels sont rares ou impossible à prévoir. + +## Qu'est-ce qui a été inclus dans des Breaking Changes précédents? + +* [30 août 2019](ChangeLog/20190830.md) + +## Quand va être le prochain Breaking Change? + +Le prochain Breaking Change est planifié pour le 29 novembre. + +### Dates importantes + +* [x] 21 septembre 2019 - `future` est créé. Il va être rebasé de manière hebdomadaire. +* [ ] 01 novembre 2019 - `future` fermé aux nouveaux PRs. +* [ ] 01 novembre 2019 - Appel aux testeurs. +* [ ] 27 novembre 2019 - `master` est bloqué, pas de PRs fusionnés. +* [ ] 29 novembre 2019 - `future` est fusionné dans `master`. +* [ ] 30 novembre 2019 - `master` est débloqué. Les PRs peuvent à nouveau être fusionnés. + +## Quels changements seront inclus? + +Pour voir une liste de candidats de breaking changes, vous pouvez regarder la liste des [labels `breaking_change`](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr). De nouveaux changements peuvent être ajoutés entre maintenant et lorsque `future` est fermée, et un PR avec ce label n'est pas garanti d'être fusionné. + +Si vous souhaitez que votre breaking change soit inclus dans ce tour, vous devez créer un PR avec le label `breaking_change` et faire en sorte qu'il soit accepté avant que `future` ne soit fermé. Une fois `future` fermé, aucun nouveau breaking change sera accepté. + +Critère d'acceptation: + +* Le PR est complété et prêt à fusionner +* Le PR a un ChangeLog + +# Checklists + +Cette section documente plusieurs processus que nous utilisons en lançant le processus de Breaking Change. + +## Rebase `future` de `master` + +Ceci est lancé chaque vendredi tant que `future` est ouvert. + +Processus: + +``` +cd qmk_firmware +git checkout master +git pull --ff-only +git checkout future +git rebase master +git push --force +``` + +## Créer la branche `future` + +Ceci est fait immédiatement après la fusion de la branche `future` précédente. + +* `qmk_firmware` git commands + * [ ] `git checkout master` + * [ ] `git pull --ff-only` + * [ ] `git checkout -b future` + * [ ] Modifie `readme.md` + * [ ] Ajoute un message en haut qui indique que c'est une branche de test. + * [ ] Ajoute un lien vers ce document + * [ ] `git commit -m 'Branch point for Breaking Change'` + * [ ] `git tag breakpoint___
` + * [ ] `git tag ` # Evite que le label point d'arrêt soit confondu par un incrément de version + * [ ] `git push origin future` + * [ ] `git push --tags` + +## 4 Semaines Avant la Fusion + +* `future` est maintenant fermé aux nouveaux PRs, seul des correctifs pour les PRs courants peuvent être mergés +* Envoi de l'appel aux testeurs + * [ ] Discord + * [ ] GitHub PR + * [ ] https://reddit.com/r/olkb + +## 1 Semaine Avant la Fusion + +* Annonce que master sera fermée entre <2 jours avant> à + * [ ] Discord + * [ ] GitHub PR + * [ ] https://reddit.com/r/olkb + +## 2 Jours Avant la Fusion + +* Annonce que master est fermé pour 2 jours + * [ ] Discord + * [ ] GitHub PR + * [ ] https://reddit.com/r/olkb + +## Jour de la fusion + +* `qmk_firmware` git commands + * [ ] `git checkout future` + * [ ] `git pull --ff-only` + * [ ] `git rebase origin/master` + * [ ] Modifie `readme.md` + * [ ] Supprimer les notes à propos de `future` + * [ ] Regroupe ChangeLog dans un fichier. + * [ ] `git commit -m 'Merge point for Breaking Change'` + * [ ] `git push origin future` +* 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/cli.md b/docs/fr-fr/cli.md new file mode 100644 index 00000000000..42815364582 --- /dev/null +++ b/docs/fr-fr/cli.md @@ -0,0 +1,146 @@ +# La CLI de QMK + +Cette page décrit comment configurer et utiliser la CLI QMK. + +# Vue d'ensemble + +La CLI de QMK permet de simplifier la compilation et l'interaction avec les claviers QMK. Nous avons défini plusieurs commandes pour simplifier et rationaliser les tâches telles qu'obtenir et compiler le firmware QMK, créer de nouvelles keymaps, et plus. + +* [CLI globale](#global-cli) +* [CLI locale](#local-cli) +* [Les commandes CLI](#cli-commands) + +# Pré-requis + +La CLI nécessite Python 3.5 ou plus récent. Nous essayons de limiter le nombre de pré-requis, mais vous allez aussi devoir installer les paquets listés dans le fichier [`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt). + +# CLI globale + +QMK met à disposition une CLI installable qui peut être utilisée pour configurer votre environnement de compilation QMK, fonctionne avec QMK, et qui rend l'utilisation de plusieurs copies de `qmk_firmware` plus simple. Nous recommandons d'installer et de mettre à jour ceci régulièrement. + +## Installer en utilisant Homebrew (macOS, quelques Linux) + +Si vous avez installé [Homebrew](https://brew.sh) vous pouvez entrer ce qui suit et installer QMK: + +``` +brew tap qmk/qmk +brew 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 +``` + +## Installer en utilisant easy_install ou pip + +Si votre système n'est pas listé ci-dessus, vous pouvez installer QMK manuellement. Premièrement, vérifiez que vous avez bien installé Python 3.5 (ou plus récent) et pip. Ensuite, installez QMK avec cette commande: + +``` +pip3 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 +``` + +## Paquets pour d'autres systèmes d'exploitation + +Nous recherchons des gens pour créer et maintenir un paquet `qmk` pour plus de systèmes d'exploitation. Si vous voulez créer un paquet pour votre système d'exploitation, suivez ces directives: + +* Suivez les bonnes pratiques pour votre système d'exploitation lorsqu'elles entrent en conflit avec ces directives + * Documentez pourquoi dans un commentaire lorsque vous ne les suivez pas +* Installez en utilisant un virtualenv +* Expliquez à l'utilisateur de définir la variable d'environnement `QMK_Home` pour "check out" les sources du firmware à un autre endroit que `~/qmk_firmware`. + +# CLI locale + +Si vous ne voulez pas utiliser la CLI globale, il y a une CLI locale empaquetée avec `qmk_firmware`. Vous pouvez le trouver dans `qmk_firmware/bin/qmk`. Vous pouvez lancer la commande `qmk` depuis n'importe quel répertoire et elle fonctionnera toujours sur cette copie de `qmk_firmware`. + +**Exemple**: + +``` +$ ~/qmk_firmware/bin/qmk hello +Ψ Hello, World! +``` + +## Limitations de la CLI locale + +Il y a quelques limitations à la CLI locale comparé à la globale: + +* La CLI locale ne supporte pas `qmk setup` ou `qmk clone` +* La CLI locale n'opère pas sur le même arbre `qmk_firmware`, même si vous avez plusieurs dépôts clonés. +* La CLI locale ne s'exécute pas dans un virtualenv, donc il y a des risques que des dépendances seront en conflit + +# Les commandes CLI + +## `qmk compile` + +Cette commande permet de compiler le firmware de n'importe quel répertoire. Vous pouvez compiler des exports JSON de ou compiler des keymaps du dépôt. + +**Utilisation pour les exports de configuration**: + +``` +qmk compile +``` + +**Utilisation pour les Keymaps**: + +``` +qmk compile -kb -km +``` + +## `qmk cformat` + +Cette commande formatte le code C en utilisant clang-format. Lancez-la sans arguments pour formatter tout le code core, ou passez les noms de fichiers à la ligne de commande pour la lancer sur des fichiers spécifiques. + +**Utilisation**: + +``` +qmk cformat [file1] [file2] [...] [fileN] +``` + +## `qmk config` + +Cette commande vous permet de configurer le comportement de QMK. Pour la documentation complète de `qmk config`, regardez [Configuration de CLI](cli_configuration.md). + +**Utilisation**: + +``` +qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN] +``` + +## `qmk doctor` + +Cette commande examine votre environnement et vous alertes des potentiels problèmes de compilation ou de flash. + +**Utilisation**: + +``` +qmk doctor +``` + +## `qmk new-keymap` + +Cette commande crée une nouvelle keymap basée sur une keymap par défaut d'un clavier existant. + +**Utilisation**: + +``` +qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] +``` + +## `qmk pyformat` + +Cette commande formate le code python dans `qmk_firmware`. + +**Utilisation**: + +``` +qmk pyformat +``` + +## `qmk pytest` + +Cette commande démarre la suite de test python. Si vous faites des changements dans le code Python, assurez-vous que les tests se lancent avec succès. + +**Utilisation**: + +``` +qmk pytest +``` diff --git a/docs/fr-fr/cli_configuration.md b/docs/fr-fr/cli_configuration.md new file mode 100644 index 00000000000..3eed1e0e950 --- /dev/null +++ b/docs/fr-fr/cli_configuration.md @@ -0,0 +1,121 @@ +# Configuration de QMK CLI + +Ce document explique comment fonctionne la commande `qmk config`. + +# Introduction + +La configuration pour QMK CLI est un système clé/valeur. Chaque clé est composée d'une sous-commande et d'un argument séparé par une virgule. Cela permet une traduction simple et directe entre les clés de configuration et l'argument qu'elle définit. + +## Exemple simple + +Comme exemple, regardons la commande `qmk compile --keyboard clueboard/66/rev4 --keymap default`. + +Il y a deux arguments de ligne de commande qui peuvent être lu de la configuration: + +* `compile.keyboard` +* `compile.keymap` + +Essayons de les définir: + +```shell +$ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default +compile.keyboard: None -> clueboard/66/rev4 +compile.keymap: None -> default +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +Maintenant, je peux lancer la commande `qmk compile` sans avoir à spécifier mon clavier et keymap à chaque fois. + +## Définir les options par défaut + +Parfois, il est utile de partager une configuration entre plusieurs commandes. Par exemple, plusieurs commandes prennent un argument `--keyboard`. Plutôt que de devoir définir cette valeur pour chaque commande, vous pouvez définir une valeur d'utilisateur qui sera utilisée par toutes les commandes qui prennent cet argument. + +Exemple: + +``` +$ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default +user.keyboard: None -> clueboard/66/rev4 +user.keymap: None -> default +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +# CLI Documentation (`qmk config`) + +La commande `qmk config` est utilisée pour interagir avec la configuration sous-jacente. Lancée sans argument, elle affiche la configuration courante. Lorsque des arguments sont définis, ils sont considérés comme étant des jetons de configuration, qui sont des chaînes de caractère ne contenant aucun espace avec le format suivant: + + [.][=] + +## Définir des valeurs de configuration + +Vous pouvez définir des valeurs de configuration en mettant le caractère égal (=) dans votre clé de configuration. La clé doit toujours être dans le format complet `
.`. + +Exemple: + +``` +$ qmk config default.keymap=default +default.keymap: None -> default +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +## Lire des valeurs de configuration + +Vous pouvez lire les valeurs de configuration pour la totalité de la configuration, une seule clé, ou une section entière. Vous pouvez aussi spécifier plusieurs clés pour afficher plus d'une valeur. + +### Exemple avec la totalité de la configuration + + qmk config + +### Exemple avec une section entière + + qmk config compile + +### Exemple avec une clé unique + + qmk config compile.keyboard + +### Exemple avec plusieurs clés + + qmk config user compile.keyboard compile.keymap + +## Supprimer des valeurs de configuration + +Vous pouvez supprimer une valeur de configuration en la définissant avec la chaîne spéciale `None`. + +Exemple: + +``` +$ qmk config default.keymap=None +default.keymap: default -> None +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +## Plusieurs opérations + +Vous pouvez combiner plusieurs opérations d'écriture et de lecture en une seule commande. Elles seront exécutées et affichées dans l'ordre: + +``` +$ qmk config compile default.keymap=default compile.keymap=None +compile.keymap=skully +compile.keyboard=clueboard/66_hotswap/gen1 +default.keymap: None -> default +compile.keymap: skully -> None +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +# Options de configuration utilisateur + +| Clé | Valeur par défaut | Description | +|-----|---------------|-------------| +| user.keyboard | None | Le chemin d'accès vers le clavier (Exemple: `clueboard/66/rev4`) | +| user.keymap | None | Le nom de la keymap (Exemple: `default`) | +| user.name | None | Le nom d'utilisateur GitHub de l'utilisateur. | + +# Toutes les options de configuration + +| Clé | Valeur par défaut | Description | +|-----|---------------|-------------| +| compile.keyboard | None | Le chemin d'accès vers le clavier (Exemple: `clueboard/66/rev4`) | +| compile.keymap | None | Le nom de la keymap (Exemple: `default`) | +| hello.name | None | Le nom à saluer lorsque démarré. | +| new_keyboard.keyboard | None | Le chemin d'accès vers le clavier (Exemple: `clueboard/66/rev4`) | +| new_keyboard.keymap | None | Le nom de la keymap (Example: `default`) | diff --git a/docs/fr-fr/contributing.md b/docs/fr-fr/contributing.md new file mode 100644 index 00000000000..0092d664efb --- /dev/null +++ b/docs/fr-fr/contributing.md @@ -0,0 +1,154 @@ +# Comment contribuer + +👍🎉 Premièrement, merci de prendre le temps de lire ceci et de contribuer! 🎉👍 + +Les contributions de tiers nous aide à améliorer et faire grandir QMK. Nous voulons rendre les pull requests et le processus de contribution utile et simple à la fois pour les contributeurs et les mainteneurs. C'est pourquoi nous avons mis en places des directives pour les contributeurs afin que votre pull request puisse être accepté sans changement majeur. + +* [Aperçu du projet](#project-overview) +* [Conventions de codage](#coding-conventions) +* [Directives générales](#general-guidelines) +* [Que veut dire le code de conduite pour moi?](#what-does-the-code-of-conduct-mean-for-me) + +## Je ne veux pas lire tout ce pavé! J'ai juste une question! + +Si vous voulez poser une question sur QMK, vous pouvez le faire sur le [sous-reddit OLKB](https://reddit.com/r/olkb) ou sur [Discord](https://discord.gg/Uq7gcHh). + +Merci de garder ceci en tête: + +* Cela peut prendre plusieurs heures pour que quelqu'un réponde à votre question. Merci d'être patient! +* Tous ceux impliqués avec QMK fait don de son temps et de son énergie. Nous ne sommes pas payés pour travailler sur ou répondre aux questions concernant QMK. +* Essayez de poser vos questions de manière à ce qu'elles soient le plus simple à répondre possible. Si vous n'êtes pas sûrs de savoir comment faire, voici quelques bon guides (en anglais): + * https://opensource.com/life/16/10/how-ask-technical-questions + * http://www.catb.org/esr/faqs/smart-questions.html + +# 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. + + + +# Où trouver de l'aide? + +Si vous avez besoin d'aide, vous pouvez [ouvrir une issue](https://github.com/qmk/qmk_firmware/issues) ou [un chat sur Discord](https://discord.gg/Uq7gcHh). + +# Comment contribuer? + +Vous n'avez encore jamais contribué à un projet open source? Vous vous demandez comment les contributions dans QMK fonctionnent? Voici un aperçu rapide! + +0. Enregistrez-vous sur [GitHub](https://github.com). +1. Définissez une keymap à contribuer, [trouvez une issue](https://github.com/qmk/qmk_firmware/issues) que vous souhaitez corriger, ou [une fonction](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature) que vous voulez ajouter. +2. Créez un fork sur le dépôt associé avec une issue sur votre compte GitHub. Cela veut dire que vous allez avoir une copie du dépôt sous `votre-login-GitHub/qmk_firmware`. +3. Clonez le dépôt sur votre machine locale en utilisant `git clone https://github.com/login-github/repository-name.git`. +4. Si vous travaillez sur une nouvelle fonctionnalité, pensez à ouvrir une issue pour parler avec nous du travail que vous souhaitez démarrer. +5. Créez une nouvelle branche pour votre correctif en utilisant `git checkout -b nom-de-branche`. +6. Faites les changements nécessaires pour corriger le problème ou ajouter la fonctionnalité. +7. Utilisez `git add chemin-de-fichier` pour ajouter les contenus des fichiers modifiés au "snapshot" que git utilise pour gérer l'état du projet, appelé aussi l'index. +8. Utilisez `git commit -m "Insérez une description courte des changements (en anglais)"` pour enregistrer le contenu de l'index avec un message descriptif. +9. Poussez les changements vers votre dépôt sur GitHub en utilisant `git push origin nom-de-branche`. +10. Créez un pull request sur [QMK Firmware](https://github.com/qmk/qmk_firmware/pull/new/master). +11. Donnez un titre à votre pull request en utilisant une description courte des changements que vous avez fait et ajoutez le numéro de l'issue ou du bug associé avec votre changement. Les commentaires de PR devraient se faire en anglais de préférence. Par exemple, vous pouvez utiliser un titre tel que celui-là: "Added more log outputting to resolve #4352". +12. Dans la description du pull request, expliquez les changements que vous avez fait et tous les problèmes qui existent, selon vous, sur le pull request que vous avez fait. Vous pouvez aussi utiliser la description pour poser des questions au mainteneur. Il n'est pas nécessaire que votre pull request soit parfait (aucun pull request ne l'est), le reviewer sera là pour vous aider à résoudre les problèmes et l'améliorer! +13. Attendez que le pull request soit revu par un mainteneur. +14. Faites des changements au pull request si le mainteneur le recommande. +15. Célébrez votre succès une fois votre pull request fusionné! + +# Conventions de codage + +La grande majorité de notre style est plutôt simple à comprendre. Si vous connaissez C ou Python, vous ne devriez pas avoir trop de difficulté avec notre style. + +* [Conventions de codage - C](coding_conventions_c.md) +* [Conventions de codage - Python](coding_conventions_python.md) + +# Directives générales + +Nous avons un certain nombre de type de changements dans QMK, chacun nécessitant un niveau de rigueur différent. Nous voulons que vous gardiez les directives suivantes en tête quel que soit le changement que vous êtes en train de faire. + +* Séparez les PR dans des unités logiques. Par exemple, ne soumettez pas un PR qui couvre deux fonctionnalités séparées, soumettez plutôt un PR pour chaque fonctionnalité. +* Vérifiez les espaces blancs non nécessaires avec `git diff --check` avant de commit. +* Assurez-vous que votre code compile. + * Keymaps: Assurez-vous que `make keyboard:your_new_keymap` ne renvoie pas d'erreur. + * Claviers: Assurez-vous que `make keyboard:all` ne renvoie pas d'erreur. + * Core: Assurez-vous que `make all` ne renvoie pas d'erreur. +* Assurez-vous que les messages de commit soient compréhensibles d'eux-mêmes. Vous devriez écrire une description simple (pas plus de 70 caractères) sur la première ligne, suivi d'une ligne vide, suivi d'un détail de votre commit, si nécessaire. Exemple: + +``` +Adjust the fronzlebop for the kerpleplork + +The kerpleplork was intermittently failing with error code 23. The root cause was the fronzlebop setting, which causes the kerpleplork to activate every N iterations. + +Limited experimentation on the devices I have available shows that 7 is high enough to avoid confusing the kerpleplork, but I'd like to get some feedback from people with ARM devices to be sure. +``` + +## Documentation + +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/. + +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: + +```c +enum my_layers { + _FIRST_LAYER, + _SECOND_LAYER +}; + +enum my_keycodes { + FIRST_LAYER = SAFE_RANGE, + SECOND_LAYER +}; +``` + +## Keymaps + +La plupart des contributeurs débutants démarrent avec leurs keymaps personnelles. Nous essayons de garder les standards pour les keymaps pluôt simple (les keymaps reflètent, après tout, la personnalité de leurs créateurs) mais nous demandons que vous suiviez les directives suivantes afin que d'autres puissent découvrir et apprendre de votre keymap. + +* Ecrivez un fichier `readme.md` en utilisant [la template](documentation_templates.md). +* Tous les PR de keymaps doivent être "squashés", donc si la manière dont vos commits sont squashés vous est important, vous devez le faire vous-même. +* Ne regroupez pas des fonctionnalités avec votre PR de keymap. Envoyez d'abord votre fonctionnalité, puis créez un second PR pour la keymap. +* N'incluez pas de fichier `Makefile` dans votre dossier de keymap (ils ne sont plus utilisés) +* Mettez à jour les copyrights dans les en-têtes de fichiers (cherchez `%YOUR_NAME%`) + +## Claviers + +Les claviers sont la raison d'être de QMK. Certains claviers sont maintenus par la communauté, alors que d'autre sont maintenus par les gens responsables de la création du clavier. Le fichier `readme.md` devrait vous informer de qui maintient le clavier. Si vous avez des questions concernant un clavier en particulier, vous pouvez [Ouvrir une issue](https://github.com/qmk/qmk_firmware/issues) et tagger le mainteneur dans votre question. + +Nous vous demandons aussi que vous suiviez ces directives: + +* Ecrivez un fichier `readme.md` en utilisant [le template](documentation_templates.md). +* Gardez un nombre de commits raisonnable, ou nous squasherons votre PR. +* Ne regroupez pas des fonctionnalités avec le PR pour votre clavier. Envoyez d'abord votre fonctionnalité, puis créez un second PR pour le clavier. +* Appelez les fichiers `.c`/`.h` du nom du dossier parent, par exemple `/keyboards///.[ch]` +* N'incluez pas de fichier `Makefile` dans votre dossier de keymap (ils ne sont plus utilisés) +* Mettez à jour les copyrights dans les en-têtes de fichiers (cherchez `%YOUR_NAME%`) + +## Quantum/TMK Core + +Faites attention d'être sûr d'implémenter votre nouvelle fonctionnalité de la meilleure manière qu'il soit avant d'investir beaucoup de travail à son développement. Vous pouvez apprendre les bases de QMK en lisant [Comprendre QMK](understanding_qmk.md), qui vous donnera une idée du flux du programme QMK. A partir de là, parlez nous afin de définir la meilleure façon d'implémenter votre idée. Il y a deux façons principale de le faire: + +* [Chat sur Discord](https://discord.gg/Uq7gcHh) +* [Ouvrir une Issue](https://github.com/qmk/qmk_firmware/issues/new) + +Les PR de nouvelles fonctionnalités de de correction de bug affectent tous les claviers. Nous sommes aussi dans un processus de restructuration de QMK. Pour cette raison, il est absolument nécessaire que tout changement important ou significatif soit discuté avant que l'implémentation soit faite. Si vous ouvrez un PR sans nous avoir parlé, préparez-vous à faire des refontes significatives si vos changements ne sont pas compatibles avec ce que nous avons planifié. + +Voici quelques choses à garder en tête lorsque vous travaillez sur une fonctionnalité ou un bug fix. + +* **Désactivé par défaut** - la mémoire est plutôt limitée sur la plupart des puces que QMK supporte, et il est important que les keymaps courantes ne soient pas cassées. S'il vous plaît faites que vos features doivent être **activées** plutôt que désactivées. Si vous pensez qu'elle devrait être activée par défaut, ou que cela réduit la taille du code, parlez-nous-en. +* **Compilez localement avant de soumettre** - Cela devrait aller sans dire, mais votre code doit compiler! Notre système Travis devrait relever les problèmes, mais il est généralement plus rapide de compiler quelques claviers en local plutôt que d'attendre le retour des résultats +* **Faites attention aux révisions et différentes bases de puces** - beaucoup de claviers ont des révisions qui permettent des changements de configuration mineurs, voir des bases de chip différentes. Essayez de faire que votre fonctionnalité soit supportée à la fois sur ARM et AVR, ou désactivez-là automatiquement sur les plateformes non supportées. +* **Expliquez votre fonctionnalité** - Documentez-là dans `docs/`, soit dans un nouveau fichier, ou dans une partie d'un fichier existant. Si vous ne la documentez pas, personne ne pourra bénéficier de votre dur labeur. + +Nous vous demandons aussi de suivre ces directives: + +* Gardez un nombre de commits raisonnable, ou nous squasherons votre PR. +* Ne regroupez pas des claviers ou des keymaps avec des changements core. Soumettez vos changements core en premier. +* Ecrivez des [Tests Unitaires](unit_testing.md) pour votre fonctionnalité. +* Suivez le style du fichier que vous modifiez. Si le style n'est pas clair ou qu'il y a un mélange de fichiers, vous devriez vous conformer aux [conventions de codage](#coding-conventions) au dessus. + +## Refactoriser + +Afin de maintenir une vision claire sur comment les choses sont architectuées dans QMK, nous essayons de planifier des refactorisations en profondeur et qu'un collaborateur fasse le changement. Si vous avez une idée de refactorisation, ou une suggestion, [ouvrez une issue] [open an issue](https://github.com/qmk/qmk_firmware/issues), nous adorons discuter de comment améliorer QMK. + +# Que veut dire le code de conduite pour moi? + +Note [Code De Conduite](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md) veut dire que vous avez la responsabilité de traiter tout le monde dans le projet avec respect et courtoisie, peu importe leur identité. Si vous êtes victime d'une attitude ou de commentaires inappropriés, tels que décrit dans notre Code de Conduite, nous sommes là pour vous et nous ferons de notre mieux pour nous assurer que le fautif soit réprimandé, tel que décrit dans notre code. diff --git a/docs/fr-fr/driver_installation_zadig.md b/docs/fr-fr/driver_installation_zadig.md new file mode 100644 index 00000000000..9e7d77b6dc4 --- /dev/null +++ b/docs/fr-fr/driver_installation_zadig.md @@ -0,0 +1,46 @@ +# Installation du driver du bootloader avec Zadig + +Vous n’aurez pas besoin de pilote particulier pour utiliser un clavier QMK. En effet, QMK se présente à l'ordinateur hôte comme un clavier HID standard et sera reconnu sans problème. Cependant vous aurez peut-être besoin d'un pilote pour flasher votre clavier avec Windows. En effet, quand vous redémarrerez votre clavier en mode bootloader, le périphérique que détectera Windows ne sera pas un clavier mais un périphérique bootloader. + +Il existe deux exceptions : le bootloader Caterina, qui se trouve en général sur les Pro Micros, et le bootloader Halfkay, livré avec les Teensy de PJRC. Ils apparaissent respectivement sous la forme d'un port série et d'un périphérique HID générique, ne nécessitant pas de pilote particulier. + +Nous vous recommandons d'utiliser l'utilitaire [Zadig](https://zadig.akeo.ie/). Si vous avez configuré votre environnement de développement avec Msys2 ou WSL, le script `qmk_install.sh` vous aura proposé l'installation des pilotes durant le processus. + +## Installation + +Passez votre clavier en mode bootloader, soit en appuyant sur le keycode `RESET` (qui peut se trouver dans un calque différent) ou en appuyant sur le bouton reset qui se trouve en général sous la board. Si votre clavier n'a aucune de ces options, essayez de le brancher en maintenant Escape ou Espace+`B` appuyés (voir la documentation de [Bootmagic](feature_bootmagic.md) pour plus de détails). Certaines boards utilisent [Command](feature_command.md) à la place de Bootmagic. Dans ce cas, vous pouvez entrer en mode bootloader en appuyant, à n'importe quel moment lorsque le clavier est branché, sur les combinaisons de touches Shift Gauche+Shift Droit+`B` ou Shift Gauche+Shift Droit+Escape. +Certains claviers ont des instructions spécifiques pour passer en mode bootloader. Par exemple, la touche [Bootmagic Lite]](feature_bootmagic.md#bootmagic-lite) (défaut : Échap) peut être sur une touche différente telle que Contrôle Gauche. La combinaison pour la Command (défaut : Shift Gauche+Shift Droit) peut être différente, par exemple Contrôle Gauche+Contrôle Droit. Référez-vous au fichier README de votre clavier. + +Pour mettre un clavier en mode bootloader avec USBaspLoader, appuyez sur le bouton `RESET` tout en maintenant le bouton `BOOT`. Vous pouvez aussi maintenir le bouton `BOOT` en branchant le câble USB. + +Zadig détectera automatiquement les périphériques en mode bootloader. Il se peut toutefois que vous deviez vérifier en passant par **Options → List All Devices**. + + + - Pour les claviers avec des MCUs Atmel AVR, le bootloader aura un nom similaire à `ATm32U4DFU`, et un Vendor ID `03EB`. + - Les bootloaders USBasp s'appelleront `USBasp`, avec un VID/PID `16C0:05DC`. + - Les claviers AVR flashé avec le bootloader QMK-DFU s'appelleront ` Bootloader` et auront aussi le VID `03EB`. + - Pour la plupart des claviers ARM, ils s'appelleront `STM32 BOOTLOADER`, et auront un VID/PID `0483:DF11`. + +!> Si Zadig affiche certains de vos périphériques avec le driver `HidUsb`, votre clavier n'est probablement pas en mode bootloader. La flèche aura une couleur orange et vous aurez un message de confirmation vous demandant de modifier un pilote système. **Ne continuez pas!** + +Si la flèche apparaît en vert, sélectionnez le driver et appuyez sur le bouton **Install Driver**. Le driver `libusb-win32` devrait normalement fonctionner pour AVR, et `WinUSB` pour ARM. Si vous avez des problèmes pour flasher la board, essayez d'installer un pilote différent de la liste. Pour flasher un périphérique USBaspLoader en ligne de commande avec msys2, le driver `libusbk` est recommandé, sinon `libusb-win32` devrait fonctionner correctement si vous utilisez QMK Toolbox pour flasher. + +![Zadig montrant un driver de bootloader installé correctement](https://i.imgur.com/b8VgXzx.png) + +Finalement, débranchez et rebranchez le clavier afin de vous assurer que le nouveau pilote a bien été chargé. Si vous utilisez QMK Toolbox pour flasher, redémarrez-le aussi, il arrive qu'il n'arrive pas à détecter le changement de driver. + +## Récupérer l'installation du mauvais périphérique + +Si vous n'arrivez plus à saisir de texte avec le clavier, il est possible que vous ayez installé le driver sur le clavier au lieu du bootloader. Vous pouvez facilement vérifier ceci dans Zadig. Un clavier fonctionnel a le pilote `HidUsb` installé sur toutes ses interfaces : + +![Un clavier fonctionnel vu par Zadig](https://i.imgur.com/Hx0E5kC.png) + +Ouvrez le Gestionnaire de périphériques et cherchez un périphérique qui ressemble à votre clavier. + +![La board avec le mauvais driver installé, dans le Gestionnaire de périphériques](https://i.imgur.com/L3wvX8f.png) + +Cliquez dessus avec le bouton droit et sélectionner **Désinstaller le périphérique**. Faites bien attention à sélectionner **Supprimer le pilote pour ce périphérique** avant de valider. + +![Le dialogue Suppression de périphérique, avec la boîte "suppression de pilote" cochée](https://i.imgur.com/aEs2RuA.png) + +Appuyez sur **Action → Analyser les changements de hardware**. A ce stade, vous devriez pouvoir saisir à nouveau. Vérifiez dans Zadig que les périphériques utilisent bien le pilote `HidUsb`. Si c'est le cas, vous avez corrigé le problème, votre clavier devrait fonctionner à nouveau ! diff --git a/docs/fr-fr/faq.md b/docs/fr-fr/faq.md new file mode 100644 index 00000000000..89576b3cc28 --- /dev/null +++ b/docs/fr-fr/faq.md @@ -0,0 +1,6 @@ +# Foire Aux Questions + +* [FAQ Générale](faq_general.md) +* [Construire ou Compiler QMK](faq_build.md) +* [Débuguer et Dépanner QMK](faq_debug.md) +* [Keymap (disposition)](faq_keymap.md) diff --git a/docs/fr-fr/faq_build.md b/docs/fr-fr/faq_build.md new file mode 100644 index 00000000000..84d88afcd8b --- /dev/null +++ b/docs/fr-fr/faq_build.md @@ -0,0 +1,154 @@ +# Foire aux questions sur la compilation + +Cette page couvre les questions concernant la compilation de QMK. Si vous ne l'avez pas encore fait, vous devriez lire les guides [Configuration de l'environnement de build](getting_started_build_tools.md) et [Instructions pour Make](getting_started_make_guide.md). + +## Je ne peux pas programmer sous Linux + +Vous aurez besoin des permissions appropriées pour utiliser un périphérique. Pour les utilisateurs de Linux, référez-vous aux instructions concernant les règles `udev` ci-dessous. Si `udev` vous pose des problèmes, une alternative est d'utiliser la commande `sudo`. Si vous ne connaissez pas cette commande, référez-vous à son manuel d'utilisation en utilisant `man sudo` ou [regardez cette page](https://linux.die.net/man/8/sudo). + +Un exemple utilisant `sudo`, lorsque votre contrôleur est un ATMega32u4 : + + $ sudo dfu-programmer atmega32u4 erase --force + $ sudo dfu-programmer atmega32u4 flash your.hex + $ sudo dfu-programmer atmega32u4 reset + +ou simplement : + + $ sudo make ::dfu + +Veuillez noter que lancer `make` avec `sudo` est généralement une **mauvaise** idée, et vous devriez préférer une des méthodes précédente, si possible. + +### Règles `udev` pour Linux + +Sous Linux, vous aurez besoin des permissions appropriées pour accéder au MCU (le micro-contrôleur). Vous avez le choix d'utiliser `sudo` en flashant le firmware, ou placer ces fichiers dans `/etc/udev/rules.d`. Une fois ajouté, lancez les commandes suivantes : + +```console +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:** + +``` +# Input Club keyboard bootloader +SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666" +``` + +**/etc/udev/rules.d/55-catalina.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:** Le filtrage utilisant ModemManager fonctionnera uniquement si vous n'êtes pas en mode strict. Les commandes suivantes peuvent changer cette option : + +```console +sudo sed -i 's/--filter-policy=strict/--filter-policy=default/' /lib/systemd/system/ModemManager.service +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" +``` + +### Le périphérique sériel n'est pas détecté en mode bootloader sous Linux + +Assurez-vous que votre kernel ait un support approprié pour votre périphérique. Si votre périphérique utilise USB ACM, par exemple pour les Pro Micro (AtMega32u4), assurez-vous d'inclure `CONFIG_USB_ACM=y`. D'autres périphériques peuvent avoir besoin de `USB_SERIAL` et de ses sous-options. + +## Périphérique inconnu pour le bootloader DFU + +Les problèmes rencontrés lorsque l'on flash des claviers sous Windows sont, la plupart du temps, dus à une installation du mauvais pilote, ou un pilote manquant. + +Relancer le script d'installation de QMK (`./util/qmk_install.sh` situé dans répertoire `qmk_firmware`sous MSYS2 ou WSL) ou réinstaller la QMK Toolbox peut résoudre le problème. Une alternative est de télécharger et lancer manuellement le package [`qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer). + +Si vous rencontrez toujours des problèmes, essayez de télécharger et lancer Zadig. Voir [Installation du driver du bootloader avec Zadig](driver_installation_zadig.md) pour plus d'informations. + +## USB VID et PID + +Vous pouvez utiliser l'ID de votre choix en modifier `config.h`. Il y a peu de chance de conflit avec d'autres produits. + +La plupart des boards QMK utilisent `0xFEED` comme vendor ID. Vérifiez les autres claviers pour être sûr de choisir un Product ID unique. + +Étudiez aussi ce ticket +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 + +## BOOTLOADER_SIZE pour AVR + +Notez que la taille du bootloader pour les Teensy2.0++ est de 2048bytes. Quelques Makefiles peuvent contenir une erreur et avoir le mauvais commentaire. + +``` +# 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)` sous MacOS + +C'est un problème de mise à jour avec brew, causée par des liens symboliques (symlinks) dont dépend avr-gcc qui sont détruits. + +La solution est de supprimer et réinstaller tous les modules affectés. + +``` +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 et LUFA + +Si vous avez mis à jour votre avr-gcc au-dessus de la version 7, vous risquez de voir des erreurs impliquant LUA. Par exemple : + +`lib/lufa/LUFA/Drivers/USB/Class/Device/AudioClassDevice.h:380:5: error: 'const' attribute on function returning 'void'` + +Pour le moment, vous devrez revenir à la version 7 de avr-gcc dans brew. + +``` +brew uninstall --force avr-gcc +brew install avr-gcc@8 +brew link --force avr-gcc@8 +``` + +### Je viens de flasher mon clavier et il ne fait rien/l'appui des touches n'est pas enregistré - c'est aussi un ARM(rev6 plank, clueboard 60, hs60v2, etc.) (Février 2019) + +A cause de la manière dont les EEPROM fonctionnent sur les puces ARM, les options sauvegardées peuvent ne plus être valides. Ceci affecte les calques par défaut et *peut*, sous certaines conditions que nous essayons encore de déterminer, rendre le clavier inutilisable. Réinitialiser l'EEPROM corrigera le problème. + +[Réinitialiser EEPROM sur Planck rev6](https://cdn.discordapp.com/attachments/473506116718952450/539284620861243409/planck_rev6_default.bin) peut être utilisé pour forcer une réinitialisation d'EEPROM. Une fois cette image flashée, flashez à nouveau votre firmware standard. Cela devrait rétablir le fonctionnement de votre clavier. +Si bootmagic est activé dans n'importe quel forme, vous devriez être capable de faire aussi ceci (regardez [Documentation Bootmagic](feature_bootmagic.md) et les informations spécifiques à votre clavier). diff --git a/docs/fr-fr/faq_debug.md b/docs/fr-fr/faq_debug.md new file mode 100644 index 00000000000..9c12f2917a0 --- /dev/null +++ b/docs/fr-fr/faq_debug.md @@ -0,0 +1,157 @@ +# FAQ Débugage + +Cette page détaille diverses questions fréquemment posées par les utilisateurs sur le dépannage de leurs claviers. + +# Console de débugage + +## `hid_listen` ne reconnaît pas de périphérique + +Lorsque la console de débugage sur votre périphérique n'est pas prêt, vous obtiendrez un message similaire : + +``` +Waiting for device:......... +``` + +Une fois le périphérique connecté, *hid_listen* le trouve et vous obtiendrez ce message : + +``` +Waiting for new device:......................... +Listening: +``` + +Si vous ne recevez pas ce message `Listening:`, essayez de compiler avec `CONSOLE_ENABLE=yes` dans le [Makefile] + +Il se peut que vous ayez besoin de certains privilèges avancés pour accéder à des périphériques sur des OS comme Linux. + +- Essayez `sudo hid_listen` + +## Ne reçoit pas de messages sur la console + +Vérifiez : + +- *hid_listen* trouve votre périphérique. Voir ci-dessus. +- Activez le débugage en appuyant sur **Magic**+d. Voir [Commandes Magic](https://github.com/tmk/tmk_keyboard#magic-commands). +- Définissez `debug_enable=true` en général dans `matrix_init()` du fichier **matrix.c**. +- Essayez d'utiliser la fonction `print` à la place du debug print. Voir **common/print.h**. +- Déconnectez tous les autres périphériques qui utilisent la fonction console. Voir [Issue #97](https://github.com/tmk/tmk_keyboard/issues/97). + +## Linux ou les systèmes UNIX nécessitent des privilèges super utilisateur + +Utilisez `sudo` pour exécuter *hid_listen* avec des privilèges étendus. + +``` +$ sudo hid_listen +``` + +Ou ajoutez une *udev rule* pour les périphériques TMK en plaçant un fichier dans le répertoire rules. Le chemin vers ce répertoire peut varier en fonction du système. + +Fichier: /etc/udev/rules.d/52-tmk-keyboard.rules(sous Ubuntu) +``` +# tmk keyboard products https://github.com/tmk/tmk_keyboard +SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666" +``` + +*** + +# Divers + +## Considérations de sécurité + +Vous ne voulez probablement pas "briquer" votre clavier, rendre impossible d'écrire un firmware dessus. Il y a quelques paramètres qui montrent ce qui est (et n'est probablement pas) trop risqué. + +- Si votre map de clavier n'inclut pas de RESET, pour entrer en mode DFU, vous devrez appuyer sur le bouton reset du PCB. Cela implique que vous devrez certainement dévisser certaines pièces de votre clavier pour y accéder. +- Modifier les fichiers tmk_core / common peut rendre le clavier inutilisable +- Si un fichier .hex trop large est la cause du problème : `make dfu` supprime le bloc puis teste la taille (il ne fait pas les choses dans le bon ordre), ce qui provoque une erreur. En résultat, le flash n’aura pas été fait et le clavier restera en mode DFU. +- Pour finir, notez que la taille maximale d'un fichier .hex sur un Plank est de 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 +``` + +- La taille du fichier ci-dessus est de 22396/577ch, ce qui est en dessous de 28672/7000h +- Tant que vous avez un fichier .hex alternatif correct, vous pouvez réessayer en le chargeant +- Certaines options que vous pouvez spécifier dans votre Makefile consomme de la mémoire supplémentaire. Faites attention aux options BOOTMAGIC_ENABLE, MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE. +- Les outils DFU **ne** vous permettent **pas** d'écrire dans le bootloader (à moins que vous n'ajoutiez des options spéciales), il n'y a donc peu de risque. +- Les EEPROM ont environ 100000 cycles d'écriture. Ne réécrivez pas le firmware de manière continue et répétée. Vous allez détruire définitivement l'EEPROM. + +## NKRO ne fonctionne pas + +Premièrement, vous devez compiler le firmware avec l'option de compilation `NKRO_ENABLE` dans le **Makefile**. + +Essayez la commande `Magic` **N** (`LShift+RShift+N` par défaut) si **NKRO** ne fonctionne toujours pas. Vous pouvez utiliser cette commande pour basculer temporairement entre le mode **NKRO** et **6KRO**. Sous certaines conditions, **NKRO** ne fonctionnera pas et vous devrez basculer en **6KRO**, en particulier lorsque vous êtes dans le BIOS. + +Si votre firmware est compilé avec `BOOTMAGIC_ENABLE` vous devrez l'activer avec la commande `BootMagic` **N** (`Espace+N` par défaut). Cette option est enregistrée dans l'EEPROM et sera gardé entre deux cycles de démarrage. + +https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch + +## Le TrackPoint a besoin Circuit de réinitialisation (Support de souris PS/2) + +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 + +## Impossible de lire la colonne de la matrice après 16 + +Utilisez `1UL<<16` à la place de `1<<16` dans `read_cols()` du fichier [matrix.h] lorsque le nombre de vos colonnes dépassent 16. + +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 + +## Les touches spéciales ne fonctionnent pas (Touche Système, Touches de contrôle du son) + +Vous devez définir `EXTRAKEY_ENABLE` dans le fichier `rules.mk` pour les utiliser dans QMK. + +``` +EXTRAKEY_ENABLE = yes # Audio control and System control +``` + +## Réveiller du mode veille ne fonctionne pas + +Sous Windows, activez l'option `Permettre au périphérique de sortir l'ordinateur de veille` dans les paramètres des **Options d'alimentations** du **Gestionnaire de périphériques**. Vérifiez aussi les paramètres du BIOS. + +Appuyer sur n'importe quelle touche en mode veille devrait sortir l'ordinateur de veille. + +## Vous utilisez un Arduino ? + +**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 + +Les Arduino Leonardo et micro ont des **ATMega32U4** et peuvent être utilisés avec TMK, mais le bootloader Arduino peut causer des problèmes. + +## Activer JTAG + +Par défaut, le débugage des interfaces JTAG est désactivé dès que le clavier démarre. Les MCUs compatible JTAG viennent d'usine avec le fusible `JTAGEN` activé, et il prend certaines pins du MCU que la board pourrait utiliser pour la matrice, les LEDs, etc. + +Si vous voulez garder JTAG activé, ajoutez la ligne suivante à votre fichier `config.h` : + +```c +#define NO_JTAG_DISABLE +``` + +## Compatibilité USB 3 + +Il semble que certaines personnes ont eu des problèmes avec les ports USB 3, essayez un port USB 2. + +## Compatibilité Mac + +### OS X 10.11 et Hub + +https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034 + +## Problème sur BIOS (UEFI) / Resume (Mise en veille et réveil) / Redémarrage + +Certaines personnes ont eu des problèmes de fonctionnement de leur clavier dans le BIOS et/ou après des redémarrages. + +Pour le moment, l'origine du problème n'est pas comprise, mais certaines options de compilation semble liées. Dans le Makefile, essayez de désactiver les options comme `CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE` et/ou d'autres. + +https://github.com/tmk/tmk_keyboard/issues/266 +https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778 diff --git a/docs/fr-fr/faq_general.md b/docs/fr-fr/faq_general.md new file mode 100644 index 00000000000..b1eae6df166 --- /dev/null +++ b/docs/fr-fr/faq_general.md @@ -0,0 +1,16 @@ +# Questions fréquemment posées + +## Qu'est-ce que QMK ? + +[QMK](https://github.com/qmk), acronyme pour Quantum Mechanical Keyboard, est un groupe de personnes qui construisent des outils pour des claviers personnalisés. Nous avons commencé par le [firmware QMK](https://github.com/qmk/qmk_firmware), un fork très modifié du firmware [TMK](https://github.com/tmk/tmk_keyboard). + +## Quelles sont les différences entre QMK et TMK ? + +TMK a été conçu et développé à l'origine par [Jun Wako](https://github.com/tmk). QMK a démarré comme étant le fork de [Jack Humbert](https://github.com/jackhumbert) pour le Planck. Au bout d'un moment, le fork de Jack a divergé de manière significative de TMK et, en 2015, Jack a décidé de le renommer QMK. + +D'un point de vue technique, QMK se base sur TMK en lui ajoutant plusieurs nouvelles fonctionnalités. +QMK a notamment augmenté le nombre de keycodes disponibles et les a utilisé pour implémenter des fonctionnalités avancées telles que `S()`, `LCTL()` et `MO()`. Vous pouvez voir une liste complète de ces keycodes dans [Keycodes] (keycodes.md). + +D'un point de vue management de projet et communauté, Hasu, sur TMK maintient tous les claviers supportés officiellement par lui-même, avec un peu de support de la communauté. Il existe ou peuvent être créées d'autres communautés maintenant des fork pour d'autres claviers. Peu de keymaps sont définies par défaut, les utilisateurs ne se partagent donc pas leurs keymaps en général. QMK encourage le partage des claviers et des keymaps à l'aide d'un dépôt géré de manière centrale, acceptant les pull requests qui suivent les standards de qualité. Ceux-ci sont surtout maitenus par la communauté, mais l'équipe de QMK aide aussi lorsque c'est nécessaire. + +Les deux approches ont leurs avantages et leurs inconvénients, et le développements de fonctionnalités intéressantes sont partagées entre TMK et QMK lorsque fait sens. diff --git a/docs/fr-fr/faq_keymap.md b/docs/fr-fr/faq_keymap.md new file mode 100644 index 00000000000..2cbbe930829 --- /dev/null +++ b/docs/fr-fr/faq_keymap.md @@ -0,0 +1,161 @@ +# FAQ Keymap + +Cette page couvre les questions souvent posées à propos des keymaps. Si vous ne l'avez pas encore fait, vous devriez commencer par là [Aperçu des Keymap](keymap.md). + +## Quels Keycodes puis-je utiliser ? + +Regardez [Keycodes](keycodes.md) pour une liste des keycodes disponibles. Certains keycodes spécifiques ont des documentations plus complètes de disponible. + +Les keycodes sont définies dans [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h). + +## Quels sont les keycodes par défaut ? + +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 + +QMK possède deux fonctionnalités, Bootmagic et Command, qui vous permettent de modifier le comportement de votre clavier à la volée. Cela inclut, sans toutefois s'y limiter, l'échange de Ctrl / Majuscules, la désactivation de l'interface graphique, le basculement de Alt/Gui, le basculement de barre d'espacement arrière/barre oblique inversée, la désactivation de toutes les touches et d'autres modifications comportementales. + +Pour résoudre rapidement le problème, essayez de maintenir les touches Espace + Retour arrière enfoncées pendant que vous branchez votre clavier. Cela réinitialisera les paramètres stockés sur votre clavier, ramenant ces touches à un fonctionnement normal. Si cela ne fonctionne pas, regardez ici: + +* [Bootmagic](feature_bootmagic.md) +* [Command](feature_command.md) + +## La touche de menu ne fonctionne pas + +La touche trouvée sur la plupart des claviers modernes située entre `KC_RGUI` et` KC_RCTL` est en réalité appelée `KC_APP`. En effet, lorsque cette touche a été inventée, il existait déjà une clé nommée `MENU` dans les normes correspondantes. MS a donc choisi de l'appeler la touche` APP`. + +## `KC_SYSREQ` ne fonctionne pas + +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 + +## Les touches alimentation ne fonctionnent pas + +Un peu déroutant, il y a deux codes de touche "Alimentation" dans QMK: `KC_POWER` dans la page d'utilisation du clavier / keypad, et `KC_SYSTEM_POWER` (ou `KC_PWR`) dans la page Consumer. + +Le premier n'est reconnu que sur macOS, alors que le dernier, `KC_SLEP` et `KC_WAKE` sont supportés par les trois principaux systèmes d'exploitation. Il est donc recommandé de les utiliser à la place. Sous Windows, ces touches prennent effet immédiatement, mais sur macOS, elles doivent être maintenues enfoncées jusqu'à ce qu'une boîte de dialogue apparaisse. + +## Modificateur "One Shot" + +Cette fonctionnalité permet de corriger un problème avec la touche Shift. En effet, il arrive de saisir plusieurs majuscules en ne voulant en saisir qu'une sur un mot. Ex : `CEtte` à la place de `Cette`. La fonctionnalité « One shot » shift permet de corriger ça. + +https://github.com/tmk/tmk_keyboard/issues/67 + +## Le modificateur d'un calque reste bloqué + +Les touches de modification ou les calques peuvent être bloquées si la commutation de calque n'est pas configurée correctement. +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://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` : + +``` +#define LOCKING_SUPPORT_ENABLE +#define LOCKING_RESYNC_ENABLE +``` + +Une fois la fonction activée, utilisez les keycodes `KC_LCAP`, `KC_LNUM` et `KC_LSCR` dans votre keymap. + +Des vieux claviers mécaniques ont parfois des touches à verrouillage, mais les claviers modernes n'en sont pas équipés. ***Vous n'avez pas besoin de cette fonction dans la majorité des cas et devez utiliser les keycodes `KC_CAPS`, `KC_NLCK` et `KC_SLCK`.*** + +## Ajouter des caractères spéciaux autres que ASCII comme la cédille 'Ç' + +Voir la fonctionnalité [Unicode](feature_unicode.md). + +## Touche `Fn` sur macOS + +Contrairement à la plupart des touches Fn, celle des claviers Apple a son propre code d'activation... en quelque sorte. Il remplace le sixième code d'activation dans un rapport de base 6KRO HID - de sorte qu'un clavier Apple ne contient en réalité que 5KRO. + +Il est techniquement possible de demander à QMK d’envoyer ce keycode. Cependant, cela nécessite une modification du format du rapport pour ajouter l'état de la touche Fn. +Pire encore, ce keycode n'est reconnu que si les identifiants du clavier VID et PID correspondent à ceux d'un vrai clavier Apple. Malheureusement QMK ne peut juridiquement prendre en charge cette fonctionnalité et il y a peu de chance que la situation s'améliore. + +Voir [cette issue](https://github.com/qmk/qmk_firmware/issues/2179) pour des informations détaillées. + +## Touches Media sous Mac OSX + +#### KC_MNXT et KC_MPRV ne fonctionnent pas sous Mac + +Utilisez `KC_MFFD`(`KC_MEDIA_FAST_FORWARD`) et `KC_MRWD`(`KC_MEDIA_REWIND`) à la place de `KC_MNXT` et `KC_MPRV`. +Voir https://github.com/tmk/tmk_keyboard/issues/195 + +## Touches supportées sous Mac OSX? + +Vous pouvez connaître les keycodes supportés par OSX en lisant ce code source. + +`usb_2_adb_keymap` contient les tableaux des pages Keyboard/Keypad vers les scancodes ADB (keycodes interne à OSX). + +https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c + +Et `IOHIDConsumer::dispatchConsumerEvent` s'occupe des utilisations Consumer page. + +https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp + +## Touches JIS dans Mac OSX + +Les touches de clavier spécifiques JIS comme `無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)` ne sont pas reconnues par OSX. Vous pouvez utiliser **Seil** pour les activer, esssayez les options suivantes. + +* Activer la touche NFER sur clavier PC +* Activer la touche XFER sur clavier PC +* Activer la touche KATAKANA sur clavier PC + +https://pqrs.org/osx/karabiner/seil.html + +## RN-42 Bluetooth ne fonctionne pas avec Karabiner + +Karabiner - Outil de Keymapping sous Mac OSX - Ignore les entrées du module RN-42. Vous devez activer cette option pour rendre Karabiner compatible avec votre clavier. +https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237 + +Plus de détails sur ce problème sur les liens suivants. +https://github.com/tmk/tmk_keyboard/issues/213 +https://github.com/tekezo/Karabiner/issues/403 + +## Esc et ` sur une touche simple. + +Cette fonctionnalité permet d'utiliser une touche à la fois comme touche Échap ou une touche `§` (En Azerty) selon le cas d’utilisation. Cela est très utile sur un clavier de petite taille. + +Voir la fonctionnalité [Grave Escape](feature_grave_esc.md). + +## Eject sur Mac OSX + +Le keycode`KC_EJCT` fonctionne sous OSX. https://github.com/tmk/tmk_keyboard/issues/250 + +Il semble que Windows 10 ignore le code et Linux/Xorg le reconnaît mais n'a pas de mapping par défaut. + +Nous ne sommes pas sûr quel keycode est utilisé pour la touche Eject sur les claviers Apple officiels. HHKB utilise `F20` pour la touche Eject (`Fn+f`) lorsqu'il est en mode Mac, mais ce n'est probablement pas la même chose que le keycode Eject d'Apple. + +## Qu'est-ce que `weak_mods` et `real_mods` dans `action_util.c` + +___TO BE IMPROVED___ + +real_mods est prévu pour retenir l'état des touches modificateur réelles/physiques, alors que weak_mods ne retient l'état que des modificateurs temporaires ou virtuels qui ne devraient pas affecter l'état des touches modificaterus réelles. + +Par exemple, disons que vous maintenez la touche physique "shift gauche" et tapez ACTION_MODS_KEY(LSHIFT, KC_A), + +en weak_mods, + +* (1) maintenir shift gauche : real_mods |= MOD_BIT(LSHIFT) +* (2) appuyer ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT) +* (3) lâcher ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods &= ~MOD_BIT(LSHIFT) +real_mods garde sur état modificateur. + +sans weak_mods, + +* (1) maintenir shift gauche : real_mods |= MOD_BIT(LSHIFT) +* (2) appuyer ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT) +* (3) lâcher ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT) +ici real_mods a perdu son état pour 'shift gauche physique'. + +weak_mods est ORed avec real_mods lorsque le rapport du clavier est envoyé. +https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57 diff --git a/docs/fr-fr/flashing.md b/docs/fr-fr/flashing.md new file mode 100644 index 00000000000..74eae497799 --- /dev/null +++ b/docs/fr-fr/flashing.md @@ -0,0 +1,238 @@ +# Instructions pour flasher et informations sur les bootloader + +Les claviers utilisent différents types de bootloaders et certains doivent être flashés différement. Heureusement, certains projets comme la [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) ont pour objectifs de permettre de flasher les différents bootloader sans trop se faire de soucis et ça peu importe les manières de les flasher. + +Si vous avez un bootloader sélectionné avec la variable `BOOTLOADER` dans votre fichier `rules.mk` alors QMK vas automatiquement calculer si votre fichier .hex n'est pas trop grand pour être flashé sur votre appareil, et il affichera la taille finale du firmware. Pour vérifier la taille manuellement, vous pouvez aussi compiler le firmware avec l'option `check-size`. Exemple : `make planck/rev4:default:check-size`. + +## DFU + +Le bootloader pour les processeurs Atmel DFU est fourni par défaut sur tous les processeurs atmega32u4. Celui-ci est utilisé par beaucoup de claviers plus vieux que les OLKB et Clueboard qui ont leur propre ICs sur leurs PCBs. D'autres claviers utilisent le bootloader DFU de LUFA (ou son fork QMK), notamment les nouveaux claviers OLKB. Ce dernier ajoute des fonctionnalités spécifiques sur le matériel. + +Pour vérifier la compatibilité avec le bootloader DFU, vérifiez que ce bloc de code est présent dans votre fichier `rules.mk`. Parfois il peut être inscrit `lufa-dfu` ou `qmk-dfu` à la place. + +```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 +``` + +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é) + +Ordre des actions : + +1. Pressez le keycode `RESET`, ou appuyez sur le bouton physique RESET ou alors créez un contact entre RST et GND. +2. Attendez que l'OS detecte l'appareil. +3. Éffacez la mémoire, cela peut être fait automatiquement. +4. Flasher le fichier .hex. +5. Redémarrez l'appareil en mode « application », cela peut être fait automatiquement. + +Alternativement : + + make ::dfu + +### DFU QMK + +QMK a un fork du bootloader LUFA DFU qui vous permet de faire un simple scan de la matrice pour quitter le bootloader et retourner à l'application. En même temps que le flash se produira, il est possible de faire flasher un led ou de produire un son via un haut parleur. Pour activer ces fonctionnalités, vous pouvez utiliser ce bloc dans votre fichier `config.h` (La touche permettant de quitter le bootloader a besoin d'être reliée entre les ports définis en INPUT et OUTPUT ici): + + #define QMK_ESC_OUTPUT F1 // usually COL + #define QMK_ESC_INPUT D5 // usually ROW + #define QMK_LED E6 + #define QMK_SPEAKER C6 + +Le fabricant et le nom du produit proviennent de vos définitions dans fichier `config.h`, et la chaîne de caractère « bootloader » est ajoutée au nom du produit. + +Pour génerer le bootloader, utilisez la cible `bootloader`. Exemple : `make planck/rev4:default:bootloader`. + +Pour génerer un fichier .hex prêt pour la production qui contiendra tant l'application que le bootloader, utilisez la cible `production`. Exemple : `make planck/rev4:default:production`. + +### Commandes DFU + +Il y a plusieurs commandes DFU que vous pouvez utiliser pour flasher le firmware sur un appareil DFU. + +* `:dfu` - C'est l'option normale qui attend qu'un appareil DFU soit disponible et qui flashe le firmware dès que c'est le cas. La vérification sera faite toutes les 5 secondes. +* `:dfu-ee` - Cette option flash un fichier `.eep` à la place d'un fichier `.hex`. Ce cas est plutôt rare. +* `:dfu-split-left` - Cette option flashe le firmware normal comme avec l'option (`:dfu`). Mais cela aussi flash le coté gauche du fichier EEPROM pour les claviers scindés. _C'est l'option idéale pour un clavier scindé basé sur le Elite C_ +* `:dfu-split-right` - Cette option flashe le firmware normal comme avec l'option (`:dfu`). Mais cela aussi flash le coté droite du fichier EEPROM pour les claviers scindés. _C'est l'option idéale pour un clavier scindé basé sur le Elite C_ + +## Caterina + +Les cartes arduinos et leurs clones utilisent le [bootloader Caterina](https://github.com/arduino/ArduinoCore-avr/tree/master/bootloaders/caterina) (tous les claviers utilisant un Pro Micro, ou un clone). Ils utilisent aussi le protocole avr109 pour communiquer en virtuellement en série (serial en anglais). Les bootloaders comme le [A-Star](https://www.pololu.com/docs/0J61/9) sont basés sur Caterina. + +Pour vérifier la compatibilité avec un bootloader Caterina, vérifiez que ce bloc est présent dans votre fichier `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 +``` + +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é) +* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS) + +Séquence de flash :  + +1. Pressez la touche avec le keycode `RESET`, ou reliez les ports GND et RST. Vous n'avez que 7 secondes pour flasher une fois que l'opération a été faite. +2. Attendez que l'OS détecte l'appareil. +3. Flasher le fichier .hex. +4. Attendez que l'appareil redémarre automatiquement. + +ou, utilisez : + + make ::avrdude + +#### Commandes Caterina + +Il existe un certain nombre de commandes DFU que vous pouvez utiliser pour mettre à jour le firmware sur un périphérique DFU: + +* `: avrdude` - Il s’agit de l’option normale. Le script va attendre qu’un appareil Caterina soit disponible. Dès que c’est le cas, il flash le firmware. Il attendra de détecter un nouveau port COM pour le flasher. +* `: avrdude-loop` - Cela fonctionne de la même manière que`: avrdude`, mais une fois que chaque périphérique est flashé, il tentera de flasher à nouveau. Cela peut être utile pour flasher plusieurs claviers à la suite. _Cela implique de sortir manuellement de la boucle en appuyant sur Ctrl + C, Cmd + C ou un raccourci équivalent selon votre OS_ +* `: avrdude-split-left` - Cela fonctionne de la même manière que la fonction (`: avrdude`). Toutefois, cela permet aussi de flasher le coté gauche de l'EEPROM des claviers splittés / divisés. C'est donc la méthode recommandée pour les claviers splittés avec Pro Micro. +* `: avrdude-split-right` - Cela fonctionne de la même manière que la fonction (`: avrdude`). Toutefois, cela permet aussi de flasher le coté droite de l'EEPROM des claviers splittés / divisés. C'est donc la méthode recommandée pour les claviers splittés avec Pro Micro. + +## Halfkay + +Halfkay est un protocole ultra-simple développé par PJRC qui utilise HID et qui est fourni avec tous les Teensys après le modèle 2.0. + +Pour vérifier la compatibilité avec le booloader Halfkay, vérifiez que ce bloc est présent dans votre fichier `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 +``` + +Flasher compatibles : + +* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (Interface graphique recomandée) +* [Teensy Loader](https://www.pjrc.com/teensy/loader.html) (petit utilitaire ultra simple) + [Teensy Loader en ligne de commande](https://www.pjrc.com/teensy/loader_cli.html) (Outil en ligne de commande recommandé) + +Séquence de flash : + +1. Pressez la touche du keycode `RESET`, ou reliez les ports RST et GND rapidement. Vous avez ensuite 7 secondes pour réaliser le flash. +2. Attendez que l'OS détecte l'appareil. +3. Flasher le fichier .hex. +4. Redémarrez l'appareil en mode « application ». Cela peut être fait automatiquement. + +## USBasploader + +USBasploader est un bootloader développé par matrixstorm. Il est utilisé sur des processeurs AVR non-USB comme le ATmega328P, qui fonctionne grâce à V-USB. + +Pour vérifier la compatibilité avec le booloader USBasploader, vérifiez que ce bloc est présent dans votre fichier `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 +``` + +Flashers compatibles : + +* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (Interface graphique recommandé) +* [avrdude](http://www.nongnu.org/avrdude/) avec le programmeur `usbasp`. +* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS) + +Séquence de flash : + +1. Pressez la touche du keycode `RESET`, ou reliez le port de boot pendant que RST et GND snt reliés. Cela doit être fait très rapidement. +2. Attendez que l'OS détecte l'appareil. +3. Flasher le fichier .hex. +4. Redémarrez l'appareil en mode « application ». Cela peut être fait automatiquement. + +## BootloadHID + +BootloadHID est un bootloader pour les microcontrôleurs AVR. L'utilitaire de téleversement ne demande pas de drivers au niveau du kernel et peut être lancé sans installer aucune DLLs. + +Pour vérifier la compatibilité avec le bootloader bootloadHID, vérifiez que ce bloc existe dans votre fichier `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 +``` + +Utilitaires de flash compatibles : + +* [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) (Utilitaire avec interface graphique recommandé) +* [bootloadhid Command Line](https://www.obdev.at/products/vusb/bootloadhid.html) / `:BootloadHID` avec QMK (utilitaire en ligne de commande recommandé) + +Séquence de flash + +1. Entrez dans le bootloader en utilisant l'une de ces méthodes : + * Pressez la touche du keycode `RESET` (Cela ne fonctionnera pas sur certains appareils). + * Verrouillez la touche « Salt » tout en branchant le clavier (Généralement ce principe est documenté dans le fichier readme du clavier) +2. Attendez que l'OS détecte l'appareil. +3. Flasher le fichier .hex. +4. Redémarrez l'appareil en mode « application ». Cela peut être fait automatiquement. + +Ou alors : + + make ::bootloadHID + +## STM32 + +Tous les processeurs STM32 contiennent un bootloader installé en usine qui ne peut pas être modifié ou supprimé. Certains processeurs STM32 ont des bootloaders qui ne peuvent pas être programmés par USB (ex : STM32F103) mais le processus reste le même. + +Pour le moment, aucune variable `BOOTLOADER` n'est nécessaire dans le fichier `rules.mk`. + +Flashers compatibles : + +* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (interface graphique recommandé) +* [dfu-util](https://github.com/Stefan-Schmidt/dfu-util) / `:dfu-util` (utilitaire en ligne de commande recommandé) + +Séquence pour flasher: + +1. Entrez dans le bootloader en utilisant l'une de ces méthodes : + * Utilisez une touche sur laquelle le keycode `RESET` (Cela peut ne pas fonctionner sur les appareils STM32F042) + * Si un circuit de réinitialisation (Reset) est présent alors utilisé le bouton qui lui est dédié. + * Autrement, vous devez réaliser une liaison entre BOOT0 et VCC (en appuyant sur le bouton ou à l'aide d'un pont) puis faire un pont entre RESET et GND et enfin relacher le pont BOOT0. +2. Attendre que l'os détecte l'appareil. +3. Flasher un fichier `.bin`.h + * Vous allez recevoir un avertissement à propos de la signature DFU. Ignorez-la. +4. Réinitialisez l'appareil en mode « application ». Cela peut être fait automatiquement. + * Si vous êtes en train de travailler en ligne de commande, par exemple avec un `make planck/rev6:default:dfu-util` alors soyez bien sur que l'argument `:leave` est passé aux arguments DFU grâce à la variable `DFU_ARGS` à l'intérieur de votre fichier `rules.mk` (Ex : `DFU_ARGS = -d 0483:df11 -a 0 -s 0x08000000:leave`) afin que votre appareil redémarre après avoir été flashé. + +### Commandes STM32 + +Il y a différentes commandes que vous pouvez utiliser pour flasher un firmware dans un appareil STM32  : + +* `:dfu-util` - C'est l'option standard pour flasher un appareil STM32. Le script attendra qu'un bootloader STM32 soit présent. +* `:dfu-util-split-left` - Permet de flasher un firmware normalement, tout comme l'option précédente mais permet de configurer le côté gauche des paramètres EEPROM sur un clavier scindé. +* `:dfu-util-split-right` - Permet de flasher un firmware normalement, tout comme l'option précédente mais permet de configurer le côté droit des paramètres EEPROM sur un clavier scindé. +* `:st-link-cli` - Cela permet de flasher le firmware avec l'utilitaire en ligne de commande ST-LINK's plutôt que d'utiliser dfu-util. diff --git a/docs/fr-fr/getting_started_getting_help.md b/docs/fr-fr/getting_started_getting_help.md new file mode 100644 index 00000000000..fedb18c76c5 --- /dev/null +++ b/docs/fr-fr/getting_started_getting_help.md @@ -0,0 +1,15 @@ +# Trouver de l'aide + +Il y a beaucoup de ressources pour trouver de l'aide avec QMK. + +## Chat temps-réel + +Vous trouverez des développeurs QMK et des utilisateurs sur notre [Serveur Discord](https://discord.gg/Uq7gcHh) principal. Il y a des canaux spécifiques dans le serveur pour discuter des firmwares, toolbox, hardware et configurateurs. + +## Sous-Reddit OLKB + +Le forum officiel de QMK est [/r/olkb](https://reddit.com/r/olkb) sur [reddit.com](https://reddit.com). + +## Tickets GitHub + +Vous pouvez ouvrir un [ticket sur GitHub](https://github.com/qmk/qmk_firmware/issues). Ceci est spécialement pratique lorsque votre problème demande une discussion sur le long terme ou un débugage. diff --git a/docs/fr-fr/getting_started_github.md b/docs/fr-fr/getting_started_github.md new file mode 100644 index 00000000000..76d107dfb99 --- /dev/null +++ b/docs/fr-fr/getting_started_github.md @@ -0,0 +1,67 @@ +# Comment utiliser GitHub avec QMK + +GitHub peut être un peu compliqué pour ceux qui n'y sont pas familier. Ce guide va vous expliquer chaque étape de "fork", clone et envoi d'un pull request avec QMK. + +?> Ce guide part du principe que vous êtes suffisamment à l'aise pour envoyer commandes sur la ligne de commande et que vous avez Git installé sur votre système. + +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) + +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) + +Faites attention à sélectionner "HTTPS", et sélectionnez le lien et copiez-le: + +![HTTPS link](http://i.imgur.com/eGO0ohO.jpg) + +Ensuite, entrez `git clone --recurse-submodules ` dans la ligne de commande, et collez votre lien: + +``` +user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git +Cloning into 'qmk_firmware'... +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: + +``` +user@computer:~$ git add . +user@computer:~$ git commit -m "adding my keymap" +[master cccb1608] adding my keymap + 1 file changed, 1 insertion(+) + create mode 100644 keyboards/planck/keymaps/mine/keymap.c +user@computer:~$ git push +Counting objects: 1, done. +Delta compression using up to 4 threads. +Compressing objects: 100% (1/1), done. +Writing objects: 100% (1/1), 1.64 KiB | 0 bytes/s, done. +Total 1 (delta 1), reused 0 (delta 0) +remote: Resolving deltas: 100% (1/1), completed with 1 local objects. +To https://github.com/whoeveryouare/qmk_firmware.git + + 20043e64...7da94ac5 master -> master +``` + +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) + +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) + +Une fois transmis, nous pourrons vous parler de vos changements, vous demander de faire des changements, et éventuellement de les accepter! + +Merci de contribuer à QMK :) diff --git a/docs/fr-fr/getting_started_introduction.md b/docs/fr-fr/getting_started_introduction.md new file mode 100644 index 00000000000..b2711a1671e --- /dev/null +++ b/docs/fr-fr/getting_started_introduction.md @@ -0,0 +1,62 @@ +# Introduction + +Le but de cette page est d'expliquer les informations de base qui vous serons nécessaire pour travailler sur le projet QMK. Il a pour pré-requis que vous soyez familier à la navigation à l'aide d'un shell Unix, mais ne s'attend pas à ce que vous soyez familier avec C ou la compilation en utilisant make. + +## 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_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 + +Dans le dossier `users` se trouve un répertoire pour chaque utilisateur. C'est un endroit où les utilisateurs peuvent mettre du code qui serait partagé entre plusieurs claviers. Merci de lire la documentation [Fonctionnalité Userspace](feature_userspace.md) pour plus d'information. + +### Structure du projet clavier + +Dans le dossier `keyboards`, son sous-dossier `handwired` et ses sous-dossiers pour les revendeurs et fabriquants (par exemple `clueboard`) se trouve un répertoire pour chaque projet clavier. Par exemple `qmk_firmware/keyboards/clueboard/2x1800`. + +A l'intérieur, vous trouverez la structure suivante: + +* `keymaps/`: différentes keymaps qui peuvent être compilées +* `rules.mk`: Ce fichier définit les options "make" par défaut. Ne modifiez pas ce fichier directement, utilisez à la place un `rules.mk` spécifique à la keymap. +* `config.h`: Ce fichier définit les options de compilation par défaut. Ne modifiez pas ce fichier directement, utilisez à la place un `config.h` spécifique à la keymap. +* `info.json`: Le fichier utilisé pour définir les options de layout de QMK Configurator. Voyez [Support Configurator](reference_configurator_support.md) pour plus d'information. +* `readme.md`: une brève description du clavier. +* `.h`: Ce fichier définit le layout du fichier par rapport à la matrice de commutation. +* `.c`: Ce fichier définit du code custom pour le clavier. + +Pour plus d'information sur la structure du projet, voyez [Directives clavier QMK](hardware_keyboard_guidelines.md). + +### Structure d'une Keymap + +Dans chaque dossier keymap, vous allez trouver les fichiers suivants. Seul le fichier `keymap.c` est nécessaire, et si le reste des fichiers n'existent pas, les options par défaut seront choisies. + +* `config.h`: les options de configuration de votre keymap +* `keymap.c`: tout le code de votre keymap, requis +* `rules.mk`: les features de QMK qui sont activées +* `readme.md`: une description de votre keymap, comment d'autres l'utiliseront, et des explications des fonctionnalités. Uploadez les images vers un service comme imgur. + +# Le fichier `config.h` + +Le fichier `config.h` peut être mis à 3 endroits: + +* keyboard (`/keyboards//config.h`) +* userspace (`/users//config.h`) +* keymap (`/keyboards//keymaps//config.h`) + +Le système de compilation cherche automatiquement les fichiers de configuration dans l'ordre au-dessus. Si vous souhaitez surcharger une configuration définie par un `config.h` précédent, vous devrez d'abord ajouter le code suivant. + +``` +#pragma once +``` + +Ensuite, pour surcharger l'option du fichier `config.h` précédent, vous devez `#undef` puis `#define` l'option à nouveau. + +Voici à quoi l'ensemble du code ressemble une fois regroupé: + +``` +#pragma once + +// overrides go here! +#undef MY_SETTING +#define MY_SETTING 4 +``` diff --git a/docs/fr-FR/newbs.md b/docs/fr-fr/newbs.md similarity index 100% rename from docs/fr-FR/newbs.md rename to docs/fr-fr/newbs.md diff --git a/docs/fr-fr/newbs_best_practices.md b/docs/fr-fr/newbs_best_practices.md new file mode 100644 index 00000000000..ec68a5e3e52 --- /dev/null +++ b/docs/fr-fr/newbs_best_practices.md @@ -0,0 +1,161 @@ +# Bonnes Pratiques + +## Ou, "Comment j'ai appris à ne plus m'en faire et aimer Git." + +Ce document a pour but d'apprendre aux novices les meilleures solutions pour faciliter la contribution à QMK. Nous allons étudier le processus de contribution à QMK, détaillant quelques moyens de rendre cette tâche plus simple. Nous allons faire quelques erreurs afin de vous apprendre à les résoudre. + +Ce document suppose les choses suivantes: + +1. Vous avez un compte GitHub, et avez [créé un "fork" pour le dépôt qmk_firmware](fr-FR/getting_started_github.md) avec votre compte. +2. Vous avez [configuré votre environnement de compilation](fr-FR/newbs_getting_started.md?id=environment-setup). + +## La branche master de votre fork: Mettre à jour souvent, ne jamais commit + +Il est hautement recommandé pour le développement de QMK, peu importe ce qui est fait ou où, de garder votre branche `master` à jour, mais de ne ***jamais*** commit dessus. A la place, faites tous vos changements dans une branche de développement et crééz des "pull requests" de votre branche lorsque vous développez. + +Pour réduire les chances de conflits de fusion (merge) — des cas où deux ou plus d'utilisateurs ont édité la même section d'un fichier en parallèle — gardez votre branche `master` relativement à jour et démarrez chaque nouveau développement en créant une nouvelle branche. + +### Mettre à jour votre branche master + +Pour garder votre branche `master` à jour, il est recommandé d'ajouter le dépôt du firmware QMK comme un dépôt distant (remote) dans git. pour se faire, ouvrez votre interface de ligne de commande Git et entrez: + +```bash +git remote add upstream https://github.com/qmk/qmk_firmware.git +``` + +Pour vérifier que le dépôt a bien été ajouté, lancez la commande `git remote -v`, qui devrait retourner le résultat suivant: + +```bash +$ git remote -v +origin https://github.com//qmk_firmware.git (fetch) +origin https://github.com//qmk_firmware.git (push) +upstream https://github.com/qmk/qmk_firmware.git (fetch) +upstream https://github.com/qmk/qmk_firmware.git (push) +``` + +Maintenant que c'est fait, vous pouvez vérifier les mises à jour au dépôt en lançant `git fetch upstream`. Cela récupère les branches et les tags — appelé de manière générale "refs" — du dépôt QMK, qui a maintenant le surnom `upstream`. Nous pouvons maintenant comparer les données sur notre "fork" `origin` à celles contenues par QMK. + +Pour mettre à jour la branche master de votre "fork", lancez les commandes suivantes (en appuyant sur Enter après chaque ligne): + +```bash +git checkout master +git fetch upstream +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. + +### Faire des changements + +Pour faire des changements, créez une nouvelle branche en entrant: + +```bash +git checkout -b dev_branch +git push --set-upstream origin dev_branch +``` + +Ceci crée une branche nommée `dev_branch`, bascule vers cette branche, et ensuite sauvegarde cette nouvelle branche vers votre fork. L'argument `--set-upstream` demande à git d'utiliser votre fork et la branche `dev_branch` à chaque fois que vous utilisez `git push` ou `git pull` depuis cette branche. Vous ne devez l'utiliser que pour le premier "push", après cela, vous pouvez utiliser simplement `git push` ou `git pull`, sans le reste des arguments. + +!> Avec `git push`, vous pouvez utiliser `-u` à la place de `--set-upstream` — `-u` est un alias pour `--set-upstream`. + +Vous pouvez appeler votre branche à peu près comme vous voulez, toutefois il est recommandé d'utiliser un nom qui est lié aux changements que vous allez faire. + +Par défaut, `git checkout -b` va faire de la branche actuelle la branche de base de votre nouvelle branche. Vous pouvez définir la base de votre nouvelle branche comme étant n'importe quelle branche existante qui n'est pas la courante en utilisant la commande: + +```bash +git checkout -b dev_branch master +``` + +Maintenant que vous avez une branche de développement, ouvrez votre éditeur de texte et faites vos changements. Il est recommandé de faire beaucoup de petits commits dans votre branche. Ainsi, un changement qui crée un problème peut être plus facilement retracé et annulé si nécessaire. Pour faire un changement, éditez et sauvez n'importe quel fichier qui doit être mis à jour, ajoutez les à la *zone de staging* de Git, et commitez les vers votre branche: + +```bash +git add path/to/updated_file +git commit -m "My commit message." +``` + +`git add` ajoute les fichiers qui ont été changés dans la *zone de staging* de Git, qui est sa "zone de chargement". Elle contient tous les changements qui vont être *validés* (committed) par `git commit`, qui sauvegarde les changements vers le dépôt. Utilisez des messages de validation descriptifs afin que vous puissiez savoir ce qui a changé d'un coup d'oeil. + +!> Si vous changez beaucoup de fichiers, mais tous les fichiers font partie du même changement, vous pouvez utiliser `git add .` pour ajouter tous les fichiers changés dans le répertoire courant, plutôt que d'avoir à ajouter chaque fichier individuellement. + +### Publier Vos Changements + +La dernière étape est de pousser vos changements vers votre fork. Pour ce faire, entrez `git push`. Git publie maintenant l'état courant de `dev_branch` vers votre fork. + +## Résoudre Les Conflits De Merge + +Parfois, lorsque votre travail sur une branche met beaucoup de temps à se compléter, des changements réalisés par d'autres peuvent entrer en conflit avec les changements que vous avez fait sur votre branche au moment où vous avez ouvert un pull request. Ceci est appelé un *conflit de merge*, et c'est ce qui arrive lorsque plusieurs personnes modifient les mêmes parties de mêmes fichiers. + +### Rebaser Vos Changements + +Un *rebase* est la manière pour Git de prendre les changements qui ont été faits à un point, les annuler, et les réappliquer sur un autre point. Dans le cas d'un conflit de merge, vous pouvez rebaser votre branche pour récupérer les changements qui ont été faits entre le moment où vous avez créé votre branche et le présent. + +Pour démarrer, lancez les commandes suivantes: + +```bash +git fetch upstream +git rev-list --left-right --count HEAD...upstream/master +``` + +La commande `git rev-list` retourne le nombre de commits qui diffère entre la branche courante et la branche master de QMK. Nous lançons `git fetch` en premier afin d'être sûr que les refs qui représentent l'état courant du dépôt upstream soient à jour. Le résultat de la commande `git rev-list` retourne deux nombres: + +```bash +$ git rev-list --left-right --count HEAD...upstream/master +7 35 +``` + +Le premier nombre représente combien il y a eu de commits sur la branche courante depuis qu'elle a été créée, et le second nombre est combien de commits ont été faits sur la branche `upstream/master` depuis que la branche a été créée et, ainsi, les changements qui ne sont pas enregistrés sur la branche courante. + +Maintenant que l'état actuel de la branche courante et la branche upstream sont connus, nous pouvons maintenant démarrer une opération de rebase: + +```bash +git rebase upstream/master +``` + +Ceci dit à Git d'annuler les commits de la branche courante puis de les réappliquer sur la branche master de QMK. + +```bash +$ git rebase upstream/master +First, rewinding head to replay your work on top of it... +Applying: Commit #1 +Using index info to reconstruct a base tree... +M conflicting_file_1.txt +Falling back to patching base and 3-way merge... +Auto-merging conflicting_file_1.txt +CONFLICT (content): Merge conflict in conflicting_file_1.txt +error: Failed to merge in the changes. +hint: Use 'git am --show-current-patch' to see the failed patch +Patch failed at 0001 Commit #1 + +Resolve all conflicts manually, mark them as resolved with +"git add/rm ", then run "git rebase --continue". +You can instead skip this commit: run "git rebase --skip". +To abort and get back to the state before "git rebase", run "git rebase --abort". +``` + +Ceci nous dit que nous avons un conflit de merge, et nous donne le nom du fichier en conflit. Ouvrez le fichier conflictuel dans votre éditeur de texte et, quelque part dans le fichier, vous trouverez quelque chose comme ça: + +```bash +<<<<<<< HEAD +

For help with any issues, email us at support@webhost.us.

+======= +

Need help? Email support@webhost.us.

+>>>>>>> Commit #1 +``` + +La ligne `<<<<<<< HEAD` montre le début d'un conflit de merge et la ligne `>>>>>>> Commit #1` indique la fin, avec les sections conflictuelles séparées par `=======`. La partie du côté `HEAD` vient de la version du fichier provenant de la branche master de QMK, et la partie marquée avec le numéro du commit provient de la branche courrante. + +Parce que Git suis *les changements des fichiers*, plutôt que les contenus des fichiers directement, si Git ne peut pas trouver le texte qu'il y avait dans le fichier avant que le commit soit fait, il ne saura pas comment modifier le fichier. Modifier le fichier à nouveau va résoudre le conflit. Faites votre changement, et sauvez le fichier. + +```bash +

Need help? Email support@webhost.us.

+``` + +Maintenant, lancez: + +```bash +git add conflicting_file_1.txt +git rebase --continue +``` + +Git enregistre le changement dans le fichier conflictuel, et continue à appliquer les commits depuis votre branche jusqu'à ce qu'il arrive à la fin. diff --git a/docs/fr-FR/newbs_building_firmware.md b/docs/fr-fr/newbs_building_firmware.md similarity index 100% rename from docs/fr-FR/newbs_building_firmware.md rename to docs/fr-fr/newbs_building_firmware.md diff --git a/docs/fr-fr/newbs_building_firmware_configurator.md b/docs/fr-fr/newbs_building_firmware_configurator.md new file mode 100644 index 00000000000..d06242f3927 --- /dev/null +++ b/docs/fr-fr/newbs_building_firmware_configurator.md @@ -0,0 +1,105 @@ +# Configurateur de QMK + +Le [Configurateur de QMK](https://config.qmk.fm) est une interface graphique en ligne permettant de générer des fichiers "hex" du firmware de QMK. + +?> **S'il vous plaît, suivez les étapes suivantes dans l'ordre.** + +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. + +!> **Les fichiers d'autres outils, tels que KLE ou kbfirmware ne seront pas compatibles avec le configurateur QMK. Ne les chargez pas, ne les importez pas. Le configurateur QMK est un outil DIFFERENT.** + +## Sélectionner votre clavier + +Cliquez la boîte déroulante et sélectionnez le clavier pour lequel vous voulez créer une keymap. + +?> Si votre clavier a plusieurs versions, faites attention à utiliser la bonne. + +Je vais le répéter, parce que c'est important + +!> **FAITES ATTENTION A UTILISER LA BONNE VERSION !** + +Si votre clavier est annoncé comme fonctionnant grâce à QMK mais n'est pas dans la liste, il y a des chances que le développeur ne l'ait pas encore fait, ou que nous n'avons pas encore eu le temps de le merger. Ajoutez un problème (issue) sur [qmk_firmware](https://github.com/qmk/qmk_firmware/issues) demandant le support de votre clavier, s'il n'y a pas de [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) ouvert pour lui. Il y a aussi des claviers alimentés par QMK qui sont sur le compte GitHub du fabricant, il est bon de le vérifier aussi. + +## Sélectionner la disposition de votre clavier + +Choisissez la disposition (layout) qui représente le mieux la keymap que vous voulez créer. Certains claviers n'ont pas encore assez de dispositions ou des dispositions incorrectes. Ils seront supportés dans le future. + +## Nom de la Keymap + +Appelez cette keymap comme vous voulez. + +?> Si vous rencontrez des problèmes lors de la compilation, il peut être utile de changer ce nom, il peut déjà exister dans le dépôt du firmware QMK. + +## Créer votre keymap + +Entrer un keycode peut s'accomplir de 3 façons différentes. + +1. Glisser déposer +2. Cliquer sur un endroit vide sur le layout et cliquer sur le keycode souhaité +3. Cliquer sur un endroit vide sur le layout et appuyer sur une touche physique de votre clavier. + +Passez votre souris au dessus d'une touche et un affichage vous dira quel est le rôle du keycode. Pour une version plus verbeuse suivre: + +[Référence Keycode basique](https://docs.qmk.fm/#/keycodes_basic) +[Référence Keycode avancé](https://docs.qmk.fm/#/feature_advanced_keycodes) + +Dans le cas où vous ne trouvez pas une disposition qui supporte votre keymap, par exemple trois places pour une barre d'espace, ou deux places pour retour clavier, ou deux places pour shift, etc. etc. remplissez les TOUTES. + +### Exemples + +3 places pour la barre d'espace: Remplissez les TOUTES avec la barre d'espace + +2 places pour un retour clavier: Remplissez les DEUX avec un retour clavier + +2 places pour un shift droit: Remplissez les DEUX avec un shift droit + +1 place pour un shift gauche et 1 place pour le support ISO: Remplissez les deux avec un shift gauche + +5 places, mais seulement 4 touches: Deviner et vérifier, ou demander à quelqu'un qui l'a déjà fait. + +## Sauvez votre keymap pour des éditions futures + +Une fois satisfait de votre keymap, ou si vous souhaitez revenir travailler dessus plus tard, appuyez sur le bouton `Export Keymap`. Il vous permettra de sauvegarder votre keymap avec le nom choisi au dessus suivi de .json. + +Vous pouvez ensuite charger ce fichier .json à nouveau en appuxant sur le bouton `Import Keymap`. + +!> **ATTENTION** Ce n'est pas le même type de fichier .json utilisé pour kbfirmware.com ou n'importe quel autre outil. Si vous essayez d'utiliser ce fichier pour d'autres outil, ou le fichier .json d'autres outils avec le configurateur QMK, il y a des chances que votre clavier **explose**. + +## Générer votre fichier firmware + +Appuyez sur le bouton `Compile`. + +Une fois la compilation terminée, vous pourrez appuyer sur le bouton vert `Download Firmware`. + +## Ecrire votre firmware sur votre clavier + +Merci de vous référer à [Flasher le Firmware](fr-FR/newbs_flashing.md) + +## Dépannage + +#### Mon fichier json ne fonctionne pas + +Si le fichier .json a été généré par le configurateur QMK, bravo vous avez trouvé un bug. Merci d'ouvrir une issue sur [qmk_configurator](https://github.com/qmk/qmk_configurator/issues) + +Sinon... vous avez raté mon message écris en gras qui dit de ne pas utiliser d'autres fichiers .json? + +#### Il y a des espaces en trop dans mon alyout? Qu'est-ce que je fais? + +Si vous voulez dire que vous avez trois places pour une barre d'espace, le mieux est de les remplir tous avec une barre d'espace. Vous pouvez faire de même avec les retour clavier et les shift. + +#### C'est quoi le keycode pour ....... + +Merci de regarder + +[Référence keycode basique](https://docs.qmk.fm/#/keycodes_basic) +[Référence keycode avancé](https://docs.qmk.fm/#/feature_advanced_keycodes) + +#### Ca ne compile pas? + +Merci de vérifier les autres dispositions de votre keymap afin d'être sûr qu'il n'y a pas de touches aléatoires. + +## Problèmes et Bugs + +Nous acceptons toujours les demandes des clients et les rapports de bugs. Merci de les remplirs sur [qmk_configurator](https://github.com/qmk/qmk_configurator/issues) diff --git a/docs/fr-fr/newbs_flashing.md b/docs/fr-fr/newbs_flashing.md new file mode 100644 index 00000000000..c9849eb1048 --- /dev/null +++ b/docs/fr-fr/newbs_flashing.md @@ -0,0 +1,367 @@ +# Flasher votre clavier + +Maintenant que vous avez compilé un firmware custom, vous allez vouloir le flasher dans votre clavier. + +## Flasher votre clavier avec QMK Toolbox + +La manière la plus simple de flasher votre clavier est avec [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases). + +Toutefois, la QMK Toolbox n'est actuellement disponible que pour Windows et macOS. Si vous utilisez Linux (ou préférez flasher le firmware depuis la ligne de commande), vous devrez utiliser [la métode décrite ci-dessous](newbs_flashing.md#flash-your-keyboard-from-the-command-line). + +### Charger le fichier dans QMK Toolbox + +Démarrez en ouvrant l'application QMK Toolbox. Cherchez le fichier de firmware dans Finder ou Explorer. Vore firmware de clavier peut être dans un de deux formats `.hex` ou `.bin`. QMK essaye de copier le bon format pour votre clavier du répertoire racine `qmk_firmware`. + +?> Si vous êtes sous Windows ou macOS il y a des commandes que vous pouvez utiliser pour facilement ouvrir le répertoire firmware dans Explorer ou Finder. + +?> Windows: + + start . + +?> macOS: + + open . + +Le fichier firmware suit toujours ce format de nommage: + + _.{bin,hex} + +Par exemple, le `plank/rev5` avec une keymap `default` aura ce nom de fichier: + + planck_rev5_default.hex + +Une fois que vous aurez trouvé votre fichier de firmware, glissez le dans la boîte "Local file" sur QMK Toolbox, ou cliquez sur "Open" et naviguez où votre firmware est enregistré. + +### Mettez votre clavier en mode DFU (Bootloader) + +Afin de flasher votre firmware custom, vous devez mettre votre clavier dans un mode spécial. Lorsqu'il sera dans ce mode, vous ne pourrez pas taper ou utiliser votre clavier. Il est très important que vous ne débranchiez pas votre clavier ou n'arrêtiez pas le processus d'écriture du firmware. + +Chaque clavier a une manière différente d'entrer dans ce mode spécial. Si votre clavier tourne actuellement QMK ou TMK et vous n'avez pas reçu d'instruction spécifiques, essayez, dans cet ordre: + +* Enfoncez les deux touches shift et appuyez sur `Pause` +* Enfoncez les deux touches shift et appuyez sur `B` +* Débranchez votre clavier, gardez shift la barre d'espace et `B` en même temps, branchez votre clavier et attendez une seconde avant de relâcher les touches. +* Appuyez la touche physique `RESET` en bas du PCB +* Trouvez les pins sur le PCB marquées `BOOT0` ou `RESET`, court circuitez ces pins en branchant votre PCB + +Lorsque vous aurez réussi, vous verrez le message suivant dans QMK Toolbox: + +``` +*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 +*** DFU device connected +``` + +### Flasher votre clavier + +Appuyez sur le boutton `Flash` dans QMK Toolbox. Vous verrez un résultat similaire à ce qui suit: + +``` +*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 +*** DFU device connected +*** Attempting to flash, please don't remove device +>>> dfu-programmer atmega32u4 erase --force + Erasing flash... Success + Checking memory from 0x0 to 0x6FFF... Empty. +>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex + Checking memory from 0x0 to 0x55FF... Empty. + 0% 100% Programming 0x5600 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + 0% 100% Reading 0x7000 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + Validating... Success + 0x5600 bytes written into 0x7000 bytes memory (76.79%). +>>> dfu-programmer atmega32u4 reset + +*** DFU device disconnected +*** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390 +``` + +## Flashez votre clavier à l'aide de la ligne de commande + +C'est désormais relativement simple. Lorsque vous êtes prêt à compiler et à flasher votre firmware, ouvrez la fenêtre de votre terminal et exécutez la commande de build : + + make ::flash + +Par exemple, si votre keymap s'appelle "xyverz" et que vous fabriquez une keymap pour un clavier `planck` de version `rev5` vous devrez utiliser cette commande: + + make planck/rev5:xyverz:flash + +La commande va vérifier la configuration du clavier, puis tentera de le flasher en fonction du bootloader (chargeur d’amorçage) spécifié. Cela signifie que vous n'avez pas besoin de savoir quel bootloader votre clavier utilise. Exécutez simplement la commande et laissez-le faire le gros du travail. + +Cependant, tout dépend du bootloader qui est installé sur le clavier. Si cette information n’est pas configurée ou si vous tentez de flasher un clavier qui ne permet pas d’être flashé alors vous obtiendrez cette erreur : + + WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time. + +Dans ce cas, vous devrez choisir le bootloader. + +Il y a cinq bootloaders principaux. Les Pro-Micro et les clones utilisent Caterina, les Teensy utilisent Halfkay, les claviers AVR d’OLKB utilisent QMK-DFU, certains controleurs atmega32u4 utilisent DFU et la plupart des controlleurs ARM utilisent ARM DFU. + +Vous pouvez trouver plus d'information à propos des bootloaders sur la page [Instructions de flash et information sur le Bootloader](flashing.md). + +Si vous savez quel bootloader vous utilisez, lorsque vous compilez le firmware, vous pouvez ajouter quelques options à la commande `make` pour automatiser le processus de flash. + +### DFU + +Pour le bootloader DFU, lorsque vous êtes prêts à compiler et flasher votre firmware, ouvrez votre fenêtre de terminal et lancez la commande de compilation: + + make ::dfu + +Par exemple, si vous keymap s'appelle "xyverz" et vous compilez une keymap pour une plank rev5, vous utiliserez cette commande: + + make planck/rev5:xyverz:dfu + +Une fois la compilation terminée, le résultat devrait être le suivant: + +``` +Linking: .build/planck_rev5_xyverz.elf [OK] +Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK] +Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK] +Checking file size of planck_rev5_xyverz.hex + * File size is fine - 18574/28672 + ``` + +Une fois arrivé à ce stade, le script de compilation va chercher le bootloader DFU toutes les 5 secondes. Il va répéter les messages suivants jusqu'à ce que l'appareil soit trouvé ou que vous l'annuliez. + + dfu-programmer: no device present. + Error: Bootloader not found. Trying again in 5s. + +Une fois terminé, vous devrez mettre à zéro le contrôleur. Vous allez voir un résultat similaire à ceci: + +``` +*** Attempting to flash, please don't remove device +>>> dfu-programmer atmega32u4 erase --force + Erasing flash... Success + Checking memory from 0x0 to 0x6FFF... Empty. +>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex + Checking memory from 0x0 to 0x55FF... Empty. + 0% 100% Programming 0x5600 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + 0% 100% Reading 0x7000 bytes... + [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success + Validating... Success + 0x5600 bytes written into 0x7000 bytes memory (76.79%). +>>> dfu-programmer atmega32u4 reset +``` + +?> Si vous avez des soucis concernant ceci - par exemple `dfu-programmer: no device present` - merci de regarder [Foires Aux Questions de Compilation](faq_build.md). + +#### Commandes DFU + +Il y aun certain nombre de commandes du DFU que vous pouvez utiliser pour flasher un firmware sur un device DFU: + +* `:dfu` - C'est l'option standard qui attends jusqu'à e qu'un appareil DFU soit disponible, puis flash le firmware. Il va vérifier toutes les 5 secondes, afin de voir si un appareil DFU est apparu. +* `:dfu-ee` - Ceci flash un fichier `eep` à la place du standard hex, peu commun. +* `:dfu-split-left` - Ceci flash le firmware standard, comme la commande standard (`:dfu`). Toutefois, elle flash aussi les fichiers EEPROM du "côté gauche" pour les claviers scindés. _C'est l'option idéale pour les claviers scindés basés sur Elite C._ +* `:dfu-split-right` - Ceci flash le firmware standard, comme la commande standard (`:dfu`). Toutefois, elle flash aussi les fichiers EEPROM du "côté droit" pour les claviers scindés. _C'est l'option idéale pour les claviers scindés basés sur Elite C._ + +### Caterina + +Pour les boards Arduino et leurs clones (tel que le SparkFun ProMicro), lorsque vous êtes prêt à compiler et flasher votre firmware, ouvrez votre terminal et lancer la commande de compilation: + + make ::avrdude + +Par exemple, si votre keymap se nomme "xyverz" et que vous compilez une keymap pour un Lets Split rev2, vous utiliserez la commande suivante: + + make lets_split/rev2:xyverz:avrdude + +Une fois le firmware compilé, vous aurez le résultat suivant: + +``` +Linking: .build/lets_split_rev2_xyverz.elf [OK] +Creating load file for flashing: .build/lets_split_rev2_xyverz.hex [OK] +Checking file size of lets_split_rev2_xyverz.hex [OK] + * File size is fine - 27938/28672 +Detecting USB port, reset your controller now.............. +``` + +Une fois ceci fait, réinitialisez votre board et le script va détecter et flasher le firmware. La sortie devrait ressembler à quelque chose comme ça: + +``` +Detected controller on USB port at /dev/ttyS15 + +Connecting to programmer: . +Found programmer: Id = "CATERIN"; type = S + Software Version = 1.0; No Hardware Version given. +Programmer supports auto addr increment. +Programmer supports buffered memory access with buffersize=128 bytes. + +Programmer supports the following devices: + Device code: 0x44 + +avrdude.exe: AVR device initialized and ready to accept instructions + +Reading | ################################################## | 100% 0.00s + +avrdude.exe: Device signature = 0x1e9587 (probably m32u4) +avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed + To disable this feature, specify the -D option. +avrdude.exe: erasing chip +avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex" +avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex +avrdude.exe: writing flash (27938 bytes): + +Writing | ################################################## | 100% 2.40s + +avrdude.exe: 27938 bytes of flash written +avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex: +avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex: +avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex +avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes +avrdude.exe: reading on-chip flash data: + +Reading | ################################################## | 100% 0.43s + +avrdude.exe: verifying ... +avrdude.exe: 27938 bytes of flash verified + +avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF) + +avrdude.exe done. Thank you. +``` + +Si vous avez un souci, essayez de faire ceci: + + sudo make ::avrdude + +#### Commandes Caterina + +Il existe un certain nombre de commandes DFU que vous pouvez utiliser pour mettre à jour le firmware sur un périphérique DFU: + +* `: avrdude` - Il s’agit de l’option normale. Elle attend qu’un appareil Caterina soit disponible, puis tente de flasher le firmware. Il attendra de détecter un autre port COM, puis il flashera à nouveau. +* `: avrdude-loop` - Cela fonctionne de la même manière que `: avrdude`, mais une fois que chaque périphérique est flashé, il tentera de flasher à nouveau. Cela peut être utile pour flasher plusieurs claviers à la suite. _Cela implique de sortir manuellement de la boucle en appuyant sur Ctrl + C, Cmd + C ou un raccourci équivalent selon votre OS_ +* `: avrdude-split-left` - Cela fonctionne de la même manière que la fonction (`: avrdude`). Toutefois, cela permet aussi de flasher le coté gauche de l'EEPROM des claviers splittés / divisés. C'est donc la méthode recommandée pour les claviers splittés avec Pro Micro. +* `: avrdude-split-right` - Cela fonctionne de la même manière que la fonction (`: avrdude`). Toutefois, cela permet aussi de flasher le coté droite de l'EEPROM des claviers splittés / divisés. C'est donc la méthode recommandée pour les claviers splittés avec Pro Micro. + +### HalfKay + +Pour les composants PJRC (les Teensy), lorsque vous êtes prêts à compiler et flasher votre firmware, ouvrez votre fenêtre de terminal et lancez la commande de compilation suivante: + + make ::teensy + +Par exemple, si vous keymap s'appelle "xyverz" et vous compilez une keymap pour un Ergodox ou un Ergodox EZ, vous utiliserez cette commande: + + make ergodox_ez:xyverz:teensy + +Une fois la compilation du firmware terminée, votre sortie devrait ressembler à ça: + +``` +Linking: .build/ergodox_ez_xyverz.elf [OK] +Creating load file for flashing: .build/ergodox_ez_xyverz.hex [OK] +Checking file size of ergodox_ez_xyverz.hex [OK] + * File size is fine - 25584/32256 + Teensy Loader, Command Line, Version 2.1 +Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage +Waiting for Teensy device... + (hint: press the reset button) + ``` + +Une fois terminé, réinitialisez votre board. Une fois fait, vous verrez une sortie comme ça: + + ``` + Found HalfKay Bootloader +Read "./.build/ergodox_ez_xyverz.hex": 28532 bytes, 88.5% usage +Programming............................................................................................................................................................................ +................................................... +Booting +``` + +### STM32 (ARM) + +Pour la majorité des boards ARM (incluant les Proton C, Planck Rev 6, et Preonic Rev 3), lorsque vous êtes prêt à compiler et flasher votre firmware, ouvrez la fenêtre de terminal et lancez la commande de compilation: + + make ::dfu-util + +Par exemple, si votre keymap s'appelle "xyverz" et vous compilez une keymap pour le clavier Plank Revision 6, vous utiliserez cette commande et redémarrerez le clavier vers le bootloader (avant que la compilation soit terminée): + + make planck/rev6:xyverz:dfu-util + +Une fois le firmware compilé, il va afficher quelque chose comme ça: + +``` +Linking: .build/planck_rev6_xyverz.elf [OK] +Creating binary load file for flashing: .build/planck_rev6_xyverz.bin [OK] +Creating load file for flashing: .build/planck_rev6_xyverz.hex [OK] + +Size after: + text data bss dec hex filename + 0 41820 0 41820 a35c .build/planck_rev6_xyverz.hex + +Copying planck_rev6_xyverz.bin to qmk_firmware folder [OK] +dfu-util 0.9 + +Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc. +Copyright 2010-2016 Tormod Volden and Stefan Schmidt +This program is Free Software and has ABSOLUTELY NO WARRANTY +Please report bugs to http://sourceforge.net/p/dfu-util/tickets/ + +Invalid DFU suffix signature +A valid DFU suffix will be required in a future dfu-util release!!! +Opening DFU capable USB device... +ID 0483:df11 +Run-time device DFU version 011a +Claiming USB DFU Interface... +Setting Alternate Setting #0 ... +Determining device status: state = dfuERROR, status = 10 +dfuERROR, clearing status +Determining device status: state = dfuIDLE, status = 0 +dfuIDLE, continuing +DFU mode device DFU version 011a +Device returned transfer size 2048 +DfuSe interface name: "Internal Flash " +Downloading to address = 0x08000000, size = 41824 +Download [=========================] 100% 41824 bytes +Download done. +File downloaded successfully +Transitioning to dfuMANIFEST state +``` + +#### Commandes STM32 + +Il y aun certain nombre de commandes du DFU que vous pouvez utiliser pour flasher un firmware sur un device STM32: + +* `:dfu-util` - C'est l'option standard pour flasher un appareil STM32. Elle attendra qu'un bootloader STM32 soit présent et tentera de l’utiliser. +* `:dfu-util-left` - Ceci flasher le firmware standard, comme la commande standard (`:dfu-util`). Toutefois, elle flasher aussi les fichiers EEPROM du "côté gauche" pour les claviers scindés. +* `:dfu-util-right` - Ceci flash le firmware standard, comme la commande standard (`:dfu-util`). Toutefois, elle flash aussi les fichiers EEPROM du "côté droit" pour les claviers scindés. +* `:st-link-cli` - Cela permet de flasher le firmware avec l'utilitaire en ligne de commande ST-LINK's plutôt que d'utiliser dfu-util. + +### BootloadHID + +Pour les claviers basés sur Bootmapper Client(BMC)/bootloadHID/ATmega32A, si vous êtes prêts à compiler et flasher le firmware, ouvrez votre fenêtre de terminal et lancez la commande suivante : + + make ::bootloaderHID + +Par exemple, si votre keymap s'appelle "xyverz" et que vous compilez une keymap pour un jj40, utilisez cette commande: + + make jj40:xyverz:bootloaderHID + +Une fois le firmware compilé, vous aurez cette sortie: + +``` +Linking: .build/jj40_default.elf [OK] +Creating load file for flashing: .build/jj40_default.hex [OK] +Copying jj40_default.hex to qmk_firmware folder [OK] +Checking file size of jj40_default.hex [OK] + * The firmware size is fine - 21920/28672 (6752 bytes free) +``` + +A ce stade, le script de build va chercher le bootloader DFU toutes les 5 secondes. Il répétera l ’affichage de ce message jusqu'à ce que l’appareil soit trouvé ou que vous annuliez l'opération``` + +``` +Error opening HIDBoot device: The specified device was not found +Trying again in 5s. +``` + +Une fois ce résultat obtenu, réinitialisez le contrôleur. Le résultat suivant devrait s’afficher : + +``` +Page size = 128 (0x80) +Device size = 32768 (0x8000); 30720 bytes remaining +Uploading 22016 (0x5600) bytes starting at 0 (0x0) +0x05580 ... 0x05600 +``` + +## Faites l'essai! + +Bravo! Votre firmware customisé a été programmé sur votre clavier! + +Essayez-le et vérifiez qu'il fonctionne comme vous le souhaitez. Nous avons écrit [Tester et débugger](newbs_testing_debugging.md) pour compléter le guide du débutant, alors allez voir là-bas pour apprendre comment dépanner vos fonctionnalités custom. diff --git a/docs/fr-fr/newbs_getting_started.md b/docs/fr-fr/newbs_getting_started.md new file mode 100644 index 00000000000..8a8029fd145 --- /dev/null +++ b/docs/fr-fr/newbs_getting_started.md @@ -0,0 +1,101 @@ +# Introduction + +Votre clavier d'ordinateur contient un processeur, proche de celui dans votre ordinateur. Ce processeur exécute un logiciel responsable de détecter les touches appuyées et envoie des rapports à propos de l'état du clavier lorsque les touches sont appuyées et relâchées. QMK prend le rôle de ce logiciel, détectant les appuis des boutons et passant cette information à l'ordinateur hôte. Lorsque vous construisez votre keymap customisée, vous créez l'équivalent d'un programme exécutable pour votre clavier. + +QMK essaie de rendre les choses simples faciles, et les choses difficiles possibles. Vous n'avez pas à savoir programmer pour créer des keymaps puissantes - vous devez seulement suivre quelques règles de syntaxe simples. + +# Guide de démarrage + +Avant de pouvoir construire des keymaps, vous devez installer quelques logiciels et configurer votre environnement de compilation. Ceci n'a besoin d'être fait seulement une fois, peu importe le nombre de clavier pour lesquels vous compter compiler un firmware. + +Si vous préférez une approche plus proche d'une interface graphique, considérez utiliser l'outil en ligne [QMK Configurator](https://config.qmk.fm). Référez-vous à [Construire votre premier firmware en utilisant l'interface graphique en ligne](newbs_building_firmware_configurator.md). + +## Logiciels à télécharger + +### Editeur de texte + +Vous allez avoir besoin d'un programme qui peut éditer et sauvegarder des fichiers **plain text**. Si vous êtes sur Windows, vous pouvez utiliser notepad et sur Linux vous pouvez utiliser gedit. Ces deux options sont des éditeurs de texte simples mais fonctionnels. Sur macOS, faites attention avec l'application par défaut TextEdit: elle ne sauvegardera pas les fichiers en mode "plain text" sauf si vous sélectionnez explicitement _Make Plain Text_ à partir du menu _Format_. + +Vous pouvez aussi télécharger et installer un éditeur de texte dédié comme [Sublime Text](https://www.sublimetext.com/) ou [VS Code](https://code.visualstudio.com/). C'est probablement la meilleure solution peu importe la plateforme car ce sont des programmes conçus spécifiquement pour éditer du code. + +?> Pas sûr de quel éditeur de texte utiliser? Laurence Bradford a écrit une [excellente introduction](https://learntocodewith.me/programming/basics/text-editors/) au sujet. + +### QMK Toolbox + +QMK Toolbox est un programme graphique optionnel pour Windows et macOS qui permet à la fois de programmer et débugger votre clavier customisé. Il vous sera probablement très utile pour facilement flasher votre clavier et analyser ses messages de débugage. + +[Télécharger la dernière version ici.](https://github.com/qmk/qmk_toolbox/releases/latest) + +* Pour Windows: `qmk_toolbox.exe` (portable) or `qmk_toolbox_install.exe` (installeur) +* Pour macOS: `QMK.Toolbox.app.zip` (portable) or `QMK.Toolbox.pkg` (installeur) + +## Configurez votre environnement + +Nous avons essayé de rendre QMK aussi simple que possible à configurer. Vous avez uniquement à préparer votre environnment Linux ou Unix et laisser QMK installer le reste. + +?> Si vous n'avez jamais travaillé avec la ligne de commande Linux/Unix, il y a un certain nombre de concepts basiques et de commandes que vous devriez apprendre. Ces ressources vous apprendrons suffisemment pour travailler avec QMK:
+[Commandes Linux à savoir](https://www.guru99.com/must-know-linux-commands.html)
+[Commandes Unix de base](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html) + +### Windows + +Vous devez installer MSYS2 et Git. + +* Suivez les instructions d'installation sur la [page de MSYS2](http://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`. + +### macOS + +Vous devez installer Homebew. Suivez les instructions sur la [page de Homebrew](https://brew.sh). + +Une fois Homebrew installé, continuez avec _Configurer QMK_. Dans cette étape, nous lancerons un script qui va installer d'autres paquets. + +### Linux + +Vous devez installer Git. Il est très probable que vous l'ayez déjà installé, mais sinon, une des commandes suivantes devrait l'installer: + +* Debian / Ubuntu / Devuan: `apt-get install git` +* Fedora / Red Hat / CentOS: `yum install git` +* Arch: `pacman -S git` + +?> Docker est aussi une option sur toutes les plateformes. [Appuyez ici pour plus de détail.](getting_started_build_tools.md#docker) + +## Configurer QMK + +Une fois votre environnement Linux/Unix configuré, vous êtes prêt à télécharger QMK. Nous allons le faire en utilisant Git pour "cloner" le dépôt de QMK. Ouvrez un terminal ou une fenêtre MSYS2 MinGW et gardez le ouvert pour le reste de ce guide. Dans ce terminal, lancez ces deux commandes: + +```shell +git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git +cd qmk_firmware +``` + +?> Si vous savez déjà [comment utiliser GitHub](getting_started_github.md), nous recommandons que vous créez et clonez votre propre fork. Si vous ne savez pas ce que cela veut dire, vous pouvez sans problème ignorer ce message. + +QMK vient avec un script pour vous aider à configurer le reste de ce que vous aurez besoin. Vous devez le lancer en tapant la ligne de commande suivante: + + util/qmk_install.sh + +## Testez votre environnement de compilation + +Maintenant que votre environnement de compilation de QMK est configuré, vous pouvez compiler un firmware pour votre clavier. Démarrez en compilant la keymap par défaut du clavier. Vous devriez pouvoir le faire avec une commande de ce format: + + make :default + +Par exemple, pour compiler un firmware pour une Clueboard 66%, vous utiliserez: + + make clueboard/66/rev3:default + +Une fois ceci fait, vous devriez avoir beaucoup d'information dans votre sortie qui devrait se terminer par quelque chose de similaire à ça: + +``` +Linking: .build/clueboard_66_rev3_default.elf [OK] +Creating load file for flashing: .build/clueboard_66_rev3_default.hex [OK] +Copying clueboard_66_rev3_default.hex to qmk_firmware folder [OK] +Checking file size of clueboard_66_rev3_default.hex [OK] + * The firmware size is fine - 26356/28672 (2316 bytes free) +``` + +# Créer votre Keymap + +Vous êtes maintenant prêt à créer votre propre keymap! Passez à l'étape [Compiler votre premier firmware](newbs_building_firmware.md) pour ce faire. diff --git a/docs/fr-FR/newbs_learn_more_resources.md b/docs/fr-fr/newbs_learn_more_resources.md similarity index 100% rename from docs/fr-FR/newbs_learn_more_resources.md rename to docs/fr-fr/newbs_learn_more_resources.md diff --git a/docs/fr-fr/newbs_testing_debugging.md b/docs/fr-fr/newbs_testing_debugging.md new file mode 100644 index 00000000000..680d7644ed2 --- /dev/null +++ b/docs/fr-fr/newbs_testing_debugging.md @@ -0,0 +1,102 @@ +# Test et débugage + +Une fois votre clavier configuré avec un firmware custom, vous êtes prêt à le tester. Avec un peu de chance, tout fonctionne parfaitement bien, dans le cas contraire, ce document vous aidera à trouver où se trouve le problème. + +## Tester + +Tester votre clavier est normalement assez simple. Appuyez chaque touche de votre clavier et assurez-vous qu'il envoie les touches auquel vous vous attendiez. Il existe même des programmes qui vous aideront à vérifier qu'aucune touche ne soit oubliée. + +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) + +## Débuguer + +Votre clavier va envoyer des informations de débugage si vous avez `CONSOLE_ENABLE = yes` dans votre fichier `rules.mk`. Par défaut, la sortie est très limitée, mais vous pouvez activer le mode debug pour augmenter la quantité de sortie de débugage. Utilisez le keycode `DEBUG` dans votre keymap, utilisez la fonction [Commande](feature_command.md) pour activer le mode debug ou ajoutez le code suivant à votre 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; +} +``` + +### Débuguer avec QMK Toolbox + +Pour les plateformes compatibles, [QMK Toolbox](https://github.com/qmk/qmk_toolbox) peut être utilisé pour afficher les messages de débugage pour votre clavier. + +### Débuguer avec hid_listen + +Vous préférez une solution basée sur le terminal? [hid_listen](https://www.pjrc.com/teensy/hid_listen.html), fourni par PJRC, peut aussi être utilisé pour afficher des messages de débugage. Des versions compilées pour Windows, Linux et MacOS sont disponibles. + + + +## Envoyer vos propres messages de débugage + +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 + +Une fois fait, vous pouvez utiliser les fonctions print suivantes: + +* `print("string")`: Affiche une simple chaîne de caractères. +* `uprintf("%s string", var)`: Affiche une chaîne de caractères formatée. +* `dprint("string")` Affiche une chaîne de caractère simple, mais uniquement lorsque le mode debug est activé. +* `dprintf("%s string", var)`: Affiche une chaîne de caractère formatée, mais uniquement lorsque le mode debug est activé. + +## Exemples de debugage + +Si dessous se trouve une liste d'exemples réels de débugage. Pour plus d'information, référez-vous à [Débuguer/Dépanner QMK](faq_debug.md). + +### A quelle position de la matrice se trouve cette activation de touche? + +Lors du portage ou lorsque vous essayez de diagnostiquer un problème de PCB, il est utile de savoir si une activation de touche est enregistrée correctement. Pour activer le log de ce scénario, ajoutez le code suivant à votre fichier 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: %u, col: %u, row: %u, pressed: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed); +#endif + return true; +} +``` + +Exemple de sortie + +```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 +``` + +### Combien de temps cela a pris pour une activation de touche? + +Lorsque vous testez des problèmes de performance, il peut être utile de savoir à quelle fréquence la matrice est scannée. Pour activer le log dans ce scénario, ajoutez la ligne suivante à votre fichier `config.h` de votre keymaps. + +```c +#define DEBUG_MATRIX_SCAN_RATE +``` + +Exemple de sortie + +```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 +``` diff --git a/docs/getting_started_build_tools.md b/docs/getting_started_build_tools.md deleted file mode 100644 index 268cc94c380..00000000000 --- a/docs/getting_started_build_tools.md +++ /dev/null @@ -1,155 +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. - -## Windows (Vista and Later) (Deprecated) - -These are the old instructions for Windows Vista and later. We recommend you use [MSYS2 as outlined above](#windows-with-msys2-recommended). - -1. If you have ever installed WinAVR, uninstall it. -2. Install [MHV AVR Tools](https://infernoembedded.com/sites/default/files/project/MHV_AVR_Tools_20131101.exe). Disable smatch, but **be sure to leave the option to add the tools to the PATH checked**. -3. If you are going to flash Infinity based keyboards you will need to install dfu-util, refer to the instructions by [Input Club](https://github.com/kiibohd/controller/wiki/Loading-DFU-Firmware). -4. Install [MinGW](https://sourceforge.net/projects/mingw/files/Installer/mingw-get-setup.exe/download). During installation, uncheck the option to install a graphical user interface. **DO NOT change the default installation folder.** The scripts depend on the default location. -5. Clone this repository. [This link will download it as a zip file, which you'll need to extract.](https://github.com/qmk/qmk_firmware/archive/master.zip) Open the extracted folder in Windows Explorer. -6. Open the `\util` folder. -7. Double-click on the `1-setup-path-win` batch script to run it. You'll need to accept a User Account Control prompt. Press the spacebar to dismiss the success message in the command prompt that pops up. -8. Right-click on the `2-setup-environment-win` batch script, select "Run as administrator", and accept the User Account Control prompt. This part may take a couple of minutes, and you'll need to approve a driver installation, but once it finishes, your environment is complete! - -If you have trouble and want to ask for help, it is useful to generate a *Win_Check_Output.txt* file by running `Win_Check.bat` in the `\util` folder. - -## 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:dfu-util -``` -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..e5309fdbbf5 --- /dev/null +++ b/docs/getting_started_docker.md @@ -0,0 +1,47 @@ +# 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` install. +* [Docker CE](https://docs.docker.com/install/#supported-platforms) + +## 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) +``` + +## 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 aeb8738b772..ae594f68d81 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](http://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](http://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) -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 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' ``` 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,7 +54,7 @@ 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) diff --git a/docs/getting_started_introduction.md b/docs/getting_started_introduction.md index e183d77eeb5..6dc51b82b73 100644 --- a/docs/getting_started_introduction.md +++ b/docs/getting_started_introduction.md @@ -4,7 +4,7 @@ This page attempts to explain the basic information you need to know to work wit ## Basic QMK Structure -QMK is a fork of [Jun Wako](https://github.com/tmk)'s [tmk_keyboard](https://github.com/tmk/tmk_keyboard) project. The original TMK code, with modifications, can be found in the `tmk` folder. The QMK additions to the project may be found in the `quantum` folder. Keyboard projects may be found in the `handwired` and `keyboard` folders. +QMK is a fork of [Jun Wako](https://github.com/tmk)'s [tmk_keyboard](https://github.com/tmk/tmk_keyboard) project. The original TMK code, with modifications, can be found in the `tmk_core` folder. The QMK additions to the project may be found in the `quantum` folder. Keyboard projects may be found in the `handwired` and `keyboard` folders. ### Userspace Structure diff --git a/docs/getting_started_make_guide.md b/docs/getting_started_make_guide.md index d1ecf6f5a64..df82a001f04 100644 --- a/docs/getting_started_make_guide.md +++ b/docs/getting_started_make_guide.md @@ -14,8 +14,8 @@ 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. -* `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:dfu`. +* `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`. * `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. You can also add extra options at the end of the make command line, after the target @@ -31,7 +31,7 @@ Here are some examples commands * `make all:all` builds everything (all keyboard folders, all keymaps). Running just `make` from the `root` will also run this. * `make ergodox_infinity:algernon:clean` will clean the build output of the Ergodox Infinity keyboard. -* `make planck/rev4:default:dfu COLOR=false` builds and uploads the keymap without color output. +* `make planck/rev4:default:flash COLOR=false` builds and uploads the keymap without color output. ## `rules.mk` Options @@ -59,7 +59,7 @@ To disable debug messages (*dprint*) and reduce the .hex file size, include `#de To disable print messages (*print*, *xprintf*) and user print messages (*uprint*) and reduce the .hex file size, include `#define NO_PRINT` in your `config.h` file. -To disable print messages (*print*, *xprintf*) and **KEEP** user print messages (*uprint*), include `#define USER_PRINT` in your `config.h` file. +To disable print messages (*print*, *xprintf*) and **KEEP** user print messages (*uprint*), include `#define USER_PRINT` in your `config.h` file (do not also include `#define NO_PRINT` in this case). To see the text, open `hid_listen` and enjoy looking at your printed messages. @@ -135,7 +135,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 b62524271c2..7a4541cfc63 100644 --- a/docs/getting_started_vagrant.md +++ b/docs/getting_started_vagrant.md @@ -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. @@ -40,7 +39,7 @@ vagrant plugin install vagrant-vbguest Finished with your environment? From anywhere inside the folder where you checked out this project, Execute: ```console -vagrant destory +vagrant destroy ``` ### What if I want to use Docker directly? @@ -54,4 +53,4 @@ Execute the following to bypass the `vagrant` user booting directly to the offic ```console vagrant ssh -c 'sudo -i' -``` \ No newline at end of file +``` diff --git a/docs/hand_wire.md b/docs/hand_wire.md index 25db9341b88..0c5b4f45f4d 100644 --- a/docs/hand_wire.md +++ b/docs/hand_wire.md @@ -1,142 +1,121 @@ -# Quantum Hand-Wiring Guide +# Hand-Wiring Guide -Parts list: +## Parts list + +You will need: (where *x* is the number of keys on your planned keyboard) + +* QMK compatible microcontroller board (Teensy, Pro-Micro, QMK Proton C etc.) * *x* keyswitches (MX, Matias, Gateron, etc) -* *x* diodes -* Keyboard plate (metal, plastic, cardboard, etc) -* Wire (strained for wiring to the Teensy, anything for the rows/columns) -* Soldering iron set at 600ºF or 315ºC (if temperature-controlled) -* Rosin-cored solder (leaded or lead-free) +* *x* through hole diodes +* Keyboard plate and plate mount stabilisers +* Wire +* Soldering iron +* Rosin-cored solder * Adequate ventilation/a fan -* Tweezers (optional) * Wire cutters/snippers -## How the Matrix Works (Why We Need Diodes) +Optional but useful: -The microcontroller (in this case, the Teensy 2.0) 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: +* Wire strippers/a sharp knife +* Tweezers and/or small needle nose pliers +* Soldering station/Helping hands - 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) +## Starting the build -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. +There are many ways to hand wire a PCB matrix, this guide will describe the fundamentals as well as some recommended ways to go about it. -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: +As we are dealing with hand wiring, it is assumed that you already have a plate. If you are planning a completely custom layout, tools such as [ai03 Plate Generator](https://kbplate.ai03.me/) and [Swillkb Plate & Case Builder](http://builder.swillkb.com/) can help when designing one. - 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) +Start by installing the switches and stabilisers in the plate. Depending on the thickness and material this may also involve hot gluing it in place. -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 +## Planning the matrix - col0: 0b01 - col1: 0b00 - │└row0 - └row1 +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. -A problem arises when you start pressing more than one key at a time. Looking at our matrix again, it should become pretty obvious: +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). - 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) +It is fairly simple to plan for an ortholinear keyboard (like a Planck). - Remember that this ^ is still connected to row1 +![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/) -The data we get from that is: +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). - col0: 0b11 - col1: 0b11 - │└row0 - └row1 +![Example ISO matrix](https://i.imgur.com/UlJ4ZDP.png) -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; +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. - 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 ─────┴────────┘ +### Common Microcontroller Boards -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: `>|` +| 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) | +| 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) | -Now when we press the three keys, invoking what would be a ghosting scenario: +*Elite C is essentially the same as a Pro Micro with a USB-C instead of Micro-USB - 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 ─────┴────────┘ +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. -Things act as they should! Which will get us the following data: +Postage board mini mounted in place - col0: 0b01 - col1: 0b11 - │└row0 - └row1 +| Board | Controller | # I/O | +| :------------ |:-------------:| ------:| +| [Swiss helper](https://www.reddit.com/r/MechanicalKeyboards/comments/8jg5d6/hand_wiring_this_might_help/) | ATmega32u4 | 20 | +| [Postage board](https://github.com/LifeIsOnTheWire/Postage-Board/)| ATmega32u4| 25 | +| [Postage board mini](https://geekhack.org/index.php?topic=101460.0)| ATmega32u4| 25 | -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. +## Wiring the matrix -# The Actual Hand-Wiring +There is no one right way to do this. What you want to achieve is good connection at all of the joints planned and no unintentional shorts. -## Getting Things in Place +Established materials and techniques include: -When starting this, you should have all of your stabilisers and keyswitches already installed (and optionally keycaps). If you're using a Cherry-type stabiliser (plate-mounted only, obviously), you'll need to install that before your keyswitches. If you're using Costar ones, you can installed them afterwards. +| Technique | Examples | Pros | Cons | Image +| :-----------| :------- | :------ | :--- | :--- +| 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) +| 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) +| 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) -To make things easier on yourself, make sure all of the keyswitches are oriented the same way (if they can be - not all layouts support this). Despite this, it's important to remember that the contacts on the keyswitches are completely symmetrical. We'll be using the keyswitch's left side contact for wiring the rows, and the right side one for wiring the columns. -Get your soldering iron heated-up and collect the rest of the materials from the part list at the beginning of the guide. Place your keyboard so that the bottoms of the keyswitches are accessible - it may be a good idea to place it on a cloth to protect your keyswitches/keycaps. +Note that these methods can be combined. Prepare your lengths of wire before moving on to soldering. -Before continuing, plan out where you're going to place your Teensy. If you're working with a board that has a large (6.25u) spacebar, it may be a good idea to place it in-between switches against the plate. Otherwise, you may want to trim some of the leads on the keyswitches where you plan on putting it - this will make it a little harder to solder the wire/diodes, but give you more room to place the Teensy. -## Preparing the Diodes +### A note on split keyboards -It's a little easier to solder the diodes in place if you bend them at a 90º angle immediately after the black line - this will help to make sure you put them on the right way (direction matters), and in the correct position. The diodes will look like this when bent (with longer leads): +If you are planning a split keyboard (e.g. Dactyl) each half will require a controller and a means of communicating between them (like a TRRS or hardwired cable). Further information can be found in the [QMK split keyboard documentation.](feature_split_keyboard.md) -``` - ┌─────┬─┐ - ───┤ │ ├─┐ - └─────┴─┘ │ - │ -``` -We'll be using the long lead at the bent end to connect it to the elbow (bent part) of the next diode, creating the row. +### Soldering -## Soldering the Diodes +There are a lot of soldering guides and tips available elsewhere but here are some of the most useful and relevant for hand wiring: -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: +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. -``` - │o - ┌┴┐ o - │ │ O - ├─┤ - └┬┘ - └───────────── -``` +Looped around rod Looped diode leg + +If your diodes are on a packaging strip and need a bend in them (either the start of a loop or for connecting to its neighbour) this can easily done by bending it over something straight like the edge of a box, table, or ruler. This also helps keep track of the direction of the diode as all the bends will be on the same side. + +Bent diode legs + +If your iron has temperature control, set it to 315ºC (600ºF). + +Once heated, tin your soldering iron - this means melting a small amount of solder on the end of the iron and then quickly wiping it off on a wet sponge or wire cleaning pad, leaving a shiny silvery coating on the end which helps keep oxidisation at bay and helps solder to flow. + +When you come to apply the solder, hold the soldering iron against the two surfaces for a second to heat it, then apply a small amount of solder to join the two pieces together. Heating the surfaces ensures that the solder adheres to it and that it does not cool too quickly. + +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. + +#### 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: + +![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. @@ -146,20 +125,13 @@ After soldering things in place, it may be helpful to blow on the joint to push 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. @@ -169,172 +141,104 @@ 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 Things to the Teensy +## Wiring up the controller -Now that the matrix itself is complete, it's time to connect what you've done to the Teensy. You'll be needing the number of pins equal to your number of columns + your number of rows. 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. +Now that the matrix itself is complete, it's time to connect what you've done to the microcontroller board. -The pins you'll absolutely have to avoid are: GND, VCC, AREF, and RST - all the others are usable and accessible in the firmware. +Place the microcontroller where you want it to be located, give thought to mounting and case alignment. Bear in mind that the location of the USB socket can be different from the controller by using a short male to female cable if required,. -Place the Teensy where you plan to put it - you'll have to cut wires to length in the next step, and you'll want to make sure they reach. +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. -Starting with the first column on the right side, measure out how much wire you'll need to connect it to the first pin on the Teensy - it helps to pick a side that you'll be able to work down, to keep the wires from overlapping too much. It may help to leave a little bit of slack so things aren't too tight. Cut the piece of wire, and solder it to the Teensy, and then the column - you can solder it anywhere along the column, but it may be easiest at the keyswitch. Just be sure the wire doesn't separate from the keyswitch when soldering. +---- -As you move from column to column, it'll be helpful to write the locations of the pins down. We'll use this data to setup the matrix in the future. +### Specific instructions for the Teensy 2.0 -When you're done with the columns, start with the rows in the same process, from top to bottom, and write them all down. Again, 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. +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. -As you move along, be sure that the Teensy is staying in place - recutting and soldering the wires is a pain! +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. -## Additional guides +---- -If you're more of a visual learner, or want some additional tips and something more to follow along, these two visual step by step guides may be helpful: -- [BrownFox's step by step guide](https://deskthority.net/viewtopic.php?f=7&t=6050) -- [Cribbit's modern hand wiring guide](https://geekhack.org/index.php?topic=87689.0) +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. -# Getting Some Basic Firmware Set Up +Ribbon cable can be used to keep this extra tidy. You may also want to consider routing the wires beneath the exisiting columns/rows. -From here, you should have a working keyboard once you program a firmware. Before we attach the Teensy permanently to the keyboard, let's quickly get some firmware loaded onto the Teensy so we can test each keyswitch. +Ribbon Cable -To start out, download [the firmware](https://github.com/qmk/qmk_firmware/) - we'll be using my (Jack's) fork of TMK called QMK/Quantum. 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). +As you solder the wires to the controller make a note of which row/column is going to which pin on the controller as we'll use this data to setup the matrix when we create the firmware. -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: +As you move along, be sure that the controller is staying in place - recutting and soldering the wires is a pain! -``` -./util/new_keyboard.sh -``` -You'll want to navigate to the `keyboards//` folder by typing, like the print-out from the script specifies: +## Getting Some Basic Firmware Set Up -``` -cd keyboards/ -``` +From here, you should have a working keyboard once you program a firmware. -### `config.h` +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). -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. +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). -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). +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: -### `.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; } -``` + ``` +4. Save and close `keymap.c`. -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. +## Flashing the Firmware -Let's say that instead, we wired our keyboard like this (a fair thing to do): +Install [QMK Toolbox](https://github.com/qmk/qmk_toolbox). -``` - ┌───┬───┬───┐ - │ ┋ │ ┋│ ┋ │ - ├─┋─┴─┬┋┴───┤ - │ ┋ │┋ │ - └─────┴─────┘ -``` +![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") -This would require our `LAYOUT` definition to look like this: +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)). -``` - #define LAYOUT( \ - k00, k01, k02, \ - k10, k11, \ - ) \ - { \ - { k00, k01, k02 }, \ - { k10, k11, KC_NO }, \ - } -``` +Plug in your keyboard and press the reset button (or short the Reset and Ground pins if there is no button) and click the "Flash" button in QMK toolbox. -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! ## Testing Your Firmware -Carefully flip your keyboard over, open up a new text document, and try typing - you should get the characters that you put into your keymap. Test each key, and note 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](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: -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. +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. -# Securing the Teensy, Finishing Your Hardware, Getting Fancier Firmware +## Finishing up -Now that you have a working board, it's time to get things in their permanent positions. I've often used liberal amounts of hot glue to secure and insulate things, so if that's your style, start spreading that stuff like butter. Otherwise, double-sided tape is always an elegant solution, and electrical tape is a distant second. Due to the nature of these builds, a lot of this part is up to you and how you planned (or didn't plan) things out. +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. -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 (Planck, Clueboard, Ergodox EZ, etc) to see how people use all of them. You can always stop by [the OLKB subreddit for help!](http://reddit.com/r/olkb) +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! + +## 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/) + + +# 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 0c1b31bb26a..2c0f2e9a1ac 100644 --- a/docs/hardware_avr.md +++ b/docs/hardware_avr.md @@ -1,6 +1,6 @@ # Keyboards with AVR Processors -This page describes the support for for AVR processors in QMK. AVR processors include the atmega32u4, atmega32u2, at90usb1286, and other processors from Atmel Corporation. AVR processors are 8-bit MCU's that are designed to be easy to work with. The most common AVR processors in keyboards have on-board USB and plenty of GPIO for supporting large keyboard matrices. They are the most popular MCU for use in keyboards today. +This page describes the support for for AVR processors in QMK. AVR processors include the atmega32u4, atmega32u2, at90usb1286, and other processors from Atmel Corporation. AVR processors are 8-bit MCUs that are designed to be easy to work with. The most common AVR processors in keyboards have on-board USB and plenty of GPIO for supporting large keyboard matrices. They are the most popular MCU for use in keyboards today. If you have not yet you should read the [Keyboard Guidelines](hardware_keyboard_guidelines.md) to get a sense of how keyboards fit into QMK. @@ -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,7 +75,6 @@ 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. diff --git a/docs/hardware_drivers.md b/docs/hardware_drivers.md index 023e92982cb..7e89c0d2b9a 100644 --- a/docs/hardware_drivers.md +++ b/docs/hardware_drivers.md @@ -20,9 +20,9 @@ Support for SSD1306 based OLED displays. For more information see the [OLED Driv ## uGFX -You can make use of uGFX within QMK to drive character and graphic LCD's, LED arrays, OLED, TFT, and other display technologies. This needs to be better documented, if you are trying to do this and reading the code doesn't help please [open an issue](https://github.com/qmk/qmk_firmware/issues/new) and we can help you through the process. +You can make use of uGFX within QMK to drive character and graphic LCDs, LED arrays, OLED, TFT, and other display technologies. This needs to be better documented, if you are trying to do this and reading the code doesn't help please [open an issue](https://github.com/qmk/qmk_firmware/issues/new) and we can help you through the process. -## WS2812 (AVR Only) +## WS2812 Support for WS2811/WS2812{a,b,c} LED's. For more information see the [RGB Light](feature_rgblight.md) page. @@ -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..a862bc0ca88 100644 --- a/docs/hardware_keyboard_guidelines.md +++ b/docs/hardware_keyboard_guidelines.md @@ -61,10 +61,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. diff --git a/docs/he-il/README.md b/docs/he-il/README.md new file mode 100644 index 00000000000..c16801b2bd1 --- /dev/null +++ b/docs/he-il/README.md @@ -0,0 +1,34 @@ +
+# קושחה עבור Quantum Mechanical Keyboard + +[![גירסה נוכחית](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags) +[![מצב הבניה](https://travis-ci.org/qmk/qmk_firmware.svg?branch=master)](https://travis-ci.org/qmk/qmk_firmware) +[![ערוץ דיסקורד](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh) +[![מצב מסמכים](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm) +[![תומכי GitHub](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly) +[![מזלגות GitHub](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/) + +## מה היא קושחת 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, הדבר הקל ביותר הוא [לעשות פורק לריפו ב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`). + +## איך לקמפל + +לפני שתצליחו לקמפל, תדרשו [להתקין סביבה](he-il/getting_started_build_tools.md) עבור פיתוח AVR ו/או ARM. ברגע שהדבר בוצע, תוכלו להריץ פקודת `make` כדי לבנות מקלדת ומיפוי עם התחביר הבא: + + make planck/rev4:default + +כך תוכלו לבנות את גרסא `rev4` של ה `planck` עם מיפוי ברירת המחדל (`default`). לא כל המקלדות בעלות גרסאות (נקרא גם תת-פרוייקט או תיקייה), במקרה כזה, אפשר להריץ את הפקודה הבאה: + + make preonic:default + +## איך להתאים + +לQMK יש המון [יכולות](he-il/features.md) שאפשר לנווט בהן, וכמות נכבדת של [תיעוד ודוקומנטציה](http://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 new file mode 100644 index 00000000000..148eb6400d8 --- /dev/null +++ b/docs/he-il/_summary.md @@ -0,0 +1,140 @@ +
+ +**בשפה העברית** +* [המדריך המלא למתחילים](he-il/newbs.md) + * [מקורות ללמידה](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) + * [קבלת עזרה](he-il/getting_started_getting_help.md) +* [שאלות נפוצות](he-il/faq.md) + * [שאלות נפוצות כלליות](he-il/faq_general.md) +* [חומרה](he-il/hardware.md) +* התייחסויות + * [איך לתעד נכון](he-il/documentation_best_practices.md) + +**בשפה האנגלית** +* [המדריך המלא למתחילים](he-il/newbs.md) + * [התחלה](he-il/newbs_getting_started.md) + * [בנייה של הקושחה הראשונה שלך](he-il/newbs_building_firmware.md) + * [צריבה של הקושחה](he-il/newbs_flashing.md) + * [בדיקות ודיבאגינג](he-il/newbs_testing_debugging.md) + * [עבודה נכונה ב GIT](he-il/newbs_best_practices.md) + * [מקורות ללמידה](he-il/newbs_learn_more_resources.md) + +* [בסיס QMK](he-il/README.md) + * [מבוא לQMK](he-il/getting_started_introduction.md) + * [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) + * [קבלת עזרה](he-il/getting_started_getting_help.md) + +* [שינויים משמעותיים](he-il/breaking_changes.md) + * [2019 Aug 30](he-il/ChangeLog/20190830.md) + +* [שאלות נפוצות](he-il/faq.md) + * [שאלות נפוצות כלליות](he-il/faq_general.md) + * [בנייה/קומפילציה של QMK](he-il/faq_build.md) + * [דיבאגינג ופתרון תקלות של QMK](he-il/faq_debug.md) + * [מיפוי מקשים](he-il/faq_keymap.md) + * [התקנת דרייברים עם Zadig](he-il/driver_installation_zadig.md) + +* מדריכים מפורטים + * [התקנת כלי Build](he-il/getting_started_build_tools.md) + * [מדריך Vagrant](he-il/getting_started_vagrant.md) + * [הוראות בנייה/קומפילציה](he-il/getting_started_make_guide.md) + * [צריבת קושחה](he-il/flashing.md) + * [התאמה אישית של הפונקציונאליות](he-il/custom_quantum_functions.md) + * [מיפוי מקשים](he-il/keymap.md) + +* [חומרה](he-il/hardware.md) + * [מעבדי AVR](he-il/hardware_avr.md) + * [דרייברים](he-il/hardware_drivers.md) + +* התייחסויות + * [מדריך למקלדות](he-il/hardware_keyboard_guidelines.md) + * [אפשרויות הגדרות](he-il/config_options.md) + * [קודי מקשים](he-il/keycodes.md) + * [קונבנציות קוד - C](he-il/coding_conventions_c.md) + * [קונבנציות קוד - Python](he-il/coding_conventions_python.md) + * [איך לתעד נכון](he-il/documentation_best_practices.md) + * [טמפלטים לדוקומנטציה](he-il/documentation_templates.md) + * [מילון](he-il/reference_glossary.md) + * [בדיקות יחידה](he-il/unit_testing.md) + * [פונקציות שימושיות](he-il/ref_functions.md) + * [תמיכה בConfigurator](he-il/reference_configurator_support.md) + * [פורמט info.json](he-il/reference_info_json.md) + * [פיתוח בPython CLI](he-il/cli_development.md) + +* [תכונות](he-il/features.md) + * [Basic Keycodes](he-il/keycodes_basic.md) + * [US ANSI Shifted Keys](he-il/keycodes_us_ansi_shifted.md) + * [Quantum Keycodes](he-il/quantum_keycodes.md) + * [Advanced Keycodes](he-il/feature_advanced_keycodes.md) + * [Audio](he-il/feature_audio.md) + * [Auto Shift](he-il/feature_auto_shift.md) + * [Backlight](he-il/feature_backlight.md) + * [Bluetooth](he-il/feature_bluetooth.md) + * [Bootmagic](he-il/feature_bootmagic.md) + * [Combos](he-il/feature_combo.md) + * [Command](he-il/feature_command.md) + * [Debounce API](he-il/feature_debounce_type.md) + * [DIP Switch](he-il/feature_dip_switch.md) + * [Dynamic Macros](he-il/feature_dynamic_macros.md) + * [Encoders](he-il/feature_encoders.md) + * [Grave Escape](he-il/feature_grave_esc.md) + * [Haptic Feedback](he-il/feature_haptic_feedback.md) + * [HD44780 LCD Controller](he-il/feature_hd44780.md) + * [Key Lock](he-il/feature_key_lock.md) + * [Layouts](he-il/feature_layouts.md) + * [Leader Key](he-il/feature_leader_key.md) + * [LED Matrix](he-il/feature_led_matrix.md) + * [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/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) + * [RGB Matrix](he-il/feature_rgb_matrix.md) + * [Space Cadet](he-il/feature_space_cadet.md) + * [Split Keyboard](he-il/feature_split_keyboard.md) + * [Stenography](he-il/feature_stenography.md) + * [Swap Hands](he-il/feature_swap_hands.md) + * [Tap Dance](he-il/feature_tap_dance.md) + * [Terminal](he-il/feature_terminal.md) + * [Thermal Printer](he-il/feature_thermal_printer.md) + * [Unicode](he-il/feature_unicode.md) + * [Userspace](he-il/feature_userspace.md) + * [Velocikey](he-il/feature_velocikey.md) + +* למייקרים ומודרים + * [מדריך לכתיבה ידנית](he-il/hand_wire.md) + * [מדריך לצריבת 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) + +* להבנה עמוקה יותר + * [איך עובדות מקלדות](he-il/how_keyboards_work.md) + * [להבין את QMK](he-il/understanding_qmk.md) + +* נושאים נוספים + * [שימוש ב - Eclipse עם QMK](he-il/other_eclipse.md) + * [שימוש ב - VSCode עם QMK](he-il/other_vscode.md) + * [תמיכה](he-il/getting_started_getting_help.md) + * [כיצד להוסיף תרגום](he-il/translating.md) + +* QMK מבפנים (בתהליך) + * [Defines](he-il/internals_defines.md) + * [Input Callback Reg](he-il/internals_input_callback_reg.md) + * [Midi Device](he-il/internals_midi_device.md) + * [Midi Device Setup Process](he-il/internals_midi_device_setup_process.md) + * [Midi Util](he-il/internals_midi_util.md) + * [Send Functions](he-il/internals_send_functions.md) + * [Sysex Tools](he-il/internals_sysex_tools.md) + +
diff --git a/docs/he-il/documentation_best_practices.md b/docs/he-il/documentation_best_practices.md new file mode 100644 index 00000000000..90c4a137a04 --- /dev/null +++ b/docs/he-il/documentation_best_practices.md @@ -0,0 +1,67 @@ +
+# איך לתעד נכון + +עמוד זה קיים כדי לתעד את השיטות הטובות ביותר כאשר כותבים תיעוד עבור QMK. מעקב אחר הוראות אלה יעזור לשמור על סגנון וטון עקביים, אשר בתורם יעזרו לאנשים אחרים להבין טוב יותר את QMK. + +# פתיחת עמוד + +התיעוד שלך צריך בד״כ להפתח עם כותרת בגודל H1, אחריה פסקה אחת של תיאור של מה המשתמש ימצא בעמוד זה. +זכור כי כותרת זו והפסקה ימוקמו ליד תוכן העניינים, אז חשוב לשמור על כותרת קצרה ולהמנע ממשפטים ארוכים ללא פיסוק. + +לדוגמה: + +``` +# הכותרת שלי + +עמוד זה מדבר על היכולת הסופר-מגניבה שלי. אתה יכול להשתמש ביכולת זו כדי להכין קפה, לסחוט תפוזים ולקבל משלוח של ביצים ועוגות מהסופר הקרוב באמצעות רחפן. +``` + +# כותרות + +עמוד התיעוד צריך לאופן כללי לכלול מס׳ כותרות בגודל "H1". רק כותרות מגודל H1 ו- H2 יכללו בתוכן העניינים, אז חשוב לתכנן אותם בהתאם. הכותרות לא להיות רחבות מידי כדי למנוע מתוכן העניינים להפוך להיות רחב מידי + +# בלוקי רמיזה מעוצבים + +ניתן להוסיף בלוקי רמיזה מעוצבים שמצויירים מסביב לטקסט כדי למשוך תשומת לב אליו. + +### חשוב + +``` +!> זה חשוב +``` + +יתרנדר כ: + +!> זה חשוב + +### טיפים כלליים + +``` +?> זהו טיפ שימושי. +``` + +יתרנדר כ: + +?> זהו טיפ שימושי. + + +# תיעוד יכולות ופיצ׳ריםDocumenting Features + +אם יוצרים יכולת חדשה ב QMK, צרו עמוד תיעוד עבורה. העמוד לא צריך להיות ארוך במיוחד, מספר משפטים המתארים את היכולת (פיצ׳ר) וטבלה המתארת קודי מקשים רלוונטיים זה מספיק. הנה דוגמה בסיסית: + +```markdown +# הפיצ׳ר המגניב שלי + +עמוד זה מדבר על היכולת הסופר-מגניבה שלי. אתה יכול להשתמש ביכולת זו כדי להכין קפה, לסחוט תפוזים ולקבל משלוח של ביצים ועוגות מהסופר הקרוב באמצעות רחפן. + +## קודי המקשים המגניבים של היכולת שלי + +|Long Name|Short Name|Description| +|---------|----------|-----------| +|KC_COFFEE||Make Coffee| +|KC_CREAM||Order Cream| +|KC_SUGAR||Order Sugar| +``` + +מקמו את התיעוד שלכם בתוך `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 new file mode 100644 index 00000000000..88ea07fbe71 --- /dev/null +++ b/docs/he-il/faq.md @@ -0,0 +1,8 @@ +
+# שאלות נפוצות + +* [כללי](faq_general.md) +* [בנייה או קומפילציה של 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 new file mode 100644 index 00000000000..26286d552f0 --- /dev/null +++ b/docs/he-il/faq_general.md @@ -0,0 +1,17 @@ +
+# שאלות נפוצות + +## מה זה QMK? + +[QMK](https://github.com/qmk), קיצור עבור Quantum Mechanical Keyboard, הוא קבוצה של אנשים הבונים כלים עבור מקלדות מותאמות אישית. התחלנו עם [קושחת QMK](https://github.com/qmk/qmk_firmware), פורק של [TMK](https://github.com/tmk/tmk_keyboard) אשר שונה באופן ניכר. + +## מה ההבדלים העיקריים בין QMK ו-Keymap TMK? + +TMK עוצב ומומש במקור ע״י [Jun Wako](https://github.com/tmk). QMK התחיל כפורק של [Jack Humbert](https://github.com/jackhumbert) של הפרוייקט של TMK עבור Planck. אחרי כמה זמן הפורק של ג׳ק השתנה מזה של TMK וב- 2015 ג׳ק החליט לשנות את שמו של הפורק ל- QMK. + +מנק׳ מבט טכנית, QMK נבנה על גבי TMK ע״י הוספת יכולות ופיצ׳רים חדשים. ראוי לציון ש- QMK הרחיב את מס׳ קודי המקלדת האפשריים ומשתמש בהם למימוש יכולות מתקדמות כמו `S()`, `LCTL()`, ו- `MO()`. ניתן לראות רשימה מלאה של קודי המקלדת האלה ב - [קודי מקלדת](keycodes.md). + +מנק׳ מבט של הפרוייקט וניהול הקהילה, 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 new file mode 100644 index 00000000000..e62c9f403dd --- /dev/null +++ b/docs/he-il/getting_started_getting_help.md @@ -0,0 +1,17 @@ +
+# קבלת עזרה + +ישנם משאבים רבים לצורך קבלת עזרה עם QMK. + +## צ׳אט בזמן אמת + +אפשר למצוא מפתחי QMK ומשתמשים [בשרת ה-Discord הראשי שלנו](https://discord.gg/Uq7gcHh). ישנם ערוצים ספציפיים בשרת לצורך שיחות על הקושחה, ארגז הכלים, חומרה והמגדיר. + +## סאב-רדיט OLKB + +הפורום הרשמי של QMK נמצא ב - [/r/olkb](https://reddit.com/r/olkb) באתר [reddit.com](https://reddit.com). + +## סוגיות 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 new file mode 100644 index 00000000000..5cafac5ac56 --- /dev/null +++ b/docs/he-il/getting_started_github.md @@ -0,0 +1,75 @@ +
+# איך להשתמש ב-GitHub עם QMK + +GitHub עלול להיות קצת טריקי למי שלא מכיר את העבודה איתו - מדריך זה ילווה אתכם שלב אחר שלב דרך ביצוע פעולות fork, clone ו-pull request עם QMK. + +?> מדריך זה מניח שאתם מרגישים בנוח עם הרצה של פקודות בסביבת command line (שורת הפקודה) ו-git מותקן במערכת שלכם. + +התחילו ב- [עמוד של QMK ב-GitHub](https://github.com/qmk/qmk_firmware), ותצמאו כפתור בחלק העליון מימין עם התיכוב "Fork": + +![Fork ב-GitHub](http://i.imgur.com/8Toomz4.jpg) + +אם אתם חלק מארגון, תצטרכו לבחור לאיזה חשבון לבצע פעולת fork. ברוב המבקרים, תרצו לבצע fork לתוך החשבון הפרטי שלכם. ברגע שה-fork הסתיים (לפעמים זה יכול לקחת קצת זמן) הקליקו על כפתור ה-"Clone or Download": + +![הורדה מ-GitHub](http://i.imgur.com/N1NYcSz.jpg) + +תוודאו שאתם בוחרים באופצייה של "HTTPS", בחרו את הקישור והעתיקו אותו: + +![קישור HTTPS](http://i.imgur.com/eGO0ohO.jpg) + +מכאן והלאה, הקיש `git clone --recurse-submodules ` בשורת הפקודה והדביקו את הלינק שלכם: + +
+ +``` +user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git +Cloning into 'qmk_firmware'... +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' +``` + +
+ +כעת, יש לכם את ה-fork של QMK על המכונה המקומית שלכם ואתם יכולים להוסיף את מיפויי המקשים שלכם, לקמפל את הפרוייקט ולצרוב אותו על הלוח שלכם. כשאתם שלמים עם השינוי שעשיתם, תוכלו להוסיף, לבצע פעולת commit ולדחוף את השינויים ל-fork שלכם באופן הבא: + +
+ +``` +user@computer:~$ git add . +user@computer:~$ git commit -m "adding my keymap" +[master cccb1608] adding my keymap + 1 file changed, 1 insertion(+) + create mode 100644 keyboards/planck/keymaps/mine/keymap.c +user@computer:~$ git push +Counting objects: 1, done. +Delta compression using up to 4 threads. +Compressing objects: 100% (1/1), done. +Writing objects: 100% (1/1), 1.64 KiB | 0 bytes/s, done. +Total 1 (delta 1), reused 0 (delta 0) +remote: Resolving deltas: 100% (1/1), completed with 1 local objects. +To https://github.com/whoeveryouare/qmk_firmware.git + + 20043e64...7da94ac5 master -> master +``` + +
+ +השינויים שלכם יופיעו ב-fork שלכם ב-GitHub - אם תחזרו לשם (`https://github.com//qmk_firmware`), תוכלו ליצור "Pull Request חדש" ע״י הקשה על הכפתור הבא: + +![Pull Request חדש](http://i.imgur.com/DxMHpJ8.jpg) + +כאן תוכלו לראות בדיוק למה עשיתם commit - אם הכל נראה תקין, תוכלו להשלים את הפעולה ע״י הקשה על "Create Pull Request": + +![צרו Pull Request](http://i.imgur.com/Ojydlaj.jpg) + +אחרי שהגשתם, אנו עלולים לפנות אליכם לגבי השינויים שהצעתם, נבקש שתבצעו שינויים ובסופו של דבר נקבל את השינויים! תודה שתרמתם לפרוייקט QMK :) +
diff --git a/docs/he-il/getting_started_introduction.md b/docs/he-il/getting_started_introduction.md new file mode 100644 index 00000000000..fca86bdaaf4 --- /dev/null +++ b/docs/he-il/getting_started_introduction.md @@ -0,0 +1,72 @@ +
+# מבוא + +עמוד זה מנסה להסביר את המידע הבסיסי אותו תדרשו לדעת כדי לעבוד עם פרוייקט QMK. הוא מניח שאתם יודעים איך לנווט בסביבת Unix Shell, אבל לא מניח שאתם מכירים את שפת C או קומפילציה באמצעות make. + +## מבנה QMK בסיסי + +QMK הוא פורק של הפרוייקט [tmk_keyboard](https://github.com/tmk/tmk_keyboard) של [Jun Wako](https://github.com/tmk). קוד הTMK המקורי, עם התאמות, יכול להמצא בתיקיית `tmk_core`. התוספות של QMK לפרוייקט יכולות להמצא בתיקיית `quantum`. פרוייקטי מקלדות יכולות להמצא בתיקיות `handwired` ו- `keyboard`. + +### מבנה אחסון המשתמש + +בתוך תיקיית `users` יש תיקייה לכל משתמש. זה המקום למשתמשים להוסיף קוד שהם רוצים להשתמש בו במקלדות שונות. מומלץ לעיין במסמך [תכונות אחסון המשתמש](feature_userspace.md) לקבלת מידע נוסף. + +### מבנה פרוייקט המקלדת + +בתוך תיקיית `keyboards`, תת התיקייה `handwired` ותת התיקיות של היצרן והמוכר, לדוגמה `clueboard` היא תיקייה לכל פרוייקט מקלדת - `qmk_firmware/keyboards/clueboard/2x1800` בתוך התיקייה הזאת תמצאו את המבנה הבא: + + +* `keymaps/`: מיפויי מקשים שונים היכולים להבנות +* `rules.mk`: קובץ המגדיר את הגדרות ברירת המחדל של `make`. נא לא לערוך את הקובץ ישירות, במקום זאת, השתמשו בקובץ מיפוי המקשים ספציפי `rules.mk`. +* `config.h`: הקובץ מכיל הגדרות לזמן הקומפילציה. נא לא לערוך את הקובץ ישירות אלא להשתמש בקובץ `config.h` לכל מיפויי מקשים. +* `info.json`: הקובץ מכיל הגדרות פריסה עבור QMK Configurator. צפו ב [תמיכת Configurator](reference_configurator_support.md) למידע נוסף. +* `readme.md`: סקירה כללית של המקלדת. +* `.h`: הקובץ בו פריסת המקלדת מוגדרת אל מול מטריצת המתגים של המקלדת. +* `.c`: הקובץ בו ניתן למצוא קוד מותאם למקלדת. + +למידע נוסף - אנא הכנסו ל [QMK](hardware_keyboard_guidelines.md). +For more information on project structure, see [QMK מדריך למקלדת](hardware_keyboard_guidelines.md). + +### מבנה מפיוי המקשים + +בכל ספריית מיפוי מקשים, הקבצים הבאים עלולים להמצא. רק הקובץ `keymap.c` הוא חובה, אם השאר לא נמצאים, אפשרויות ברירת המחדל יבחרו. +In every keymap folder, the following files may be found. Only `keymap.c` is required, and if the rest of the files are not found the default options will be chosen. + +* `config.h`: ההגדרות השונות עבור מיפוי המקשים. +* `keymap.c`: כל הקודים של מיפוי המקשים, קובץ חובה +* `rules.mk`: אילו יכולות של QMK מאופשרות. +* `readme.md`: הסבר על מיפוי המקשים, איך אחרים ישתמשו בו והסבר על היכולות. נא להעלות תמונות לשירותים כמו imgur. + +# קובץ `config.h` + +לקובץ `config.h` יש 3 מיקומים אפשריים: + +* keyboard (`/keyboards//config.h`) +* userspace (`/users//config.h`) +* keymap (`/keyboards//keymaps//config.h`) + +מערכת הבילד אוטומטית בוחרת את קובץ ההגדרות לפי הסדר הנ״ל. אם רוצים לדרוס הגדרה מסויימת שהוגדרה בקובץ `config.h` קודם, ראשית תצטרכו להשתמש בקוד מוכן עבור ההגדרות שאתם רוצים לשנות. + +
+ +``` +#pragma once +``` + +
+ +כדי לדרוס הגדרות מקובץ `config.h` קודם, אתם מוכרחים להשתמש בפקודת `#undef` ואז שוב `#define`. + +דוגמה לקוד כזה נראית כך: +
+ +``` +#pragma once + +// overrides go here! +#undef MY_SETTING +#define MY_SETTING 4 +``` + +
+
diff --git a/docs/he-il/hardware.md b/docs/he-il/hardware.md new file mode 100644 index 00000000000..441792e031b --- /dev/null +++ b/docs/he-il/hardware.md @@ -0,0 +1,10 @@ +
+# חומרה + +QMK רצה על מגוון של חומרות. אם המעבד שלך יכול להיות ממוקד (מטורגט) ע״י [LUFA](http://www.fourwalledcubicle.com/LUFA.php) או [ChibiOS](http://www.chibios.com) כנראה שתוכל לגרום ל 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 new file mode 100644 index 00000000000..8792a9de0a7 --- /dev/null +++ b/docs/he-il/newbs_learn_more_resources.md @@ -0,0 +1,16 @@ +
+# מקורות ללמידה + +המקורות הבאים מטרתם היא לתת למשתמשים חדשים בקהילת QMK כדי להבין לעומק את המידע שמגיע במסמכי המתחילים. + +מקורות גיט: + +* [מדריך כללי מעולה](https://www.codecademy.com/learn/learn-git) +* [משחק גיט כדי ללמוד מדוגמאות](https://learngitbranching.js.org/) +* [מקורות גיט כדי ללמוד עוד על GitHub](getting_started_github.md) +* [מקור גיט כדי ללמוד במפורש על QMK](contributing.md) + +מקורות לפקודות שורה (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/proton_c_conversion.md b/docs/he-il/proton_c_conversion.md new file mode 100644 index 00000000000..9642ca30905 --- /dev/null +++ b/docs/he-il/proton_c_conversion.md @@ -0,0 +1,36 @@ +
+# המרה של לוח להשתמש ב-Proton C + +אם לוח נתמך ב-QMK משתמש בלוח Pro Micro (או כל לוח נתמך) ואתם רוצים להשתמש ב-Proton C, ניתן לייצר את החומרה ע"י הוספה של הפקודה `CONVERT_TO_PROTON_C=yes` (או `CTPC=yes`) לפקודת make, כמו כאן: +
+ +``` + make 40percentclub/mf68:default CTPC=yes +``` + +
+ניתן להוסיף את אותו ארגומנט לקובץ `rules.mk` במיפוי המקשים שלכם, שתיצור את אותה התוצאה. + +הדבר חושף את דגל `CONVERT_TO_PROTON_C` שניתן להשתמש בו בקוד שלכם באמצעות פקודת `#ifdef`, כמו כאן: +
+ +``` + #ifdef CONVERT_TO_PROTON_C + // Proton C code + #else + // Pro Micro code + #endif +``` + +
+לפני שתצליחו לקמפל, יכול להיות שתקבלו שגיאות שונות לגבי `PORTB/DDRB`, וכו' שלא הוגדרו, אם כך, תצטרכו להמיר את קודי המקלדת להשתמש ב - [בקרי GPIO](internals_gpio_control.md) שיעבדו עבור ARM וגם AVR. הדבר לא אמור להשפיע על הבילדים של AVR בכלל. + +ל-Proton C יש רק מנורת LED אחת על הלוח (C13), וכברירת מחדל, TXLED (D5) ממופה אליו. אם תרצו במקום, למפות אליו את RXLED (B0), הוסיפו את השורה הבא לקובץ `config.h`: +
+ +``` + #define CONVERT_TO_PROTON_C_RXLED +``` + +
+
diff --git a/docs/he-il/quantum_keycodes.md b/docs/he-il/quantum_keycodes.md new file mode 100644 index 00000000000..5374fd47ad4 --- /dev/null +++ b/docs/he-il/quantum_keycodes.md @@ -0,0 +1,25 @@ +
+# קודי מקלדת Quantum + +קודי מקלדת Quantum מאפשרים התאמה נוחה יותר של מיפוי המקשים שלך מעבר למה שהבסיסי מאפשר, ללא צורך בהגדרת של פעולות מותאמות אישית. + +כל קודי המקלדת בתוך quantum הם מספרים בין `0x0000` ֿֿֿ ל-`0xFFFF`. בתוך הקובץ `keymap.c` זה עלול להראות כאילו יש לך פונקציות ומקרים יחודיים נוספים, אבל בסופו של דבר הקדם-מעבד של שפת C יתרגם אלה לתוך מספר יחיד בין 4 בתים. QMK שמרה את מרחב הכתובות בין `0x0000` עד ל- `0x00FF` עבור קודי מקשים סטנדרטיים. קודי מקשים אלה, כגון `KC_A`, `KC_1`, ו- `KC_LCTL`, אשר מתארים מקשים בסיסיים מוגדרים בתוך USB HID specification. + +בעמודו זה יש לנו את קודי המקשים מתועדים בין `0x00FF` ֿֿ ל- `0xFFFF` אשר משומשים בשביל לממש יכולות מתקדמות של quantum. אם תגדירו קודי מקשים משלכם, הם יתווספו לתוך המרחב הזה גם כן. + +## קודי מקשים של QMK +
+ +``` +|Key |Aliases |Description | +|---------------|-----------|---------------------------------------------------------------------| +|`RESET` | |Put the keyboard into DFU mode for flashing | +|`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_LEAD` | |The [Leader key](feature_leader_key.md) | +|`KC_LOCK` | |The [Lock key](feature_key_lock.md) | +``` + +
+
diff --git a/docs/how_a_matrix_works.md b/docs/how_a_matrix_works.md new file mode 100644 index 00000000000..df7d164cbbb --- /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](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/) (animated examples) +- [How keyboards work - QMK documentation](how_keyboards_work.md) diff --git a/docs/how_keyboards_work.md b/docs/how_keyboards_work.md index bbd22a2788c..3dcbc645222 100644 --- a/docs/how_keyboards_work.md +++ b/docs/how_keyboards_work.md @@ -35,7 +35,7 @@ USB for a given key. ## 3. What the Event Input/Kernel Does -The *scancode* is mapped to a *keycode* dependent on the keyboard [60-keyboard.hwdb at Master](https://github.com/systemd/systemd/blob/master/hwdb/60-keyboard.hwdb). Without this mapping, the operating system will not receive a valid keycode and will be unable to do anything useful with that key press. +The *scancode* is mapped to a *keycode* dependent on the keyboard [60-keyboard.hwdb at Master](https://github.com/systemd/systemd/blob/master/hwdb.d/60-keyboard.hwdb). Without this mapping, the operating system will not receive a valid keycode and will be unable to do anything useful with that key press. ## 4. What the Operating System Does diff --git a/docs/i2c_driver.md b/docs/i2c_driver.md index d5c340edce7..0103e1b4ccc 100644 --- a/docs/i2c_driver.md +++ b/docs/i2c_driver.md @@ -1,33 +1,46 @@ -# 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 +## An important note on I2C Addresses :id=note-on-i2c-addresses + +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`. + +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`: + +`#define MY_I2C_ADDRESS (0x18 << 1)` + +See https://www.robot-electronics.co.uk/i2c-tutorial for more information about I2C addressing and other technical details. + +## Available functions :id=available-functions |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. | +|`i2c_status_t i2c_start(uint8_t address, uint16_t timeout);` |Starts an I2C transaction. Address is the 7-bit slave address without the direction bit. | +|`i2c_status_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. | +|`i2c_status_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. | +|`i2c_status_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. | +|`i2c_status_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. | +|`i2c_status_t i2c_stop(void);` |Ends an I2C transaction. | -### Function Return +### Function Return :id=function-return All the above functions, except `void i2c_init(void);` return the following truth table: -|Return Value |Description | -|---------------|---------------------------------------------------| -|0 |Operation executed successfully. | -|-1 |Operation failed. | -|-2 |Operation timed out. | +|Return Constant |Value|Description | +|--------------------|-----|--------------------------------| +|`I2C_STATUS_SUCCESS`|0 |Operation executed successfully.| +|`I2C_STATUS_ERROR` |-1 |Operation failed. | +|`I2C_STATUS_TIMEOUT`|-2 |Operation timed out. | -## AVR +## AVR :id=avr -### Configuration +### Configuration :id=avr-configuration The following defines can be used to configure the I2C master driver. @@ -37,12 +50,12 @@ The following defines can be used to configure the I2C master driver. AVRs usually have set GPIO which turn into I2C pins, therefore no further configuration is required. -## ARM +## ARM :id=arm For ARM the Chibios I2C HAL driver is under the hood. This section assumes an STM32 MCU. -### Configuration +### Configuration :id=arm-configuration 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. @@ -68,8 +81,8 @@ STM32 MCUs allows a variety of pins to be configured as I2C pins depending on th |--------------------------|----------------------------------------------------------------------------------------------|---------| | `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_SCL` | The pin number for the SCL pin (0-15) | `6` | +| `I2C1_SDA` | The pin number for the SDA pin (0-15) | `7` | | `I2C1_BANK` (deprecated) | The bank of pins (`GPIOA`, `GPIOB`, `GPIOC`), superceded by `I2C1_SCL_BANK`, `I2C1_SDA_BANK` | `GPIOB` | The ChibiOS I2C driver configuration depends on STM32 MCU: @@ -77,7 +90,7 @@ The ChibiOS I2C driver configuration depends on STM32 MCU: STM32F1xx, STM32F2xx, STM32F4xx, STM32L0xx and STM32L1xx use I2Cv1; STM32F0xx, STM32F3xx, STM32F7xx and STM32L4xx use I2Cv2; -#### I2Cv1 +#### I2Cv1 :id=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: | Variable | Default | @@ -86,7 +99,7 @@ STM32 MCUs allow for different clock and duty parameters when configuring I2Cv1. | `I2C1_CLOCK_SPEED` | `100000` | | `I2C1_DUTY_CYCLE` | `STD_DUTY_CYCLE` | -#### I2Cv2 +#### I2Cv2 :id=i2cv2 STM32 MCUs allow for different timing parameters when configuring I2Cv2. These can be modified using the following parameters, using as a reference: | Variable | Default | @@ -104,10 +117,10 @@ STM32 MCUs allow for different "alternate function" modes when configuring GPIO | `I2C1_SCL_PAL_MODE` | `4` | | `I2C1_SDA_PAL_MODE` | `4` | -#### Other +#### Other :id=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: -```C +```c void i2c_init(void) { setPinInput(B6); // Try releasing special pins for a short time diff --git a/docs/index.html b/docs/index.html index 94372944a97..68bd00f6ddd 100644 --- a/docs/index.html +++ b/docs/index.html @@ -6,48 +6,125 @@ - + - - - + + + + +
+ +