diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ChangeLog/20230226/PR15741.md | 43 | ||||
| -rw-r--r-- | docs/_summary.md | 2 | ||||
| -rw-r--r-- | docs/config_options.md | 20 | ||||
| -rw-r--r-- | docs/feature_auto_shift.md | 11 | ||||
| -rw-r--r-- | docs/feature_leader_key.md | 12 | ||||
| -rw-r--r-- | docs/feature_os_detection.md | 77 | ||||
| -rw-r--r-- | docs/feature_pointing_device.md | 21 | ||||
| -rw-r--r-- | docs/feature_unicode.md | 10 | ||||
| -rw-r--r-- | docs/ja/config_options.md | 2 | ||||
| -rw-r--r-- | docs/ja/feature_grave_esc.md | 4 | ||||
| -rw-r--r-- | docs/ja/tap_hold.md | 19 | ||||
| -rw-r--r-- | docs/newbs_building_firmware.md | 2 | ||||
| -rw-r--r-- | docs/platformdev_rp2040.md | 6 | ||||
| -rw-r--r-- | docs/quantum_painter_lvgl.md | 55 | ||||
| -rw-r--r-- | docs/reference_info_json.md | 35 | ||||
| -rw-r--r-- | docs/tap_hold.md | 124 | ||||
| -rw-r--r-- | docs/zh-cn/feature_grave_esc.md | 4 |
17 files changed, 354 insertions, 93 deletions
diff --git a/docs/ChangeLog/20230226/PR15741.md b/docs/ChangeLog/20230226/PR15741.md new file mode 100644 index 0000000000..385816d65b --- /dev/null +++ b/docs/ChangeLog/20230226/PR15741.md @@ -0,0 +1,43 @@ +`IGNORE_MOD_TAP_INTERRUPT_PER_KEY` has been removed and `IGNORE_MOD_TAP_INTERRUPT` deprecated as a stepping stone towards making `IGNORE_MOD_TAP_INTERRUPT` the new default behavior for mod-taps in the future. + +In place of the now removed `IGNORE_MOD_TAP_INTERRUPT_PER_KEY`, one must use the pre-existing `HOLD_ON_OTHER_KEY_PRESS` option. + +In most cases, updating `get_ignore_mod_tap_interrupt` to `get_hold_on_other_key_press` is simply a matter of renaming the function and swapping every `true` by `false` and vice versa. The one subtlety you may need to look out for is that the `get_ignore_mod_tap_interrupt` was only ever called with mod-taps passed in as the `keycode` argument, while the `keycode` argument of `get_hold_on_other_key_press` can be any dual-role key. This includes not only mod-taps, but also layer-taps, one shot keys, `TT(layer)` and more. This has an impact on the effect of the `default` case in a typical per-key configuration making use of a `switch(keycode)` statement. + +To illustrate, let's take the example of a configuration where we'd want all mod-taps to activate the modifier if another key is pressed while held with the exception of `LCTL_T(KC_A)`, which should ignore keys pressed while it is held and activate the modifier only if it has been held for longer than the tapping term. In addition, we would like to keep the default "ignore-interrupt" behavior of layer taps. + +An old way to do this would be via the following code: + +```c +bool get_ignore_mod_tap_interrupt(uint16_t keycode, keyrecord_t *record) { + switch(keycode) { + case LCTL_T(KC_A): + return true; + default: + return false; + } +} +``` + +The correct way to update this code without accidentally changing how the layer-taps work would be the following: + +```c +bool get_hold_on_other_key_press(uint16_t keycode, keyrecord_t *record) { + switch(keycode) { + // Capture all mod-tap keycodes. + case QK_MOD_TAP ... QK_MOD_TAP_MAX: + if (keycode == LCTL_T(KC_A)) { + // Disable HOLD_ON_OTHER_KEY_PRESS for LCTL_T(KC_A) + // aka enable IGNORE_MOD_TAP_INTERRUPT for LCTL_T(KC_A). + return false; + } else { + // Enable HOLD_ON_OTHER_KEY_PRESS for every other mod-tap keycode. + return true; + } + default: + return false; + } +} +``` + +For more information, you are invited to read the sections on [IGNORE_MOD_TAP_INTERRUPT](tap_hold.md#ignore-mod-tap-interrupt) and [HOLD_ON_OTHER_KEY_PRESS](tap_hold.md#hold-on-other-key-press) in the page on [Tap-Hold configuration options](tap_hold.md). diff --git a/docs/_summary.md b/docs/_summary.md index 738c24ee42..d2d4bb9b32 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -85,6 +85,7 @@ * [Key Overrides](feature_key_overrides.md) * [Layers](feature_layers.md) * [One Shot Keys](one_shot_keys.md) + * [OS Detection](feature_os_detection.md) * [Raw HID](feature_rawhid.md) * [Secure](feature_secure.md) * [Send String](feature_send_string.md) @@ -99,6 +100,7 @@ * Hardware Features * Displays * [Quantum Painter](quantum_painter.md) + * [Quantum Painter LVGL Integration](quantum_painter_lvgl.md) * [HD44780 LCD Driver](feature_hd44780.md) * [ST7565 LCD Driver](feature_st7565.md) * [OLED Driver](feature_oled_driver.md) diff --git a/docs/config_options.md b/docs/config_options.md index 6b1f83214c..7a91160bcd 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -169,14 +169,18 @@ If you define these options you will enable the associated feature, which may in * `#define IGNORE_MOD_TAP_INTERRUPT` * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold, by enforcing the `TAPPING_TERM` for both keys. * See [Ignore Mod Tap Interrupt](tap_hold.md#ignore-mod-tap-interrupt) for details -* `#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY` - * enables handling for per key `IGNORE_MOD_TAP_INTERRUPT` settings -* `#define TAPPING_FORCE_HOLD` - * makes it possible to use a dual role key as modifier shortly after having been tapped - * See [Tapping Force Hold](tap_hold.md#tapping-force-hold) - * Breaks any Tap Toggle functionality (`TT` or the One Shot Tap Toggle) -* `#define TAPPING_FORCE_HOLD_PER_KEY` - * enables handling for per key `TAPPING_FORCE_HOLD` settings +* `#define QUICK_TAP_TERM 100` + * tap-then-hold timing to use a dual role key to repeat keycode + * See [Quick Tap Term](tap_hold.md#quick-tap-term) + * Changes the timing of Tap Toggle functionality (`TT` or the One Shot Tap Toggle) + * Defaults to `TAPPING_TERM` if not defined +* `#define QUICK_TAP_TERM_PER_KEY` + * enables handling for per key `QUICK_TAP_TERM` settings +* `#define HOLD_ON_OTHER_KEY_PRESS` + * selects the hold action of a dual-role key as soon as the tap of the dual-role key is interrupted by the press of another key. + * See "[hold on other key press](tap_hold.md#hold-on-other-key-press)" for details +* `#define HOLD_ON_OTHER_KEY_PRESS_PER_KEY` + * enables handling for per key `HOLD_ON_OTHER_KEY_PRESS` settings * `#define LEADER_TIMEOUT 300` * how long before the leader key times out * If you're having issues finishing the sequence before it times out, you may need to increase the timeout setting. Or you may want to enable the `LEADER_PER_KEY_TIMING` option, which resets the timeout after each key is tapped. diff --git a/docs/feature_auto_shift.md b/docs/feature_auto_shift.md index d3437a9c60..1719807e26 100644 --- a/docs/feature_auto_shift.md +++ b/docs/feature_auto_shift.md @@ -281,16 +281,7 @@ Tap Hold Configurations work a little differently when using Retro Shift. Referencing `TAPPING_TERM` makes little sense, as holding longer would result in shifting one of the keys. -`IGNORE_MOD_TAP_INTERRUPT` changes *only* rolling from a mod tap (releasing it -first), sending both keys instead of the modifier on the second. Its effects on -nested presses are ignored. - -As nested taps were changed to act as though `PERMISSIVE_HOLD` is set unless only -`IGNORE_MOD_TAP_INTERRUPT` is (outside of Retro Shift), and Retro Shift ignores -`IGNORE_MOD_TAP_INTERRUPT`, `PERMISSIVE_HOLD` has no effect on Mod Taps. - -Nested taps will *always* act as though the `TAPPING_TERM` was exceeded for both -Mod and Layer Tap keys. +`RETRO_SHIFT` enables [`PERMISSIVE_HOLD`-like behaviour](tap_hold.md#permissive-hold) (even if not explicitly enabled) on all mod-taps for which `RETRO_SHIFT` applies. ## Using Auto Shift Setup diff --git a/docs/feature_leader_key.md b/docs/feature_leader_key.md index e285d10597..4e7a487be7 100644 --- a/docs/feature_leader_key.md +++ b/docs/feature_leader_key.md @@ -93,18 +93,18 @@ While, this may be fine for most, if you want to specify the whole keycode (eg, ## Customization -The Leader Key feature has some additional customization to how the Leader Key feature works. It has two functions that can be called at certain parts of the process. Namely `leader_start()` and `leader_end()`. +The Leader Key feature has some additional customization to how the Leader Key feature works. It has two functions that can be called at certain parts of the process. Namely `leader_start_user()` and `leader_end_user()`. -The `leader_start()` function is called when you tap the `QK_LEAD` key, and the `leader_end()` function is called when either the leader sequence is completed, or the leader timeout is hit. +The `leader_start_user()` function is called when you tap the `QK_LEAD` key, and the `leader_end_user()` function is called when either the leader sequence is completed, or the leader timeout is hit. You can add these functions to your code (`keymap.c` usually) to add feedback to the Leader sequences (such as beeping or playing music). ```c -void leader_start(void) { +void leader_start_user(void) { // sequence started } -void leader_end(void) { +void leader_end_user(void) { // sequence ended (no success/failure detection) } ``` @@ -139,13 +139,13 @@ void matrix_scan_user(void) { } } -void leader_start(void) { +void leader_start_user(void) { #ifdef AUDIO_ENABLE PLAY_SONG(leader_start); #endif } -void leader_end(void) { +void leader_end_user(void) { if (did_leader_succeed) { #ifdef AUDIO_ENABLE PLAY_SONG(leader_succeed); diff --git a/docs/feature_os_detection.md b/docs/feature_os_detection.md new file mode 100644 index 0000000000..f32e419807 --- /dev/null +++ b/docs/feature_os_detection.md @@ -0,0 +1,77 @@ +# OS Detection + +This feature makes a best guess at the host OS based on OS specific behavior during USB setup. It may not always get the correct OS, and shouldn't be relied on as for critical functionality. + +Using it you can have OS specific key mappings or combos which work differently on different devices. + +It is available for keyboards which use ChibiOS, LUFA and V-USB. + +## Usage + +In your `rules.mk` add: + +```make +OS_DETECTION_ENABLE = yes +``` + +Include `"os_detection.h"` in your `keymap.c`. +It declares `os_variant_t detected_host_os(void);` which you can call to get detected OS. + +It returns one of the following values: + +```c +enum { + OS_UNSURE, + OS_LINUX, + OS_WINDOWS, + OS_MACOS, + OS_IOS, +} os_variant_t; +``` + +?> Note that it takes some time after firmware is booted to detect the OS. +This time is quite short, probably hundreds of milliseconds, but this data may be not ready in keyboard and layout setup functions which run very early during firmware startup. + +## Debug + +If OS is guessed incorrectly, you may want to collect data about USB setup packets to refine the detection logic. + +To do so in your `rules.mk` add: + +```make +OS_DETECTION_DEBUG_ENABLE = yes +CONSOLE_ENABLE = yes +``` + +And also include `"os_detection.h"` in your `keymap.c`. + +Then you can define custom keycodes to store data about USB setup packets in EEPROM (persistent memory) and to print it later on host where you can run `qmk console`: + +```c +enum custom_keycodes { + STORE_SETUPS = SAFE_RANGE, + PRINT_SETUPS, +}; + +bool process_record_user(uint16_t keycode, keyrecord_t *record) { + switch (keycode) { + case STORE_SETUPS: + if (record->event.pressed) { + store_setups_in_eeprom(); + } + return false; + case PRINT_SETUPS: + if (record->event.pressed) { + print_stored_setups(); + } + return false; + } +} +``` + +Then please open an issue on Github with this information and tell what OS was not detected correctly and if you have any intermediate devices between keyboard and your computer. + + +## Credits + +Original idea is coming from [FingerprintUSBHost](https://github.com/keyboardio/FingerprintUSBHost) project. diff --git a/docs/feature_pointing_device.md b/docs/feature_pointing_device.md index be984dd5a5..ecb7ee42cb 100644 --- a/docs/feature_pointing_device.md +++ b/docs/feature_pointing_device.md @@ -22,11 +22,11 @@ POINTING_DEVICE_DRIVER = adns5050 The ADNS 5050 sensor uses a serial type protocol for communication, and requires an additional light source. -| Setting | Description | Default | -| ------------------- | ------------------------------------------------------------------- | -------------------------- | -| `ADNS5050_SCLK_PIN` | (Required) The pin connected to the clock pin of the sensor. | `POINTING_DEVICE_SCLK_PIN` | -| `ADNS5050_SDIO_PIN` | (Required) The pin connected to the data pin of the sensor. | `POINTING_DEVICE_SDIO_PIN` | -| `ADNS5050_CS_PIN` | (Required) The pin connected to the cable select pin of the sensor. | `POINTING_DEVICE_CS_PIN` | +| Setting | Description | Default | +| ------------------- | ------------------------------------------------------------------ | -------------------------- | +| `ADNS5050_SCLK_PIN` | (Required) The pin connected to the clock pin of the sensor. | `POINTING_DEVICE_SCLK_PIN` | +| `ADNS5050_SDIO_PIN` | (Required) The pin connected to the data pin of the sensor. | `POINTING_DEVICE_SDIO_PIN` | +| `ADNS5050_CS_PIN` | (Required) The pin connected to the Chip Select pin of the sensor. | `POINTING_DEVICE_CS_PIN` | @@ -48,7 +48,7 @@ The ADNS 9800 is an SPI driven optical sensor, that uses laser output for surfac | `ADNS9800_SPI_LSBFIRST` | (Optional) Sets the Least/Most Significant Byte First setting for SPI. | `false` | | `ADNS9800_SPI_MODE` | (Optional) Sets the SPI Mode for the sensor. | `3` | | `ADNS9800_SPI_DIVISOR` | (Optional) Sets the SPI Divisor used for SPI communication. | _varies_ | -| `ADNS9800_CS_PIN` | (Required) Sets the Cable Select pin connected to the sensor. | `POINTING_DEVICE_CS_PIN` | +| `ADNS9800_CS_PIN` | (Required) Sets the Chip Select pin connected to the sensor. | `POINTING_DEVICE_CS_PIN` | The CPI range is 800-8200, in increments of 200. Defaults to 1800 CPI. @@ -124,7 +124,7 @@ Default attenuation is set to 4X, although if you are using a thicker overlay (s | `CIRQUE_PINNACLE_SPI_LSBFIRST` | (Optional) Sets the Least/Most Significant Byte First setting for SPI. | `false` | | `CIRQUE_PINNACLE_SPI_MODE` | (Optional) Sets the SPI Mode for the sensor. | `1` | | `CIRQUE_PINNACLE_SPI_DIVISOR` | (Optional) Sets the SPI Divisor used for SPI communication. | _varies_ | -| `CIRQUE_PINNACLE_SPI_CS_PIN` | (Required) Sets the Cable Select pin connected to the sensor. | `POINTING_DEVICE_CS_PIN` | +| `CIRQUE_PINNACLE_SPI_CS_PIN` | (Required) Sets the Chip Select pin connected to the sensor. | `POINTING_DEVICE_CS_PIN` | Default Scaling is 1024. Actual CPI depends on trackpad diameter. @@ -218,11 +218,14 @@ POINTING_DEVICE_DRIVER = pmw3389 The CPI range is 50-16000, in increments of 50. Defaults to 2000 CPI. Both PMW 3360 and PMW 3389 are SPI driven optical sensors, that use a built in IR LED for surface tracking. +If you have different CS wiring on each half you can use `PMW33XX_CS_PIN_RIGHT` or `PMW33XX_CS_PINS_RIGHT` in combination with `PMW33XX_CS_PIN` or `PMW33XX_CS_PINS` to configure both sides independently. If `_RIGHT` values aren't provided, they default to be the same as the left ones. | Setting | Description | Default | | ---------------------------- | ------------------------------------------------------------------------------------------- | ------------------------ | -| `PMW33XX_CS_PIN` | (Required) Sets the Cable Select pin connected to the sensor. | `POINTING_DEVICE_CS_PIN` | -| `PMW33XX_CS_PINS` | (Alternative) Sets the Cable Select pins connected to multiple sensors. | _not defined_ | +| `PMW33XX_CS_PIN` | (Required) Sets the Chip Select pin connected to the sensor. | `POINTING_DEVICE_CS_PIN` | +| `PMW33XX_CS_PINS` | (Alternative) Sets the Chip Select pins connected to multiple sensors. | `{PMW33XX_CS_PIN}` | +| `PMW33XX_CS_PIN_RIGHT` | (Optional) Sets the Chip Select pin connected to the sensor on the right half. | `PMW33XX_CS_PIN` | +| `PMW33XX_CS_PINS_RIGHT` | (Optional) Sets the Chip Select pins connected to multiple sensors on the right half. | `{PMW33XX_CS_PIN_RIGHT}` | | `PMW33XX_CPI` | (Optional) Sets counts per inch sensitivity of the sensor. | _varies_ | | `PMW33XX_CLOCK_SPEED` | (Optional) Sets the clock speed that the sensor runs at. | `2000000` | | `PMW33XX_SPI_DIVISOR` | (Optional) Sets the SPI Divisor used for SPI communication. | _varies_ | diff --git a/docs/feature_unicode.md b/docs/feature_unicode.md index a93e9ad2ba..1ea411191e 100644 --- a/docs/feature_unicode.md +++ b/docs/feature_unicode.md @@ -83,7 +83,7 @@ UCIS_ENABLE = yes Then define a table like this in your keymap file: ```c -const qk_ucis_symbol_t ucis_symbol_table[] = UCIS_TABLE( +const ucis_symbol_t ucis_symbol_table[] = UCIS_TABLE( UCIS_SYM("poop", 0x1F4A9), // 💩 UCIS_SYM("rofl", 0x1F923), // 🤣 UCIS_SYM("cuba", 0x1F1E8, 0x1F1FA), // 🇨🇺 @@ -93,15 +93,15 @@ const qk_ucis_symbol_t ucis_symbol_table[] = UCIS_TABLE( By default, each table entry may be up to 3 code points long. This number can be changed by adding `#define UCIS_MAX_CODE_POINTS n` to your `config.h` file. -To use UCIS input, call `qk_ucis_start()`. Then, type the mnemonic for the character (such as "rofl") and hit Space, Enter or Esc. QMK should erase the "rofl" text and insert the laughing emoji. +To use UCIS input, call `ucis_start()`. Then, type the mnemonic for the character (such as "rofl") and hit Space, Enter or Esc. QMK should erase the "rofl" text and insert the laughing emoji. #### Customization There are several functions that you can define in your keymap to customize the functionality of this feature. -* `void qk_ucis_start_user(void)` – This runs when you call the "start" function, and can be used to provide feedback. By default, it types out a keyboard emoji. -* `void qk_ucis_success(uint8_t symbol_index)` – This runs when the input has matched something and has completed. By default, it doesn't do anything. -* `void qk_ucis_symbol_fallback (void)` – This runs when the input doesn't match anything. By default, it falls back to trying that input as a Unicode code. +* `void ucis_start_user(void)` – This runs when you call the "start" function, and can be used to provide feedback. By default, it types out a keyboard emoji. +* `void ucis_success(uint8_t symbol_index)` – This runs when the input has matched something and has completed. By default, it doesn't do anything. +* `void ucis_symbol_fallback (void)` – This runs when the input doesn't match anything. By default, it falls back to trying that input as a Unicode code. You can find the default implementations of these functions in [`process_ucis.c`](https://github.com/qmk/qmk_firmware/blob/master/quantum/process_keycode/process_ucis.c). diff --git a/docs/ja/config_options.md b/docs/ja/config_options.md index c95753bd5d..6135721a42 100644 --- a/docs/ja/config_options.md +++ b/docs/ja/config_options.md @@ -162,8 +162,6 @@ QMK ã§ã®å…¨ã¦ã®åˆ©ç”¨å¯èƒ½ãªè¨å®šã«ã¯ãƒ‡ãƒ•ã‚©ãƒ«ãƒˆãŒã‚ã‚Šã¾ã™ã€‚ã * `#define IGNORE_MOD_TAP_INTERRUPT` * 両方ã®ã‚ー㫠`TAPPING_TERM` ã‚’é©ç”¨ã™ã‚‹ã“ã¨ã§ã€ãƒ›ãƒ¼ãƒ«ãƒ‰æ™‚ã«ä»–ã®ã‚ーã«å¤‰æ›ã™ã‚‹ã‚ーを使ã£ã¦ãƒãƒ¼ãƒªãƒ³ã‚°ã‚³ãƒ³ãƒœ (zx) ã‚’ã™ã‚‹ã“ã¨ãŒã§ãるよã†ã«ã—ã¾ã™ * 詳細㯠[Ignore Mod Tap Interrupt](ja/tap_hold.md#ignore-mod-tap-interrupt) を見ã¦ãã ã•ã„ -* `#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY` - * ã‚ーã”ã¨ã® `IGNORE_MOD_TAP_INTERRUPT` è¨å®šã®å‡¦ç†ã‚’有効ã«ã—ã¾ã™ * `#define TAPPING_FORCE_HOLD` * タップã•ã‚ŒãŸç›´å¾Œã«ã€ãƒ‡ãƒ¥ã‚¢ãƒ«ãƒãƒ¼ãƒ«ã‚ーを修飾åã¨ã—ã¦ä½¿ç”¨ã§ãるよã†ã«ã—ã¾ã™ * [Tapping Force Hold](ja/tap_hold.md#tapping-force-hold)を見ã¦ãã ã•ã„ diff --git a/docs/ja/feature_grave_esc.md b/docs/ja/feature_grave_esc.md index 8c6680d74d..746e9e5d14 100644 --- a/docs/ja/feature_grave_esc.md +++ b/docs/ja/feature_grave_esc.md @@ -9,7 +9,7 @@ ## 使用法 -ã‚ーマップ内㮠`KC_GRAVE` ã‚ー (通常ã¯`1` ã‚ーã®å·¦)ã‚’ `KC_GESC` ã«ç½®ãæ›ãˆã¾ã™ã€‚ã»ã¨ã‚“ã©ã®å ´åˆã€ã“ã®ã‚ーã¯æŠ¼ã•ã‚ŒãŸæ™‚ã« `KC_ESC` を出力ã—ã¾ã™ã€‚ãŸã ã—ã€Shift ã‚ã‚‹ã„㯠GUI を押ã—ãŸã¾ã¾ã«ã™ã‚‹ã¨ã€ä»£ã‚ã‚Šã« `KC_GRV` を出力ã—ã¾ã™ã€‚ +ã‚ーマップ内㮠`KC_GRAVE` ã‚ー (通常ã¯`1` ã‚ーã®å·¦)ã‚’ `QK_GESC` ã«ç½®ãæ›ãˆã¾ã™ã€‚ã»ã¨ã‚“ã©ã®å ´åˆã€ã“ã®ã‚ーã¯æŠ¼ã•ã‚ŒãŸæ™‚ã« `KC_ESC` を出力ã—ã¾ã™ã€‚ãŸã ã—ã€Shift ã‚ã‚‹ã„㯠GUI を押ã—ãŸã¾ã¾ã«ã™ã‚‹ã¨ã€ä»£ã‚ã‚Šã« `KC_GRV` を出力ã—ã¾ã™ã€‚ ## OS ã«è¦‹ãˆã‚‹ã‚‚ã® @@ -19,7 +19,7 @@ | ã‚ー | エイリアス | 説明 | |---------|-----------|------------------------------------------------------------------| -| `KC_GESC` | `GRAVE_ESC` | 押ã•ã‚ŒãŸå ´åˆã« Escape。Shift ã‚ã‚‹ã„㯠GUI ãŒæŠ¼ã•ã‚ŒãŸã¾ã¾ã®å ´åˆã¯ <code>`</code> | +| `QK_GESC` | `GRAVE_ESC` | 押ã•ã‚ŒãŸå ´åˆã« Escape。Shift ã‚ã‚‹ã„㯠GUI ãŒæŠ¼ã•ã‚ŒãŸã¾ã¾ã®å ´åˆã¯ <code>`</code> | ### 注æ„äº‹é … diff --git a/docs/ja/tap_hold.md b/docs/ja/tap_hold.md index 07242821a9..ac64fe6ce3 100644 --- a/docs/ja/tap_hold.md +++ b/docs/ja/tap_hold.md @@ -110,25 +110,6 @@ bool get_permissive_hold(uint16_t keycode, keyrecord_t *record) { ?> `許容ホールド`を有効ã«ã™ã‚‹ã¨ã€ã“ã‚Œã¯ä¸¡æ–¹ãŒã©ã®ã‚ˆã†ã«å‹•ä½œã™ã‚‹ã‹ã‚’変更ã—ã¾ã™ã€‚通常ã®ã‚ーã«ã¯ã€æœ€åˆã®ã‚ーãŒæœ€åˆã«æ”¾ã•ã‚ŒãŸå ´åˆã€ã‚ã‚‹ã„ã¯ä¸¡æ–¹ã®ã‚ー㌠`TAPPING_TERM` より長ãホールドã•ã‚ŒãŸå ´åˆã«ã€ä¿®é£¾ã‚ーãŒè¿½åŠ ã•ã‚Œã¾ã™ã€‚ -ã“ã®æ©Ÿèƒ½ã‚’より細ã‹ã制御ã™ã‚‹ãŸã‚ã«ã€ä»¥ä¸‹ã‚’ `config.h` ã«è¿½åŠ ã™ã‚‹ã“ã¨ãŒã§ãã¾ã™: - -```c -#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY -``` - -ãã—ã¦ã€ä»¥ä¸‹ã®é–¢æ•°ã‚’ã‚ーマップã«è¿½åŠ ã—ã¾ã™: - -```c -bool get_ignore_mod_tap_interrupt(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case SFT_T(KC_SPC): - return true; - default: - return false; - } -} -``` - ## タッピング強制ホールド `タッピング強制ホールド` を有効ã«ã™ã‚‹ã«ã¯ã€ä»¥ä¸‹ã‚’ `config.h` ã«è¿½åŠ ã—ã¾ã™: diff --git a/docs/newbs_building_firmware.md b/docs/newbs_building_firmware.md index 6163c6b02e..de9217e9f0 100644 --- a/docs/newbs_building_firmware.md +++ b/docs/newbs_building_firmware.md @@ -28,7 +28,7 @@ If you did not configure your environment, or you have multiple keyboards, you c Look at the output from that command, you should see something like this: - Ψ <github_username> keymap directory created in: /home/me/qmk_firmware/keyboards/clueboard/66/rev3/keymaps/<github_username> + Ψ Created a new keymap called <github_username> in: /home/me/qmk_firmware/keyboards/clueboard/66/rev3/keymaps/<github_username>. This is the location of your new `keymap.c` file. diff --git a/docs/platformdev_rp2040.md b/docs/platformdev_rp2040.md index 3a6f1a1683..11a93edd89 100644 --- a/docs/platformdev_rp2040.md +++ b/docs/platformdev_rp2040.md @@ -38,8 +38,8 @@ QMK RP2040 support builds upon ChibiOS and thus follows their convention for act | RP2040 Peripheral | `mcuconf.h` values | `I2C_DRIVER` | | ----------------- | ------------------ | ------------ | -| `I2C0` | `RP_I2C_USE_I2C0` | `I2CD1` | -| `I2C1` | `RP_I2C_USE_I2C1` | `I2CD2` | +| `I2C0` | `RP_I2C_USE_I2C0` | `I2CD0` | +| `I2C1` | `RP_I2C_USE_I2C1` | `I2CD1` | To configure the I2C driver please read the [ChibiOS/ARM](i2c_driver.md#arm-configuration) section. @@ -74,7 +74,7 @@ This is the default board that is chosen, unless any other RP2040 board is selec | Driver configuration define | Value | | -------------------------------------------------------------------------- | ------------------------------------ | | **I2C driver** | | -| `I2C_DRIVER` | `I2CD2` | +| `I2C_DRIVER` | `I2CD1` | | `I2C1_SDA_PIN` | `GP2` | | `I2C1_SCL_PIN` | `GP3` | | **SPI driver** | | diff --git a/docs/quantum_painter_lvgl.md b/docs/quantum_painter_lvgl.md new file mode 100644 index 0000000000..3edb37fbce --- /dev/null +++ b/docs/quantum_painter_lvgl.md @@ -0,0 +1,55 @@ +# Quantum Painter LVGL Integration :id=lvgl + +LVGL (Light and Versatile Graphics Library) is an open-source graphics library providing everything you need to create an embedded GUI for your board with easy-to-use graphical elements. + +LVGL integrates with [Quantum Painter's](quantum_painter.md) API and drivers to render to the display, the hardware supported by Quantum Painter is also supported by LVGL. + +?> Keep in mind that enabling the LVGL integration has a big impact in firmware size, it is recommeded to use a supported MCU with >256 kB of flash space. + +To learn more about LVGL and how to use it please take a look at their [official documentation](https://docs.lvgl.io/8.2/intro/) + +## Enabling LVGL :id=lvgl-enabling +To enable LVGL to be built into your firmware, add the following to `rules.mk`: + +```make +QUANTUM_PAINTER_ENABLE = yes +QUANTUM_PAINTER_DRIVERS = ...... +QUANTUM_PAINTER_LVGL_INTEGRATION = yes +``` +To configure the Quantum Painter Display Drivers please read the [Quantum Painter Display Drivers](quantum_painter.md#quantum-painter-drivers) section. + +## Quantum Painter LVGL API :id=lvgl-api + +### Quantum Painter LVGL Attach :id=lvgl-api-init + +```c +bool qp_lvgl_attach(painter_device_t device); +``` + +The `qp_lvgl_attach` function is used to set up LVGL with the supplied display, and requires an already configured display. + +```c +static painter_device_t display; +void keyboard_post_init_kb(void) { + display = qp_make_.......; // Create the display + qp_init(display, QP_ROTATION_0); // Initialise the display + + if (qp_lvgl_attach(display)) { // Attach LVGL to the display + ...Your code to draw // Run LVGL specific code to draw + } +} +``` +To init. the display please read the [Display Initialisation](quantum_painter.md#quantum-painter-api-init) section. + +!> Attaching LVGL to a display means LVGL subsequently "owns" the display. Using standard Quantum Painter drawing operations with the display after LVGL attachment will likely result in display artifacts. +### Quantum Painter LVGL Detach :id=lvgl-api-init + +```c +void qp_lvgl_detach() +``` + +The `qp_lvgl_detach` function stops the internal LVGL ticks and releases resources related to it. + +## Enabling/Disabling LVGL features :id=lvgl-configuring + +You can overwrite LVGL specific features in your `lv_conf.h` file. diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md index d5469c835a..354863f507 100644 --- a/docs/reference_info_json.md +++ b/docs/reference_info_json.md @@ -113,6 +113,20 @@ Example: } ``` +### Additional Options + +* `input_pressed_state` + * This configures state of the GPIO pins when the key is pressed - `1` for high, `0` for low + * Default: `0` + +Example: + +```json + "matrix_pins": { + "input_pressed_state": 1, +}, +``` + ## Non-RGB LED Lighting This section controls basic 2-pin LEDs, which typically pass through keyswitches and are soldered into the PCB, or are placed in PCB sockets. @@ -333,3 +347,24 @@ Example: } } ``` + +## Bootmagic + +This section configures [Bootmagic Lite](feature_bootmagic.md) support. + +The following options can be configured: + +|Key |Description | +|---------|-----------------------------------------------------------------------------| +|`matrix` | A two item list describing the row and column location for the trigger key. | + +Example: + +```json +{ + "bootmagic": { + "enabled": true, + "matrix": [0, 0] + }, +} +``` diff --git a/docs/tap_hold.md b/docs/tap_hold.md index 8914b730b3..348e2655eb 100644 --- a/docs/tap_hold.md +++ b/docs/tap_hold.md @@ -118,7 +118,7 @@ The reason is that `TAPPING_TERM` is a macro that expands to a constant integer 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: -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. +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. In other words, this mode ignores interrupts. 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. @@ -126,6 +126,73 @@ The code which decides between the tap and hold actions of dual-role keys suppor 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. +### Comparison :id=comparison + +To better illustrate the tap-or-hold decision modes, let us compare the expected output of each decision mode in a handful of tapping scenarios involving a mod-tap key (`LSFT_T(KC_A)`) and a regular key (`KC_B`) with the `TAPPING_TERM` set to 200ms. + +By default, mod-taps behave like `HOLD_ON_OTHER_KEY_PRESS`, while layer-taps behave like "Ignore Interrupt" out of the box. If you want "Ignore Interrupt"-like behaviour for mod-taps, you must enable `IGNORE_MOD_TAP_INTERRUPT`, or return `false` in the `get_hold_on_other_key_press` function for all mod-taps. + +Note: "`kc` held" in the "Physical key event" column means that the key wasn't physically released yet at this point in time. + +#### Distinct taps (AABB) :id=distinct-taps + +| Time | Physical key event |Ignore Interrupt| `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | +|------|--------------------|----------------|-------------------|----------------------------| +| 0 | `LSFT_T(KC_A)` down| | | | +| 199 | `LSFT_T(KC_A)` up | a | a | a | +| 210 | `KC_B` down | ab | ab | ab | +| 220 | `KC_B` up | ab | ab | ab | + +| Time | Physical key event |Ignore Interrupt| `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | +|------|--------------------|----------------|-------------------|----------------------------| +| 0 | `LSFT_T(KC_A)` down| | | | +| 200 | `LSFT_T(KC_A)` held|<kbd>Shift</kbd>| <kbd>Shift</kbd> | <kbd>Shift</kbd> | +| 201 | `LSFT_T(KC_A)` up |<kbd>Shift</kbd>| <kbd>Shift</kbd> | <kbd>Shift</kbd> | +| 205 | `KC_B` down | b | b | b | +| 210 | `KC_B` up | b | b | b | + +#### Nested tap (ABBA) :id=nested-tap + +| Time | Physical key event |Ignore Interrupt| `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | +|------|--------------------|----------------|-------------------|----------------------------| +| 0 | `LSFT_T(KC_A)` down| | | | +| 110 | `KC_B` down | | | B | +| 120 | `KC_B` up | | B | B | +| 199 | `LSFT_T(KC_A)` up | ab | B | B | + +| Time | Physical key event |Ignore Interrupt| `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | +|------|--------------------|----------------|-------------------|----------------------------| +| 0 | `LSFT_T(KC_A)` down| | | | +| 110 | `KC_B` down | | | B | +| 120 | `KC_B` up | | B | B | +| 200 | `LSFT_T(KC_A)` held| B | B | B | +| 210 | `LSFT_T(KC_A)` up | B | B | B | + +| Time | Physical key event |Ignore Interrupt| `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | +|------|--------------------|----------------|-------------------|----------------------------| +| 0 | `LSFT_T(KC_A)` down| | | | +| 200 | `LSFT_T(KC_A)` held|<kbd>Shift</kbd>| <kbd>Shift</kbd> | <kbd>Shift</kbd> | +| 205 | `KC_B` down | B | B | B | +| 210 | `KC_B` up | B | B | B | +| 220 | `LSFT_T(KC_A)` up | B | B | B | + +#### Rolling keys (ABAB) :id=rolling-keys + +| Time | Physical key event |Ignore Interrupt| `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | +|------|--------------------|----------------|-------------------|----------------------------| +| 0 | `LSFT_T(KC_A)` down| | | | +| 110 | `KC_B` down | | | B | +| 130 | `LSFT_T(KC_A)` up | ab | ab | B | +| 140 | `KC_B` up | ab | ab | B | + +| Time | Physical key event |Ignore Interrupt| `PERMISSIVE_HOLD` | `HOLD_ON_OTHER_KEY_PRESS` | +|------|--------------------|----------------|-------------------|----------------------------| +| 0 | `LSFT_T(KC_A)` down| | | | +| 110 | `KC_B` down | | | B | +| 200 | `LSFT_T(KC_A)` held| B | B | B | +| 205 | `LSFT_T(KC_A)` up | B | B | B | +| 210 | `KC_B` up | B | B | B | + ### Default Mode Example sequence 1 (the `L` key is also mapped to `KC_RGHT` on layer 2): @@ -179,8 +246,6 @@ since `SFT_T(KC_A)` is NOT held longer than the `TAPPING_TERM`. However, the actual output would be capital `X` (`SHIFT` + `x`) due to reasons explained under [Ignore Mod Tap Interrupt](#ignore-mod-tap-interrupt). - - ### Permissive Hold The “permissive hold†mode can be enabled for all dual-role keys by adding the corresponding option to `config.h`: @@ -212,7 +277,7 @@ An example of a sequence that is affected by the “permissive hold†mode: +---------------------------|--------+ ``` -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). We could describe this sequence as a “nested press†(the modified key's key down and key up events are “nested†between the dual-role key's key down and key up events). +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). We could describe this sequence as a “nested tap†(the modified key's key down and key up events are “nested†between the dual-role key's key down and key up events). However, this slightly different sequence will not be affected by the “permissive hold†mode: @@ -235,7 +300,7 @@ However, this slightly different sequence will not be affected by the “permiss 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. We could describe this as a “rolling press†(the two keys' key down and key up events behave as if you were rolling a ball across the two keys, first pressing each key down in sequence and then releasing them in the same order). -?> 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. +?> The `PERMISSIVE_HOLD` option is not noticeable if you also enable `HOLD_ON_OTHER_KEY_PRESS` because the latter option considers both the “nested tap†and “rolling press†sequences like shown above as a hold action, not the tap action. `HOLD_ON_OTHER_KEY_PRESS` makes the Tap-Or-Hold decision earlier in the chain of key events, thus taking a precedence over `PERMISSIVE_HOLD`. This remark also applies to default mod-taps. For more granular control of this feature, you can add the following to your `config.h`: @@ -291,7 +356,7 @@ An example of a sequence that is affected by the “hold on other key press†m 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. +?> The `HOLD_ON_OTHER_KEY_PRESS` option is essentially redundant with the default mod-tap behaviour. The only notable difference is that `HOLD_ON_OTHER_KEY_PRESS` reduces 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`: @@ -355,69 +420,76 @@ However, if the `HOLD_ON_OTHER_KEY_PRESS` option is enabled in addition to `IGNO For more granular control of this feature, you can add the following to your `config.h`: ```c -#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY +#define HOLD_ON_OTHER_KEY_PRESS_PER_KEY ``` +?> This option affects *all* dual-role keys. + You can then add the following function to your keymap: ```c -bool get_ignore_mod_tap_interrupt(uint16_t keycode, keyrecord_t *record) { +bool get_hold_on_other_key_press(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; + return false; default: - // Force the mod-tap key press to be handled as a modifier if any + // Force the dual-role key press to be handled as a modifier if any // other key was pressed while the mod-tap key is held down. - return false; + return true; } } ``` -## Tapping Force Hold +Note that you must return `false` in `get_hold_on_other_key_press` in order to apply `IGNORE_MOD_TAP_INTERRUPT` for a certain mod-tap key. -To enable `tapping force hold`, add the following to your `config.h`: +?> `IGNORE_MOD_TAP_INTERRUPT[_PER_KEY]` is being progressively phased out to align the (default) behavior and configuration of mod-taps with the rest of dual-role keys. + +## Quick Tap Term + +When the user holds a key after tapping it, the tapping function is repeated by default, rather than activating the hold function. This allows keeping the ability to auto-repeat the tapping function of a dual-role key. `QUICK_TAP_TERM` enables fine tuning of that ability. If set to `0`, it will remove the auto-repeat ability and activate the hold function instead. + +`QUICK_TAP_TERM` is set to `TAPPING_TERM` by default, which is the maximum allowed value for `QUICK_TAP_TERM`. To override its value (in milliseconds) add the following to your `config.h`: ```c -#define TAPPING_FORCE_HOLD +#define QUICK_TAP_TERM 120 ``` -When the user holds a key after tapping it, the tapping function is repeated by default, rather than activating the hold function. This allows keeping the ability to auto-repeat the tapping function of a dual-role key. `TAPPING_FORCE_HOLD` removes that ability to let the user activate the hold function instead, in the case of holding the dual-role key after having tapped it. - Example: - `SFT_T(KC_A)` Down - `SFT_T(KC_A)` Up - `SFT_T(KC_A)` Down -- wait until the tapping term expires... -- `SFT_T(KC_A)` Up +- (wait until tapping term expires...) -With default settings, `a` will be sent on the first release, then `a` will be sent on the second press allowing the computer to trigger its auto-repeat function. +With default settings, `a` will be sent on the first release, then `a` will be sent on the second press allowing the computer to trigger its auto repeat function until the key is released. -With `TAPPING_FORCE_HOLD`, the second press will be interpreted as a Shift, allowing to use it as a modifier shortly after having used it as a tap. +With `QUICK_TAP_TERM` configured, the timing between `SFT_T(KC_A)` up and `SFT_T(KC_A)` down must be within `QUICK_TAP_TERM` to trigger auto repeat. Otherwise the second press will be sent as a Shift. If `QUICK_TAP_TERM` is set to `0`, the second press will always be sent as a Shift, effectively disabling auto-repeat. -!> `TAPPING_FORCE_HOLD` will break anything that uses tapping toggles (Such as the `TT` layer keycode, and the One Shot Tap Toggle). +!> `QUICK_TAP_TERM` timing will also impact anything that uses tapping toggles (Such as the `TT` layer keycode, and the One Shot Tap Toggle). For more granular control of this feature, you can add the following to your `config.h`: ```c -#define TAPPING_FORCE_HOLD_PER_KEY +#define QUICK_TAP_TERM_PER_KEY ``` You can then add the following function to your keymap: ```c -bool get_tapping_force_hold(uint16_t keycode, keyrecord_t *record) { +uint16_t get_quick_tap_term(uint16_t keycode, keyrecord_t *record) { switch (keycode) { - case LT(1, KC_BSPC): - return true; + case SFT_T(KC_SPC): + return QUICK_TAP_TERM - 20; default: - return false; + return QUICK_TAP_TERM; } } ``` +?> If `QUICK_TAP_TERM` is set higher than `TAPPING_TERM`, it will default to `TAPPING_TERM`. + ## Retro Tapping To enable `retro tapping`, add the following to your `config.h`: diff --git a/docs/zh-cn/feature_grave_esc.md b/docs/zh-cn/feature_grave_esc.md index f57dabeaff..1795a508ef 100644 --- a/docs/zh-cn/feature_grave_esc.md +++ b/docs/zh-cn/feature_grave_esc.md @@ -11,7 +11,7 @@ ## 使用方法 -在é…列ä¸ä½¿ç”¨ `KC_GESC` æ›¿æ¢ `KC_GRAVE` （一般都在`1`键左边）。默认点击会输出 `KC_ESC`，按下Shift或GUI键时，点击会输出 `KC_GRV` +在é…列ä¸ä½¿ç”¨ `QK_GESC` æ›¿æ¢ `KC_GRAVE` （一般都在`1`键左边）。默认点击会输出 `KC_ESC`，按下Shift或GUI键时，点击会输出 `KC_GRV` ## æ“作系统视角 @@ -21,7 +21,7 @@ |é”® |别å |æè¿° | |---------|-----------|------------------------------------------------------------------| -|`KC_GESC`|`GRAVE_ESC`|å•å‡»è¾“出Escape, 按ä½Shift或GUI时输出<code>`</code> | +|`QK_GESC`|`GRAVE_ESC`|å•å‡»è¾“出Escape, 按ä½Shift或GUI时输出<code>`</code> | ### é¡»ç•™æ„ |