<divid="app"><divclass="Layout"data-v-5d98c3a5><!--[--><!--]--><!--[--><spantabindex="-1"data-v-0f60ec36></span><ahref="#VPContent"class="VPSkipLink visually-hidden"data-v-0f60ec36> Skip to content </a><!--]--><!----><headerclass="VPNav"data-v-5d98c3a5data-v-ae24b3ad><divclass="VPNavBar has-sidebar top"data-v-ae24b3addata-v-ccf7ddec><divclass="wrapper"data-v-ccf7ddec><divclass="container"data-v-ccf7ddec><divclass="title"data-v-ccf7ddec><divclass="VPNavBarTitle has-sidebar"data-v-ccf7ddecdata-v-ab179fa1><aclass="title"href="/"data-v-ab179fa1><!--[--><!--]--><!--[--><!--[--><!--[--><imgclass="VPImage dark logo"src="/qmk-logo-dark.svg"altdata-v-8426fc1a><!--]--><!--[--><imgclass="VPImage light logo"src="/qmk-logo-light.svg"altdata-v-8426fc1a><!--]--><!--]--><!--]--><spandata-v-ab179fa1>QMK Firmware</span><!--[--><!--]--></a></div></div><divclass="content"data-v-ccf7ddec><divclass="content-body"data-v-ccf7ddec><!--[--><!--]--><divclass="VPNavBarSearch search"data-v-ccf7ddec><!--[--><!----><divid="local-search"><buttontype="button"class="DocSearch DocSearch-Button"aria-label="Search"><spanclass="DocSearch-Button-Container"><spanclass="vp-icon DocSearch-Search-Icon"></span><spanclass="DocSearch-Button-Placeholder">Search</span></span><spanclass="DocSearch-Button-Keys"><kbdclass="DocSearch-Button-Key"></kbd><kbdclass="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><navaria-labelledby="main-nav-aria-label"class="VPNavBarMenu menu"data-v-ccf7ddecdata-v-7f418b0f><spanid="main-nav-aria-label"class="visually-hidden"data-v-7f418b0f>Main Navigation</span><!--[--><!--[--><aclass="VPLink link VPNavBarMenuLink"href="./"tabindex="0"data-v-7f418b0fdata-v-9c663999><!--[--><spandata-v-9c663999>Home</span><!--]--></a><!--]--><!--]--></nav><!----><divclass="VPNavBarAppearance appearance"data-v-ccf7ddecdata-v-e6aabb21><buttonclass="VPSwitch VPSwitchAppearance"type="button"role="switch"title="Switch to dark theme"aria-checked="false"data-v-e6aabb21data-v-d1f28634data-v-1d5665e3><spanclass="check"data-v-1d5665e3><spanclass="icon"data-v-1d5665e3><!--[--><spanclass="vpi-sun sun"data-v-d1f28634></span><spanclass="vpi-moon moon"data-v-d1f28634></span><!--]--></span></span></button></div><divclass="VPSocialLinks VPNavBarSocialLinks social-links"data-v-ccf7ddecdata-v-0394ad82data-v-7bc22406><!--[--><aclass="VPSocialLink no-icon"href="https://reddit.com/r/olkb"aria-labeltarget="_blank"rel="noopener"data-v-7bc22406data-v-eee4e7cb><svgxmlns="http://www.w3.org/2000/svg"viewBox="0 0 50 50"width="50px"height="50px"><pathd="M293C28.0625327.1640633.38281326.54C25.8359384.61718825.3632815.433594256.40625C24.3554698.14062524.08593810.39453124.0312513.03125C19.23437513.17968814.82031314.42187511.2812516.46875C10.21484415.468758.85546914.968757.514.96875C6.08984414.968754.67578115.5117193.5937516.59375C1.42578118.7617191.42578122.2382813.5937524.40625L3.8437524.65625C3.312526.035156327.488281329C333.5273445.56640637.5859389.562540.4375C13.55859443.28906319.007813452545C30.9921884536.44140643.28906340.437540.4375C44.43359437.5859384733.5273444729C4727.48828146.687526.03515646.1562524.65625L46.4062524.40625C48.57421922.23828148.57421918.76171946.4062516.59375C45.32421915.51171943.91015614.9687542.514.96875C41.14453114.9687539.78515615.4687538.7187516.46875C35.19531314.43359430.80078113.19140626.0312513.03125C26.0937510.54687526.3632818.4687526.8757.09375C27.1640636.31640627.5273445.75781327.8755.4375C28.2226565.11718828.5390635295C29.460938529.6835945.12530.031255.40625C30.3789065.687530.7851566.14843831.31256.6875C32.2539067.65234433.6953138.71484436.093758.9375C36.53906311.23828138.574219134113C43.75134610.75468C465.2543.753413C38.605469336.5742194.71093836.093756.96875C34.31256.79687533.5273446.10937532.755.3125C32.3007814.85156331.886719
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">RGBLIGHT_DRIVER = apa102</span></span></code></pre></div><p>At minimum you must define the data pin your LED strip is connected to, and the number of LEDs in the strip, in your <code>config.h</code>. For APA102 LEDs, you must also define the clock pin. If your keyboard has onboard RGB LEDs, and you are simply creating a keymap, you usually won't need to modify these.</p><table><thead><tr><th>Define</th><th>Description</th></tr></thead><tbody><tr><td><code>WS2812_DI_PIN</code></td><td>The pin connected to the data pin of the LEDs (WS2812)</td></tr><tr><td><code>APA102_DI_PIN</code></td><td>The pin connected to the data pin of the LEDs (APA102)</td></tr><tr><td><code>APA102_CI_PIN</code></td><td>The pin connected to the clock pin of the LEDs (APA102)</td></tr><tr><td><code>RGBLIGHT_LED_COUNT</code></td><td>The number of LEDs connected</td></tr><tr><td><code>RGBLED_SPLIT</code></td><td>(Optional) For split keyboards, the number of LEDs connected on each half</td></tr></tbody></table><p>Then you should be able to use the keycodes below to change the RGB lighting to your liking.</p><h3id="color-selection"tabindex="-1">Color Selection <aclass="header-anchor"href="#color-selection"aria-label="Permalink to "Color Selection""></a></h3><p>QMK uses <ahref="https://en.wikipedia.org/wiki/HSL_and_HSV"target="_blank"rel="noreferrer">Hue, Saturation, and Value</a> to select colors rather than RGB. The color wheel below demonstrates how this works.</p><imgsrc="/assets/color-wheel.DWgAL3vL.svg"alt="HSV Color Wheel"width="250"><p>Changing the <strong>Hue</strong> cycles around the circle.<br> Changing the <strong>Saturation</strong> moves between the inner and outer sections of the wheel, affecting the intensity of the color.<br> Changing the <strong>Value</strong> sets the overall brightness.<br></p><p><imgsrc="https://i.imgur.com/vkYVo66.jpg"alt="QMK Color Wheel with HSV Values"></p><h2id="keycodes"tabindex="-1">Keycodes <aclass="header-anchor"href="#keycodes"aria-label="Permalink to "Keycodes""></a></h2><table><thead><tr><th>Key</th><th>Aliases</th><th>Description</th></tr></thead><tbody><tr><td><code>RGB_TOG</code></td><td></td><td>Toggle RGB lighting on or off</td></tr><tr><td><code>RGB_MODE_FORWARD</code></td><td><code>RGB_MOD</code></td><td>Cycle through modes, reverse direction when Shift is held</td></tr><tr><td><code>RGB_MODE_REVERSE</code></td><td><code>RGB_RMOD</code></td><td>Cycle through modes in reverse, forward direction when Shift is held</td></tr><tr><td><code>RGB_HUI</code></td><td></td><td>Increase hue, decrease hue when Shift is held</td></tr><tr><td><code>RGB_HUD</code></td><td></td><td>Decrease hue, increase hue when Shift is held</td></tr><tr><td><code>RGB_SAI</code></td><td></td><td>Increase saturation, decrease saturation when Shift is held</td></tr><tr><td><code>RGB_SAD</code></td><td></td><td>Decrease saturation, increase saturation when Shift is held</td></tr><tr><td><code>RGB_VAI</code></td><td></td><td>Increase value (brightness), decrease value when Shift is held</td></tr><tr><td><code>RGB_VAD</code></td><td></td><td>Decrease value (brightness), increase value when Shift is held</td></tr><tr><td><code>RGB_MODE_PLAIN</code></td><td><code>RGB_M_P </code></td><td>Static (no animation) mode</td></tr><tr><td><code>RGB_MODE_BREATHE</code></td><td><code>RGB_M_B</code></td><td>Breathing animation mode</td></tr><tr><td><code>RGB_MODE_RAINBOW</code></td><td><code>RGB_M_R</code></td><td>Rainbow animation mode</td></tr><tr><td><code>RGB_MODE_SWIRL</code></td><td><code>RGB_M_SW</code></td><td>Swirl animation mode</td></tr><tr><td><code>RGB_MODE_SNAKE</code></td><td><code>RGB_M_SN</code></td><td>Snake animation mode</td></tr><tr><td><code>RGB_MODE_KNIGHT</code></td><td><code>RGB_M_K</code></td><td>"Knight Rider" animation mode</td></tr><tr><td><code>RGB_MODE_XMAS</code></td><td><code>RGB_M_X</code></td><td>Christmas animation mode</td></tr><tr><td><code>RGB_MODE_GRADIENT</code></td><td><c
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> #define RGBLIGHT_SAT_STEP 8</span></span></code></pre></div><h3id="animation-speed"tabindex="-1">Animation Speed <aclass="header-anchor"href="#animation-speed"aria-label="Permalink to "Animation Speed""></a></h3><p>You can also modify the speeds that the different modes animate at:</p><p>Here is a quick demo on Youtube (with NPKC KC60) (<ahref="https://www.youtube.com/watch?v=VKrpPAHlisY"target="_blank"rel="noreferrer">https://www.youtube.com/watch?v=VKrpPAHlisY</a>).</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// How long (in milliseconds) to wait between animation steps for each of the "Solid color breathing" animations</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// How long (in milliseconds) to wait between animation steps for each of the "Cycling rainbow" animations</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// How long (in milliseconds) to wait between animation steps for each of the "Swirling rainbow" animations</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// How long (in milliseconds) to wait between animation steps for each of the "Snake" animations</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// How long (in milliseconds) to wait between animation steps for each of the "Knight" animations</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// How long (in milliseconds) to wait between animation steps for each of the "Twinkle" animations</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// These control which hues are selected for each of the "Static gradient" modes</span></span>
<spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;"> uint8_t</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> RGBLED_GRADIENT_RANGES</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">[]</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> PROGMEM </span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">255</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">170</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">127</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">85</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">64</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">};</span></span></code></pre></div><h2id="lighting-layers"tabindex="-1">Lighting Layers <aclass="header-anchor"href="#lighting-layers"aria-label="Permalink to "Lighting Layers""></a></h2><divclass="tip custom-block"><pclass="custom-block-title">TIP</p><p><strong>Note:</strong> Lighting Layers is an RGB Light feature, it will not work for RGB Matrix. See <ahref="./rgb_matrix#indicators">RGB Matrix Indicators</a> for details on how to do so.</p></div><p>By including <code>#define RGBLIGHT_LAYERS</code> in your <code>config.h</code> file you can enable lighting layers. These make it easy to use your underglow LEDs as status indicators to show which keyboard layer is currently active, or the state of caps lock, all without disrupting any animations. <ahref="https://youtu.be/uLGE1epbmdY"target="_blank"rel="noreferrer">Here's a video</a> showing an example of what you can do.</p><h3id="defining-lighting-layers"tabindex="-1">Defining Lighting Layers <aclass="header-anchor"href="#defining-lighting-layers"aria-label="Permalink to "Defining Lighting Layers {#defining-lighting-layers}""></a></h3><p>By default, 8 layers are possible. This can be expanded to as many as 32 by overriding the definition of <code>RGBLIGHT_MAX_LAYERS</code> in <code>config.h</code> (e.g. <code>#define RGBLIGHT_MAX_LAYERS 32</code>). Please note, if you use a split keyboard, you will need to flash both sides of the split after changing this. Also, increasing the maximum will increase the firmware size, and will slow sync on split keyboards.</p><p>To define a layer, we modify <code>keymap.c</code> to list the LED ranges and the colors we want to overlay on them using an array of <code>rgblight_segment_t</code> using the <code>RGBLIGHT_LAYER_SEGMENTS</code> macro. We can define multiple layers and enable/disable them independently:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Light LEDs 6 to 9 and 12 to 15 red when caps lock is active. Hard to ignore!</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Light LEDs 9 & 10 in cyan when keyboard layer 1 is active</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Light LEDs 11 & 12 in purple when keyboard layer 2 is active</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Light LEDs 13 & 14 in green when keyboard layer 3 is active</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// etc..</span></span></code></pre></div><p>We combine these layers into an array using the <code>RGBLIGHT_LAYERS_LIST</code> macro, and assign it to the <code>rgblight_layers</code> variable during keyboard setup. Note that you can only define up to 8 lighting layers. Any extra layers will be ignored. Since the different lighting layers overlap, the order matters in the array, with later layers taking precedence:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Now define the array of layers. Later layers take precedence</span></span>
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Note: For split keyboards with two controllers, both sides need to be flashed when updating the contents of rgblight_layers.</p><h3id="enabling-lighting-layers"tabindex="-1">Enabling and disabling lighting layers <aclass="header-anchor"href="#enabling-lighting-layers"aria-label="Permalink to "Enabling and disabling lighting layers {#enabling-lighting-layers}""></a></h3><p>Everything above just configured the definition of each lighting layer. We can now enable and disable the lighting layers whenever the state of the keyboard changes:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">bool</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> led_update_user</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">led_t</span><spanstyle="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> led_state</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3id="lighting-layer-blink"tabindex="-1">Lighting layer blink <aclass="header-anchor"href="#lighting-layer-blink"aria-label="Permalink to "Lighting layer blink {#lighting-layer-blink}""></a></h3><p>By including <code>#define RGBLIGHT_LAYER_BLINK</code> in your <code>config.h</code> file you can turn a lighting layer on for a specified duration. Once the specified number of milliseconds has elapsed the layer will be turned off. This is useful, e.g., if you want to acknowledge some action (e.g. toggling some setting):</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> rgblight_segment_t</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> PROGMEM _yes_layer</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">[]</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> RGBLIGHT_LAYER_SEGMENTS</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">( {</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">9</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">6</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, HSV_GREEN} );</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Note we user post_process_record_user because we want the state</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// after the flag has been flipped...</span></span>
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>You can also use <code>rgblight_blink_layer_repeat</code> to specify the amount of times the layer is supposed to blink. Using the layers from above,</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">void</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> post_process_record_user</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">uint16_t</span><spanstyle="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> keycode</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">keyrecord_t</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><spanstyle="--shiki-light:#E36209;--shiki-dark:#FFAB70;">record</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>would turn the layer 0 (or 1) on and off again three times when <code>DB_TOGG</code> is pressed.</p><p>Blinking accumulates layers so if multiple layers are set blinking at the same time they will all blink for the duration and repeat times of the last layer to be blinked. To stop these other layers from blinking use <code>rgblight_unblink_layer</code> or <code>rgblight_unblink_all_but_layer</code>:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">rgblight_blink_layer</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">500</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">rgblight_blink_layer</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">500</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><divclass="warning custom-block"><pclass="custom-block-title">WARNING</p><p>Lighting layers on split keyboards will require layer state synced to the slave half (e.g. <code>#define SPLIT_LAYER_STATE_ENABLE</code>). See <ahref="./split_keyboard#data-sync-options">data sync options</a> for more details.</p></div><h3id="overriding-rgb-lighting-on-off-status"tabindex="-1">Overriding RGB Lighting on/off status <aclass="header-anchor"href="#overriding-rgb-lighting-on-off-status"aria-label="Permalink to "Overriding RGB Lighting on/off status""></a></h3><p>Normally lighting layers are not shown when RGB Lighting is disabled (e.g. with <code>RGB_TOG</code> keycode). If you would like lighting layers to work even when the RGB Lighting is otherwise off, add <code>#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF</code> to your <code>config.h</code>.</p><h3id="retain-brightness"tabindex="-1">Retain brightness <aclass="header-anchor"href="#retain-brightness"aria-label="Permalink to "Retain brightness""></a></h3><p>Usually lighting layers apply their configured brightness once activated. If you would like lighting layers to retain the currently used brightness (as returned by <code>rgblight_get_val()</code>), add <code>#define RGBLIGHT_LAYERS_RETAIN_VAL</code> to your <code>config.h</code>.</p><h2id="functions"tabindex="-1">Functions <aclass="header-anchor"href="#functions"aria-label="Permalink to "Functions""></a></h2><p>If you need to change your RGB lighting in code, for example in a macro to change the color whenever you switch layers, QMK provides a set of functions to assist you. See <ahref="https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight/rgblight.h"target="_blank"rel="noreferrer"><code>rgblight.h</code></a> for the full list, but the most commonly used functions include:</p><h3id="low-level-functions"tabindex="-1">Low level Functions <aclass="header-anchor"href="#low-level-functions"aria-label="Permalink to "Low level Functions""></a></h3><table><thead><tr><th>Function</th><th>Description</th></tr></thead><tbody><tr><td><code>rgblight_set()</code></td><td>Flush out led buffers to LEDs</td></tr><tr><td><code>rgblight_set_clipping_range(pos, num)</code></td><td>Set clipping Range. see <ahref="#clipping-range">Clipping Range</a></td></tr></tbody></table><h3id="effects-and-animations-functions"tabindex="-1">Effects and Animations Functions <aclass="header-anchor"href="#effects-and-animations-functions"aria-label="Permalink to "Effects and Animations Functions""></a></h3><h4id="effect-range-setting"tabindex="-1">effect range setting <aclass="header-anchor"href="#effect-range-setting"aria-label="Permalink to "effect range setting""></a></h4><table><thead><tr><th>Function</th><th>Description</th></tr></thead><tbody><tr><td><code>rgblight_set_effect_range(pos, num)</code></td><td>Set Effects Range</td></tr></tbody></table><h4id="direct-operation"tabindex="-1">direct operation <aclass="header-anchor"href="#direct-operation"aria-label="Permalink to "direct operation""></a></h4><table><thead><tr><th>Function</th><th>Description</th></tr></thead><tbody><tr><td><code>rgblight_setrgb_at(r, g, b, index)</code></td><td>Set a single LED to the given RGB value, where <code>r</code>/<code>g</code>/<code>b</code> are between 0 and 255 and <code>index</code> is between 0 and <code>RGBLIGHT_LED_COUNT</code> (not written to EEPROM)</td></tr><tr><td><code>rgblight_sethsv_at(h, s, v, index)</code></td><td>Set a single LED to the given HSV value, where <code>
<spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">rgblight_sethsv_at</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(HSV_RED, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // led 1</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">rgblight_sethsv_at</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(HSV_GREEN, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // led 2</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// The above functions automatically calls rgblight_set(), so there is no need to call it explicitly.</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Note that it is inefficient to call repeatedly.</span></span></code></pre></div><h4id="effect-mode-change"tabindex="-1">effect mode change <aclass="header-anchor"href="#effect-mode-change"aria-label="Permalink to "effect mode change""></a></h4><table><thead><tr><th>Function</th><th>Description</th></tr></thead><tbody><tr><td><code>rgblight_mode(x)</code></td><td>Set the mode, if RGB animations are enabled</td></tr><tr><td><code>rgblight_mode_noeeprom(x)</code></td><td>Set the mode, if RGB animations are enabled (not written to EEPROM)</td></tr><tr><td><code>rgblight_step()</code></td><td>Change the mode to the next RGB animation in the list of enabled RGB animations</td></tr><tr><td><code>rgblight_step_noeeprom()</code></td><td>Change the mode to the next RGB animation in the list of enabled RGB animations (not written to EEPROM)</td></tr><tr><td><code>rgblight_step_reverse()</code></td><td>Change the mode to the previous RGB animation in the list of enabled RGB animations</td></tr><tr><td><code>rgblight_step_reverse_noeeprom()</code></td><td>Change the mode to the previous RGB animation in the list of enabled RGB animations (not written to EEPROM)</td></tr><tr><td><code>rgblight_reload_from_eeprom()</code></td><td>Reload the effect configuration (enabled, mode and color) from EEPROM</td></tr></tbody></table><h4id="effects-mode-disable-enable"tabindex="-1">effects mode disable/enable <aclass="header-anchor"href="#effects-mode-disable-enable"aria-label="Permalink to "effects mode disable/enable""></a></h4><table><thead><tr><th>Function</th><th>Description</th></tr></thead><tbody><tr><td><code>rgblight_toggle()</code></td><td>Toggle effect range LEDs between on and off</td></tr><tr><td><code>rgblight_toggle_noeeprom()</code></td><td>Toggle effect range LEDs between on and off (not written to EEPROM)</td></tr><tr><td><code>rgblight_enable()</code></td><td>Turn effect range LEDs on, based on their previous state</td></tr><tr><td><code>rgblight_enable_noeeprom()</code></td><td>Turn effect range LEDs on, based on their previous state (not written to EEPROM)</td></tr><tr><td><code>rgblight_disable()</code></td><td>Turn effect range LEDs off</td></tr><tr><td><code>rgblight_disable_noeeprom()</code></td><td>Turn effect range LEDs off (not written to EEPROM)</td></tr></tbody></table><h4id="hue-sat-val-change"tabindex="-1">hue, sat, val change <aclass="header-anchor"href="#hue-sat-val-change"aria-label="Permalink to "hue, sat, val change""></a></h4><table><thead><tr><th>Function</th><th>Description</th></tr></thead><tbody><tr><td><code>rgblight_increase_hue()</code></td><td>Increase the hue for effect range LEDs. This wraps around at maximum hue</td></tr><tr><td><code>rgblight_increase_hue_noeeprom()</code></td><td>Increase the hue for effect range LEDs. This wraps around at maximum hue (not written to EEPROM)</td></tr><tr><td><code>rgblight_decrease_hue()</code></td><td>Decrease the hue for effect range LEDs. This wraps around at minimum hue</td></tr><tr><td><code>rgblight_decrease_hue_noeeprom()</code></td><td>Decrease the hue for effect range LEDs. This wraps around at minimum hue (not written to EEPROM)</td></tr><tr><td><code>rgblight_increase_sat()</code></td><td>Increase the saturation for effect range LEDs. This stops at maximum saturation</td></tr><tr><td><code>rgblight_increase_sat_noeeprom()</code></td><td>Increase the saturation for effect range LEDs. This stops at maximum saturation (not written to EEPROM)</td></tr><tr><td><code>rgblight_decrease_sat()</code></td><td>Decrease the saturation for effect range LEDs. This stops at minimum saturation</td></tr><tr><td><code>rgblight_decrease_sat_noeeprom()</code></td><td>Decrease the saturation for effect range LEDs. This stops at minimum saturation (not written to EEPROM)</td></tr><tr><td><code>rgblight_increase_val()</code></td><td>Increase the value for effect range LEDs. This stops at maximum value</td></tr><tr><td><code>rgblight_increase_
<spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">rgblight_sethsv_range</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(HSV_WHITE, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">6</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>These are defined in <ahref="https://github.com/qmk/qmk_firmware/blob/master/quantum/color.h"target="_blank"rel="noreferrer"><code>color.h</code></a>. Feel free to add to this list!</p><h2id="changing-the-order-of-the-leds"tabindex="-1">Changing the order of the LEDs <aclass="header-anchor"href="#changing-the-order-of-the-leds"aria-label="Permalink to "Changing the order of the LEDs""></a></h2><p>If you want to make the logical order of LEDs different from the electrical connection order, you can do this by defining the <code>RGBLIGHT_LED_MAP</code> macro in your <code>config.h</code>.</p><p>Normally, the contents of the LED buffer are output to the LEDs in the same order. <imgsrc="https://user-images.githubusercontent.com/2170248/55743718-01866c80-5a6e-11e9-8134-25419928327a.JPG"alt="simple dicrect"width="50%"></p><p>By defining <code>RGBLIGHT_LED_MAP</code> as in the example below, you can specify the LED with addressing in reverse order of the electrical connection order.</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// config.h</span></span>
<spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> RGBLIGHT_LED_MAP</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">3</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span></code></pre></div><imgsrc="https://user-images.githubusercontent.com/2170248/55743725-08ad7a80-5a6e-11e9-83ed-126a2b0209fc.JPG"alt="simple mapped"width="50%"><h2id="clipping-range"tabindex="-1">Clipping Range <aclass="header-anchor"href="#clipping-range"aria-label="Permalink to "Clipping Range""></a></h2><p>Using the <code>rgblight_set_clipping_range()</code> function, you can prepare more buffers than the actual number of LEDs, and output some of the buffers to the LEDs. This is useful if you want the split keyboard to treat left and right LEDs as logically contiguous.</p><p>You can set the Clipping Range by executing the following code.</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// some source</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">rgblight_set_clipping_range</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">3</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">4</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><imgsrc="https://user-images.githubusercontent.com/2170248/55743785-2bd82a00-5a6e-11e9-9d4b-1b4ffaf4932b.JPG"alt="clip direct"width="70%"><p>In addition to setting the Clipping Range, you can use <code>RGBLIGHT_LED_MAP</code> together.</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// config.h</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// some source</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">rgblight_set_clipping_range</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">3</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">4</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><imgsrc="https://user-images.githubusercontent.com/2170248/55743747-119e4c00-5a6e-11e9-91e5-013203ffae8a.JPG"alt="clip mapped"width="70%"><h2id="hardware-modification"tabindex="-1">Hardware Modification <aclass="header-anchor"href="#hardware-modification"aria-label="Permalink to "Hardware Modification""></a></h2><p>If your keyboard lacks onboard underglow LEDs, you may often be able to solder on an RGB LED strip yourself. You will need to find an unused pin to wire to the data pin of your LED strip. Some keyboards may break out unused pins from the MCU to make soldering easier. The other two pins, VCC and GND, must also be connected to the appropriate power pins.</p><h2id="velocikey"tabindex="-1">Velocikey <aclass="header-anchor"href="#velocikey"aria-label="Permalink to "Velocikey""></a></h2><p>Velocikey is a feature that lets you control the speed of lighting effects (like the Rainbow Swirl effect) with the speed of your typing. The faster you type, the faster the lights will go!</p><h3id="usage-1"tabindex="-1">Usage <aclass="header-anchor"href="#usage-1"aria-label="Permalink to "Usage""></a></h3><p>For Velocikey to take effect, there are two steps. First, when compiling your keyboard, you'll need to set <code>VELOCIKEY_ENABLE=yes</code> in <code>rules.mk</code>, e.g.:</p><divclass="language- vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang"></span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><span>MOUSEKEY_ENABLE = no</span></span>
<spanclass="line"><span>VELOCIKEY_ENABLE = yes</span></span></code></pre></div><p>Then, while using your keyboard, you need to also turn it on with the <code>VK_TOGG</code> keycode, which toggles the feature on and off.</p><p>The following light effects will all be controlled by Velocikey when it is enabled:</p><ul><li>RGB Breathing</li><li>RGB Rainbow Mood</li><li>RGB Rainbow Swirl</li><li>RGB Snake</li><li>RGB Knight</li></ul><p>Support for LED breathing effects is planned but not available yet.</p><p>As long as Velocikey is enabled, it will control the speed regardless of any other speed setting that your RGB lights are currently on.</p><h3id="configuration-1"tabindex="-1">Configuration <aclass="header-anchor"href="#configuration-1"aria-label="Permalink to "Configuration""></a></h3><p>Velocikey doesn't currently support any configuration via keyboard settings. If you want to adjust something like the speed increase or decay rate, you would need to edit <code>velocikey.c</code> and adjust the values there to achieve the kinds of speeds that you like.</p></div></div></main><footerclass="VPDocFooter"data-v-39a288b8data-v-09de1c0f><!--[--><!--]--><!----><navclass="prev-next"data-v-09de1c0f><divclass="pager"data-v-09de1c0f><aclass="VPLink link pager-link prev"href="/features/led_matrix"data-v-09de1c0f><!--[--><spanclass="desc"data-v-09de1c0f>Previous page</span><spanclass="title"data-v-09de1c0f>LED Matrix</span><!--]--></a></div><divclass="pager"data-v-09de1c0f><aclass="VPLink link pager-link next"href="/features/rgb_matrix"data-v-09de1c0f><!--[--><spanclass="desc"data-v-09de1c0f>Next page</span><spanclass="title"data-v-09de1c0f>RGB Matrix</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
