From ac7b2d92bf1254803ec97c075e6d0c833dfd4146 Mon Sep 17 00:00:00 2001 From: yiancar Date: Thu, 4 Oct 2018 22:37:26 +0100 Subject: ARM SWD guide - Added a detailed (but saddly long) debugging guide. - Modified sidebar and summary to include the links. --- docs/_summary.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/_summary.md') diff --git a/docs/_summary.md b/docs/_summary.md index a35014dd8c..973428c9e0 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -74,6 +74,7 @@ * For Makers and Modders * [Hand Wiring Guide](hand_wire.md) * [ISP Flashing Guide](isp_flashing_guide.md) + * [ARM Debugging Guide](arm_debugging.md) * For a Deeper Understanding * [How Keyboards Work](how_keyboards_work.md) -- cgit 1.4.1 From a7d05820a6258178b7ea440ee2781edf074d8f41 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Wed, 10 Oct 2018 12:38:10 -0700 Subject: Add documentation for Combo feature --- docs/_sidebar.md | 1 + docs/_summary.md | 1 + docs/config_options.md | 6 ++++ docs/feature_combo.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 96 insertions(+) create mode 100644 docs/feature_combo.md (limited to 'docs/_summary.md') diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 32e3c7eca0..56a6463918 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -48,6 +48,7 @@ * [Backlight](feature_backlight.md) * [Bluetooth](feature_bluetooth.md) * [Bootmagic](feature_bootmagic.md) + * [Combos](feature_combo) * [Command](feature_command.md) * [Dynamic Macros](feature_dynamic_macros.md) * [Grave Escape](feature_grave_esc.md) diff --git a/docs/_summary.md b/docs/_summary.md index 973428c9e0..11aeb7cd36 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -47,6 +47,7 @@ * [Backlight](feature_backlight.md) * [Bluetooth](feature_bluetooth.md) * [Bootmagic](feature_bootmagic.md) + * [Combos](feature_combo) * [Command](feature_command.md) * [Dynamic Macros](feature_dynamic_macros.md) * [Grave Escape](feature_grave_esc.md) diff --git a/docs/config_options.md b/docs/config_options.md index 4678a7146c..19861c9d23 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -155,6 +155,10 @@ If you define these options you will enable the associated feature, which may in going to produce the 500 keystrokes a second needed to actually get more than a few ms of delay from this. But if you're doing chording on something with 3-4ms scan times? You probably want this. +* `#define COMBO_COUNT 2` + * Set this to the number of combos that you're using in the [Combo](feature_combo.md) feature. +* `#define COMBO_TERM 200` + * how long for the Combo keys to be detected. Defaults to `TAPPING_TERM` if not defined. ## RGB Light Configuration @@ -234,6 +238,8 @@ Use these to enable or disable building certain features. The more you have enab * Console for debug(+400) * `COMMAND_ENABLE` * Commands for debug and configuration +* `COMBO_ENABLE` + * Key combo feature * `NKRO_ENABLE` * USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work * `AUDIO_ENABLE` diff --git a/docs/feature_combo.md b/docs/feature_combo.md new file mode 100644 index 0000000000..f509e9f33f --- /dev/null +++ b/docs/feature_combo.md @@ -0,0 +1,88 @@ +# Combos + +The Combo feature is a chording type solution for adding custom actions. It lets you hit multiple keys at once and produce a different effect. For instance, hitting `A` and `S` within the tapping term would hit `ESC` instead, or have it perform even more complex tasks. + +To enable this feature, yu need to add `COMBO_ENABLE = yes` to your `rules.mk`. + +Additionally, in your `config.h`, you'll need to specify the number of combos that you'll be using, by adding `#define COMBO_COUNT 1` (replacing 1 with the number that you're using). + + +Also, by default, the tapping term for the Combos is set to the same value as `TAPPING_TERM` (200 by default on most boards). But you can specify a different value by defining it in your `config.h`. For instance: `#define COMBO_TERM 300` would set the time out period for combos to 300ms. + +Then, your `keymap.c` file, you'll need to define a sequence of keys, terminated with `COMBO_END`, and a structure to list the combination of keys, and it's resulting action. + +```c +const uint16_t PROGMEM test_combo[] = {KC_A, KC_B, COMBO_END}; +combo_t key_combos[COMBO_COUNT] = {COMBO(test_combo, KC_ESC)}; +``` + +This will send "Escape" if you hit the A and B keys. + +!> This method only supports [basic keycodes](keycodes_basic.md). See the examples for more control. + +## Examples + +If you want to add a list, then you'd use something like this: + +```c +enum combos { + AB_ESC, + JK_TAB +} +const uint16_t PROGMEM ab_combo[] = {KC_A, KC_B, COMBO_END}; +const uint16_t PROGMEM jk_combo[] = {KC_J, KC_K, COMBO_END}; + +combo_t key_combos[COMBO_COUNT] = { + [AB_ESC] = COMBO(ab_combo, KC_ESC), + [JK_TAB] = COMBO(jk_combo, KC_TAB) +}; +``` + +For a more complicated implementation, you can use the `process_combo_event` function to add custom handling. + +```c +enum combo_events { + ZC_COPY, + ZV_PASTE + }; + +const uint16_t PROGMEM copy_combo[] = {KC_Z, KC_C, COMBO_END}; +const uint16_t PROGMEM paste_combo[] = {KC_Z, KC_V, COMBO_END}; + +combo_t key_combos[COMBO_COUNT] = { + [ZC_COPY] = COMBO_ACTION(copy_combo), + [ZV_PASTE] = COMBO_ACTION(paste_combo), +}; + +void process_combo_event(uint8_t combo_index, bool pressed) { + switch(combo_index) { + case ZC_COPY: + if (pressed) { + register_code(KC_LCTL); + register_code(KC_C); + unregister_code(KC_C); + unregister_code(KC_LCTL); + } + break; + + case ZV_PASTE: + if (pressed) { + register_code(KC_LCTL); + register_code(KC_V); + unregister_code(KC_V); + unregister_code(KC_LCTL); + } + break; + } +} +``` + +This will send Ctrl+C if you hit Z and C, and Ctrl+V if you hit Z and V. But you could change this to do stuff like change layers, play sounds, or change settings. + +## Additional Configuration + +If you're using long combos, or even longer combos, you may run into issues with this, as the structure may not be large enough to accommodate what you're doing. + +In this case, you can add either `#define EXTRA_LONG_COMBOS` or `#define EXTRA_EXTRA_LONG_COMBOS` in your `config.h` file. + +You may also be able to enable action keys by defining `COMBO_ALLOW_ACTION_KEYS`. -- cgit 1.4.1 From 480651cf9df5c0b7453f60dffe13ae5de665a120 Mon Sep 17 00:00:00 2001 From: noroadsleft <18669334+noroadsleft@users.noreply.github.com> Date: Thu, 18 Oct 2018 15:12:11 -0700 Subject: Docs: Adding QMK Git Conventions doc; formatting cleanup on Learning Resources doc (#3902) * Docs: newbs_learn_more_resources.md: formatting * Added QMK Git Conventions doc, initial version * Renamed contributing_qmk.md to newbs_best_practices.md * Updated per review by @drashna * Added navigation links * Updated to Best Practices doc * Minor updates to Learn More Resources doc Markdown formatting consistency because I'm particular about it. * Added Merge Conflict section to Best Practices doc --- docs/_sidebar.md | 1 + docs/_summary.md | 2 + docs/newbs.md | 1 + docs/newbs_best_practices.md | 163 +++++++++++++++++++++++++++++++++++++ docs/newbs_learn_more_resources.md | 6 +- 5 files changed, 171 insertions(+), 2 deletions(-) create mode 100644 docs/newbs_best_practices.md (limited to 'docs/_summary.md') diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 56a6463918..465f4657cd 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -3,6 +3,7 @@ * [Building Your First Firmware](newbs_building_firmware.md) * [Flashing Firmware](newbs_flashing.md) * [Testing and Debugging](newbs_testing_debugging.md) + * [Best Practices](newbs_best_practices.md) * [Learning Resources](newbs_learn_more_resources.md) * [QMK Basics](README.md) diff --git a/docs/_summary.md b/docs/_summary.md index 11aeb7cd36..465f4657cd 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -3,6 +3,8 @@ * [Building Your First Firmware](newbs_building_firmware.md) * [Flashing Firmware](newbs_flashing.md) * [Testing and Debugging](newbs_testing_debugging.md) + * [Best Practices](newbs_best_practices.md) + * [Learning Resources](newbs_learn_more_resources.md) * [QMK Basics](README.md) * [QMK Introduction](getting_started_introduction.md) diff --git a/docs/newbs.md b/docs/newbs.md index 38a9607d44..e687fd2279 100644 --- a/docs/newbs.md +++ b/docs/newbs.md @@ -12,6 +12,7 @@ There are 5 main sections to this guide: * [Building Your First Firmware](newbs_building_firmware.md) * [Flashing Firmware](newbs_flashing.md) * [Testing and Debugging](newbs_testing_debugging.md) +* [Best Practices](newbs_best_practices.md) * [Learn More with these Resources](newbs_learn_more_resources.md) This guide is focused on helping someone who has never compiled software before. It makes choices and recommendations based on that viewpoint. There are alternative methods for many of these procedures, and we support most of those alternatives. If you have any doubt about how to accomplish a task you can [ask us for guidance](getting_started_getting_help.md). diff --git a/docs/newbs_best_practices.md b/docs/newbs_best_practices.md new file mode 100644 index 0000000000..61bcc0c6ad --- /dev/null +++ b/docs/newbs_best_practices.md @@ -0,0 +1,163 @@ +# Best Practices + +## Or, "How I Learned to Stop Worrying and Love Git." + +This document aims to instruct novices in the best ways to have a smooth experience in contributing to QMK. We will walk through the process of contributing to QMK, detailing some ways to make this task easier, and then later we'll break some things in order to teach you how to fix them. + +This document assumes a few things: + +1. You have a GitHub account, and have [forked the qmk_firmware repository](getting_started_github.md) to your account. +2. You've [set up your build environment](newbs_getting_started.md?id=environment-setup). + + +## Your fork's master: Update Often, Commit Never + +It is highly recommended for QMK development, regardless of what is being done or where, to keep your `master` branch updated, but ***never*** commit to it. Instead, do all your changes in a development branch and issue pull requests from your branches when you're developing. + +To reduce the chances of merge conflicts — instances where two or more users have edited the same part of a file concurrently — keep your `master` branch relatively up-to-date, and start any new developments by creating a new branch. + +### Updating your master branch + +To keep your `master` branch updated, it is recommended to add the QMK Firmware repository ("repo") as a remote repository in git. To do this, open your Git command line interface and enter: + +``` +git remote add upstream https://github.com/qmk/qmk_firmware.git +``` + +To verify that the repository has been added, run `git remote -v`, which should return the following: + +``` +$ 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) +``` + +Now that this is done, you can check for updates to the repo by running `git fetch upstream`. This retrieves the branches and tags — collectively referred to as "refs" — from the QMK repo, which now has the nickname `upstream`. We can now compare the data on our fork `origin` to that held by QMK. + +To update your fork's master, run the following, hitting the Enter key after each line: + +``` +git checkout master +git fetch upstream +git pull upstream master +git push origin master +``` + +This switches you to your `master` branch, retrieves the refs from the QMK repo, downloads the current QMK `master` branch to your computer, and then uploads it to your fork. + +### Making Changes + +To make changes, create a new branch by entering: + +``` +git checkout -b dev_branch +git push --set-upstream origin dev_branch +``` + +This creates a new branch named `dev_branch`, checks it out, and then saves the new branch to your fork. The `--set-upstream` argument tells git to use your fork and the `dev_branch` branch every time you use `git push` or `git pull` from this branch. It only needs to be used on the first push; after that, you can safely use `git push` or `git pull`, without the rest of the arguments. + +!> With `git push`, you can use `-u` in place of `--set-upstream` — `-u` is an alias for `--set-upstream`. + +You can name your branch nearly anything you want, though it is recommended to name it something related to the changes you are going to make. + +By default `git checkout -b` will base your new branch on the branch that is checked out. You can base your new branch on an existing branch that is not checked out by adding the name of the existing branch to the command: + +``` +git checkout -b dev_branch master +``` + +Now that you have a development branch, open your text editor and make whatever changes you need to make. It is recommended to make many small commits to your branch; that way, any change that causes issues can be more easily traced and undone if needed. To make your changes, edit and save any files that need to be updated, add them to Git's *staging area*, and then commit them to your branch: + +``` +git add path/to/updated_file +git commit -m "My commit message." +``` + +`git add` adds files that have been changed to Git's *staging area*, which is Git's "loading zone." This contains the changes that are going to be *committed* by `git commit`, which saves the changes to the repo. Use descriptive commit messages so you can know what was changed at a glance. + +!> If you've changed a lot of files, but all the files are part of the same change, you can use `git add .` to add all the changed files that are in your current directory, rather than having to add each file individually. + +### Publishing Your Changes + +The last step is to push your changes to your fork. To do this, enter `git push`. Git now publishes the current state of `dev_branch` to your fork. + + +## Resolving Merge Conflicts + +Sometimes when your work in a branch takes a long time to complete, changes that have been made by others conflict with changes you have made to your branch when you open a pull request. This is called a *merge conflict*, and is what happens when multiple people edit the same parts of the same files. + +### Rebasing Your Changes + +A *rebase* is Git's way of taking changes that were applied at one point, reversing them, and then applying the same changes to another point. In the case of a merge conflict, you can rebase your branch to grab the changes that were made between when you created your branch and the present time. + +To start, run the following: + +``` +git fetch upstream +git rev-list --left-right --count HEAD...upstream/master +``` + +The `git rev-list` command entered here returns the number of commits that differ between the current branch and QMK's master branch. We run `git fetch` first to make sure we have the refs that represent the current state of the upstream repo. The output of the `git rev-list` command entered returns two numbers: + +``` +$ git rev-list --left-right --count HEAD...upstream/master +7 35 +``` + +The first number represents the number of commits on the current branch since it was created, and the second number is the number of commits made to `upstream/master` since the current branch was created, and thus, the changes that are not recorded in the current branch. + +Now that the current states of both the current branch and the upstream repo are known, we can start a rebase operation: + +``` +git rebase upstream/master +``` + +This tells Git to undo the commits on the current branch, and then reapply them against QMK's master branch. + +``` +$ 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". +``` + +This tells us that we have a merge conflict, and gives the name of the file with the conflict. Open the conflicting file in your text editor, and somewhere in the file, you'll find something like this: + +``` +<<<<<<< HEAD +

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

