Skip to main content

RGB Underglow Behavior

Summary​

This page contains RGB Underglow behaviors supported by ZMK.

RGB Action Defines​

RGB actions defines are provided through the dt-bindings/zmk/rgb.h header, which is added at the top of the keymap file:

#include <dt-bindings/zmk/rgb.h>

This will allow you to reference the actions defined in this header such as RGB_TOG.

Here is a table describing the action for each define:

DefineAction
RGB_ONTurns the RGB feature on
RGB_OFFTurns the RGB feature off
RGB_TOGToggles the RGB feature on and off
RGB_HUIIncreases the hue of the RGB feature
RGB_HUDDecreases the hue of the RGB feature
RGB_SAIIncreases the saturation of the RGB feature
RGB_SADDecreases the saturation of the RGB feature
RGB_BRIIncreases the brightness of the RGB feature
RGB_BRDDecreases the brightness of the RGB feature
RGB_SPIIncreases the speed of the RGB feature effect's animation
RGB_SPDDecreases the speed of the RGB feature effect's animation
RGB_EFFCycles the RGB feature's effect forwards
RGB_EFRCycles the RGB feature's effect reverse
RGB_COLOR_HSBSets a specific HSB (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)
HSB Values

When specifying HSB values you'll need to use RGB_COLOR_HSB(h, s, b) in your keymap file.

Value Limits:

  • Hue values can not exceed 360 (degrees)
  • Saturation values can not exceed 100 (percent)
  • Brightness values can not exceed 100 (percent)
RGB settings persistence

The RGB settings that are changed via the &rgb_ug behavior will be saved to flash storage and hence persist across restarts and firmware flashes. They will also override the start values set by CONFIG_ZMK_RGB_*_START settings. However the settings will only be saved after CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE milliseconds in order to reduce potential wear on the flash memory.

Examples​

  1. Toggle underglow on/off

    &rgb_ug RGB_TOG

  2. Set a specific HSB color (green)

    &rgb_ug RGB_COLOR_HSB(128,100,100)

Split Keyboards​

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