Skip to content

Commit

Permalink
feat(docs): Document RGB momentary effect selection
Browse files Browse the repository at this point in the history
  • Loading branch information
ReFil committed Oct 18, 2023
1 parent 7283d32 commit 9e9b5f5
Showing 1 changed file with 17 additions and 1 deletion.
18 changes: 17 additions & 1 deletion docs/docs/behaviors/underglow.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -61,6 +63,14 @@ 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 number as an argument in the keymap corresponding to the effect you want to select e.g. `RGB_EFS 0`

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 restored after resetting/power cycling

:::

## Examples

1. Toggle underglow on/off
Expand All @@ -75,6 +85,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 3
```

## Split Keyboards

RGB underglow behaviors are global: This means that when triggered, they affect both the central and peripheral side of split keyboards.

0 comments on commit 9e9b5f5

Please sign in to comment.