From 0e984b6e7e216a62df0b5d53f6a8f0d4bc13dca3 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Mon, 1 Mar 2021 08:57:02 -0800 Subject: Add ability to toggle One Shot functionality (#4198) Co-authored-by: Nick Brassel Co-authored-by: Ryan --- docs/keycodes.md | 3 +++ docs/one_shot_keys.md | 3 +++ 2 files changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/keycodes.md b/docs/keycodes.md index 9acf8b6839..f3c519b130 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -516,6 +516,9 @@ See also: [One Shot Keys](one_shot_keys.md) |------------|----------------------------------| |`OSM(mod)` |Hold `mod` for one keypress | |`OSL(layer)`|Switch to `layer` for one keypress| +|`OS_ON` |Turns One Shot keys on | +|`OS_OFF` |Turns One Shot keys off | +|`OS_TOGG` |Toggles One Shot keys status | ## Space Cadet :id=space-cadet diff --git a/docs/one_shot_keys.md b/docs/one_shot_keys.md index 9a082d7d6d..9fc5486299 100644 --- a/docs/one_shot_keys.md +++ b/docs/one_shot_keys.md @@ -17,6 +17,9 @@ You can control the behavior of one shot keys by defining these in `config.h`: * `OSM(mod)` - Momentarily hold down *mod*. You must use the `MOD_*` keycodes as shown in [Mod Tap](mod_tap.md), not the `KC_*` codes. * `OSL(layer)` - momentary switch to *layer*. +* `OS_ON` - Turns on One Shot keys. +* `OS_OFF` - Turns off One Shot keys. OSM act as regular mod keys, OSL act like `MO`. +* `ON_TOGG` - Toggles the one shot key status. Sometimes, you want to activate a one-shot key as part of a macro or tap dance routine. -- cgit v1.2.3 From cde2859a6591b1274da20978bd158f20229faa88 Mon Sep 17 00:00:00 2001 From: XScorpion2 Date: Tue, 2 Mar 2021 14:32:15 -0600 Subject: Split RGB Matrix (#11055) * Split RGB Matrix * Suspend State sync for rgb matrix --- docs/feature_rgb_matrix.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index fd866bd571..878acaf8b3 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -439,6 +439,8 @@ These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blo #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) +#define RGB_MATRIX_SPLIT { X, Y } // (Optional) For split keyboards, the number of LEDs connected on each half. X = left, Y = Right. + // If RGB_MATRIX_KEYPRESSES or RGB_MATRIX_KEYRELEASES is enabled, you also will want to enable SPLIT_TRANSPORT_MIRROR ``` ## EEPROM storage :id=eeprom-storage -- cgit v1.2.3 From 18a333ec6bc9051ae7ec63a809d725c5c5f77046 Mon Sep 17 00:00:00 2001 From: Sergey Vlasov Date: Wed, 3 Mar 2021 07:26:06 +0300 Subject: Add support for complementary outputs to the WS2812 PWM driver (#11988) --- docs/ws2812_driver.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs') diff --git a/docs/ws2812_driver.md b/docs/ws2812_driver.md index cca6827ec8..fa14f02fdb 100644 --- a/docs/ws2812_driver.md +++ b/docs/ws2812_driver.md @@ -102,11 +102,14 @@ Configure the hardware via your config.h: #define WS2812_PWM_DRIVER PWMD2 // default: PWMD2 #define WS2812_PWM_CHANNEL 2 // default: 2 #define WS2812_PWM_PAL_MODE 2 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 2 +//#define WS2812_PWM_COMPLEMENTARY_OUTPUT // Define for a complementary timer output (TIMx_CHyN); omit for a normal timer output (TIMx_CHy). #define WS2812_DMA_STREAM STM32_DMA1_STREAM2 // DMA Stream for TIMx_UP, see the respective reference manual for the appropriate values for your MCU. #define WS2812_DMA_CHANNEL 2 // DMA Channel for TIMx_UP, see the respective reference manual for the appropriate values for your MCU. #define WS2812_DMAMUX_ID STM32_DMAMUX1_TIM2_UP // DMAMUX configuration for TIMx_UP -- only required if your MCU has a DMAMUX peripheral, see the respective reference manual for the appropriate values for your MCU. ``` +Note that using a complementary timer output (TIMx_CHyN) is possible only for advanced-control timers (TIM1, TIM8, TIM20 on STM32), and the `STM32_PWM_USE_ADVANCED` option in mcuconf.h must be set to `TRUE`. Complementary outputs of general-purpose timers are not supported due to ChibiOS limitations. + You must also turn on the PWM feature in your halconf.h and mcuconf.h #### Testing Notes -- cgit v1.2.3 From 6f7466b6dd72e161b61683e26b7720421d8cc9bd Mon Sep 17 00:00:00 2001 From: Xelus22 <17491233+Xelus22@users.noreply.github.com> Date: Fri, 19 Mar 2021 08:29:18 +0000 Subject: ARM WS2812 SPI config (baudrate and circular buffer) (#12216) * initial commit * include circular buffer command * add endif * circular buffer mode * remove untrue comment * revamp and add documentation * do not allow WS2812_SPI_SYNC & CIRCULAR_BUFFER --- docs/ws2812_driver.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'docs') diff --git a/docs/ws2812_driver.md b/docs/ws2812_driver.md index fa14f02fdb..e69400364c 100644 --- a/docs/ws2812_driver.md +++ b/docs/ws2812_driver.md @@ -77,6 +77,25 @@ Configure the hardware via your config.h: You must also turn on the SPI feature in your halconf.h and mcuconf.h +#### Circular Buffer Mode +Some boards may flicker while in the normal buffer mode. To fix this issue, circular buffer mode may be used to rectify the issue. + +By default, the circular buffer mode is disabled. + +To enable this alternative buffer mode, place this into your `config.h` file: +```c +#define WS2812_SPI_USE_CIRCULAR_BUFFER +``` + +#### Setting baudrate with divisor +To adjust the baudrate at which the SPI peripheral is configured, users will need to derive the target baudrate from the clock tree provided by STM32CubeMX. + +Only divisors of 2, 4, 8, 16, 32, 64, 128 and 256 are supported by hardware. + +|Define |Default|Description | +|--------------------|-------|-------------------------------------| +|`WS2812_SPI_DIVISOR`|`16` |SPI source clock peripheral divisor | + #### Testing Notes While not an exhaustive list, the following table provides the scenarios that have been partially validated: -- cgit v1.2.3 From a8d64c8b897fc7cb5be372d9580801fd1e4f8a9e Mon Sep 17 00:00:00 2001 From: James Young <18669334+noroadsleft@users.noreply.github.com> Date: Mon, 12 Apr 2021 12:18:52 -0700 Subject: Change `BOOTMAGIC_ENABLE=yes` to use Bootmagic Lite (#12172) --- docs/ChangeLog/20210529/PR12172.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 docs/ChangeLog/20210529/PR12172.md (limited to 'docs') diff --git a/docs/ChangeLog/20210529/PR12172.md b/docs/ChangeLog/20210529/PR12172.md new file mode 100644 index 0000000000..0c355c151e --- /dev/null +++ b/docs/ChangeLog/20210529/PR12172.md @@ -0,0 +1,13 @@ +## Bootmagic Deprecation and Refactor ([#12172](https://github.com/qmk/qmk_firmware/pull/12172)) + +QMK has decided to deprecate the full Bootmagic feature and leave Bootmagic Lite as the only remaining option. + +This pull request changes the behavior of `BOOTMAGIC_ENABLE` such that specifying `BOOTMAGIC_ENABLE = yes` enables Bootmagic Lite instead of full Bootmagic. + +### Tentative Deprecation Schedule + +This is the current planned roadmap for the behavior of `BOOTMAGIC_ENABLE`: + +- From 2021-05-29, setting `BOOTMAGIC_ENABLE = yes` will enable Bootmagic Lite instead of full Bootmagic. +- From 2021-08-28, `BOOTMAGIC_ENABLE` must be either `yes`, `lite`, or `no` – setting `BOOTMAGIC_ENABLE = full` will cause compilation to fail. +- From 2021-11-27, `BOOTMAGIC_ENABLE` must be either `yes` or `no` – setting `BOOTMAGIC_ENABLE = lite` will cause compilation to fail. -- cgit v1.2.3 From a28fbcda2306634c74e196ce98f8bebb701445b0 Mon Sep 17 00:00:00 2001 From: Ryan Date: Tue, 13 Apr 2021 19:51:31 +1000 Subject: Terrazzo: Fix wrong LED Matrix function names (#12561) --- docs/feature_led_matrix.md | 2 +- docs/ja/feature_led_matrix.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/feature_led_matrix.md b/docs/feature_led_matrix.md index f4a6616340..ac2be2e775 100644 --- a/docs/feature_led_matrix.md +++ b/docs/feature_led_matrix.md @@ -79,7 +79,7 @@ Custom layer effects can be done by defining this in your `.c`: ```c void led_matrix_indicators_kb(void) { - led_matrix_set_index_value(index, value); + led_matrix_set_value(index, value); } ``` diff --git a/docs/ja/feature_led_matrix.md b/docs/ja/feature_led_matrix.md index b73487ca63..62e22859fb 100644 --- a/docs/ja/feature_led_matrix.md +++ b/docs/ja/feature_led_matrix.md @@ -76,7 +76,7 @@ I2C IS31FL3731 RGB コントローラを使ったアドレス指定可能な LED カスタムレイヤー効果は `.c` 内で以下を定義することで行うことができます: void led_matrix_indicators_kb(void) { - led_matrix_set_index_value(index, value); + led_matrix_set_value(index, value); } 同様の関数がキーマップ内で `led_matrix_indicators_user` として動作します。 -- cgit v1.2.3 From e2289ffac09e86da32a331ce688e9cd3875e1cd6 Mon Sep 17 00:00:00 2001 From: Joshua Diamond Date: Thu, 15 Apr 2021 19:32:17 -0400 Subject: Add missing RGB_MODE_TWINKLE / RGB_M_TW keycodes (#11935) * Add missing RGB_MODE_TWINKLE / RGB_M_TW keycodes * Better comment Co-authored-by: Ryan Co-authored-by: Ryan --- docs/feature_rgblight.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index d2612a6d1b..8e8d6b81c3 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -74,6 +74,7 @@ Changing the **Value** sets the overall brightness.
|`RGB_MODE_XMAS` |`RGB_M_X` |Christmas animation mode | |`RGB_MODE_GRADIENT`|`RGB_M_G` |Static gradient animation mode | |`RGB_MODE_RGBTEST` |`RGB_M_T` |Red, Green, Blue test animation mode | +|`RGB_MODE_TWINKLE` |`RGB_M_TW`|Twinkle 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. -- cgit v1.2.3 From 180a32ec59339cf07323412457ec771fba69ea61 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Sun, 18 Apr 2021 23:26:37 -0700 Subject: Enhancement of WPM feature (#11727) --- docs/feature_wpm.md | 67 +++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 52 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/feature_wpm.md b/docs/feature_wpm.md index 12dd080579..c8ec3a7f32 100644 --- a/docs/feature_wpm.md +++ b/docs/feature_wpm.md @@ -1,25 +1,62 @@ # 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. +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. +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. +## Configuration +|Define |Default | Description | +|-----------------------------|--------------|------------------------------------------------------------------------------------------| +|`WPM_SMOOTHING` |`0.0487` | Sets the smoothing to about 40 keystrokes | +|`WPM_ESTIMATED_WORD_SIZE` |`5` | This is the value used when estimating average word size (for regression and normal use) | +|`WPM_ALLOW_COUNT_REGRESSOIN` |_Not defined_ | If defined allows the WPM to be decreased when hitting Delete or Backspace | +## Public Functions -## 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. +|Function |Description | +|--------------------------|--------------------------------------------------| +|`get_current_wpm(void)` | Returns the current WPM as a value between 0-255 | +|`set_current_wpm(x)` | Sets the current WPM to `x` (between 0-255) | + +## Callbacks + +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 your own `bool 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. + +For instance, the default is: + +```c +bool wpm_keycode_user(uint16_t keycode) { + if ((keycode >= QK_MOD_TAP && keycode <= QK_MOD_TAP_MAX) || (keycode >= QK_LAYER_TAP && keycode <= QK_LAYER_TAP_MAX) || (keycode >= QK_MODS && keycode <= QK_MODS_MAX)) { + keycode = keycode & 0xFF; + } else if (keycode > 0xFF) { + keycode = 0; + } + if ((keycode >= KC_A && keycode <= KC_0) || (keycode >= KC_TAB && keycode <= KC_SLASH)) { + return true; + } + + return false; +} +``` + +Additionally, if `WPM_ALLOW_COUNT_REGRESSION` is defined, there is the `uint8_t wpm_regress_count(uint16_t keycode)` function that allows you to decrease the WPM. This is useful if you want to be able to penalize certain keycodes (or even combinations). + +__attribute__((weak)) uint8_t wpm_regress_count(uint16_t keycode) { + bool weak_modded = (keycode >= QK_LCTL && keycode < QK_LSFT) || (keycode >= QK_RCTL && keycode < QK_RSFT); + + if ((keycode >= QK_MOD_TAP && keycode <= QK_MOD_TAP_MAX) || (keycode >= QK_LAYER_TAP && keycode <= QK_LAYER_TAP_MAX) || (keycode >= QK_MODS && keycode <= QK_MODS_MAX)) { + keycode = keycode & 0xFF; + } else if (keycode > 0xFF) { + keycode = 0; + } + if (((get_mods() | get_oneshot_mods()) & MOD_MASK_CTRL} || weak_modded) && (keycode == KC_DEL || keycode == KC_BSPC)) { + return WPM_ESTIMATED_WORD_SIZE; + } + if (keycode == KC_DEL || keycode == KC_BSPC) { + return 1; + } +} -- cgit v1.2.3 From c02137a0d245a7be8ca44cf46f05a632cc8fc702 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Mon, 19 Apr 2021 20:34:14 -0700 Subject: Add Per Key functionality for AutoShift (#11536) Co-authored-by: Ryan --- docs/feature_auto_shift.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'docs') diff --git a/docs/feature_auto_shift.md b/docs/feature_auto_shift.md index 8e04d9dd38..ec7eeaaa0c 100644 --- a/docs/feature_auto_shift.md +++ b/docs/feature_auto_shift.md @@ -109,6 +109,33 @@ Do not Auto Shift numeric keys, zero through nine. Do not Auto Shift alpha characters, which include A through Z. +### Auto Shift Per Key + +This is a function that allows you to determine which keys shold be autoshifted, much like the tap-hold keys. + +The default function looks like this: + +```c +bool get_auto_shifted_key(uint16_t keycode, keyrecord_t *record) { + switch (keycode) { +# ifndef NO_AUTO_SHIFT_ALPHA + case KC_A ... KC_Z: +# endif +# ifndef NO_AUTO_SHIFT_NUMERIC + case KC_1 ... KC_0: +# endif +# ifndef NO_AUTO_SHIFT_SPECIAL + case KC_TAB: + case KC_MINUS ... KC_SLASH: + case KC_NONUS_BSLASH: +# endif + return true; + } + return false; +} +``` +This functionality is enabled by default, and does not need a define. + ### AUTO_SHIFT_REPEAT (simple define) Enables keyrepeat. -- cgit v1.2.3 From 26b9b3aa2308a24e069f5ae2ab86e3df24492eed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Rodr=C3=ADguez=20Rivero?= Date: Sun, 25 Apr 2021 02:22:47 +0200 Subject: feat: infinite timeout for leader key (#6580) * feat: implement leader_no_timeout logic * docs(leader_key): infinite leader timeout docs --- docs/feature_leader_key.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'docs') diff --git a/docs/feature_leader_key.md b/docs/feature_leader_key.md index 41ff8f1a4e..f10bca7589 100644 --- a/docs/feature_leader_key.md +++ b/docs/feature_leader_key.md @@ -72,6 +72,19 @@ SEQ_THREE_KEYS(KC_C, KC_C, KC_C) { } ``` +## Infinite Leader key timeout + +Sometimes your leader key is not on a comfortable places as the rest of keys on your sequence. Imagine that your leader key is one of your outer top right keys, you may need to reposition your hand just to reach your leader key. +This can make typing the entire sequence on time hard even if you are able to type most of the sequence fast. For example, if your sequence is `Leader + asd` typing `asd` fast is very easy once you have your hands in your home row. However starting the sequence in time after moving your hand out of the home row to reach the leader key and back is not. +To remove the stress this situation produces to your hands you can enable an infinite timeout just for the leader key. This mean that, after you hit the leader key you will have an infinite amount of time to start the rest of the sequence, allowing you to proper position your hands on the best position to type the rest of the sequence comfortably. +This infinite timeout only affects the leader key, so in our previous example of `Leader + asd` you will have an infinite amount of time between `Leader` and `a`, but once you start the sequence the timeout you have configured (global or per key) will work normally. +This way you can configure a very short `LEADER_TIMEOUT` but still have plenty of time to position your hands. + +In order to enable this, place this in your `config.h`: +```c +#define LEADER_NO_TIMEOUT +``` + ## Strict Key Processing 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. -- cgit v1.2.3 From 65c97527624d4865d3867371722742c477f71268 Mon Sep 17 00:00:00 2001 From: Sergey Vlasov Date: Sun, 25 Apr 2021 04:15:37 +0300 Subject: Update ADC driver for STM32F1xx, STM32F3xx, STM32F4xx (#12403) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Fix default ADC_RESOLUTION for ADCv3 (and ADCv4) Recent ChibiOS update removed ADC_CFGR1_RES_10BIT from the ADCv3 headers (that macro should not have been there, because ADCv3 has CFGR instead of CFGR1). Fix the default value for ADC_RESOLUTION to use ADC_CFGR_RES_10BITS if it is defined (that name is used for ADCv3 and ADCv4). * Update ADC docs to match the actually used resolution ADC driver for ChibiOS actually uses the 10-bit resolution by default (probably to match AVR); fix the documentation accordingly. Also add both ADC_CFGR_RES_10BITS and ADC_CFGR1_RES_10BIT constants (these names differ according to the ADC implementation in the particular MCU). * Fix pinToMux() for B12 and B13 on STM32F3xx Testing on STM32F303CCT6 revealed that the ADC mux values for B12 and B13 pins were wrong. * Add support for all possible analog pins on STM32F1xx Added ADC mux values for pins A0...A7, B0, B1, C0...C5 on STM32F1xx (they are the same at least for STM32F103x8 and larger F103 devices, and also F102, F105, F107 families). Actually tested on STM32F103C8T6 (therefore pins C0...C5 were not tested). Pins F6...F10, which are present on STM32F103x[C-G] in 144-pin packages, cannot be supported at the moment, because those pins are connected only to ADC3, but the ChibiOS ADC driver for STM32F1xx supports only ADC1. * Add support for all possible analog pins on STM32F4xx Added ADC mux values for pins A0...A7, B0, B1, C0...C5 and optionally F3...F10 (if STM32_ADC_USE_ADC3 is enabled). These mux values are apparently the same for all F4xx devices, except some smaller devices may not have ADC3. Actually tested on STM32F401CCU6, STM32F401CEU6, STM32F411CEU6 (using various WeAct “Blackpill” boards); only pins A0...A7, B0, B1 were tested. Pins F3...F10 are inside `#if STM32_ADC_USE_ADC3` because some devices which don't have ADC3 also don't have the GPIOF port, therefore the code which refers to Fx pins does not compile. * Fix STM32F3xx ADC mux table in documentation The ADC driver documentation had some errors in the mux table for STM32F3xx. Fix this table to match the datasheet and the actual code (mux settings for B12 and B13 were also tested on a real STM32F303CCT6 chip). * Add STM32F1xx ADC pins to the documentation * Add STM32F4xx ADC pins to the documentation --- docs/adc_driver.md | 154 ++++++++++++++++++++++++++++------------------------- 1 file changed, 80 insertions(+), 74 deletions(-) (limited to 'docs') diff --git a/docs/adc_driver.md b/docs/adc_driver.md index 6e3d513863..69fff4b3c2 100644 --- a/docs/adc_driver.md +++ b/docs/adc_driver.md @@ -47,73 +47,79 @@ Note that some of these pins are doubled-up on ADCs with the same channel. This Also note that the F0 and F3 use different numbering schemes. The F0 has a single ADC and the channels are 0-indexed, whereas the F3 has 4 ADCs and the channels are 1-indexed. This is because the F0 uses the `ADCv1` implementation of the ADC, whereas the F3 uses the `ADCv3` implementation. -|ADC|Channel|STM32F0xx|STM32F3xx| -|---|-------|---------|---------| -|1 |0 |`A0` | | -|1 |1 |`A1` |`A0` | -|1 |2 |`A2` |`A1` | -|1 |3 |`A3` |`A2` | -|1 |4 |`A4` |`A3` | -|1 |5 |`A5` |`F4` | -|1 |6 |`A6` |`C0` | -|1 |7 |`A7` |`C1` | -|1 |8 |`B0` |`C2` | -|1 |9 |`B1` |`C3` | -|1 |10 |`C0` |`F2` | -|1 |11 |`C1` | | -|1 |12 |`C2` | | -|1 |13 |`C3` | | -|1 |14 |`C4` | | -|1 |15 |`C5` | | -|1 |16 | | | -|2 |1 | |`A4` | -|2 |2 | |`A5` | -|2 |3 | |`A6` | -|2 |4 | |`A7` | -|2 |5 | |`C4` | -|2 |6 | |`C0` | -|2 |7 | |`C1` | -|2 |8 | |`C2` | -|2 |9 | |`C3` | -|2 |10 | |`F2` | -|2 |11 | |`C5` | -|2 |12 | |`B2` | -|2 |13 | | | -|2 |14 | | | -|2 |15 | | | -|2 |16 | | | -|3 |1 | |`B1` | -|3 |2 | |`E9` | -|3 |3 | |`E13` | -|3 |4 | | | -|3 |5 | | | -|3 |6 | |`E8` | -|3 |7 | |`D10` | -|3 |8 | |`D11` | -|3 |9 | |`D12` | -|3 |10 | |`D13` | -|3 |11 | |`D14` | -|3 |12 | |`B0` | -|3 |13 | |`E7` | -|3 |14 | |`E10` | -|3 |15 | |`E11` | -|3 |16 | |`E12` | -|4 |1 | |`E14` | -|4 |2 | |`B12` | -|4 |3 | |`B13` | -|4 |4 | |`B14` | -|4 |5 | |`B15` | -|4 |6 | |`E8` | -|4 |7 | |`D10` | -|4 |8 | |`D11` | -|4 |9 | |`D12` | -|4 |10 | |`D13` | -|4 |11 | |`D14` | -|4 |12 | |`D8` | -|4 |13 | |`D9` | -|4 |14 | | | -|4 |15 | | | -|4 |16 | | | +|ADC|Channel|STM32F0xx|STM32F1xx|STM32F3xx|STM32F4xx| +|---|-------|---------|---------|---------|---------| +|1 |0 |`A0` |`A0` | |`A0` | +|1 |1 |`A1` |`A1` |`A0` |`A1` | +|1 |2 |`A2` |`A2` |`A1` |`A2` | +|1 |3 |`A3` |`A3` |`A2` |`A3` | +|1 |4 |`A4` |`A4` |`A3` |`A4` | +|1 |5 |`A5` |`A5` |`F4` |`A5` | +|1 |6 |`A6` |`A6` |`C0` |`A6` | +|1 |7 |`A7` |`A7` |`C1` |`A7` | +|1 |8 |`B0` |`B0` |`C2` |`B0` | +|1 |9 |`B1` |`B1` |`C3` |`B1` | +|1 |10 |`C0` |`C0` |`F2` |`C0` | +|1 |11 |`C1` |`C1` | |`C1` | +|1 |12 |`C2` |`C2` | |`C2` | +|1 |13 |`C3` |`C3` | |`C3` | +|1 |14 |`C4` |`C4` | |`C4` | +|1 |15 |`C5` |`C5` | |`C5` | +|1 |16 | | | | | +|2 |0 | |`A0`¹ | |`A0`² | +|2 |1 | |`A1`¹ |`A4` |`A1`² | +|2 |2 | |`A2`¹ |`A5` |`A2`² | +|2 |3 | |`A3`¹ |`A6` |`A3`² | +|2 |4 | |`A4`¹ |`A7` |`A4`² | +|2 |5 | |`A5`¹ |`C4` |`A5`² | +|2 |6 | |`A6`¹ |`C0` |`A6`² | +|2 |7 | |`A7`¹ |`C1` |`A7`² | +|2 |8 | |`B0`¹ |`C2` |`B0`² | +|2 |9 | |`B1`¹ |`C3` |`B1`² | +|2 |10 | |`C0`¹ |`F2` |`C0`² | +|2 |11 | |`C1`¹ |`C5` |`C1`² | +|2 |12 | |`C2`¹ |`B2` |`C2`² | +|2 |13 | |`C3`¹ | |`C3`² | +|2 |14 | |`C4`¹ | |`C4`² | +|2 |15 | |`C5`¹ | |`C5`² | +|2 |16 | | | | | +|3 |0 | |`A0`¹ | |`A0`² | +|3 |1 | |`A1`¹ |`B1` |`A1`² | +|3 |2 | |`A2`¹ |`E9` |`A2`² | +|3 |3 | |`A3`¹ |`E13` |`A3`² | +|3 |4 | |`F6`¹ | |`F6`² | +|3 |5 | |`F7`¹ |`B13` |`F7`² | +|3 |6 | |`F8`¹ |`E8` |`F8`² | +|3 |7 | |`F9`¹ |`D10` |`F9`² | +|3 |8 | |`F10`¹ |`D11` |`F10`² | +|3 |9 | | |`D12` |`F3`² | +|3 |10 | |`C0`¹ |`D13` |`C0`² | +|3 |11 | |`C1`¹ |`D14` |`C1`² | +|3 |12 | |`C2`¹ |`B0` |`C2`² | +|3 |13 | |`C3`¹ |`E7` |`C3`² | +|3 |14 | | |`E10` |`F4`² | +|3 |15 | | |`E11` |`F5`² | +|3 |16 | | |`E12` | | +|4 |1 | | |`E14` | | +|4 |2 | | |`E15` | | +|4 |3 | | |`B12` | | +|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 | | | | | + +¹ As of ChibiOS 20.3.4, the ADC driver for STM32F1xx devices supports only ADC1, therefore any configurations involving ADC2 or ADC3 cannot actually be used. In particular, pins `F6`…`F10`, which are present at least on some STM32F103x[C-G] devices, cannot be used as ADC inputs because of this driver limitation. + +² Not all STM32F4xx devices have ADC2 and/or ADC3, therefore some configurations shown in this table may be unavailable; in particular, pins `F4`…`F10` cannot be used as ADC inputs on devices which do not have ADC3. Check the device datasheet to confirm which pin functions are supported. ## Functions @@ -141,10 +147,10 @@ Also note that the F0 and F3 use different numbering schemes. The F0 has a singl The ARM implementation of the ADC has a few additional options that you can override in your own keyboards and keymaps to change how it operates. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options. -|`#define` |Type |Default |Description | -|---------------------|------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|`ADC_CIRCULAR_BUFFER`|`bool`|`false` |If `true`, then the implementation will use a circular buffer. | -|`ADC_NUM_CHANNELS` |`int` |`1` |Sets the number of channels that will be scanned as part of an ADC operation. The current implementation only supports `1`. | -|`ADC_BUFFER_DEPTH` |`int` |`2` |Sets the depth of each result. Since we are only getting a 12-bit result by default, we set this to 2 bytes so we can contain our one value. This could be set to 1 if you opt for an 8-bit or lower result.| -|`ADC_SAMPLING_RATE` |`int` |`ADC_SMPR_SMP_1P5` |Sets the sampling rate of the ADC. By default, it is set to the fastest setting. | -|`ADC_RESOLUTION` |`int` |`ADC_CFGR1_RES_12BIT`|The resolution of your result. We choose 12 bit by default, but you can opt for 12, 10, 8, or 6 bit. | +|`#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 10-bit result by default, we set this to 2 bytes so we can contain our one value. This could be set to 1 if you opt for an 8-bit or lower result.| +|`ADC_SAMPLING_RATE` |`int` |`ADC_SMPR_SMP_1P5` |Sets the sampling rate of the ADC. By default, it is set to the fastest setting. | +|`ADC_RESOLUTION` |`int` |`ADC_CFGR1_RES_10BIT` or `ADC_CFGR_RES_10BITS`|The resolution of your result. We choose 10 bit by default, but you can opt for 12, 10, 8, or 6 bit. Different MCUs use slightly different names for the resolution constants. | -- cgit v1.2.3 From 891d18d3565090abd5f218a8787acc3e25349b73 Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Sun, 25 Apr 2021 13:40:56 +1000 Subject: Add initial support for tinyuf2 bootloader (when hosted on F411 blackpill) (#12600) * Add support for jumping to tinyuf2 bootloader. Adds blackpill UF2 example. * Update flashing.md * Update chconf.h * Update config.h * Update halconf.h * Update mcuconf.h --- docs/flashing.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'docs') diff --git a/docs/flashing.md b/docs/flashing.md index 7804a6bad8..83c97444e1 100644 --- a/docs/flashing.md +++ b/docs/flashing.md @@ -249,3 +249,29 @@ Flashing sequence: 2. Wait for the OS to detect the device 3. Flash a .bin file 4. Reset the device into application mode (may be done automatically) + +## tinyuf2 + +Keyboards may opt into supporting the tinyuf2 bootloader. This is currently only supported on the F411 blackpill. + +The `rules.mk` setting for this bootloader is `tinyuf2`, and can be specified at the keymap or user level. + +To ensure compatibility with the tinyuf2 bootloader, make sure this block is present in your `rules.mk`: + +```make +# Bootloader selection +BOOTLOADER = tinyuf2 +``` + +Compatible flashers: + +* Any application able to copy a file from one place to another, such as _macOS Finder_ or _Windows Explorer_. + +Flashing sequence: + +1. Enter the bootloader using any of the following methods: + * Tap the `RESET` keycode + * Double-tap the `nRST` button on the PCB. +2. Wait for the OS to detect the device +3. Copy the .uf2 file to the new USB disk +4. Wait for the keyboard to become available -- cgit v1.2.3 From 3f7350732c9722b87ea52eee740e587a70b8fb38 Mon Sep 17 00:00:00 2001 From: Purdea Andrei Date: Sun, 25 Apr 2021 11:59:25 +0300 Subject: Add support for MCU = STM32F446 (#12619) * Add support for MCU = STM32F446 * Update platforms/chibios/GENERIC_STM32_F446XE/configs/config.h Co-authored-by: Nick Brassel * Restore mcuconf.h to the one used by RT-STM32F446RE-NUCLEO64 * stm32f446: update mcuconf.h and board.h for 16MHz operation, with USB enabled, and other peripherals disabled. Co-authored-by: Nick Brassel --- docs/compatible_microcontrollers.md | 1 + docs/ja/compatible_microcontrollers.md | 1 + 2 files changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md index 47a4844e7f..5e16ab2770 100644 --- a/docs/compatible_microcontrollers.md +++ b/docs/compatible_microcontrollers.md @@ -28,6 +28,7 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s * [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html) * [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html) * [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html) + * [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html) * [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html) * [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html) diff --git a/docs/ja/compatible_microcontrollers.md b/docs/ja/compatible_microcontrollers.md index fdd11f14fa..69da70f2c3 100644 --- a/docs/ja/compatible_microcontrollers.md +++ b/docs/ja/compatible_microcontrollers.md @@ -33,6 +33,7 @@ QMK は十分な容量のフラッシュメモリを備えた USB 対応 AVR ま * [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html) * [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html) * [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html) +* [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html) * [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html) * [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html) -- cgit v1.2.3 From 9cf82fae9566c68ea2ffcb120375868f27f94ecf Mon Sep 17 00:00:00 2001 From: Xelus22 <17491233+Xelus22@users.noreply.github.com> Date: Mon, 26 Apr 2021 03:07:15 +0000 Subject: Add STM32L433 and L443 support (#12063) * initial L433 commit * change to XC * fix L433 * disable all peripherals * update system and peripheral clocks * 433 change * use its own board files * revert its own board files * l433 specific change * fix stm32l432xx define * remove duplicate #define * fix bootloader jump * move to L443xx and add i2c2, spi2, usart3 to mcuconf.h * move to L443 * move to L443 * fix sdmmc in mcuconf.h * include STM32L443 * add L443 * Include L443 in compatible microcontrollers Co-authored-by: Nick Brassel * Include L443 in compatible microcontrollers Co-authored-by: Nick Brassel * Update config bootloader jump description Co-authored-by: Nick Brassel * Update ChibiOS define reasoning Co-authored-by: Nick Brassel * Update quantum/mcu_selection.mk Co-authored-by: Nick Brassel * fix git conflict Co-authored-by: Nick Brassel --- docs/compatible_microcontrollers.md | 2 ++ docs/ja/compatible_microcontrollers.md | 2 ++ 2 files changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md index 5e16ab2770..0f5b140de0 100644 --- a/docs/compatible_microcontrollers.md +++ b/docs/compatible_microcontrollers.md @@ -31,6 +31,8 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s * [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html) * [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html) * [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html) + * [STM32L433](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html) + * [STM32L443](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html) ### NXP (Kinetis) diff --git a/docs/ja/compatible_microcontrollers.md b/docs/ja/compatible_microcontrollers.md index 69da70f2c3..b675b038d2 100644 --- a/docs/ja/compatible_microcontrollers.md +++ b/docs/ja/compatible_microcontrollers.md @@ -36,6 +36,8 @@ QMK は十分な容量のフラッシュメモリを備えた USB 対応 AVR ま * [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html) * [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html) * [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html) +* [STM32L433](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html) +* [STM32L443](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html) ### NXP (Kinetis) -- cgit v1.2.3 From d8167779cdfb243cb140782210d2cc6a7cb9b123 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Wed, 28 Apr 2021 19:39:54 -0700 Subject: Change RGB/LED Matrix to use a simple define for USB suspend (#12697) --- docs/feature_rgb_matrix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 046b1f17fa..63ff7d6ad6 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -437,7 +437,7 @@ These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blo #define RGB_MATRIX_KEYRELEASES // reacts to keyreleases (instead of keypresses) #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_DISABLE_WHEN_USB_SUSPENDED // 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 -- cgit v1.2.3 From fca7cc1747642d077898e301945df86bfdea0784 Mon Sep 17 00:00:00 2001 From: Barabas Date: Sat, 8 May 2021 11:27:13 +0100 Subject: Added OLED fade out support (#12086) --- docs/feature_oled_driver.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/feature_oled_driver.md b/docs/feature_oled_driver.md index 44202487f1..d2dc6103a6 100644 --- a/docs/feature_oled_driver.md +++ b/docs/feature_oled_driver.md @@ -145,6 +145,8 @@ void oled_task_user(void) { |`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_FADE_OUT` |*Not defined* |Enables fade out animation. Use together with `OLED_TIMEOUT`. | +|`OLED_FADE_OUT_INTERVAL` |`0` |The speed of fade out animation, from 0 to 15. Larger values are slower. | |`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. | -- cgit v1.2.3 From 7a25dcacffcadf541da5107a35856b66e770bcaf Mon Sep 17 00:00:00 2001 From: Zach White Date: Sat, 8 May 2021 20:56:07 -0700 Subject: New command: qmk console (#12828) * stash poc * stash * tidy up implementation * Tidy up slightly for review * Tidy up slightly for review * Bodge environment to make tests pass * Refactor away from asyncio due to windows issues * Filter devices * align vid/pid printing * Add hidapi to the installers * start preparing for multiple hid_listeners * udev rules for hid_listen * refactor to move closer to end state * very basic implementation of the threaded model * refactor how vid/pid/index are supplied and parsed * windows improvements * read the report directly when usage page isn't available * add per-device colors, the choice to show names or numbers, and refactor * add timestamps * Add support for showing bootloaders * tweak the color for bootloaders * Align bootloader disconnect with connect color * add support for showing all bootloaders * fix the pyusb check * tweaks * fix exception * hide a stack trace behind -v * add --no-bootloaders option * add documentation for qmk console * Apply suggestions from code review Co-authored-by: Ryan * pyformat * clean up and flesh out KNOWN_BOOTLOADERS Co-authored-by: zvecr Co-authored-by: Ryan --- docs/cli_commands.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) (limited to 'docs') diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 05e9306070..581342093a 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -107,6 +107,54 @@ This command lets you configure the behavior of QMK. For the full `qmk config` d qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN] ``` +## `qmk console` + +This command lets you connect to keyboard consoles to get debugging messages. It only works if your keyboard firmware has been compiled with `CONSOLE_ENABLED=yes`. + +**Usage**: + +``` +qmk console [-d :[:]] [-l] [-n] [-t] [-w ] +``` + +**Examples**: + +Connect to all available keyboards and show their console messages: + +``` +qmk console +``` + +List all devices: + +``` +qmk console -l +``` + +Show only messages from clueboard/66/rev3 keyboards: + +``` +qmk console -d C1ED:2370 +``` + +Show only messages from the second clueboard/66/rev3: + +``` +qmk console -d C1ED:2370:2 +``` + +Show timestamps and VID:PID instead of names: + +``` +qmk console -n -t +``` + +Disable bootloader messages: + +``` +qmk console --no-bootloaders +``` + ## `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. -- cgit v1.2.3 From f0b30e0027cb890c7510fa22e5824a43c0d9e86f Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Sun, 9 May 2021 23:21:09 -0700 Subject: Make Swap Hands use PROGMEM (#12284) This converts the array that the Swap Hands feature uses to use PROGMEM, and to read from that array, as such. Since this array never changes at runtime, there is no reason to keep it in memory. Especially for AVR boards, as memory is a precious resource. --- docs/feature_swap_hands.md | 2 +- docs/ja/feature_swap_hands.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/feature_swap_hands.md b/docs/feature_swap_hands.md index 009477d203..cbc574b6b8 100644 --- a/docs/feature_swap_hands.md +++ b/docs/feature_swap_hands.md @@ -7,7 +7,7 @@ The swap-hands action allows support for one-handed typing without requiring a s The configuration table is a simple 2-dimensional array to map from column/row to new column/row. Example `hand_swap_config` for Planck: ```C -const keypos_t hand_swap_config[MATRIX_ROWS][MATRIX_COLS] = { +const keypos_t PROGMEM hand_swap_config[MATRIX_ROWS][MATRIX_COLS] = { {{11, 0}, {10, 0}, {9, 0}, {8, 0}, {7, 0}, {6, 0}, {5, 0}, {4, 0}, {3, 0}, {2, 0}, {1, 0}, {0, 0}}, {{11, 1}, {10, 1}, {9, 1}, {8, 1}, {7, 1}, {6, 1}, {5, 1}, {4, 1}, {3, 1}, {2, 1}, {1, 1}, {0, 1}}, {{11, 2}, {10, 2}, {9, 2}, {8, 2}, {7, 2}, {6, 2}, {5, 2}, {4, 2}, {3, 2}, {2, 2}, {1, 2}, {0, 2}}, diff --git a/docs/ja/feature_swap_hands.md b/docs/ja/feature_swap_hands.md index 3150801c55..5164584e8a 100644 --- a/docs/ja/feature_swap_hands.md +++ b/docs/ja/feature_swap_hands.md @@ -12,7 +12,7 @@ 設定テーブルは列/行から新しい列/行にマップするための単純な2次元配列です。Planck の `hand_swap_config` の例: ```C -const keypos_t hand_swap_config[MATRIX_ROWS][MATRIX_COLS] = { +const keypos_t PROGMEM hand_swap_config[MATRIX_ROWS][MATRIX_COLS] = { {{11, 0}, {10, 0}, {9, 0}, {8, 0}, {7, 0}, {6, 0}, {5, 0}, {4, 0}, {3, 0}, {2, 0}, {1, 0}, {0, 0}}, {{11, 1}, {10, 1}, {9, 1}, {8, 1}, {7, 1}, {6, 1}, {5, 1}, {4, 1}, {3, 1}, {2, 1}, {1, 1}, {0, 1}}, {{11, 2}, {10, 2}, {9, 2}, {8, 2}, {7, 2}, {6, 2}, {5, 2}, {4, 2}, {3, 2}, {2, 2}, {1, 2}, {0, 2}}, -- cgit v1.2.3 From 7078d5a5bdf9a639003a124342de567c976182ff Mon Sep 17 00:00:00 2001 From: Ryan Date: Thu, 13 May 2021 12:57:57 +1000 Subject: LED Matrix: Documentation (#12685) --- docs/feature_led_matrix.md | 356 +++++++++++++++++++++++++++++++++++++++------ docs/feature_rgb_matrix.md | 4 +- 2 files changed, 313 insertions(+), 47 deletions(-) (limited to 'docs') diff --git a/docs/feature_led_matrix.md b/docs/feature_led_matrix.md index ac2be2e775..7834b940d5 100644 --- a/docs/feature_led_matrix.md +++ b/docs/feature_led_matrix.md @@ -1,34 +1,21 @@ -# LED Matrix Lighting +# LED Matrix Lighting :id=led-matrix-lighting This feature allows you to use LED matrices driven by external drivers. It hooks into the backlight system so you can use the same keycodes as backlighting to control it. If you want to use RGB LED's you should use the [RGB Matrix Subsystem](feature_rgb_matrix.md) instead. -## Driver configuration +## Driver configuration :id=driver-configuration +--- +### IS31FL3731 :id=is31fl3731 -### IS31FL3731 - -There is basic support for addressable LED matrix lighting with the I2C IS31FL3731 RGB controller. To enable it, add this to your `rules.mk`: +There is basic support for addressable LED matrix lighting with the I2C IS31FL3731 LED controller. To enable it, add this to your `rules.mk`: ```make LED_MATRIX_ENABLE = yes LED_MATRIX_DRIVER = IS31FL3731 ``` -You can use between 1 and 4 IS31FL3731 IC's. Do not specify `LED_DRIVER_ADDR_` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`: - -| Variable | Description | Default | -|----------|-------------|---------| -| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages | 100 | -| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | -| `LED_DRIVER_COUNT` | (Required) How many LED driver IC's are present | | -| `DRIVER_LED_TOTAL` | (Required) How many LED lights are present across all drivers | | -| `LED_DRIVER_ADDR_1` | (Required) Address for the first LED driver | | -| `LED_DRIVER_ADDR_2` | (Optional) Address for the second LED driver | | -| `LED_DRIVER_ADDR_3` | (Optional) Address for the third LED driver | | -| `LED_DRIVER_ADDR_4` | (Optional) Address for the fourth LED driver | | - -Here is an example using 2 drivers. +Configure the hardware via your `config.h`: ```c // This is a 7-bit address, that gets left-shifted and bit 0 @@ -38,63 +25,342 @@ Here is an example using 2 drivers. // 0b1110111 AD <-> VCC // 0b1110101 AD <-> SCL // 0b1110110 AD <-> SDA -#define LED_DRIVER_ADDR_1 0b1110100 -#define LED_DRIVER_ADDR_2 0b1110110 +#define DRIVER_ADDR_1 0b1110100 +#define DRIVER_ADDR_2 0b1110110 -#define LED_DRIVER_COUNT 2 -#define LED_DRIVER_1_LED_COUNT 25 -#define LED_DRIVER_2_LED_COUNT 24 -#define DRIVER_LED_TOTAL LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL +#define DRIVER_COUNT 2 +#define DRIVER_1_LED_TOTAL 25 +#define DRIVER_2_LED_TOTAL 24 +#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) ``` +!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. + Currently only 2 drivers are supported, but it would be trivial to support all 4 combinations. Define these arrays listing all the LEDs in your `.c`: ```c - const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { - /* Refer to IS31 manual for these locations - * driver - * | LED address - * | | */ - { 0, C1_1 }, - { 0, C1_15 }, - // ... - } +const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { +/* Refer to IS31 manual for these locations + * driver + * | LED address + * | | */ + { 0, C1_1 }, + { 0, C1_15 }, + // ... +} ``` Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731-simple.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` ). -## Keycodes +--- + +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 +led_config_t g_led_config = { { + // Key Matrix to LED Index + { 5, NO_LED, NO_LED, 0 }, + { NO_LED, NO_LED, NO_LED, NO_LED }, + { 4, NO_LED, NO_LED, 1 }, + { 3, NO_LED, NO_LED, 2 } +}, { + // LED Index to Physical Position + { 188, 16 }, { 187, 48 }, { 149, 64 }, { 112, 64 }, { 37, 48 }, { 38, 16 } +}, { + // LED Index to Flag + 1, 4, 4, 4, 4, 1 +} }; +``` + +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 +x = 224 / (NUMBER_OF_COLS - 1) * COL_POSITION +y = 64 / (NUMBER_OF_ROWS - 1) * ROW_POSITION +``` + +Where NUMBER_OF_COLS, NUMBER_OF_ROWS, COL_POSITION, & ROW_POSITION are all based on the physical layout of your keyboard, not the electrical layout. + +As mentioned earlier, the center of the keyboard by default is expected to be `{ 112, 32 }`, but this can be changed if you want to more accurately calculate the LED's physical `{ x, y }` positions. Keyboard designers can implement `#define LED_MATRIX_CENTER { 112, 32 }` in their config.h file with the new center point of the keyboard, or where they want it to be allowing more possibilities for the `{ x, y }` values. Do note that the maximum value for x or y is 255, and the recommended maximum is 224 as this gives animations runoff room before they reset. + +`// 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 :id=flags + +|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_KEYLIGHT` |`0x04`|If the LED is for key backlight | +|`LED_FLAG_INDICATOR` |`0x08`|If the LED is for keyboard state indication | + +## Keycodes :id=keycodes + +All LED matrix keycodes are currently shared with the [Backlight feature](feature_backlight.md). + +|Key |Description | +|---------|-----------------------------| +|`BL_TOGG`|Toggle LED Matrix on or off | +|`BL_STEP`|Cycle through modes | +|`BL_ON` |Turn on LED Matrix | +|`BL_OFF` |Turn off LED Matrix | +|`BL_INC` |Increase the brightness level| +|`BL_DEC` |Decrease the brightness level| -All LED matrix keycodes are currently shared with the [backlight system](feature_backlight.md). +## LED Matrix Effects :id=led-matrix-effects -## LED Matrix Effects +These are the effects that are currently available: -Currently no LED matrix effects have been created. +```c +enum led_matrix_effects { + LED_MATRIX_NONE = 0, + LED_MATRIX_SOLID = 1, // Static single val, no speed support + LED_MATRIX_ALPHAS_MODS, // Static dual val, speed is val for LEDs marked as modifiers + LED_MATRIX_BREATHING, // Cycling brightness animation + LED_MATRIX_BAND, // Band fading brightness scrolling left to right + LED_MATRIX_BAND_PINWHEEL, // 3 blade spinning pinwheel fades brightness + LED_MATRIX_BAND_SPIRAL, // Spinning spiral fades brightness + LED_MATRIX_CYCLE_LEFT_RIGHT, // Full gradient scrolling left to right + LED_MATRIX_CYCLE_UP_DOWN, // Full gradient scrolling top to bottom + LED_MATRIX_CYCLE_OUT_IN, // Full gradient scrolling out to in + LED_MATRIX_DUAL_BEACON, // Full gradient spinning around center of keyboard +#if defined(LED_MATRIX_KEYPRESSES) || defined(LED_MATRIX_KEYRELEASES) + LED_MATRIX_SOLID_REACTIVE_SIMPLE, // Pulses keys hit then fades out + LED_MATRIX_SOLID_REACTIVE_WIDE // Value pulses near a single key hit then fades out + LED_MATRIX_SOLID_REACTIVE_MULTIWIDE // Value pulses near multiple key hits then fades out + LED_MATRIX_SOLID_REACTIVE_CROSS // Value pulses the same column and row of a single key hit then fades out + LED_MATRIX_SOLID_REACTIVE_MULTICROSS // Value pulses the same column and row of multiple key hits then fades out + LED_MATRIX_SOLID_REACTIVE_NEXUS // Value pulses away on the same column and row of a single key hit then fades out + LED_MATRIX_SOLID_REACTIVE_MULTINEXUS // Value pulses away on the same column and row of multiple key hits then fades out + LED_MATRIX_SOLID_SPLASH, // Value pulses away from a single key hit then fades out + LED_MATRIX_SOLID_MULTISPLASH, // Value pulses away from multiple key hits then fades out +#endif + LED_MATRIX_WAVE_LEFT_RIGHT // Sine wave scrolling from left to right + LED_MATRIX_WAVE_UP_DOWN // Sine wave scrolling from up to down + LED_MATRIX_EFFECT_MAX +}; +``` + +You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `config.h`: + + +|Define |Description | +|-------------------------------------------------------|-----------------------------------------------| +|`#define DISABLE_LED_MATRIX_SOLID` |Disables `LED_MATRIX_SOLID` | +|`#define DISABLE_LED_MATRIX_ALPHAS_MODS` |Disables `LED_MATRIX_ALPHAS_MODS` | +|`#define DISABLE_LED_MATRIX_BREATHING` |Disables `LED_MATRIX_BREATHING` | +|`#define DISABLE_LED_MATRIX_BAND` |Disables `LED_MATRIX_BAND` | +|`#define DISABLE_LED_MATRIX_BAND_PINWHEEL` |Disables `LED_MATRIX_BAND_PINWHEEL` | +|`#define DISABLE_LED_MATRIX_BAND_SPIRAL` |Disables `LED_MATRIX_BAND_SPIRAL` | +|`#define DISABLE_LED_MATRIX_CYCLE_LEFT_RIGHT` |Disables `LED_MATRIX_CYCLE_LEFT_RIGHT` | +|`#define DISABLE_LED_MATRIX_CYCLE_UP_DOWN` |Disables `LED_MATRIX_CYCLE_UP_DOWN` | +|`#define DISABLE_LED_MATRIX_CYCLE_OUT_IN` |Disables `LED_MATRIX_CYCLE_OUT_IN` | +|`#define DISABLE_LED_MATRIX_DUAL_BEACON` |Disables `LED_MATRIX_DUAL_BEACON` | +|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_SIMPLE` |Disables `LED_MATRIX_SOLID_REACTIVE_SIMPLE` | +|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_WIDE` |Disables `LED_MATRIX_SOLID_REACTIVE_WIDE` | +|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_MULTIWIDE` |Disables `LED_MATRIX_SOLID_REACTIVE_MULTIWIDE` | +|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_CROSS` |Disables `LED_MATRIX_SOLID_REACTIVE_CROSS` | +|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_MULTICROSS` |Disables `LED_MATRIX_SOLID_REACTIVE_MULTICROSS`| +|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_NEXUS` |Disables `LED_MATRIX_SOLID_REACTIVE_NEXUS` | +|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_MULTINEXUS` |Disables `LED_MATRIX_SOLID_REACTIVE_MULTINEXUS`| +|`#define DISABLE_LED_MATRIX_SOLID_SPLASH` |Disables `LED_MATRIX_SOLID_SPLASH` | +|`#define DISABLE_LED_MATRIX_SOLID_MULTISPLASH` |Disables `LED_MATRIX_SOLID_MULTISPLASH` | +|`#define DISABLE_LED_MATRIX_WAVE_LEFT_RIGHT` |Disables `LED_MATRIX_WAVE_LEFT_RIGHT` | +|`#define DISABLE_LED_MATRIX_WAVE_UP_DOWN` |Disables `LED_MATRIX_WAVE_UP_DOWN` | + +## Custom LED Matrix Effects :id=custom-led-matrix-effects -## Custom Layer Effects +By setting `LED_MATRIX_CUSTOM_USER` (and/or `LED_MATRIX_CUSTOM_KB`) in `rules.mk`, new effects can be defined directly from userspace, without having to edit any QMK core files. -Custom layer effects can be done by defining this in your `.c`: +To declare new effects, create a new `led_matrix_user/kb.inc` that looks something like this: + +`led_matrix_user.inc` should go in the root of the keymap directory. +`led_matrix_kb.inc` should go in the root of the keyboard directory. + +To use custom effects in your code, simply prepend `LED_MATRIX_CUSTOM_` to the effect name specified in `LED_MATRIX_EFFECT()`. For example, an effect declared as `LED_MATRIX_EFFECT(my_cool_effect)` would be referenced with: + +```c +led_matrix_mode(led_MATRIX_CUSTOM_my_cool_effect); +``` +```c +// !!! DO NOT ADD #pragma once !!! // + +// Step 1. +// Declare custom effects using the LED_MATRIX_EFFECT macro +// (note the lack of semicolon after the macro!) +LED_MATRIX_EFFECT(my_cool_effect) +LED_MATRIX_EFFECT(my_cool_effect2) + +// Step 2. +// Define effects inside the `LED_MATRIX_CUSTOM_EFFECT_IMPLS` ifdef block +#ifdef LED_MATRIX_CUSTOM_EFFECT_IMPLS + +// e.g: A simple effect, self-contained within a single method +static bool my_cool_effect(effect_params_t* params) { + LED_MATRIX_USE_LIMITS(led_min, led_max); + for (uint8_t i = led_min; i < led_max; i++) { + led_matrix_set_value(i, 0xFF); + } + return led_max < DRIVER_LED_TOTAL; +} + +// e.g: A more complex effect, relying on external methods and state, with +// dedicated init and run methods +static uint8_t some_global_state; +static void my_cool_effect2_complex_init(effect_params_t* params) { + some_global_state = 1; +} +static bool my_cool_effect2_complex_run(effect_params_t* params) { + LED_MATRIX_USE_LIMITS(led_min, led_max); + for (uint8_t i = led_min; i < led_max; i++) { + led_matrix_set_value(i, some_global_state++); + } + + return led_max < DRIVER_LED_TOTAL; +} +static bool my_cool_effect2(effect_params_t* params) { + if (params->init) my_cool_effect2_complex_init(params); + return my_cool_effect2_complex_run(params); +} + +#endif // LED_MATRIX_CUSTOM_EFFECT_IMPLS +``` + +For inspiration and examples, check out the built-in effects under `quantum/led_matrix_animations/` + + + + + + + + + +## Additional `config.h` Options :id=additional-configh-options + +```c +#define LED_MATRIX_KEYPRESSES // reacts to keypresses +#define LED_MATRIX_KEYRELEASES // reacts to keyreleases (instead of keypresses) +#define LED_DISABLE_TIMEOUT 0 // number of milliseconds to wait until led automatically turns off +#define LED_DISABLE_AFTER_TIMEOUT 0 // OBSOLETE: number of ticks to wait until disabling effects +#define LED_DISABLE_WHEN_USB_SUSPENDED false // turn off effects when suspended +#define LED_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 LED_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 LED_MATRIX_MAXIMUM_BRIGHTNESS 255 // limits maximum brightness of LEDs +#define LED_MATRIX_STARTUP_MODE LED_MATRIX_SOLID // Sets the default mode, if none has been set +#define LED_MATRIX_STARTUP_VAL LED_MATRIX_MAXIMUM_BRIGHTNESS // Sets the default brightness value, if none has been set +#define LED_MATRIX_STARTUP_SPD 127 // Sets the default animation speed, if none has been set +#define LED_MATRIX_SPLIT { X, Y } // (Optional) For split keyboards, the number of LEDs connected on each half. X = left, Y = Right. + // If LED_MATRIX_KEYPRESSES or LED_MATRIX_KEYRELEASES is enabled, you also will want to enable SPLIT_TRANSPORT_MIRROR +``` + +## EEPROM storage :id=eeprom-storage + +The EEPROM for it is currently shared with the RGB Matrix system (it's generally assumed only one feature would be used at a time), but could be configured to use its own 32bit address with: + +```c +#define EECONFIG_LED_MATRIX (uint32_t *)28 +``` + +Where `28` is an unused index from `eeconfig.h`. + +### Direct Operation :id=direct-operation +|Function |Description | +|--------------------------------------------|-------------| +|`led_matrix_set_value_all(v)` |Set all of the LEDs to the given value, where `v` is between 0 and 255 (not written to EEPROM) | +|`led_matrix_set_value(index, v)` |Set a single LED to the given value, where `v` is between 0 and 255, and `index` is between 0 and `DRIVER_LED_TOTAL` (not written to EEPROM) | + +### Disable/Enable Effects :id=disable-enable-effects +|Function |Description | +|--------------------------------------------|-------------| +|`led_matrix_toggle()` |Toggle effect range LEDs between on and off | +|`led_matrix_toggle_noeeprom()` |Toggle effect range LEDs between on and off (not written to EEPROM) | +|`led_matrix_enable()` |Turn effect range LEDs on, based on their previous state | +|`led_matrix_enable_noeeprom()` |Turn effect range LEDs on, based on their previous state (not written to EEPROM) | +|`led_matrix_disable()` |Turn effect range LEDs off, based on their previous state | +|`led_matrix_disable_noeeprom()` |Turn effect range LEDs off, based on their previous state (not written to EEPROM) | + +### Change Effect Mode :id=change-effect-mode +|Function |Description | +|--------------------------------------------|-------------| +|`led_matrix_mode(mode)` |Set the mode, if LED animations are enabled | +|`led_matrix_mode_noeeprom(mode)` |Set the mode, if LED animations are enabled (not written to EEPROM) | +|`led_matrix_step()` |Change the mode to the next LED animation in the list of enabled LED animations | +|`led_matrix_step_noeeprom()` |Change the mode to the next LED animation in the list of enabled LED animations (not written to EEPROM) | +|`led_matrix_step_reverse()` |Change the mode to the previous LED animation in the list of enabled LED animations | +|`led_matrix_step_reverse_noeeprom()` |Change the mode to the previous LED animation in the list of enabled LED animations (not written to EEPROM) | +|`led_matrix_increase_speed()` |Increase the speed of the animations | +|`led_matrix_increase_speed_noeeprom()` |Increase the speed of the animations (not written to EEPROM) | +|`led_matrix_decrease_speed()` |Decrease the speed of the animations | +|`led_matrix_decrease_speed_noeeprom()` |Decrease the speed of the animations (not written to EEPROM) | +|`led_matrix_set_speed(speed)` |Set the speed of the animations to the given value where `speed` is between 0 and 255 | +|`led_matrix_set_speed_noeeprom(speed)` |Set the speed of the animations to the given value where `speed` is between 0 and 255 (not written to EEPROM) | + +### Change Value :id=change-value +|Function |Description | +|--------------------------------------------|-------------| +|`led_matrix_increase_val()` |Increase the value for effect range LEDs. This wraps around at maximum value | +|`led_matrix_increase_val_noeeprom()` |Increase the value for effect range LEDs. This wraps around at maximum value (not written to EEPROM) | +|`led_matrix_decrease_val()` |Decrease the value for effect range LEDs. This wraps around at minimum value | +|`led_matrix_decrease_val_noeeprom()` |Decrease the value for effect range LEDs. This wraps around at minimum value (not written to EEPROM) | + +### Query Current Status :id=query-current-status +|Function |Description | +|---------------------------------|---------------------------| +|`led_matrix_is_enabled()` |Gets current on/off status | +|`led_matrix_get_mode()` |Gets current mode | +|`led_matrix_get_val()` |Gets current val | +|`led_matrix_get_speed()` |Gets current speed | +|`led_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 `led_matrix_indicators_kb` or `led_matrix_indicators_user` function for that: ```c void led_matrix_indicators_kb(void) { - led_matrix_set_value(index, value); + led_matrix_set_color(index, value); } ``` -A similar function works in the keymap as `led_matrix_indicators_user`. +In addition, there are the advanced indicator functions. These are aimed at those with heavily customized displays, where rendering every LED per cycle is expensive. This includes a special macro to help make this easier to use: `LED_MATRIX_INDICATOR_SET_VALUE(i, v)`. + +```c +void led_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { + LED_MATRIX_INDICATOR_SET_VALUE(index, value); +} +``` -## Suspended State +## Suspended State :id=suspended-state +To use the suspend feature, make sure that `#define LED_DISABLE_WHEN_USB_SUSPENDED true` is added to the `config.h` file. -To use the suspend feature, add this to your `.c`: +Additionally add this to your `.c`: ```c void suspend_power_down_kb(void) { led_matrix_set_suspend_state(true); + suspend_power_down_user(); } void suspend_wakeup_init_kb(void) { led_matrix_set_suspend_state(false); + suspend_wakeup_init_user(); +} +``` +or add this to your `keymap.c`: +```c +void suspend_power_down_user(void) { + led_matrix_set_suspend_state(true); +} + +void suspend_wakeup_init_user(void) { + led_matrix_set_suspend_state(false); } -``` \ No newline at end of file +``` diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 63ff7d6ad6..ffbb8c0b60 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -399,7 +399,7 @@ static bool my_cool_effect2(effect_params_t* params) { #endif // RGB_MATRIX_CUSTOM_EFFECT_IMPLS ``` -For inspiration and examples, check out the built-in effects under `quantum/rgb_matrix_animation/` +For inspiration and examples, check out the built-in effects under `quantum/rgb_matrix_animations/` ## Colors :id=colors @@ -453,7 +453,7 @@ These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blo ## 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: +The EEPROM for it is currently shared with the LED Matrix system (it's generally assumed only one feature would be used at a time), but could be configured to use its own 32bit address with: ```c #define EECONFIG_RGB_MATRIX (uint32_t *)28 -- cgit v1.2.3 From 04ab5de73cbf342adb1ca551cca20fac9535abad Mon Sep 17 00:00:00 2001 From: Ryan Date: Fri, 14 May 2021 03:25:40 +1000 Subject: Deprecate `send_unicode_hex_string()` (#12602) --- docs/feature_unicode.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_unicode.md b/docs/feature_unicode.md index 1208ac0064..6c3e2a1a2f 100644 --- a/docs/feature_unicode.md +++ b/docs/feature_unicode.md @@ -230,7 +230,7 @@ send_unicode_string("(ノಠ痊ಠ)ノ彡┻━┻"); Example uses include sending Unicode strings when a key is pressed, as described in [Macros](feature_macros.md). -### `send_unicode_hex_string()` +### `send_unicode_hex_string()` (Deprecated) 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: -- cgit v1.2.3 From 6c7450dad7c3651e0aae7ebaeb6c3cf15bde5112 Mon Sep 17 00:00:00 2001 From: Matthes W <48785515+matthesinator@users.noreply.github.com> Date: Mon, 17 May 2021 02:59:02 +0200 Subject: Add function to allow repeated blinking of one layer (#12237) * Implement function rgblight_blink_layer_repeat to allow repeated blinking of one layer at a time * Update doc * Rework rgblight blinking according to requested change * optimize storage --- docs/feature_rgblight.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs') diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index 8e8d6b81c3..292176548f 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -310,6 +310,18 @@ void post_process_record_user(uint16_t keycode, keyrecord_t *record) { } ``` +You can also use `rgblight_blink_layer_repeat` to specify the amount of times the layer is supposed to blink. Using the layers from above, +```c +void post_process_record_user(uint16_t keycode, keyrecord_t *record) { + switch (keycode) { + case DEBUG: + rgblight_blink_layer_repeat(debug_enable ? 0 : 1, 200, 3); + break; + } +} +``` +would turn the layer 0 (or 1) on and off again three times when `DEBUG` is pressed. + ### 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`. -- cgit v1.2.3 From 8e96c5a060896c4aa5ed181d9c86c4e66bb78cfc Mon Sep 17 00:00:00 2001 From: Donald Kjer Date: Fri, 21 May 2021 21:42:39 -0700 Subject: Add support for up to 4 IS31FL3733 drivers (#12342) Co-authored-by: James Young <18669334+noroadsleft@users.noreply.github.com> --- docs/feature_led_matrix.md | 31 ++++++++++----- docs/feature_rgb_matrix.md | 96 +++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 108 insertions(+), 19 deletions(-) (limited to 'docs') diff --git a/docs/feature_led_matrix.md b/docs/feature_led_matrix.md index 7834b940d5..e56caabfe7 100644 --- a/docs/feature_led_matrix.md +++ b/docs/feature_led_matrix.md @@ -15,7 +15,20 @@ LED_MATRIX_ENABLE = yes LED_MATRIX_DRIVER = IS31FL3731 ``` -Configure the hardware via your `config.h`: +You can use between 1 and 4 IS31FL3731 IC's. Do not specify `LED_DRIVER_ADDR_` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`: + +| Variable | Description | Default | +|----------|-------------|---------| +| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | +| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | +| `LED_DRIVER_COUNT` | (Required) How many LED driver IC's are present | | +| `DRIVER_LED_TOTAL` | (Required) How many LED lights are present across all drivers | | +| `LED_DRIVER_ADDR_1` | (Required) Address for the first LED driver | | +| `LED_DRIVER_ADDR_2` | (Optional) Address for the second LED driver | | +| `LED_DRIVER_ADDR_3` | (Optional) Address for the third LED driver | | +| `LED_DRIVER_ADDR_4` | (Optional) Address for the fourth LED driver | | + +Here is an example using 2 drivers. ```c // This is a 7-bit address, that gets left-shifted and bit 0 @@ -25,18 +38,16 @@ Configure the hardware via your `config.h`: // 0b1110111 AD <-> VCC // 0b1110101 AD <-> SCL // 0b1110110 AD <-> SDA -#define DRIVER_ADDR_1 0b1110100 -#define DRIVER_ADDR_2 0b1110110 +#define LED_DRIVER_ADDR_1 0b1110100 +#define LED_DRIVER_ADDR_2 0b1110110 -#define DRIVER_COUNT 2 -#define DRIVER_1_LED_TOTAL 25 -#define DRIVER_2_LED_TOTAL 24 -#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) +#define LED_DRIVER_COUNT 2 +#define LED_DRIVER_1_LED_TOTAL 25 +#define LED_DRIVER_2_LED_TOTAL 24 +#define DRIVER_LED_TOTAL (LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL) ``` -!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. - -Currently only 2 drivers are supported, but it would be trivial to support all 4 combinations. +!> Note the parentheses, this is so when `LED_DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL)` will give very different results than `rand() % LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL`. Define these arrays listing all the LEDs in your `.c`: diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index ffbb8c0b60..a29d5c624b 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -15,7 +15,20 @@ RGB_MATRIX_ENABLE = yes RGB_MATRIX_DRIVER = IS31FL3731 ``` -Configure the hardware via your `config.h`: +You can use between 1 and 4 IS31FL3731 IC's. Do not specify `DRIVER_ADDR_` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`: + +| Variable | Description | Default | +|----------|-------------|---------| +| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | +| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | +| `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | +| `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | | +| `DRIVER_ADDR_1` | (Required) Address for the first RGB driver | | +| `DRIVER_ADDR_2` | (Optional) Address for the second RGB driver | | +| `DRIVER_ADDR_3` | (Optional) Address for the third RGB driver | | +| `DRIVER_ADDR_4` | (Optional) Address for the fourth RGB driver | | + +Here is an example using 2 drivers. ```c // This is a 7-bit address, that gets left-shifted and bit 0 @@ -36,8 +49,6 @@ Configure the hardware via your `config.h`: !> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. -Currently only 2 drivers are supported, but it would be trivial to support all 4 combinations. - Define these arrays listing all the LEDs in your `.c`: ```c @@ -53,12 +64,10 @@ 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](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0` or `1` right now). +Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3`). --- -### IS31FL3733/IS31FL3737 :id=is31fl3733is31fl3737 - -!> For the IS31FL3737, replace all instances of `IS31FL3733` below with `IS31FL3737`. +### IS31FL3733 :id=is31fl3733 There is basic support for addressable RGB matrix lighting with the I2C IS31FL3733 RGB controller. To enable it, add this to your `rules.mk`: @@ -67,7 +76,24 @@ RGB_MATRIX_ENABLE = yes RGB_MATRIX_DRIVER = IS31FL3733 ``` -Configure the hardware via your `config.h`: +You can use between 1 and 4 IS31FL3733 IC's. Do not specify `DRIVER_ADDR_` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`: + +| Variable | Description | Default | +|----------|-------------|---------| +| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | +| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | +| `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | +| `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | | +| `DRIVER_ADDR_1` | (Required) Address for the first RGB driver | | +| `DRIVER_ADDR_2` | (Optional) Address for the second RGB driver | | +| `DRIVER_ADDR_3` | (Optional) Address for the third RGB driver | | +| `DRIVER_ADDR_4` | (Optional) Address for the fourth RGB driver | | +| `DRIVER_SYNC_1` | (Optional) Sync configuration for the first RGB driver | 0 | +| `DRIVER_SYNC_2` | (Optional) Sync configuration for the second RGB driver | 0 | +| `DRIVER_SYNC_3` | (Optional) Sync configuration for the third RGB driver | 0 | +| `DRIVER_SYNC_4` | (Optional) Sync configuration for the fourth RGB driver | 0 | + +Here is an example using 2 drivers. ```c // This is a 7-bit address, that gets left-shifted and bit 0 @@ -81,6 +107,58 @@ Configure the hardware via your `config.h`: // ADDR2 represents A3:A2 of the 7-bit address. // The result is: 0b101(ADDR2)(ADDR1) #define DRIVER_ADDR_1 0b1010000 +#define DRIVER_ADDR_2 0b1010011 + +#define DRIVER_COUNT 2 +#define DRIVER_1_LED_TOTAL 58 +#define DRIVER_2_LED_TOTAL 10 +#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) +``` + +!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. + +Currently only 4 drivers are supported, but it would be trivial to support all 8 combinations. + +Define these arrays listing all the LEDs in your `.c`: + +```c +const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { +/* Refer to IS31 manual for these locations + * driver + * | R location + * | | G location + * | | | B location + * | | | | */ + {0, B_1, A_1, C_1}, + .... +} +``` + +Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3733.pdf) and the header file `drivers/issi/is31fl3733.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` for now). + +--- +### IS31FL3737 :id=is31fl3737 + +There is basic support for addressable RGB matrix lighting with the I2C IS31FL3737 RGB controller. To enable it, add this to your `rules.mk`: + +```makefile +RGB_MATRIX_ENABLE = yes +RGB_MATRIX_DRIVER = IS31FL3737 +``` + +Configure the hardware via your `config.h`: + +```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: +// 0000 <-> GND +// 0101 <-> SCL +// 1010 <-> SDA +// 1111 <-> VCC +// ADDR represents A3:A0 of the 7-bit address. +// The result is: 0b101(ADDR) +#define DRIVER_ADDR_1 0b1010000 #define DRIVER_ADDR_2 0b1010000 // this is here for compliancy reasons. #define DRIVER_COUNT 2 @@ -105,7 +183,7 @@ const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { } ``` -Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3733.pdf) and the header file `drivers/issi/is31fl3733.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0` right now). +Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3737.pdf) and the header file `drivers/issi/is31fl3737.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0` right now). --- -- cgit v1.2.3 From a0fed0ea176d1c986e40fc4981b900509c90d66e Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Fri, 21 May 2021 23:17:32 -0700 Subject: Convert Encoder callbacks to be boolean functions (#12805) Co-authored-by: James Young <18669334+noroadsleft@users.noreply.github.com> --- docs/feature_encoders.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/feature_encoders.md b/docs/feature_encoders.md index 4338c85e84..a56f093a39 100644 --- a/docs/feature_encoders.md +++ b/docs/feature_encoders.md @@ -53,15 +53,15 @@ 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`: ```c -void encoder_update_kb(uint8_t index, bool clockwise) { - encoder_update_user(index, clockwise); +bool encoder_update_kb(uint8_t index, bool clockwise) { + return encoder_update_user(index, clockwise); } ``` or `keymap.c`: ```c -void encoder_update_user(uint8_t index, bool clockwise) { +bool encoder_update_user(uint8_t index, bool clockwise) { if (index == 0) { /* First encoder */ if (clockwise) { tap_code(KC_PGDN); @@ -75,9 +75,12 @@ void encoder_update_user(uint8_t index, bool clockwise) { tap_code(KC_UP); } } + return true; } ``` +!> If you return `true`, this will allow the keyboard level code to run, as well. Returning `false` will override the keyboard level code. Depending on how the keyboard level function is set up. + ## 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. -- cgit v1.2.3 From 8f4767d9663874c318cd2e66f745503d63a50f05 Mon Sep 17 00:00:00 2001 From: Ryan Date: Sat, 22 May 2021 16:56:17 +1000 Subject: [Keyboard] Fix Terrazzo build failure (#12977) --- docs/feature_led_matrix.md | 1 - docs/feature_rgb_matrix.md | 1 - 2 files changed, 2 deletions(-) (limited to 'docs') diff --git a/docs/feature_led_matrix.md b/docs/feature_led_matrix.md index e56caabfe7..e3b389762d 100644 --- a/docs/feature_led_matrix.md +++ b/docs/feature_led_matrix.md @@ -162,7 +162,6 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con |Define |Description | |-------------------------------------------------------|-----------------------------------------------| -|`#define DISABLE_LED_MATRIX_SOLID` |Disables `LED_MATRIX_SOLID` | |`#define DISABLE_LED_MATRIX_ALPHAS_MODS` |Disables `LED_MATRIX_ALPHAS_MODS` | |`#define DISABLE_LED_MATRIX_BREATHING` |Disables `LED_MATRIX_BREATHING` | |`#define DISABLE_LED_MATRIX_BAND` |Disables `LED_MATRIX_BAND` | diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index a29d5c624b..3871e6bfda 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -362,7 +362,6 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con |Define |Description | |-------------------------------------------------------|-----------------------------------------------| -|`#define DISABLE_RGB_MATRIX_SOLID_COLOR` |Disables `RGB_MATRIX_SOLID_COLOR` | |`#define DISABLE_RGB_MATRIX_ALPHAS_MODS` |Disables `RGB_MATRIX_ALPHAS_MODS` | |`#define DISABLE_RGB_MATRIX_GRADIENT_UP_DOWN` |Disables `RGB_MATRIX_GRADIENT_UP_DOWN` | |`#define DISABLE_RGB_MATRIX_GRADIENT_LEFT_RIGHT` |Disables `MATRIX_GRADIENT_LEFT_RIGHT` | -- cgit v1.2.3 From d9610120de0452bc6a548bd36b1d4fdfba56d071 Mon Sep 17 00:00:00 2001 From: Stefan Kerkmann Date: Thu, 27 May 2021 05:37:54 +0200 Subject: Add Full-duplex serial driver for ARM boards (#9842) --- docs/serial_driver.md | 154 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 147 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/serial_driver.md b/docs/serial_driver.md index c98f4c1176..359fc59551 100644 --- a/docs/serial_driver.md +++ b/docs/serial_driver.md @@ -3,16 +3,18 @@ This driver powers the [Split Keyboard](feature_split_keyboard.md) feature. ?> Serial in this context should be read as **sending information one bit at a time**, rather than implementing UART/USART/RS485/RS232 standards. -All drivers in this category have the following characteristics: -* Provides data and signaling over a single conductor -* Limited to single master, single slave +Drivers in this category have the following characteristics: +* bit bang and USART Half-duplex provide data and signaling over a single conductor +* USART Full-duplex provide data and signaling over two conductors +* They are all limited to single master and single slave communication scheme ## Supported Driver Types | | AVR | ARM | -|-------------------|--------------------|--------------------| +| ----------------- | ------------------ | ------------------ | | bit bang | :heavy_check_mark: | :heavy_check_mark: | | USART Half-duplex | | :heavy_check_mark: | +| USART Full-duplex | | :heavy_check_mark: | ## Driver configuration @@ -42,7 +44,7 @@ Configure the driver via your config.h: Along with the generic options above, you must also turn on the `PAL_USE_CALLBACKS` feature in your halconf.h. ### USART Half-duplex -Targeting STM32 boards where communication is offloaded to a USART hardware device. The advantage is that this provides fast and accurate timings. `SOFT_SERIAL_PIN` for this driver is the configured USART TX pin. **The TX pin must have appropriate pull-up resistors**. To configure it, add this to your rules.mk: +Targeting STM32 boards where communication is offloaded to a USART hardware device. The advantage over bitbang is that this provides fast and accurate timings. `SERIAL_PIN_TX` for this driver is the configured USART TX pin. As this Pin is configured in open-drain mode an **external pull-up resistor is needed to keep the line high** (resistor values of 1.5k to 8.2k are known to work). To configure it, add this to your rules.mk: ```make SERIAL_DRIVER = usart @@ -50,7 +52,8 @@ SERIAL_DRIVER = usart Configure the hardware via your config.h: ```c -#define SOFT_SERIAL_PIN B6 // USART TX pin +#define SOFT_SERIAL_PIN B6 // USART TX pin +//#define USART1_REMAP // Remap USART TX and RX pins on STM32F103 MCUs, see table below. #define SELECT_SOFT_SERIAL_SPEED 1 // or 0, 2, 3, 4, 5 // 0: about 460800 baud // 1: about 230400 baud (default) @@ -58,7 +61,7 @@ Configure the hardware via your config.h: // 3: about 57600 baud // 4: about 38400 baud // 5: about 19200 baud -#define SERIAL_USART_DRIVER SD1 // USART driver of TX pin. default: SD1 +#define SERIAL_USART_DRIVER SD1 // USART driver of TX pin. default: SD1 #define SERIAL_USART_TX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7 #define SERIAL_USART_TIMEOUT 100 // USART driver timeout. default 100 ``` @@ -68,3 +71,140 @@ You must also enable the ChibiOS `SERIAL` feature: * In your board's mcuconf.h: `#define STM32_SERIAL_USE_USARTn TRUE` (where 'n' matches the peripheral number of your selected USART on the MCU) Do note that the configuration required is for the `SERIAL` peripheral, not the `UART` peripheral. + +### USART Full-duplex +Targeting STM32 boards where communication is offloaded to a USART hardware device. The advantage over bitbang is that this provides fast and accurate timings. USART Full-Duplex requires two conductors **without** pull-up resistors instead of one conductor with a pull-up resistor unlike the Half-duplex driver, but it is more efficent as it uses DMA transfers, which can result in even faster transmission speeds. + +#### Pin configuration + +`SERIAL_USART_TX_PIN` is the USART `TX` pin, `SERIAL_USART_RX_PIN` is the USART `RX` pin. No external pull-up resistors are needed as the `TX` pin operates in push-pull mode. To use this driver the usart peripherals `TX` and `RX` pins must be configured with the correct Alternate-functions. If you are using a Proton-C everything is already setup, same is true for STM32F103 MCUs. For MCUs which are using a modern flexible GPIO configuration you have to specify these by setting `SERIAL_USART_TX_PAL_MODE` and `SERIAL_USART_RX_PAL_MODE`. Refeer to the corresponding datasheets of your MCU or find those settings in the table below. + +#### Connecting the halves and Pin Swap +Please note that `TX` of the master half has to be connected with the `RX` pin of the slave half and `RX` of the master half has to be connected with the `TX` pin of the slave half! Usually this pin swap has to be done outside of the MCU e.g. with cables or on the pcb. Some MCUs like the STM32F303 used on the Proton-C allow this pin swap directly inside the MCU, this feature can be enabled using `#define SERIAL_USART_PIN_SWAP` in your config.h. + +#### Setup +To use the driver, add this to your rules.mk: + +```make +SERIAL_DRIVER = usart_duplex +``` + +Next configure the hardware via your config.h: + +```c +#define SERIAL_USART_TX_PIN B6 // USART TX pin +#define SERIAL_USART_RX_PIN B7 // USART RX pin +//#define USART1_REMAP // Remap USART TX and RX pins on STM32F103 MCUs, see table below. +//#define SERIAL_USART_PIN_SWAP // Swap TX and RX pins if keyboard is master halve. + // Check if this feature is necessary with your keyboard design and available on the mcu. +#define SELECT_SOFT_SERIAL_SPEED 1 // or 0, 2, 3, 4, 5 + // 0: 460800 baud + // 1: 230400 baud (default) + // 2: 115200 baud + // 3: 57600 baud + // 4: 38400 baud + // 5: 19200 baud +#define SERIAL_USART_DRIVER UARTD1 // USART driver of TX and RX pin. default: UARTD1 +#define SERIAL_USART_TX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7 +#define SERIAL_USART_RX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7 +#define SERIAL_USART_TIMEOUT 100 // USART driver timeout. default 100 +``` + +You must also enable the ChibiOS `UART` with blocking api feature: +* In your board's halconf.h: `#define HAL_USE_UART TRUE` and `#define UART_USE_WAIT TRUE` +* In your board's mcuconf.h: `#define STM32_UART_USE_USARTn TRUE` (where 'n' matches the peripheral number of your selected USART on the MCU) + +Do note that the configuration required is for the `UART` peripheral, not the `SERIAL` peripheral. + +#### Pins for USART Peripherals with Alternate Functions for selected STM32 MCUs + +##### STM32F303 / Proton-C [Datasheet](https://www.st.com/resource/en/datasheet/stm32f303cc.pdf) + +Pin Swap available: :heavy_check_mark: + +| Pin | Function | Mode | +| ---------- | -------- | ---- | +| **USART1** | | | +| PA9 | TX | AF7 | +| PA10 | RX | AF7 | +| PB6 | TX | AF7 | +| PB7 | RX | AF7 | +| PC4 | TX | AF7 | +| PC5 | RX | AF7 | +| PE0 | TX | AF7 | +| PE1 | RX | AF7 | +| **USART2** | | | +| PA2 | TX | AF7 | +| PA3 | RX | AF7 | +| PA14 | TX | AF7 | +| PA15 | RX | AF7 | +| PB3 | TX | AF7 | +| PB4 | RX | AF7 | +| PD5 | TX | AF7 | +| PD6 | RX | AF7 | +| **USART3** | | | +| PB10 | TX | AF7 | +| PB11 | RX | AF7 | +| PC10 | TX | AF7 | +| PC11 | RX | AF7 | +| PD8 | TX | AF7 | +| PD9 | RX | AF7 | + +##### STM32F072 [Datasheet](https://www.st.com/resource/en/datasheet/stm32f072c8.pdf) + +Pin Swap available: :heavy_check_mark: + +| Pin | Function | Mode | +| ------ | -------- | ---- | +| USART1 | | | +| PA9 | TX | AF1 | +| PA10 | RX | AF1 | +| PB6 | TX | AF0 | +| PB7 | RX | AF0 | +| USART2 | | | +| PA2 | TX | AF1 | +| PA3 | RX | AF1 | +| PA14 | TX | AF1 | +| PA15 | RX | AF1 | +| USART3 | | | +| PB10 | TX | AF4 | +| PB11 | RX | AF4 | +| PC4 | TX | AF1 | +| PC5 | RX | AF1 | +| PC10 | TX | AF1 | +| PC11 | RX | AF1 | +| PD8 | TX | AF0 | +| PD9 | RX | AF0 | +| USART4 | | | +| PA0 | TX | AF4 | +| PA1 | RX | AF4 | + +##### STM32F103 Medium Density (C8-CB) [Datasheet](https://www.st.com/resource/en/datasheet/stm32f103c8.pdf) + +Pin Swap available: N/A + +TX Pin is always Alternate Function Push-Pull, RX Pin is always regular input pin for any USART peripheral. **For STM32F103 no additional Alternate Function configuration is necessary. QMK is already configured.** + +Pin remapping: + +The pins of USART Peripherals use default Pins that can be remapped to use other pins using the AFIO registers. Default pins are marked **bold**. Add the appropriate defines to your config.h file. + +| Pin | Function | Mode | USART_REMAP | +| ---------- | -------- | ---- | ------------------- | +| **USART1** | | | | +| **PA9** | TX | AFPP | | +| **PA10** | RX | IN | | +| PB6 | TX | AFPP | USART1_REMAP | +| PB7 | RX | IN | USART1_REMAP | +| **USART2** | | | | +| **PA2** | TX | AFPP | | +| **PA3** | RX | IN | | +| PD5 | TX | AFPP | USART2_REMAP | +| PD6 | RX | IN | USART2_REMAP | +| **USART3** | | | | +| **PB10** | TX | AFPP | | +| **PB11** | RX | IN | | +| PC10 | TX | AFPP | USART3_PARTIALREMAP | +| PC11 | RX | IN | USART3_PARTIALREMAP | +| PD8 | TX | AFPP | USART3_FULLREMAP | +| PD9 | RX | IN | USART3_FULLREMAP | -- cgit v1.2.3 From ebaba80287b7535a264cea9f725ceef1f2305e72 Mon Sep 17 00:00:00 2001 From: peepeetee <43021794+peepeetee@users.noreply.github.com> Date: Wed, 26 May 2021 23:22:56 -0500 Subject: Document LED_MATRIX_FRAMEBUFFER_EFFECTS (#12987) --- docs/feature_led_matrix.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/feature_led_matrix.md b/docs/feature_led_matrix.md index e3b389762d..9c3e2c7f3d 100644 --- a/docs/feature_led_matrix.md +++ b/docs/feature_led_matrix.md @@ -257,6 +257,7 @@ For inspiration and examples, check out the built-in effects under `quantum/led_ ```c #define LED_MATRIX_KEYPRESSES // reacts to keypresses #define LED_MATRIX_KEYRELEASES // reacts to keyreleases (instead of keypresses) +#define LED_MATRIX_FRAMEBUFFER_EFFECTS // enable framebuffer effects #define LED_DISABLE_TIMEOUT 0 // number of milliseconds to wait until led automatically turns off #define LED_DISABLE_AFTER_TIMEOUT 0 // OBSOLETE: number of ticks to wait until disabling effects #define LED_DISABLE_WHEN_USB_SUSPENDED false // turn off effects when suspended -- cgit v1.2.3 From 06aea834c420d5c11bbcf64d37596cb0cee9af98 Mon Sep 17 00:00:00 2001 From: Ryan Date: Thu, 27 May 2021 15:21:15 +1000 Subject: Backlight: add defines for default level and breathing state (#12560) --- docs/feature_backlight.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md index 74511dd43f..d47ecc6824 100644 --- a/docs/feature_backlight.md +++ b/docs/feature_backlight.md @@ -62,15 +62,17 @@ Valid driver values are `pwm`, `software`, `custom` or `no`. See below for help To configure the backlighting, `#define` these in your `config.h`: -| Define | Default | Description | -|------------------------|---------------|-------------------------------------------------------------------------------------------------------------------| -| `BACKLIGHT_PIN` | *Not defined* | The pin that controls the LED(s) | -| `BACKLIGHT_LEVELS` | `3` | The number of brightness levels (maximum 31 excluding off) | -| `BACKLIGHT_CAPS_LOCK` | *Not defined* | Enable Caps Lock indicator using backlight (for keyboards without dedicated LED) | -| `BACKLIGHT_BREATHING` | *Not defined* | Enable backlight breathing, if supported | -| `BREATHING_PERIOD` | `6` | The length of one backlight "breath" in seconds | -| `BACKLIGHT_ON_STATE` | `1` | The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low | -| `BACKLIGHT_LIMIT_VAL ` | `255` | The maximum duty cycle of the backlight -- `255` allows for full brightness, any lower will decrease the maximum. | +|Define |Default |Description | +|-----------------------------|------------------|-----------------------------------------------------------------------------------------------------------------| +|`BACKLIGHT_PIN` |*Not defined* |The pin that controls the LED(s) | +|`BACKLIGHT_LEVELS` |`3` |The number of brightness levels (maximum 31 excluding off) | +|`BACKLIGHT_CAPS_LOCK` |*Not defined* |Enable Caps Lock indicator using backlight (for keyboards without dedicated LED) | +|`BACKLIGHT_BREATHING` |*Not defined* |Enable backlight breathing, if supported | +|`BREATHING_PERIOD` |`6` |The length of one backlight "breath" in seconds | +|`BACKLIGHT_ON_STATE` |`1` |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low | +|`BACKLIGHT_LIMIT_VAL` |`255` |The maximum duty cycle of the backlight -- `255` allows for full brightness, any lower will decrease the maximum.| +|`BACKLIGHT_DEFAULT_LEVEL` |`BACKLIGHT_LEVELS`|The default backlight level to use upon clearing the EEPROM | +|`BACKLIGHT_DEFAULT_BREATHING`|*Not defined* |Whether to enable backlight breathing upon clearing the EEPROM | Unless you are designing your own keyboard, you generally should not need to change the `BACKLIGHT_PIN` or `BACKLIGHT_ON_STATE`. -- cgit v1.2.3 From 275996f4c1e2ba0a7d1f66ed05de50e11a6a7520 Mon Sep 17 00:00:00 2001 From: James Young <18669334+noroadsleft@users.noreply.github.com> Date: Sat, 29 May 2021 12:30:31 -0700 Subject: Add changelog for 2021-05-29 Breaking Changes merge (#12939) * Add ChangeLog for 2021-05-29 Breaking Changes Merge: initial version * Add recent develop changes * Sort recent develop changes * Remove sections for ChibiOS changes per tzarc No ChibiOS changes this round. * Add and sort recent develop changes * add notes about keyboard moves/deletions * import changelog for PR 12172 Documents the change to BOOTMAGIC_ENABLE. * update section headings * re-sort changelog * add additional note regarding Bootmagic changes * remove changelog timestamp * update dates in main Breaking Changes docs * fix broken section anchors in previous changelogs * add link to backlight/eeprom patch to changelog * highlight some more changes * link PRs from section headers Co-authored-by: Zach White --- docs/ChangeLog/20200829.md | 2 +- docs/ChangeLog/20201128.md | 2 +- docs/ChangeLog/20210529.md | 192 +++++++++++++++++++++++++++++++++++++ docs/ChangeLog/20210529/PR12172.md | 13 --- docs/_summary.md | 2 +- docs/breaking_changes.md | 15 +-- docs/breaking_changes_history.md | 1 + 7 files changed, 204 insertions(+), 23 deletions(-) create mode 100644 docs/ChangeLog/20210529.md delete mode 100644 docs/ChangeLog/20210529/PR12172.md (limited to 'docs') diff --git a/docs/ChangeLog/20200829.md b/docs/ChangeLog/20200829.md index 00e0bd1a28..c6abed5b30 100644 --- a/docs/ChangeLog/20200829.md +++ b/docs/ChangeLog/20200829.md @@ -5,7 +5,7 @@ Four times a year QMK runs a process for merging Breaking Changes. A Breaking Ch ## Changes Requiring User Action :id=changes-requiring-user-action -### Relocated Keyboards :id-relocated-keyboards +### Relocated Keyboards :id=relocated-keyboards #### The Key Company project consolidation ([#9547](https://github.com/qmk/qmk_firmware/pull/9547)) #### relocating boards by flehrad to flehrad/ folder ([#9635](https://github.com/qmk/qmk_firmware/pull/9635)) diff --git a/docs/ChangeLog/20201128.md b/docs/ChangeLog/20201128.md index 86abd384df..4441320295 100644 --- a/docs/ChangeLog/20201128.md +++ b/docs/ChangeLog/20201128.md @@ -5,7 +5,7 @@ Four times a year QMK runs a process for merging Breaking Changes. A Breaking Ch ## Changes Requiring User Action :id=changes-requiring-user-action -### Relocated Keyboards :id-relocated-keyboards +### Relocated Keyboards :id=relocated-keyboards #### Reduce Helix keyboard build variation ([#8669](https://github.com/qmk/qmk_firmware/pull/8669)) diff --git a/docs/ChangeLog/20210529.md b/docs/ChangeLog/20210529.md new file mode 100644 index 0000000000..d005aeed36 --- /dev/null +++ b/docs/ChangeLog/20210529.md @@ -0,0 +1,192 @@ +# QMK Breaking Changes - 2021 May 29 Changelog + +## Notable Changes :id=notable-changes + +### RGB Matrix support for split common ([#11055](https://github.com/qmk/qmk_firmware/pull/11055)) :id=rgb-matrix-split-common + +Split boards can now use RGB Matrix without defining a custom matrix. + +### Teensy 3.6 support ([#12258](https://github.com/qmk/qmk_firmware/pull/12258)) :id=teensy-3-6-support + +Added support for MK66F18 (Teensy 3.6) microcontroller. + +### New command: qmk console ([#12828](https://github.com/qmk/qmk_firmware/pull/12828)) :id=new-command-qmk-console + +A new `qmk console` command has been added for attaching to your keyboard's console. It operates similiarly to QMK Toolbox by allowing you to connect to one or more keyboard consoles to display debugging messages. + +### Improved command: qmk config :id=improve-command-qmk-config + +We've updated the `qmk config` command to show only the configuration items you have actually set. You can now display (almost) all of the available configuration options, along with their default values, using `qmk config -a`. + +### LED Matrix Improvements ([#12509](https://github.com/qmk/qmk_firmware/pull/12509), [#12580](https://github.com/qmk/qmk_firmware/pull/12580), [#12588](https://github.com/qmk/qmk_firmware/pull/12588), [#12633](https://github.com/qmk/qmk_firmware/pull/12633), [#12651](https://github.com/qmk/qmk_firmware/pull/12651), [#12685](https://github.com/qmk/qmk_firmware/pull/12685)) :id=led-matrix-improvements + +LED Matrix has been improved with effects, CIE1931 curves, and a task system. + +## Changes Requiring User Action :id=changes-requiring-user-action + +### Updated Keyboard Codebases :id=updated-keyboard-codebases + +* Durgod keyboard refactor in preparation for adding additional durgod keyboards ([#11978](https://github.com/qmk/qmk_firmware/pull/11978)) +* Updated Function96 with V2 files and removed chconf.h and halconf.h ([#12613](https://github.com/qmk/qmk_firmware/pull/12613)) +* [Keyboard] updated a vendor name / fixed minor keymap issues ([#12881](https://github.com/qmk/qmk_firmware/pull/12881)) +* [Keyboard] Corne - Remove legacy revision support ([#12226](https://github.com/qmk/qmk_firmware/pull/12226)) + +The following keyboards have had their source moved within QMK: + +Old Keyboard Name | New Keyboard Name +:---------------- | :---------------- +crkbd/rev1/common | crkbd/rev1 +function96 | function96/v1 +nckiibs/flatbread60 | delikeeb/flatbread60 +nckiibs/vaguettelite | delikeeb/vaguettelite +nckiibs/vanana/rev1 | delikeeb/vanana/rev1 +nckiibs/vanana/rev2 | delikeeb/vanana/rev2 +nckiibs/vaneela | delikeeb/vaneela +nckiibs/vaneelaex | delikeeb/vaneelaex +nckiibs/waaffle/rev3/elite_c | delikeeb/waaffle/rev3/elite_c +nckiibs/waaffle/rev3/pro_micro | delikeeb/waaffle/rev3/pro_micro + +The [Function96 V2](https://github.com/qmk/qmk_firmware/tree/0.13.0/keyboards/function96/v2) has also been added as part of these changes. + +The codebase for the [Durgod K320](https://github.com/qmk/qmk_firmware/tree/0.13.0/keyboards/durgod/k320) has been reworked in anticipation of additional Durgod keyboards gaining QMK support. + +Additionally, the `crkbd/rev1/legacy` keyboard has been removed. + +### Bootmagic Deprecation and Refactor ([#12172](https://github.com/qmk/qmk_firmware/pull/12172)) :id=bootmagic-deprecation-and-refactor + +QMK has decided to deprecate the full Bootmagic feature and leave Bootmagic Lite as the only remaining option. + +This pull request changes the behavior of `BOOTMAGIC_ENABLE` such that specifying `BOOTMAGIC_ENABLE = yes` enables Bootmagic Lite instead of full Bootmagic. + +If attempts to use Bootmagic functionality result in unexpected behavior, check your `rules.mk` file and change the `BOOTMAGIC_ENABLE` setting to specify either `lite` or `full`. + +#### Tentative Deprecation Schedule + +This is the current planned roadmap for the behavior of `BOOTMAGIC_ENABLE`: + +- From 2021 May 29, setting `BOOTMAGIC_ENABLE = yes` will enable Bootmagic Lite instead of full Bootmagic. +- From 2021 Aug 28, `BOOTMAGIC_ENABLE` must be either `yes`, `lite`, or `no` – setting `BOOTMAGIC_ENABLE = full` will cause compilation to fail. +- From 2021 Nov 27, `BOOTMAGIC_ENABLE` must be either `yes` or `no` – setting `BOOTMAGIC_ENABLE = lite` will cause compilation to fail. + +### Removal of LAYOUT_kc ([#12160](https://github.com/qmk/qmk_firmware/pull/12160)) :id=removal-of-layout-kc + +We've removed support for `LAYOUT_kc` macros, if your keymap uses one you will need to update it use a regular `LAYOUT` macro. + +### Encoder callbacks are now boolean ([#12805](https://github.com/qmk/qmk_firmware/pull/12805), [#12985](https://github.com/qmk/qmk_firmware/pull/12985)) :id=encoder-callback-boolean + +To allow for keyboards to override (or not) keymap level code the `encoder_update_kb` function has been changed from `void` to `bool`. You will need to update your function definition to reflect this and ensure that you return a `true` or `false` value. + +Example code before change: + +```c +void encoder_update_kb(uint8_t index, bool clockwise) { + encoder_update_user(index, clockwise); +} +``` + +Example code after change: + +```c +bool encoder_update_kb(uint8_t index, bool clockwise) { + return encoder_update_user(index, clockwise); +} +``` + +## Core Changes :id=core-changes + +### Fixes :id=core-fixes + +* Fix connection issue in split keyboards when slave and OLED display are connected via I2C (fixes #9335) ([#11487](https://github.com/qmk/qmk_firmware/pull/11487)) +* Terrazzo: Fix wrong LED Matrix function names ([#12561](https://github.com/qmk/qmk_firmware/pull/12561)) +* Apply the "NO_LIMITED_CONTROLLER_CONNECT" fix to atmega16u2 ([#12482](https://github.com/qmk/qmk_firmware/pull/12482)) +* Fix comment parsing ([#12750](https://github.com/qmk/qmk_firmware/pull/12750)) +* Turn OLED off on suspend in soundmonster Corne keymap ([#10419](https://github.com/qmk/qmk_firmware/pull/10419)) +* Fixup build errors on `develop` branch. ([#12723](https://github.com/qmk/qmk_firmware/pull/12723)) +* Fix syntax error when compiling for ARM ([#12866](https://github.com/qmk/qmk_firmware/pull/12866)) +* Add missing LED Matrix suspend code to suspend.c ([#12878](https://github.com/qmk/qmk_firmware/pull/12878)) +* Fix spelling mistake regarding LED Matrix in split_common. ([#12888](https://github.com/qmk/qmk_firmware/pull/12888)) +* [Keymap] Fix QWERTY/DVORAK status output for kzar keymap ([#12895](https://github.com/qmk/qmk_firmware/pull/12895)) +* Fixup housekeeping from being invoked twice per loop. ([#12933](https://github.com/qmk/qmk_firmware/pull/12933)) +* wait for matrix row signal to go HIGH for every row ([#12945](https://github.com/qmk/qmk_firmware/pull/12945)) +* ensure we do not conflict with existing keymap aliases ([#12976](https://github.com/qmk/qmk_firmware/pull/12976)) +* [Keyboard] Fix Terrazzo build failure ([#12977](https://github.com/qmk/qmk_firmware/pull/12977)) +* Do not hard set config in CPTC files ([#11864](https://github.com/qmk/qmk_firmware/pull/11864)) + +### Additions and Enhancements :id=core-additions + +* ARM - Refactor SLEEP_LED to support more platforms ([#8403](https://github.com/qmk/qmk_firmware/pull/8403)) +* Add ability to toggle One Shot functionality ([#4198](https://github.com/qmk/qmk_firmware/pull/4198)) +* Add RGB Matrix support to Split Common ([#11055](https://github.com/qmk/qmk_firmware/pull/11055)) +* Add support for complementary outputs to the ChibiOS WS2812 PWM driver ([#11988](https://github.com/qmk/qmk_firmware/pull/11988)) +* Enable RGB Matrix for Corne ([#12091](https://github.com/qmk/qmk_firmware/pull/12091)) +* Set default OLED Update Interval for Split Keyboards to improve matrix scan performance ([#12107](https://github.com/qmk/qmk_firmware/pull/12107)) +* Add support for MK66F18 (Teensy 3.6) micro controller ([#12258](https://github.com/qmk/qmk_firmware/pull/12258)) +* Split RGB Matrix support for RGBKB Zygomorph ([#11083](https://github.com/qmk/qmk_firmware/pull/11083)) +* Add baudrate and circular buffer to ARM WS2812 SPI config ([#12216](https://github.com/qmk/qmk_firmware/pull/12216)) +* Add keyboard level weak function for slave matrix scan ([#12317](https://github.com/qmk/qmk_firmware/pull/12317)) +* Add link to schematic on EasyEDA for XD60 ([#12018](https://github.com/qmk/qmk_firmware/pull/12018)) +* Add Config functions for LED Matrix ([#12361](https://github.com/qmk/qmk_firmware/pull/12361)) +* Add pin definitions for MK66F18 ([#12419](https://github.com/qmk/qmk_firmware/pull/12419)) +* add kinesis/kint36 keyboard ([#10171](https://github.com/qmk/qmk_firmware/pull/10171)) +* Add support for producing UF2-format binaries. ([#12435](https://github.com/qmk/qmk_firmware/pull/12435)) +* Implement CIE1931 curve for LED Matrix ([#12417](https://github.com/qmk/qmk_firmware/pull/12417)) +* Change `BOOTMAGIC_ENABLE=yes` to use Bootmagic Lite ([#12172](https://github.com/qmk/qmk_firmware/pull/12172)) +* Add kzar keymap for Kinesis Advantage ([#12444](https://github.com/qmk/qmk_firmware/pull/12444)) +* LED Matrix: suspend code ([#12509](https://github.com/qmk/qmk_firmware/pull/12509)) +* LED Matrix: Task system ([#12580](https://github.com/qmk/qmk_firmware/pull/12580)) +* Add missing RGB_MODE_TWINKLE / RGB_M_TW keycodes ([#11935](https://github.com/qmk/qmk_firmware/pull/11935)) +* Enhancement of WPM feature ([#11727](https://github.com/qmk/qmk_firmware/pull/11727)) +* Add Per Key functionality for AutoShift ([#11536](https://github.com/qmk/qmk_firmware/pull/11536)) +* LED Matrix: Reactive effect buffers & advanced indicators ([#12588](https://github.com/qmk/qmk_firmware/pull/12588)) +* LED Matrix: support for Split keyboards ([#12633](https://github.com/qmk/qmk_firmware/pull/12633)) +* add setting to enable infinite timeout for leader key ([#6580](https://github.com/qmk/qmk_firmware/pull/6580), [#12721](https://github.com/qmk/qmk_firmware/pull/12721 "Fix bad PR merge for #6580")) +* Update ADC driver for STM32F1xx, STM32F3xx, STM32F4xx ([#12403](https://github.com/qmk/qmk_firmware/pull/12403)) +* Add initial support for tinyuf2 bootloader (when hosted on F411 blackpill) ([#12600](https://github.com/qmk/qmk_firmware/pull/12600)) +* Add support for STM32F446 MCU ([#12619](https://github.com/qmk/qmk_firmware/pull/12619)) +* Add STM32L433 and L443 support ([#12063](https://github.com/qmk/qmk_firmware/pull/12063)) +* Added OLED fade out support ([#12086](https://github.com/qmk/qmk_firmware/pull/12086)) +* New command: `qmk console` ([#12828](https://github.com/qmk/qmk_firmware/pull/12828)) +* LED Matrix: Effects! ([#12651](https://github.com/qmk/qmk_firmware/pull/12651)) +* Add setup, clone, and env to the list of commands we allow even with broken modules ([#12868](https://github.com/qmk/qmk_firmware/pull/12868)) +* LED Matrix: Documentation ([#12685](https://github.com/qmk/qmk_firmware/pull/12685)) +* Add function to allow repeated blinking of one layer ([#12237](https://github.com/qmk/qmk_firmware/pull/12237)) +* Add support for up to 4 IS31FL3733 drivers ([#12342](https://github.com/qmk/qmk_firmware/pull/12342)) +* Convert Encoder callbacks to be boolean functions ([#12805](https://github.com/qmk/qmk_firmware/pull/12805), [#12985](https://github.com/qmk/qmk_firmware/pull/12985)) +* [Keymap] Update to Drashna keymap and user code (based on develop) ([#12936](https://github.com/qmk/qmk_firmware/pull/12936)) +* Add Full-duplex serial driver for ARM boards ([#9842](https://github.com/qmk/qmk_firmware/pull/9842)) +* Document LED_MATRIX_FRAMEBUFFER_EFFECTS ([#12987](https://github.com/qmk/qmk_firmware/pull/12987)) +* Backlight: add defines for default level and breathing state ([#12560](https://github.com/qmk/qmk_firmware/pull/12560), [#13024](https://github.com/qmk/qmk_firmware/pull/13024)) +* Add dire message about LUFA mass storage bootloader ([#13014](https://github.com/qmk/qmk_firmware/pull/13014)) + +### Clean-ups and Optimizations :id=core-optimizations + +* Overhaul bootmagic logic to have single entrypoint ([#8532](https://github.com/qmk/qmk_firmware/pull/8532)) +* Refactor of USB code within split_common ([#11890](https://github.com/qmk/qmk_firmware/pull/11890)) +* Begin the process of deprecating `bin/qmk` in favor of the global CLI ([#12109](https://github.com/qmk/qmk_firmware/pull/12109)) +* LED Matrix: decouple from Backlight ([#12054](https://github.com/qmk/qmk_firmware/pull/12054)) +* Remove `FUNC()` ([#12161](https://github.com/qmk/qmk_firmware/pull/12161)) +* Move gpio wait logic to wait.h ([#12067](https://github.com/qmk/qmk_firmware/pull/12067)) +* LED Matrix: Clean up includes ([#12197](https://github.com/qmk/qmk_firmware/pull/12197)) +* Consistently use bin/qmk when that script is called ([#12286](https://github.com/qmk/qmk_firmware/pull/12286)) +* LED Matrix: Additional common_features.mk tweaks ([#12187](https://github.com/qmk/qmk_firmware/pull/12187)) +* LED Matrix: Fix up eeconfig code ([#12327](https://github.com/qmk/qmk_firmware/pull/12327)) +* Big quantum_keycodes cleanup ([#12249](https://github.com/qmk/qmk_firmware/pull/12249)) +* Fix up builds that are now too big for `develop` branch. ([#12495](https://github.com/qmk/qmk_firmware/pull/12495)) +* [Keyboard] kint36: switch to sym_eager_pk debouncing ([#12626](https://github.com/qmk/qmk_firmware/pull/12626)) +* [Keyboard] kint2pp: reduce input latency by ≈10ms ([#12625](https://github.com/qmk/qmk_firmware/pull/12625)) +* eeprom driver: Refactor where eeprom driver initialisation (and EEPROM emulation initialisation) occurs to make it non-target-specific. ([#12671](https://github.com/qmk/qmk_firmware/pull/12671)) +* Change RGB/LED Matrix to use a simple define for USB suspend ([#12697](https://github.com/qmk/qmk_firmware/pull/12697), [#12770](https://github.com/qmk/qmk_firmware/pull/12770 "Fixing transport's led/rgb matrix suspend state logic")) +* Remove pointless SERIAL_LINK_ENABLE rules ([#12846](https://github.com/qmk/qmk_firmware/pull/12846)) +* Make Swap Hands use PROGMEM ([#12284](https://github.com/qmk/qmk_firmware/pull/12284)) +* Remove KEYMAP and LAYOUT_kc ([#12160](https://github.com/qmk/qmk_firmware/pull/12160)) +* Rename `point_t` -> `led_point_t` ([#12864](https://github.com/qmk/qmk_firmware/pull/12864)) +* Deprecate `send_unicode_hex_string()` ([#12602](https://github.com/qmk/qmk_firmware/pull/12602)) +* [Keyboard] Remove redundant legacy and common headers for crkbd ([#13023](https://github.com/qmk/qmk_firmware/pull/13023)) + +### QMK Infrastructure and Internals :id=qmk-internals + +* trivial change to trigger api update ([`b15288fb87`](https://github.com/qmk/qmk_firmware/commit/b15288fb87)) +* fix some references to bin/qmk that slipped in ([#12832](https://github.com/qmk/qmk_firmware/pull/12832)) +* Resolve a number of warnings in `qmk generate-api` ([#12833](https://github.com/qmk/qmk_firmware/pull/12833)) +* Fix another bin/qmk reference ([#12856](https://github.com/qmk/qmk_firmware/pull/12856)) +* Use milc.subcommand.config instead of qmk.cli.config ([#12915](https://github.com/qmk/qmk_firmware/pull/12915)) diff --git a/docs/ChangeLog/20210529/PR12172.md b/docs/ChangeLog/20210529/PR12172.md deleted file mode 100644 index 0c355c151e..0000000000 --- a/docs/ChangeLog/20210529/PR12172.md +++ /dev/null @@ -1,13 +0,0 @@ -## Bootmagic Deprecation and Refactor ([#12172](https://github.com/qmk/qmk_firmware/pull/12172)) - -QMK has decided to deprecate the full Bootmagic feature and leave Bootmagic Lite as the only remaining option. - -This pull request changes the behavior of `BOOTMAGIC_ENABLE` such that specifying `BOOTMAGIC_ENABLE = yes` enables Bootmagic Lite instead of full Bootmagic. - -### Tentative Deprecation Schedule - -This is the current planned roadmap for the behavior of `BOOTMAGIC_ENABLE`: - -- From 2021-05-29, setting `BOOTMAGIC_ENABLE = yes` will enable Bootmagic Lite instead of full Bootmagic. -- From 2021-08-28, `BOOTMAGIC_ENABLE` must be either `yes`, `lite`, or `no` – setting `BOOTMAGIC_ENABLE = full` will cause compilation to fail. -- From 2021-11-27, `BOOTMAGIC_ENABLE` must be either `yes` or `no` – setting `BOOTMAGIC_ENABLE = lite` will cause compilation to fail. diff --git a/docs/_summary.md b/docs/_summary.md index 825514e6b5..38937771f6 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -120,7 +120,7 @@ * Breaking Changes * [Overview](breaking_changes.md) * [My Pull Request Was Flagged](breaking_changes_instructions.md) - * [Most Recent ChangeLog](ChangeLog/20210227.md "QMK v0.12.0 - 2021 Feb 27") + * [Most Recent ChangeLog](ChangeLog/20210529.md "QMK v0.13.0 - 2021 May 29") * [Past Breaking Changes](breaking_changes_history.md) * C Development diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md index 0503789cdb..3e85a70761 100644 --- a/docs/breaking_changes.md +++ b/docs/breaking_changes.md @@ -6,6 +6,7 @@ The breaking change period is when we will merge PR's that change QMK in dangero ## What has been included in past Breaking Changes? +* [2021 May 29](ChangeLog/20210529.md) * [2021 Feb 27](ChangeLog/20210227.md) * [2020 Nov 28](ChangeLog/20201128.md) * [2020 Aug 29](ChangeLog/20200829.md) @@ -15,16 +16,16 @@ The breaking change period is when we will merge PR's that change QMK in dangero ## When is the next Breaking Change? -The next Breaking Change is scheduled for May 29, 2021. +The next Breaking Change is scheduled for August 28, 2021. ### Important Dates -* [x] 2021 Feb 27 - `develop` is created. Each push to `master` is subsequently merged to `develop` -* [ ] 2021 May 01 - `develop` closed to new PR's. -* [ ] 2021 May 01 - Call for testers. -* [ ] 2021 May 27 - `master` is locked, no PR's merged. -* [ ] 2021 May 29 - Merge `develop` to `master`. -* [ ] 2021 May 29 - `master` is unlocked. PR's can be merged again. +* [x] 2021 May 29 - `develop` is created. Each push to `master` is subsequently merged to `develop` +* [ ] 2021 Jul 31 - `develop` closed to new PR's. +* [ ] 2021 Jul 31 - Call for testers. +* [ ] 2021 Aug 26 - `master` is locked, no PR's merged. +* [ ] 2021 Aug 28 - Merge `develop` to `master`. +* [ ] 2021 Aug 28 - `master` is unlocked. PR's can be merged again. ## What changes will be included? diff --git a/docs/breaking_changes_history.md b/docs/breaking_changes_history.md index dd474f1bb7..6ba8fe3b06 100644 --- a/docs/breaking_changes_history.md +++ b/docs/breaking_changes_history.md @@ -2,6 +2,7 @@ This page links to all previous changelogs from the QMK Breaking Changes process. +* [2021 May 29](ChangeLog/20210529.md) - version 0.13.0 * [2021 Feb 27](ChangeLog/20210227.md) - version 0.12.0 * [2020 Nov 28](ChangeLog/20201128.md) - version 0.11.0 * [2020 Aug 29](ChangeLog/20200829.md) - version 0.10.0 -- cgit v1.2.3 From 554c36a0555998c57b78a5e66074b8292b0e9577 Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Tue, 1 Jun 2021 08:11:50 +1000 Subject: Update ChibiOS, ChibiOS-Contrib. (#13056) * Update ChibiOS, ChibiOS-Contrib. * Add instructions. * Wrong remote name * Explicit version tag. * Add link to procedure on the breaking changes page. --- docs/breaking_changes.md | 4 +++ docs/chibios_upgrade_instructions.md | 56 ++++++++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+) create mode 100644 docs/chibios_upgrade_instructions.md (limited to 'docs') diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md index 3e85a70761..2ad8b5a14d 100644 --- a/docs/breaking_changes.md +++ b/docs/breaking_changes.md @@ -96,3 +96,7 @@ This happens immediately after the previous `develop` branch is merged. * [ ] Create a PR for `develop` * [ ] Make sure travis comes back clean * [ ] Merge `develop` PR + +## Post-merge operations + +* (Optional) [update ChibiOS + ChibiOS-Contrib on `develop`](chibios_upgrade_instructions.md) \ No newline at end of file diff --git a/docs/chibios_upgrade_instructions.md b/docs/chibios_upgrade_instructions.md new file mode 100644 index 0000000000..40c2faafcf --- /dev/null +++ b/docs/chibios_upgrade_instructions.md @@ -0,0 +1,56 @@ +# ChibiOS Upgrade Procedure + +ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a branch tied to the ChibiOS version in use and should not be mixed with different versions. + +## Getting ChibiOS + +* `svn` Initialisation: + * Only needed to be done once + * You might need to separately install `git-svn` package in your OS's package manager + * `git svn init --stdlayout --prefix='svn/' http://svn.osdn.net/svnroot/chibios/` + * `git remote add qmk git@github.com:qmk/ChibiOS.git` +* Updating: + * `git svn fetch` + * First time around this will take several hours + * Subsequent updates will be incremental only +* Tagging example (work out which version first!): + * `git tag -a ver20.3.3 -m ver20.3.3 svn/tags/ver20.3.3` + * `git push qmk ver20.3.3` + * `git tag -a breaking_YYYY_qN -m breaking_YYYY_qN svn/tags/ver20.3.3` + * `git push qmk breaking_YYYY_qN` + +## Getting ChibiOS-Contrib + +* `git` Initialisation: + * `git clone git@github.com:qmk/ChibiOS-Contrib` + * `git remote add upstream https://github.com/ChibiOS/ChibiOS-Contrib` + * `git checkout -b chibios-20.3.x upstream/chibios-20.3.x` +* Updating: + * `git fetch --all --tags --prune` + * `git checkout chibios-20.3.x` + * `git pull --ff-only` + * `git push origin chibios-20.3.x` + * `git tag -a breaking_YYYY_qN -m breaking_YYYY_qN chibios-20.3.x` + * `git push origin breaking_YYYY_qN` + +## Updating submodules + +* Update the submodules + * `cd $QMK_FIRMWARE` + * `git checkout develop` + * `git pull --ff-only` + * `git checkout -b chibios-version-bump` + * `cd lib/chibios` + * `git fetch --all --tags --prune` + * `git checkout breaking_YYYY_qN` + * `cd ../chibios-contrib` + * `git fetch --all --tags --prune` + * `git checkout breaking_YYYY_qN` +* Build everything + * `cd $QMK_FIRMWARE` + * `qmk multibuild -j4` + * Make sure there are no errors +* Push to the repo + * `git commit -am 'Update ChibiOS to XXXXXXXXX'` + * `git push --set-upstream origin chibios-version-bump` +* Make a PR to qmk_firmware with the new branch \ No newline at end of file -- cgit v1.2.3 From f287597c19dc926c7c28cefa32ffc3f0b4fdba7f Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Wed, 9 Jun 2021 17:19:42 +1000 Subject: Use single memcmp to determine if matrix changed. (#13064) * Use memcmp to determine if matrix changed. * Firmware size issues. * Add documentation for the lack of need of MATRIX_ROW_PINS/MATRIX_COL_PINS, when overriding low-level matrix functions. --- docs/config_options.md | 3 +++ docs/custom_quantum_functions.md | 8 ++++++++ 2 files changed, 11 insertions(+) (limited to 'docs') diff --git a/docs/config_options.md b/docs/config_options.md index d0f0b316e0..26fe8cea55 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -51,8 +51,10 @@ This is a C header file that is one of the first things included, and will persi * the number of columns in your keyboard's matrix * `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }` * pins of the rows, from top to bottom + * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. * `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }` * pins of the columns, from left to right + * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. * `#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 }` @@ -280,6 +282,7 @@ There are a few different ways to set handedness for split keyboards (listed in * `#define MATRIX_ROW_PINS_RIGHT { }` * `#define MATRIX_COL_PINS_RIGHT { }` * If you want to specify a different pinout for the right half than the left half, you can define `MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT`. Currently, the size of `MATRIX_ROW_PINS` must be the same as `MATRIX_ROW_PINS_RIGHT` and likewise for the definition of columns. + * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. * `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }` * If you want to specify a different direct pinout for the right half than the left half, you can define `DIRECT_PINS_RIGHT`. Currently, the size of `DIRECT_PINS` must be the same as `DIRECT_PINS_RIGHT`. diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index 694b421e79..30c637bb49 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -144,6 +144,14 @@ This is useful for setting up stuff that you may need elsewhere, but isn't hardw * Keyboard/Revision: `void matrix_init_kb(void)` * Keymap: `void matrix_init_user(void)` +### Low-level Matrix Overrides Function Documentation :id=low-level-matrix-overrides + +* GPIO pin initialisation: `void matrix_init_pins(void)` + * This needs to perform the low-level initialisation of all row and column pins. By default this will initialise the input/output state of each of the GPIO pins listed in `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`, based on whether or not the keyboard is set up for `ROW2COL`, `COL2ROW`, or `DIRECT_PINS`. Should the keyboard designer override this function, no initialisation of pin state will occur within QMK itself, instead deferring to the keyboard's override. +* `COL2ROW`-based row reads: `void matrix_read_rows_on_col(matrix_row_t current_matrix[], uint8_t current_col)` +* `ROW2COL`-based column reads: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)` +* `DIRECT_PINS`-based reads: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)` + * These three functions need to perform the low-level retrieval of matrix state of relevant input pins, based on the matrix type. Only one of the functions should be implemented, if needed. By default this will iterate through `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`, configuring the inputs and outputs based on whether or not the keyboard is set up for `ROW2COL`, `COL2ROW`, or `DIRECT_PINS`. Should the keyboard designer override this function, no manipulation of matrix GPIO pin state will occur within QMK itself, instead deferring to the keyboard's override. ## Keyboard Post Initialization code -- cgit v1.2.3 From 32b2ac0a807bdb088df685e6118f4c0966b6cca4 Mon Sep 17 00:00:00 2001 From: Gigahawk Date: Wed, 9 Jun 2021 18:40:25 -0700 Subject: GMMK Pro RGB Support (#13147) * Enable SPI1 for GMMK pro * Setup initial boilerplate for new LED driver * RGB matrix minimally functional * Map full LED matrix * Return keymap to default * Fix printscreen LED mapping * Reduce max brightness * Default values for AW20216 * Add documentation for AW20216 * Disable console and warnings * Run cformat * Update drivers/awinic/aw20216.h Co-authored-by: Drashna Jaelre * make aw struct match issi struct Co-authored-by: Drashna Jaelre * add led location defines Co-authored-by: Drashna Jaelre * Use led pin definitions in keyboard.c * Add driver indices to led map * Fix elif typo * Run cformat * Update docs * Fix typo in docs * Document global brightness limits Co-authored-by: Drashna Jaelre --- docs/feature_rgb_matrix.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 169443fb85..afd72fecff 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -227,6 +227,74 @@ Configure the hardware via your `config.h`: #define DRIVER_LED_TOTAL 70 ``` +--- +### AW20216 :id=aw20216 +There is basic support for addressable RGB matrix lighting with the SPI AW20216 RGB controller. To enable it, add this to your `rules.mk`: + +```makefile +RGB_MATRIX_ENABLE = yes +RGB_MATRIX_DRIVER = AW20216 +``` + +You can use up to 2 AW20216 IC's. Do not specify `DRIVER__xxx` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`: + +| Variable | Description | Default | +|----------|-------------|---------| +| `DRIVER_1_CS` | (Required) MCU pin connected to first RGB driver chip select line | B13 | +| `DRIVER_2_CS` | (Optional) MCU pin connected to second RGB driver chip select line | | +| `DRIVER_1_EN` | (Required) MCU pin connected to first RGB driver hardware enable line | C13 | +| `DRIVER_2_EN` | (Optional) MCU pin connected to second RGB driver hardware enable line | | +| `DRIVER_1_LED_TOTAL` | (Required) How many RGB lights are connected to first RGB driver | | +| `DRIVER_2_LED_TOTAL` | (Optional) How many RGB lights are connected to second RGB driver | | +| `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | +| `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | | +| `AW_SCALING_MAX` | (Optional) LED current scaling value (0-255, higher values mean LED is brighter at full PWM) | 150 | +| `AW_GLOBAL_CURRENT_MAX` | (Optional) Driver global current limit (0-255, higher values means the driver may consume more power) | 150 | + +Here is an example using 2 drivers. + +```c +#define DRIVER_1_CS B13 +#define DRIVER_2_CS B14 +// Hardware enable lines may be connected to the same pin +#define DRIVER_1_EN C13 +#define DRIVER_2_EN C13 + +#define DRIVER_COUNT 2 +#define DRIVER_1_LED_TOTAL 66 +#define DRIVER_2_LED_TOTAL 32 +#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) +``` + +!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. + +Define these arrays listing all the LEDs in your `.c`: + +```c +const aw_led g_aw_leds[DRIVER_LED_TOTAL] = { +/* Each AW20216 channel is controlled by a register at some offset between 0x00 + * and 0xD7 inclusive. + * See drivers/awinic/aw20216.h for the mapping between register offsets and + * driver pin locations. + * driver + * | R location + * | | G location + * | | | B location + * | | | | */ + { 0, CS1_SW1, CS2_SW1, CS3_SW1 }, + { 0, CS4_SW1, CS5_SW1, CS6_SW1 }, + { 0, CS7_SW1, CS8_SW1, CS9_SW1 }, + { 0, CS10_SW1, CS11_SW1, CS12_SW1 }, + { 0, CS13_SW1, CS14_SW1, CS15_SW1 }, + ... + { 1, CS1_SW1, CS2_SW1, CS3_SW1 }, + { 1, CS13_SW1, CS14_SW1, CS15_SW1 }, + { 1, CS16_SW1, CS17_SW1, CS18_SW1 }, + { 1, CS4_SW2, CS5_SW2, CS6_SW2 }, + ... +}; +``` + --- 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: -- cgit v1.2.3 From b2fdd4874434ef6921a436fc82d9f24909c726f8 Mon Sep 17 00:00:00 2001 From: Ryan Date: Thu, 10 Jun 2021 17:16:09 +1000 Subject: Add ST7565 LCD driver (#13089) Co-authored-by: Joakim Tufvegren --- docs/_summary.md | 1 + docs/feature_st7565.md | 270 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 271 insertions(+) create mode 100644 docs/feature_st7565.md (limited to 'docs') diff --git a/docs/_summary.md b/docs/_summary.md index 9798ef5127..4141e01e77 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -93,6 +93,7 @@ * Hardware Features * Displays * [HD44780 LCD Controller](feature_hd44780.md) + * [ST7565 LCD Driver](feature_st7565.md) * [OLED Driver](feature_oled_driver.md) * Lighting * [Backlight](feature_backlight.md) diff --git a/docs/feature_st7565.md b/docs/feature_st7565.md new file mode 100644 index 0000000000..7db0f9ac4a --- /dev/null +++ b/docs/feature_st7565.md @@ -0,0 +1,270 @@ +# ST7565 LCD Driver + +## Supported Hardware + +LCD modules using ST7565 driver IC, communicating over SPI. + +|Module |IC |Size |Notes | +|------------------------------|-------|------|----------------------------------------------------------| +|Newhaven Display NHD-C12832A1Z|ST7565R|128x32|Used by Ergodox Infinity; primary consumer of this feature| +|Zolentech ZLE12864B |ST7565P|128x64|Requires contrast adjustment | + +## Usage + +To enable the feature, there are three steps. First, when compiling your keyboard, you'll need to add the following to your `rules.mk`: + +```make +ST7565_ENABLE = yes +``` + +Then in your `keymap.c` file, implement the ST7565 task call. This example assumes your keymap has three layers named `_QWERTY`, `_FN` and `_ADJ`: + +```c +#ifdef ST7565_ENABLE +void st7565_task_user(void) { + // Host Keyboard Layer Status + st7565_write_P(PSTR("Layer: "), false); + + switch (get_highest_layer(layer_state)) { + case _QWERTY: + st7565_write_P(PSTR("Default\n"), false); + break; + case _FN: + st7565_write_P(PSTR("FN\n"), false); + break; + case _ADJ: + st7565_write_P(PSTR("ADJ\n"), false); + break; + default: + // Or use the write_ln shortcut over adding '\n' to the end of your string + st7565_write_ln_P(PSTR("Undefined"), false); + } + + // Host Keyboard LED Status + led_t led_state = host_keyboard_led_state(); + st7565_write_P(led_state.num_lock ? PSTR("NUM ") : PSTR(" "), false); + st7565_write_P(led_state.caps_lock ? PSTR("CAP ") : PSTR(" "), false); + st7565_write_P(led_state.scroll_lock ? PSTR("SCR ") : PSTR(" "), false); +} +#endif +``` + +## Logo Example + +In the default font, certain ranges of characters are reserved for a QMK logo. To render this logo to the screen, use the following code example: + +```c +static void render_logo(void) { + static const char PROGMEM qmk_logo[] = { + 0x80, 0x81, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89, 0x8A, 0x8B, 0x8C, 0x8D, 0x8E, 0x8F, 0x90, 0x91, 0x92, 0x93, 0x94, + 0xA0, 0xA1, 0xA2, 0xA3, 0xA4, 0xA5, 0xA6, 0xA7, 0xA8, 0xA9, 0xAA, 0xAB, 0xAC, 0xAD, 0xAE, 0xAF, 0xB0, 0xB1, 0xB2, 0xB3, 0xB4, + 0xC0, 0xC1, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, 0xC8, 0xC9, 0xCA, 0xCB, 0xCC, 0xCD, 0xCE, 0xCF, 0xD0, 0xD1, 0xD2, 0xD3, 0xD4, 0x00 + }; + + st7565_write_P(qmk_logo, false); +} +``` + +## Buffer Read Example +For some purposes, you may need to read the current state of the display buffer. The `st7565_read_raw` function can be used to safely read bytes from the buffer. + +In this example, calling `fade_display` in the `st7565_task_user` function will slowly fade away whatever is on the screen by turning random pixels off over time. +```c +//Setup some mask which can be or'd with bytes to turn off pixels +const uint8_t single_bit_masks[8] = {127, 191, 223, 239, 247, 251, 253, 254}; + +static void fade_display(void) { + //Define the reader structure + display_buffer_reader_t reader; + uint8_t buff_char; + if (random() % 30 == 0) { + srand(timer_read()); + // Fetch a pointer for the buffer byte at index 0. The return structure + // will have the pointer and the number of bytes remaining from this + // index position if we want to perform a sequential read by + // incrementing the buffer pointer + reader = st7565_read_raw(0); + //Loop over the remaining buffer and erase pixels as we go + for (uint16_t i = 0; i < reader.remaining_element_count; i++) { + //Get the actual byte in the buffer by dereferencing the pointer + buff_char = *reader.current_element; + if (buff_char != 0) { + st7565_write_raw_byte(buff_char & single_bit_masks[rand() % 8], i); + } + //increment the pointer to fetch a new byte during the next loop + reader.current_element++; + } + } +} +``` + +## Other Examples + +In split keyboards, it is very common to have two displays that each render different content and are oriented or flipped differently. You can do this by switching which content to render by using the return value from `is_keyboard_master()` or `is_keyboard_left()` found in `split_util.h`, e.g: + +```c +#ifdef ST7565_ENABLE +display_rotation_t st7565_init_user(display_rotation_t rotation) { + if (!is_keyboard_master()) { + return DISPLAY_ROTATION_180; // flips the display 180 degrees if offhand + } + + return rotation; +} + +void st7565_task_user(void) { + if (is_keyboard_master()) { + render_status(); // Renders the current keyboard state (layer, lock, caps, scroll, etc) + } else { + render_logo(); // Renders a static logo + } +} +#endif +``` + +## Basic Configuration + +|Define |Default |Description | +|------------------------|--------------|-----------------------------------------------------------------------------------------------------| +|`ST7565_A0_PIN` |*Not defined* |(Required) The GPIO connected to the display's A0 (data/command) pin | +|`ST7565_RST_PIN` |*Not defined* |(Required) The GPIO connected to the display's reset pin | +|`ST7565_SS_PIN` |*Not defined* |(Required) The GPIO connected to the display's slave select pin | +|`ST7565_SPI_CLK_DIVISOR`|`4` |The SPI clock divisor to use | +|`ST7565_FONT_H` |`"glcdfont.c"`|The font code file to use for custom fonts | +|`ST7565_FONT_START` |`0` |The starting character index for custom fonts | +|`ST7565_FONT_END` |`223` |The ending character index for custom fonts | +|`ST7565_FONT_WIDTH` |`6` |The font width | +|`ST7565_FONT_HEIGHT` |`8` |The font height (untested) | +|`ST7565_TIMEOUT` |`60000` |Turns off the screen after 60000ms of keyboard inactivity. Helps reduce burn-in. Set to 0 to disable.| +|`ST7565_COLUMN_OFFSET` |`0` |Shift output to the right this many pixels. | +|`ST7565_CONTRAST` |`32` |The default contrast level of the display, from 0 to 255. | +|`ST7565_UPDATE_INTERVAL`|`0` |Set the time interval for updating the display in ms. This will improve the matrix scan rate. | + +## Custom sized displays + +The default display size for this feature is 128x32 and all necessary defines are precalculated with that in mind. + +|Define |Default |Description | +|-----------------------|----------|-----------------------------------------------------------------------------------------------------------| +|`ST7565_DISPLAY_WIDTH` |`128` |The width of the display. | +|`ST7565_DISPLAY_HEIGHT`|`32` |The height of the display. | +|`ST7565_MATRIX_SIZE` |`512` |The local buffer size to allocate.
`(ST7565_DISPLAY_HEIGHT / 8 * ST7565_DISPLAY_WIDTH)`. | +|`ST7565_BLOCK_TYPE` |`uint16_t`|The unsigned integer type to use for dirty rendering. | +|`ST7565_BLOCK_COUNT` |`16` |The number of blocks the display is divided into for dirty rendering.
`(sizeof(ST7565_BLOCK_TYPE) * 8)`.| +|`ST7565_BLOCK_SIZE` |`32` |The size of each block for dirty rendering
`(ST7565_MATRIX_SIZE / ST7565_BLOCK_COUNT)`. | + +## API + +```c +// Rotation enum values are flags +typedef enum { + DISPLAY_ROTATION_0, + DISPLAY_ROTATION_180 +} display_rotation_t; + +// Initialize the display, rotating the rendered output based on the define passed in. +// Returns true if the was initialized successfully +bool st7565_init(display_rotation_t rotation); + +// Called at the start of st7565_init, weak function overridable by the user +// rotation - the value passed into st7565_init +// Return new display_rotation_t if you want to override default rotation +display_rotation_t st7565_init_user(display_rotation_t rotation); + +// Clears the display buffer, resets cursor position to 0, and sets the buffer to dirty for rendering +void st7565_clear(void); + +// Renders the dirty chunks of the buffer to display +void st7565_render(void); + +// Moves cursor to character position indicated by column and line, wraps if out of bounds +// Max column denoted by 'st7565_max_chars()' and max lines by 'st7565_max_lines()' functions +void st7565_set_cursor(uint8_t col, uint8_t line); + +// Advances the cursor to the next page, writing ' ' if true +// Wraps to the begining when out of bounds +void st7565_advance_page(bool clearPageRemainder); + +// Moves the cursor forward 1 character length +// Advance page if there is not enough room for the next character +// Wraps to the begining when out of bounds +void st7565_advance_char(void); + +// Writes a single character to the buffer at current cursor position +// Advances the cursor while writing, inverts the pixels if true +// Main handler that writes character data to the display buffer +void st7565_write_char(const char data, bool invert); + +// Writes a string to the buffer at current cursor position +// Advances the cursor while writing, inverts the pixels if true +void st7565_write(const char *data, bool invert); + +// Writes a string to the buffer at current cursor position +// Advances the cursor while writing, inverts the pixels if true +// Advances the cursor to the next page, wiring ' ' to the remainder of the current page +void st7565_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 +void st7565_pan(bool left); + +// Returns a pointer to the requested start index in the buffer plus remaining +// buffer length as struct +display_buffer_reader_t st7565_read_raw(uint16_t start_index); + +// Writes a string to the buffer at current cursor position +void st7565_write_raw(const char *data, uint16_t size); + +// Writes a single byte into the buffer at the specified index +void st7565_write_raw_byte(const char data, uint16_t index); + +// Sets a specific pixel on or off +// Coordinates start at top-left and go right and down for positive x and y +void st7565_write_pixel(uint8_t x, uint8_t y, bool on); + +// 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 st7565_write(const char *data, bool invert);' on ARM +void st7565_write_P(const char *data, bool invert); + +// Writes a PROGMEM string to the buffer at current cursor position +// Advances the cursor while writing, inverts the pixels if true +// Advances the cursor to the next page, wiring ' ' to the remainder of the current page +// Remapped to call 'void st7565_write_ln(const char *data, bool invert);' on ARM +void st7565_write_ln_P(const char *data, bool invert); + +// Writes a PROGMEM string to the buffer at current cursor position +void st7565_write_raw_P(const char *data, uint16_t size); + +// Can be used to manually turn on the screen if it is off +// Returns true if the screen was on or turns on +bool st7565_on(void); + +// Called when st7565_on() turns on the screen, weak function overridable by the user +// Not called if the screen is already on +void st7565_on_user(void); + +// Can be used to manually turn off the screen if it is on +// Returns true if the screen was off or turns off +bool st7565_off(void); + +// Called when st7565_off() turns off the screen, weak function overridable by the user +// Not called if the screen is already off +void st7565_off_user(void); + +// Returns true if the screen is currently on, false if it is +// not +bool st7565_is_on(void); + +// Basically it's st7565_render, but with timeout management and st7565_task_user calling! +void st7565_task(void); + +// Called at the start of st7565_task, weak function overridable by the user +void st7565_task_user(void); + +// Returns the maximum number of characters that will fit on a line +uint8_t st7565_max_chars(void); + +// Returns the maximum number of lines that will fit on the display +uint8_t st7565_max_lines(void); +``` -- cgit v1.2.3 From a0959f1b3393d284b3aa11162497e8851fd94bca Mon Sep 17 00:00:00 2001 From: Simon Arlott <70171+nomis@users.noreply.github.com> Date: Wed, 16 Jun 2021 05:00:37 +0100 Subject: Add asym_eager_defer_pk debounce type (#12689) --- docs/feature_debounce_type.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/feature_debounce_type.md b/docs/feature_debounce_type.md index 3ad74224c1..306185fe83 100644 --- a/docs/feature_debounce_type.md +++ b/docs/feature_debounce_type.md @@ -121,16 +121,16 @@ DEBOUNCE_TYPE = Where name of algorithm is one of: * ```sym_defer_g``` - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occurred, all input changes are pushed. * This is the current default algorithm. This is the highest performance algorithm with lowest memory usage, and it's also noise-resistant. -* ```sym_eager_pr``` - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row. +* ```sym_eager_pr``` - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row. For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use. * ```sym_eager_pk``` - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key * ```sym_defer_pk``` - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key status change is pushed. +* ```asym_eager_defer_pk``` - debouncing per key. On a key-down state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key. On a key-up state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key-up status change is pushed. ### A couple algorithms that could be implemented in the future: * ```sym_defer_pr``` * ```sym_eager_g``` -* ```asym_eager_defer_pk``` ### Use your own debouncing code You have the option to implement you own debouncing algorithm. To do this: -- cgit v1.2.3 From 172e6a703041363decd6fc829542f33180c13beb Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Fri, 18 Jun 2021 09:10:06 +1000 Subject: Extensible split data sync (#11930) * Extensible split data sync capability through transactions. - Split common transport has been split up between the transport layer and data layer. - Split "transactions" model used, with convergence between I2C and serial data definitions. - Slave matrix "generation count" is used to determine if the full slave matrix needs to be retrieved. - Encoders get the same "generation count" treatment. - All other blocks of data are synchronised when a change is detected. - All transmissions have a globally-configurable deadline before a transmission is forced (`FORCED_SYNC_THROTTLE_MS`, default 100ms). - Added atomicity for all core-synced data, preventing partial updates - Added retries to AVR i2c_master's i2c_start, to minimise the number of failed transactions when interrupts are disabled on the slave due to atomicity checks. - Some keyboards have had slight modifications made in order to ensure that they still build due to firmware size restrictions. * Fixup LED_MATRIX compile. * Parameterise ERROR_DISCONNECT_COUNT. --- docs/config_options.md | 26 +++++++++- docs/feature_split_keyboard.md | 114 +++++++++++++++++++++++++++++++++++++---- 2 files changed, 128 insertions(+), 12 deletions(-) (limited to 'docs') diff --git a/docs/config_options.md b/docs/config_options.md index 26fe8cea55..980195ac68 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -274,7 +274,7 @@ There are a few different ways to set handedness for split keyboards (listed in ### Other Options * `#define USE_I2C` - * For using I2C instead of Serial (defaults to serial) + * For using I2C instead of Serial (default is serial; serial transport is supported on ARM -- I2C is AVR-only) * `#define SOFT_SERIAL_PIN D0` * When using serial, define this. `D0` or `D1`,`D2`,`D3`,`E6`. @@ -303,7 +303,7 @@ There are a few different ways to set handedness for split keyboards (listed in * `#define SPLIT_USB_DETECT` * Detect (with timeout) USB connection when delegating master/slave * Default behavior for ARM - * Required for AVR Teensy + * Required for AVR Teensy (without hardware mods) * `#define SPLIT_USB_TIMEOUT 2000` * Maximum timeout when detecting master/slave when using `SPLIT_USB_DETECT` @@ -311,6 +311,28 @@ There are a few different ways to set handedness for split keyboards (listed in * `#define SPLIT_USB_TIMEOUT_POLL 10` * Poll frequency when detecting master/slave when using `SPLIT_USB_DETECT` +* `#define FORCED_SYNC_THROTTLE_MS 100` + * Deadline for synchronizing data from master to slave when using the QMK-provided split transport. + +* `#define SPLIT_TRANSPORT_MIRROR` + * Mirrors the master-side matrix on the slave when using the QMK-provided split transport. + +* `#define SPLIT_LAYER_STATE_ENABLE` + * Ensures the current layer state is available on the slave when using the QMK-provided split transport. + +* `#define SPLIT_LED_STATE_ENABLE` + * Ensures the current host indicator state (caps/num/scroll) is available on the slave when using the QMK-provided split transport. + +* `#define SPLIT_MODS_ENABLE` + * Ensures the current modifier state (normal, weak, and oneshot) is available on the slave when using the QMK-provided split transport. + +* `#define SPLIT_WPM_ENABLE` + * Ensures the current WPM is available on the slave when using the QMK-provided split transport. + +* `#define SPLIT_TRANSACTION_IDS_KB .....` +* `#define SPLIT_TRANSACTION_IDS_USER .....` + * Allows for custom data sync with the slave when using the QMK-provided split transport. See [custom data sync between sides](feature_split_keyboard.md#custom-data-sync) for more information. + # 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. diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md index 4ebf585f5c..603c387c2d 100644 --- a/docs/feature_split_keyboard.md +++ b/docs/feature_split_keyboard.md @@ -8,8 +8,7 @@ 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 fully supported for Split Keyboards and has many limitations. Progress is being made, but we have not yet reached 100% feature parity. - +!> ARM split supports most QMK subsystems when using the 'serial' and 'serial_usart' drivers. I2C slave is currently unsupported. ## Compatibility Overview @@ -169,7 +168,7 @@ Because not every split keyboard is identical, there are a number of additional #define USE_I2C ``` -This enables I2C support for split keyboards. This isn't strictly for communication, but can be used for OLED or other I2C-based devices. +This configures the use of I2C support for split keyboard transport (AVR only). ```c #define SOFT_SERIAL_PIN D0 @@ -193,20 +192,115 @@ If you're having issues with serial communication, you can change this value, as * **`5`**: about 20kbps ```c -#define SPLIT_MODS_ENABLE +#define FORCED_SYNC_THROTTLE_MS 100 ``` -This enables transmitting modifier state (normal, weak and oneshot) to the non -primary side of the split keyboard. This adds a few bytes of data to the split -communication protocol and may impact the matrix scan speed when enabled. -The purpose of this feature is to support cosmetic use of modifer state (e.g. -displaying status on an OLED screen). +This sets the maximum number of milliseconds before forcing a synchronization of data from master to slave. Under normal circumstances this sync occurs whenever the data _changes_, for safety a data transfer occurs after this number of milliseconds if no change has been detected since the last sync. ```c #define SPLIT_TRANSPORT_MIRROR ``` -This mirrors the master side matrix to the slave side for features that react or require knowledge of master side key presses on the slave side. This adds a few bytes of data to the split communication protocol and may impact the matrix scan speed when enabled. The purpose of this feature is to support cosmetic use of key events (e.g. RGB reacting to Keypresses). +This mirrors the master side matrix to the slave side for features that react or require knowledge of master side key presses on the slave side. The purpose of this feature is to support cosmetic use of key events (e.g. RGB reacting to keypresses). This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled. + +```c +#define SPLIT_LAYER_STATE_ENABLE +``` + +This enables syncing of the layer state between both halves of the split keyboard. The main purpose of this feature is to enable support for use of things like OLED display of the currently active layer. This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled. + +```c +#define SPLIT_LED_STATE_ENABLE +``` + +This enables syncing of the Host LED status (caps lock, num lock, etc) between both halves of the split keyboard. The main purpose of this feature is to enable support for use of things like OLED display of the Host LED status. This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled. + +```c +#define SPLIT_MODS_ENABLE +``` + +This enables transmitting modifier state (normal, weak and oneshot) to the non primary side of the split keyboard. The purpose of this feature is to support cosmetic use of modifer state (e.g. displaying status on an OLED screen). This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled. + +```c +#define SPLIT_WPM_ENABLE +``` + +This enables transmitting the current WPM to the slave side of the split keyboard. The purpose of this feature is to support cosmetic use of WPM (e.g. displaying the current value on an OLED screen). This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled. + +### Custom data sync between sides :id=custom-data-sync + +QMK's split transport allows for arbitrary data transactions at both the keyboard and user levels. This is modelled on a remote procedure call, with the master invoking a function on the slave side, with the ability to send data from master to slave, process it slave side, and send data back from slave to master. + +To leverage this, a keyboard or user/keymap can define a comma-separated list of _transaction IDs_: + +```c +// for keyboard-level data sync: +#define SPLIT_TRANSACTION_IDS_KB KEYBOARD_SYNC_A, KEYBOARD_SYNC_B +// or, for user: +#define SPLIT_TRANSACTION_IDS_USER USER_SYNC_A, USER_SYNC_B, USER_SYNC_C +``` + +These _transaction IDs_ then need a slave-side handler function to be registered with the split transport, for example: + +```c +typedef struct _master_to_slave_t { + int m2s_data; +} master_to_slave_t; + +typedef struct _slave_to_master_t { + int s2m_data; +} slave_to_master_t; + +void user_sync_a_slave_handler(uint8_t in_buflen, const void* in_data, uint8_t out_buflen, void* out_data) { + const master_to_slave_t *m2s = (const master_to_slave_t*)in_data; + slave_to_master_t *s2m = (slave_to_master_t*)out_data; + s2m->s2m_data = m2s->m2s_data + 5; // whatever comes in, add 5 so it can be sent back +} + +void keyboard_post_init_user(void) { + transaction_register_rpc(USER_SYNC_A, user_sync_a_slave_handler); +} +``` + +The master side can then invoke the slave-side handler - for normal keyboard functionality to be minimally affected, any keyboard- or user-level code attempting to sync data should be throttled: + +```c +void housekeeping_task_user(void) { + if (is_keyboard_master()) { + // Interact with slave every 500ms + static uint32_t last_sync = 0; + if (timer_elapsed32(last_sync) > 500) { + master_to_slave_t m2s = {6}; + slave_to_master_t s2m = {0}; + if(transaction_rpc_exec(USER_SYNC_A, sizeof(m2s), &m2s, sizeof(s2m), &s2m)) { + last_sync = timer_read32(); + dprintf("Slave value: %d\n", s2m.s2m_data); // this will now be 11, as the slave adds 5 + } else { + dprint("Slave sync failed!\n"); + } + } + } +} +``` + +!> It is recommended that any data sync between halves happens during the master side's _housekeeping task_. This ensures timely retries should failures occur. + +If only one-way data transfer is needed, helper methods are provided: + +```c +bool transaction_rpc_exec(int8_t transaction_id, uint8_t initiator2target_buffer_size, const void *initiator2target_buffer, uint8_t target2initiator_buffer_size, void *target2initiator_buffer); +bool transaction_rpc_send(int8_t transaction_id, uint8_t initiator2target_buffer_size, const void *initiator2target_buffer); +bool transaction_rpc_recv(int8_t transaction_id, uint8_t target2initiator_buffer_size, void *target2initiator_buffer); +``` + +By default, the inbound and outbound data is limited to a maximum of 32 bytes each. The sizes can be altered if required: + +```c +// Master to slave: +#define RPC_M2S_BUFFER_SIZE 48 +// Slave to master: +#define RPC_S2M_BUFFER_SIZE 48 +``` ### Hardware Configuration Options -- cgit v1.2.3 From 0311c8036d693baf63ed4d3b7badf4257ffd5f46 Mon Sep 17 00:00:00 2001 From: Ignaz Kevenaar Date: Fri, 18 Jun 2021 17:08:22 +0200 Subject: Add oled_invert (#13172) Co-authored-by: Drashna Jaelre --- docs/feature_oled_driver.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/feature_oled_driver.md b/docs/feature_oled_driver.md index f3b659b1bc..c90aabb9c6 100644 --- a/docs/feature_oled_driver.md +++ b/docs/feature_oled_driver.md @@ -346,6 +346,10 @@ bool oled_scroll_left(void); // Returns true if the screen was not scrolling or stops scrolling bool oled_scroll_off(void); +// Inverts the display +// Returns true if the screen was or is inverted +bool oled_invert(bool invert); + // Returns the maximum number of characters that will fit on a line uint8_t oled_max_chars(void); -- cgit v1.2.3 From 37fba09021fe094ea4daf0813626b1b6a201c8c0 Mon Sep 17 00:00:00 2001 From: Ryan Date: Sat, 19 Jun 2021 18:51:35 +1000 Subject: ST7565 invert (#13237) --- docs/feature_st7565.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/feature_st7565.md b/docs/feature_st7565.md index 7db0f9ac4a..de3e44d8e9 100644 --- a/docs/feature_st7565.md +++ b/docs/feature_st7565.md @@ -262,6 +262,10 @@ void st7565_task(void); // Called at the start of st7565_task, weak function overridable by the user void st7565_task_user(void); +// Inverts the display +// Returns true if the screen was or is inverted +bool st7565_invert(bool invert); + // Returns the maximum number of characters that will fit on a line uint8_t st7565_max_chars(void); -- cgit v1.2.3 From e4c5b1bbbb3d76a7632c8a9d5c19c5eb8a9a4e1f Mon Sep 17 00:00:00 2001 From: Roland Huber <36362570+darkcruix@users.noreply.github.com> Date: Sun, 20 Jun 2021 04:28:54 +0200 Subject: Add Per Key exclusions for Haptic Feedback (#12386) Co-authored-by: Drashna Jaelre --- docs/feature_haptic_feedback.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_haptic_feedback.md b/docs/feature_haptic_feedback.md index a092e784c7..469c9c7981 100644 --- a/docs/feature_haptic_feedback.md +++ b/docs/feature_haptic_feedback.md @@ -162,4 +162,28 @@ 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. +This mode sets continuous haptic feedback with the option to increase or decrease strength. + +## Haptic Key Exclusion +The Haptic Exclusion is implemented as `__attribute__((weak)) bool get_haptic_enabled_key(uint16_t keycode, keyrecord_t *record)` in haptic.c. This allows a re-definition at the required level with the specific requirement / exclusion. + +### NO_HAPTIC_MOD +With the entry of `#define NO_HAPTIC_MOD` in config.h, modifiers from Left Control to Right GUI will not trigger a feedback. This also includes modifiers in a Mod Tap configuration. + +### NO_HAPTIC_FN +With the entry of `#define NO_HAPTIC_FN` in config.h, layer keys will not rigger a feedback. + +### NO_HAPTIC_ALPHA +With the entry of `#define NO_HAPTIC_ALPHA` in config.h, none of the alpha keys (A ... Z) will trigger a feedback. + +### NO_HAPTIC_PUNCTUATION +With the entry of `#define NO_HAPTIC_PUNCTUATION` in config.h, none of the following keys will trigger a feedback: Enter, ESC, Backspace, Space, Minus, Equal, Left Bracket, Right Bracket, Backslash, Non-US Hash, Semicolon, Quote, Grave, Comma, Slash, Dot, Non-US Backslash. + +### NO_HAPTIC_LOCKKEYS +With the entry of `#define NO_HAPTIC_LOCKKEYS` in config.h, none of the following keys will trigger a feedback: Caps Lock, Scroll Lock, Num Lock. + +### NO_HAPTIC_NAV +With the entry of `#define NO_HAPTIC_NAV` in config.h, none of the following keys will trigger a feedback: Print Screen, Pause, Insert, Delete, Page Down, Page Up, Left Arrow, Up Arrow, Right Arrow, Down Arrow, End, Home. + +### NO_HAPTIC_NUMERIC +With the entry of `#define NO_HAPTIC_NUMERIC` in config.h, none of the following keys between 0 and 9 (KC_1 ... KC_0) will trigger a feedback. \ No newline at end of file -- cgit v1.2.3 From dd16d3cc7e427c5256f5d2089d0cc2b6bbc776e1 Mon Sep 17 00:00:00 2001 From: Purdea Andrei Date: Tue, 22 Jun 2021 05:34:28 +0300 Subject: eeprom_i2c driver: added EXTERNAL_EEPROM_WP_PIN configuration option. (#12617) --- docs/eeprom_driver.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs') diff --git a/docs/eeprom_driver.md b/docs/eeprom_driver.md index e2c262546d..6dcf10c04d 100644 --- a/docs/eeprom_driver.md +++ b/docs/eeprom_driver.md @@ -31,6 +31,9 @@ Currently QMK supports 24xx-series chips over I2C. As such, requires a working i `#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 +`#define EXTERNAL_EEPROM_WP_PIN` | If defined the WP pin will be toggled appropriately when writing to the EEPROM. | _none_ + +Some I2C EEPROM manufacturers explicitly recommend against hardcoding the WP pin to ground. This is in order to protect the eeprom memory content during power-up/power-down/brown-out conditions at low voltage where the eeprom is still operational, but the i2c master output might be unpredictable. If a WP pin is configured, then having an external pull-up on the WP pin is recommended. Default values and extended descriptions can be found in `drivers/eeprom/eeprom_i2c.h`. -- cgit v1.2.3 From 1ea01765e19bf84b9a09954443b7d64be2bec0c7 Mon Sep 17 00:00:00 2001 From: Gigahawk Date: Wed, 23 Jun 2021 02:57:46 -0700 Subject: Allow settable SPI divisor for AW20216 driver, set default to 4 (#13309) --- docs/feature_rgb_matrix.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 25ba3ffe32..925c9de6e4 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -250,6 +250,7 @@ You can use up to 2 AW20216 IC's. Do not specify `DRIVER__xxx` defines for IC | `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | | | `AW_SCALING_MAX` | (Optional) LED current scaling value (0-255, higher values mean LED is brighter at full PWM) | 150 | | `AW_GLOBAL_CURRENT_MAX` | (Optional) Driver global current limit (0-255, higher values means the driver may consume more power) | 150 | +| `AW_SPI_DIVISOR` | (Optional) Clock divisor for SPI communication (powers of 2, smaller numbers means faster communication, should not be less than 4) | 4 | Here is an example using 2 drivers. -- cgit v1.2.3 From cb23fe9fc1fa6e2219380228ae589f3d733ea4e6 Mon Sep 17 00:00:00 2001 From: Ryan Date: Mon, 28 Jun 2021 15:15:24 +1000 Subject: Move RGBLight code into its own folder (#13312) --- docs/cli_commands.md | 2 +- docs/feature_rgblight.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 581342093a..e30593daa9 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -368,7 +368,7 @@ qmk generate-docs ## `qmk generate-rgb-breathe-table` -This command generates a lookup table (LUT) header file for the [RGB Lighting](feature_rgblight.md) feature's breathing animation. Place this file in your keyboard or keymap directory as `rgblight_breathe_table.h` to override the default LUT in `quantum/`. +This command generates a lookup table (LUT) header file for the [RGB Lighting](feature_rgblight.md) feature's breathing animation. Place this file in your keyboard or keymap directory as `rgblight_breathe_table.h` to override the default LUT in `quantum/rgblight/`. **Usage**: diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index 994a014a28..0e75411f09 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -119,7 +119,7 @@ if `RGBLIGHT_EFFECT_xxxx` or `RGBLIGHT_ANIMATIONS` is defined, you also have a n Check out [this video](https://youtube.com/watch?v=VKrpPAHlisY) for a demonstration. -Note: For versions older than 0.6.117, The mode numbers were written directly. In `quantum/rgblight.h` there is a contrast table between the old mode number and the current symbol. +Note: For versions older than 0.6.117, The mode numbers were written directly. In `quantum/rgblight/rgblight.h` there is a contrast table between the old mode number and the current symbol. ### Effect and Animation Toggles @@ -328,7 +328,7 @@ Normally lighting layers are not shown when RGB Lighting is disabled (e.g. with ## 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: +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/rgblight.h) for the full list, but the most commonly used functions include: ### Utility Functions |Function |Description | -- cgit v1.2.3 From 653082235aaca8552078e62714eab30d1a517f57 Mon Sep 17 00:00:00 2001 From: Ryan Date: Wed, 30 Jun 2021 04:15:58 +1000 Subject: Relocate RGB/HSV color defs to a more fitting place (#13377) --- docs/feature_rgb_matrix.md | 45 +++++++++++++++++++++++---------------------- docs/feature_rgblight.md | 43 ++++++++++++++++++++++--------------------- 2 files changed, 45 insertions(+), 43 deletions(-) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 925c9de6e4..4bd8e1eb98 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -554,28 +554,29 @@ For inspiration and examples, check out the built-in effects under `quantum/rgb_ These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions. -|RGB |HSV | -|-------------------|-------------------| -|`RGB_WHITE` |`HSV_WHITE` | -|`RGB_RED` |`HSV_RED` | -|`RGB_CORAL` |`HSV_CORAL` | -|`RGB_ORANGE` |`HSV_ORANGE` | -|`RGB_GOLDENROD` |`HSV_GOLDENROD` | -|`RGB_GOLD` |`HSV_GOLD` | -|`RGB_YELLOW` |`HSV_YELLOW` | -|`RGB_CHARTREUSE` |`HSV_CHARTREUSE` | -|`RGB_GREEN` |`HSV_GREEN` | -|`RGB_SPRINGGREEN` |`HSV_SPRINGGREEN` | -|`RGB_TURQUOISE` |`HSV_TURQUOISE` | -|`RGB_TEAL` |`HSV_TEAL` | -|`RGB_CYAN` |`HSV_CYAN` | -|`RGB_AZURE` |`HSV_AZURE` | -|`RGB_BLUE` |`HSV_BLUE` | -|`RGB_PURPLE` |`HSV_PURPLE` | -|`RGB_MAGENTA` |`HSV_MAGENTA` | -|`RGB_PINK` |`HSV_PINK` | - -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! +|RGB |HSV | +|---------------------|---------------------| +|`RGB_AZURE` |`HSV_AZURE` | +|`RGB_BLACK`/`RGB_OFF`|`HSV_BLACK`/`HSV_OFF`| +|`RGB_BLUE` |`HSV_BLUE` | +|`RGB_CHARTREUSE` |`HSV_CHARTREUSE` | +|`RGB_CORAL` |`HSV_CORAL` | +|`RGB_CYAN` |`HSV_CYAN` | +|`RGB_GOLD` |`HSV_GOLD` | +|`RGB_GOLDENROD` |`HSV_GOLDENROD` | +|`RGB_GREEN` |`HSV_GREEN` | +|`RGB_MAGENTA` |`HSV_MAGENTA` | +|`RGB_ORANGE` |`HSV_ORANGE` | +|`RGB_PINK` |`HSV_PINK` | +|`RGB_PURPLE` |`HSV_PURPLE` | +|`RGB_RED` |`HSV_RED` | +|`RGB_SPRINGGREEN` |`HSV_SPRINGGREEN` | +|`RGB_TEAL` |`HSV_TEAL` | +|`RGB_TURQUOISE` |`HSV_TURQUOISE` | +|`RGB_WHITE` |`HSV_WHITE` | +|`RGB_YELLOW` |`HSV_YELLOW` | + +These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/color.h). Feel free to add to this list! ## Additional `config.h` Options :id=additional-configh-options diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index 0e75411f09..d323dee4f7 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -449,26 +449,27 @@ rgblight_sethsv_at(HSV_GREEN, 2); // led 2 These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions. -|RGB |HSV | -|-------------------|-------------------| -|`RGB_WHITE` |`HSV_WHITE` | -|`RGB_RED` |`HSV_RED` | -|`RGB_CORAL` |`HSV_CORAL` | -|`RGB_ORANGE` |`HSV_ORANGE` | -|`RGB_GOLDENROD` |`HSV_GOLDENROD` | -|`RGB_GOLD` |`HSV_GOLD` | -|`RGB_YELLOW` |`HSV_YELLOW` | -|`RGB_CHARTREUSE` |`HSV_CHARTREUSE` | -|`RGB_GREEN` |`HSV_GREEN` | -|`RGB_SPRINGGREEN` |`HSV_SPRINGGREEN` | -|`RGB_TURQUOISE` |`HSV_TURQUOISE` | -|`RGB_TEAL` |`HSV_TEAL` | -|`RGB_CYAN` |`HSV_CYAN` | -|`RGB_AZURE` |`HSV_AZURE` | -|`RGB_BLUE` |`HSV_BLUE` | -|`RGB_PURPLE` |`HSV_PURPLE` | -|`RGB_MAGENTA` |`HSV_MAGENTA` | -|`RGB_PINK` |`HSV_PINK` | +|RGB |HSV | +|---------------------|---------------------| +|`RGB_AZURE` |`HSV_AZURE` | +|`RGB_BLACK`/`RGB_OFF`|`HSV_BLACK`/`HSV_OFF`| +|`RGB_BLUE` |`HSV_BLUE` | +|`RGB_CHARTREUSE` |`HSV_CHARTREUSE` | +|`RGB_CORAL` |`HSV_CORAL` | +|`RGB_CYAN` |`HSV_CYAN` | +|`RGB_GOLD` |`HSV_GOLD` | +|`RGB_GOLDENROD` |`HSV_GOLDENROD` | +|`RGB_GREEN` |`HSV_GREEN` | +|`RGB_MAGENTA` |`HSV_MAGENTA` | +|`RGB_ORANGE` |`HSV_ORANGE` | +|`RGB_PINK` |`HSV_PINK` | +|`RGB_PURPLE` |`HSV_PURPLE` | +|`RGB_RED` |`HSV_RED` | +|`RGB_SPRINGGREEN` |`HSV_SPRINGGREEN` | +|`RGB_TEAL` |`HSV_TEAL` | +|`RGB_TURQUOISE` |`HSV_TURQUOISE` | +|`RGB_WHITE` |`HSV_WHITE` | +|`RGB_YELLOW` |`HSV_YELLOW` | ```c rgblight_setrgb(RGB_ORANGE); @@ -477,7 +478,7 @@ rgblight_setrgb_at(RGB_GOLD, 3); rgblight_sethsv_range(HSV_WHITE, 0, 6); ``` -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! +These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/color.h). Feel free to add to this list! ## Changing the order of the LEDs -- cgit v1.2.3 From 8bb231aa1c40a7c6b6fdd229e88ef79c3fa930e2 Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Wed, 30 Jun 2021 10:07:40 +1000 Subject: Adds support for STM32L412xB, STM32L422xB. (#13383) * Adds support for STM32L412xB, STM32L422xB. * Add to list of supported MCUs. * Disable SPI1 by default. --- docs/compatible_microcontrollers.md | 2 ++ docs/ja/compatible_microcontrollers.md | 2 ++ 2 files changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md index 0f5b140de0..865b29feec 100644 --- a/docs/compatible_microcontrollers.md +++ b/docs/compatible_microcontrollers.md @@ -31,6 +31,8 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s * [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html) * [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html) * [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html) + * [STM32L412](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html) + * [STM32L422](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html) * [STM32L433](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html) * [STM32L443](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html) diff --git a/docs/ja/compatible_microcontrollers.md b/docs/ja/compatible_microcontrollers.md index b675b038d2..761a4cda46 100644 --- a/docs/ja/compatible_microcontrollers.md +++ b/docs/ja/compatible_microcontrollers.md @@ -36,6 +36,8 @@ QMK は十分な容量のフラッシュメモリを備えた USB 対応 AVR ま * [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html) * [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html) * [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html) +* [STM32L412](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html) +* [STM32L422](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html) * [STM32L433](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html) * [STM32L443](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html) -- cgit v1.2.3 From 0bde920817ef458f2ad61a66ce76a2535bbc261b Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Thu, 1 Jul 2021 08:22:21 -0700 Subject: Convert Dip Switch callbacks to boolean functions (#13399) --- docs/feature_dip_switch.md | 16 ++++++++++------ docs/ja/feature_dip_switch.md | 16 ++++++++++------ 2 files changed, 20 insertions(+), 12 deletions(-) (limited to 'docs') diff --git a/docs/feature_dip_switch.md b/docs/feature_dip_switch.md index 15e449c4c4..5e8c19bfa7 100644 --- a/docs/feature_dip_switch.md +++ b/docs/feature_dip_switch.md @@ -23,8 +23,9 @@ or The callback functions can be inserted into your `.c`: ```c -void dip_switch_update_kb(uint8_t index, bool active) { - dip_switch_update_user(index, active); +bool dip_switch_update_kb(uint8_t index, bool active) { + if !(dip_switch_update_user(index, active)) { return false; } + return true; } ``` @@ -32,7 +33,7 @@ void dip_switch_update_kb(uint8_t index, bool active) { or `keymap.c`: ```c -void dip_switch_update_user(uint8_t index, bool active) { +bool dip_switch_update_user(uint8_t index, bool active) { switch (index) { case 0: if(active) { audio_on(); } else { audio_off(); } @@ -57,6 +58,7 @@ void dip_switch_update_user(uint8_t index, bool active) { } break; } + return true; } ``` @@ -64,8 +66,9 @@ Additionally, we support bit mask functions which allow for more complex handlin ```c -void dip_switch_update_mask_kb(uint32_t state) { - dip_switch_update_mask_user(state); +bool dip_switch_update_mask_kb(uint32_t state) { + if (!dip_switch_update_mask_user(state)) { return false; } + return true; } ``` @@ -73,7 +76,7 @@ void dip_switch_update_mask_kb(uint32_t state) { or `keymap.c`: ```c -void dip_switch_update_mask_user(uint32_t state) { +bool dip_switch_update_mask_user(uint32_t state) { if (state & (1UL<<0) && state & (1UL<<1)) { layer_on(_ADJUST); // C on esc } else { @@ -89,6 +92,7 @@ void dip_switch_update_mask_user(uint32_t state) { } else { layer_off(_TEST_B); } + return true; } ``` diff --git a/docs/ja/feature_dip_switch.md b/docs/ja/feature_dip_switch.md index a0f6aeb003..a5436779f1 100644 --- a/docs/ja/feature_dip_switch.md +++ b/docs/ja/feature_dip_switch.md @@ -28,8 +28,9 @@ DIP スイッチは、以下を `rules.mk` に追加することでサポート コールバック関数を `.c` に記述することができます: ```c -void dip_switch_update_kb(uint8_t index, bool active) { - dip_switch_update_user(index, active); +bool dip_switch_update_kb(uint8_t index, bool active) { + if !(dip_switch_update_user(index, active)) { return false; } + return true; } ``` @@ -37,7 +38,7 @@ void dip_switch_update_kb(uint8_t index, bool active) { あるいは `keymap.c` に記述することもできます: ```c -void dip_switch_update_user(uint8_t index, bool active) { +bool dip_switch_update_user(uint8_t index, bool active) { switch (index) { case 0: if(active) { audio_on(); } else { audio_off(); } @@ -62,6 +63,7 @@ void dip_switch_update_user(uint8_t index, bool active) { } break; } + return true; } ``` @@ -69,8 +71,9 @@ void dip_switch_update_user(uint8_t index, bool active) { ```c -void dip_switch_update_mask_kb(uint32_t state) { - dip_switch_update_mask_user(state); +bool dip_switch_update_mask_kb(uint32_t state) { + if (!dip_switch_update_mask_user(state)) { return false; } + return true; } ``` @@ -78,7 +81,7 @@ void dip_switch_update_mask_kb(uint32_t state) { あるいは `keymap.c` に記述することもできます: ```c -void dip_switch_update_mask_user(uint32_t state) { +bool dip_switch_update_mask_user(uint32_t state) { if (state & (1UL<<0) && state & (1UL<<1)) { layer_on(_ADJUST); // C on esc } else { @@ -94,6 +97,7 @@ void dip_switch_update_mask_user(uint32_t state) { } else { layer_off(_TEST_B); } + return true; } ``` -- cgit v1.2.3 From 117bff17ba89a70dd85163b499c262b879f52afd Mon Sep 17 00:00:00 2001 From: Stefan Kerkmann Date: Fri, 2 Jul 2021 00:24:08 +0200 Subject: [Core] Unite half-duplex and full-duplex serial drivers (#13081) * Unite half-duplex and full-duplex serial driver. * Add full duplex operation mode to the interrupt based driver * Delete DMA UART based full duplex driver * The new driver targets #11930 * Fix freezes with failing transactions in half-duplex * Increase default serial TX/RX buffer size to 128 bytes * Correctly use bool instead of size_t Co-authored-by: Nick Brassel --- docs/serial_driver.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/serial_driver.md b/docs/serial_driver.md index 359fc59551..ed989b0a15 100644 --- a/docs/serial_driver.md +++ b/docs/serial_driver.md @@ -73,7 +73,7 @@ You must also enable the ChibiOS `SERIAL` feature: Do note that the configuration required is for the `SERIAL` peripheral, not the `UART` peripheral. ### USART Full-duplex -Targeting STM32 boards where communication is offloaded to a USART hardware device. The advantage over bitbang is that this provides fast and accurate timings. USART Full-Duplex requires two conductors **without** pull-up resistors instead of one conductor with a pull-up resistor unlike the Half-duplex driver, but it is more efficent as it uses DMA transfers, which can result in even faster transmission speeds. +Targeting STM32 boards where communication is offloaded to a USART hardware device. The advantage over bitbang is that this provides fast and accurate timings. USART Full-Duplex requires two conductors **without** pull-up resistors instead of one conductor with a pull-up resistor unlike the Half-duplex driver. Due to its internal design it is more efficent, which can result in even faster transmission speeds. #### Pin configuration @@ -86,12 +86,13 @@ Please note that `TX` of the master half has to be connected with the `RX` pin o To use the driver, add this to your rules.mk: ```make -SERIAL_DRIVER = usart_duplex +SERIAL_DRIVER = usart ``` Next configure the hardware via your config.h: ```c +#define SERIAL_USART_FULL_DUPLEX // Enable full duplex operation mode. #define SERIAL_USART_TX_PIN B6 // USART TX pin #define SERIAL_USART_RX_PIN B7 // USART RX pin //#define USART1_REMAP // Remap USART TX and RX pins on STM32F103 MCUs, see table below. @@ -104,17 +105,17 @@ Next configure the hardware via your config.h: // 3: 57600 baud // 4: 38400 baud // 5: 19200 baud -#define SERIAL_USART_DRIVER UARTD1 // USART driver of TX and RX pin. default: UARTD1 +#define SERIAL_USART_DRIVER SD1 // USART driver of TX and RX pin. default: SD1 #define SERIAL_USART_TX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7 #define SERIAL_USART_RX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7 #define SERIAL_USART_TIMEOUT 100 // USART driver timeout. default 100 ``` -You must also enable the ChibiOS `UART` with blocking api feature: -* In your board's halconf.h: `#define HAL_USE_UART TRUE` and `#define UART_USE_WAIT TRUE` -* In your board's mcuconf.h: `#define STM32_UART_USE_USARTn TRUE` (where 'n' matches the peripheral number of your selected USART on the MCU) +You must also enable the ChibiOS `SERIAL` feature: +* In your board's halconf.h: `#define HAL_USE_SERIAL TRUE` +* In your board's mcuconf.h: `#define STM32_SERIAL_USE_USARTn TRUE` (where 'n' matches the peripheral number of your selected USART on the MCU) -Do note that the configuration required is for the `UART` peripheral, not the `SERIAL` peripheral. +Do note that the configuration required is for the `SERIAL` peripheral, not the `UART` peripheral. #### Pins for USART Peripherals with Alternate Functions for selected STM32 MCUs -- cgit v1.2.3 From 550d9253b03c4273065b212d0b856a9ad07132df Mon Sep 17 00:00:00 2001 From: Jameson Thatcher Date: Mon, 5 Jul 2021 00:06:40 +0100 Subject: Allow invert of SPLIT_HAND_PIN logic (#13433) * added support for inverting the hand pin for split keyboards * Added docs about SPLIT_HAND_LOW_IS_LEFT * Update docs/feature_split_keyboard.md bring #define for split hand pin low for left half name in line with grid pin define Co-authored-by: Joel Challis * Update quantum/split_common/split_util.c update split hand pin low is left name to match split hand grid define Co-authored-by: Joel Challis Co-authored-by: Joel Challis --- docs/feature_split_keyboard.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md index 603c387c2d..428d581cab 100644 --- a/docs/feature_split_keyboard.md +++ b/docs/feature_split_keyboard.md @@ -89,7 +89,13 @@ You can configure the firmware to read a pin on the controller to determine hand #define SPLIT_HAND_PIN B7 ``` -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. +This will read the specified pin. By default, 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. + +This behaviour can be flipped by adding this to you `config.h` file: + +```c +#define SPLIT_HAND_PIN_LOW_IS_LEFT +``` #### Handedness by Matrix Pin -- cgit v1.2.3 From 9c74fd14bc9777ec45cc93fa57bf83ab17b988db Mon Sep 17 00:00:00 2001 From: Chris Cullin Date: Tue, 13 Jul 2021 01:51:23 +1000 Subject: Enable g_is31_leds PROGMEM for RGB Matrix IS31FL3737 driver (#13480) --- docs/feature_rgb_matrix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 675b7a1be0..be763ee025 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -171,7 +171,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 -const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { +const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = { /* Refer to IS31 manual for these locations * driver * | R location -- cgit v1.2.3 From 52cfc9259b58a3a11a244fbe35c49c7dd1a9cae0 Mon Sep 17 00:00:00 2001 From: Jonas Gessner Date: Tue, 13 Jul 2021 19:13:51 +0200 Subject: [Feature] Key Overrides (#11422) --- docs/_summary.md | 1 + docs/config_options.md | 4 + docs/feature_key_overrides.md | 229 ++++++++++++++++++++++++++++++++++++++++++ docs/syllabus.md | 1 + docs/understanding_qmk.md | 1 + 5 files changed, 236 insertions(+) create mode 100644 docs/feature_key_overrides.md (limited to 'docs') diff --git a/docs/_summary.md b/docs/_summary.md index 4141e01e77..6c39aeda09 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -77,6 +77,7 @@ * [Combos](feature_combo.md) * [Debounce API](feature_debounce_type.md) * [Key Lock](feature_key_lock.md) + * [Key Overrides](feature_key_overrides.md) * [Layers](feature_layers.md) * [One Shot Keys](one_shot_keys.md) * [Pointing Device](feature_pointing_device.md) diff --git a/docs/config_options.md b/docs/config_options.md index 980195ac68..0c98b31010 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -195,6 +195,8 @@ If you define these options you will enable the associated feature, which may in * Sets the delay between `register_code` and `unregister_code`, if you're having issues with it registering properly (common on VUSB boards). The value is in milliseconds. * `#define TAP_HOLD_CAPS_DELAY 80` * Sets the delay for Tap Hold keys (`LT`, `MT`) when using `KC_CAPSLOCK` keycode, as this has some special handling on MacOS. The value is in milliseconds, and defaults to 80 ms if not defined. For macOS, you may want to set this to 200 or higher. +* `#define KEY_OVERRIDE_REPEAT_DELAY 500` + * Sets the key repeat interval for [key overrides](feature_key_overrides.md). ## RGB Light Configuration @@ -400,6 +402,8 @@ Use these to enable or disable building certain features. The more you have enab * USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work * `AUDIO_ENABLE` * Enable the audio subsystem. +* `KEY_OVERRIDE_ENABLE` + * Enable the key override feature * `RGBLIGHT_ENABLE` * Enable keyboard underlight functionality * `LEADER_ENABLE` diff --git a/docs/feature_key_overrides.md b/docs/feature_key_overrides.md new file mode 100644 index 0000000000..861c4bef5d --- /dev/null +++ b/docs/feature_key_overrides.md @@ -0,0 +1,229 @@ +# Key Overrides + +Key overrides allow you to override modifier-key combinations to send a different modifier-key combination or perform completely custom actions. Don't want `shift` + `1` to type `!` on your computer? Use a key override to make your keyboard type something different when you press `shift` + `1`. The general behavior is like this: If `modifiers w` + `key x` are pressed, replace these keys with `modifiers y` + `key z` in the keyboard report. + +You can use key overrides in a similar way to momentary layer/fn keys to activate custom keycodes/shortcuts, with a number of benefits: You completely keep the original use of the modifier keys, while being able to save space by removing fn keys from your keyboard. You can also easily configure _combinations of modifiers_ to trigger different actions than individual modifiers, and much more. The possibilities are quite vast and this documentation contains a few examples for inspiration throughout. + +##### A few more examples to get started: You could use key overrides to... +- Send `brightness up/down` when pressing `ctrl` + `volume up/down`. +- Send `delete` when pressing `shift` + `backspace`. +- Create custom shortcuts or change existing ones: E.g. Send `ctrl`+`shift`+`z` when `ctrl`+`y` is pressed. +- Run custom code when `ctrl` + `alt` + `esc` is pressed. + +## Setup + +To enable this feature, you need to add `KEY_OVERRIDE_ENABLE = yes` to your `rules.mk`. + +Then, in your `keymap.c` file, you'll need to define the array `key_overrides`, which defines all key overrides to be used. Each override is a value of type `key_override_t`. The array `key_overrides` is `NULL`-terminated and contains pointers to `key_override_t` values (`const key_override_t **`). + +## Creating Key Overrides + +The `key_override_t` struct has many options that allow you to precisely tune your overrides. The full reference is shown below. Instead of manually creating a `key_override_t` value, it is recommended to use these dedicated initializers: + +#### `ko_make_basic(modifiers, key, replacement)` +Returns a `key_override_t`, which sends `replacement` (can be a key-modifer combination), when `key` and `modifiers` are all pressed down. This override still activates if any additional modifiers not specified in `modifiers` are also pressed down. See `ko_make_with_layers_and_negmods` to customize this behavior. + +#### `ko_make_with_layers(modifiers, key, replacement, layers)` +Additionally takes a bitmask `layers` that defines on which layers the override is used. + +#### `ko_make_with_layers_and_negmods(modifiers, key, replacement, layers, negative_mods)` +Additionally takes a bitmask `negative_mods` that defines which modifiers may not be pressed for this override to activate. + +#### `ko_make_with_layers_negmods_and_options(modifiers, key, replacement, layers, negative_mods, options)` +Additionally takes a bitmask `options` that specifies additional options. See `ko_option_t` for available options. + +For more customization possibilities, you may directly create a `key_override_t`, which allows you to customize even more behavior. Read further below for details and examples. + +## Simple Example + +This shows how the mentioned example of sending `delete` when `shift` + `backspace` are pressed is realized: + +```c +const key_override_t delete_key_override = ko_make_basic(MOD_MASK_SHIFT, KC_BSPACE, KC_DELETE); + +// This globally defines all key overrides to be used +const key_override_t **key_overrides = (const key_override_t *[]){ + &delete_key_override, + NULL // Null terminate the array of overrides! +}; +``` + +## Intermediate Difficulty Examples + +### Media Controls & Screen Brightness + +In this example a single key is configured to control media, volume and screen brightness by using key overrides. + +- The key is set to send `play/pause` in the keymap. + +The following key overrides will be configured: + +- `Ctrl` + `play/pause` will send `next track`. +- `Ctrl` + `Shift` + `play/pause` will send `previous track`. +- `Alt` + `play/pause` will send `volume up`. +- `Alt` + `Shift` + `play/pause` will send `volume down`. +- `Ctrl` + `Alt` + `play/pause` will send `brightness up`. +- `Ctrl` + `Alt` + `Shift` + `play/pause` will send `brightness down`. + + +```c +const key_override_t next_track_override = + ko_make_with_layers_negmods_and_options( + MOD_MASK_CTRL, // Trigger modifiers: ctrl + KC_MPLY, // Trigger key: play/pause + KC_MNXT, // Replacement key + ~0, // Activate on all layers + MOD_MASK_SA, // Do not activate when shift or alt are pressed + ko_option_no_reregister_trigger); // Specifies that the play key is not registered again after lifting ctrl + +const key_override_t prev_track_override = ko_make_with_layers_negmods_and_options(MOD_MASK_CS, KC_MPLY, + KC_MPRV, ~0, MOD_MASK_ALT, ko_option_no_reregister_trigger); + +const key_override_t vol_up_override = ko_make_with_layers_negmods_and_options(MOD_MASK_ALT, KC_MPLY, + KC_VOLU, ~0, MOD_MASK_CS, ko_option_no_reregister_trigger); + +const key_override_t vol_down_override = ko_make_with_layers_negmods_and_options(MOD_MASK_SA, KC_MPLY, + KC_VOLD, ~0, MOD_MASK_CTRL, ko_option_no_reregister_trigger); + +const key_override_t brightness_up_override = ko_make_with_layers_negmods_and_options(MOD_MASK_CA, KC_MPLY, + KC_BRIU, ~0, MOD_MASK_SHIFT, ko_option_no_reregister_trigger); + +const key_override_t brightness_down_override = ko_make_basic(MOD_MASK_CSA, KC_MPLY, KC_BRID); + +// This globally defines all key overrides to be used +const key_override_t **key_overrides = (const key_override_t *[]){ + &next_track_override, + &prev_track_override, + &vol_up_override, + &vol_down_override, + &brightness_up_override, + &brightness_down_override, + NULL +}; +``` + +### Flexible macOS-friendly Grave Escape +The [Grave Escape feature](https://docs.qmk.fm/using-qmk/advanced-keycodes/feature_grave_esc) is limited in its configurability and has [bugs when used on macOS](https://docs.qmk.fm/using-qmk/advanced-keycodes/feature_grave_esc#caveats). Key overrides can be used to achieve a similar functionality as Grave Escape, but with more customization and without bugs on macOS. + +```c +// Shift + esc = ~ +const key_override_t tilde_esc_override = ko_make_basic(MOD_MASK_SHIFT, KC_ESC, S(KC_GRAVE)); + +// GUI + esc = ` +const key_override_t grave_esc_override = ko_make_basic(MOD_MASK_GUI, KC_ESC, KC_GRAVE); + +const key_override_t **key_overrides = (const key_override_t *[]){ + &tilde_esc_override, + &grave_esc_override, + NULL +}; +``` + +In addition to not encountering unexpected bugs on macOS, you can also change the behavior as you wish. Instead setting `GUI` + `ESC` = `` ` `` you may change it to an arbitrary other modifier, for example `Ctrl` + `ESC` = `` ` ``. + +## Advanced Examples +### Modifiers as Layer Keys + +Do you really need a dedicated key to toggle your fn layer? With key overrides, perhaps not. This example shows how you can configure to use `rGUI` + `rAlt` (right GUI and right alt) to access a momentary layer like an fn layer. With this you completely eliminate the need to use a dedicated layer key. Of course the choice of modifier keys can be changed as needed, `rGUI` + `rAlt` is just an example here. + +```c +// This is called when the override activates and deactivates. Enable the fn layer on activation and disable on deactivation +bool momentary_layer(bool key_down, void *layer) { + if (key_down) { + layer_on((uint8_t)(uintptr_t)layer); + } else { + layer_off((uint8_t)(uintptr_t)layer); + } + + return false; +} + +const key_override_t fn_override = {.trigger_mods = MOD_BIT(KC_RGUI) | MOD_BIT(KC_RCTL), // + .layers = ~(1 << LAYER_FN), // + .suppressed_mods = MOD_BIT(KC_RGUI) | MOD_BIT(KC_RCTL), // + .options = ko_option_no_unregister_on_other_key_down, // + .negative_mod_mask = (uint8_t) ~(MOD_BIT(KC_RGUI) | MOD_BIT(KC_RCTL)), // + .custom_action = momentary_layer, // + .context = (void *)LAYER_FN, // + .trigger = KC_NO, // + .replacement = KC_NO, // + .enabled = NULL}; +``` + +## Keycodes + +You can enable, disable and toggle all key overrides on the fly. + +|Keycode |Description |Function Equivalent| +|----------|---------------------------------|--------| +|`KEY_OVERRIDE_ON` |Turns on Key Override feature | `key_override_on(void)`| +|`KEY_OVERRIDE_OFF` |Turns off Key Override feature |`key_override_off(void)`| +|`KEY_OVERRIDE_TOGGLE` |Toggles Key Override feature on and off |`key_override_toggle(void)`| + +## Reference for `key_override_t` + +Advanced users may need more customization than what is offered by the simple `ko_make` initializers. For this, directly create a `key_override_t` value and set all members. Below is a reference for all members of `key_override_t`. + +| Member | Description | +|--------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `uint16_t trigger` | The non-modifier keycode that triggers the override. This keycode, and the necessary modifiers (`trigger_mods`) must be pressed to activate this override. Set this to the keycode of the key that should activate the override. Set to `KC_NO` to require only the necessary modifiers to be pressed and no non-modifier. | +| `uint8_t trigger_mods` | Which mods need to be down for activation. If both sides of a modifier are set (e.g. left ctrl and right ctrl) then only one is required to be pressed (e.g. left ctrl suffices). Use the `MOD_MASK_XXX` and `MOD_BIT()` macros for this. | +| `layer_state_t layers` | This is a BITMASK (!), defining which layers this override applies to. To use this override on layer i set the ith bit `(1 << i)`. | +| `uint8_t negative_mod_mask` | Which modifiers cannot be down. It must hold that `(active_modifiers & negative_mod_mask) == 0`, otherwise the key override will not be activated. An active override will be deactivated once this is no longer true. | +| `uint8_t suppressed_mods` | Modifiers to 'suppress' while the override is active. To suppress a modifier means that even though the modifier key is held down, the host OS sees the modifier as not pressed. Can be used to suppress the trigger modifiers, as a trivial example. | +| `uint16_t replacement` | The complex keycode to send as replacement when this override is triggered. This can be a simple keycode, a key-modifier combination (e.g. `C(KC_A)`), or `KC_NO` (to register no replacement keycode). Use in combination with suppressed_mods to get the correct modifiers to be sent. | +| `ko_option_t options` | Options controlling the behavior of the override, such as what actions are allowed to activate the override. | +| `bool (*custom_action)(bool activated, void *context)` | If not NULL, this function will be called right before the replacement key is registered, along with the provided context and a flag indicating whether the override was activated or deactivated. This function allows you to run some custom actions for specific key overrides. If you return `false`, the replacement key is not registered/unregistered as it would normally. Return `true` to register and unregister the override normally. | +| `void *context` | A context that will be passed to the custom action function. | +| `bool *enabled` | If this points to false this override will not be used. Set to NULL to always have this override enabled. | + +### Reference for `ko_option_t` + +Bitfield with various options controlling the behavior of a key override. + +| Value | Description | +|------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `ko_option_activation_trigger_down` | Allow activating when the trigger key is pressed down. | +| `ko_option_activation_required_mod_down` | Allow activating when a necessary modifier is pressed down. | +| `ko_option_activation_negative_mod_up` | Allow activating when a negative modifier is released. | +| `ko_option_one_mod` | If set, any of the modifiers in `trigger_mods` will be enough to activate the override (logical OR of modifiers). If not set, all the modifiers in `trigger_mods` have to be pressed (logical AND of modifiers). | +| `ko_option_no_unregister_on_other_key_down` | If set, the override will not deactivate when another key is pressed down. Use only if you really know you need this. | +| `ko_option_no_reregister_trigger` | If set, the trigger key will never be registered again after the override is deactivated. | +| `ko_options_default` | The default options used by the `ko_make_xxx` functions | + +## For Advanced Users: Inner Workings + +This section explains how a key override works in detail, explaining where each member of `key_override_t` comes into play. Understanding this is essential to be able to take full advantage of all the options offered by key overrides. + +#### Activation + +When the necessary keys are pressed (`trigger_mods` + `trigger`), the override is 'activated' and the replacement key is registered in the keyboard report (`replacement`), while the `trigger` key is removed from the keyboard report. The trigger modifiers may also be removed from the keyboard report upon activation of an override (`suppressed_mods`). The override will not activate if any of the `negative_modifiers` are pressed. + +Overrides can activate in three different cases: + +1. The trigger key is pressed down and necessary modifiers are already down. +2. A necessary modifier is pressed down, while the trigger key and other necessary modifiers are already down. +3. A negative modifier is released, while all necessary modifiers and the trigger key are already down. + +Use the `option` member to customize which of these events are allowed to activate your overrides (default: all three). + +In any case, a key override can only activate if the `trigger` key is the _last_ non-modifier key that was pressed down. This emulates the behavior of how standard OSes (macOS, Windows, Linux) handle normal key input (to understand: Hold down `a`, then also hold down `b`, then hold down `shift`; `B` will be typed but not `A`). + +#### Deactivation + +An override is 'deactivated' when one of the trigger keys (`trigger_mods`, `trigger`) is lifted, another non-modifier key is pressed down, or one of the `negative_modifiers` is pressed down. When an override deactivates, the `replacement` key is removed from the keyboard report, while the `suppressed_mods` that are still held down are re-added to the keyboard report. By default, the `trigger` key is re-added to the keyboard report if it is still held down and no other non-modifier key has been pressed since. This again emulates the behavior of how standard OSes handle normal key input (To understand: hold down `a`, then also hold down `b`, then also `shift`, then release `b`; `A` will not be typed even though you are holding the `a` and `shift` keys). Use the `option` field `ko_option_no_reregister_trigger` to prevent re-registering the trigger key in all cases. + +#### Key Repeat Delay + +A third way in which standard OS-handling of modifier-key input is emulated in key overrides is with a ['key repeat delay'](https://www.dummies.com/computers/pcs/set-your-keyboards-repeat-delay-and-repeat-rate/). To explain what this is, let's look at how normal keyboard input is handled by mainstream OSes again: If you hold down `a`, followed by `shift`, you will see the letter `a` is first typed, then for a short moment nothing is typed and then repeating `A`s are typed. Take note that, although shift is pressed down just after `a` is pressed, it takes a moment until `A` is typed. This is caused by the aforementioned key repeat delay, and it is a feature that prevents unwanted repeated characters from being typed. + +This applies equally to releasing a modifier: When you hold `shift`, then press `a`, the letter `A` is typed. Now if you release `shift` first, followed by `a` shortly after, you will not see the letter `a` being typed, even though for a short moment of time you were just holding down the key `a`. This is because no modified characters are typed until the key repeat delay has passed. + + This exact behavior is implemented in key overrides as well: If a key override for `shift` + `a` = `b` exists, and `a` is pressed and held, followed by `shift`, you will not immediately see the letter `b` being typed. Instead, this event is deferred for a short moment, until the key repeat delay has passed, measured from the moment when the trigger key (`a`) was pressed down. + +The duration of the key repeat delay is controlled with the `KEY_OVERRIDE_REPEAT_DELAY` macro. Define this value in your `config.h` file to change it. It is 500ms by default. + + +## Difference to Combos + +Note that key overrides are very different from [combos](https://docs.qmk.fm/#/feature_combo). Combos require that you press down several keys almost _at the same time_ and can work with any combination of non-modifier keys. Key overrides work like keyboard shortcuts (e.g. `ctrl` + `z`): They take combinations of _multiple_ modifiers and _one_ non-modifier key to then perform some custom action. Key overrides are implemented with much care to behave just like normal keyboard shortcuts would in regards to the order of pressed keys, timing, and interacton with other pressed keys. There are a number of optional settings that can be used to really fine-tune the behavior of each key override as well. Using key overrides also does not delay key input for regular key presses, which inherently happens in combos and may be undesirable. diff --git a/docs/syllabus.md b/docs/syllabus.md index ec7f66ba78..b33bd9e727 100644 --- a/docs/syllabus.md +++ b/docs/syllabus.md @@ -40,6 +40,7 @@ These topics start to dig into some of the features that QMK supports. You don't * [Tap Dance](feature_tap_dance.md) * [Combos](feature_combo.md) * [Userspace](feature_userspace.md) + * [Key Overrides](feature_key_overrides.md) # Advanced Topics diff --git a/docs/understanding_qmk.md b/docs/understanding_qmk.md index 331b1c893c..e3dd5cb780 100644 --- a/docs/understanding_qmk.md +++ b/docs/understanding_qmk.md @@ -146,6 +146,7 @@ The `process_record()` function itself is deceptively simple, but hidden within * [`bool process_audio(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_audio.c#L19) * [`bool process_steno(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_steno.c#L160) * [`bool process_music(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_music.c#L114) + * [`bool process_key_override(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/5a1b857dea45a17698f6baa7dd1b7a7ea907fb0a/quantum/process_keycode/process_key_override.c#L397) * [`bool process_tap_dance(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_tap_dance.c#L141) * [`bool process_unicode_common(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_unicode_common.c#L169) calls one of: -- cgit v1.2.3 From 70267b35c357f2744262300db03eafe642159734 Mon Sep 17 00:00:00 2001 From: Chris Cullin Date: Fri, 16 Jul 2021 07:52:05 +1000 Subject: Dual RGB Matrix IS31FL3737 driver support to address #13442 (#13457) * initial commit * removed changes to write_pwm_buffer * backward compatbility added * fixed issue with backward compatibility * documentation update * removed unneccessary comment. branched from master * updated per comments #13457 * removed blank line * cformat on diff files --- docs/feature_rgb_matrix.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index be763ee025..f3e25f2f13 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -145,9 +145,22 @@ There is basic support for addressable RGB matrix lighting with the I2C IS31FL37 RGB_MATRIX_ENABLE = yes RGB_MATRIX_DRIVER = IS31FL3737 ``` +You can use between 1 and 2 IS31FL3737 IC's. Do not specify `DRIVER_ADDR_2` define for second IC if not present on your keyboard. Configure the hardware via your `config.h`: +| Variable | Description | Default | +|----------|-------------|---------| +| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | +| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | +| `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | +| `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | | +| `DRIVER_ADDR_1` | (Required) Address for the first RGB driver | | +| `DRIVER_ADDR_2` | (Optional) Address for the second RGB driver | | + + +Here is an example using 2 drivers. + ```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) @@ -159,14 +172,16 @@ Configure the hardware via your `config.h`: // ADDR represents A3:A0 of the 7-bit address. // The result is: 0b101(ADDR) #define DRIVER_ADDR_1 0b1010000 -#define DRIVER_ADDR_2 0b1010000 // this is here for compliancy reasons. +#define DRIVER_ADDR_2 0b1010001 #define DRIVER_COUNT 2 -#define DRIVER_1_LED_TOTAL 64 -#define DRIVER_LED_TOTAL DRIVER_1_LED_TOTAL +#define DRIVER_1_LED_TOTAL 30 +#define DRIVER_2_LED_TOTAL 36 +#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) ``` +!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. -Currently only a single drivers is supported, but it would be trivial to support all 4 combinations. For now define `DRIVER_ADDR_2` as `DRIVER_ADDR_1` +Currently only 2 drivers are supported, but it would be trivial to support all 4 combinations. Define these arrays listing all the LEDs in your `.c`: @@ -183,7 +198,7 @@ const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = { } ``` -Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3737.pdf) and the header file `drivers/issi/is31fl3737.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0` right now). +Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3737.pdf) and the header file `drivers/issi/is31fl3737.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0`, `1` for now). --- -- cgit v1.2.3 From b73a29aaeabe1004423a2ea6180a94a95a1f0d91 Mon Sep 17 00:00:00 2001 From: Xelus22 <17491233+Xelus22@users.noreply.github.com> Date: Tue, 20 Jul 2021 02:50:55 +1000 Subject: [Bug] Develop - Change uint32_t to layer_state_t (#13596) * fix sat75 * update uint32_t to layer_state --- docs/zh-cn/custom_quantum_functions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/zh-cn/custom_quantum_functions.md b/docs/zh-cn/custom_quantum_functions.md index 27b2edf38f..44cb5cf76d 100644 --- a/docs/zh-cn/custom_quantum_functions.md +++ b/docs/zh-cn/custom_quantum_functions.md @@ -297,7 +297,7 @@ void suspend_wakeup_init_user(void) { 本例使用了Planck键盘示范了如何设置 [RGB背光灯](feature_rgblight.md)使之与层对应 ```c -uint32_t layer_state_set_user(uint32_t state) { +layer_state_t layer_state_set_user(layer_state_t state) { switch (biton32(state)) { case _RAISE: rgblight_setrgb (0x00, 0x00, 0xFF); @@ -321,7 +321,7 @@ uint32_t layer_state_set_user(uint32_t state) { ### `layer_state_set_*` 函数文档 * 键盘/修订: `uint32_t layer_state_set_kb(uint32_t state)` -* 布局: `uint32_t layer_state_set_user(uint32_t state)` +* 布局: `layer_state_t layer_state_set_user(layer_state_t state)` 该`状态`是活动层的bitmask, 详见[布局概述](keymap.md#布局的层状态) @@ -377,7 +377,7 @@ void keyboard_post_init_user(void) { 以上函数会在读EEPROM配置后立即使用该设置来设置默认层RGB颜色。"raw"的值是从你上面基于"union"创建的结构体中转换来的。 ```c -uint32_t layer_state_set_user(uint32_t state) { +layer_state_t layer_state_set_user(layer_state_t state) { switch (biton32(state)) { case _RAISE: if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); } -- cgit v1.2.3 From fb9a254a432e307e82c9dce45e1aba2cf21fa339 Mon Sep 17 00:00:00 2001 From: Patrick Stadler Date: Thu, 22 Jul 2021 08:46:12 +0200 Subject: Retain brightness with lighting layers (#13025) Add guard `RGBLIGHT_LAYERS_RETAIN_VAL` to retain the currently used val when applying lighting layers. --- docs/feature_rgblight.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index d323dee4f7..8484586c05 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -326,6 +326,10 @@ would turn the layer 0 (or 1) on and off again three times when `DEBUG` is press 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`. +### Retain brightness + +Usually lighting layers apply their configured brightness once activated. If you would like lighting layers to retain the currently used brightness (as returned by `rgblight_get_val()`), add `#define RGBLIGHT_LAYERS_RETAIN_VAL` 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/rgblight.h) for the full list, but the most commonly used functions include: -- cgit v1.2.3 From fdcea0633657fba4cebcef45eee2f103d162e28c Mon Sep 17 00:00:00 2001 From: Erovia Date: Fri, 23 Jul 2021 21:41:33 +0100 Subject: CLI/Docs: Fix the format commands' name (#13668) PR #13296 changed the name of the `cformat` and `pyformat` commands to `format-c` and `format-py` respectively. This PR updates the documentation and some parts of the CLI to use the new names. Also add documentation for the new `format-text` subcommand, introduced in the same PR. --- docs/cli_commands.md | 25 ++++++++++++++++++------- docs/cli_development.md | 4 ++-- docs/de/cli.md | 8 ++++---- docs/fr-fr/cli.md | 8 ++++---- docs/ja/cli_commands.md | 14 +++++++------- docs/ja/cli_development.md | 4 ++-- 6 files changed, 37 insertions(+), 26 deletions(-) (limited to 'docs') diff --git a/docs/cli_commands.md b/docs/cli_commands.md index e30593daa9..0a2bd8121e 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -314,7 +314,18 @@ qmk clean [-a] # Developer Commands -## `qmk cformat` +## `qmk format-text` + +This command formats text files to have proper line endings. + +Every text file in the repository needs to have Unix (LF) line ending. +If you are working on **Windows**, you must ensure that line endings are corrected in order to get your PRs merged. + +``` +qmk format-text +``` + +## `qmk format-c` This command formats C code using clang-format. @@ -325,25 +336,25 @@ Run it with `-a` to format all core code, or pass filenames on the command line **Usage for specified files**: ``` -qmk cformat [file1] [file2] [...] [fileN] +qmk format-c [file1] [file2] [...] [fileN] ``` **Usage for all core files**: ``` -qmk cformat -a +qmk format-c -a ``` **Usage for only changed files against origin/master**: ``` -qmk cformat +qmk format-c ``` **Usage for only changed files against branch_name**: ``` -qmk cformat -b branch_name +qmk format-c -b branch_name ``` ## `qmk docs` @@ -398,14 +409,14 @@ $ qmk kle2json -f kle.txt -f Ψ Wrote out to info.json ``` -## `qmk pyformat` +## `qmk format-python` This command formats python code in `qmk_firmware`. **Usage**: ``` -qmk pyformat +qmk format-python ``` ## `qmk pytest` diff --git a/docs/cli_development.md b/docs/cli_development.md index 07c8f281ba..0f4f401b33 100644 --- a/docs/cli_development.md +++ b/docs/cli_development.md @@ -188,7 +188,7 @@ cli.log.info('Reading from %s and writing to %s', cli.args.filename, cli.args.ou # 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: +We use nose2, flake8, and yapf to test, lint, and format code. You can use the `pytest` and `format-py` subcommands to run these tests: ### Testing and Linting @@ -196,7 +196,7 @@ We use nose2, flake8, and yapf to test, lint, and format code. You can use the ` ### Formatting - qmk pyformat + qmk format-py ## Formatting Details diff --git a/docs/de/cli.md b/docs/de/cli.md index 437062ad66..7dc02d505b 100644 --- a/docs/de/cli.md +++ b/docs/de/cli.md @@ -88,14 +88,14 @@ qmk compile qmk compile -kb -km ``` -## `qmk cformat` +## `qmk format-c` 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 format-c [file1] [file2] [...] [fileN] ``` ## `qmk config` @@ -148,14 +148,14 @@ Dieser Befehl erstellt eine neue Keymap basierend auf einer existierenden Standa qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] ``` -## `qmk pyformat` +## `qmk format-py` Dieser Befehl formatiert Python-Code in `qmk_firmware`. **Anwendung**: ``` -qmk pyformat +qmk format-py ``` ## `qmk pytest` diff --git a/docs/fr-fr/cli.md b/docs/fr-fr/cli.md index 4281536458..bfa060f2ad 100644 --- a/docs/fr-fr/cli.md +++ b/docs/fr-fr/cli.md @@ -85,14 +85,14 @@ qmk compile qmk compile -kb -km ``` -## `qmk cformat` +## `qmk format-c` 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 format-c [file1] [file2] [...] [fileN] ``` ## `qmk config` @@ -125,14 +125,14 @@ Cette commande crée une nouvelle keymap basée sur une keymap par défaut d'un qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] ``` -## `qmk pyformat` +## `qmk format-py` Cette commande formate le code python dans `qmk_firmware`. **Utilisation**: ``` -qmk pyformat +qmk format-py ``` ## `qmk pytest` diff --git a/docs/ja/cli_commands.md b/docs/ja/cli_commands.md index 81cb03cfe5..35937dbbcb 100644 --- a/docs/ja/cli_commands.md +++ b/docs/ja/cli_commands.md @@ -211,7 +211,7 @@ qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] # 開発者用コマンド -## `qmk cformat` +## `qmk format-c` このコマンドは clang-format を使って C コードを整形します。 @@ -222,25 +222,25 @@ qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] **指定したファイルに対する使い方**: ``` -qmk cformat [file1] [file2] [...] [fileN] +qmk format-c [file1] [file2] [...] [fileN] ``` **全てのコアファイルに対する使い方**: ``` -qmk cformat -a +qmk format-c -a ``` **origin/master で変更されたファイルのみに対する使い方**: ``` -qmk cformat +qmk format-c ``` **branch_name で変更されたファイルのみに対する使い方**: ``` -qmk cformat -b branch_name +qmk format-c -b branch_name ``` ## `qmk docs` @@ -275,14 +275,14 @@ $ qmk kle2json -f kle.txt -f Ψ Wrote out to info.json ``` -## `qmk pyformat` +## `qmk format-py` このコマンドは `qmk_firmware` 内の python コードを整形します。 **使用法**: ``` -qmk pyformat +qmk format-py ``` ## `qmk pytest` diff --git a/docs/ja/cli_development.md b/docs/ja/cli_development.md index 47262213ae..28cdd91c1e 100644 --- a/docs/ja/cli_development.md +++ b/docs/ja/cli_development.md @@ -192,7 +192,7 @@ cli.log.info('Reading from %s and writing to %s', cli.args.filename, cli.args.ou # テスト、リントおよびフォーマット -nose2、flake8 および yapf を使ってコードをテスト、リントおよびフォーマットします。これらのテストを実行するために `pytest` と `pyformat` サブコマンドを使うことができます。 +nose2、flake8 および yapf を使ってコードをテスト、リントおよびフォーマットします。これらのテストを実行するために `pytest` と `format-py` サブコマンドを使うことができます。 ### テストとリント @@ -200,7 +200,7 @@ nose2、flake8 および yapf を使ってコードをテスト、リントお ### フォーマット - qmk pyformat + qmk format-py ## フォーマットの詳細 -- cgit v1.2.3 From b8a1e14f53489eea63bd747d1b94d7d9b7da5ac9 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Sat, 24 Jul 2021 00:37:19 -0700 Subject: Remove deprecated callbacks for encoders and dip switches (#13404) --- docs/ja/feature_encoders.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/ja/feature_encoders.md b/docs/ja/feature_encoders.md index 7b7f394c83..21f42d38b7 100644 --- a/docs/ja/feature_encoders.md +++ b/docs/ja/feature_encoders.md @@ -51,15 +51,18 @@ ENCODER_ENABLE = yes コールバック関数を `.c` に記述することができます: ```c -void encoder_update_kb(uint8_t index, bool clockwise) { - encoder_update_user(index, clockwise); +bool encoder_update_kb(uint8_t index, bool clockwise) { + if (!encoder_update_user(index, clockwise)) { + return false; + } + } ``` あるいは `keymap.c` に記述することもできます: ```c -void encoder_update_user(uint8_t index, bool clockwise) { +bool encoder_update_user(uint8_t index, bool clockwise) { if (index == 0) { /* First encoder */ if (clockwise) { tap_code(KC_PGDN); @@ -73,6 +76,7 @@ void encoder_update_user(uint8_t index, bool clockwise) { tap_code(KC_UP); } } + return true; } ``` -- cgit v1.2.3 From d972919204a5f1cb96d4e16c765d7028a423888a Mon Sep 17 00:00:00 2001 From: Dasky <32983009+daskygit@users.noreply.github.com> Date: Sat, 24 Jul 2021 18:44:31 +0100 Subject: [Docs] Fix typo in dip switch example (#13688) --- docs/feature_dip_switch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_dip_switch.md b/docs/feature_dip_switch.md index 5e8c19bfa7..43a6a3faf7 100644 --- a/docs/feature_dip_switch.md +++ b/docs/feature_dip_switch.md @@ -24,7 +24,7 @@ The callback functions can be inserted into your `.c`: ```c bool dip_switch_update_kb(uint8_t index, bool active) { - if !(dip_switch_update_user(index, active)) { return false; } + if (!dip_switch_update_user(index, active)) { return false; } return true; } ``` -- cgit v1.2.3 From 0b95ac2e4b29a663258aee475a70a3200d113ac2 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Sat, 24 Jul 2021 12:17:04 -0700 Subject: Clean up remaining RGB_DISABLE_WHEN_USB_SUSPENDED defines (#13689) --- docs/feature_led_matrix.md | 29 +---------------------------- docs/feature_rgb_matrix.md | 27 --------------------------- 2 files changed, 1 insertion(+), 55 deletions(-) (limited to 'docs') diff --git a/docs/feature_led_matrix.md b/docs/feature_led_matrix.md index 5134ab6efa..018da43dd1 100644 --- a/docs/feature_led_matrix.md +++ b/docs/feature_led_matrix.md @@ -262,7 +262,7 @@ For inspiration and examples, check out the built-in effects under `quantum/led_ #define LED_MATRIX_FRAMEBUFFER_EFFECTS // enable framebuffer effects #define LED_DISABLE_TIMEOUT 0 // number of milliseconds to wait until led automatically turns off #define LED_DISABLE_AFTER_TIMEOUT 0 // OBSOLETE: number of ticks to wait until disabling effects -#define LED_DISABLE_WHEN_USB_SUSPENDED false // turn off effects when suspended +#define LED_DISABLE_WHEN_USB_SUSPENDED // turn off effects when suspended #define LED_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 LED_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 LED_MATRIX_MAXIMUM_BRIGHTNESS 255 // limits maximum brightness of LEDs @@ -350,30 +350,3 @@ void led_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { LED_MATRIX_INDICATOR_SET_VALUE(index, value); } ``` - -## Suspended State :id=suspended-state -To use the suspend feature, make sure that `#define LED_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) { - led_matrix_set_suspend_state(true); - suspend_power_down_user(); -} - -void suspend_wakeup_init_kb(void) { - led_matrix_set_suspend_state(false); - suspend_wakeup_init_user(); -} -``` -or add this to your `keymap.c`: -```c -void suspend_power_down_user(void) { - led_matrix_set_suspend_state(true); -} - -void suspend_wakeup_init_user(void) { - led_matrix_set_suspend_state(false); -} -``` diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index f3e25f2f13..bd47fb6d39 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -741,30 +741,3 @@ void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { } } ``` - -### 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_user(void) { - rgb_matrix_set_suspend_state(false); -} -``` -- cgit v1.2.3 From 958483a4bad62cb55e2782dbf0f8762692748515 Mon Sep 17 00:00:00 2001 From: Marc Tamsky Date: Sat, 24 Jul 2021 20:51:40 -0700 Subject: docs/cli_commands: fix typo (#13697) --- docs/cli_commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 0a2bd8121e..876ffb5831 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -109,7 +109,7 @@ qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN] ## `qmk console` -This command lets you connect to keyboard consoles to get debugging messages. It only works if your keyboard firmware has been compiled with `CONSOLE_ENABLED=yes`. +This command lets you connect to keyboard consoles to get debugging messages. It only works if your keyboard firmware has been compiled with `CONSOLE_ENABLE=yes`. **Usage**: -- cgit v1.2.3 From 71e9f8fc11f617278497611e169bf2ddccd2211c Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Sat, 24 Jul 2021 23:00:57 -0700 Subject: Update LUFA (18-07-2021) and add QMK-HID Bootloader support (#13588) Co-authored-by: Ryan --- docs/driver_installation_zadig.md | 1 + docs/flashing.md | 46 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+) (limited to 'docs') diff --git a/docs/driver_installation_zadig.md b/docs/driver_installation_zadig.md index fd5d3e92fc..e4db069f1d 100644 --- a/docs/driver_installation_zadig.md +++ b/docs/driver_installation_zadig.md @@ -95,3 +95,4 @@ The device name here is the name that appears in Zadig, and may not be what the |`stm32-dfu` |STM32 BOOTLOADER |`0483:DF11` |WinUSB | |`kiibohd` |Kiibohd DFU Bootloader |`1C11:B007` |WinUSB | |`stm32duino` |Maple 003 |`1EAF:0003` |WinUSB | +|`qmk-hid` |(keyboard name) Bootloader |`03EB:2067` |HidUsb | diff --git a/docs/flashing.md b/docs/flashing.md index 83c97444e1..da3c64c4a4 100644 --- a/docs/flashing.md +++ b/docs/flashing.md @@ -171,6 +171,52 @@ Flashing sequence: 3. Flash a .hex file 4. Reset the device into application mode (may be done automatically) +### QMK HID + +QMK maintains [a fork of the LUFA HID bootloader](https://github.com/qmk/lufa/tree/master/Bootloaders/HID), which uses a USB HID Endpoint for flashing in the way that the PJRC's Teensy Loader flasher and HalfKay bootloader work. Additionally, it performs a simple matrix scan for exiting the bootloader and returning to the application, as well as flashing an LED/making a ticking noise with a speaker when things are happening. + +To ensure compatibility with the QMK HID bootloader, make sure this block is present in your `rules.mk`: + +```make +# Bootloader selection +BOOTLOADER = qmk-hid +``` + +To enable the additional features, add the following defines to your `config.h`: + +```c +#define QMK_ESC_OUTPUT F1 // COL pin if COL2ROW +#define QMK_ESC_INPUT D5 // ROW pin if COL2ROW +// Optional: +//#define QMK_LED E6 +//#define QMK_SPEAKER C6 +``` + +Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md#bootmagic-lite), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader. + +The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string. + +To generate this bootloader, use the `bootloader` target, eg. `make planck/rev4:default:bootloader`. To generate a production-ready .hex file (combining QMK and the bootloader), use the `production` target, eg. `make planck/rev4:default:production`. + +Compatible flashers: + +* TBD + * Currently, you need to either use the [Python script](https://github.com/qmk/lufa/tree/master/Bootloaders/HID/HostLoaderApp_python), or compile [`hid_bootloader_cli`](https://github.com/qmk/lufa/tree/master/Bootloaders/HID/HostLoaderApp), from the LUFA repo. Homebrew may (will) have support for this directly (via `brew install qmk/qmk/hid_bootloader_cli`). + +Flashing sequence: + +1. Enter the bootloader using any of the following methods: + * Press the `RESET` keycode + * Press the `RESET` button on the PCB if available + * short RST to GND quickly +2. Wait for the OS to detect the device +3. Flash a .hex file +4. Reset the device into application mode (may be done automatically) + +### `make` Targets + +* `:qmk-hid`: Checks every 5 seconds until a DFU device is available, and then flashes the firmware. + ## STM32/APM32 DFU All STM32 and APM32 MCUs, except for F103 (see the [STM32duino section](#stm32duino)) come preloaded with a factory bootloader that cannot be modified nor deleted. -- cgit v1.2.3 From 03d258c2226959480fc3ead1568ca2fe8ba37c59 Mon Sep 17 00:00:00 2001 From: Joel Challis Date: Wed, 28 Jul 2021 12:01:23 +0100 Subject: matrix_scan_x -> x_task (#13748) --- docs/feature_tap_dance.md | 2 +- docs/ja/feature_tap_dance.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/feature_tap_dance.md b/docs/feature_tap_dance.md index 5d77f3e08d..f4e989921f 100644 --- a/docs/feature_tap_dance.md +++ b/docs/feature_tap_dance.md @@ -50,7 +50,7 @@ The main entry point is `process_tap_dance()`, called from `process_record_quant This means that you have `TAPPING_TERM` time to tap the key again; you do not have to input all the taps within a single `TAPPING_TERM` timeframe. This allows for longer tap counts, with minimal impact on responsiveness. -Our next stop is `matrix_scan_tap_dance()`. This handles the timeout of tap-dance keys. +Our next stop is `tap_dance_task()`. This handles the timeout of tap-dance keys. 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. diff --git a/docs/ja/feature_tap_dance.md b/docs/ja/feature_tap_dance.md index 3d9d30ecf0..dd2b8bdb6c 100644 --- a/docs/ja/feature_tap_dance.md +++ b/docs/ja/feature_tap_dance.md @@ -59,7 +59,7 @@ このことは、あなたは再びキーをタップするまでの時間として `TAPPING_TERM` の時間を持っていることを意味します。そのため、あなたは1つの `TAPPING_TERM` の時間内に全てのタップを行う必要はありません。これにより、キーの反応への影響を最小限に抑えながら、より長いタップ回数を可能にします。 -次は `matrix_scan_tap_dance()` です。この関数はタップダンスキーのタイムアウトを制御します。 +次は `tap_dance_task()` です。この関数はタップダンスキーのタイムアウトを制御します。 柔軟性のために、タップダンスは、キーコードの組み合わせにも、ユーザー関数にもなることができます。後者は、より高度なタップ回数の制御や、LED を点滅させたり、バックライトをいじったり、等々の制御を可能にします。これは、1つの共用体と、いくつかの賢いマクロによって成し遂げられています。 -- cgit v1.2.3 From 25f43837d2d603505a498662993bdeaecb7bc43d Mon Sep 17 00:00:00 2001 From: Ryan Date: Fri, 30 Jul 2021 15:37:18 +1000 Subject: Remove references to info.json `width` and `height` in CLI (#13728) --- docs/ja/reference_configurator_support.md | 2 -- docs/ja/reference_info_json.md | 4 ---- docs/reference_configurator_support.md | 2 -- docs/reference_info_json.md | 4 ---- 4 files changed, 12 deletions(-) (limited to 'docs') diff --git a/docs/ja/reference_configurator_support.md b/docs/ja/reference_configurator_support.md index 4fb98fc0ec..83d6d648d0 100644 --- a/docs/ja/reference_configurator_support.md +++ b/docs/ja/reference_configurator_support.md @@ -104,8 +104,6 @@ JSON ファイルをビルドする最も簡単な方法は、[Keyboard Layout E "tags": { "form_factor": "numpad" }, - "width": 4, - "height": 5, "layouts": { "LAYOUT": { "layout": [ diff --git a/docs/ja/reference_info_json.md b/docs/ja/reference_info_json.md index 5b9a1b6b63..7346a63956 100644 --- a/docs/ja/reference_info_json.md +++ b/docs/ja/reference_info_json.md @@ -20,10 +20,6 @@ * キーボードの製品ページ、[QMK.fm/keyboards](https://qmk.fm/keyboards) のページ、あるいはキーボードに関する情報を説明する他のページの URL。 * `maintainer` * メンテナの GitHub のユーザ名、あるいはコミュニティが管理するキーボードの場合は `qmk` -* `width` - * キー単位でのキーボードの幅 -* `height` - * キー単位でのキーボードの高さ * `layouts` * 物理的なレイアウト表現。詳細は以下のセクションを見てください。 diff --git a/docs/reference_configurator_support.md b/docs/reference_configurator_support.md index 1b34c85a29..ba3d49e2b2 100644 --- a/docs/reference_configurator_support.md +++ b/docs/reference_configurator_support.md @@ -99,8 +99,6 @@ Use the `keyboard_name` object to set the name of the keyboard. For instruction "tags": { "form_factor": "numpad" }, - "width": 4, - "height": 5, "layouts": { "LAYOUT": { "layout": [ diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md index 30d813e93a..cf492629f3 100644 --- a/docs/reference_info_json.md +++ b/docs/reference_info_json.md @@ -15,10 +15,6 @@ The `info.json` file is a JSON formatted dictionary with the following keys avai * A URL to the keyboard's product page, [QMK.fm/keyboards](https://qmk.fm/keyboards) page, or other page describing information about the keyboard. * `maintainer` * GitHub username of the maintainer, or `qmk` for community maintained boards -* `width` - * Width of the board in Key Units -* `height` - * Height of the board in Key Units * `debounce` * How many milliseconds (ms) to wait for debounce to happen. (Default: 5) * `diode_direction` -- cgit v1.2.3 From b021c2f2c5890df5335d3dd163167c6fe6213e0d Mon Sep 17 00:00:00 2001 From: Ryan Date: Sat, 31 Jul 2021 06:57:40 +1000 Subject: Port new_keyboard.sh to CLI (#13706) Co-authored-by: Erovia --- docs/cli_commands.md | 4 ++-- docs/es/hardware_avr.md | 38 ++++++++++++++++++++------------------ docs/hardware_avr.md | 38 ++++++++++++++++++++------------------ docs/ja/hardware_avr.md | 38 ++++++++++++++++++++------------------ 4 files changed, 62 insertions(+), 56 deletions(-) (limited to 'docs') diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 314e7448d7..c7468eb5e7 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -280,12 +280,12 @@ qmk list-keymaps -kb planck/ez This command creates a new keyboard based on available templates. -This command will prompt for input to guide you though the generation process. +Any arguments that are not provided will prompt for input. If `-u` is not passed and `user.name` is set in .gitconfig, it will be used as the default username in the prompt. **Usage**: ``` -qmk new-keyboard +qmk new-keyboard [-kb KEYBOARD] [-t {avr,ps2avrgb}] -u USERNAME ``` ## `qmk new-keymap` diff --git a/docs/es/hardware_avr.md b/docs/es/hardware_avr.md index f8c426381f..ac6a715658 100644 --- a/docs/es/hardware_avr.md +++ b/docs/es/hardware_avr.md @@ -6,26 +6,28 @@ Si aún no lo has hecho, debes leer las [Pautas de teclados](hardware_keyboard_g ## 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`: +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 `qmk new-keyboard`: ``` -$ ./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. +$ qmk new-keyboard +Ψ Generating a new QMK keyboard directory + +Keyboard Name: mycoolkeeb +Keyboard Type: + 1. avr + 2. ps2avrgb +Please enter your choice: [1] +Your Name: [John Smith] +Ψ Copying base template files... +Ψ Copying avr template files... +Ψ Renaming keyboard.[ch] to mycoolkeeb.[ch]... +Ψ Replacing %YEAR% with 2021... +Ψ Replacing %KEYBOARD% with mycoolkeeb... +Ψ Replacing %YOUR_NAME% with John Smith... + +Ψ Created a new keyboard called mycoolkeeb. +Ψ To start working on things, `cd` into keyboards/mycoolkeeb, +Ψ or open the directory in your preferred 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. diff --git a/docs/hardware_avr.md b/docs/hardware_avr.md index eb536ca961..3d58cdc055 100644 --- a/docs/hardware_avr.md +++ b/docs/hardware_avr.md @@ -6,26 +6,28 @@ If you have not yet you should read the [Keyboard Guidelines](hardware_keyboard_ ## Adding Your AVR Keyboard to QMK -QMK has a number of features to simplify working with AVR keyboards. For most keyboards you don't have to write a single line of code. To get started, run the `util/new_keyboard.sh` script: +QMK has a number of features to simplify working with AVR keyboards. For most keyboards you don't have to write a single line of code. To get started, run `qmk new-keyboard`: ``` -$ ./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. +$ qmk new-keyboard +Ψ Generating a new QMK keyboard directory + +Keyboard Name: mycoolkeeb +Keyboard Type: + 1. avr + 2. ps2avrgb +Please enter your choice: [1] +Your Name: [John Smith] +Ψ Copying base template files... +Ψ Copying avr template files... +Ψ Renaming keyboard.[ch] to mycoolkeeb.[ch]... +Ψ Replacing %YEAR% with 2021... +Ψ Replacing %KEYBOARD% with mycoolkeeb... +Ψ Replacing %YOUR_NAME% with John Smith... + +Ψ Created a new keyboard called mycoolkeeb. +Ψ To start working on things, `cd` into keyboards/mycoolkeeb, +Ψ or open the directory in your preferred text editor. ``` This will create all the files needed to support your new keyboard, and populate the settings with default values. Now you just need to customize it for your keyboard. diff --git a/docs/ja/hardware_avr.md b/docs/ja/hardware_avr.md index 66be2f71c9..cdc5f8cb86 100644 --- a/docs/ja/hardware_avr.md +++ b/docs/ja/hardware_avr.md @@ -12,26 +12,28 @@ ## AVR を使用したキーボードを QMK に追加する -QMK には AVR を使ったキーボードでの作業を簡略化するための機能が多数あります。大体のキーボードでは1行もコードを書く必要がありません。まずはじめに、`util/new_keyboard.sh` スクリプトを実行します。 +QMK には AVR を使ったキーボードでの作業を簡略化するための機能が多数あります。大体のキーボードでは1行もコードを書く必要がありません。まずはじめに、`qmk new-keyboard` を実行します。 ``` -$ ./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. +$ qmk new-keyboard +Ψ Generating a new QMK keyboard directory + +Keyboard Name: mycoolkeeb +Keyboard Type: + 1. avr + 2. ps2avrgb +Please enter your choice: [1] +Your Name: [John Smith] +Ψ Copying base template files... +Ψ Copying avr template files... +Ψ Renaming keyboard.[ch] to mycoolkeeb.[ch]... +Ψ Replacing %YEAR% with 2021... +Ψ Replacing %KEYBOARD% with mycoolkeeb... +Ψ Replacing %YOUR_NAME% with John Smith... + +Ψ Created a new keyboard called mycoolkeeb. +Ψ To start working on things, `cd` into keyboards/mycoolkeeb, +Ψ or open the directory in your preferred text editor. ``` これにより、新しいキーボードをサポートするために必要なすべてのファイルが作成され、デフォルト値で設定が入力されます。あとはあなたのキーボード用にカスタマイズするだけです。 -- cgit v1.2.3 From 206a995ccd53b0843e72da606abebe06f39c9c28 Mon Sep 17 00:00:00 2001 From: Joel Challis Date: Sat, 31 Jul 2021 14:31:09 +0100 Subject: Move some led drivers to common folder (#13749) * Move some led drivers to common folder --- docs/feature_led_matrix.md | 2 +- docs/feature_rgb_matrix.md | 6 +++--- docs/ja/feature_led_matrix.md | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/feature_led_matrix.md b/docs/feature_led_matrix.md index 018da43dd1..afa11e7232 100644 --- a/docs/feature_led_matrix.md +++ b/docs/feature_led_matrix.md @@ -63,7 +63,7 @@ const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { } ``` -Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731-simple.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` ). +Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/led/issi/is31fl3731-simple.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` ). --- diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index bd47fb6d39..18e38955ec 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -64,7 +64,7 @@ const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { } ``` -Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3`). +Where `Cx_y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3731.pdf) and the header file `drivers/led/issi/is31fl3731.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3`). --- ### IS31FL3733 :id=is31fl3733 @@ -134,7 +134,7 @@ const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { } ``` -Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3733.pdf) and the header file `drivers/issi/is31fl3733.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` for now). +Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3733.pdf) and the header file `drivers/led/issi/is31fl3733.h`. The `driver` is the index of the driver you defined in your `config.h` (`0`, `1`, `2`, or `3` for now). --- ### IS31FL3737 :id=is31fl3737 @@ -198,7 +198,7 @@ const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = { } ``` -Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3737.pdf) and the header file `drivers/issi/is31fl3737.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0`, `1` for now). +Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](https://www.issi.com/WW/pdf/31FL3737.pdf) and the header file `drivers/led/issi/is31fl3737.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0`, `1` for now). --- diff --git a/docs/ja/feature_led_matrix.md b/docs/ja/feature_led_matrix.md index 62e22859fb..f132d716f6 100644 --- a/docs/ja/feature_led_matrix.md +++ b/docs/ja/feature_led_matrix.md @@ -61,7 +61,7 @@ I2C IS31FL3731 RGB コントローラを使ったアドレス指定可能な LED .... } -ここで、`Cx_y` は[データシート](https://www.issi.com/WW/pdf/31FL3731.pdf)およびヘッダファイル `drivers/issi/is31fl3731-simple.h` で定義されるマトリックス内の LED の位置です。`driver` は `config.h` で定義したドライバのインデックス(`0`、`1`、`2`、`3`のいずれか)です。 +ここで、`Cx_y` は[データシート](https://www.issi.com/WW/pdf/31FL3731.pdf)およびヘッダファイル `drivers/led/issi/is31fl3731-simple.h` で定義されるマトリックス内の LED の位置です。`driver` は `config.h` で定義したドライバのインデックス(`0`、`1`、`2`、`3`のいずれか)です。 ## キーコード -- cgit v1.2.3 From 70fb3e1aaf406cbbd5137916a93ed814d6891ef2 Mon Sep 17 00:00:00 2001 From: Joel Challis Date: Sat, 31 Jul 2021 14:35:30 +0100 Subject: __flash? (#13799) --- docs/feature_led_matrix.md | 2 +- docs/feature_rgb_matrix.md | 8 ++++---- docs/ja/feature_led_matrix.md | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/feature_led_matrix.md b/docs/feature_led_matrix.md index afa11e7232..7d7971bbed 100644 --- a/docs/feature_led_matrix.md +++ b/docs/feature_led_matrix.md @@ -52,7 +52,7 @@ Here is an example using 2 drivers. Define these arrays listing all the LEDs in your `.c`: ```c -const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { +const is31_led __flash g_is31_leds[DRIVER_LED_TOTAL] = { /* Refer to IS31 manual for these locations * driver * | LED address diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 18e38955ec..670d7e09bf 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -52,7 +52,7 @@ Here is an example using 2 drivers. Define these arrays listing all the LEDs in your `.c`: ```c -const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { +const is31_led __flash g_is31_leds[DRIVER_LED_TOTAL] = { /* Refer to IS31 manual for these locations * driver * | R location @@ -122,7 +122,7 @@ Currently only 4 drivers are supported, but it would be trivial to support all 8 Define these arrays listing all the LEDs in your `.c`: ```c -const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { +const is31_led __flash g_is31_leds[DRIVER_LED_TOTAL] = { /* Refer to IS31 manual for these locations * driver * | R location @@ -186,7 +186,7 @@ Currently only 2 drivers are supported, but it would be trivial to support all 4 Define these arrays listing all the LEDs in your `.c`: ```c -const is31_led PROGMEM g_is31_leds[DRIVER_LED_TOTAL] = { +const is31_led __flash g_is31_leds[DRIVER_LED_TOTAL] = { /* Refer to IS31 manual for these locations * driver * | R location @@ -287,7 +287,7 @@ Here is an example using 2 drivers. Define these arrays listing all the LEDs in your `.c`: ```c -const aw_led g_aw_leds[DRIVER_LED_TOTAL] = { +const aw_led __flash g_aw_leds[DRIVER_LED_TOTAL] = { /* Each AW20216 channel is controlled by a register at some offset between 0x00 * and 0xD7 inclusive. * See drivers/awinic/aw20216.h for the mapping between register offsets and diff --git a/docs/ja/feature_led_matrix.md b/docs/ja/feature_led_matrix.md index f132d716f6..6511b28249 100644 --- a/docs/ja/feature_led_matrix.md +++ b/docs/ja/feature_led_matrix.md @@ -52,7 +52,7 @@ I2C IS31FL3731 RGB コントローラを使ったアドレス指定可能な LED `.c` に全ての LED を列挙する配列を定義します: - const is31_led g_is31_leds[DRIVER_LED_TOTAL] = { + const is31_led __flash g_is31_leds[DRIVER_LED_TOTAL] = { /* これらの位置については IS31 マニュアルを参照してください * driver * | LED address -- cgit v1.2.3 From bcb6e23387290afb64712314bfb095f8d96c1a4e Mon Sep 17 00:00:00 2001 From: JohSchneider Date: Thu, 5 Aug 2021 21:51:24 +0000 Subject: Arm ps2 mouse interrupt (#6490) * ps2_mouse on ARM: an interrupt-version of the ps2-mouse code ported to ARM/chibios * ps2_mouse on ARM: link EXT callback-channel selection to the user defined PS2_LINE_CLOCK * ps2_mouse on ARM: replace DELAY_X defines with hardware-agnostic wait_X * ps2_mouse on ARM: replace chibios-specific defines for the pins/lines with defines from quantum/config_common.h and drop the '_LINE' component from teh define name * ps2_mouse on ARM: expose the software-intterupt port as a user editable define * Update docs/feature_ps2_mouse.md Co-Authored-By: Hugo van Kemenade * Update feature_ps2_mouse.md * use a define to deduce the PS_DATA_PORT instead * reduce all-zero extcfg to oneliner * ps2_mouse: use generic wait instead of avr-delay * Update docs/feature_ps2_mouse.md * ps2_mouse: changes for new chibios version (17.6.0 -> 19.1.0) replacing the legacy externa-interrupt driver with pal-callbacks * ps2_mouse: use PLATFORM_KEY Co-Authored-By: Joel Challis * ps2_mouse: clang-format corrections * ps2_mouse: add systemlocks using the chibios equivalent to AVRs cli: chSys[Unl|L]ock Co-authored-by: Johannes Co-authored-by: Hugo van Kemenade Co-authored-by: Joel Challis --- docs/feature_ps2_mouse.md | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/feature_ps2_mouse.md b/docs/feature_ps2_mouse.md index 8e84e22d8a..00c7ee72ee 100644 --- a/docs/feature_ps2_mouse.md +++ b/docs/feature_ps2_mouse.md @@ -50,7 +50,7 @@ In your keyboard config.h: #endif ``` -## Interrupt Version :id=interrupt-version +### Interrupt Version (AVR/ATMega32u4) :id=interrupt-version-avr 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. @@ -88,7 +88,31 @@ In your keyboard config.h: #endif ``` -## USART Version :id=usart-version +### Interrupt Version (ARM chibios) :id=interrupt-version-chibios + +Pretty much any two pins can be used for the (software) interrupt variant on ARM cores. The example below uses A8 for clock, and A9 for data. + +In rules.mk: + +``` +PS2_MOUSE_ENABLE = yes +PS2_USE_INT = yes +``` + +In your keyboard config.h: + +```c +#define PS2_CLOCK A8 +#define PS2_DATA A9 +``` + +And in the chibios specifig halconf.h: +```c +#define PAL_USE_CALLBACKS TRUE +``` + + +### 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. -- cgit v1.2.3 From 07553b41f0a03ca6549c09cecf9cd3dec7332346 Mon Sep 17 00:00:00 2001 From: Juan Pablo Kutianski Date: Thu, 5 Aug 2021 16:09:58 -0700 Subject: [Feature] Swap buttons on PS2 Mouse/Trackball (#9205) * [Feature Request] Swap buttons on PS2 Mouse/Trackball * [Feature Request] Swap buttons on PS2 Mouse/Trackball * Added id: to the doc * Missing space * Solve comment https://github.com/qmk/qmk_firmware/pull/9205#discussion_r430783182 * Solve comments https://github.com/qmk/qmk_firmware/pull/9205#discussion_r430783182 & https://github.com/qmk/qmk_firmware/pull/9205#discussion_r430783884 * Format code more according to https://docs.qmk.fm/#/coding_conventions_c * change logic to LUT * WIP: Clean up * WIP: Solution with xor operators to mask the change * delete #endif & added the missed xor operator (ahhh) * Variable (mouse_report->buttons): avoid setting twice https://github.com/qmk/qmk_firmware/pull/9205#discussion_r430783884 * Update tmk_core/protocol/ps2_mouse.c Co-authored-by: Nick Brassel Co-authored-by: juank Co-authored-by: Nick Brassel --- docs/feature_ps2_mouse.md | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs') diff --git a/docs/feature_ps2_mouse.md b/docs/feature_ps2_mouse.md index 00c7ee72ee..776a33150e 100644 --- a/docs/feature_ps2_mouse.md +++ b/docs/feature_ps2_mouse.md @@ -270,6 +270,16 @@ Fine control over the scrolling is supported with the following defines: #define PS2_MOUSE_SCROLL_DIVISOR_V 2 ``` +### Invert Mouse buttons :id=invert-buttons + +To invert the left & right buttons you can put: + +```c +#define PS2_MOUSE_INVERT_BUTTONS +``` + +into config.h. + ### Invert Mouse and Scroll Axes :id=invert-mouse-and-scroll-axes To invert the X and Y axes you can put: -- cgit v1.2.3 From 7e983796e18e7401c062c158f23966aeb7b1405b Mon Sep 17 00:00:00 2001 From: Pete Sevander Date: Fri, 6 Aug 2021 02:44:57 +0300 Subject: Process combos earlier & overlapping combos (#8591) * Combo processing improvements. Now it is possible to use ModTap and LayerTap keys as part of combos. Overlapping combos also don't trigger all the combos, just exactly the one that you press. New settings: - COMBO_MUST_HOLD_MODS - COMBO_MOD_TERM - COMBO_TERM_PER_COMBO - COMBO_MUST_HOLD_PER_COMBO - COMBO_STRICT_TIMER - COMBO_NO_TIMER * Remove the size flags from combo_t struct boolean members. This in the end actually saves space as the members are accessed so many times. The amount of operations needed to access the bits uses more memory than setting the size saves. * Fix `process_combo_key_release` not called correctly with tap-only combos * Fix not passing a pointer when NO_ACTION_TAPPING is defined. * Docs for `COMBO_ONLY_FROM_LAYER` * Update docs/feature_combo.md Co-authored-by: precondition <57645186+precondition@users.noreply.github.com> * Update quantum/process_keycode/process_combo.c Co-authored-by: precondition <57645186+precondition@users.noreply.github.com> * Add `EXTRA_SHORT_COMBOS` option. Stuff combo's `disabled` and `active` flags into `state`. Possibly can save some space. * Add more examples and clarify things with dict management system. - Simple examples now has a combo that has modifiers included. - The slightly more advanced examples now are actually more advanced instead of just `tap_code16()`. - Added a note that `COMBO_ACTION`s are not needed anymore as you can just use custom keycodes. - Added a note that the `g/keymap_combo.h` macros use the `process_combo_event` function and that it is not usable in one's keymap afterwards. * Update docs/feature_combo.md Co-authored-by: precondition <57645186+precondition@users.noreply.github.com> * Update docs/feature_combo.md Co-authored-by: precondition <57645186+precondition@users.noreply.github.com> * Update docs/feature_combo.md Co-authored-by: precondition <57645186+precondition@users.noreply.github.com> * Update docs/feature_combo.md Co-authored-by: precondition <57645186+precondition@users.noreply.github.com> * Update docs/feature_combo.md Co-authored-by: precondition <57645186+precondition@users.noreply.github.com> * Change "the" combo action example to "email" example. * Update docs/feature_combo.md Co-authored-by: precondition <57645186+precondition@users.noreply.github.com> * Fix sneaky infinite loop with `combo_disable()` No need to call `dump_key_buffer` when disabling combos because the buffer is either being dumped if a combo-key was pressed, or the buffer is empty if a non-combo-key is pressed. * Update docs/feature_combo.md Co-authored-by: precondition <57645186+precondition@users.noreply.github.com> * Update docs/feature_combo.md Co-authored-by: precondition <57645186+precondition@users.noreply.github.com> Co-authored-by: precondition <57645186+precondition@users.noreply.github.com> Co-authored-by: Drashna Jaelre --- docs/config_options.md | 14 ++- docs/feature_combo.md | 292 +++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 272 insertions(+), 34 deletions(-) (limited to 'docs') diff --git a/docs/config_options.md b/docs/config_options.md index 0c98b31010..78c1f70fd7 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -188,9 +188,21 @@ If you define these options you will enable the associated feature, which may in 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. + * Set this to the number of combos that you're using in the [Combo](feature_combo.md) feature. Or leave it undefined and programmatically set the count. * `#define COMBO_TERM 200` * how long for the Combo keys to be detected. Defaults to `TAPPING_TERM` if not defined. +* `#define COMBO_MUST_HOLD_MODS` + * Flag for enabling extending timeout on Combos containing modifers +* `#define COMBO_MOD_TERM 200` + * Allows for extending COMBO_TERM for mod keys while mid-combo. +* `#define COMBO_MUST_HOLD_PER_COMBO` + * Flag to enable per-combo COMBO_TERM extension and `get_combo_must_hold()` function +* `#define COMBO_TERM_PER_COMBO` + * Flag to enable per-combo COMBO_TERM extension and `get_combo_term()` function +* `#define COMBO_STRICT_TIMER` + * Only start the combo timer on the first key press instead of on all key presses. +* `#define COMBO_NO_TIMER` + * Disable the combo timer completely for relaxed combos. * `#define TAP_CODE_DELAY 100` * Sets the delay between `register_code` and `unregister_code`, if you're having issues with it registering properly (common on VUSB boards). The value is in milliseconds. * `#define TAP_HOLD_CAPS_DELAY 80` diff --git a/docs/feature_combo.md b/docs/feature_combo.md index d831328f69..d98e6f2ac7 100644 --- a/docs/feature_combo.md +++ b/docs/feature_combo.md @@ -1,24 +1,39 @@ # 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. +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 combo term would hit `ESC` instead, or have it perform even more complex tasks. To enable this feature, you 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). - +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). It is also possible to not define this and instead set the variable `COMBO_LEN` yourself. There's a trick where we don't need to think about this variable at all. More on this later. -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. +Then, in 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 its 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)}; +const uint16_t PROGMEM test_combo1[] = {KC_A, KC_B, COMBO_END}; +const uint16_t PROGMEM test_combo2[] = {KC_C, KC_D, COMBO_END}; +combo_t key_combos[COMBO_COUNT] = { + COMBO(test_combo1, KC_ESC), + COMBO(test_combo2, LCTL(KC_Z)), // keycodes with modifiers are possible too! +}; ``` -This will send "Escape" if you hit the A and B keys. +This will send "Escape" if you hit the A and B keys, and Ctrl+Z when you hit the C and D keys. + +As of [PR#8591](https://github.com/qmk/qmk_firmware/pull/8591/), it is possible to fire combos from ModTap keys and LayerTap keys. So in the above example you could have keys `LSFT_T(KC_A)` and `LT(_LAYER, KC_B)` and it would work. So Home Row Mods and Home Row Combos at same time is now a thing! -!> This method only supports [basic keycodes](keycodes_basic.md). See the examples for more control. +It is also now possible to overlap combos. Before, with the example below both combos would activate when all three keys were pressed. Now only the three key combo will activate. + +```c +const uint16_t PROGMEM test_combo1[] = {LSFT_T(KC_A), LT(_LAYER, KC_B), COMBO_END}; +const uint16_t PROGMEM test_combo2[] = {LSFT_T(KC_A), LT(_LAYER, KC_B), KC_C, COMBO_END}; +combo_t key_combos[COMBO_COUNT] = { + COMBO(test_combo1, KC_ESC) + COMBO(test_combo2, KC_TAB) +}; +``` + +Executing more complex keycodes like ModTaps and LayerTaps is now also possible. ## Examples @@ -27,63 +42,68 @@ If you want to add a list, then you'd use something like this: ```c enum combos { AB_ESC, - JK_TAB + JK_TAB, + QW_SFT, + SD_LAYER, }; const uint16_t PROGMEM ab_combo[] = {KC_A, KC_B, COMBO_END}; const uint16_t PROGMEM jk_combo[] = {KC_J, KC_K, COMBO_END}; +const uint16_t PROGMEM qw_combo[] = {KC_Q, KC_W, COMBO_END}; +const uint16_t PROGMEM sd_combo[] = {KC_S, KC_D, COMBO_END}; combo_t key_combos[COMBO_COUNT] = { [AB_ESC] = COMBO(ab_combo, KC_ESC), - [JK_TAB] = COMBO(jk_combo, KC_TAB) + [JK_TAB] = COMBO(jk_combo, KC_TAB), + [QW_SFT] = COMBO(qw_combo, KC_LSFT) + [SD_LAYER] = COMBO(layer_combo, MO(_LAYER)), }; ``` For a more complicated implementation, you can use the `process_combo_event` function to add custom handling. +Additionally, this example shows how you can leave `COMBO_COUNT` undefined. ```c enum combo_events { - ZC_COPY, - XV_PASTE + EM_EMAIL, + BSPC_LSFT_CLEAR, + COMBO_LENGTH }; +uint16_t COMBO_LEN = COMBO_LENGTH; // remove the COMBO_COUNT define and use this instead! -const uint16_t PROGMEM copy_combo[] = {KC_Z, KC_C, COMBO_END}; -const uint16_t PROGMEM paste_combo[] = {KC_X, KC_V, COMBO_END}; +const uint16_t PROGMEM email_combo[] = {KC_E, KC_M, COMBO_END}; +const uint16_t PROGMEM clear_line_combo[] = {KC_BSPC, KC_LSFT, COMBO_END}; -combo_t key_combos[COMBO_COUNT] = { - [ZC_COPY] = COMBO_ACTION(copy_combo), - [XV_PASTE] = COMBO_ACTION(paste_combo), +combo_t key_combos[] = { + [EM_EMAIL] = COMBO_ACTION(email_combo), + [BSPC_LSFT_CLEAR] = COMBO_ACTION(clear_line_combo), }; +/* COMBO_ACTION(x) is same as COMBO(x, KC_NO) */ void process_combo_event(uint16_t combo_index, bool pressed) { switch(combo_index) { - case ZC_COPY: + case EM_EMAIL: if (pressed) { - tap_code16(LCTL(KC_C)); + SEND_STRING("john.doe@example.com"); } break; - case XV_PASTE: + case BSPC_LSFT_CLEAR: if (pressed) { - tap_code16(LCTL(KC_V)); + tap_code16(KC_END); + tap_code16(S(KC_HOME)); + tap_code16(KC_BSPC); } break; } } ``` -This will send Ctrl+C if you hit Z and C, and Ctrl+V if you hit X and V. But you could change this to do stuff like change layers, play sounds, or change settings. - -## Additional Configuration +This will send "john.doe@example.com" if you chord E and M together, and clear the current line with Backspace and Left-Shift. You could change this to do stuff like play sounds or change settings. -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. +It is worth noting that `COMBO_ACTION`s are not needed anymore. As of [PR#8591](https://github.com/qmk/qmk_firmware/pull/8591/), it is possible to run your own custom keycodes from combos. Just define the custom keycode, program its functionality in `process_record_user`, and define a combo with `COMBO(, )`. -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`. - -## Keycodes - -You can enable, disable and toggle the Combo feature on the fly. This is useful if you need to disable them temporarily, such as for a game. +## Keycodes +You can enable, disable and toggle the Combo feature on the fly. This is useful if you need to disable them temporarily, such as for a game. The following keycodes are available for use in your `keymap.c` |Keycode |Description | |----------|---------------------------------| @@ -91,6 +111,187 @@ You can enable, disable and toggle the Combo feature on the fly. This is useful |`CMB_OFF` |Turns off Combo feature | |`CMB_TOG` |Toggles Combo feature on and off | +# Advanced Configuration +These configuration settings can be set in your `config.h` file. + +## Combo Term +By default, the timeout for the Combos to be recognized is set to 50ms. This can be changed if accidental combo misfires are happening or if you're having difficulties pressing keys at the same time. For instance, `#define COMBO_TERM 40` would set the timeout period for combos to 40ms. + +## Buffer and state sizes +If you're using long combos, or you have a lot of overlapping combos, you may run into issues with this, as the buffers may not be large enough to accommodate what you're doing. In this case, you can configure the sizes of the buffers used. Be aware, larger combo sizes and larger buffers will increase memory usage! + +To configure the amount of keys a combo can be composed of, change the following: + +| Keys | Define to be set | +|------|-----------------------------------| +| 6 | `#define EXTRA_SHORT_COMBOS` | +| 8 | QMK Default | +| 16 | `#define EXTRA_LONG_COMBOS` | +| 32 | `#define EXTRA_EXTRA_LONG_COMBOS` | + +Defining `EXTRA_SHORT_COMBOS` combines a combo's internal state into just one byte. This can, in some cases, save some memory. If it doesn't, no point using it. If you do, you also have to make sure you don't define combos with more than 6 keys. + +Processing combos has two buffers, one for the key presses, another for the combos being activated. Use the following options to configure the sizes of these buffers: + +| Define | Default | +|-------------------------------------|------------------------------------------------------| +| `#define COMBO_KEY_BUFFER_LENGTH 8` | 8 (the key amount `(EXTRA_)EXTRA_LONG_COMBOS` gives) | +| `#define COMBO_BUFFER_LENGTH 4` | 4 | + +## Modifier Combos +If a combo resolves to a Modifier, the window for processing the combo can be extended independently from normal combos. By default, this is disabled but can be enabled with `#define COMBO_MUST_HOLD_MODS`, and the time window can be configured with `#define COMBO_HOLD_TERM 150` (default: `TAPPING_TERM`). With `COMBO_MUST_HOLD_MODS`, you cannot tap the combo any more which makes the combo less prone to misfires. + +## Per Combo Timing, Holding and Tapping +For each combo, it is possible to configure the time window it has to pressed in, if it needs to be held down, or if it needs to be tapped. + +For example, tap-only combos are useful if any (or all) of the underlying keys is a Mod-Tap or a Layer-Tap key. When you tap the combo, you get the combo result. When you press the combo and hold it down, the combo doesn't actually activate. Instead the keys are processed separately as if the combo wasn't even there. + +In order to use these features, the following configuration options and functions need to be defined. Coming up with useful timings and configuration is left as an exercise for the reader. + +| Config Flag | Function | Description | +|-----------------------------|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------| +| `COMBO_TERM_PER_COMBO` | uint16_t get_combo_term(uint16_t index, combo_t \*combo) | Optional per-combo timeout window. (default: `COMBO_TERM`) | +| `COMBO_MUST_HOLD_PER_COMBO` | bool get_combo_must_hold(uint16_t index, combo_t \*combo) | Controls if a given combo should fire immediately on tap or if it needs to be held. (default: `false`) | +| `COMBO_MUST_TAP_PER_COMBO` | bool get_combo_must_tap(uint16_t index, combo_t \*combo) | Controls if a given combo should fire only if tapped within `COMBO_HOLD_TERM`. (default: `false`) | + +Examples: +```c +uint16_t get_combo_term(uint16_t index, combo_t *combo) { + // decide by combo->keycode + switch (combo->keycode) { + case KC_X: + return 50; + } + + // or with combo index, i.e. its name from enum. + switch (index) { + case COMBO_NAME_HERE: + return 9001; + } + + // And if you're feeling adventurous, you can even decide by the keys in the chord, + // i.e. the exact array of keys you defined for the combo. + // This can be useful if your combos have a common key and you want to apply the + // same combo term for all of them. + if (combo->keys[0] == KC_ENTER) { // if first key in the array is KC_ENTER + return 150; + } + + return COMBO_TERM; +} + +bool get_combo_must_hold(uint16_t index, combo_t *combo) { + // Same as above, decide by keycode, the combo index, or by the keys in the chord. + + if (KEYCODE_IS_MOD(combo->keycode) || + (combo->keycode >= QK_MOMENTARY && combo->keycode <= QK_MOMENTARY_MAX) // MO(kc) keycodes + ) { + return true; + } + + switch (index) { + case COMBO_NAME_HERE: + return true; + } + + return false; +} + +bool get_combo_must_tap(uint16_t index, combo_t *combo) { + // If you want all combos to be tap-only, just uncomment the next line + // return true + + // If you want *all* combos, that have Mod-Tap/Layer-Tap/Momentary keys in its chord, to be tap-only, this is for you: + uint16_t key; + uint8_t idx = 0; + while ((key = pgm_read_word(&combo->keys[idx])) != COMBO_END) { + switch (key) { + case QK_MOD_TAP...QK_MOD_TAP_MAX: + case QK_LAYER_TAP...QK_LAYER_TAP_MAX: + case QK_MOMENTARY...QK_MOMENTARY_MAX: + return true; + } + idx += 1; + } + return false; + +} +``` + +## Variable Length Combos +If you leave `COMBO_COUNT` undefined in `config.h`, it allows you to programmatically declare the size of the Combo data structure and avoid updating `COMBO_COUNT`. Instead a variable called `COMBO_LEN` has to be set. It can be set with something similar to the following in `keymap.c`: `uint16_t COMBO_LEN = sizeof(key_combos) / sizeof(key_combos[0]);` or by adding `COMBO_LENGTH` as the *last* entry in the combo enum and then `uint16_t COMBO_LEN = COMBO_LENGTH;` as such: +```c +enum myCombos { + ..., + COMBO_LENGTH +}; +uint16_t COMBO_LEN = COMBO_LENGTH; +``` +Regardless of the method used to declare `COMBO_LEN`, this also requires to convert the `combo_t key_combos[COMBO_COUNT] = {...};` line to `combo_t key_combos[] = {...};`. + + +## Combo timer + +Normally, the timer is started on the first key press and then reset on every subsequent key press within the `COMBO_TERM`. +Inputting combos is relaxed like this, but also slightly more prone to accidental misfires. + +The next two options alter the behaviour of the timer. + +### `#define COMBO_STRICT_TIMER` + +With `COMBO_STRICT_TIMER`, the timer is started only on the first key press. +Inputting combos is now less relaxed; you need to make sure the full chord is pressed within the `COMBO_TERM`. +Misfires are less common but if you type multiple combos fast, there is a +chance that the latter ones might not activate properly. + +### `#define COMBO_NO_TIMER` + +By defining `COMBO_NO_TIMER`, the timer is disabled completely and combos are activated on the first key release. +This also disables the "must hold" functionalities as they just wouldn't work at all. + +## Customizable key releases + +By defining `COMBO_PROCESS_KEY_RELEASE` and implementing the function `bool process_combo_key_release(uint16_t combo_index, combo_t *combo, uint8_t key_index, uint16_t keycode)`, you can run your custom code on each key release after a combo was activated. For example you could change the RGB colors, activate haptics, or alter the modifiers. + +You can also release a combo early by returning `true` from the function. + +Here's an example where a combo resolves to two modifiers, and on key releases the modifiers are unregistered one by one, depending on which key was released. + +```c +enum combos { + AB_MODS, + COMBO_LENGTH +}; +uint16_t COMBO_LEN = COMBO_LENGTH; + +const uint16_t PROGMEM ab_combo[] = {KC_A, KC_B, COMBO_END}; + +combo_t key_combos[] = { + [AB_MODS] = COMBO(ab_combo, LCTL(KC_LSFT)), +}; + +bool process_combo_key_release(uint16_t combo_index, combo_t *combo, uint8_t key_index, uint16_t keycode) { + switch (combo_index) { + case AB_MODS: + switch(keycode) { + case KC_A: + unregister_mods(MOD_MASK_CTRL); + break; + case KC_B: + unregister_mods(MOD_MASK_SHIFT); + break; + } + return false; // do not release combo + } + return false; +} +``` +## Layer independent combos + +If you, for example, use multiple base layers for different key layouts, one for QWERTY, and another one for Colemak, you might want your combos to work from the same key positions on all layers. Defining the same combos again for another layout is redundant and takes more memory. The solution is to just check the keycodes from one layer. + +With `#define COMBO_ONLY_FROM_LAYER _LAYER_A` the combos' keys are always checked from layer `_LAYER_A` even though the active layer would be `_LAYER_B`. + ## User callbacks In addition to the keycodes, there are a few functions that you can use to set the status, or check it: @@ -101,3 +302,28 @@ In addition to the keycodes, there are a few functions that you can use to set t | `combo_disable()` | Disables the combo feature, and clears the combo buffer | | `combo_toggle()` | Toggles the state of the combo feature | | `is_combo_enabled()` | Returns the status of the combo feature state (true or false) | + + +# Dictionary Management + +Having 3 places to update when adding new combos or altering old ones does become cumbersome when you have a lot of combos. We can alleviate this with some magic! ... If you consider C macros magic. +First, you need to add `VPATH += keyboards/gboards` to your `rules.mk`. Next, include the file `g/keymap_combo.h` in your `keymap.c`. + +!> This functionality uses the same `process_combo_event` function as `COMBO_ACTION` macros do, so you cannot use the function yourself in your keymap. Instead, you have to define the `case`s of the `switch` statement by themselves within `inject.h`, which `g/keymap_combo.h` will then include into the function. + +Then, write your combos in `combos.def` file in the following manner: + +```c +// name result chord keys +COMB(AB_ESC, KC_ESC, KC_A, KC_B) +COMB(JK_TAB, KC_TAB, KC_J, KC_K) +COMB(JKL_SPC, KC_SPC, KC_J, KC_K, KC_L) +COMB(BSSL_CLR, KC_NO, KC_BSPC, KC_LSFT) // using KC_NO as the resulting keycode is the same as COMBO_ACTION before. +COMB(QW_UNDO, C(KC_Z), KC_Q, KC_W) +SUBS(TH_THE, "the", KC_T, KC_H) // SUBS uses SEND_STRING to output the given string. +... +``` + +Now, you can update only one place to add or alter combos. You don't even need to remember to update the `COMBO_COUNT` or the `COMBO_LEN` variables at all. Everything is taken care of. Magic! + +For small to huge ready made dictionaries of combos, you can check out http://combos.gboards.ca/. -- cgit v1.2.3 From 610035dce8f4f7010779e61e1cb590eebc8cea46 Mon Sep 17 00:00:00 2001 From: Sergey Vlasov Date: Sat, 7 Aug 2021 02:16:26 +0300 Subject: Add HOLD_ON_OTHER_KEY_PRESS option for dual-role keys (#9404) * Add HOLD_ON_OTHER_KEY_PRESS option for dual-role keys Implement an additional option for dual-role keys which converts the dual-role key press into a hold action immediately when another key is pressed (this is different from the existing PERMISSIVE_HOLD option, which selects the hold action when another key is tapped (pressed and then released) while the dual-role key is pressed). The Mod-Tap keys already behave in a similar way, unless the IGNORE_MOD_TAP_INTERRUPT option is enabled (but with some additional delays); the added option makes this behavior available for all other kinds of dual-role keys. * [Docs] Update tap-hold docs for HOLD_ON_OTHER_KEY_PRESS Document the newly added HOLD_ON_OTHER_KEY_PRESS option and update the documentation for closely related options (PERMISSIVE_HOLD and IGNORE_MOD_TAP_INTERRUPT). Use Layer Tap instead of Mod Tap in examples for PERMISSIVE_HOLD and HOLD_ON_OTHER_KEY_PRESS, because the effect of using these options with Mod Tap keys is mostly invisible without IGNORE_MOD_TAP_INTERRUPT. Add comments before return statements in sample implementations of `get_ignore_mod_tap_interrupt()`, `get_hold_on_other_key_press()` and `get_permissive_hold()`. Thanks to @Erovia and @precondition for comments and suggestions to improve the documentation. --- docs/tap_hold.md | 108 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 89 insertions(+), 19 deletions(-) (limited to 'docs') diff --git a/docs/tap_hold.md b/docs/tap_hold.md index 085bbde16a..71bff30baa 100644 --- a/docs/tap_hold.md +++ b/docs/tap_hold.md @@ -36,29 +36,49 @@ uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) { } ``` +## Tap-Or-Hold Decision Modes -## Permissive Hold +The code which decides between the tap and hold actions of dual-role keys supports three different modes, in increasing order of preference for the hold action: -As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new `config.h` option: +1. The default mode selects the hold action only if the dual-role key is held down longer than the tapping term. In this mode pressing other keys while the dual-role key is held down does not influence the tap-or-hold decision. + +2. The “permissive hold” mode, in addition to the default behavior, immediately selects the hold action when another key is tapped (pressed and then released) while the dual-role key is held down, even if this happens earlier than the tapping term. If another key is just pressed, but then the dual-role key is released before that other key (and earlier than the tapping term), this mode will still select the tap action. + +3. The “hold on other key press” mode, in addition to the default behavior, immediately selects the hold action when another key is pressed while the dual-role key is held down, even if this happens earlier than the tapping term. + +Note that until the tap-or-hold decision completes (which happens when either the dual-role key is released, or the tapping term has expired, or the extra condition for the selected decision mode is satisfied), key events are delayed and not transmitted to the host immediately. The default mode gives the most delay (if the dual-role key is held down, this mode always waits for the whole tapping term), and the other modes may give less delay when other keys are pressed, because the hold action may be selected earlier. + +### Permissive Hold + +The “permissive hold” mode can be enabled for all dual-role keys by adding the corresponding option to `config.h`: ```c #define PERMISSIVE_HOLD ``` -This makes tap and hold keys (like Mod Tap) work better for fast typists, or for high `TAPPING_TERM` settings. +This makes tap and hold keys (like Layer Tap) work better for fast typists, 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. +If you press a dual-role key, tap another key (press and release) and then release the dual-role key, all within the tapping term, by default the dual-role key will perform its tap action. If the `PERMISSIVE_HOLD` option is enabled, the dual-role key will perform its hold action instead. -For Instance: +An example of a sequence which is affected by the “permissive hold” mode: -- `SFT_T(KC_A)` Down -- `KC_X` Down -- `KC_X` Up -- `SFT_T(KC_A)` Up +- `LT(2, KC_A)` Down +- `KC_L` Down (the `L` key is also mapped to `KC_RGHT` on layer 2) +- `KC_L` Up +- `LT(2, KC_A)` Up + +Normally, if you do all this within the `TAPPING_TERM` (default: 200ms), this will be registered as `al` by the firmware and host system. With the `PERMISSIVE_HOLD` option enabled, the Layer Tap key is considered as a layer switch if another key is tapped, and the above sequence would be registered as `KC_RGHT` (the mapping of `L` on layer 2). + +However, this slightly different sequence will not be affected by the “permissive hold” mode: -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`). +- `LT(2, KC_A)` Down +- `KC_L` Down (the `L` key is also mapped to `KC_RGHT` on layer 2) +- `LT(2, KC_A)` Up +- `KC_L` Up -?> 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`. +In the sequence above the dual-role key is released before the other key is released, and if that happens within the tapping term, the “permissive hold” mode will still choose the tap action for the dual-role key, and the sequence will be registered as `al` by the host. + +?> The `PERMISSIVE_HOLD` option also affects Mod Tap keys, but this may not be noticeable if you do not also enable the `IGNORE_MOD_TAP_INTERRUPT` option for those keys, because the default handler for Mod Tap keys also considers both the “nested press” and “rolling press” sequences like shown above as a modifier hold, not the tap action. If you do not enable `IGNORE_MOD_TAP_INTERRUPT`, the effect of `PERMISSIVE_HOLD` on Mod Tap keys would be limited to reducing the delay before the key events are made visible to the host. For more granular control of this feature, you can add the following to your `config.h`: @@ -72,13 +92,60 @@ You can then add the following function to your keymap: bool get_permissive_hold(uint16_t keycode, keyrecord_t *record) { switch (keycode) { case LT(1, KC_BSPC): + // Immediately select the hold action when another key is tapped. + return true; + default: + // Do not select the hold action when another key is tapped. + return false; + } +} +``` + +### Hold On Other Key Press + +The “hold on other key press” mode can be enabled for all dual-role keys by adding the corresponding option to `config.h`: + +```c +#define HOLD_ON_OTHER_KEY_PRESS +``` + +This mode makes tap and hold keys (like Layer Tap) work better for fast typists, or for high `TAPPING_TERM` settings. Compared to the “permissive hold” mode, this mode selects the hold action in more cases. + +If you press a dual-role key, press another key, and then release the dual-role key, all within the tapping term, by default the dual-role key will perform its tap action. If the `HOLD_ON_OTHER_KEY_PRESS` option is enabled, the dual-role key will perform its hold action instead. + +An example of a sequence which is affected by the “hold on other key press” mode, but not by the “permissive hold” mode: + +- `LT(2, KC_A)` Down +- `KC_L` Down (the `L` key is also mapped to `KC_RGHT` on layer 2) +- `LT(2, KC_A)` Up +- `KC_L` Up + +Normally, if you do all this within the `TAPPING_TERM` (default: 200ms), this will be registered as `al` by the firmware and host system. With the `HOLD_ON_OTHER_KEY_PRESS` option enabled, the Layer Tap key is considered as a layer switch if another key is pressed, and the above sequence would be registered as `KC_RGHT` (the mapping of `L` on layer 2). + +?> The `HOLD_ON_OTHER_KEY_PRESS` option also affects Mod Tap keys, but this may not be noticeable if you do not also enable the `IGNORE_MOD_TAP_INTERRUPT` option for those keys, because the default handler for Mod Tap keys also considers the “rolling press” sequence like shown above as a modifier hold, not the tap action. If you do not enable `IGNORE_MOD_TAP_INTERRUPT`, the effect of `HOLD_ON_OTHER_KEY_PRESS` on Mod Tap keys would be limited to reducing the delay before the key events are made visible to the host. + +For more granular control of this feature, you can add the following to your `config.h`: + +```c +#define HOLD_ON_OTHER_KEY_PRESS_PER_KEY +``` + +You can then add the following function to your keymap: + +```c +bool get_hold_on_other_key_press(uint16_t keycode, keyrecord_t *record) { + switch (keycode) { + case LT(1, KC_BSPC): + // Immediately select the hold action when another key is pressed. return true; default: + // Do not select the hold action when another key is pressed. return false; } } ``` + ## Ignore Mod Tap Interrupt To enable this setting, add this to your `config.h`: @@ -87,23 +154,22 @@ To enable this setting, add this to your `config.h`: #define IGNORE_MOD_TAP_INTERRUPT ``` -Similar to Permissive Hold, this alters how the firmware processes inputs for fast typists. 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 Mod plus the normal key, even if pressed within the `TAPPING_TERM`. This may not be desirable for rolling combo keys, or for fast typists who have a Mod Tap on a frequently used key (`RCTL_T(KC_QUOT)`, for example). +?> This option affects only the Mod Tap keys; it does not affect other dual-role keys such as Layer Tap. + +By default the tap-or-hold decision for Mod Tap keys strongly prefers the hold action. If you press a Mod Tap key, then press another key while still holding the Mod Tap key down, the Mod Tap press will be handled as a modifier hold even if the Mod Tap key is then released within the tapping term, and irrespective of the order in which those keys are released. Using options such as `PERMISSIVE_HOLD` or `HOLD_ON_OTHER_KEY_PRESS` will not affect the functionality of Mod Tap keys in a major way (these options would still affect the delay until the common code for dual-role keys finishes its tap-or-hold decision, but then the special code for Mod Tap keys will override the result of that decision and choose the hold action if another key was pressed). In fact, by default the tap-or-hold decision for Mod Tap keys is done in the same way as if the `HOLD_ON_OTHER_KEY_PRESS` option was enabled, but without the decreased delay provided by `HOLD_ON_OTHER_KEY_PRESS`. -Setting `Ignore Mod Tap Interrupt` requires holding both keys for the `TAPPING_TERM` to trigger the hold function (the mod). +If the `IGNORE_MOD_TAP_INTERRUPT` option is enabled, Mod Tap keys are no longer treated as a special case, and their behavior will match the behavior of other dual-role keys such as Layer Tap. Then the behavior of Mod Tap keys can be further tuned using other options such as `PERMISSIVE_HOLD` or `HOLD_ON_OTHER_KEY_PRESS`. -For Instance: +An example of a sequence which will be affected by the `IGNORE_MOD_TAP_INTERRUPT` option (assuming that options like `PERMISSIVE_HOLD` or `HOLD_ON_OTHER_KEY_PRESS` are not enabled): - `SFT_T(KC_A)` Down - `KC_X` Down - `SFT_T(KC_A)` Up - `KC_X` Up -Normally, this would send a capital `X` (`SHIFT`+`x`), or, Mod + key. 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 capital `X` (`SHIFT`+`x`). - - -?> __Note__: This only concerns modifiers and not layer switching keys. +Normally, this would send a capital `X` (`SHIFT`+`x`), even if the sequence is performed faster than the `TAPPING_TERM`. However, if the `IGNORE_MOD_TAP_INTERRUPT` option is enabled, the `SFT_T(KC_A)` key must be held longer than the `TAPPING_TERM` to register the hold action. A quick tap will output `ax` in this case, while a hold will still output a capital `X` (`SHIFT`+`x`). -?> 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`. +However, if the `HOLD_ON_OTHER_KEY_PRESS` option is enabled in addition to `IGNORE_MOD_TAP_INTERRUPT`, the above sequence will again send a capital `X` (`SHIFT`+`x`) even if performed faster that the `TAPPING_TERM`. The difference from the default configuration is that by default the host will receive the key events only after the `SFT_T(KC_A)` key is released, but with the `HOLD_ON_OTHER_KEY_PRESS` option the host will start receiving key events when the `KC_X` key is pressed. For more granular control of this feature, you can add the following to your `config.h`: @@ -117,8 +183,12 @@ You can then add the following function to your keymap: bool get_ignore_mod_tap_interrupt(uint16_t keycode, keyrecord_t *record) { switch (keycode) { case SFT_T(KC_SPC): + // Do not force the mod-tap key press to be handled as a modifier + // if any other key was pressed while the mod-tap key is held down. return true; default: + // Force the mod-tap key press to be handled as a modifier if any + // other key was pressed while the mod-tap key is held down. return false; } } -- cgit v1.2.3 From a03aa301def77c867ae6c6c840f7fc82b26d91d6 Mon Sep 17 00:00:00 2001 From: James Young <18669334+noroadsleft@users.noreply.github.com> Date: Fri, 6 Aug 2021 23:59:56 -0700 Subject: Remove Full Bootmagic (#13846) * disambiguate Bootmagic rules in keymaps The files edited by this commit were added at a point in time where `BOOTMAGIC_ENABLE = yes` enabled full Bootmagic. This commit edits the files to specify that full Bootmagic is intended. * remove BOOTMAGIC_ENABLE=full setting * unify commented BOOTMAGIC_ENABLE rules in keyboards Explicitly sets `BOOTMAGIC_ENABLE = no` in keyboards where the rule was commented out. Command: ``` find keyboards/ -type f -name 'rules.mk' -and -not -path '*/keymaps/*' -exec sed -i -e 's;#[ \t]*\(BOOTMAGIC_ENABLE\)[ \t=]\+\([a-zA-Z]\+\).*;\1 = no # Virtual DIP switch configuration;g' {} + ``` * remove commented Bootmagic rules from keymap/user level Command: ``` find keyboards/ layouts/ users/ -type f -name 'rules.mk' -exec sed -i -e '/#.*\(BOOTMAGIC_ENABLE\)[ \t=]\+\([a-z]\+\).*/d' {} + ``` * update keyboard BOOTMAGIC_ENABLE rule formatting Sets the formatting of BOOTMAGIC_ENABLE rules to `BOOTMAGIC_ENABLE = [value]`, without the inline comments (which will be replaced later). Command: ``` find keyboards/ -type f -name 'rules.mk' -and -not -path '*/keymaps/*' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE\)[ \t=]\+\([a-z]\+\).*;\1 = \2;g' '{}' + ``` * update keyboards' BOOTMAGIC_ENABLE settings Updates keyboard `rules.mk` files to use `BOOTMAGIC_ENABLE = lite` where `BOOTMAGIC_ENABLE = full` was being used. Command: ``` find keyboards/ -type f -name 'rules.mk' -and -not -path '*/keymaps/*' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE = \)full;\1lite;g' '{}' + ``` * update keymap/user BOOTMAGIC_ENABLE settings Updates keymap/user `rules.mk` files to use `BOOTMAGIC_ENABLE = lite` where `BOOTMAGIC_ENABLE = full` was being used. Commands: ``` find keyboards/ -type f -name 'rules.mk' -and -path '*/keymaps/*' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE[ \t=]\+\)full;\1lite;g' '{}' + find layouts/community/ users/ -type f -name 'rules.mk' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE[ \t=]\+\)full;\1lite;g' '{}' + ``` * remove and replace inline comments in keyboards and keymap/user files Removes and replaces the inline comments, which have been updated to read `Enable Bootmagic Lite`. Commands: ``` find keyboards/ -type f -name 'rules.mk' -and -path '*/keymaps/*' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE\)[ \t=]\+\([a-z]\+\).*;\1 = \2;g' '{}' + find layouts/community/ users/ -type f -name 'rules.mk' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE\)[ \t=]\+\([a-z]\+\).*;\1 = \2;g' '{}' + find keyboards/ layouts/community/ users/ -type f -name 'rules.mk' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE = lite\);\1 # Enable Bootmagic Lite;g' '{}' + find keyboards/ layouts/community/ users/ -type f -name 'rules.mk' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE = yes\);\1 # Enable Bootmagic Lite;g' '{}' + find keyboards/ layouts/community/ users/ -type f -name 'rules.mk' -exec sed -i -e 's;\(BOOTMAGIC_ENABLE = no\);\1 # Enable Bootmagic Lite;g' '{}' + ``` * rename improperly named makefiles Some files intended to be used as makefiles had improper names causing them to not be used as intended when building. This commit corrects the filenames of the affected files. * update renamed file with new rule formatting * update QMK's template files Updates QMK's `rules.mk` templates to use the new inline comment. * update QMK Docs - remove documentation of full Bootmagic - update links to Bootmagic Lite doc - add doc for Magic Keycodes * rules.mk patch for coarse/ixora and coarse/vinta --- docs/_summary.md | 3 +- docs/custom_quantum_functions.md | 2 +- docs/driver_installation_zadig.md | 4 +- docs/faq_keymap.md | 2 +- docs/feature_bootmagic.md | 141 ++++------------------------------- docs/feature_command.md | 2 +- docs/flashing.md | 4 +- docs/hardware_keyboard_guidelines.md | 4 +- docs/keycodes.md | 72 +++++++++--------- docs/keycodes_magic.md | 35 +++++++++ docs/ref_functions.md | 2 +- docs/syllabus.md | 2 +- 12 files changed, 97 insertions(+), 176 deletions(-) create mode 100644 docs/keycodes_magic.md (limited to 'docs') diff --git a/docs/_summary.md b/docs/_summary.md index 6c39aeda09..7e6c062136 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -60,6 +60,7 @@ * [Language-Specific Keycodes](reference_keymap_extras.md) * [Modifier Keys](feature_advanced_keycodes.md) * [Quantum Keycodes](quantum_keycodes.md) + * [Magic Keycodes](keycodes_magic.md) * Advanced Keycodes * [Command](feature_command.md) @@ -103,7 +104,7 @@ * [RGB Matrix](feature_rgb_matrix.md) * [Audio](feature_audio.md) * [Bluetooth](feature_bluetooth.md) - * [Bootmagic](feature_bootmagic.md) + * [Bootmagic Lite](feature_bootmagic.md) * [Custom Matrix](custom_matrix.md) * [DIP Switch](feature_dip_switch.md) * [Encoders](feature_encoders.md) diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index 30c637bb49..494e76996e 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -382,7 +382,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. +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 Lite](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! diff --git a/docs/driver_installation_zadig.md b/docs/driver_installation_zadig.md index e4db069f1d..137ec8ad64 100644 --- a/docs/driver_installation_zadig.md +++ b/docs/driver_installation_zadig.md @@ -8,8 +8,8 @@ We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have ## Installation -Put your keyboard into bootloader mode, either by hitting the `RESET` keycode (which may be on a different layer), or by pressing the reset switch that's usually located on the underside of the board. If your keyboard has neither, try holding Escape or Space+`B` as you plug it in (see the [Bootmagic](feature_bootmagic.md) docs for more details). Some boards use [Command](feature_command.md) instead of Bootmagic; in this case, you can enter bootloader mode by hitting Left Shift+Right Shift+`B` or Left Shift+Right Shift+Escape at any point while the keyboard is plugged in. -Some keyboards may have specific instructions for entering the bootloader. For example, the [Bootmagic Lite](feature_bootmagic.md#bootmagic-lite) key (default: Escape) might be on a different key, e.g. Left Control; or the magic combination for Command (default: Left Shift+Right Shift) might require you to hold something else, e.g. Left Control+Right Control. Refer to the board's README file if you are unsure. +Put your keyboard into bootloader mode, either by hitting the `RESET` keycode (which may be on a different layer), or by pressing the reset switch that's usually located on the underside of the board. If your keyboard has neither, try holding Escape or Space+`B` as you plug it in (see the [Bootmagic Lite](feature_bootmagic.md) docs for more details). Some boards use [Command](feature_command.md) instead of Bootmagic; in this case, you can enter bootloader mode by hitting Left Shift+Right Shift+`B` or Left Shift+Right Shift+Escape at any point while the keyboard is plugged in. +Some keyboards may have specific instructions for entering the bootloader. For example, the [Bootmagic Lite](feature_bootmagic.md) key (default: Escape) might be on a different key, e.g. Left Control; or the magic combination for Command (default: Left Shift+Right Shift) might require you to hold something else, e.g. Left Control+Right Control. Refer to the board's README file if you are unsure. To put a device in bootloader mode with USBaspLoader, tap the `RESET` button while holding down the `BOOT` button. Alternatively, hold `BOOT` while inserting the USB cable. diff --git a/docs/faq_keymap.md b/docs/faq_keymap.md index c30e17990f..3de4cd2409 100644 --- a/docs/faq_keymap.md +++ b/docs/faq_keymap.md @@ -31,7 +31,7 @@ QMK has two features, Bootmagic and Command, which allow you to change the behav As a quick fix try holding down `Space`+`Backspace` while you plug in your keyboard. This will reset the stored settings on your keyboard, returning those keys to normal operation. If that doesn't work look here: -* [Bootmagic](feature_bootmagic.md) +* [Bootmagic Lite](feature_bootmagic.md) * [Command](feature_command.md) ## The Menu Key Isn't Working diff --git a/docs/feature_bootmagic.md b/docs/feature_bootmagic.md index 4c655d8e1c..6c66b00679 100644 --- a/docs/feature_bootmagic.md +++ b/docs/feature_bootmagic.md @@ -1,136 +1,15 @@ -# Bootmagic - -There are three separate but related features that allow you to change the behavior of your keyboard without reflashing. While each of them have similar functionality, it is accessed in different ways depending on how your keyboard is configured. - -**Bootmagic** is a system for configuring your keyboard while it initializes. To trigger a Bootmagic command, hold down the Bootmagic key and one or more command keys. - -**Bootmagic Keycodes** are prefixed with `MAGIC_`, and allow you to access the Bootmagic functionality *after* your keyboard has initialized. To use the keycodes, assign them to your keymap as you would any other keycode. - -**Command**, formerly known as **Magic**, is another feature that allows you to control different aspects of your keyboard. While it shares some functionality with Bootmagic, it also allows you to do things that Bootmagic does not, such as printing version information to the console. For more information, see [Command](feature_command.md). - -On some keyboards Bootmagic is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk` with: - -```make -BOOTMAGIC_ENABLE = full -``` - -?> You may see `yes` being used in place of `full`, and this is okay. However, `yes` is deprecated, and ideally `full` (or `lite`) should be used instead. - -Additionally, you can use [Bootmagic Lite](#bootmagic-lite) (a scaled down, very basic version of Bootmagic) by adding the following to your `rules.mk` file: - -```make -BOOTMAGIC_ENABLE = lite -``` - -## Hotkeys - -Hold down the Bootmagic key (Space by default) and the desired hotkey while plugging in your keyboard. For example, holding Space+`B` should cause it to enter the bootloader. - -|Hotkey |Description | -|------------------|---------------------------------------------| -|Escape |Ignore Bootmagic configuration in EEPROM | -|`B` |Enter the bootloader | -|`D` |Toggle debugging over serial | -|`X` |Toggle key matrix debugging | -|`K` |Toggle keyboard debugging | -|`M` |Toggle mouse debugging | -|`L` |Set "Left Hand" for EE_HANDS handedness | -|`R` |Set "Right Hand" for EE_HANDS handedness | -|Backspace |Clear the EEPROM | -|Caps Lock |Toggle treating Caps Lock as Left Control | -|Left Control |Toggle swapping Caps Lock and Left Control | -|Left Alt |Toggle swapping Left Alt and Left GUI | -|Right Alt |Toggle swapping Right Alt and Right GUI | -|Left GUI |Toggle the GUI keys (useful when gaming) | -|`|Toggle swapping ` and Escape| -|`\` |Toggle swapping `\` and Backspace | -|`N` |Toggle N-Key Rollover (NKRO) | -|`0` |Make layer 0 the default layer | -|`1` |Make layer 1 the default layer | -|`2` |Make layer 2 the default layer | -|`3` |Make layer 3 the default layer | -|`4` |Make layer 4 the default layer | -|`5` |Make layer 5 the default layer | -|`6` |Make layer 6 the default layer | -|`7` |Make layer 7 the default layer | - -## Keycodes :id=keycodes - -|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 - -If you would like to change the hotkey assignments for Bootmagic, `#define` these in your `config.h` at either the keyboard or keymap level. - -|Define |Default |Description | -|----------------------------------------|-------------|---------------------------------------------------| -|`BOOTMAGIC_KEY_SALT` |`KC_SPACE` |The Bootmagic key | -|`BOOTMAGIC_KEY_SKIP` |`KC_ESC` |Ignore Bootmagic configuration in EEPROM | -|`BOOTMAGIC_KEY_EEPROM_CLEAR` |`KC_BSPACE` |Clear the EEPROM configuration | -|`BOOTMAGIC_KEY_BOOTLOADER` |`KC_B` |Enter the bootloader | -|`BOOTMAGIC_KEY_DEBUG_ENABLE` |`KC_D` |Toggle debugging over serial | -|`BOOTMAGIC_KEY_DEBUG_MATRIX` |`KC_X` |Toggle matrix debugging | -|`BOOTMAGIC_KEY_DEBUG_KEYBOARD` |`KC_K` |Toggle keyboard debugging | -|`BOOTMAGIC_KEY_DEBUG_MOUSE` |`KC_M` |Toggle mouse debugging | -|`BOOTMAGIC_KEY_EE_HANDS_LEFT` |`KC_L` |Set "Left Hand" for EE_HANDS handedness | -|`BOOTMAGIC_KEY_EE_HANDS_RIGHT` |`KC_R` |Set "Right Hand" for EE_HANDS handedness | -|`BOOTMAGIC_KEY_SWAP_CONTROL_CAPSLOCK` |`KC_LCTRL` |Swap Left Control and Caps Lock | -|`BOOTMAGIC_KEY_CAPSLOCK_TO_CONTROL` |`KC_CAPSLOCK`|Toggle treating Caps Lock as Left Control | -|`BOOTMAGIC_KEY_SWAP_LALT_LGUI` |`KC_LALT` |Toggle swapping Left Alt and Left GUI (for macOS) | -|`BOOTMAGIC_KEY_SWAP_RALT_RGUI` |`KC_RALT` |Toggle swapping Right Alt and Right GUI (for macOS)| -|`BOOTMAGIC_KEY_NO_GUI` |`KC_LGUI` |Toggle the GUI keys (useful when gaming) | -|`BOOTMAGIC_KEY_SWAP_GRAVE_ESC` |`KC_GRAVE` |Toggle swapping ` and Escape | -|`BOOTMAGIC_KEY_SWAP_BACKSLASH_BACKSPACE`|`KC_BSLASH` |Toggle swapping `\` and Backspace | -|`BOOTMAGIC_HOST_NKRO` |`KC_N` |Toggle N-Key Rollover (NKRO) | -|`BOOTMAGIC_KEY_DEFAULT_LAYER_0` |`KC_0` |Make layer 0 the default layer | -|`BOOTMAGIC_KEY_DEFAULT_LAYER_1` |`KC_1` |Make layer 1 the default layer | -|`BOOTMAGIC_KEY_DEFAULT_LAYER_2` |`KC_2` |Make layer 2 the default layer | -|`BOOTMAGIC_KEY_DEFAULT_LAYER_3` |`KC_3` |Make layer 3 the default layer | -|`BOOTMAGIC_KEY_DEFAULT_LAYER_4` |`KC_4` |Make layer 4 the default layer | -|`BOOTMAGIC_KEY_DEFAULT_LAYER_5` |`KC_5` |Make layer 5 the default layer | -|`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 :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. +The Bootmagic Lite feature that only handles jumping into the bootloader. This is great for boards that don't have a physical reset button, giving you a way to jump into the bootloader -To enable this version of Bootmagic, you need to enable it in your `rules.mk` with: +On some keyboards Bootmagic Lite is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk` with: ```make -BOOTMAGIC_ENABLE = lite +BOOTMAGIC_ENABLE = yes ``` +?> You may see `lite` being used in place of `yes`. + 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 @@ -142,7 +21,7 @@ By default, these are set to 0 and 0, which is usually the "ESC" key on a majori And to trigger the bootloader, you hold this key down when plugging the keyboard in. Just the single key. -!> Using bootmagic lite will **always reset** the EEPROM, so you will lose any settings that have been saved. +!> Using Bootmagic Lite will **always reset** the EEPROM, so you will lose any settings that have been saved. ## Split Keyboards @@ -174,4 +53,10 @@ 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 Lite. Keep in mind that `bootmagic_lite` is called before a majority of features are initialized in the firmware. + +## Addenda + +To manipulate settings that were formerly configured through the now-deprecated full Bootmagic feature, see [Magic Keycodes](keycodes_magic.md). + +The Command feature, formerly known as Magic, also allows you to control different aspects of your keyboard. While it shares some functionality with Magic Keycodes, it also allows you to do things that Magic Keycodes cannot, such as printing version information to the console. For more information, see [Command](feature_command.md). diff --git a/docs/feature_command.md b/docs/feature_command.md index a4ce3f5aea..8300066131 100644 --- a/docs/feature_command.md +++ b/docs/feature_command.md @@ -1,6 +1,6 @@ # Command -Command, formerly known as Magic, is a way to change your keyboard's behavior without having to flash or unplug it to use [Bootmagic](feature_bootmagic.md). There is a lot of overlap between this functionality and the [Bootmagic Keycodes](feature_bootmagic.md#keycodes). Wherever possible we encourage you to use that feature instead of Command. +Command, formerly known as Magic, is a way to change your keyboard's behavior without having to flash or unplug it to use [Bootmagic Lite](feature_bootmagic.md). There is a lot of overlap between this functionality and the [Magic Keycodes](keycodes_magic.md). Wherever possible we encourage you to use that feature instead of Command. On some keyboards Command is disabled by default. If this is the case, it must be explicitly enabled in your `rules.mk`: diff --git a/docs/flashing.md b/docs/flashing.md index da3c64c4a4..fae9c5d1c4 100644 --- a/docs/flashing.md +++ b/docs/flashing.md @@ -48,7 +48,7 @@ QMK maintains [a fork of the LUFA DFU bootloader](https://github.com/qmk/lufa/tr //#define QMK_LED E6 //#define QMK_SPEAKER C6 ``` -Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md#bootmagic-lite), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader. +Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader. The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string. @@ -192,7 +192,7 @@ To enable the additional features, add the following defines to your `config.h`: //#define QMK_SPEAKER C6 ``` -Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md#bootmagic-lite), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader. +Currently we do not recommend making `QMK_ESC` the same key as the one designated for [Bootmagic Lite](feature_bootmagic.md), as holding it down will cause the MCU to loop back and forth between entering and exiting the bootloader. The manufacturer and product strings are automatically pulled from `config.h`, with " Bootloader" appended to the product string. diff --git a/docs/hardware_keyboard_guidelines.md b/docs/hardware_keyboard_guidelines.md index 4f32715046..7630b44e0c 100644 --- a/docs/hardware_keyboard_guidelines.md +++ b/docs/hardware_keyboard_guidelines.md @@ -189,9 +189,9 @@ Hardware files (such as plates, cases, pcb) can be contributed to the [qmk.fm re Given the amount of functionality that QMK exposes it's very easy to confuse new users. When putting together the default firmware for your keyboard we recommend limiting your enabled features and options to the minimal set needed to support your hardware. Recommendations for specific features follow. -### Bootmagic and Command +### Magic Keycodes and Command -[Bootmagic](feature_bootmagic.md) and [Command](feature_command.md) are two related features that allow a user to control their keyboard in non-obvious ways. We recommend you think long and hard about if you're going to enable either feature, and how you will expose this functionality. Keep in mind that users who want this functionality can enable it in their personal keymaps without affecting all the novice users who may be using your keyboard as their first programmable board. +[Magic Keycodes](keycodes_magic.md) and [Command](feature_command.md) are two related features that allow a user to control their keyboard in non-obvious ways. We recommend you think long and hard about if you're going to enable either feature, and how you will expose this functionality. Keep in mind that users who want this functionality can enable it in their personal keymaps without affecting all the novice users who may be using your keyboard as their first programmable board. By far the most common problem new users encounter is accidentally triggering Bootmagic while they're plugging in their keyboard. They're holding the keyboard by the bottom, unknowingly pressing in alt and spacebar, and then they find that these keys have been swapped on them. We recommend leaving this feature disabled by default, but if you do turn it on consider setting `BOOTMAGIC_KEY_SALT` to a key that is hard to press while plugging your keyboard in. diff --git a/docs/keycodes.md b/docs/keycodes.md index 85988f1855..a134c5a1b2 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -257,42 +257,6 @@ See also: [Backlighting](feature_backlight.md) |`BL_DEC` |Decrease the backlight level | |`BL_BRTG`|Toggle backlight breathing | -## Bootmagic :id=bootmagic - -See also: [Bootmagic](feature_bootmagic.md) - -|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`)| - ## Bluetooth :id=bluetooth See also: [Bluetooth](feature_bluetooth.md) @@ -354,6 +318,42 @@ See also: [Leader Key](feature_leader_key.md) |---------|------------------------| |`KC_LEAD`|Begins a leader sequence| +## Magic Keycodes :id=magic-keycodes + +See also: [Magic Keycodes](keycodes_magic.md) + +|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`)| + ## MIDI :id=midi See also: [MIDI](feature_midi.md) diff --git a/docs/keycodes_magic.md b/docs/keycodes_magic.md new file mode 100644 index 0000000000..719d820312 --- /dev/null +++ b/docs/keycodes_magic.md @@ -0,0 +1,35 @@ +# Magic Keycodes :id=magic-keycodes + +**Magic Keycodes** are prefixed with `MAGIC_`, and allow you to access the functionality of the deprecated Bootmagic feature *after* your keyboard has initialized. To use the keycodes, assign them to your keymap as you would any other keycode. + +|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`)| diff --git a/docs/ref_functions.md b/docs/ref_functions.md index 27ae95aa93..c6185c8703 100644 --- a/docs/ref_functions.md +++ b/docs/ref_functions.md @@ -93,7 +93,7 @@ And to do so, add `reset_keyboard()` to your function or macro, and this will re ## Wiping the EEPROM (Persistent Storage) -If you're having issues with Audio, RGB Underglow, backlighting or keys acting weird, then you can reset the EEPROM (persistent setting storage). To force an EEPROM reset, use the [`EEP_RST` keycode](quantum_keycodes.md) or [Bootmagic](feature_bootmagic.md) functionality. If neither of those are an option, then you can use a custom macro to do so. +If you're having issues with Audio, RGB Underglow, backlighting or keys acting weird, then you can reset the EEPROM (persistent setting storage). To force an EEPROM reset, use the [`EEP_RST` keycode](quantum_keycodes.md) or [Bootmagic Lite](feature_bootmagic.md) functionality. If neither of those are an option, then you can use a custom macro to do so. To wipe the EEPROM, run `eeconfig_init()` from your function or macro to reset most of the settings to default. diff --git a/docs/syllabus.md b/docs/syllabus.md index b33bd9e727..ccb382c5d4 100644 --- a/docs/syllabus.md +++ b/docs/syllabus.md @@ -54,7 +54,7 @@ Everything below here requires a lot of foundational knowledge. Besides being ab * **Advanced Features** * [Unicode](feature_unicode.md) * [API](api_overview.md) - * [Bootmagic](feature_bootmagic.md) + * [Bootmagic Lite](feature_bootmagic.md) * **Hardware** * [How Keyboards Work](how_keyboards_work.md) * [How A Keyboard Matrix Works](how_a_matrix_works.md) -- cgit v1.2.3 From b43c6bc176dcd612ae14f9819a171abe286e92bc Mon Sep 17 00:00:00 2001 From: thpoll83 <67008047+thpoll83@users.noreply.github.com> Date: Sun, 8 Aug 2021 22:52:13 +0200 Subject: Add support for STM32F407x MCUs. (#13718) * Add support for STM32F407x MCUs. * Removing STMF407 MCU variation * Update quantum/mcu_selection.mk Remove options for dfu flashing Co-authored-by: Ryan * DISABLE STM32_USB_USE_OTG1 * Update platforms/chibios/GENERIC_STM32_F407XE/configs/mcuconf.h Co-authored-by: Drashna Jaelre * Update platforms/chibios/GENERIC_STM32_F407XE/configs/mcuconf.h Co-authored-by: thomas.pollak Co-authored-by: Ryan Co-authored-by: Drashna Jaelre Co-authored-by: Nick Brassel --- docs/compatible_microcontrollers.md | 1 + docs/ja/compatible_microcontrollers.md | 1 + 2 files changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md index 865b29feec..2bf3b0ebb7 100644 --- a/docs/compatible_microcontrollers.md +++ b/docs/compatible_microcontrollers.md @@ -27,6 +27,7 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s * [STM32F103](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html) * [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html) * [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html) + * [STM32F407](https://www.st.com/en/microcontrollers-microprocessors/stm32f407-417.html) * [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html) * [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html) * [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html) diff --git a/docs/ja/compatible_microcontrollers.md b/docs/ja/compatible_microcontrollers.md index 761a4cda46..85b31f3f12 100644 --- a/docs/ja/compatible_microcontrollers.md +++ b/docs/ja/compatible_microcontrollers.md @@ -32,6 +32,7 @@ QMK は十分な容量のフラッシュメモリを備えた USB 対応 AVR ま * [STM32F103](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html) * [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html) * [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html) +* [STM32F407](https://www.st.com/en/microcontrollers-microprocessors/stm32f407-417.html) * [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html) * [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html) * [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html) -- cgit v1.2.3 From c0628c2820b436550f62af5f6b7fae1f66b0bf8b Mon Sep 17 00:00:00 2001 From: Joel Challis Date: Mon, 9 Aug 2021 19:46:18 +0100 Subject: Remove backwards compatibility of debounce names (#13877) * Remove backwards compatibility of debounce names * Update docs * Update keyboards/keymaps --- docs/feature_debounce_type.md | 17 ----------------- docs/ja/feature_debounce_type.md | 17 ----------------- 2 files changed, 34 deletions(-) (limited to 'docs') diff --git a/docs/feature_debounce_type.md b/docs/feature_debounce_type.md index 306185fe83..f37a785b1e 100644 --- a/docs/feature_debounce_type.md +++ b/docs/feature_debounce_type.md @@ -92,15 +92,6 @@ susceptible to noise, you must choose a debounce method that will also mitigate ## Debounce algorithms supported by QMK QMK supports multiple debounce algorithms through its debounce API. -The logic for which debounce method called is below. It checks various defines that you have set in ```rules.mk``` - -``` -DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce -DEBOUNCE_TYPE?= sym_defer_g -ifneq ($(strip $(DEBOUNCE_TYPE)), custom) - QUANTUM_SRC += $(DEBOUNCE_DIR)/$(strip $(DEBOUNCE_TYPE)).c -endif -``` ### Debounce selection @@ -140,11 +131,3 @@ You have the option to implement you own debouncing algorithm. To do this: * Debouncing occurs after every raw matrix scan. * Use num_rows rather than MATRIX_ROWS, so that split keyboards are supported correctly. * If the algorithm might be applicable to other keyboards, please consider adding it to ```quantum/debounce``` - -### Old names -The following old names for existing algorithms will continue to be supported, however it is recommended to use the new names instead. - -* sym_g - old name for sym_defer_g -* eager_pk - old name for sym_eager_pk -* sym_pk - old name for sym_defer_pk -* eager_pr - old name for sym_eager_pr diff --git a/docs/ja/feature_debounce_type.md b/docs/ja/feature_debounce_type.md index 03f68d7214..258ca194da 100644 --- a/docs/ja/feature_debounce_type.md +++ b/docs/ja/feature_debounce_type.md @@ -88,15 +88,6 @@ voltage +---------------------- ## QMK でサポートされるデバウンスアルゴリズム QMK はデバウンス API を介して複数のデバウンスアルゴリズムをサポートします。 -どのデバウンスメソッドが呼ばれるかのロジックは下記のとおりです。```rules.mk``` で設定された様々な定義をチェックします。 - -``` -DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce -DEBOUNCE_TYPE?= sym_defer_g -ifneq ($(strip $(DEBOUNCE_TYPE)), custom) - QUANTUM_SRC += $(DEBOUNCE_DIR)/$(strip $(DEBOUNCE_TYPE)).c -endif -``` ### デバウンスの選択 @@ -135,11 +126,3 @@ DEBOUNCE_TYPE = <アルゴリズムの名前> * デバウンスは、全てのマトリクススキャンの後で発生します。 * MATRIX_ROWS ではなく num_rows を使って、分割キーボードが正しくサポートされるようにします。 * アルゴリズムが他のキーボードにも適用できる可能性がある場合、```quantum/debounce``` に追加することを検討してください。 - -### 古い名前 -次の既存のアルゴリズムの古い名前は引き続きサポートされますが、代わりに新しい名前を使うことを推奨します。 - -* sym_g - sym_defer_g の古い名前 -* eager_pk - sym_eager_pk の古い名前 -* sym_pk - sym_defer_pk の古い名前 -* eager_pr - sym_eager_pr の古い名前 -- cgit v1.2.3 From 477365912de93ad5d5b55c27f7861ad254c275b4 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Thu, 12 Aug 2021 13:03:40 -0700 Subject: Fix some additional bootmagic settings (#13979) --- docs/ja/feature_bootmagic.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ja/feature_bootmagic.md b/docs/ja/feature_bootmagic.md index 20a93d5c44..2ad6fc8531 100644 --- a/docs/ja/feature_bootmagic.md +++ b/docs/ja/feature_bootmagic.md @@ -16,7 +16,7 @@ 一部のキーボードでは、ブートマジックはデフォルトで無効になっています。その場合、`rules.mk` 内で以下のように明示的に有効にする必要があります: ```make -BOOTMAGIC_ENABLE = full +BOOTMAGIC_ENABLE = yes ``` ?> `full` の代わりに `yes` が使われていることがあるかもしれませんが、これは問題ありません。ただし、`yes` は非推奨で、理想的には `full` (あるいは`lite`) が使われるべきです。 -- cgit v1.2.3 From 60a36863bca9f52cad6984de4e877f8dcd30a88f Mon Sep 17 00:00:00 2001 From: Zach White Date: Sat, 14 Aug 2021 08:42:59 -0700 Subject: [Keyboard] ez_maker/directpins for easy one-offs in qmk_configurator (#13321) * new keyboard: handwired/directpins * fix promicro keyboard_name * add teensy2 and teensy2++ support * align with handwired/onekey * tweak pids * add teensy 3.2 and teensy lc to directpins * move directpins from handwired to ez_maker * add docs for easy maker --- docs/_summary.md | 1 + docs/easy_maker.md | 31 +++++++++++++++++++++++++++++++ 2 files changed, 32 insertions(+) create mode 100644 docs/easy_maker.md (limited to 'docs') diff --git a/docs/_summary.md b/docs/_summary.md index 1d95400822..48115cef46 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -36,6 +36,7 @@ * Guides * [Customizing Functionality](custom_quantum_functions.md) * [Driver Installation with Zadig](driver_installation_zadig.md) + * [Easy Maker for One Offs](easy_maker.md) * [Keymap Overview](keymap.md) * Development Environments * [Docker Guide](getting_started_docker.md) diff --git a/docs/easy_maker.md b/docs/easy_maker.md new file mode 100644 index 0000000000..dc97272333 --- /dev/null +++ b/docs/easy_maker.md @@ -0,0 +1,31 @@ +# Easy Maker - Build One-Off Projects In Configurator + +Have you ever needed an easy way to program a controller, such as a Proton C or Teensy 2.0, for a one-off project you're building? QMK has you covered with the Easy Maker. Now you can create a firmware in minutes using QMK Configurator. + +There are different styles of Easy Maker available depending on your needs: + +* [Direct Pin](https://config.qmk.fm/#/?filter=ez_maker/direct) - Connect a single switch to a single pin +* Direct Pin + Backlight (Coming Soon) - Like Direct Pin but dedicates a single pin to [Backlight](feature_backlight.md) control +* Direct Pin + Numlock (Coming Soon) - Like Direct Pin but dedicates a single pin to the Numlock LED +* Direct Pin + Capslock (Coming Soon) - Like Direct Pin but dedicates a single pin to the Numlock LED +* Direct Pin + Encoder (Coming Soon) - Like Direct Pin but uses 2 pins to add a single rotary encoder + +## Quickstart + +The easiest way to get started is with the Direct Pin boards. This will assign a single key to each pin and you can short that pin to ground to activate it. Select your MCU from the Keyboard dropdown here: + +* + +For more details see the [Direct Pin](#direct-pin) section. + +# Direct Pin + +As its name implies Direct Pin works by connecting one switch per pin. The other side of the switch should be connected to ground (VSS or GND.) You don't need any other components, your MCU has internal pull-up resistors so that the switch sensing can work. + +Here is a schematic showing how we connect a single button to pin A3 on a ProMicro: + +![Schematic diagram showing a ProMicro with a wire coming out of A3, connecting to the left side of a switch. Another wire comes out of the right side of the switch to connect to the Ground Plane.](https://i.imgur.com/JcDhZll.png) + +Once you have wired your switches you can assign keycodes to each pin and build a firmware by selecting the MCU you are using from the Keyboard dropdown. Use this link to show only Easy Maker Direct Pin: + +* -- cgit v1.2.3 From 488aaa0980b113240a461d6d7878c62f5663f5c6 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Sat, 14 Aug 2021 22:39:08 -0700 Subject: Enable sync of OLED/ST7565 display on/off state on Splits (#13542) * Enable sync of OLED/ST7565 display on/off state on Splits * Only send if states are not matched Co-authored-by: Nick Brassel Co-authored-by: Nick Brassel --- docs/config_options.md | 6 ++++++ docs/feature_split_keyboard.md | 12 ++++++++++++ 2 files changed, 18 insertions(+) (limited to 'docs') diff --git a/docs/config_options.md b/docs/config_options.md index 78c1f70fd7..94f99e74c0 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -343,6 +343,12 @@ There are a few different ways to set handedness for split keyboards (listed in * `#define SPLIT_WPM_ENABLE` * Ensures the current WPM is available on the slave when using the QMK-provided split transport. +* `#define SPLIT_OLED_ENABLE` + * Syncs the on/off state of the OLED between the halves. + +* `#define SPLIT_ST7565_ENABLE` + * Syncs the on/off state of the ST7565 screen between the halves. + * `#define SPLIT_TRANSACTION_IDS_KB .....` * `#define SPLIT_TRANSACTION_IDS_USER .....` * Allows for custom data sync with the slave when using the QMK-provided split transport. See [custom data sync between sides](feature_split_keyboard.md#custom-data-sync) for more information. diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md index 428d581cab..a84d384601 100644 --- a/docs/feature_split_keyboard.md +++ b/docs/feature_split_keyboard.md @@ -233,6 +233,18 @@ This enables transmitting modifier state (normal, weak and oneshot) to the non p This enables transmitting the current WPM to the slave side of the split keyboard. The purpose of this feature is to support cosmetic use of WPM (e.g. displaying the current value on an OLED screen). This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled. +```c +#define SPLIT_OLED_ENABLE +``` + +This enables transmitting the current OLED on/off status to the slave side of the split keyboard. The purpose of this feature is to support state (on/off state only) syncing. This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled. + +```c +#define SPLIT_ST7565_ENABLE +``` + +This enables transmitting the current ST7565 on/off status to the slave side of the split keyboard. The purpose of this feature is to support state (on/off state only) syncing. This adds overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled. + ### Custom data sync between sides :id=custom-data-sync QMK's split transport allows for arbitrary data transactions at both the keyboard and user levels. This is modelled on a remote procedure call, with the master invoking a function on the slave side, with the ability to send data from master to slave, process it slave side, and send data back from slave to master. -- cgit v1.2.3 From 4e3726bfe11b02757c5724211d2a0fc62c7f66e8 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Sun, 15 Aug 2021 13:51:50 -0700 Subject: Fixup Audio startup and add to documents (#13606) * Fixup Audio startup and add to documents * fix doc descriptions --- docs/feature_audio.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'docs') diff --git a/docs/feature_audio.md b/docs/feature_audio.md index 9ffbc2cba8..5b84dc7747 100644 --- a/docs/feature_audio.md +++ b/docs/feature_audio.md @@ -167,6 +167,32 @@ The available keycodes for audio are: !> These keycodes turn all of the audio functionality on and off. Turning it off means that audio feedback, audio clicky, music mode, etc. are disabled, completely. +## Audio Config + +| Settings | Default | Description | +|---------------------------------|----------------------|-------------------------------------------------------------------------------| +|`AUDIO_PIN` | *Not defined* |Configures the pin that the speaker is connected to. | +|`AUDIO_PIN_ALT` | *Not defined* |Configures the pin for a second speaker or second pin connected to one speaker.| +|`AUDIO_PIN_ALT_AS_NEGATIVE` | *Not defined* |Enables support for one speaker connected to two pins. | +|`AUDIO_INIT_DELAY` | *Not defined* |Enables delay during startup song to accomidate for USB startup issues. | +|`AUDIO_ENABLE_TONE_MULTIPLEXING` | *Not defined* |Enables time splicing/multiplexing to create multiple tones simutaneously. | +|`STARTUP_SONG` | `STARTUP_SOUND` |Plays when the keyboard starts up (audio.c) | +|`GOODBYE_SONG` | `GOODBYE_SOUND` |Plays when you press the RESET key (quantum.c) | +|`AG_NORM_SONG` | `AG_NORM_SOUND` |Plays when you press AG_NORM (process_magic.c) | +|`AG_SWAP_SONG` | `AG_SWAP_SOUND` |Plays when you press AG_SWAP (process_magic.c) | +|`CG_NORM_SONG` | `AG_NORM_SOUND` |Plays when you press CG_NORM (process_magic.c) | +|`CG_SWAP_SONG` | `AG_SWAP_SOUND` |Plays when you press CG_SWAP (process_magic.c) | +|`MUSIC_ON_SONG` | `MUSIC_ON_SOUND` |Plays when music mode is activated (process_music.c) | +|`MUSIC_OFF_SONG` | `MUSIC_OFF_SOUND` |Plays when music mode is deactivated (process_music.c) | +|`MIDI_ON_SONG` | `MUSIC_ON_SOUND` |Plays when midi mode is activated (process_music.c) | +|`MIDI_OFF_SONG` | `MUSIC_OFF_SOUND` |Plays when midi mode is deactivated (process_music.c) | +|`CHROMATIC_SONG` | `CHROMATIC_SOUND` |Plays when the chromatic music mode is selected (process_music.c) | +|`GUITAR_SONG` | `GUITAR_SOUND` |Plays when the guitar music mode is selected (process_music.c) | +|`VIOLIN_SONG` | `VIOLIN_SOUND` |Plays when the violin music mode is selected (process_music.c) | +|`MAJOR_SONG` | `MAJOR_SOUND` |Plays when the major music mode is selected (process_music.c) | +|`DEFAULT_LAYER_SONGS` | *Not defined* |Plays song when switched default layers with [`set_single_persistent_default_layer(layer)`](ref_functions.md#setting-the-persistent-default-layer)(quantum.c) | +|`SENDSTRING_BELL` | *Not defined* |Plays chime when the "enter" ("\a") character is sent (send_string.c) | + ## Tempo the 'speed' at which SONGs are played is dictated by the set Tempo, which is measured in beats-per-minute. Note lengths are defined relative to that. The initial/default tempo is set to 120 bpm, but can be configured by setting `TEMPO_DEFAULT` in `config.c`. -- cgit v1.2.3 From 7da97c293da851851c204af065a0c8d2f884effd Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Tue, 17 Aug 2021 11:19:00 -0700 Subject: Rgb matrix/enable modes explicitly (#13758) * Change animations to require explicet activation * Add support for legacy config * Make default for now * Add LED Matrix support * change LED Matrix docs --- docs/feature_led_matrix.md | 40 +++++++++++------------ docs/feature_rgb_matrix.md | 80 +++++++++++++++++++++++----------------------- 2 files changed, 60 insertions(+), 60 deletions(-) (limited to 'docs') diff --git a/docs/feature_led_matrix.md b/docs/feature_led_matrix.md index 7d7971bbed..fc66826015 100644 --- a/docs/feature_led_matrix.md +++ b/docs/feature_led_matrix.md @@ -164,26 +164,26 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con |Define |Description | |-------------------------------------------------------|-----------------------------------------------| -|`#define DISABLE_LED_MATRIX_ALPHAS_MODS` |Disables `LED_MATRIX_ALPHAS_MODS` | -|`#define DISABLE_LED_MATRIX_BREATHING` |Disables `LED_MATRIX_BREATHING` | -|`#define DISABLE_LED_MATRIX_BAND` |Disables `LED_MATRIX_BAND` | -|`#define DISABLE_LED_MATRIX_BAND_PINWHEEL` |Disables `LED_MATRIX_BAND_PINWHEEL` | -|`#define DISABLE_LED_MATRIX_BAND_SPIRAL` |Disables `LED_MATRIX_BAND_SPIRAL` | -|`#define DISABLE_LED_MATRIX_CYCLE_LEFT_RIGHT` |Disables `LED_MATRIX_CYCLE_LEFT_RIGHT` | -|`#define DISABLE_LED_MATRIX_CYCLE_UP_DOWN` |Disables `LED_MATRIX_CYCLE_UP_DOWN` | -|`#define DISABLE_LED_MATRIX_CYCLE_OUT_IN` |Disables `LED_MATRIX_CYCLE_OUT_IN` | -|`#define DISABLE_LED_MATRIX_DUAL_BEACON` |Disables `LED_MATRIX_DUAL_BEACON` | -|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_SIMPLE` |Disables `LED_MATRIX_SOLID_REACTIVE_SIMPLE` | -|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_WIDE` |Disables `LED_MATRIX_SOLID_REACTIVE_WIDE` | -|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_MULTIWIDE` |Disables `LED_MATRIX_SOLID_REACTIVE_MULTIWIDE` | -|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_CROSS` |Disables `LED_MATRIX_SOLID_REACTIVE_CROSS` | -|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_MULTICROSS` |Disables `LED_MATRIX_SOLID_REACTIVE_MULTICROSS`| -|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_NEXUS` |Disables `LED_MATRIX_SOLID_REACTIVE_NEXUS` | -|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_MULTINEXUS` |Disables `LED_MATRIX_SOLID_REACTIVE_MULTINEXUS`| -|`#define DISABLE_LED_MATRIX_SOLID_SPLASH` |Disables `LED_MATRIX_SOLID_SPLASH` | -|`#define DISABLE_LED_MATRIX_SOLID_MULTISPLASH` |Disables `LED_MATRIX_SOLID_MULTISPLASH` | -|`#define DISABLE_LED_MATRIX_WAVE_LEFT_RIGHT` |Disables `LED_MATRIX_WAVE_LEFT_RIGHT` | -|`#define DISABLE_LED_MATRIX_WAVE_UP_DOWN` |Disables `LED_MATRIX_WAVE_UP_DOWN` | +|`#define ENABLE_LED_MATRIX_ALPHAS_MODS` |Enables `LED_MATRIX_ALPHAS_MODS` | +|`#define ENABLE_LED_MATRIX_BREATHING` |Enables `LED_MATRIX_BREATHING` | +|`#define ENABLE_LED_MATRIX_BAND` |Enables `LED_MATRIX_BAND` | +|`#define ENABLE_LED_MATRIX_BAND_PINWHEEL` |Enables `LED_MATRIX_BAND_PINWHEEL` | +|`#define ENABLE_LED_MATRIX_BAND_SPIRAL` |Enables `LED_MATRIX_BAND_SPIRAL` | +|`#define ENABLE_LED_MATRIX_CYCLE_LEFT_RIGHT` |Enables `LED_MATRIX_CYCLE_LEFT_RIGHT` | +|`#define ENABLE_LED_MATRIX_CYCLE_UP_DOWN` |Enables `LED_MATRIX_CYCLE_UP_DOWN` | +|`#define ENABLE_LED_MATRIX_CYCLE_OUT_IN` |Enables `LED_MATRIX_CYCLE_OUT_IN` | +|`#define ENABLE_LED_MATRIX_DUAL_BEACON` |Enables `LED_MATRIX_DUAL_BEACON` | +|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_SIMPLE` |Enables `LED_MATRIX_SOLID_REACTIVE_SIMPLE` | +|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_WIDE` |Enables `LED_MATRIX_SOLID_REACTIVE_WIDE` | +|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_MULTIWIDE` |Enables `LED_MATRIX_SOLID_REACTIVE_MULTIWIDE` | +|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_CROSS` |Enables `LED_MATRIX_SOLID_REACTIVE_CROSS` | +|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_MULTICROSS` |Enables `LED_MATRIX_SOLID_REACTIVE_MULTICROSS`| +|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_NEXUS` |Enables `LED_MATRIX_SOLID_REACTIVE_NEXUS` | +|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_MULTINEXUS` |Enables `LED_MATRIX_SOLID_REACTIVE_MULTINEXUS`| +|`#define ENABLE_LED_MATRIX_SOLID_SPLASH` |Enables `LED_MATRIX_SOLID_SPLASH` | +|`#define ENABLE_LED_MATRIX_SOLID_MULTISPLASH` |Enables `LED_MATRIX_SOLID_MULTISPLASH` | +|`#define ENABLE_LED_MATRIX_WAVE_LEFT_RIGHT` |Enables `LED_MATRIX_WAVE_LEFT_RIGHT` | +|`#define ENABLE_LED_MATRIX_WAVE_UP_DOWN` |Enables `LED_MATRIX_WAVE_UP_DOWN` | ## Custom LED Matrix Effects :id=custom-led-matrix-effects diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 670d7e09bf..31fa9ed36e 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -448,46 +448,46 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con |Define |Description | |-------------------------------------------------------|-----------------------------------------------| -|`#define DISABLE_RGB_MATRIX_ALPHAS_MODS` |Disables `RGB_MATRIX_ALPHAS_MODS` | -|`#define DISABLE_RGB_MATRIX_GRADIENT_UP_DOWN` |Disables `RGB_MATRIX_GRADIENT_UP_DOWN` | -|`#define DISABLE_RGB_MATRIX_GRADIENT_LEFT_RIGHT` |Disables `MATRIX_GRADIENT_LEFT_RIGHT` | -|`#define DISABLE_RGB_MATRIX_BREATHING` |Disables `RGB_MATRIX_BREATHING` | -|`#define DISABLE_RGB_MATRIX_BAND_SAT` |Disables `RGB_MATRIX_BAND_SAT` | -|`#define DISABLE_RGB_MATRIX_BAND_VAL` |Disables `RGB_MATRIX_BAND_VAL` | -|`#define DISABLE_RGB_MATRIX_BAND_PINWHEEL_SAT` |Disables `RGB_MATRIX_BAND_PINWHEEL_SAT` | -|`#define DISABLE_RGB_MATRIX_BAND_PINWHEEL_VAL` |Disables `RGB_MATRIX_BAND_PINWHEEL_VAL` | -|`#define DISABLE_RGB_MATRIX_BAND_SPIRAL_SAT` |Disables `RGB_MATRIX_BAND_SPIRAL_SAT` | -|`#define DISABLE_RGB_MATRIX_BAND_SPIRAL_VAL` |Disables `RGB_MATRIX_BAND_SPIRAL_VAL` | -|`#define DISABLE_RGB_MATRIX_CYCLE_ALL` |Disables `RGB_MATRIX_CYCLE_ALL` | -|`#define DISABLE_RGB_MATRIX_CYCLE_LEFT_RIGHT` |Disables `RGB_MATRIX_CYCLE_LEFT_RIGHT` | -|`#define DISABLE_RGB_MATRIX_CYCLE_UP_DOWN` |Disables `RGB_MATRIX_CYCLE_UP_DOWN` | -|`#define DISABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON` |Disables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON` | -|`#define DISABLE_RGB_MATRIX_CYCLE_OUT_IN` |Disables `RGB_MATRIX_CYCLE_OUT_IN` | -|`#define DISABLE_RGB_MATRIX_CYCLE_OUT_IN_DUAL` |Disables `RGB_MATRIX_CYCLE_OUT_IN_DUAL` | -|`#define DISABLE_RGB_MATRIX_CYCLE_PINWHEEL` |Disables `RGB_MATRIX_CYCLE_PINWHEEL` | -|`#define DISABLE_RGB_MATRIX_CYCLE_SPIRAL` |Disables `RGB_MATRIX_CYCLE_SPIRAL` | -|`#define DISABLE_RGB_MATRIX_DUAL_BEACON` |Disables `RGB_MATRIX_DUAL_BEACON` | -|`#define DISABLE_RGB_MATRIX_RAINBOW_BEACON` |Disables `RGB_MATRIX_RAINBOW_BEACON` | -|`#define DISABLE_RGB_MATRIX_RAINBOW_PINWHEELS` |Disables `RGB_MATRIX_RAINBOW_PINWHEELS` | -|`#define DISABLE_RGB_MATRIX_RAINDROPS` |Disables `RGB_MATRIX_RAINDROPS` | -|`#define DISABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS` |Disables `RGB_MATRIX_JELLYBEAN_RAINDROPS` | -|`#define DISABLE_RGB_MATRIX_HUE_BREATHING` |Disables `RGB_MATRIX_HUE_BREATHING` | -|`#define DISABLE_RGB_MATRIX_HUE_PENDULUM` |Disables `RGB_MATRIX_HUE_PENDULUM` | -|`#define DISABLE_RGB_MATRIX_HUE_WAVE ` |Disables `RGB_MATRIX_HUE_WAVE ` | -|`#define DISABLE_RGB_MATRIX_TYPING_HEATMAP` |Disables `RGB_MATRIX_TYPING_HEATMAP` | -|`#define DISABLE_RGB_MATRIX_DIGITAL_RAIN` |Disables `RGB_MATRIX_DIGITAL_RAIN` | -|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_SIMPLE` |Disables `RGB_MATRIX_SOLID_REACTIVE_SIMPLE` | -|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE` |Disables `RGB_MATRIX_SOLID_REACTIVE` | -|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_WIDE` |Disables `RGB_MATRIX_SOLID_REACTIVE_WIDE` | -|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` | -|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_CROSS` |Disables `RGB_MATRIX_SOLID_REACTIVE_CROSS` | -|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTICROSS` |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTICROSS`| -|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_NEXUS` |Disables `RGB_MATRIX_SOLID_REACTIVE_NEXUS` | -|`#define DISABLE_RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS` |Disables `RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS`| -|`#define DISABLE_RGB_MATRIX_SPLASH` |Disables `RGB_MATRIX_SPLASH` | -|`#define DISABLE_RGB_MATRIX_MULTISPLASH` |Disables `RGB_MATRIX_MULTISPLASH` | -|`#define DISABLE_RGB_MATRIX_SOLID_SPLASH` |Disables `RGB_MATRIX_SOLID_SPLASH` | -|`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH` |Disables `RGB_MATRIX_SOLID_MULTISPLASH` | +|`#define ENABLE_RGB_MATRIX_ALPHAS_MODS` |Enables `RGB_MATRIX_ALPHAS_MODS` | +|`#define ENABLE_RGB_MATRIX_GRADIENT_UP_DOWN` |Enables `RGB_MATRIX_GRADIENT_UP_DOWN` | +|`#define ENABLE_RGB_MATRIX_GRADIENT_LEFT_RIGHT` |Enables `MATRIX_GRADIENT_LEFT_RIGHT` | +|`#define ENABLE_RGB_MATRIX_BREATHING` |Enables `RGB_MATRIX_BREATHING` | +|`#define ENABLE_RGB_MATRIX_BAND_SAT` |Enables `RGB_MATRIX_BAND_SAT` | +|`#define ENABLE_RGB_MATRIX_BAND_VAL` |Enables `RGB_MATRIX_BAND_VAL` | +|`#define ENABLE_RGB_MATRIX_BAND_PINWHEEL_SAT` |Enables `RGB_MATRIX_BAND_PINWHEEL_SAT` | +|`#define ENABLE_RGB_MATRIX_BAND_PINWHEEL_VAL` |Enables `RGB_MATRIX_BAND_PINWHEEL_VAL` | +|`#define ENABLE_RGB_MATRIX_BAND_SPIRAL_SAT` |Enables `RGB_MATRIX_BAND_SPIRAL_SAT` | +|`#define ENABLE_RGB_MATRIX_BAND_SPIRAL_VAL` |Enables `RGB_MATRIX_BAND_SPIRAL_VAL` | +|`#define ENABLE_RGB_MATRIX_CYCLE_ALL` |Enables `RGB_MATRIX_CYCLE_ALL` | +|`#define ENABLE_RGB_MATRIX_CYCLE_LEFT_RIGHT` |Enables `RGB_MATRIX_CYCLE_LEFT_RIGHT` | +|`#define ENABLE_RGB_MATRIX_CYCLE_UP_DOWN` |Enables `RGB_MATRIX_CYCLE_UP_DOWN` | +|`#define ENABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON` |Enables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON` | +|`#define ENABLE_RGB_MATRIX_CYCLE_OUT_IN` |Enables `RGB_MATRIX_CYCLE_OUT_IN` | +|`#define ENABLE_RGB_MATRIX_CYCLE_OUT_IN_DUAL` |Enables `RGB_MATRIX_CYCLE_OUT_IN_DUAL` | +|`#define ENABLE_RGB_MATRIX_CYCLE_PINWHEEL` |Enables `RGB_MATRIX_CYCLE_PINWHEEL` | +|`#define ENABLE_RGB_MATRIX_CYCLE_SPIRAL` |Enables `RGB_MATRIX_CYCLE_SPIRAL` | +|`#define ENABLE_RGB_MATRIX_DUAL_BEACON` |Enables `RGB_MATRIX_DUAL_BEACON` | +|`#define ENABLE_RGB_MATRIX_RAINBOW_BEACON` |Enables `RGB_MATRIX_RAINBOW_BEACON` | +|`#define ENABLE_RGB_MATRIX_RAINBOW_PINWHEELS` |Enables `RGB_MATRIX_RAINBOW_PINWHEELS` | +|`#define ENABLE_RGB_MATRIX_RAINDROPS` |Enables `RGB_MATRIX_RAINDROPS` | +|`#define ENABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS` |Enables `RGB_MATRIX_JELLYBEAN_RAINDROPS` | +|`#define ENABLE_RGB_MATRIX_HUE_BREATHING` |Enables `RGB_MATRIX_HUE_BREATHING` | +|`#define ENABLE_RGB_MATRIX_HUE_PENDULUM` |Enables `RGB_MATRIX_HUE_PENDULUM` | +|`#define ENABLE_RGB_MATRIX_HUE_WAVE ` |Enables `RGB_MATRIX_HUE_WAVE ` | +|`#define ENABLE_RGB_MATRIX_TYPING_HEATMAP` |Enables `RGB_MATRIX_TYPING_HEATMAP` | +|`#define ENABLE_RGB_MATRIX_DIGITAL_RAIN` |Enables `RGB_MATRIX_DIGITAL_RAIN` | +|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_SIMPLE` |Enables `RGB_MATRIX_SOLID_REACTIVE_SIMPLE` | +|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE` |Enables `RGB_MATRIX_SOLID_REACTIVE` | +|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_WIDE` |Enables `RGB_MATRIX_SOLID_REACTIVE_WIDE` | +|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` |Enables `RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE` | +|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_CROSS` |Enables `RGB_MATRIX_SOLID_REACTIVE_CROSS` | +|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_MULTICROSS` |Enables `RGB_MATRIX_SOLID_REACTIVE_MULTICROSS`| +|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_NEXUS` |Enables `RGB_MATRIX_SOLID_REACTIVE_NEXUS` | +|`#define ENABLE_RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS` |Enables `RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS`| +|`#define ENABLE_RGB_MATRIX_SPLASH` |Enables `RGB_MATRIX_SPLASH` | +|`#define ENABLE_RGB_MATRIX_MULTISPLASH` |Enables `RGB_MATRIX_MULTISPLASH` | +|`#define ENABLE_RGB_MATRIX_SOLID_SPLASH` |Enables `RGB_MATRIX_SOLID_SPLASH` | +|`#define ENABLE_RGB_MATRIX_SOLID_MULTISPLASH` |Enables `RGB_MATRIX_SOLID_MULTISPLASH` | ### RGB Matrix Effect Typing Heatmap :id=rgb-matrix-effect-typing-heatmap -- cgit v1.2.3 From 705774f7bfe13face6a276cee276d43411bb1693 Mon Sep 17 00:00:00 2001 From: freqmod Date: Tue, 17 Aug 2021 20:48:00 +0200 Subject: Steno combinedkeys (#12538) * Add support for steno keys that press adjacent keys simultaniously * Add some docs for steno combined keys --- docs/feature_stenography.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'docs') diff --git a/docs/feature_stenography.md b/docs/feature_stenography.md index bf4bd39db9..af4754ed78 100644 --- a/docs/feature_stenography.md +++ b/docs/feature_stenography.md @@ -128,3 +128,18 @@ As defined in `keymap_steno.h`. |`STN_RES1`||(GeminiPR only)| |`STN_RES2`||(GeminiPR only)| |`STN_PWR`||(GeminiPR only)| + +If you do not want to hit two keys with one finger combined keycodes can be used. These are also defined in `keymap_steno.h`, and causes both keys to be reported as pressed or released. To use these keycodes define `STENO_COMBINEDMAP` in your `config.h` file +|Combined key | Key1 | Key 2 | +|---------------|--------|----------| +|STN_S3 | STN_S1 | STN_S2 | +|STN_TKL | STN_TL | STN_KL | +|STN_PWL | STN_PL | STN_WL | +|STN_HRL | STN_HL | STN_RL | +|STN_FRR | STN_FR | STN_RR | +|STN_PBR | STN_PR | STN_BR | +|STN_LGR | STN_LR | STN_GR | +|STN_TSR | STN_TR | STN_SR | +|STN_DZR | STN_DR | STN_ZR | +|STN_AO | STN_A | STN_O | +|STN_EU | STN_E | STN_U | -- cgit v1.2.3 From 75b49aff56436c57a424e622c91f6d80e1d0ecc2 Mon Sep 17 00:00:00 2001 From: a-chol Date: Tue, 17 Aug 2021 20:52:44 +0200 Subject: Digitizer HID interface : absolute coordinates for mouse cursor (#12851) * Add digitizer HID interface for setting the mouse cursor position at absolute screen coordinates. Tested on Pro Micro, Proton C and Blackpill. * Update docs/feature_digitizer.md Co-authored-by: Ryan * Update tmk_core/protocol/usb_descriptor.c Co-authored-by: Ryan * Add missing copyrights Add V-USB support * Add support for digitizer dedicated endpoint for lufa and chibios. Fix formatting issues Move digitizer_task definition to the feature's base implementation file * Run cformat on modified files * Change digitizer report usage to Digitizer instead of Pen to avoid pointer disappearing on Windows. * Update tmk_core/protocol/vusb/vusb.c Co-authored-by: Ryan * Run cformat from docker image * Remove send_digitizer from host_driver_t and instead rely on the declaration being the interface to the implementation in each HW-specific usb implementation. * Fix build : send_digitizer shouldn't be static in vusb and add weak-linkage implementation for tests without usb implementation * Change digitizer user interface to match pointing device's * Update documentation with new API Co-authored-by: a-chol Co-authored-by: Ryan --- docs/_summary.md | 1 + docs/feature_digitizer.md | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 docs/feature_digitizer.md (limited to 'docs') diff --git a/docs/_summary.md b/docs/_summary.md index 48115cef46..2f6309e41d 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -108,6 +108,7 @@ * [Bluetooth](feature_bluetooth.md) * [Bootmagic Lite](feature_bootmagic.md) * [Custom Matrix](custom_matrix.md) + * [Digitizer](feature_digitizer.md) * [DIP Switch](feature_dip_switch.md) * [Encoders](feature_encoders.md) * [Haptic Feedback](feature_haptic_feedback.md) diff --git a/docs/feature_digitizer.md b/docs/feature_digitizer.md new file mode 100644 index 0000000000..9b6aeddbaa --- /dev/null +++ b/docs/feature_digitizer.md @@ -0,0 +1,35 @@ +## Digitizer + +The digitizer HID interface allows setting the mouse cursor position at absolute coordinates, unlike the Pointing Device feature that applies relative displacements. + +To enable the digitizer interface, add the following line to your rules.mk: + +```makefile +DIGITIZER_ENABLE = yes +``` + +In order to change the mouse cursor position from your keymap.c file, include the digitizer header : + +```c +#include "digitizer.h" +``` + +This gives you access to the `digitizer` structure which members allow you to change the cursor position. + +The coordinates are normalized, meaning there value must be set between 0 and 1. For the `x` coordinate, the value `0` is the leftmost position, whereas the value `1` is the rightmost position. +For the `y` coordinate, `0` is at the top and `1` at the bottom. + +Here is an example setting the cursor in the middle of the screen: + +```c +digitizer_t digitizer; +digitizer.x = 0.5; +digitizer.y = 0.5; +digitizer.tipswitch = 0; +digitizer.inrange = 1; +digitizer_set_report(digitizer); +``` + +The `tipswitch` member triggers what equates to a click when set to `1`. The `inrange` member is required for the change in coordinates to be taken. It can then be set to `0` in a new report to signal the end of the digitizer interaction, but it is not strictly required. + +Once all members are set to the desired value, the `status` member needs its bitmask `DZ_UPDATED` to be set so the report is sent during the next main loop iteration. -- cgit v1.2.3 From 3b28178deb7a42a2df8c19b9bf190bb5da732b33 Mon Sep 17 00:00:00 2001 From: ruro Date: Wed, 18 Aug 2021 01:46:59 +0300 Subject: `--parallel` improvements (#13800) * improve make parallel jobs support * document the --parallel option * disable the output-sync for interactive targets --- docs/cli_commands.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/cli_commands.md b/docs/cli_commands.md index c7468eb5e7..8fa7ad41dc 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -17,7 +17,7 @@ qmk compile [-c] **Usage for Keymaps**: ``` -qmk compile [-c] [-e =] -kb -km +qmk compile [-c] [-e =] [-j ] -kb -km ``` **Usage in Keyboard Directory**: @@ -73,6 +73,17 @@ $ qmk compile -kb dz60 ... ``` +**Parallel Compilation**: + +It is possible to speed up compilation by adding the `-j`/`--parallel` flag. +``` +qmk compile -j -kb +``` +The `num_jobs` argument determines the maximum number of jobs that can be used. Setting it to zero will enable parallel compilation without limiting the maximum number of jobs. +``` +qmk compile -j 0 -kb +``` + ## `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. @@ -82,13 +93,13 @@ This command is directory aware. It will automatically fill in KEYBOARD and/or K **Usage for Configurator Exports**: ``` -qmk flash [-bl ] [-c] [-e =] +qmk flash [-bl ] [-c] [-e =] [-j ] ``` **Usage for Keymaps**: ``` -qmk flash -kb -km [-bl ] [-c] [-e =] +qmk flash -kb -km [-bl ] [-c] [-e =] [-j ] ``` **Listing the Bootloaders** -- cgit v1.2.3 From 4c4f632378867b5c3e61461333974f59170893c3 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Tue, 17 Aug 2021 15:47:50 -0700 Subject: Add a toggle key for GUI On/Off in Magic feature (#13830) --- docs/keycodes_magic.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/keycodes_magic.md b/docs/keycodes_magic.md index 719d820312..7e1b1a4f62 100644 --- a/docs/keycodes_magic.md +++ b/docs/keycodes_magic.md @@ -24,6 +24,7 @@ |`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_TOGGLE_GUI` |`GUI_TOG`|Toggles the status of 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 | -- cgit v1.2.3 From 703f0277170c7e2d1acaa00b274f6fd479045abd Mon Sep 17 00:00:00 2001 From: tucvbif <47757803+tucvbif@users.noreply.github.com> Date: Wed, 18 Aug 2021 02:40:00 +0300 Subject: Allow for removal of hysteresis on 4x encoders (#13698) * Remove hysteresis on 4x encoders Sometimes, controller skips encoder pulses and when it returns to default position, the encoder_pulses variable isn't equals 0. And when I turn encoder in opposite direciton, it skips first click becase of encoder_pulses crosses zero. To prevent this, I add the ENCODER_DEFAULT_POS constant, and reset encoder_pulses into 0 when the state variable equals ENCODER_DEFAULT_POS. * Documentation for ENCODER_DEFAULT_POS --- docs/feature_encoders.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/feature_encoders.md b/docs/feature_encoders.md index a56f093a39..509f55b917 100644 --- a/docs/feature_encoders.md +++ b/docs/feature_encoders.md @@ -38,6 +38,12 @@ It can also be defined per-encoder, by instead defining: #define ENCODER_RESOLUTIONS { 4, 2 } ``` +For 4× encoders you also can assign default position if encoder skips pulses when it changes direction. For example, if your encoder send high level on both pins by default, define this: + +```c +#define ENCODER_DEFAULT_POS 0x3 +``` + ## Split Keyboards If you are using different pinouts for the encoders on each half of a split keyboard, you can define the pinout (and optionally, resolutions) for the right half like this: -- cgit v1.2.3 From 9d1c98c891bb8e1e98dc618e0693a7efff23a22e Mon Sep 17 00:00:00 2001 From: XScorpion2 Date: Thu, 19 Aug 2021 12:39:15 -0500 Subject: Added right vs left specific pin assignments for dip switch (#13074) * Added right vs left specific pin assignments for dip switch * Update feature_dip_switch.md * Ran formatting tools --- docs/feature_dip_switch.md | 3 ++- docs/ja/feature_dip_switch.md | 2 ++ 2 files changed, 4 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_dip_switch.md b/docs/feature_dip_switch.md index 43a6a3faf7..6fbe91657d 100644 --- a/docs/feature_dip_switch.md +++ b/docs/feature_dip_switch.md @@ -9,6 +9,8 @@ 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 } +// For split keyboards, you can separately define the right side pins +#define DIP_SWITCH_PINS_RIGHT { ... } ``` or @@ -96,7 +98,6 @@ bool dip_switch_update_mask_user(uint32_t state) { } ``` - ## Hardware ### Connects each switch in the dip switch to the GPIO pin of the MCU diff --git a/docs/ja/feature_dip_switch.md b/docs/ja/feature_dip_switch.md index a5436779f1..8d0eeafa5a 100644 --- a/docs/ja/feature_dip_switch.md +++ b/docs/ja/feature_dip_switch.md @@ -14,6 +14,8 @@ DIP スイッチは、以下を `rules.mk` に追加することでサポート ```c // Connects each switch in the dip switch to the GPIO pin of the MCU #define DIP_SWITCH_PINS { B14, A15, A10, B9 } +// For split keyboards, you can separately define the right side pins +#define DIP_SWITCH_PINS_RIGHT { ... } ``` あるいは -- cgit v1.2.3 From 0ae20e74578ae4420af3e684f7ad9fcbd7beee94 Mon Sep 17 00:00:00 2001 From: Joakim Tufvegren Date: Sun, 22 Aug 2021 02:51:17 +0200 Subject: Make solo half of split keyboards (more) usable. (#13523) * Make solo half of split keyboards (more) usable. Using only one half of a split keyboard (that's using the split_common framework to communicate) is not a great experience, since several read timeouts per scan cycle cause an unusably slow scan rate. This change blocks all split communication attempts for 500 ms (configurable) after an error occurs, causing the scan rate to become at least _more_ usable, but might need some tweaking to work fully on most keyboards. One read timeout still needs to occur after the 500 ms has passed, and if that timeout isn't low enough, some scan cycles may still be too slow. * Fix lint complaint. * Require 25 consecutive comm errors to see comms as disconnected. The number of max errors can be overridden by defining `SPLIT_MAX_CONNECTION_ERRORS`. * Add comments to new defines, and ability to disable disconnection check. Also increase `SPLIT_MAX_CONNECTION_ERRORS` to 40, since it's divisible by most relevant numbers for the description. * Make lint happy ...again * Only update `connection_check_timer` when needed. * Add new defines to split keyboard documentation. * Move connection timeout logic to transport.c, add `is_transport_connected`. * Use split_common disconnection logic in matrix.c. Instead of doing more or less the same thing twice. * Move disconnection logic to `transport_master`. Is a cleaner implementation, and causes the scan rate while disconnected to increase instead of decrease. * Lint fixes. * Lower default `SERIAL_USART_TIMEOUT` to 20 ms. The read timeout must be low enough to not cause exessively long scan cycles when using a solo split half. 10 ms was determined from testing to work fine even with the slowest defined baudrate of 19200 (5 ms was too low for that case), so 20 ms should be fine for most cases. * Remove `SERIAL_USART_TIMEOUT` from ergodox_infinity/config.h Was somewhat mistakenly included in an earlier PR. * Fix building with `USE_I2C`. * Reduce built firmware size. Not really sure why this works, the idea was taken from tzarc's work on split disconnection. * Tweak and improve opt-out for split disconnection logic. There are now two ways to opt out from this feature: * Set `SPLIT_MAX_CONNECTION_ERRORS` to 0. This will completely disable the connection status checks (also affects the slave matrix reset logic in matrix.c, though). * Set `SPLIT_CONNECTION_CHECK_TIMEOUT` to 0. This will only disable the communication throttling while disconnected. Will make the firmware smaller. * Make split disconnection logic work with custom transports. Includes a fallback implementation for keyboards using a custom split_util.c but not a custom matrix.c (currently no such keyboard seems to be merged, though). * Remove unnecessary include of timer.h Co-authored-by: Joel Challis Co-authored-by: Joel Challis --- docs/feature_split_keyboard.md | 16 ++++++++++++++++ docs/serial_driver.md | 6 +++--- 2 files changed, 19 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md index a84d384601..27df46a82a 100644 --- a/docs/feature_split_keyboard.md +++ b/docs/feature_split_keyboard.md @@ -203,6 +203,22 @@ If you're having issues with serial communication, you can change this value, as This sets the maximum number of milliseconds before forcing a synchronization of data from master to slave. Under normal circumstances this sync occurs whenever the data _changes_, for safety a data transfer occurs after this number of milliseconds if no change has been detected since the last sync. +```c +#define SPLIT_MAX_CONNECTION_ERRORS 10 +``` +This sets the maximum number of failed communication attempts (one per scan cycle) from the master part before it assumes that no slave part is connected. This makes it possible to use a master part without the slave part connected. + +Set to 0 to disable the disconnection check altogether. + +```c +#define SPLIT_CONNECTION_CHECK_TIMEOUT 500 +``` +How long (in milliseconds) the master part should block all connection attempts to the slave after the communication has been flagged as disconnected (see `SPLIT_MAX_CONNECTION_ERRORS` above). + +One communication attempt will be allowed everytime this amount of time has passed since the last attempt. If that attempt succeeds, the communication is seen as working again. + +Set to 0 to disable this throttling of communications while disconnected. This can save you a couple of bytes of firmware size. + ```c #define SPLIT_TRANSPORT_MIRROR ``` diff --git a/docs/serial_driver.md b/docs/serial_driver.md index ed989b0a15..3e89deffad 100644 --- a/docs/serial_driver.md +++ b/docs/serial_driver.md @@ -63,7 +63,7 @@ Configure the hardware via your config.h: // 5: about 19200 baud #define SERIAL_USART_DRIVER SD1 // USART driver of TX pin. default: SD1 #define SERIAL_USART_TX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7 -#define SERIAL_USART_TIMEOUT 100 // USART driver timeout. default 100 +#define SERIAL_USART_TIMEOUT 20 // USART driver timeout. default 20 ``` You must also enable the ChibiOS `SERIAL` feature: @@ -105,10 +105,10 @@ Next configure the hardware via your config.h: // 3: 57600 baud // 4: 38400 baud // 5: 19200 baud -#define SERIAL_USART_DRIVER SD1 // USART driver of TX and RX pin. default: SD1 +#define SERIAL_USART_DRIVER SD1 // USART driver of TX and RX pin. default: SD1 #define SERIAL_USART_TX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7 #define SERIAL_USART_RX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7 -#define SERIAL_USART_TIMEOUT 100 // USART driver timeout. default 100 +#define SERIAL_USART_TIMEOUT 20 // USART driver timeout. default 20 ``` You must also enable the ChibiOS `SERIAL` feature: -- cgit v1.2.3 From f314705921c9c316e69cfb6767aba8f0570c7012 Mon Sep 17 00:00:00 2001 From: Path Nirvana Date: Tue, 24 Aug 2021 05:05:10 +0700 Subject: adding uf2 flash support for blackpill 401 (#13968) * adding uf2 flash support for blackpill 401 * forgot to add blackpill to keyboard header file * making changes requested by drashna * fixing tzarc s comments * removing the keyboard * undo the change to dactyl_manuform.h --- docs/flashing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/flashing.md b/docs/flashing.md index fae9c5d1c4..7b7fe956f3 100644 --- a/docs/flashing.md +++ b/docs/flashing.md @@ -298,7 +298,7 @@ Flashing sequence: ## tinyuf2 -Keyboards may opt into supporting the tinyuf2 bootloader. This is currently only supported on the F411 blackpill. +Keyboards may opt into supporting the tinyuf2 bootloader. This is currently only supported on the F401/F411 blackpill. The `rules.mk` setting for this bootloader is `tinyuf2`, and can be specified at the keymap or user level. -- cgit v1.2.3 From 4e1c5887c5c08ebd2cf7868c8d9292aa728e7bf0 Mon Sep 17 00:00:00 2001 From: Xelus22 <17491233+Xelus22@users.noreply.github.com> Date: Tue, 24 Aug 2021 16:28:26 +1000 Subject: [Core] Refactor OLED to allow easy addition of other types (#13454) * add docs * core changes * update keyboards to new OLED * updated users to new OLED * update layouts to new OLED * fixup docs * drashna's suggestion * fix up docs * new keyboards with oled * core split changes * remaining keyboard files * Fix The Helix keyboards oled options * reflect develop Co-authored-by: Drashna Jaelre Co-authored-by: mtei <2170248+mtei@users.noreply.github.com> --- docs/feature_oled_driver.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/feature_oled_driver.md b/docs/feature_oled_driver.md index c90aabb9c6..c97843cfb3 100644 --- a/docs/feature_oled_driver.md +++ b/docs/feature_oled_driver.md @@ -21,13 +21,23 @@ Hardware configurations using Arm-based microcontrollers or different sizes of O 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 +OLED_ENABLE = yes +``` + +## OLED type +|OLED Driver |Supported Device | +|-------------------|---------------------------| +|SSD1306 (default) |For both SSD1306 and SH1106| + +e.g. +```make +OLED_DRIVER = SSD1306 ``` 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 -#ifdef OLED_DRIVER_ENABLE +#ifdef OLED_ENABLE void oled_task_user(void) { // Host Keyboard Layer Status oled_write_P(PSTR("Layer: "), false); @@ -114,7 +124,7 @@ static void fade_display(void) { In split keyboards, it is very common to have two OLED displays that each render different content and are oriented or flipped differently. You can do this by switching which content to render by using the return value from `is_keyboard_master()` or `is_keyboard_left()` found in `split_util.h`, e.g: ```c -#ifdef OLED_DRIVER_ENABLE +#ifdef OLED_ENABLE 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 -- cgit v1.2.3 From 29ec2d8f4283212cf45c926c288f652a6727acb7 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Thu, 26 Aug 2021 13:41:33 -0700 Subject: [Docs] Add examples to RGB Matrix Indicators docs (#12797) --- docs/feature_rgb_matrix.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 31fa9ed36e..42a57aec19 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -741,3 +741,42 @@ void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { } } ``` + +#### Examples :id=indicator-examples + +This example sets the modifiers to be a specific color based on the layer state. You can use a switch case here, instead, if you would like. This uses HSV and then converts to RGB, because this allows the brightness to be limited (important when using the WS2812 driver). + +```c +void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { + HSV hsv = {0, 255, 255}; + + if (layer_state_is(layer_state, 2)) { + hsv = {130, 255, 255}; + } else { + hsv = {30, 255, 255}; + } + + if (hsv.v > rgb_matrix_get_val()) { + hsv.v = rgb_matrix_get_val(); + } + RGB rgb = hsv_to_rgb(hsv); + + for (uint8_t i = led_min; i <= led_max; i++) { + if (HAS_FLAGS(g_led_config.flags[i], 0x01)) { // 0x01 == LED_FLAG_MODIFIER + rgb_matrix_set_color(i, rgb.r, rgb.g, rgb.b); + } + } +} +``` + +If you want to indicate a Host LED status (caps lock, num lock, etc), you can use something like this to light up the caps lock key: + +```c +void rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { + if (host_keyboard_led_state().caps_lock) { + RGB_MATRIX_INDICATOR_SET_COLOR(5, 255, 255, 255); // assuming caps lock is at led #5 + } else { + RGB_MATRIX_INDICATOR_SET_COLOR(5, 0, 0, 0); + } +} +``` -- cgit v1.2.3 From 4bad375d7c09d949a9dcdd4feba147c9c7a67ec6 Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Sun, 29 Aug 2021 08:18:18 +1000 Subject: 2021Q3 pre-merge `develop` changelog, keyboard aliases (#14198) * Initial changelog. * Data driven. * Submodule update. * Updated breaking changes docs. * Aliases. * Aliases. --- docs/ChangeLog/20210828.md | 557 +++++++++++++++++++++++++++++++++++++++ docs/breaking_changes.md | 13 +- docs/breaking_changes_history.md | 1 + 3 files changed, 565 insertions(+), 6 deletions(-) create mode 100644 docs/ChangeLog/20210828.md (limited to 'docs') diff --git a/docs/ChangeLog/20210828.md b/docs/ChangeLog/20210828.md new file mode 100644 index 0000000000..22c547f8b9 --- /dev/null +++ b/docs/ChangeLog/20210828.md @@ -0,0 +1,557 @@ +# QMK Breaking Changes - 2021 August 28 Changelog + +## Notable Features :id=notable-features + +### Combo processing improvements ([#8591](https://github.com/qmk/qmk_firmware/pull/8591)) :id=combo-processing-improvements + +Combo processing has been reordered with respect to keypress handling, allowing for much better compatibility with mod taps. + +It is also now possible to define combos that have keys overlapping with other combos, triggering only one. For example, a combo of `A`, `B` can coexist with a longer combo of `A`, `B`, `C` -- previous functionality would trigger both combos if all three keys were pressed. + +### Key Overrides ([#11422](https://github.com/qmk/qmk_firmware/pull/11422)) :id=key-overrides + +QMK now has a new feature: [key overrides](https://docs.qmk.fm/#/feature_key_overrides). This feature allows for overriding the output of key combinations involving modifiers. As an example, pressing Shift+2 normally results in an @ on US-ANSI keyboard layouts -- the new key overrides allow for adding similar functionality, but for any modifier + key press. + +To illustrate, it's now possible to use the key overrides feature to translate Shift + Backspace into Delete -- an often-requested example of where this functionality comes in handy. + +There's far more to describe that what lives in this changelog, so head over to the [key overrides documentation](https://docs.qmk.fm/#/feature_key_overrides) for more examples and info. + +### Digitizer support ([#12851](https://github.com/qmk/qmk_firmware/pull/12851)) + +QMK gained the ability to pretend to be a digitizer device -- much like a tablet device. A mouse uses delta-coordinates -- move up, move right -- but a digitizer works with absolute coordinates -- top left, bottom right. + +## Changes Requiring User Action :id=changes-requiring-user-action + +### Updated Keyboard Codebases :id=updated-keyboard-codebases + +The following keyboards have had their source moved within QMK: + +Old Keyboard Name | New Keyboard Name +------------------------------|--------------------------------------------------------- +aeboards/constellation | aeboards/constellation/rev1, aeboards/constellation/rev2 +bakeneko65 | bakeneko65/rev2, bakeneko65/rev3 +bm16a | kprepublic/bm16a +bm16s | kprepublic/bm16s +bm40hsrgb | kprepublic/bm40hsrgb +bm43a | kprepublic/bm43a +bm60poker | kprepublic/bm60poker +bm60rgb | kprepublic/bm60rgb +bm60rgb_iso | kprepublic/bm60rgb_iso +bm68rgb | kprepublic/bm68rgb +clawsome/gamebuddy | clawsome/gamebuddy/v1_0, clawsome/gamebuddy/v1_m +cospad | kprepublic/cospad +custommk/genesis | custommk/genesis/rev1, custommk/genesis/rev2 +daisy | ktec/daisy +durgod/k320 | durgod/k3x0/k320 +dztech/volcano660 | ilumkb/volcano660 +ergodone | ktec/ergodone +gmmk/pro | gmmk/pro/ansi, gmmk/pro/iso +handwired/p1800fl | team0110/p1800fl +jj40 | kprepublic/jj40 +jj4x4 | kprepublic/jj4x4 +jj50 | kprepublic/jj50 +kyria | splitkb/kyria +lazydesigners/the60 | lazydesigners/the60/rev1, lazydesigners/the60/rev2 +matrix/m12og | matrix/m12og/rev1, matrix/m12og/rev2 +mechlovin/hannah65/mechlovin9 | mechlovin/mechlovin9/rev1, mechlovin/mechlovin9/rev2 +peiorisboards/ixora | coarse/ixora +ramonimbao/mona | ramonimbao/mona/v1, ramonimbao/mona/v1_1 +staryu | ktec/staryu +tokyo60 | tokyokeyboard/tokyo60 +vinta | coarse/vinta +xd002 | xiudi/xd002 +xd004 | xiudi/xd004 +xd60 | xiudi/xd60 +xd68 | xiudi/xd68 +xd75 | xiudi/xd75 +xd84 | xiudi/xd84 +xd84pro | xiudi/xd84pro +xd87 | xiudi/xd87 +xd96 | xiudi/xd96 + +### Bootmagic Full Removal ([#13846](https://github.com/qmk/qmk_firmware/pull/13846)) :id=bootmagic-full-removal + +As noted during last breaking changes cycle, QMK has decided to deprecate the full Bootmagic feature and leave Bootmagic Lite as the only remaining option. + +This pull request changes the behavior of `BOOTMAGIC_ENABLE` such that specifying `full` results in an error, allowing only `no`, `yes`, or `lite`. + +Next cycle, `lite` will be removed, so `yes` and `no` should be used in to minimise disruption. + +#### Bootmagic Full Deprecation Schedule + +This is the current roadmap for the behavior of `BOOTMAGIC_ENABLE`: + +- (done) From 2021 May 29, setting `BOOTMAGIC_ENABLE = yes` will enable Bootmagic Lite instead of full Bootmagic. +- (now) From 2021 Aug 28, `BOOTMAGIC_ENABLE` must be either `yes`, `lite`, or `no` – setting `BOOTMAGIC_ENABLE = full` will cause compilation to fail. +- (next) From 2021 Nov 27, `BOOTMAGIC_ENABLE` must be either `yes` or `no` – setting `BOOTMAGIC_ENABLE = lite` will cause compilation to fail. + +### DIP switch callbacks are now boolean ([#13399](https://github.com/qmk/qmk_firmware/pull/13399)) :id=dip-switch-boolean + +To match the encoder change last breaking changes cycle, DIP switch callbacks now return `bool`, too. + +Example code before change: + +```c +void dip_switch_update_kb(uint8_t index, bool active) { + dip_switch_update_user(index, active); +} + +void dip_switch_update_user(uint8_t index, bool active) { + switch (index) { + case 0: + if(active) { audio_on(); } else { audio_off(); } + break; + } +} + +void dip_switch_update_mask_kb(uint32_t state) { + dip_switch_update_mask_user(state); +} + +void dip_switch_update_mask_user(uint32_t state) { + if (state & (1UL<<0) && state & (1UL<<1)) { + layer_on(_ADJUST); // C on esc + } else { + layer_off(_ADJUST); + } +} +``` + +Example code after change: + +```c +bool dip_switch_update_kb(uint8_t index, bool active) { + if !(dip_switch_update_user(index, active)) { return false; } + return true; +} + +bool dip_switch_update_user(uint8_t index, bool active) { + switch (index) { + case 0: + if(active) { audio_on(); } else { audio_off(); } + break; + } + return true; // Returning true allows keyboard code to execute, false will tell the keyboard code "I've already handled it". +} + +bool dip_switch_update_mask_kb(uint32_t state) { + if (!dip_switch_update_mask_user(state)) { return false; } + return true; +} + +bool dip_switch_update_mask_user(uint32_t state) { + if (state & (1UL<<0) && state & (1UL<<1)) { + layer_on(_ADJUST); // C on esc + } else { + layer_off(_ADJUST); + } + return true; // Returning true allows keyboard code to execute, false will tell the keyboard code "I've already handled it". +} +``` + +## Notable core changes :id=notable-core + +### Split transport improvements :id=split-transport-improvements + +Split keyboards gained a significant amount of improvements during this breaking changes cycle, specifically: + +* Extensible split data sync ([#11930](https://github.com/qmk/qmk_firmware/pull/11930)) -- rewritten data sharing between sides, allowing for data transfer only when required, as well as enabling keyboards and keymaps to define their own shared data. +* Full-duplex ARM USART split ([#13081](https://github.com/qmk/qmk_firmware/pull/13081)) -- adds to the previous half-duplex driver and now allows for full-duplex support on ARM. +* Make solo half of split keyboards (more) usable. ([#13523](https://github.com/qmk/qmk_firmware/pull/13523)) -- allows the slave to be disconnected, enabling one-handed use. +* Switch split_common to CRC subsystem ([#13418](https://github.com/qmk/qmk_firmware/pull/13418)) + +!> If you're updating your split keyboard, you will need to flash both sides of the split with the your firmware. + +### Teensy 4.x support ([#13056](https://github.com/qmk/qmk_firmware/pull/13056), [#13076](https://github.com/qmk/qmk_firmware/pull/13076), [#13077](https://github.com/qmk/qmk_firmware/pull/13077)) :id=teensy-4-x-support + +Updated ChibiOS and ChibiOS-Contrib, which brought in support for Teensy 4.x dev boards, running NXP i.MX1062. + +### Data Driven Improvements ([#13366](https://github.com/qmk/qmk_firmware/pull/13366)) + +QMK's pursuit of data-driven keyboards has progressed, allowing substantially more configurable options to be specified in `info.json`. + +#### Tags + +Tags will let you categorize your keyboard, and will be used in the future to allow browsing and sorting through keyboards in QMK. Tags are free-form text identifiers that identify attributes about your keyboard. To add tags you simply add a `tags` key to your `info.json`: + + "tags": ["tkl", "backlight", "encoder"] + +#### Dot Notation + +With this release we are moving towards using JSON dot notation in more places. For example, when using `qmk info -f text`: + +``` +$ qmk info -f text -kb clueboard/card + bootloader: atmel-dfu + debounce: 20 + diode_direction: ROW2COL + features.audio: True + features.backlight: True + features.bluetooth: False + features.bootmagic: False + features.command: True + features.console: True + features.extrakey: True + features.lto: True + features.midi: False + features.mousekey: True + features.nkro: False + features.rgblight: True + features.unicode: False + height: 8 + keyboard_folder: clueboard/card + keyboard_name: Cluecard + layout_aliases.LAYOUT: LAYOUT_all + layouts: LAYOUT_all + maintainer: skullydazed + manufacturer: Clueboard + matrix_pins.cols: F1, F6, F7 + matrix_pins.rows: B4, F0, F4, F5 + platform: unknown + processor: atmega32u4 + processor_type: avr + protocol: LUFA + rgblight.brightness_steps: 17 + rgblight.hue_steps: 10 + rgblight.led_count: 4 + rgblight.pin: E6 + rgblight.saturation_steps: 17 + split.transport.protocol: serial + usb.device_ver: 0x0001 + usb.pid: 0x2330 + usb.vid: 0xC1ED + width: 10 +``` + +#### New configuration keys + +We've added dozens of new keys to `info.json` so that you can configure more than ever without writing a single line of code. A quick overview of the new items you can configure: + +* `audio.pins`, `audio.voices` +* `backlight.breathing`, `backlight.breathing_period`, `backlight.levels`, `backlight.pin`, +* `bluetooth.driver`, `bluetooth.lto` +* `bootloader_instructions` +* `build.debounce_type`, `build.firmware_format`, `build.lto` +* `combo.count`, `combo.term` +* `leader_key.timing`, `leader_key.strict_processing`, `leader_key.timeout` +* `matrix.custom`, `matrix.custom_lite`, `matrix.ghost`, `matrix.io_delay` +* `mouse_key.enabled`, `mouse_key.delay`, `mouse_key.interval`, `mouse_key.max_speed`, `mouse_key.time_to_max`, `mouse_key.wheel_delay` +* `oneshot.tap_toggle`, `oneshot.timeout` +* `rgblight.layers.blink`, `rgblight.layers.enabled`, `rgblight.layers.max`, `rgblight.layers.override_rgb`, `rgblight.rgbw` +* `split.enabled`, `split.matrix_grid`, `split.matrix_pins`, `split.main`, `split.soft_serial_pin`, `split.soft_serial_speed`, `split.transport.protocol`, `split.transport.sync_matrix_state`, `split.transport.sync_modifiers`, `split.usb_detect` +* `tapping.force_hold`, `tapping.force_hold_per_key`, `tapping.ignore_mod_tap_interrupt`, `tapping.ignore_mod_tap_interrupt_per_key`, `tapping.permissive_hold`, `tapping.permissive_hold_per_key`, `tapping.retro`, `tapping.retro_per_key`, `tapping.term`, `tapping.term_per_key`, `tapping.toggle` +* `usb.force_nkro`, `usb.max_power`, `usb.no_startup_check`, `usb.polling_interval`, `usb.shared_endpoint.keyboard`, `usb.shared_endpoint.mouse`, `usb.suspend_wakeup_delay`, `usb.wait_for` +* `qmk.keys_per_scan`, `qmk.tap_keycode_delay`, `qmk.tap_capslock_delay` + +### Codebase restructure and cleanup :id=codebase-restructure + +QMK was originally based on TMK, and has grown in size considerably since its first inception. To keep moving things forward, restructure of some of the core areas of the code is needed to support new concepts and new hardware, and progress is happening along those lines: + +* Move RGBLight code into its own folder ([#13312](https://github.com/qmk/qmk_firmware/pull/13312)) +* Migrate platform independent code from tmk_core -> quantum ([#13673](https://github.com/qmk/qmk_firmware/pull/13673)) +* matrix_scan_x -> x_task ([#13748](https://github.com/qmk/qmk_firmware/pull/13748)) +* Move some led drivers to common folder ([#13749](https://github.com/qmk/qmk_firmware/pull/13749)) +* Move chibios board files to allow tmk_core platform migration ([#13777](https://github.com/qmk/qmk_firmware/pull/13777)) +* Begin to carve out platform/protocol API - Single main loop ([#13843](https://github.com/qmk/qmk_firmware/pull/13843)) +* Relocate platform specific drivers ([#13894](https://github.com/qmk/qmk_firmware/pull/13894)) +* Move all the flash logic from tmk_core ([#13927](https://github.com/qmk/qmk_firmware/pull/13927)) +* Move USB Host Shield and Arduino core to `lib/` ([#13973](https://github.com/qmk/qmk_firmware/pull/13973)) +* Unify behaviour of wait on AVR ([#14025](https://github.com/qmk/qmk_firmware/pull/14025)) +* Move nix folder alongside vagrant ([#14132](https://github.com/qmk/qmk_firmware/pull/14132)) +* Align some quantum sub-directories ([#14134](https://github.com/qmk/qmk_firmware/pull/14134)) + +--- + +## Full changelist + +Core: +* Arm ps2 mouse interrupt ([#6490](https://github.com/qmk/qmk_firmware/pull/6490)) +* Process combos earlier & overlapping combos ([#8591](https://github.com/qmk/qmk_firmware/pull/8591)) +* Swap buttons on PS2 Mouse/Trackball ([#9205](https://github.com/qmk/qmk_firmware/pull/9205)) +* Add HOLD_ON_OTHER_KEY_PRESS option for dual-role keys ([#9404](https://github.com/qmk/qmk_firmware/pull/9404)) +* add yaml_build_options target ([#10533](https://github.com/qmk/qmk_firmware/pull/10533)) +* Warn when building a board that uses arm_atsam ([#10904](https://github.com/qmk/qmk_firmware/pull/10904)) +* Key Overrides ([#11422](https://github.com/qmk/qmk_firmware/pull/11422)) +* Refactor `quantum/command.{c,h}` for code size & {read,maintain}ability ([#11842](https://github.com/qmk/qmk_firmware/pull/11842)) +* Extensible split data sync ([#11930](https://github.com/qmk/qmk_firmware/pull/11930)) +* Move print/debug files to quantum ([#12069](https://github.com/qmk/qmk_firmware/pull/12069)) +* Unconditionally call led_init_ports ([#12116](https://github.com/qmk/qmk_firmware/pull/12116)) +* Support using a timer for wait_us() on ChibiOS-based boards ([#12211](https://github.com/qmk/qmk_firmware/pull/12211)) +* Add support for NO_PIN to all matrix types ([#12238](https://github.com/qmk/qmk_firmware/pull/12238)) +* Avoid 8-bit timer overflows in debounce algorithms ([#12240](https://github.com/qmk/qmk_firmware/pull/12240)) +* Add Per Key exclusions for Haptic Feedback ([#12386](https://github.com/qmk/qmk_firmware/pull/12386)) +* Steno combinedkeys ([#12538](https://github.com/qmk/qmk_firmware/pull/12538)) +* eeprom_stm32: implement high density wear leveling ([#12567](https://github.com/qmk/qmk_firmware/pull/12567)) +* eeprom_i2c driver: added EXTERNAL_EEPROM_WP_PIN configuration option. ([#12617](https://github.com/qmk/qmk_firmware/pull/12617)) +* Add CRC8 calculation subsystem to quantum ([#12641](https://github.com/qmk/qmk_firmware/pull/12641)) +* Limit saturation for RGB_MATRIX_JELLYBEAN_RAINDROPS ([#12669](https://github.com/qmk/qmk_firmware/pull/12669)) +* Add asym_eager_defer_pk debounce type ([#12689](https://github.com/qmk/qmk_firmware/pull/12689)) +* Include lib8tion.c into RGB/LED matrix build list ([#12699](https://github.com/qmk/qmk_firmware/pull/12699)) +* Add readPort() and some API to 'tmk_core/common/*/gpio.h' ([#12754](https://github.com/qmk/qmk_firmware/pull/12754)) +* add wait_cpuclock() macro for AVR and CPU_CLOCK macro ([#12755](https://github.com/qmk/qmk_firmware/pull/12755)) +* Trigger a wakeup after USB Reset on ChibiOS. ([#12831](https://github.com/qmk/qmk_firmware/pull/12831)) +* Add sync_timer support over serial_link (i.e. Ergodox Infinity) ([#12845](https://github.com/qmk/qmk_firmware/pull/12845)) +* Digitizer HID interface : absolute coordinates for mouse cursor ([#12851](https://github.com/qmk/qmk_firmware/pull/12851)) +* Add config.h and rules.mk support for data driven keymaps ([#12859](https://github.com/qmk/qmk_firmware/pull/12859)) +* Add alternate ldscript for STM32duino (F103xB) ([#12914](https://github.com/qmk/qmk_firmware/pull/12914)) +* `keymap_extras`: Remove deprecated defines ([#12949](https://github.com/qmk/qmk_firmware/pull/12949)) +* Retain brightness with lighting layers ([#13025](https://github.com/qmk/qmk_firmware/pull/13025)) +* Move optical sensor code to drivers folder ([#13044](https://github.com/qmk/qmk_firmware/pull/13044)) +* Change the prototype of matrix_output_unselect_delay() ([#13045](https://github.com/qmk/qmk_firmware/pull/13045)) +* Add weak refs on reading rows/cols. ([#13062](https://github.com/qmk/qmk_firmware/pull/13062)) +* Use single memcmp to determine if matrix changed. ([#13064](https://github.com/qmk/qmk_firmware/pull/13064)) +* Improve layer mask handling ([#13065](https://github.com/qmk/qmk_firmware/pull/13065)) +* mousekey: expose current report to users ([#13069](https://github.com/qmk/qmk_firmware/pull/13069)) +* ChibiOS SVN mirror script. ([#13070](https://github.com/qmk/qmk_firmware/pull/13070)) +* Added right vs left specific pin assignments for dip switch ([#13074](https://github.com/qmk/qmk_firmware/pull/13074)) +* make RESET key work with Teensy 4.x ([#13076](https://github.com/qmk/qmk_firmware/pull/13076)) +* wire up flash make target for Teensy 4.x ([#13077](https://github.com/qmk/qmk_firmware/pull/13077)) +* bump USB spec version in device descriptor to 2.0 ([#13078](https://github.com/qmk/qmk_firmware/pull/13078)) +* Unite half-duplex and full-duplex serial drivers ([#13081](https://github.com/qmk/qmk_firmware/pull/13081)) +* Add ST7565 LCD driver ([#13089](https://github.com/qmk/qmk_firmware/pull/13089)) +* `spi_master` Kinetis support ([#13098](https://github.com/qmk/qmk_firmware/pull/13098)) +* GMMK Pro RGB Support ([#13147](https://github.com/qmk/qmk_firmware/pull/13147)) +* Remove dfu-util arguments from mcu_selection ([#13150](https://github.com/qmk/qmk_firmware/pull/13150)) +* Add subcommand to generate version.h ([#13151](https://github.com/qmk/qmk_firmware/pull/13151)) +* Add oled_invert ([#13172](https://github.com/qmk/qmk_firmware/pull/13172)) +* ST7565 invert ([#13237](https://github.com/qmk/qmk_firmware/pull/13237)) +* RGB Matrix eeprom write limiting ([#13238](https://github.com/qmk/qmk_firmware/pull/13238)) +* Temporary disable of CRC ([#13252](https://github.com/qmk/qmk_firmware/pull/13252)) +* Move LED/RGB Matrix code into their own directories ([#13257](https://github.com/qmk/qmk_firmware/pull/13257)) +* Skip EEPROM writes once done. ([#13293](https://github.com/qmk/qmk_firmware/pull/13293)) +* Remove rgblight stubs ([#13302](https://github.com/qmk/qmk_firmware/pull/13302)) +* Allow settable SPI divisor for AW20216 driver, set default to 4 ([#13309](https://github.com/qmk/qmk_firmware/pull/13309)) +* Move RGBLight code into its own folder ([#13312](https://github.com/qmk/qmk_firmware/pull/13312)) +* Unify matrix for split common and regular matrix ([#13330](https://github.com/qmk/qmk_firmware/pull/13330)) +* Relocate RGB/HSV color defs to a more fitting place ([#13377](https://github.com/qmk/qmk_firmware/pull/13377)) +* Adds support for STM32L412xB, STM32L422xB. ([#13383](https://github.com/qmk/qmk_firmware/pull/13383)) +* Convert Dip Switch callbacks to boolean functions ([#13399](https://github.com/qmk/qmk_firmware/pull/13399)) +* Use string literals for `SERIAL_NUMBER` ([#13403](https://github.com/qmk/qmk_firmware/pull/13403)) +* Switch split_common to CRC subsystem ([#13418](https://github.com/qmk/qmk_firmware/pull/13418)) +* Improve 'show_build_options' target ([#13425](https://github.com/qmk/qmk_firmware/pull/13425)) +* AW20216 use register increment for framebuffer flushes ([#13430](https://github.com/qmk/qmk_firmware/pull/13430)) +* Allow invert of SPLIT_HAND_PIN logic ([#13433](https://github.com/qmk/qmk_firmware/pull/13433)) +* chibios: bootloader: use integer pointers as volatile ([#13450](https://github.com/qmk/qmk_firmware/pull/13450)) +* Refactor OLED to allow easy addition of other types ([#13454](https://github.com/qmk/qmk_firmware/pull/13454)) +* Dual RGB Matrix IS31FL3737 driver support to address #13442 ([#13457](https://github.com/qmk/qmk_firmware/pull/13457)) +* Enable g_is31_leds PROGMEM for RGB Matrix IS31FL3737 driver ([#13480](https://github.com/qmk/qmk_firmware/pull/13480)) +* Switch Ergodox Infinity over to split_common ([#13481](https://github.com/qmk/qmk_firmware/pull/13481)) +* Make solo half of split keyboards (more) usable. ([#13523](https://github.com/qmk/qmk_firmware/pull/13523)) +* Enable sync of OLED/ST7565 display on/off state on Splits ([#13542](https://github.com/qmk/qmk_firmware/pull/13542)) +* Revert "Add rgblight to RGB Matrix VPATH" ([#13559](https://github.com/qmk/qmk_firmware/pull/13559)) +* Move `SENDSTRING_BELL` code to `send_string.h` ([#13566](https://github.com/qmk/qmk_firmware/pull/13566)) +* Migrate platform independent code from tmk_core -> quantum ([#13673](https://github.com/qmk/qmk_firmware/pull/13673)) +* Avoid LTO conficts on arm_atsam ([#13676](https://github.com/qmk/qmk_firmware/pull/13676)) +* Allow for removal of hysteresis on 4x encoders ([#13698](https://github.com/qmk/qmk_firmware/pull/13698)) +* Port new_keyboard.sh to CLI ([#13706](https://github.com/qmk/qmk_firmware/pull/13706)) +* Align AW20216 driver ([#13712](https://github.com/qmk/qmk_firmware/pull/13712)) +* Haptic: driver-> feature ([#13713](https://github.com/qmk/qmk_firmware/pull/13713)) +* Add support for STM32F407x MCUs. ([#13718](https://github.com/qmk/qmk_firmware/pull/13718)) +* Remove legacy BACKLIGHT_CUSTOM_DRIVER option ([#13731](https://github.com/qmk/qmk_firmware/pull/13731)) +* Minor tidy up of key overrides ([#13747](https://github.com/qmk/qmk_firmware/pull/13747)) +* matrix_scan_x -> x_task ([#13748](https://github.com/qmk/qmk_firmware/pull/13748)) +* Move some led drivers to common folder ([#13749](https://github.com/qmk/qmk_firmware/pull/13749)) +* Allow for higher USB Polling rate on ATSAM boards ([#13755](https://github.com/qmk/qmk_firmware/pull/13755)) +* Rgb matrix/enable modes explicitly ([#13758](https://github.com/qmk/qmk_firmware/pull/13758)) +* Move chibios board files to allow tmk_core platform migration ([#13777](https://github.com/qmk/qmk_firmware/pull/13777)) +* __flash? ([#13799](https://github.com/qmk/qmk_firmware/pull/13799)) +* `--parallel` improvements ([#13800](https://github.com/qmk/qmk_firmware/pull/13800)) +* Speed up pimoroni trackball driver ([#13823](https://github.com/qmk/qmk_firmware/pull/13823)) +* Add a toggle key for GUI On/Off in Magic feature ([#13830](https://github.com/qmk/qmk_firmware/pull/13830)) +* Begin to carve out platform/protocol API - Single main loop ([#13843](https://github.com/qmk/qmk_firmware/pull/13843)) +* Remove Full Bootmagic ([#13846](https://github.com/qmk/qmk_firmware/pull/13846)) +* Remove backwards compatibility of debounce names ([#13877](https://github.com/qmk/qmk_firmware/pull/13877)) +* Relocate platform specific drivers ([#13894](https://github.com/qmk/qmk_firmware/pull/13894)) +* Remove ONEHAND_ENABLE ([#13920](https://github.com/qmk/qmk_firmware/pull/13920)) +* Move all the flash logic from tmk_core ([#13927](https://github.com/qmk/qmk_firmware/pull/13927)) +* adding uf2 flash support for blackpill 401 ([#13968](https://github.com/qmk/qmk_firmware/pull/13968)) +* Unify behaviour of wait on AVR ([#14025](https://github.com/qmk/qmk_firmware/pull/14025)) +* Add qmk-hid bootloader detection support to `qmk console` ([#14038](https://github.com/qmk/qmk_firmware/pull/14038)) +* Align DIP_SWITCH_PINS_RIGHT implementation with encoders ([#14079](https://github.com/qmk/qmk_firmware/pull/14079)) +* Tidy up quantum.c now some of tmk_core has been merged ([#14083](https://github.com/qmk/qmk_firmware/pull/14083)) +* Improve pmw3360 sensor and make it more hardware agnostic ([#14097](https://github.com/qmk/qmk_firmware/pull/14097)) +* Move nix folder alongside vagrant ([#14132](https://github.com/qmk/qmk_firmware/pull/14132)) +* Align some quantum sub-directories ([#14134](https://github.com/qmk/qmk_firmware/pull/14134)) +* Revert 14083 && 14144 ([#14150](https://github.com/qmk/qmk_firmware/pull/14150)) + +CLI: +* allow LINE_PINxx for Teensy 4.x pins ([#13247](https://github.com/qmk/qmk_firmware/pull/13247)) +* Remove the redundant pin name validation ([#13251](https://github.com/qmk/qmk_firmware/pull/13251)) +* Move all our CLI file formatters to the format dir ([#13296](https://github.com/qmk/qmk_firmware/pull/13296)) +* Refactor doctor.py into a directory ([#13298](https://github.com/qmk/qmk_firmware/pull/13298)) +* Add git and venv info to doctor's output ([#13405](https://github.com/qmk/qmk_firmware/pull/13405)) +* Matrix consistency check ([#13470](https://github.com/qmk/qmk_firmware/pull/13470)) +* Remove references to info.json `width` and `height` in CLI ([#13728](https://github.com/qmk/qmk_firmware/pull/13728)) +* Make `qmk doctor` more lenient about system config ([#13804](https://github.com/qmk/qmk_firmware/pull/13804)) +* Defer the expensive search for layout macros until info.json has been processed ([#14007](https://github.com/qmk/qmk_firmware/pull/14007)) + +Submodule updates: +* Update ChibiOS, ChibiOS-Contrib. ([#13056](https://github.com/qmk/qmk_firmware/pull/13056)) +* Update LUFA (18-07-2021) and add QMK-HID Bootloader support ([#13588](https://github.com/qmk/qmk_firmware/pull/13588)) +* Update LUFA Submodule (2021-07-30) ([#13819](https://github.com/qmk/qmk_firmware/pull/13819)) +* Bump gtest ([#13885](https://github.com/qmk/qmk_firmware/pull/13885)) +* Update ChibiOS-Contrib, mirroring script. ([#13896](https://github.com/qmk/qmk_firmware/pull/13896)) +* Move USB Host Shield and Arduino core to `lib/` ([#13973](https://github.com/qmk/qmk_firmware/pull/13973)) + +Keyboards: +* Migrate keyboards using uGFX to LED_MATRIX ([#9657](https://github.com/qmk/qmk_firmware/pull/9657)) +* Remove MIDI Configuration boilerplate ([#11151](https://github.com/qmk/qmk_firmware/pull/11151)) +* manyboard macro ([#11896](https://github.com/qmk/qmk_firmware/pull/11896)) +* Moved tokyo60/ into tokyokeyboard/tokyo60/. ([#12023](https://github.com/qmk/qmk_firmware/pull/12023)) +* Organize KPrepublic, K.T.E.C, xiudi boards into directories ([#12159](https://github.com/qmk/qmk_firmware/pull/12159)) +* Add Durgod Taurus K310 keyboard ([#12314](https://github.com/qmk/qmk_firmware/pull/12314)) +* add support for m65 and simple 5x13 ortholinear ([#12315](https://github.com/qmk/qmk_firmware/pull/12315)) +* Relocalize and Update p1800fl ([#12425](https://github.com/qmk/qmk_firmware/pull/12425)) +* GameBuddy v1.M ([#12637](https://github.com/qmk/qmk_firmware/pull/12637)) +* Add mechlovin9 rev2 PCB ([#12767](https://github.com/qmk/qmk_firmware/pull/12767)) +* Add RGB matrix support for Kyria ([#12789](https://github.com/qmk/qmk_firmware/pull/12789)) +* RGB Matrix working for Sofle RGB ([#12861](https://github.com/qmk/qmk_firmware/pull/12861)) +* Add Durgod Hades, Galaxy and Venus Keyboards ([#12893](https://github.com/qmk/qmk_firmware/pull/12893)) +* kint36: set correct EEPROM size ([#12946](https://github.com/qmk/qmk_firmware/pull/12946)) +* Updated encoder_update_user on my keymap to follow the new signature on quantum ([#13152](https://github.com/qmk/qmk_firmware/pull/13152)) +* Add Creator Pro by SergioPoverony ([#13154](https://github.com/qmk/qmk_firmware/pull/13154)) +* Use the new ST7565 driver on Ergodox Infinity ([#13165](https://github.com/qmk/qmk_firmware/pull/13165)) +* Refactor atom47 and add rev4 and rev5 ([#13201](https://github.com/qmk/qmk_firmware/pull/13201)) +* Add Bakeneko65 V3 and revision folders ([#13228](https://github.com/qmk/qmk_firmware/pull/13228)) +* Keyboards/RGBKB/Mün ([#13239](https://github.com/qmk/qmk_firmware/pull/13239)) +* Optimize our jsonschema by using refs ([#13271](https://github.com/qmk/qmk_firmware/pull/13271)) +* Handwired/Stream_Cheap/2x4: Add via support ([#13297](https://github.com/qmk/qmk_firmware/pull/13297)) +* ez_maker/directpins for easy one-offs in qmk_configurator ([#13321](https://github.com/qmk/qmk_firmware/pull/13321)) +* add kinT kinesis keyboard controller (kint41 variant) ([#13333](https://github.com/qmk/qmk_firmware/pull/13333)) +* Error log cleanup ([#13349](https://github.com/qmk/qmk_firmware/pull/13349)) +* Drashna's split updates ([#13350](https://github.com/qmk/qmk_firmware/pull/13350)) +* Migrate SHIFT_ESC and RGB `fn_actions` to Grave Escape and RGB keycodes ([#13360](https://github.com/qmk/qmk_firmware/pull/13360)) +* Add a lot more data to info.json ([#13366](https://github.com/qmk/qmk_firmware/pull/13366)) +* Remove `API_SYSEX_ENABLE`s from rules.mk ([#13389](https://github.com/qmk/qmk_firmware/pull/13389)) +* gmmk/pro/mike1808 keymap ([#13398](https://github.com/qmk/qmk_firmware/pull/13398)) +* Remove deprecated callbacks for encoders and dip switches ([#13404](https://github.com/qmk/qmk_firmware/pull/13404)) +* first pass: matrix consistency improvements ([#13471](https://github.com/qmk/qmk_firmware/pull/13471)) +* Migrate more `fn_actions` stuff ([#13502](https://github.com/qmk/qmk_firmware/pull/13502)) +* add simple gmmk pro macos keymap with rgb ([#13504](https://github.com/qmk/qmk_firmware/pull/13504)) +* move volcano660 to ilumkb folder ([#13550](https://github.com/qmk/qmk_firmware/pull/13550)) +* Valor Rev 2 ([#13551](https://github.com/qmk/qmk_firmware/pull/13551)) +* Split GMMK Pro PCBs into separate revisions ([#13570](https://github.com/qmk/qmk_firmware/pull/13570)) +* Remove the vision_division keyboard ([#13571](https://github.com/qmk/qmk_firmware/pull/13571)) +* Develop - Change uint32_t to layer_state_t ([#13596](https://github.com/qmk/qmk_firmware/pull/13596)) +* Develop - DC01 left ([#13597](https://github.com/qmk/qmk_firmware/pull/13597)) +* Created "paddlegame" keymap ([#13629](https://github.com/qmk/qmk_firmware/pull/13629)) +* Add timer_avr to includes for broken builds ([#13641](https://github.com/qmk/qmk_firmware/pull/13641)) +* Disable console by default on all Keebio boards ([#13649](https://github.com/qmk/qmk_firmware/pull/13649)) +* Enable LTO by default on BastardKB Scylla ([#13664](https://github.com/qmk/qmk_firmware/pull/13664)) +* Reduce compile size for dz60rgb v2.1 ([#13680](https://github.com/qmk/qmk_firmware/pull/13680)) +* Clean up remaining RGB_DISABLE_WHEN_USB_SUSPENDED defines ([#13689](https://github.com/qmk/qmk_firmware/pull/13689)) +* Remove some legacy files ([#13715](https://github.com/qmk/qmk_firmware/pull/13715)) +* [Keyboard Update] Change to L422 ([#13717](https://github.com/qmk/qmk_firmware/pull/13717)) +* Update kyria make path example ([#13720](https://github.com/qmk/qmk_firmware/pull/13720)) +* Drashna's Defaults cleanup ([#13722](https://github.com/qmk/qmk_firmware/pull/13722)) +* Reduce firmware size in prep for #12670 ([#13724](https://github.com/qmk/qmk_firmware/pull/13724)) +* Tidy up rgbkb/mun ([#13801](https://github.com/qmk/qmk_firmware/pull/13801)) +* Make default keymap for GMMK Pro reflect stock ([#13850](https://github.com/qmk/qmk_firmware/pull/13850)) +* Rework as per 9824 ([#13898](https://github.com/qmk/qmk_firmware/pull/13898)) +* Remove console from keebio via keyboards ([#13901](https://github.com/qmk/qmk_firmware/pull/13901)) +* Drashna split transport improvement ([#13905](https://github.com/qmk/qmk_firmware/pull/13905)) +* Copy GMMK Pro screw specs to ISO readme ([#13908](https://github.com/qmk/qmk_firmware/pull/13908)) +* Clean up remaining RGB_DISABLE_WHEN_USB_SUSPENDED defines Part 2 ([#13912](https://github.com/qmk/qmk_firmware/pull/13912)) +* Add andrebrait layout for GMMK Pro ([#13932](https://github.com/qmk/qmk_firmware/pull/13932)) +* Updated RGB Matrix suspend define part 3 ([#13954](https://github.com/qmk/qmk_firmware/pull/13954)) +* Improve andrebrait keymap ([#13985](https://github.com/qmk/qmk_firmware/pull/13985)) +* Drashna's Improve OLEDs and custom Split code ([#14063](https://github.com/qmk/qmk_firmware/pull/14063)) +* Kyria default reformat ([#14080](https://github.com/qmk/qmk_firmware/pull/14080)) +* Feature rich keymap for GMMK Pro (ANSI) ([#14120](https://github.com/qmk/qmk_firmware/pull/14120)) + +Keyboard fixes: +* Fix LED mapping for GMMK Pro ([#13189](https://github.com/qmk/qmk_firmware/pull/13189)) +* Fix up SplitKB keyboards ([#13511](https://github.com/qmk/qmk_firmware/pull/13511)) +* Keyboards/sol rev2 fix ([#13533](https://github.com/qmk/qmk_firmware/pull/13533)) +* Fix MATRIX_COLS for aeboards/constellation/rev2 ([#13633](https://github.com/qmk/qmk_firmware/pull/13633)) +* Fix errors with matrix_output_unselect_delay function calls ([#13645](https://github.com/qmk/qmk_firmware/pull/13645)) +* Fix default keymap for 0xCB 1337 keyboard ([#13646](https://github.com/qmk/qmk_firmware/pull/13646)) +* Fix Matrix Row number for ggkeyboards/genisis ([#13647](https://github.com/qmk/qmk_firmware/pull/13647)) +* Fix matrix issues with Promethium ([#13648](https://github.com/qmk/qmk_firmware/pull/13648)) +* Fix dc01/left so that it doesn't throw a warning ([#13653](https://github.com/qmk/qmk_firmware/pull/13653)) +* Remove broken, unmaintained converter/ibm_5291 ([#13658](https://github.com/qmk/qmk_firmware/pull/13658)) +* Quick hack to fix Astro65 board ([#13665](https://github.com/qmk/qmk_firmware/pull/13665)) +* Fix symmetric70_proto build break on develop branch ([#13667](https://github.com/qmk/qmk_firmware/pull/13667)) +* Fix matrix delay on Drop boards ([#13671](https://github.com/qmk/qmk_firmware/pull/13671)) +* Fix split matrix for sekigon grs 70ec ([#13672](https://github.com/qmk/qmk_firmware/pull/13672)) +* Fix type on pandora via keymap ([#13681](https://github.com/qmk/qmk_firmware/pull/13681)) +* Fix & clean up tronguylabs/m122_3270 ([#13684](https://github.com/qmk/qmk_firmware/pull/13684)) +* Fix up xd002 rgb keymaps ([#13685](https://github.com/qmk/qmk_firmware/pull/13685)) +* Dactyl Manuform cleanup ([#13686](https://github.com/qmk/qmk_firmware/pull/13686)) +* Fix Q1 change dip switch to bool ([#13687](https://github.com/qmk/qmk_firmware/pull/13687)) +* Fix compile size for the Merge UM70 via keymap ([#13690](https://github.com/qmk/qmk_firmware/pull/13690)) +* Fix compile size for the Lets Split Sockets via keymap ([#13691](https://github.com/qmk/qmk_firmware/pull/13691)) +* Fix Compile size on ungodly Launch Pad ([#13692](https://github.com/qmk/qmk_firmware/pull/13692)) +* dirty fix ([#13695](https://github.com/qmk/qmk_firmware/pull/13695)) +* Fix compile size for the Vitamins Included via keymap ([#13696](https://github.com/qmk/qmk_firmware/pull/13696)) +* Fix typo in Dactyl Manuform ([#13740](https://github.com/qmk/qmk_firmware/pull/13740)) +* Fix compile issues due to LED changes ([#13821](https://github.com/qmk/qmk_firmware/pull/13821)) +* Fix SRC include for matrix/m20add issi driver ([#13826](https://github.com/qmk/qmk_firmware/pull/13826)) +* fix develop branch move file ([#13832](https://github.com/qmk/qmk_firmware/pull/13832)) +* Fix knops keymaps ([#13872](https://github.com/qmk/qmk_firmware/pull/13872)) +* Switch Draculad to using WPM char hack ([#13886](https://github.com/qmk/qmk_firmware/pull/13886)) +* Fix up builds after #8591 ([#13900](https://github.com/qmk/qmk_firmware/pull/13900)) +* Fix matrix_output_unselect_delay for handwired/xealousbrown ([#13913](https://github.com/qmk/qmk_firmware/pull/13913)) +* Fixup rgb matrix config for KBD67 mkII boards ([#13931](https://github.com/qmk/qmk_firmware/pull/13931)) +* Fix compliation for ferris 0.2 bling ([#13937](https://github.com/qmk/qmk_firmware/pull/13937)) +* Fix some additional bootmagic settings ([#13979](https://github.com/qmk/qmk_firmware/pull/13979)) +* Fix default keymap for GMMK Pro Iso ([#13980](https://github.com/qmk/qmk_firmware/pull/13980)) +* Fixup Ungodly Launch Pad config ([#13992](https://github.com/qmk/qmk_firmware/pull/13992)) +* Fix errors that have cropped up in develop ([#14005](https://github.com/qmk/qmk_firmware/pull/14005)) +* Fix wait_us overflow in matrix for dactyl based boards ([#14039](https://github.com/qmk/qmk_firmware/pull/14039)) +* Fixup Neson Design N6 ISSI includes ([#14045](https://github.com/qmk/qmk_firmware/pull/14045)) +* Fixup `massdrop/alt`, `cest73/tkm`. ([#14048](https://github.com/qmk/qmk_firmware/pull/14048)) +* fix helix:fraanrosi compile error caused by #13677. ([#14061](https://github.com/qmk/qmk_firmware/pull/14061)) +* Fix compile issues for Tractyl Manuform ([#14105](https://github.com/qmk/qmk_firmware/pull/14105)) +* Disable Console on Keebio Quefrency ([#14108](https://github.com/qmk/qmk_firmware/pull/14108)) +* Fixed GMMK Pro -> stickandgum keymap readme.md ([#14123](https://github.com/qmk/qmk_firmware/pull/14123)) +* Drashna keymap fixups ([#14140](https://github.com/qmk/qmk_firmware/pull/14140)) +* fix ([#14142](https://github.com/qmk/qmk_firmware/pull/14142)) +* Fix merge artifacts ([#14146](https://github.com/qmk/qmk_firmware/pull/14146)) +* Update readme files ([#14172](https://github.com/qmk/qmk_firmware/pull/14172)) + +Others: +* Add examples to RGB Matrix Indicators docs ([#12797](https://github.com/qmk/qmk_firmware/pull/12797)) + +Bugs: +* Fix Indicator LED issues ([#12097](https://github.com/qmk/qmk_firmware/pull/12097)) +* Fixing incorrect keymap build when switching between multiple keymap.jsons ([#12632](https://github.com/qmk/qmk_firmware/pull/12632)) +* Fix LED Hit Counter for LED/RGB Matrix ([#12674](https://github.com/qmk/qmk_firmware/pull/12674)) +* ChibiOS fix O3 and LTO breakage of extra keys and joystick ([#12819](https://github.com/qmk/qmk_firmware/pull/12819)) +* Remove the #10088 hotfix for Teensy 3.1-like Input:Club keyboards ([#12870](https://github.com/qmk/qmk_firmware/pull/12870)) +* Fix firmware size check with avr-libc 1:2.0.0+Atmel3.6.2-1.1 (Debian bullseye) ([#12951](https://github.com/qmk/qmk_firmware/pull/12951)) +* Fix RGB/LED Suspend defines ([#13146](https://github.com/qmk/qmk_firmware/pull/13146)) +* Fix overrun in st7565_write_raw when not at (0, 0) ([#13209](https://github.com/qmk/qmk_firmware/pull/13209)) +* Upgrades Vagrant box to Debian 10 to fix Docker build error on Debian 9. ([#13236](https://github.com/qmk/qmk_firmware/pull/13236)) +* Fix issues with VIA EEPROM init and bring in line with eeconfig functionality ([#13243](https://github.com/qmk/qmk_firmware/pull/13243)) +* Fix CRC for AVR and enable again. ([#13253](https://github.com/qmk/qmk_firmware/pull/13253)) +* Fix linker error when rgblight and RGB Matrix are both enabled ([#13304](https://github.com/qmk/qmk_firmware/pull/13304)) +* Fix building layouts from JSON ([#13310](https://github.com/qmk/qmk_firmware/pull/13310)) +* Add rgblight to RGB Matrix VPATH ([#13371](https://github.com/qmk/qmk_firmware/pull/13371)) +* Fix two out of bounds accesses from #13330. ([#13525](https://github.com/qmk/qmk_firmware/pull/13525)) +* Fixes for clang not being able to run unit tests ([#13546](https://github.com/qmk/qmk_firmware/pull/13546)) +* Fixup Audio startup and add to documents ([#13606](https://github.com/qmk/qmk_firmware/pull/13606)) +* CLI/Docs: Fix the format commands' name ([#13668](https://github.com/qmk/qmk_firmware/pull/13668)) +* Disables rgblight twinkle by default. ([#13677](https://github.com/qmk/qmk_firmware/pull/13677)) +* Fix typo in dip switch example ([#13688](https://github.com/qmk/qmk_firmware/pull/13688)) +* docs/cli_commands: fix typo ([#13697](https://github.com/qmk/qmk_firmware/pull/13697)) +* Include gpio.h in solenoid driver for GPIO Control functions ([#13716](https://github.com/qmk/qmk_firmware/pull/13716)) +* Fix pimoroni trackball read address ([#13810](https://github.com/qmk/qmk_firmware/pull/13810)) +* Fix Key Override includes ([#13831](https://github.com/qmk/qmk_firmware/pull/13831)) +* Fix alignment of USB out report buffer 2 -> 4 ([#13838](https://github.com/qmk/qmk_firmware/pull/13838)) +* Fix compilation issue. ([#13926](https://github.com/qmk/qmk_firmware/pull/13926)) +* Fix `combo_disable` ([#13988](https://github.com/qmk/qmk_firmware/pull/13988)) +* Fix pmw3360 code to only output debug info if mouse debugging is enabled ([#13993](https://github.com/qmk/qmk_firmware/pull/13993)) +* Fix ifdefs for OLED split sync code ([#14017](https://github.com/qmk/qmk_firmware/pull/14017)) +* Various fixes from reorg of files ([#14051](https://github.com/qmk/qmk_firmware/pull/14051)) +* Fixup atsam builds. ([#14052](https://github.com/qmk/qmk_firmware/pull/14052)) +* Fix RGB/LED Matrix Suspend code ([#14084](https://github.com/qmk/qmk_firmware/pull/14084)) +* Fix issues with recent keymap.json changes ([#14089](https://github.com/qmk/qmk_firmware/pull/14089)) +* Fix LED Matrix suspend code ([#14090](https://github.com/qmk/qmk_firmware/pull/14090)) +* Fix up compilation issues. ([#14095](https://github.com/qmk/qmk_firmware/pull/14095)) +* Fix copypasta issue with pmw3360 sensor config ([#14106](https://github.com/qmk/qmk_firmware/pull/14106)) +* Fix typo ([#14118](https://github.com/qmk/qmk_firmware/pull/14118)) +* Fix bootloadHID comments breaking :flash ([#14133](https://github.com/qmk/qmk_firmware/pull/14133)) +* Fix Mouse Shared EP functionality ([#14136](https://github.com/qmk/qmk_firmware/pull/14136)) +* Short term bodge for firmware size bloat ([#14144](https://github.com/qmk/qmk_firmware/pull/14144)) +* Move to correct location ([#14171](https://github.com/qmk/qmk_firmware/pull/14171)) diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md index 56a59648c0..c5f4eec04d 100644 --- a/docs/breaking_changes.md +++ b/docs/breaking_changes.md @@ -6,6 +6,7 @@ The breaking change period is when we will merge PR's that change QMK in dangero ## What has been included in past Breaking Changes? +* [2021 Aug 28](ChangeLog/20210828.md) * [2021 May 29](ChangeLog/20210529.md) * [2021 Feb 27](ChangeLog/20210227.md) * [2020 Nov 28](ChangeLog/20201128.md) @@ -20,12 +21,12 @@ The next Breaking Change is scheduled for August 28, 2021. ### Important Dates -* [x] 2021 May 29 - `develop` is created. Each push to `master` is subsequently merged to `develop` -* [ ] 2021 Jul 31 - `develop` closed to new PR's. -* [ ] 2021 Jul 31 - Call for testers. -* [ ] 2021 Aug 26 - `master` is locked, no PR's merged. -* [ ] 2021 Aug 28 - Merge `develop` to `master`. -* [ ] 2021 Aug 28 - `master` is unlocked. PR's can be merged again. +* [x] 2021 Aug 29 - `develop` is created. Each push to `master` is subsequently merged to `develop` +* [ ] 2021 Oct 31 - `develop` closed to new PR's. +* [ ] 2021 Oct 31 - Call for testers. +* [ ] 2021 Nov 26 - `master` is locked, no PR's merged. +* [ ] 2021 Nov 28 - Merge `develop` to `master`. +* [ ] 2021 Nov 28 - `master` is unlocked. PR's can be merged again. ## What changes will be included? diff --git a/docs/breaking_changes_history.md b/docs/breaking_changes_history.md index 6ba8fe3b06..f78e97f1c7 100644 --- a/docs/breaking_changes_history.md +++ b/docs/breaking_changes_history.md @@ -2,6 +2,7 @@ This page links to all previous changelogs from the QMK Breaking Changes process. +* [2021 Aug 28](ChangeLog/20210828.md) - version 0.14.0 * [2021 May 29](ChangeLog/20210529.md) - version 0.13.0 * [2021 Feb 27](ChangeLog/20210227.md) - version 0.12.0 * [2020 Nov 28](ChangeLog/20201128.md) - version 0.11.0 -- cgit v1.2.3