aboutsummaryrefslogtreecommitdiff
path: root/docs/features
diff options
context:
space:
mode:
Diffstat (limited to 'docs/features')
-rw-r--r--docs/features/community_modules.md20
-rw-r--r--docs/features/key_overrides.md6
-rw-r--r--docs/features/led_matrix.md21
-rw-r--r--docs/features/pointing_device.md32
-rw-r--r--docs/features/ps2_mouse.md13
-rw-r--r--docs/features/rgb_matrix.md25
-rw-r--r--docs/features/stenography.md16
-rw-r--r--docs/features/tap_dance.md35
8 files changed, 118 insertions, 50 deletions
diff --git a/docs/features/community_modules.md b/docs/features/community_modules.md
index 69fc47f617..eff07c939a 100644
--- a/docs/features/community_modules.md
+++ b/docs/features/community_modules.md
@@ -123,6 +123,14 @@ 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:
@@ -141,12 +149,12 @@ Community Modules may provide specializations for the following APIs:
| `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_word` | `1.1.0` |
-| `led_matrix_indicators_advanced` | `led_matrix_indicators_advanced_<module>` | `led_matrix_indicators_advanced_hello_word` | `1.1.0` |
-| `rgb_matrix_indicators` | `rgb_matrix_indicators_<module>` | `rgb_matrix_indicators_hello_word` | `1.1.0` |
-| `rgb_matrix_indicators_advanced` | `rgb_matrix_indicators_advanced_<module>` | `rgb_matrix_indicators_advanced_hello_word` | `1.1.0` |
-| `pointing_device_init` | `pointing_device_init_<module>` | `pointing_device_init_hello_word` | `1.1.0` |
-| `pointing_device_task` | `pointing_device_task_<module>` | `pointing_device_task_hello_word` | `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
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 113b13f03b..28d24bc400 100644
--- a/docs/features/led_matrix.md
+++ b/docs/features/led_matrix.md
@@ -214,9 +214,30 @@ led_matrix_mode(LED_MATRIX_CUSTOM_my_cool_effect);
For inspiration and examples, check out the built-in effects under `quantum/led_matrix/animations/`.
+## Naming
+
+If you wish to be able to use the name of an effect in your code -- say for a display indicator -- then you can enable the function `led_matrix_get_mode_name` in the following manner:
+
+In your keymap's `config.h`:
+```c
+#define LED_MATRIX_MODE_NAME_ENABLE
+```
+
+In your `keymap.c`
+```c
+const char* effect_name = led_matrix_get_mode_name(led_matrix_get_mode());
+// do something with `effect_name`, like `oled_write_ln(effect_name, false);`
+```
+
+::: info
+`led_matrix_get_mode_name()` is not enabled by default as it increases the amount of flash memory used by the firmware based on the number of effects enabled.
+:::
+
+
## Additional `config.h` Options {#additional-configh-options}
```c
+#define LED_MATRIX_MODE_NAME_ENABLE // enables led_matrix_get_mode_name()
#define LED_MATRIX_KEYRELEASES // reactive effects respond to keyreleases (instead of keypresses)
#define LED_MATRIX_TIMEOUT 0 // number of milliseconds to wait until led automatically turns off
#define LED_MATRIX_SLEEP // turn off effects when suspended
diff --git a/docs/features/pointing_device.md b/docs/features/pointing_device.md
index a139df9dc4..f25ea1b033 100644
--- a/docs/features/pointing_device.md
+++ b/docs/features/pointing_device.md
@@ -379,7 +379,7 @@ POINTING_DEVICE_DRIVER = custom
Using the custom driver will require implementing the following functions:
```c
-void pointing_device_driver_init(void) {}
+bool pointing_device_driver_init(void) { return true; }
report_mouse_t pointing_device_driver_get_report(report_mouse_t mouse_report) { return mouse_report; }
uint16_t pointing_device_driver_get_cpi(void) { return 0; }
void pointing_device_driver_set_cpi(uint16_t cpi) {}
@@ -467,20 +467,22 @@ If there is a `_RIGHT` configuration option or callback, the [common configurati
## Callbacks and Functions
-| Function | Description |
-| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `pointing_device_init_kb(void)` | Callback to allow for keyboard level initialization. Useful for additional hardware sensors. |
-| `pointing_device_init_user(void)` | Callback to allow for user level initialization. Useful for additional hardware sensors. |
-| `pointing_device_task_kb(mouse_report)` | Callback that sends sensor data, so keyboard code can intercept and modify the data. Returns a mouse report. |
-| `pointing_device_task_user(mouse_report)` | Callback that sends sensor data, so user code can intercept and modify the data. Returns a mouse report. |
-| `pointing_device_handle_buttons(buttons, pressed, button)` | Callback to handle hardware button presses. Returns a `uint8_t`. |
-| `pointing_device_get_cpi(void)` | Gets the current CPI/DPI setting from the sensor, if supported. |
-| `pointing_device_set_cpi(uint16_t)` | Sets the CPI/DPI, if supported. |
-| `pointing_device_get_report(void)` | Returns the current mouse report (as a `report_mouse_t` data structure). |
-| `pointing_device_set_report(mouse_report)` | Sets the mouse report to the assigned `report_mouse_t` data structured passed to the function. |
-| `pointing_device_send(void)` | Sends the current mouse report to the host system. Function can be replaced. |
-| `has_mouse_report_changed(new_report, old_report)` | Compares the old and new `report_mouse_t` data and returns true only if it has changed. |
-| `pointing_device_adjust_by_defines(mouse_report)` | Applies rotations and invert configurations to a raw mouse report. |
+| Function | Description |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `pointing_device_init_kb(void)` | Callback to allow for keyboard level initialization. Useful for additional hardware sensors. |
+| `pointing_device_init_user(void)` | Callback to allow for user level initialization. Useful for additional hardware sensors. |
+| `pointing_device_task_kb(mouse_report)` | Callback that sends sensor data, so keyboard code can intercept and modify the data. Returns a mouse report. |
+| `pointing_device_task_user(mouse_report)` | Callback that sends sensor data, so user code can intercept and modify the data. Returns a mouse report. |
+| `pointing_device_handle_buttons(buttons, pressed, button)` | Callback to handle hardware button presses. Returns a `uint8_t`. |
+| `pointing_device_get_cpi(void)` | Gets the current CPI/DPI setting from the sensor, if supported. |
+| `pointing_device_set_cpi(uint16_t)` | Sets the CPI/DPI, if supported. |
+| `pointing_device_get_report(void)` | Returns the current mouse report (as a `report_mouse_t` data structure). |
+| `pointing_device_set_report(mouse_report)` | Sets the mouse report to the assigned `report_mouse_t` data structured passed to the function. |
+| `pointing_device_send(void)` | Sends the current mouse report to the host system. Function can be replaced. |
+| `has_mouse_report_changed(new_report, old_report)` | Compares the old and new `report_mouse_t` data and returns true only if it has changed. |
+| `pointing_device_adjust_by_defines(mouse_report)` | Applies rotations and invert configurations to a raw mouse report. |
+| `pointing_device_get_status(void)` | Returns device status as `pointing_device_status_t` a good return is `POINTING_DEVICE_STATUS_SUCCESS`. |
+| `pointing_device_set_status(pointing_device_status_t status)` | Sets device status, anything other than `POINTING_DEVICE_STATUS_SUCCESS` will disable reports from the device.|
## Split Keyboard Callbacks and Functions
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..b0110b436b 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` |
@@ -363,9 +365,30 @@ These are shorthands to popular colors. The `RGB` ones can be passed to the `set
These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/color.h). Feel free to add to this list!
+## Naming
+
+If you wish to be able to use the name of an effect in your code -- say for a display indicator -- then you can enable the function `rgb_matrix_get_mode_name` in the following manner:
+
+In your keymap's `config.h`:
+```c
+#define RGB_MATRIX_MODE_NAME_ENABLE
+```
+
+In your `keymap.c`
+```c
+const char* effect_name = rgb_matrix_get_mode_name(rgb_matrix_get_mode());
+// do something with `effect_name`, like `oled_write_ln(effect_name, false);`
+```
+
+::: info
+`rgb_matrix_get_mode_name()` is not enabled by default as it increases the amount of flash memory used by the firmware based on the number of effects enabled.
+:::
+
+
## Additional `config.h` Options {#additional-configh-options}
```c
+#define RGB_MATRIX_MODE_NAME_ENABLE // enables rgb_matrix_get_mode_name()
#define RGB_MATRIX_KEYRELEASES // reactive effects respond to keyreleases (instead of keypresses)
#define RGB_MATRIX_TIMEOUT 0 // number of milliseconds to wait until rgb automatically turns off
#define RGB_MATRIX_SLEEP // turn off effects when suspended
@@ -484,7 +507,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}