Lighting Behavior

Summary

Lighting is often used for either aesthetics or for the practical purposes of lighting up keys in the dark. Currently ZMK supports RGB underglow, which can be changed and configured using its behavior.

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_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

RGB Underglow

The "RGB underglow" behavior completes an RGB action given on press.

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 values of the color to set within parenthesis and separated by a common (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. See below for an example.

Value Limits:

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

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)
Edit this page