feat(Underglow): Momentary effect selection

app/include/dt-bindings/zmk/rgb.h

@@ -18,7 +18,8 @@
 #define RGB_EFF_CMD 11
 #define RGB_EFR_CMD 12
 #define RGB_EFS_CMD 13
-#define RGB_COLOR_HSB_CMD 14
+#define RGB_MEFS_CMD 14
+#define RGB_COLOR_HSB_CMD 15
 
 #define RGB_TOG RGB_TOG_CMD 0
 #define RGB_ON RGB_ON_CMD 0
@@ -33,6 +34,13 @@
 #define RGB_SPD RGB_SPD_CMD 0
 #define RGB_EFF RGB_EFF_CMD 0
 #define RGB_EFR RGB_EFR_CMD 0
+#define RGB_EFS RGB_EFS_CMD
+#define RGB_MEFS RGB_MEFS_CMD
 #define RGB_COLOR_HSB_VAL(h, s, v) (((h) << 16) + ((s) << 8) + (v))
 #define RGB_COLOR_HSB(h, s, v) RGB_COLOR_HSB_CMD##(RGB_COLOR_HSB_VAL(h, s, v))
-#define RGB_COLOR_HSV RGB_COLOR_HSB
+#define RGB_COLOR_HSV RGB_COLOR_HSB
+
+#define RGB_EFF_SOLID 0
+#define RGB_EFF_BREATHE 1
+#define RGB_EFF_SPECTRUM 2
+#define RGB_EFF_SWIRL 3

app/src/behaviors/behavior_rgb_underglow.c

@@ -18,6 +18,8 @@ LOG_MODULE_DECLARE(zmk, CONFIG_ZMK_LOG_LEVEL);
 
 #if DT_HAS_COMPAT_STATUS_OKAY(DT_DRV_COMPAT)
 
+static uint8_t old_effect;
+
 #if IS_ENABLED(CONFIG_ZMK_BEHAVIOR_METADATA)
 
 static const struct behavior_parameter_value_metadata no_arg_values[] = {
@@ -236,6 +238,9 @@ static int on_keymap_binding_pressed(struct zmk_behavior_binding *binding,
         return zmk_rgb_underglow_change_spd(-1);
     case RGB_EFS_CMD:
         return zmk_rgb_underglow_select_effect(binding->param2);
+    case RGB_MEFS_CMD:
+        old_effect = zmk_rgb_underglow_calc_effect(0);
+        return zmk_rgb_underglow_select_effect(binding->param2);
     case RGB_EFF_CMD:
         return zmk_rgb_underglow_cycle_effect(1);
     case RGB_EFR_CMD:
@@ -251,6 +256,8 @@ static int on_keymap_binding_pressed(struct zmk_behavior_binding *binding,
 
 static int on_keymap_binding_released(struct zmk_behavior_binding *binding,
                                       struct zmk_behavior_binding_event event) {
+    if (binding->param1 == RGB_MEFS_CMD)
+        return zmk_rgb_underglow_select_effect(old_effect);
     return ZMK_BEHAVIOR_OPAQUE;
 }
 

docs/docs/keymaps/behaviors/underglow.md

@@ -35,13 +35,15 @@ Here is a table describing the action for each define:
 | `RGB_SPD`       | Decreases the speed of the RGB feature effect's animation                                      |
 | `RGB_EFF`       | Cycles the RGB feature's effect forwards                                                       |
 | `RGB_EFR`       | Cycles the RGB feature's effect reverse                                                        |
+| `RGB_EFS`       | Selects a specific RGB effect                                                                  |
+| `RGB_MEFS`      | Selects a specific RGB effect whilst held down and reverts when released                       |
 | `RGB_COLOR_HSB` | Sets a specific [HSB (HSV)](https://en.wikipedia.org/wiki/HSL_and_HSV) value for the underglow |
 
 ## Behavior Binding
 
 - Reference: `&rgb_ug`
 - Parameter #1: The RGB action define, e.g. `RGB_TOG` or `RGB_BRI`
-- Parameter #2: Only applies to `RGB_COLOR_HSB` and is the HSB representation of the color to set (see below for an example)
+- Parameter #2: Applies to `RGB_EFS` and `RGB_MEFS` (the effect to select) as well as `RGB_COLOR_HSB` (the HSB representation of the color to set). See below for examples.
 
 :::note[HSB Values]
 
@@ -61,6 +63,27 @@ They will also override the start values set by [`CONFIG_ZMK_RGB_*_START` settin
 However the settings will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE`](../../config/system.md#general) milliseconds in order to reduce potential wear on the flash memory.
 :::
 
+:::note Effect Selection
+
+When using the `RGB_EFS` or `RGB_MEFS` definitions you must also include a parameter corresponding to the effect you want to select, e.g. `&rgb_ug RGB_EFS RGB_EFF_SOLID`. There are currently 4 RGB effects, defined in [`dt-bindings/zmk/rgb.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/rgb.h):
+
+| Value              | Effect                                    |
+| ------------------ | ----------------------------------------- |
+| `RGB_EFF_SOLID`    | Solid color (set by HSB)                  |
+| `RGB_EFF_BREATHE`  | Breathe a solid color                     |
+| `RGB_EFF_SPECTRUM` | Cycle all LEDs through the color spectrum |
+| `RGB_EFF_SWIRL`    | Swirl a rainbow around the LEDs           |
+
+When using the `RGB_EFS` or `RGB_MEFS` definitions you must also include a number as an argument in the keymap corresponding to the effect you want to select e.g. `RGB_EFS 0`
+
+:::
+
+:::warning
+
+If the `RGB_MEFS` key is held down for longer than [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE`](../../config/system.md#general) milliseconds and the board is reset prior to releasing the key, the temporary effect will have been saved to flash memory and will be the one selected after resetting/power cycling.
+
+:::
+
 ## Examples
 
 1. Toggle underglow on/off
@@ -75,6 +98,12 @@ However the settings will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNC
    &rgb_ug RGB_COLOR_HSB(128,100,100)
    ```
 
+1. Select a specific RGB effect (Swirl)
+
+   ```dts
+   &rgb_ug RGB_EFS RGB_EFF_SWIRL
+   ```
+
 ## Split Keyboards
 
 RGB underglow behaviors are [global](../../features/split-keyboards.md#global-locality-behaviors): This means that when triggered, they affect both the central and peripheral side of split keyboards.