diff options
Diffstat (limited to 'docs/features')
-rw-r--r-- | docs/features/community_modules.md | 48 | ||||
-rw-r--r-- | docs/features/key_overrides.md | 6 | ||||
-rw-r--r-- | docs/features/led_matrix.md | 2 | ||||
-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 | 6 | ||||
-rw-r--r-- | docs/features/rgblight.md | 6 | ||||
-rw-r--r-- | docs/features/split_keyboard.md | 2 | ||||
-rw-r--r-- | docs/features/stenography.md | 2 |
9 files changed, 85 insertions, 26 deletions
diff --git a/docs/features/community_modules.md b/docs/features/community_modules.md index 3a1a82e7bc..eff07c939a 100644 --- a/docs/features/community_modules.md +++ b/docs/features/community_modules.md @@ -40,7 +40,7 @@ cd /path/to/your/external/userspace mkdir -p modules # Replace the following {user} and {repo} with the author's community module repository git submodule add https://github.com/{user}/{repo}.git modules/{user} -git submdule update --init --recursive +git submodule update --init --recursive ``` This will ensure the copy of the module is made in your userspace. @@ -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/led_matrix.md b/docs/features/led_matrix.md index 756cc11e2b..113b13f03b 100644 --- a/docs/features/led_matrix.md +++ b/docs/features/led_matrix.md @@ -227,6 +227,8 @@ For inspiration and examples, check out the built-in effects under `quantum/led_ #define LED_MATRIX_DEFAULT_MODE LED_MATRIX_SOLID // Sets the default mode, if none has been set #define LED_MATRIX_DEFAULT_VAL LED_MATRIX_MAXIMUM_BRIGHTNESS // Sets the default brightness value, if none has been set #define LED_MATRIX_DEFAULT_SPD 127 // Sets the default animation speed, if none has been set +#define LED_MATRIX_VAL_STEP 8 // The value by which to increment the brightness per adjustment action +#define LED_MATRIX_SPD_STEP 16 // The value by which to increment the animation speed per adjustment action #define LED_MATRIX_DEFAULT_FLAGS LED_FLAG_ALL // Sets the default LED flags, 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 reactive effects are enabled, you also will want to enable SPLIT_TRANSPORT_MIRROR 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 0e53ce9c35..ca50fc5257 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` | @@ -378,6 +380,10 @@ These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master #define RGB_MATRIX_DEFAULT_SAT 255 // Sets the default saturation value, if none has been set #define RGB_MATRIX_DEFAULT_VAL RGB_MATRIX_MAXIMUM_BRIGHTNESS // Sets the default brightness value, if none has been set #define RGB_MATRIX_DEFAULT_SPD 127 // Sets the default animation speed, if none has been set +#define RGB_MATRIX_HUE_STEP 8 // The value by which to increment the hue per adjustment action +#define RGB_MATRIX_SAT_STEP 16 // The value by which to increment the saturation per adjustment action +#define RGB_MATRIX_VAL_STEP 16 // The value by which to increment the brightness per adjustment action +#define RGB_MATRIX_SPD_STEP 16 // The value by which to increment the animation speed per adjustment action #define RGB_MATRIX_DEFAULT_FLAGS LED_FLAG_ALL // Sets the default LED flags, if none has been set #define RGB_MATRIX_SPLIT { X, Y } // (Optional) For split keyboards, the number of LEDs connected on each half. X = left, Y = Right. // If reactive effects are enabled, you also will want to enable SPLIT_TRANSPORT_MIRROR diff --git a/docs/features/rgblight.md b/docs/features/rgblight.md index 4322fe796e..43e3781f8d 100644 --- a/docs/features/rgblight.md +++ b/docs/features/rgblight.md @@ -97,9 +97,9 @@ Your RGB lighting can be configured by placing these `#define`s in your `config. |Define |Default |Description | |---------------------------|----------------------------|---------------------------------------------------------------------------------------------------------------------------| -|`RGBLIGHT_HUE_STEP` |`8` |The number of steps to cycle through the hue by | -|`RGBLIGHT_SAT_STEP` |`17` |The number of steps to increment the saturation by | -|`RGBLIGHT_VAL_STEP` |`17` |The number of steps to increment the brightness by | +|`RGBLIGHT_HUE_STEP` |`8` |The value by which to increment the hue per adjustment action | +|`RGBLIGHT_SAT_STEP` |`17` |The value by which to increment the saturation per adjustment action | +|`RGBLIGHT_VAL_STEP` |`17` |The value by which to increment the brightness per adjustment action | |`RGBLIGHT_LIMIT_VAL` |`255` |The maximum brightness level | |`RGBLIGHT_SLEEP` |*Not defined* |If defined, the RGB lighting will be switched off when the host goes to sleep | |`RGBLIGHT_SPLIT` |*Not defined* |If defined, synchronization functionality for split keyboards is added | diff --git a/docs/features/split_keyboard.md b/docs/features/split_keyboard.md index 49582c3946..fbf5d3d3e2 100644 --- a/docs/features/split_keyboard.md +++ b/docs/features/split_keyboard.md @@ -444,7 +444,7 @@ This setting implies that `RGBLIGHT_SPLIT` is enabled, and will forcibly enable #define SPLIT_USB_DETECT ``` -Enabling this option changes the startup behavior to listen for an active USB communication to delegate which part is master and which is slave. With this option enabled and theres's USB communication, then that half assumes it is the master, otherwise it assumes it is the slave. +Enabling this option changes the startup behavior to listen for an active USB communication to delegate which part is master and which is slave. With this option enabled and active USB communication, then that half assumes it is the master, otherwise it assumes it is the slave. Without this option, the master is the half that can detect voltage on the physical USB connection (VBUS detection). diff --git a/docs/features/stenography.md b/docs/features/stenography.md index c6c2155a9a..7fd245d59a 100644 --- a/docs/features/stenography.md +++ b/docs/features/stenography.md @@ -8,7 +8,7 @@ The [Open Steno Project](https://www.openstenoproject.org/) has built an open-so 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. |