diff options
Diffstat (limited to 'docs/features')
-rw-r--r-- | docs/features/community_modules.md | 46 | ||||
-rw-r--r-- | docs/features/key_overrides.md | 6 | ||||
-rw-r--r-- | docs/features/pointing_device.md | 26 | ||||
-rw-r--r-- | docs/features/ps2_mouse.md | 13 | ||||
-rw-r--r-- | docs/features/rgb_matrix.md | 4 | ||||
-rw-r--r-- | docs/features/stenography.md | 16 | ||||
-rw-r--r-- | docs/features/tap_dance.md | 35 |
7 files changed, 105 insertions, 41 deletions
diff --git a/docs/features/community_modules.md b/docs/features/community_modules.md index a28c5afaeb..eff07c939a 100644 --- a/docs/features/community_modules.md +++ b/docs/features/community_modules.md @@ -72,6 +72,7 @@ A Community Module is denoted by a `qmk_module.json` file such as the following: { "module_name": "Hello World", "maintainer": "QMK Maintainers", + "license": "GPL-2.0-or-later", "features": { "deferred_exec": true }, @@ -86,6 +87,10 @@ A Community Module is denoted by a `qmk_module.json` file such as the following: At minimum, the module must provide the `module_name` and `maintainer` fields. +The `license` field is encouraged to indicate the terms for using and sharing the module. It is recommended to use a [SPDX license identifier](https://spdx.org/licenses/) like "`Apache-2.0`" or "`GPL-2.0-or-later`" if possible. + +The `url` field may specify a URL to more information about the module. + The use of `features` matches the definition normally provided within `keyboard.json` and `info.json`, allowing a module to signal to the build system that it has its own dependencies. In the example above, it enables the _deferred executor_ feature whenever the above module is used in a build. The `keycodes` array allows a module to provide new keycodes (as well as corresponding aliases) to a keymap. @@ -118,22 +123,39 @@ The source file may provide functions which allow access to information specifie Introspection is a relatively advanced topic within QMK, and existing patterns should be followed. If you need help please [open an issue](https://github.com/qmk/qmk_firmware/issues/new) or [chat with us on Discord](https://discord.gg/qmk). ::: +### `led_matrix_module.inc` + +This file defines LED matrix effects in the same form as used with `led_matrix_kb.inc` and `led_matrix_user.inc` (see [Custom LED Matrix Effects](led_matrix#custom-led-matrix-effects)). Effect mode names are prepended with `LED_MATRIX_COMMUNITY_MODULE_`. + +### `rgb_matrix_module.inc` + +This file defines RGB matrix effects in the same form as used with `rgb_matrix_kb.inc` and `rgb_matrix_user.inc` (see [Custom RGB Matrix Effects](rgb_matrix#custom-rgb-matrix-effects)). Effect mode names are prepended with `RGB_MATRIX_COMMUNITY_MODULE_`. + ### Compatible APIs Community Modules may provide specializations for the following APIs: -| Base API | API Format | Example (`hello_world` module) | API Version | -|----------------------------|-------------------------------------|----------------------------------------|-------------| -| `keyboard_pre_init` | `keyboard_pre_init_<module>` | `keyboard_pre_init_hello_world` | `0.1.0` | -| `keyboard_post_init` | `keyboard_post_init_<module>` | `keyboard_post_init_hello_world` | `0.1.0` | -| `pre_process_record` | `pre_process_record_<module>` | `pre_process_record_hello_world` | `0.1.0` | -| `process_record` | `process_record_<module>` | `process_record_hello_world` | `0.1.0` | -| `post_process_record` | `post_process_record_<module>` | `post_process_record_hello_world` | `0.1.0` | -| `housekeeping_task` | `housekeeping_task_<module>` | `housekeeping_task_hello_world` | `1.0.0` | -| `suspend_power_down` | `suspend_power_down_<module>` | `suspend_power_down_hello_world` | `1.0.0` | -| `suspend_wakeup_init` | `suspend_wakeup_init_<module>` | `suspend_wakeup_init_hello_world` | `1.0.0` | -| `shutdown` | `shutdown_<module>` | `shutdown_hello_world` | `1.0.0` | -| `process_detected_host_os` | `process_detected_host_os_<module>` | `process_detected_host_os_hello_world` | `1.0.0` | +| Base API | API Format | Example (`hello_world` module) | API Version | +|----------------------------------|-------------------------------------------|---------------------------------------------|-------------| +| `keyboard_pre_init` | `keyboard_pre_init_<module>` | `keyboard_pre_init_hello_world` | `0.1.0` | +| `keyboard_post_init` | `keyboard_post_init_<module>` | `keyboard_post_init_hello_world` | `0.1.0` | +| `pre_process_record` | `pre_process_record_<module>` | `pre_process_record_hello_world` | `0.1.0` | +| `process_record` | `process_record_<module>` | `process_record_hello_world` | `0.1.0` | +| `post_process_record` | `post_process_record_<module>` | `post_process_record_hello_world` | `0.1.0` | +| `housekeeping_task` | `housekeeping_task_<module>` | `housekeeping_task_hello_world` | `1.0.0` | +| `suspend_power_down` | `suspend_power_down_<module>` | `suspend_power_down_hello_world` | `1.0.0` | +| `suspend_wakeup_init` | `suspend_wakeup_init_<module>` | `suspend_wakeup_init_hello_world` | `1.0.0` | +| `shutdown` | `shutdown_<module>` | `shutdown_hello_world` | `1.0.0` | +| `process_detected_host_os` | `process_detected_host_os_<module>` | `process_detected_host_os_hello_world` | `1.0.0` | +| `default_layer_state_set` | `default_layer_state_set_<module>` | `default_layer_state_set_hello_world` | `1.1.0` | +| `layer_state_set` | `layer_state_set_<module>` | `layer_state_set_hello_world` | `1.1.0` | +| `led_matrix_indicators` | `led_matrix_indicators_<module>` | `led_matrix_indicators_hello_world` | `1.1.0` | +| `led_matrix_indicators_advanced` | `led_matrix_indicators_advanced_<module>` | `led_matrix_indicators_advanced_hello_world` | `1.1.0` | +| `rgb_matrix_indicators` | `rgb_matrix_indicators_<module>` | `rgb_matrix_indicators_hello_world` | `1.1.0` | +| `rgb_matrix_indicators_advanced` | `rgb_matrix_indicators_advanced_<module>` | `rgb_matrix_indicators_advanced_hello_world` | `1.1.0` | +| `pointing_device_init` | `pointing_device_init_<module>` | `pointing_device_init_hello_world` | `1.1.0` | +| `pointing_device_task` | `pointing_device_task_<module>` | `pointing_device_task_hello_world` | `1.1.0` | + ::: info An unspecified API is disregarded if a Community Module does not provide a specialization for it. diff --git a/docs/features/key_overrides.md b/docs/features/key_overrides.md index 9b6015175c..e83f0295ab 100644 --- a/docs/features/key_overrides.md +++ b/docs/features/key_overrides.md @@ -135,11 +135,11 @@ bool momentary_layer(bool key_down, void *layer) { return false; } -const key_override_t fn_override = {.trigger_mods = MOD_BIT(KC_RGUI) | MOD_BIT(KC_RCTL), // +const key_override_t fn_override = {.trigger_mods = MOD_BIT(KC_RGUI) | MOD_BIT(KC_RALT), // .layers = ~(1 << LAYER_FN), // - .suppressed_mods = MOD_BIT(KC_RGUI) | MOD_BIT(KC_RCTL), // + .suppressed_mods = MOD_BIT(KC_RGUI) | MOD_BIT(KC_RALT), // .options = ko_option_no_unregister_on_other_key_down, // - .negative_mod_mask = (uint8_t) ~(MOD_BIT(KC_RGUI) | MOD_BIT(KC_RCTL)), // + .negative_mod_mask = (uint8_t) ~(MOD_BIT(KC_RGUI) | MOD_BIT(KC_RALT)), // .custom_action = momentary_layer, // .context = (void *)LAYER_FN, // .trigger = KC_NO, // diff --git a/docs/features/pointing_device.md b/docs/features/pointing_device.md index 0ecf82c8df..a139df9dc4 100644 --- a/docs/features/pointing_device.md +++ b/docs/features/pointing_device.md @@ -419,6 +419,32 @@ The `POINTING_DEVICE_CS_PIN`, `POINTING_DEVICE_SDIO_PIN`, and `POINTING_DEVICE_S Any pointing device with a lift/contact status can integrate inertial cursor feature into its driver, controlled by `POINTING_DEVICE_GESTURES_CURSOR_GLIDE_ENABLE`. e.g. PMW3360 can use Lift_Stat from Motion register. Note that `POINTING_DEVICE_MOTION_PIN` cannot be used with this feature; continuous polling of `get_report()` is needed to generate glide reports. ::: +## High Resolution Scrolling + +| Setting | Description | Default | +| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------- | +| `POINTING_DEVICE_HIRES_SCROLL_ENABLE` | (Optional) Enables high resolution scrolling. | _not defined_ | +| `POINTING_DEVICE_HIRES_SCROLL_MULTIPLIER`| (Optional) Resolution mutiplier value used by high resolution scrolling. Must be between 1 and 127, inclusive. | `120` | +| `POINTING_DEVICE_HIRES_SCROLL_EXPONENT` | (Optional) Resolution exponent value used by high resolution scrolling. Must be between 0 and 127, inclusive. | `0` | + +The `POINTING_DEVICE_HIRES_SCROLL_ENABLE` setting enables smooth and continuous scrolling when using trackballs or high-end encoders as mouse wheels (as opposed to the typical stepped behavior of most mouse wheels). +This works by adding a resolution multiplier to the HID descriptor for mouse wheel reports, causing the host computer to interpret each wheel tick sent by the keyboard as a fraction of a normal wheel tick. +The resolution multiplier is set to `1 / (POINTING_DEVICE_HIRES_SCROLL_MULTIPLIER * (10 ^ POINTING_DEVICE_HIRES_SCROLL_EXPONENT))`, which is `1 / 120` by default. +If even smoother scrolling than provided by this default value is desired, first try using `#define POINTING_DEVICE_HIRES_SCROLL_EXPONENT 1` which will result in a multiplier of `1 / 1200`. + +The function `pointing_device_get_hires_scroll_resolution()` can be called to get the pre-computed resolution multiplier value as a `uint16_t`. + +::: warning +High resolution scrolling usually results in larger and/or more frequent mouse reports. This can result in overflow errors and overloading of the host computer's input buffer. +To deal with these issues, define `WHEEL_EXTENDED_REPORT` and throttle the rate at which mouse reports are sent. +::: + +::: warning +Many programs, especially those that implement their own smoothing for scrolling, don't work well when they receive simultaneous vertical and horizontal wheel inputs (e.g. from high resolution drag-scroll using a trackball). +These programs typically implement their smoothing in a way that assumes the user will only scroll in one axis at a time, resulting in slow or jittery motion when trying to scroll at an angle. +This can be addressed by snapping scrolling to one axis at a time. +::: + ## Split Keyboard Configuration The following configuration options are only available when using `SPLIT_POINTING_ENABLE` see [data sync options](split_keyboard#data-sync-options). The rotation and invert `*_RIGHT` options are only used with `POINTING_DEVICE_COMBINED`. If using `POINTING_DEVICE_LEFT` or `POINTING_DEVICE_RIGHT` use the common configuration above to configure your pointing device. diff --git a/docs/features/ps2_mouse.md b/docs/features/ps2_mouse.md index 52443c3ce2..6ef7e46768 100644 --- a/docs/features/ps2_mouse.md +++ b/docs/features/ps2_mouse.md @@ -23,8 +23,11 @@ MODULE 5+ --------+--+--------- PWR CONTROLLER CLK ------+------------ PIN ``` +## Driver Configuration {#driver-configuration} -## Busywait Version {#busywait-version} +Driver selection can be configured in `rules.mk` as `PS2_DRIVER`, or in `info.json` as `ps2.driver`. Valid values are `busywait` (default), `interrupt`, `usart`, or `vendor`. See below for information on individual drivers. + +### Busywait Driver {#busywait-driver} Note: This is not recommended, you may encounter jerky movement or unsent inputs. Please use interrupt or USART version if possible. @@ -45,7 +48,7 @@ In your keyboard config.h: #endif ``` -### Interrupt Version (AVR/ATMega32u4) {#interrupt-version-avr} +### Interrupt Driver (AVR/ATMega32u4) {#interrupt-driver-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. @@ -78,7 +81,7 @@ In your keyboard config.h: #endif ``` -### Interrupt Version (ARM chibios) {#interrupt-version-chibios} +### Interrupt Driver (ARM chibios) {#interrupt-driver-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. @@ -107,7 +110,7 @@ And in the ChibiOS specific `halconf.h`: #include_next <halconf.h> ``` -### USART Version {#usart-version} +### USART Driver {#usart-driver} 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. @@ -159,7 +162,7 @@ In your keyboard config.h: #endif ``` -### RP2040 PIO Version {#rp2040-pio-version} +### RP2040 PIO Driver {#rp2040-pio-driver} The `PIO` subsystem is a Raspberry Pi RP2040 specific implementation, using the integrated PIO peripheral and is therefore only available on this MCU. diff --git a/docs/features/rgb_matrix.md b/docs/features/rgb_matrix.md index a22f931f1b..130c1c5a5e 100644 --- a/docs/features/rgb_matrix.md +++ b/docs/features/rgb_matrix.md @@ -150,6 +150,7 @@ enum rgb_matrix_effects { RGB_MATRIX_SOLID_SPLASH, // Hue & value pulse away from a single key hit then fades value out RGB_MATRIX_SOLID_MULTISPLASH, // Hue & value pulse away from multiple key hits then fades value out RGB_MATRIX_STARLIGHT, // LEDs turn on and off at random at varying brightness, maintaining user set color + RGB_MATRIX_STARLIGHT_SMOOTH, // LEDs slowly increase and decrease in brightness randomly RGB_MATRIX_STARLIGHT_DUAL_HUE, // LEDs turn on and off at random at varying brightness, modifies user set hue by +- 30 RGB_MATRIX_STARLIGHT_DUAL_SAT, // LEDs turn on and off at random at varying brightness, modifies user set saturation by +- 30 RGB_MATRIX_RIVERFLOW, // Modification to breathing animation, offset's animation depending on key location to simulate a river flowing @@ -193,6 +194,7 @@ You can enable a single effect by defining `ENABLE_[EFFECT_NAME]` in your `confi |`#define ENABLE_RGB_MATRIX_PIXEL_FLOW` |Enables `RGB_MATRIX_PIXEL_FLOW` | |`#define ENABLE_RGB_MATRIX_PIXEL_RAIN` |Enables `RGB_MATRIX_PIXEL_RAIN` | |`#define ENABLE_RGB_MATRIX_STARLIGHT` |Enables `RGB_MATRIX_STARLIGHT` | +|`#define ENABLE_RGB_MATRIX_STARLIGHT_SMOOTH` |Enables `RGB_MATRIX_STARLIGHT_SMOOTH` | |`#define ENABLE_RGB_MATRIX_STARLIGHT_DUAL_HUE` |Enables `RGB_MATRIX_STARLIGHT_DUAL_HUE` | |`#define ENABLE_RGB_MATRIX_STARLIGHT_DUAL_SAT` |Enables `RGB_MATRIX_STARLIGHT_DUAL_SAT` | |`#define ENABLE_RGB_MATRIX_RIVERFLOW` |Enables `RGB_MATRIX_RIVERFLOW` | @@ -484,7 +486,7 @@ This example sets the modifiers to be a specific color based on the layer state. bool rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) { hsv_t hsv = {0, 255, 255}; - if (layer_state_is(layer_state, 2)) { + if (get_highest_layer(layer_state|default_layer_state) == 2) { hsv = (hsv_t){130, 255, 255}; } else { hsv = (hsv_t){30, 255, 255}; diff --git a/docs/features/stenography.md b/docs/features/stenography.md index c6c2155a9a..4176344b5a 100644 --- a/docs/features/stenography.md +++ b/docs/features/stenography.md @@ -4,24 +4,32 @@ The [Open Steno Project](https://www.openstenoproject.org/) has built an open-source program called Plover that provides real-time translation of steno strokes into words and commands. It has an established dictionary and supports +## Steno Support in QMK + +There are three ways that QMK keyboards can support steno, with varying degrees of configuration required: + +1. Plover with [Arpeggiation](https://plover.wiki/index.php/Glossary#Arpeggiate) requires no changes to any keyboard and is supported by QMK as well as any other QWERTY keyboard. +2. Plover with [NKRO](https://plover.wiki/index.php/Using_a_standard_keyboard_with_Plover#NKRO). If your keyboard supports NKRO in hardware and you have NKRO enabled as a USB endpoint, you can chord with the keyboard. Many devices will arrive stock like this and will require no changes. +3. Steno Machine Protocols. This requires the most configuration, but this has the advantage of allowing you to use your keyboard keys normally (either on another layer or another piece of hardware) without enabling and disabling your steno software. + ## Plover with QWERTY Keyboard {#plover-with-qwerty-keyboard} Plover can work with any standard QWERTY keyboard, although it is more efficient if the keyboard supports NKRO (n-key rollover) to allow Plover to see all the pressed keys at once. An example keymap for Plover can be found in `planck/keymaps/default`. Switching to the `PLOVER` layer adjusts the position of the keyboard to support the number bar. -To enable NKRO, add `NKRO_ENABLE = yes` in your `rules.mk` and make sure to press `NK_ON` to turn it on because `NKRO_ENABLE = yes` merely adds the possibility of switching to NKRO mode but it doesn't automatically switch to it. If you want to automatically switch, add `#define FORCE_NKRO` in your `config.h`. +To enable NKRO, add `NKRO_ENABLE = yes` in your `rules.mk` and make sure to press `NK_ON` to turn it on because `NKRO_ENABLE = yes` merely adds the possibility of switching to NKRO mode but it doesn't automatically switch to it. If you want to automatically switch, add `#define NKRO_DEFAULT_ON true` in your `config.h`. You may also need to adjust your layout, either in QMK or in Plover, if you have anything other than a standard layout. You may also want to purchase some steno-friendly keycaps to make it easier to hit multiple keys. ## Plover with Steno Protocol {#plover-with-steno-protocol} -Plover also understands the language of several steno machines. QMK can speak a couple of these languages: TX Bolt and GeminiPR. An example layout can be found in `planck/keymaps/steno`. +Plover also understands the language of several steno machines. QMK can speak a couple of these languages: TX Bolt and GeminiPR. An example layout can be found in `splitography/keymaps/default`. When QMK speaks to Plover over a steno protocol, Plover will not use the keyboard as input. This means that you can switch back and forth between a standard keyboard and your steno keyboard, or even switch layers from Plover to standard and back without needing to activate/deactivate Plover. In this mode, Plover expects to speak with a steno machine over a serial port so QMK will present itself to the operating system as a virtual serial port in addition to a keyboard. ::: info -Note: Due to hardware limitations, you might not be able to run both a virtual serial port and mouse emulation at the same time. +Due to hardware limitations, you might not be able to run both a virtual serial port and other features (mouse keys, NKRO, or MIDI support) at the same time. You will likely encounter a compile time error if this is the case. Disable those other features as necessary. ::: ::: warning @@ -156,7 +164,7 @@ At the end of this scenario given as an example, `chord` would have five bits se ## Keycode Reference {#keycode-reference} ::: info -Note: TX Bolt does not support the full set of keys. The TX Bolt implementation in QMK will map the GeminiPR keys to the nearest TX Bolt key so that one key map will work for both. +TX Bolt does not support the full set of keys. The TX Bolt implementation in QMK will map the GeminiPR keys to the nearest TX Bolt key so that one key map will work for both. ::: |GeminiPR|TX Bolt|Steno Key| diff --git a/docs/features/tap_dance.md b/docs/features/tap_dance.md index 8fdd83c18d..d533e41aaa 100644 --- a/docs/features/tap_dance.md +++ b/docs/features/tap_dance.md @@ -170,20 +170,6 @@ typedef struct { uint16_t held; } tap_dance_tap_hold_t; -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - tap_dance_action_t *action; - - switch (keycode) { - case TD(CT_CLN): // list all tap dance keycodes with tap-hold configurations - action = &tap_dance_actions[QK_TAP_DANCE_GET_INDEX(keycode)]; - if (!record->event.pressed && action->state.count && !action->state.finished) { - tap_dance_tap_hold_t *tap_hold = (tap_dance_tap_hold_t *)action->user_data; - tap_code16(tap_hold->tap); - } - } - return true; -} - void tap_dance_tap_hold_finished(tap_dance_state_t *state, void *user_data) { tap_dance_tap_hold_t *tap_hold = (tap_dance_tap_hold_t *)user_data; @@ -211,12 +197,29 @@ void tap_dance_tap_hold_reset(tap_dance_state_t *state, void *user_data) { } } -#define ACTION_TAP_DANCE_TAP_HOLD(tap, hold) \ - { .fn = {NULL, tap_dance_tap_hold_finished, tap_dance_tap_hold_reset}, .user_data = (void *)&((tap_dance_tap_hold_t){tap, hold, 0}), } +#define ACTION_TAP_DANCE_TAP_HOLD(tap, hold) \ + { \ + .fn = {NULL, tap_dance_tap_hold_finished, tap_dance_tap_hold_reset}, \ + .user_data = (void *)&((tap_dance_tap_hold_t){tap, hold, 0}), \ + } tap_dance_action_t tap_dance_actions[] = { [CT_CLN] = ACTION_TAP_DANCE_TAP_HOLD(KC_COLN, KC_SCLN), }; + +bool process_record_user(uint16_t keycode, keyrecord_t *record) { + tap_dance_action_t *action; + + switch (keycode) { + case TD(CT_CLN): // list all tap dance keycodes with tap-hold configurations + action = &tap_dance_actions[QK_TAP_DANCE_GET_INDEX(keycode)]; + if (!record->event.pressed && action->state.count && !action->state.finished) { + tap_dance_tap_hold_t *tap_hold = (tap_dance_tap_hold_t *)action->user_data; + tap_code16(tap_hold->tap); + } + } + return true; +} ``` #### Example 4: 'Quad Function Tap-Dance' {#example-4} |