+======= +

Need help? Email support@webhost.us.

+>>>>>>> Commit #1 +``` + +The line `<<<<<<< HEAD` marks the beginning of a merge conflict, and the `>>>>>>> Commit #1` line marks the end, with the conflicting sections separated by `=======`. The part on the `HEAD` side is from the QMK master version of the file, and the part marked with the commit message is from the current branch and commit. + +Because Git tracks *changes to files* rather than the contents of the files directly, if Git can't find the text that was in the file previous to the commit that was made, it won't know how to edit the file. Re-editing the file will solve the conflict. Make your changes, and then save the file. + +``` +

Need help? Email support@webhost.us.

+``` + +Now run: + +``` +git add conflicting_file_1.txt +git rebase --continue +``` + +Git logs the changes to the conflicting file, and continues applying the commits from our branch until it reaches the end. diff --git a/docs/newbs_learn_more_resources.md b/docs/newbs_learn_more_resources.md index 23b99f470f..9b77db8fd4 100644 --- a/docs/newbs_learn_more_resources.md +++ b/docs/newbs_learn_more_resources.md @@ -1,13 +1,15 @@ # Learning Resources -These resources are aimed at giving new members in the qmk community more understanding to the information provided in the newbs docs. + +These resources are aimed at giving new members in the QMK community more understanding to the information provided in the Newbs docs. Git resources: * [Great General Tutorial](https://www.codecademy.com/learn/learn-git) * [Git Game To Learn From Examples](https://learngitbranching.js.org/) * [Git Resources to Learn More About Github](getting_started_github.md) -* [Git Resources Aimed Specificly toward QMK](contributing.md) +* [Git Resources Aimed Specifically toward QMK](contributing.md) Command Line resources: + * [Good General Tutorial on Command Line](https://www.codecademy.com/learn/learn-the-command-line) -- cgit 1.4.1 From 85688e5b52112c86895171d3dc8b26610480e932 Mon Sep 17 00:00:00 2001 From: Jack Humbert Date: Fri, 26 Oct 2018 16:19:23 -0400 Subject: add support for encoders to core --- common_features.mk | 5 +++ docs/_sidebar.md | 1 + docs/_summary.md | 1 + docs/feature_encoders.md | 41 +++++++++++++++++++++++++ keyboards/planck/planck.h | 2 ++ keyboards/planck/rev6/config.h | 4 +++ keyboards/planck/rev6/matrix.c | 29 ----------------- keyboards/planck/rev6/rules.mk | 1 + quantum/encoder.c | 70 ++++++++++++++++++++++++++++++++++++++++++ quantum/encoder.h | 29 +++++++++++++++++ quantum/quantum.c | 12 ++++++++ 11 files changed, 166 insertions(+), 29 deletions(-) create mode 100644 docs/feature_encoders.md create mode 100644 quantum/encoder.c create mode 100644 quantum/encoder.h (limited to 'docs/_summary.md') diff --git a/common_features.mk b/common_features.mk index 65ff6b5b38..3fd8361a52 100644 --- a/common_features.mk +++ b/common_features.mk @@ -219,6 +219,11 @@ ifeq ($(strip $(USB_HID_ENABLE)), yes) include $(TMK_DIR)/protocol/usb_hid.mk endif +ifeq ($(strip $(ENCODER_ENABLE)), yes) + SRC += $(QUANTUM_DIR)/encoder.c + OPT_DEFS += -DENCODER_ENABLE +endif + ifeq ($(strip $(HD44780_ENABLE)), yes) SRC += drivers/avr/hd44780.c OPT_DEFS += -DHD44780_ENABLE diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 465f4657cd..2c57380122 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -52,6 +52,7 @@ * [Combos](feature_combo) * [Command](feature_command.md) * [Dynamic Macros](feature_dynamic_macros.md) + * [Encoders](feature_encoders.md) * [Grave Escape](feature_grave_esc.md) * [Key Lock](feature_key_lock.md) * [Layouts](feature_layouts.md) diff --git a/docs/_summary.md b/docs/_summary.md index 465f4657cd..2c57380122 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -52,6 +52,7 @@ * [Combos](feature_combo) * [Command](feature_command.md) * [Dynamic Macros](feature_dynamic_macros.md) + * [Encoders](feature_encoders.md) * [Grave Escape](feature_grave_esc.md) * [Key Lock](feature_key_lock.md) * [Layouts](feature_layouts.md) diff --git a/docs/feature_encoders.md b/docs/feature_encoders.md new file mode 100644 index 0000000000..f482eefec8 --- /dev/null +++ b/docs/feature_encoders.md @@ -0,0 +1,41 @@ +# Encoders + +Basic encoders are supported by adding this to your `rules.mk`: + + ENCODER_ENABLE = yes + +and this to your `config.h`: + + #define NUMBER_OF_ENCODERS 1 + #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 { encoder1a, encoder2b } + +If your encoder's clockwise directions are incorrect, you can swap the A & B pad definitions. + +Additionally, the resolution can be specified in the same file (the default & suggested is 4): + + #define ENCODER_RESOLUTION 4 + +## Callbacks + +The callback functions can be inserted into your `.c`: + + void encoder_update_kb(uint8_t index, bool clockwise) { + encoder_update_user(index, clockwise); + } + +or `keymap.c`: + + void encoder_update_user(uint8_t index, bool clockwise) { + + } + + +## Hardware + +The A an B lines of the encoders should be wired directly to the MCU, and the C/common lines should be wired to ground. diff --git a/keyboards/planck/planck.h b/keyboards/planck/planck.h index f0a12d9335..d908d80ec4 100644 --- a/keyboards/planck/planck.h +++ b/keyboards/planck/planck.h @@ -3,6 +3,8 @@ #include "quantum.h" +#define encoder_update(clockwise) encoder_update_user(uint8_t index, clockwise) + #ifdef __AVR__ #define LAYOUT_planck_mit( \ k00, k01, k02, k03, k04, k05, k06, k07, k08, k09, k0a, k0b, \ diff --git a/keyboards/planck/rev6/config.h b/keyboards/planck/rev6/config.h index afd69f7d84..c0fbb412ee 100644 --- a/keyboards/planck/rev6/config.h +++ b/keyboards/planck/rev6/config.h @@ -43,6 +43,10 @@ * #define UNUSED_PINS */ +#define NUMBER_OF_ENCODERS 1 +#define ENCODERS_PAD_A { B12 } +#define ENCODERS_PAD_B { B13 } + #define MUSIC_MAP #undef AUDIO_VOICES #undef C6_AUDIO diff --git a/keyboards/planck/rev6/matrix.c b/keyboards/planck/rev6/matrix.c index e4ebe48acc..2df588cefc 100644 --- a/keyboards/planck/rev6/matrix.c +++ b/keyboards/planck/rev6/matrix.c @@ -21,10 +21,6 @@ static matrix_row_t matrix_debouncing[MATRIX_COLS]; static bool debouncing = false; static uint16_t debouncing_time = 0; -static uint8_t encoder_state = 0; -static int8_t encoder_value = 0; -static int8_t encoder_LUT[] = { 0, -1, 1, 0, 1, 0, 0, -1, -1, 0, 0, 1, 0, 1, -1, 0 }; - static bool dip_switch[4] = {0, 0, 0, 0}; __attribute__ ((weak)) @@ -53,12 +49,6 @@ void matrix_init(void) { palSetPadMode(GPIOA, 10, PAL_MODE_INPUT_PULLUP); palSetPadMode(GPIOB, 9, PAL_MODE_INPUT_PULLUP); - // encoder setup - palSetPadMode(GPIOB, 12, PAL_MODE_INPUT_PULLUP); - palSetPadMode(GPIOB, 13, PAL_MODE_INPUT_PULLUP); - - encoder_state = (palReadPad(GPIOB, 12) << 0) | (palReadPad(GPIOB, 13) << 1); - // actual matrix setup palSetPadMode(GPIOB, 11, PAL_MODE_OUTPUT_PUSHPULL); palSetPadMode(GPIOB, 10, PAL_MODE_OUTPUT_PUSHPULL); @@ -87,15 +77,8 @@ void matrix_init(void) { __attribute__ ((weak)) void dip_update(uint8_t index, bool active) { } -__attribute__ ((weak)) -void encoder_update(bool clockwise) { } - bool last_dip_switch[4] = {0}; -#ifndef ENCODER_RESOLUTION - #define ENCODER_RESOLUTION 4 -#endif - uint8_t matrix_scan(void) { // dip switch dip_switch[0] = !palReadPad(GPIOB, 14); @@ -108,18 +91,6 @@ uint8_t matrix_scan(void) { } memcpy(last_dip_switch, dip_switch, sizeof(&dip_switch)); - // encoder on B12 and B13 - encoder_state <<= 2; - encoder_state |= (palReadPad(GPIOB, 12) << 0) | (palReadPad(GPIOB, 13) << 1); - encoder_value += encoder_LUT[encoder_state & 0xF]; - if (encoder_value >= ENCODER_RESOLUTION) { - encoder_update(0); - } - if (encoder_value <= -ENCODER_RESOLUTION) { // direction is arbitrary here, but this clockwise - encoder_update(1); - } - encoder_value %= ENCODER_RESOLUTION; - // actual matrix for (int col = 0; col < MATRIX_COLS; col++) { matrix_row_t data = 0; diff --git a/keyboards/planck/rev6/rules.mk b/keyboards/planck/rev6/rules.mk index 3603e287b3..dce683a7ff 100644 --- a/keyboards/planck/rev6/rules.mk +++ b/keyboards/planck/rev6/rules.mk @@ -54,3 +54,4 @@ CUSTOM_MATRIX = yes # Custom matrix file AUDIO_ENABLE = yes RGBLIGHT_ENABLE = no # SERIAL_LINK_ENABLE = yes +ENCODER_ENABLE = yes diff --git a/quantum/encoder.c b/quantum/encoder.c new file mode 100644 index 0000000000..6629a098b8 --- /dev/null +++ b/quantum/encoder.c @@ -0,0 +1,70 @@ +/* + * Copyright 2018 Jack Humbert + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + */ + +#include "encoder.h" + +#ifndef ENCODER_RESOLUTION + #define ENCODER_RESOLUTION 4 +#endif + +#ifndef NUMBER_OF_ENCODERS + #error "Number of encoders not defined by NUMBER_OF_ENCODERS" +#endif + +#if !defined(ENCODERS_PAD_A) || !defined(ENCODERS_PAD_B) + #error "No encoder pads defined by ENCODERS_PAD_A and ENCODERS_PAD_B" +#endif + +static pin_t encoders_pad_a[NUMBER_OF_ENCODERS] = ENCODERS_PAD_A; +static pin_t encoders_pad_b[NUMBER_OF_ENCODERS] = ENCODERS_PAD_B; + +static int8_t encoder_LUT[] = { 0, -1, 1, 0, 1, 0, 0, -1, -1, 0, 0, 1, 0, 1, -1, 0 }; + +static uint8_t encoder_state[NUMBER_OF_ENCODERS] = {0}; +static int8_t encoder_value[NUMBER_OF_ENCODERS] = {0}; + +__attribute__ ((weak)) +void encoder_update_user(int8_t index, bool clockwise) { } + +__attribute__ ((weak)) +void encoder_update_kb(int8_t index, bool clockwise) { + encoder_update_user(index, clockwise); +} + +void encoder_init(void) { + for (int i = 0; i < NUMBER_OF_ENCODERS; i++) { + setPinInputHigh(encoders_pad_a[i]); + setPinInputHigh(encoders_pad_b[i]); + + encoder_state[i] = (readPin(encoders_pad_a[i]) << 0) | (readPin(encoders_pad_b[i]) << 1); + } +} + +void encoder_read(void) { + for (int i = 0; i < NUMBER_OF_ENCODERS; i++) { + encoder_state[i] <<= 2; + encoder_state[i] |= (readPin(encoders_pad_a[i]) << 0) | (readPin(encoders_pad_b[i]) << 1); + encoder_value[i] += encoder_LUT[encoder_state[i] & 0xF]; + if (encoder_value[i] >= ENCODER_RESOLUTION) { + encoder_update_kb(i, COUNTRECLOCKWISE); + } + if (encoder_value[i] <= -ENCODER_RESOLUTION) { // direction is arbitrary here, but this clockwise + encoder_update_kb(i, CLOCKWISE); + } + encoder_value[i] %= ENCODER_RESOLUTION; + } +} diff --git a/quantum/encoder.h b/quantum/encoder.h new file mode 100644 index 0000000000..2024fa303f --- /dev/null +++ b/quantum/encoder.h @@ -0,0 +1,29 @@ +/* + * Copyright 2018 Jack Humbert + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + */ + +#pragma once + +#include "quantum.h" + +#define COUNTRECLOCKWISE 0 +#define CLOCKWISE 1 + +void encoder_init(void); +void encoder_read(void); + +void encoder_update_kb(int8_t index, bool clockwise); +void encoder_update_user(int8_t index, bool clockwise); diff --git a/quantum/quantum.c b/quantum/quantum.c index eed59f811e..c9bec6740b 100644 --- a/quantum/quantum.c +++ b/quantum/quantum.c @@ -42,6 +42,11 @@ extern backlight_config_t backlight_config; #include "process_midi.h" #endif + +#ifdef ENCODER_ENABLE +#include "encoder.h" +#endif + #ifdef AUDIO_ENABLE #ifndef GOODBYE_SONG #define GOODBYE_SONG SONG(GOODBYE_SOUND) @@ -957,6 +962,9 @@ void matrix_init_quantum() { #ifdef RGB_MATRIX_ENABLE rgb_matrix_init(); #endif + #ifdef ENCODER_ENABLE + encoder_init(); + #endif matrix_init_kb(); } @@ -991,6 +999,10 @@ void matrix_scan_quantum() { rgb_matrix_task_counter = ((rgb_matrix_task_counter + 1) % (RGB_MATRIX_SKIP_FRAMES + 1)); #endif + #ifdef ENCODER_ENABLE + encoder_read(); + #endif + matrix_scan_kb(); } #if defined(BACKLIGHT_ENABLE) && defined(BACKLIGHT_PIN) -- cgit 1.4.1 From 408361402385ea938575956e9368b5f373edc629 Mon Sep 17 00:00:00 2001 From: yiancar Date: Sat, 10 Nov 2018 12:26:39 -0800 Subject: I2C driver docs (#4298) * I2C driver docs - Added I2C driver docs. - Changed arm master i2c driver to have a weak i2c_init as it is impossible to account for all possible port configuration in the STM32 world. * Update docs/i2c_driver.md Co-Authored-By: yiancar * Update docs/i2c_driver.md Co-Authored-By: yiancar * Update docs/i2c_driver.md Co-Authored-By: yiancar * Update docs/i2c_driver.md Co-Authored-By: yiancar * GPIO release fix --- docs/_sidebar.md | 1 + docs/_summary.md | 1 + docs/i2c_driver.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++++ drivers/arm/i2c_master.c | 5 ++- 4 files changed, 89 insertions(+), 1 deletion(-) create mode 100644 docs/i2c_driver.md (limited to 'docs/_summary.md') diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 2c57380122..67e81422a1 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -79,6 +79,7 @@ * [Hand Wiring Guide](hand_wire.md) * [ISP Flashing Guide](isp_flashing_guide.md) * [ARM Debugging Guide](arm_debugging.md) + * [I2C Driver](i2c_driver.md) * For a Deeper Understanding * [How Keyboards Work](how_keyboards_work.md) diff --git a/docs/_summary.md b/docs/_summary.md index 2c57380122..67e81422a1 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -79,6 +79,7 @@ * [Hand Wiring Guide](hand_wire.md) * [ISP Flashing Guide](isp_flashing_guide.md) * [ARM Debugging Guide](arm_debugging.md) + * [I2C Driver](i2c_driver.md) * For a Deeper Understanding * [How Keyboards Work](how_keyboards_work.md) diff --git a/docs/i2c_driver.md b/docs/i2c_driver.md new file mode 100644 index 0000000000..f69eb5a9da --- /dev/null +++ b/docs/i2c_driver.md @@ -0,0 +1,83 @@ +# I2C Master Driver + +The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs. + +## 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);` |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. | +|`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(uint16_t timeout);` |Stops the I2C driver. | + +### 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. | + + +## AVR + +### Configuration + +The following defines can be used to configure the I2C master driver. + +|Variable |Description |Default| +|------------------|---------------------------------------------------|-------| +|`#F_SCL` |Clock frequency in Hz |400KHz | +|`#Prescaler` |Divides master clock to aid in I2C clock selection |1 | + +AVRs usually have set GPIO which turn into I2C pins, therefore no further configuration is required. + +## ARM + +For ARM the Chibios I2C HAL driver is under the hood. +This section assumes an STM32 MCU. + +### 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. + +Firstly the `mcuconf.h` file must be setup to enable the necessary hardware drivers. + +|Variable |Description |Default| +|------------------------------|------------------------------------------------------------------------------------|-------| +|`#STM32_I2C_USE_XXX` |Enable/Disable the hardware driver XXX (each driver should be explicitly listed) |FALSE | +|`#STM32_I2C_BUSY_TIMEOUT` |Time in ms until the I2C command is aborted if no response is received |50 | +|`#STM32_I2C_XXX_IRQ_PRIORITY` |Interrupt priority for hardware driver XXX (THIS IS AN EXPERT SETTING) |10 | +|`#STM32_I2C_USE_DMA` |Enable/Disable the ability of the MCU to offload the data transfer to the DMA unit |TRUE | +|`#STM32_I2C_XXX_DMA_PRIORITY` |Priority of DMA unit for hardware driver XXX (THIS IS AN EXPERT SETTING) |1 | + +Secondly, in the `halconf.h` file, `#define HAL_USE_I2C` must be set to `TRUE`. This allows ChibiOS to load its I2C driver. + +Lastly, we need to assign the correct GPIO pins depending on the I2C hardware driver we want to use. + +By default the I2C1 hardware driver is assumed to be used. If another hardware driver is used, `#define I2C_DRIVER I2CDX` should be added to the `config.h` file with X being the number of hardware driver used. For example is I2C3 is enabled, the `config.h` file should contain `#define I2C_DRIVER I2CD3`. This aligns the QMK I2C driver with the Chibios I2C driver. + +STM32 MCUs allows a variety of pins to be configured as I2C pins depending on the hardware driver used. By default B6 and B7 are set to I2C. + +This can be changed by declaring the `i2c_init` function which intentionally has a weak attribute. Please consult the datasheet of your MCU for the available GPIO configurations. The following is an example initialization function: + +```C +void i2c_init(void) +{ + setPinInput(B6); // Try releasing special pins for a short time + setPinInput(B7); + chThdSleepMilliseconds(10); // Wait for the release to happen + + palSetPadMode(GPIOB, 6, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B6 to I2C function + palSetPadMode(GPIOB, 7, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); // Set B7 to I2C function +} +``` + + diff --git a/drivers/arm/i2c_master.c b/drivers/arm/i2c_master.c index 2a7badd351..de58438392 100644 --- a/drivers/arm/i2c_master.c +++ b/drivers/arm/i2c_master.c @@ -26,6 +26,7 @@ */ #include "i2c_master.h" +#include "quantum.h" #include #include @@ -41,9 +42,11 @@ static const I2CConfig i2cconfig = { 0 }; +__attribute__ ((weak)) void i2c_init(void) { - palSetGroupMode(GPIOB, GPIOB_PIN6 | GPIOB_PIN7, 0, PAL_MODE_INPUT); // Try releasing special pins for a short time + setPinInput(B6); // Try releasing special pins for a short time + setPinInput(B7); chThdSleepMilliseconds(10); palSetPadMode(GPIOB, 6, PAL_MODE_ALTERNATE(4) | PAL_STM32_OTYPE_OPENDRAIN | PAL_STM32_PUPDR_PULLUP); -- cgit 1.4.1 From d8f090e5592fd5b6fde35ae36e36f2473c716312 Mon Sep 17 00:00:00 2001 From: noroadsleft <18669334+noroadsleft@users.noreply.github.com> Date: Wed, 14 Nov 2018 18:32:28 -0800 Subject: Docs: Supporting a keyboard in the QMK Configurator (#4396) * Docs: Configurator Support * Minor updates * Updated keyboard.h example to use #pragma once per @drashna https://github.com/qmk/qmk_firmware/pull/4396#discussion_r232140934 * Add link to doc under Reference section Added to _sidebar.md and _summary.md * Changed doc title; minor tweaks Re-titled the doc as "Supporting Your Keyboard in QMK Configurator". Made some minor changes to the keyboard.h examples. * Added tags object to JSON example --- docs/_sidebar.md | 1 + docs/_summary.md | 1 + docs/reference_configurator_support.md | 195 +++++++++++++++++++++++++++++++++ 3 files changed, 197 insertions(+) create mode 100644 docs/reference_configurator_support.md (limited to 'docs/_summary.md') diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 67e81422a1..1fb5398d93 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -39,6 +39,7 @@ * [Glossary](reference_glossary.md) * [Unit Testing](unit_testing.md) * [Useful Functions](ref_functions.md) + * [Configurator Support](reference_configurator_support.md) * [Features](features.md) * [Basic Keycodes](keycodes_basic.md) diff --git a/docs/_summary.md b/docs/_summary.md index 67e81422a1..1fb5398d93 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -39,6 +39,7 @@ * [Glossary](reference_glossary.md) * [Unit Testing](unit_testing.md) * [Useful Functions](ref_functions.md) + * [Configurator Support](reference_configurator_support.md) * [Features](features.md) * [Basic Keycodes](keycodes_basic.md) diff --git a/docs/reference_configurator_support.md b/docs/reference_configurator_support.md new file mode 100644 index 0000000000..a20a6c9adb --- /dev/null +++ b/docs/reference_configurator_support.md @@ -0,0 +1,195 @@ +# Supporting Your Keyboard in QMK Configurator + +This page covers how to properly support keyboards in the [QMK Configurator](https://config.qmk.fm/). + + +## How the Configurator Understands Keyboards + +To understand how the Configurator understands keyboards, first one must understand layout macros. For this exercise, we're going to imagine a 17-key numpad PCB, which we're going to call `numpad`. + +``` +┌───┬───┬───┬───┐ +│NLk│ / │ * │ - │ +├───┼───┼───┼───┤ +│7 │8 │9 │ + │ +├───┼───┼───┤ │ +│4 │5 │6 │ │ +├───┼───┼───┼───┤ +│1 │2 │3 │Ent│ +├───┴───┼───┤ │ +│0 │ . │ │ +└───────┴───┴───┘ +``` + +?> For more on layout macros, see [Understanding QMK: Matrix Scanning](understanding_qmk.md?id=matrix-scanning) and [Understanding QMK: Matrix to Physical Layout Map](understanding_qmk.md?id=matrix-to-physical-layout-map). + +The Configurator's API reads the keyboard's `.h` file from `qmk_firmware/keyboards//.h`. For our numpad, this file would be `qmk_firmware/keyboards/numpad/numpad.h`: + +```c +#pragma once + +#define LAYOUT( \ + k00, k01, k02, k03, \ + k10, k11, k12, k13, \ + k20, k21, k22, \ + k30, k31, k32, k33, \ + k40, k42 \ + ) { \ + { k00, k01, k02, k03 }, \ + { k10, k11, k12, k13 }, \ + { k20, k21, k22, KC_NO }, \ + { k30, k31, k32, k33 }, \ + { k40, KC_NO, k42, KC_NO } \ +} +``` + +QMK uses `KC_NO` to designate places in the switch matrix where there is no switch. Sometimes, `XXX`, `___` or `____` are used as shorthand to make this section easier to read if it needs to be debugged. This is usually defined near the beginning of the `.h` file: + +```c +#pragma once + +#define XXX KC_NO + +#define LAYOUT( \ + k00, k01, k02, k03, \ + k10, k11, k12, k13, \ + k20, k21, k22, \ + k30, k31, k32, k33, \ + k40, k42 \ + ) { \ + { k00, k01, k02, k03 }, \ + { k10, k11, k12, k13 }, \ + { k20, k21, k22, XXX }, \ + { k30, k31, k32, k33 }, \ + { k40, XXX, k42, XXX } \ +} +``` + +!> This usage differs from that of keymap macros, which almost always use `XXXXXXX` (seven capital X's) for `KC_NO` and `_______` (seven underscores) for `KC_TRNS`. + +!> To prevent user confusion, using `KC_NO` is preferred. + +The layout macro tells the Configurator that our keyboard has 17 keys, arranged in five rows of four columns each. Our switch positions are named `k`, counting from 0. The names themselves actually don't matter, as long as they match between the top section, which receives the keycodes from the keymap, and the bottom half which designates where each key is in the matrix. + +To display our keyboard in a way that resembles the physical keyboard, we need to build a JSON file that tells the Configurator how to tie the physical locations and sizes of our keys to our switch matrix. + +## Building the JSON file + +To build the JSON file, the easiest way is to build the layout in [Keyboard Layout Editor](http://www.keyboard-layout-editor.com/) ("KLE"), from which we'll feed the Raw Data into a QMK tool that converts this data into a JSON the Configurator will read and use. Since KLE opens by default with a numpad layout, we're just going to remove the Getting Started instructions, and use what's left. + +Once the layout is as desired, move to the Raw Data tab in KLE, and copy the contents: + +``` +["Num Lock","/","*","-"], +["7\nHome","8\n↑","9\nPgUp",{h:2},"+"], +["4\n←","5","6\n→"], +["1\nEnd","2\n↓","3\nPgDn",{h:2},"Enter"], +[{w:2},"0\nIns",".\nDel"] +``` + +To convert this data into our JSON, go to the [QMK KLE-JSON Converter](https://qmk.fm/converter/), paste the Raw Data into the Input field, and click the Convert button. After a moment, our JSON data will appear in the Output field. Copy the contents to a new text document, and name the document `info.json`, saving it in the same folder that contains `numpad.h`. + +Use the `keyboard_name` object to set the name of the keyboard. The `bootloader` object is deprecated, so it can be deleted. For instruction purposes, we will put each key's object on its own line. This is only to make the file more human-readable, and does not affect the Configurator's functionality. + +```json +{ + "keyboard_name": "Numpad", + "url": "", + "maintainer": "qmk", + "tags": { + "form_factor": "numpad" + }, + "width": 4, + "height": 5, + "layouts": { + "LAYOUT": { + "layout": [ + {"label":"Num Lock", "x":0, "y":0}, + {"label":"/", "x":1, "y":0}, + {"label":"*", "x":2, "y":0}, + {"label":"-", "x":3, "y":0}, + {"label":"7", "x":0, "y":1}, + {"label":"8", "x":1, "y":1}, + {"label":"9", "x":2, "y":1}, + {"label":"+", "x":3, "y":1, "h":2}, + {"label":"4", "x":0, "y":2}, + {"label":"5", "x":1, "y":2}, + {"label":"6", "x":2, "y":2}, + {"label":"1", "x":0, "y":3}, + {"label":"2", "x":1, "y":3}, + {"label":"3", "x":2, "y":3}, + {"label":"Enter", "x":3, "y":3, "h":2}, + {"label":"0", "x":0, "y":4, "w":2}, + {"label":".", "x":2, "y":4} + ] + } + } +} +``` + +The `layouts` object contains the data that represents the physical layout of the keyboard. It has an object `LAYOUT`, which needs to match the name of our layout macro from `numpad.h`. The `LAYOUT` object itself has an object named `layout`, which contains one JSON object for each physical key on our keyboard, formatted as follows: + +``` + ┌ The name of the key. Not displayed in the Configurator. + │ ┌ The key's X-axis location, in key units from the + │ │ keyboard's left edge. + │ │ ┌ The key's Y-axis location, in key units from + │ │ │ the keyboard's top (rear-facing) edge. + ↓ ↓ ↓ +{"label":"Num Lock", "x":0, "y":0}, +``` + +Some objects will also have `"w"` and `"h"` keys, which represent a key's width and height, respectively. + +?> For more on the `info.json` files, see [QMK Keyboard Guidelines: Keyboard Metadata](hardware_keyboard_guidelines.md?id=keyboard-metadata) + + +## How the Configurator Programs Keys + +The Configurator's API uses the layout macro and the JSON file we've given it to create a visual representation of the keyboard that has each visual object tied to a specific key, in sequence: + +key in layout macro | JSON object used +:---: | :---- +k00 | {"label":"Num Lock", "x":0, "y":0} +k01 | {"label":"/", "x":1, "y":0} +k02 | {"label":"*", "x":2, "y":0} +k03 | {"label":"-", "x":3, "y":0} +k10 | {"label":"7", "x":0, "y":1} +k11 | {"label":"8", "x":1, "y":1} +k12 | {"label":"9", "x":2, "y":1} +k13 | {"label":"+", "x":3, "y":1, "h":2} +k20 | {"label":"4", "x":0, "y":2} +k21 | {"label":"5", "x":1, "y":2} +k22 | {"label":"6", "x":2, "y":2} +k30 | {"label":"1", "x":0, "y":3} +k31 | {"label":"2", "x":1, "y":3} +k32 | {"label":"3", "x":2, "y":3} +k33 | {"label":"Enter", "x":3, "y":3, "h":2} +k40 | {"label":"0", "x":0, "y":4, "w":2} +k42 | {"label":".", "x":2, "y":4} + +When a user selects the top-left key in the Configurator, and assigns Num Lock to it, the Configurator builds a keymap file with `KC_NLCK` as the first key, and so on as the keymap is built. The `label` keys are not used; they are only for the user's reference in identifying specific keys when debugging the `info.json` file. + + +## Issues and Hazards + +Currently, the Configurator does not support key rotation or non-rectangular key shapes like ISO Enter. Additionally, keys that are vertically-offset from their "row" — the arrow keys on 1800-layouts like the [TKC1800](https://github.com/qmk/qmk_firmware/tree/4ac48a61a66206beaf2fdd5f2939d8bbedd0004c/keyboards/tkc1800/) being a prominent example — confuse the KLE-to-JSON Converter, if not adjusted for by the contributor of the `info.json` file. + +### Workarounds + +#### Non-rectangular keys + +For ISO Enter keys, QMK custom is to display it as a rectangular key, 1.25u wide and 2u high, aligned so its right edge is aligned with the right edge of the alphanumeric key block. + +![](https://i.imgur.com/JKngtTw.png) +*A 60% keyboard in standard ISO layout, as rendered by QMK Configurator.* + +#### Vertically-offset keys + +For vertically-offset keys, place them in KLE as if they were not offset, then edit the Y-values as needed in the converted JSON file + +![](https://i.imgur.com/fmDvDzR.png) +*An 1800-layout keyboard as rendered in Keyboard Layout Editor, without the vertical offset applied to the arrow keys.* + +![](https://i.imgur.com/8beYMBR.png) +*A Unix diff file, showing the changes needed to vertically-offset the arrow keys in our keyboard's JSON file.* -- cgit 1.4.1 From 59b2be6200e13166cf69ae04aa7a05ec5e837d79 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Wed, 5 Dec 2018 10:28:06 -0800 Subject: Re-order feature list in sidebar (#4555) Specifically, moved the shifted keycodes to the top of the 'Feature' list, so it's more visible. This way, all of the keycodes are at the top of the list, rather than having the shifted keys at the bottom, so they should be easier to find since they're all in one place. --- docs/_sidebar.md | 2 +- docs/_summary.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/_summary.md') diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 1fb5398d93..6338d69121 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -43,6 +43,7 @@ * [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) @@ -74,7 +75,6 @@ * [Thermal Printer](feature_thermal_printer.md) * [Unicode](feature_unicode.md) * [Userspace](feature_userspace.md) - * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md) * For Makers and Modders * [Hand Wiring Guide](hand_wire.md) diff --git a/docs/_summary.md b/docs/_summary.md index 1fb5398d93..6338d69121 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -43,6 +43,7 @@ * [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) @@ -74,7 +75,6 @@ * [Thermal Printer](feature_thermal_printer.md) * [Unicode](feature_unicode.md) * [Userspace](feature_userspace.md) - * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md) * For Makers and Modders * [Hand Wiring Guide](hand_wire.md) -- cgit 1.4.1 From 2ad2b73d685cf25268fa7d3726f45594edee70c4 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Fri, 7 Dec 2018 16:51:27 -0800 Subject: Add support for PR and Issue templates to QMK_firmware GitHub (#4494) * Add support document * Add Bug Report * Add GitHub Pull Request Template * Feature request issue template * Touch up feature request template * Add 'other issues' template * move support doc * Minor tweaks * More minor tweaks * Spleeling fix Co-Authored-By: drashna * CapiTALization fIXes Co-Authored-By: drashna * Use new issue URL Co-Authored-By: drashna * Add blanck issue template * Update the PR template * Formatting and additional changes * Update docs/support.md Co-Authored-By: drashna --- .github/ISSUE_TEMPLATE/blank.md | 5 ++++ .github/ISSUE_TEMPLATE/bug_report.md | 31 ++++++++++++++++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 19 ++++++++++++++ .github/ISSUE_TEMPLATE/other_issues.md | 9 +++++++ .github/PULL_REQUEST_TEMPLATE.md | 32 +++++++++++++++++++++++ docs/_sidebar.md | 1 + docs/_summary.md | 1 + docs/support.md | 43 +++++++++++++++++++++++++++++++ 8 files changed, 141 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/blank.md create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/ISSUE_TEMPLATE/other_issues.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 docs/support.md (limited to 'docs/_summary.md') diff --git a/.github/ISSUE_TEMPLATE/blank.md b/.github/ISSUE_TEMPLATE/blank.md new file mode 100644 index 0000000000..50a32034d6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/blank.md @@ -0,0 +1,5 @@ +--- +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 new file mode 100644 index 0000000000..a4f90389b0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,31 @@ +--- +name: Bug report +about: Create a report to help us improve the QMK Firmware +--- + + + + + +**Describe the bug** + + + +**System Information** + - Keyboard: + - Revision (if applicable): + - Operating System: + - avr-gcc version: + + - arm gcc version: + + - QMK Firmware version: + + - Any keyboard related software installed? + - [ ] Auto Hot Key + - [ ] Karabiner + - [ ] Other + +**Additional context** + + diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000000..c9198adff2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,19 @@ +--- +name: Feature request +about: Suggest a new feature or changes to existing features +--- + + + + + +## Feature Request Type + +- [ ] Core Functionality +- [ ] Add-on hardware support (e.g. audio, RGB, OLED screen, etc.) +- [ ] Alteration (enhancement/optimization) of existing Feature(s) +- [ ] New behavior + +## Description + + diff --git a/.github/ISSUE_TEMPLATE/other_issues.md b/.github/ISSUE_TEMPLATE/other_issues.md new file mode 100644 index 0000000000..5f3e986cc4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/other_issues.md @@ -0,0 +1,9 @@ +--- +name: Other issues +about: Anything else that doesn't fall into the above categories. +--- + + + + + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000000..05223aa4f6 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,32 @@ + + + + + +## Description + + +## Types of changes + +- [ ] Core +- [ ] Bugfix +- [ ] New Feature +- [ ] Enhancement/Optimization +- [ ] Keyboard (addition or update) +- [ ] Keymap/Layout/Userspace (addition or update) +- [ ] Documentation + + +## Issues Fixed or Closed by this PR + +* + +## Checklist: + + +- [ ] My code follows the code style of this project. +- [ ] 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) +- [ ] I have added tests to cover my changes. +- [ ] I have tested the changes and verified that they work and don't break anything (as well as I can manage). diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 6338d69121..b209c5e0b8 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -88,6 +88,7 @@ * Other Topics * [Using Eclipse with QMK](eclipse.md) + * [Support](support.md) * QMK Internals (In Progress) * [Defines](internals_defines.md) diff --git a/docs/_summary.md b/docs/_summary.md index 6338d69121..b209c5e0b8 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -88,6 +88,7 @@ * Other Topics * [Using Eclipse with QMK](eclipse.md) + * [Support](support.md) * QMK Internals (In Progress) * [Defines](internals_defines.md) diff --git a/docs/support.md b/docs/support.md new file mode 100644 index 0000000000..5c275b07e4 --- /dev/null +++ b/docs/support.md @@ -0,0 +1,43 @@ +# Support + +If you need help with something, the best place to get quick support is going to be on our [Discord Server](https://discord.gg/Uq7gcHh). There is usually somebody online, and there are a bunch of very helpful people there. + +Don't forget to read our [Code of Conduct](https://qmk.fm/coc/). + +## Help! I don't know where to start! + +If this is the case, then you should start with our [Newbs Guide](https://docs.qmk.fm/#/newbs). 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. + +## Help! I'm having issues flashing! + +First, head to the [Compiling/Flashing FAQ Page](https://docs.qmk.fm/#/faq_build). There is a good deal of info there, and you'll find a bunch of solutions to common issues there. + +## Help, I have an issue that isn't covered by the links above + +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](https://docs.qmk.fm/#/newbs_best_practices) 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](https://docs.qmk.fm/#/newbs_learn_more_resources). + +## 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). -- cgit 1.4.1