aboutsummaryrefslogtreecommitdiff
path: root/docs/features
diff options
context:
space:
mode:
Diffstat (limited to 'docs/features')
-rw-r--r--docs/features/bluetooth.md10
-rw-r--r--docs/features/combo.md70
-rw-r--r--docs/features/os_detection.md30
-rw-r--r--docs/features/pointing_device.md1
-rw-r--r--docs/features/rgb_matrix.md62
-rw-r--r--docs/features/rgblight.md6
6 files changed, 112 insertions, 67 deletions
diff --git a/docs/features/bluetooth.md b/docs/features/bluetooth.md
index 1dbf15f4e1..d3634498be 100644
--- a/docs/features/bluetooth.md
+++ b/docs/features/bluetooth.md
@@ -39,8 +39,8 @@ BLUETOOTH_DRIVER = bluefruit_le # or rn42
This is used when multiple keyboard outputs can be selected. Currently this only allows for switching between USB and Bluetooth on keyboards that support both.
-|Key |Aliases |Description |
-|---------------------|---------|----------------------------------------------|
-|`QK_OUTPUT_AUTO` |`OU_AUTO`|Automatically switch between USB and Bluetooth|
-|`QK_OUTPUT_USB` |`OU_USB` |USB only |
-|`QK_OUTPUT_BLUETOOTH`|`OU_BT` |Bluetooth only |
+| Key | Aliases | Description |
+|-----------------------|----------------------|------------------------------------------------|
+| `QK_OUTPUT_NEXT` | `OU_NEXT`, `OU_AUTO` | Automatically switch between USB and Bluetooth |
+| `QK_OUTPUT_USB` | `OU_USB` | USB only |
+| `QK_OUTPUT_BLUETOOTH` | `OU_BT` | Bluetooth only |
diff --git a/docs/features/combo.md b/docs/features/combo.md
index bdb8c4b15f..afe202ad54 100644
--- a/docs/features/combo.md
+++ b/docs/features/combo.md
@@ -152,14 +152,15 @@ In order to use these features, the following configuration options and function
| Config Flag | Function | Description |
|-----------------------------|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
-| `COMBO_TERM_PER_COMBO` | uint16_t get_combo_term(uint16_t index, combo_t \*combo) | Optional per-combo timeout window. (default: `COMBO_TERM`) |
-| `COMBO_MUST_HOLD_PER_COMBO` | bool get_combo_must_hold(uint16_t index, combo_t \*combo) | Controls if a given combo should fire immediately on tap or if it needs to be held. (default: `false`) |
-| `COMBO_MUST_TAP_PER_COMBO` | bool get_combo_must_tap(uint16_t index, combo_t \*combo) | Controls if a given combo should fire only if tapped within `COMBO_HOLD_TERM`. (default: `false`) |
-| `COMBO_MUST_PRESS_IN_ORDER_PER_COMBO` | bool get_combo_must_press_in_order(uint16_t index, combo_t \*combo) | Controls if a given combo should fire only if its keys are pressed in order. (default: `true`) |
+| `COMBO_TERM_PER_COMBO` | `uint16_t get_combo_term(uint16_t combo_index, combo_t *combo)` | Optional per-combo timeout window. (default: `COMBO_TERM`) |
+| `COMBO_MUST_HOLD_PER_COMBO` | `bool get_combo_must_hold(uint16_t combo_index, combo_t *combo)` | Controls if a given combo should fire immediately on tap or if it needs to be held. (default: `false`) |
+| `COMBO_MUST_TAP_PER_COMBO` | `bool get_combo_must_tap(uint16_t combo_index, combo_t *combo)` | Controls if a given combo should fire only if tapped within `COMBO_HOLD_TERM`. (default: `false`) |
+| `COMBO_MUST_PRESS_IN_ORDER_PER_COMBO` | `bool get_combo_must_press_in_order(uint16_t combo_index, combo_t *combo)` | Controls if a given combo should fire only if its keys are pressed in order. (default: `true`) |
Examples:
```c
-uint16_t get_combo_term(uint16_t index, combo_t *combo) {
+#ifdef COMBO_TERM_PER_COMBO
+uint16_t get_combo_term(uint16_t combo_index, combo_t *combo) {
// decide by combo->keycode
switch (combo->keycode) {
case KC_X:
@@ -167,7 +168,7 @@ uint16_t get_combo_term(uint16_t index, combo_t *combo) {
}
// or with combo index, i.e. its name from enum.
- switch (index) {
+ switch (combo_index) {
case COMBO_NAME_HERE:
return 9001;
}
@@ -182,8 +183,10 @@ uint16_t get_combo_term(uint16_t index, combo_t *combo) {
return COMBO_TERM;
}
+#endif
-bool get_combo_must_hold(uint16_t index, combo_t *combo) {
+#ifdef COMBO_MUST_HOLD_PER_COMBO
+bool get_combo_must_hold(uint16_t combo_index, combo_t *combo) {
// Same as above, decide by keycode, the combo index, or by the keys in the chord.
if (KEYCODE_IS_MOD(combo->keycode) ||
@@ -192,15 +195,17 @@ bool get_combo_must_hold(uint16_t index, combo_t *combo) {
return true;
}
- switch (index) {
+ switch (combo_index) {
case COMBO_NAME_HERE:
return true;
}
return false;
}
+#endif
-bool get_combo_must_tap(uint16_t index, combo_t *combo) {
+#ifdef COMBO_MUST_TAP_PER_COMBO
+bool get_combo_must_tap(uint16_t combo_index, combo_t *combo) {
// If you want all combos to be tap-only, just uncomment the next line
// return true
@@ -219,7 +224,9 @@ bool get_combo_must_tap(uint16_t index, combo_t *combo) {
return false;
}
+#endif
+#ifdef COMBO_MUST_PRESS_IN_ORDER_PER_COMBO
bool get_combo_must_press_in_order(uint16_t combo_index, combo_t *combo) {
switch (combo_index) {
/* List combos here that you want to only activate if their keys
@@ -231,6 +238,7 @@ bool get_combo_must_press_in_order(uint16_t combo_index, combo_t *combo) {
return false;
}
}
+#endif
```
### Generic hook to (dis)allow a combo activation
@@ -307,6 +315,50 @@ bool process_combo_key_release(uint16_t combo_index, combo_t *combo, uint8_t key
return false;
}
```
+
+### Customizable key repress
+By defining `COMBO_PROCESS_KEY_REPRESS` and implementing `bool process_combo_key_repress(uint16_t combo_index, combo_t *combo, uint8_t key_index, uint16_t keycode)` you can run your custom code when you repress just released key of a combo. By combining it with custom `process_combo_event` we can for example make special handling for Alt+Tab to switch windows, which, on combo F+G activation, registers Alt and presses Tab - then we can switch windows forward by releasing G and pressing it again, or backwards with F key. Here's the full example:
+
+```c
+enum combos {
+ CMB_ALTTAB
+};
+
+const uint16_t PROGMEM combo_alttab[] = {KC_F, KC_G, COMBO_END};
+
+combo_t key_combos[COMBO_LENGTH] = {
+ [CMB_ALTTAB] = COMBO(combo_alttab, KC_NO), // KC_NO to leave processing for process_combo_event
+};
+
+void process_combo_event(uint16_t combo_index, bool pressed) {
+ switch (combo_index) {
+ case CMB_ALTTAB:
+ if (pressed) {
+ register_mods(MOD_LALT);
+ tap_code(KC_TAB);
+ } else {
+ unregister_mods(MOD_LALT);
+ }
+ break;
+ }
+}
+
+bool process_combo_key_repress(uint16_t combo_index, combo_t *combo, uint8_t key_index, uint16_t keycode) {
+ switch (combo_index) {
+ case CMB_ALTTAB:
+ switch (keycode) {
+ case KC_F:
+ tap_code16(S(KC_TAB));
+ return true;
+ case KC_G:
+ tap_code(KC_TAB);
+ return true;
+ }
+ }
+ return false;
+}
+```
+
### Layer independent combos
If you, for example, use multiple base layers for different key layouts, one for QWERTY, and another one for Colemak, you might want your combos to work from the same key positions on all layers. Defining the same combos again for another layout is redundant and takes more memory. The solution is to just check the keycodes from one layer.
diff --git a/docs/features/os_detection.md b/docs/features/os_detection.md
index d0556d2549..880e88d4b9 100644
--- a/docs/features/os_detection.md
+++ b/docs/features/os_detection.md
@@ -70,17 +70,33 @@ The process is done in steps, generating a number of intermediate results until
We therefore resort to debouncing the result until it has been stable for a given amount of milliseconds.
This amount can be configured, in case your board is not stable within the default debouncing time of 200ms.
-## KVM and USB switches
-
-Some KVM and USB switches may not trigger the USB controller on the keyboard to fully reset upon switching machines.
-If your keyboard does not redetect the OS in this situation, you can force the keyboard to reset when the USB initialization event is detected, forcing the USB controller to be reconfigured.
-
## Configuration Options
-* `#define OS_DETECTION_DEBOUNCE 200`
+* `#define OS_DETECTION_DEBOUNCE 250`
* defined the debounce time for OS detection, in milliseconds
+ * defaults to 250ms
* `#define OS_DETECTION_KEYBOARD_RESET`
- * enables the keyboard reset upon a USB device reinitilization, such as switching devices on some KVMs
+ * enables the keyboard reset upon a USB device reinitilization
+ * this setting may help with detection issues when switching between devices on some KVMs (see [Troubleshooting](#troubleshooting))
+* `#define OS_DETECTION_SINGLE_REPORT`
+ * allows the report callbacks to be called only once, when the OS detection result is considered stable
+ * subsequent changes in the detection results, if any, are ignored
+ * this setting may help with delayed stability issues when switching devices on some KVMs (see [Troubleshooting](#troubleshooting))
+
+## Troubleshooting
+
+Some KVMs and USB switches may cause issues when the OS detection is turned on.
+Here is a list of common issues and how to fix them:
+
+* **Problem**: _keyboard won't redetect the OS when switching between machines using a KVM_
+ * **Explanation**: some KVMs keep the USB controller powered on during the switch and OS
+ detection happens when the USB device description is being assembled.
+ * **Solution**: use `OS_DETECTION_KEYBOARD_RESET` to force the keyboard to reset upon switching.
+* **Problem**: _keyboard OS detection callback gets invoked even minuted after startup_
+ * **Explanation**: some OSes, notably macOS on ARM-based Macs, may cause this behavior.
+ The actual cause is not known at this time.'
+ * **Solution**: use `OS_DETECTION_SINGLE_REPORT` to suppress repeated callback invocations.
+
## Debug
diff --git a/docs/features/pointing_device.md b/docs/features/pointing_device.md
index a6bf521a18..0ecf82c8df 100644
--- a/docs/features/pointing_device.md
+++ b/docs/features/pointing_device.md
@@ -394,6 +394,7 @@ Ideally, new sensor hardware should be added to `drivers/sensors/` and `quantum/
| Setting | Description | Default |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `MOUSE_EXTENDED_REPORT` | (Optional) Enables support for extended mouse reports. (-32767 to 32767, instead of just -127 to 127). | _not defined_ |
+| `WHEEL_EXTENDED_REPORT` | (Optional) Enables support for extended wheel reports. (-32767 to 32767, instead of just -127 to 127). | _not defined_ |
| `POINTING_DEVICE_ROTATION_90` | (Optional) Rotates the X and Y data by 90 degrees. | _not defined_ |
| `POINTING_DEVICE_ROTATION_180` | (Optional) Rotates the X and Y data by 180 degrees. | _not defined_ |
| `POINTING_DEVICE_ROTATION_270` | (Optional) Rotates the X and Y data by 270 degrees. | _not defined_ |
diff --git a/docs/features/rgb_matrix.md b/docs/features/rgb_matrix.md
index bc14bb6277..0e53ce9c35 100644
--- a/docs/features/rgb_matrix.md
+++ b/docs/features/rgb_matrix.md
@@ -81,38 +81,21 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{
## Keycodes {#keycodes}
-All RGB keycodes are currently shared with the RGBLIGHT system:
-
-|Key |Aliases |Description |
-|-------------------|----------|--------------------------------------------------------------------------------------|
-|`RGB_TOG` | |Toggle RGB lighting on or off |
-|`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held |
-|`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held |
-|`RGB_HUI` | |Increase hue, decrease hue when Shift is held |
-|`RGB_HUD` | |Decrease hue, increase hue when Shift is held |
-|`RGB_SAI` | |Increase saturation, decrease saturation when Shift is held |
-|`RGB_SAD` | |Decrease saturation, increase saturation when Shift is held |
-|`RGB_VAI` | |Increase value (brightness), decrease value when Shift is held |
-|`RGB_VAD` | |Decrease value (brightness), increase value when Shift is held |
-|`RGB_SPI` | |Increase effect speed (does not support eeprom yet), decrease speed when Shift is held|
-|`RGB_SPD` | |Decrease effect speed (does not support eeprom yet), increase speed when Shift is held|
-|`RGB_MODE_PLAIN` |`RGB_M_P` |Static (no animation) mode |
-|`RGB_MODE_BREATHE` |`RGB_M_B` |Breathing animation mode |
-|`RGB_MODE_RAINBOW` |`RGB_M_R` |Full gradient scrolling left to right (uses the `RGB_MATRIX_CYCLE_LEFT_RIGHT` mode) |
-|`RGB_MODE_SWIRL` |`RGB_M_SW`|Full gradient spinning pinwheel around center of keyboard (uses `RGB_MATRIX_CYCLE_PINWHEEL` mode) |
-
-* `RGB_MODE_*` keycodes will generally work, but not all of the modes are currently mapped to the correct effects for the RGB Matrix system.
-
-`RGB_MODE_PLAIN`, `RGB_MODE_BREATHE`, `RGB_MODE_RAINBOW`, and `RGB_MODE_SWIRL` are the only ones that are mapped properly. The rest don't have a direct equivalent, and are not mapped.
-
-::: tip
-`RGB_*` keycodes cannot be used with functions like `tap_code16(RGB_HUD)` as they're not USB HID keycodes. If you wish to replicate similar behaviour in custom code within your firmware (e.g. inside `encoder_update_user()` or `process_record_user()`), the equivalent [RGB functions](#functions) should be used instead.
-:::
-
-
-::: warning
-By default, if you have both the [RGB Light](rgblight) and the RGB Matrix feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature.
-:::
+|Key |Aliases |Description |
+|-------------------------------|---------|-----------------------------------|
+|`QK_RGB_MATRIX_ON` |`RM_ON` |Turn on RGB Matrix |
+|`QK_RGB_MATRIX_OFF` |`RM_OFF` |Turn off RGB Matrix |
+|`QK_RGB_MATRIX_TOGGLE` |`RM_TOGG`|Toggle RGB Matrix on or off |
+|`QK_RGB_MATRIX_MODE_NEXT` |`RM_NEXT`|Cycle through animations |
+|`QK_RGB_MATRIX_MODE_PREVIOUS` |`RM_PREV`|Cycle through animations in reverse|
+|`QK_RGB_MATRIX_HUE_UP` |`RM_HUEU`|Cycle through hue |
+|`QK_RGB_MATRIX_HUE_DOWN` |`RM_HUED`|Cycle through hue in reverse |
+|`QK_RGB_MATRIX_SATURATION_UP` |`RM_SATU`|Increase the saturation |
+|`QK_RGB_MATRIX_SATURATION_DOWN`|`RM_SATD`|Decrease the saturation |
+|`QK_RGB_MATRIX_VALUE_UP` |`RM_VALU`|Increase the brightness level |
+|`QK_RGB_MATRIX_VALUE_DOWN` |`RM_VALD`|Decrease the brightness level |
+|`QK_RGB_MATRIX_SPEED_UP` |`RM_SPDU`|Increase the animation speed |
+|`QK_RGB_MATRIX_SPEED_DOWN` |`RM_SPDD`|Decrease the animation speed |
## RGB Matrix Effects {#rgb-matrix-effects}
@@ -289,7 +272,7 @@ Solid reactive effects will pulse RGB light on key presses with user configurabl
#define RGB_MATRIX_SOLID_REACTIVE_GRADIENT_MODE
```
-Gradient mode will loop through the color wheel hues over time and its duration can be controlled with the effect speed keycodes (`RGB_SPI`/`RGB_SPD`).
+Gradient mode will loop through the color wheel hues over time and its duration can be controlled with the effect speed keycodes (`RM_SPDU`/`RM_SPDD`).
## Custom RGB Matrix Effects {#custom-rgb-matrix-effects}
@@ -396,7 +379,6 @@ These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master
#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_DEFAULT_FLAGS LED_FLAG_ALL // Sets the default LED flags, if none has been set
-#define RGB_MATRIX_DISABLE_KEYCODES // disables control of rgb matrix by keycodes (must use code functions to control the feature)
#define RGB_MATRIX_SPLIT { X, Y } // (Optional) For split keyboards, the number of LEDs connected on each half. X = left, Y = Right.
// If reactive effects are enabled, you also will want to enable SPLIT_TRANSPORT_MIRROR
#define RGB_TRIGGER_ON_KEYDOWN // Triggers RGB keypress events on key down. This makes RGB control feel more responsive. This may cause RGB to not function properly on some boards
@@ -496,18 +478,18 @@ This example sets the modifiers to be a specific color based on the layer state.
```c
bool rgb_matrix_indicators_advanced_user(uint8_t led_min, uint8_t led_max) {
- HSV hsv = {0, 255, 255};
+ hsv_t hsv = {0, 255, 255};
if (layer_state_is(layer_state, 2)) {
- hsv = (HSV){130, 255, 255};
+ hsv = (hsv_t){130, 255, 255};
} else {
- hsv = (HSV){30, 255, 255};
+ hsv = (hsv_t){30, 255, 255};
}
if (hsv.v > rgb_matrix_get_val()) {
hsv.v = rgb_matrix_get_val();
}
- RGB rgb = hsv_to_rgb(hsv);
+ rgb_t rgb = hsv_to_rgb(hsv);
for (uint8_t i = led_min; i < led_max; i++) {
if (HAS_FLAGS(g_led_config.flags[i], 0x01)) { // 0x01 == LED_FLAG_MODIFIER
@@ -873,13 +855,13 @@ Set the global effect hue, saturation, and value (brightness). New state is not
---
-### `HSV rgb_matrix_get_hsv(void)` {#api-rgb-matrix-get-hsv}
+### `hsv_t rgb_matrix_get_hsv(void)` {#api-rgb-matrix-get-hsv}
Get the current global effect hue, saturation, and value (brightness).
#### Return Value {#api-rgb-matrix-get-hsv-return}
-The current effect HSV as an `HSV` struct.
+The current effect HSV as an `hsv_t` struct.
---
diff --git a/docs/features/rgblight.md b/docs/features/rgblight.md
index 794398a0f9..2afc2eb7d0 100644
--- a/docs/features/rgblight.md
+++ b/docs/features/rgblight.md
@@ -87,11 +87,6 @@ Changing the **Value** sets the overall brightness.<br>
These keycodes cannot be used with functions like `tap_code16()` as they are not USB HID keycodes. If you wish to replicate similar behaviour in custom code within your firmware (e.g. inside `encoder_update_user()` or `process_record_user()`), the equivalent [RGB functions](#functions) should be used instead.
:::
-
-::: warning
-By default, if you have both the RGB Light and the [RGB Matrix](rgb_matrix) feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature.
-:::
-
## Configuration
Your RGB lighting can be configured by placing these `#define`s in your `config.h`:
@@ -104,7 +99,6 @@ Your RGB lighting can be configured by placing these `#define`s in your `config.
|`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 |
-|`RGBLIGHT_DISABLE_KEYCODES`|*Not defined* |If defined, disables the ability to control RGB Light from the keycodes. You must use code functions to control the feature|
|`RGBLIGHT_DEFAULT_MODE` |`RGBLIGHT_MODE_STATIC_LIGHT`|The default mode to use upon clearing the EEPROM |
|`RGBLIGHT_DEFAULT_HUE` |`0` (red) |The default hue to use upon clearing the EEPROM |
|`RGBLIGHT_DEFAULT_SAT` |`UINT8_MAX` (255) |The default saturation to use upon clearing the EEPROM |