zmk/docs/docs/behaviors/lighting.md

title	sidebar_label
Lighting Behavior	Lighting

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:

Define	Action
RGB_TOG	Toggles the RGB feature on and off
RGB_HUI	Increases the hue of the RGB feature
RGB_HUD	Decreases the hue of the RGB feature
RGB_SAI	Increases the saturation of the RGB feature
RGB_SAD	Decreases the saturation of the RGB feature
RGB_BRI	Increases the brightness of the RGB feature
RGB_BRD	Decreases the brightness of the RGB feature
RGB_SPI	Increases the speed of the RGB feature effect's animation
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_COLOR_HSB	Sets 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)

:::note 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)