16 lines
16 KiB
JavaScript
16 lines
16 KiB
JavaScript
import { _ as _export_sfc, c as createElementBlock, o as openBlock, a8 as createStaticVNode } from "./chunks/framework.B9AX-CPi.js";
|
||
const __pageData = JSON.parse('{"title":"LED Indicators","description":"","frontmatter":{},"headers":[],"relativePath":"features/led_indicators.md","filePath":"features/led_indicators.md","lastUpdated":null}');
|
||
const _sfc_main = { name: "features/led_indicators.md" };
|
||
const _hoisted_1 = /* @__PURE__ */ createStaticVNode('<h1 id="led-indicators" tabindex="-1">LED Indicators <a class="header-anchor" href="#led-indicators" aria-label="Permalink to "LED Indicators""></a></h1><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>LED indicators on split keyboards will require state information synced to the slave half (e.g. <code>#define SPLIT_LED_STATE_ENABLE</code>). See <a href="./split_keyboard#data-sync-options">data sync options</a> for more details.</p></div><p>QMK provides methods to read 5 of the LEDs defined in the HID spec:</p><ul><li>Num Lock</li><li>Caps Lock</li><li>Scroll Lock</li><li>Compose</li><li>Kana</li></ul><p>There are three ways to get the lock LED state:</p><ul><li>Configuration options in <code>config.h</code></li><li>Implement <code>led_update_*</code> function</li><li>Call <code>led_t host_keyboard_led_state()</code></li></ul><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>The <code>host_keyboard_led_state()</code> may reflect an updated state before <code>led_update_user()</code> is called.</p></div><p>Deprecated functions that provide the LED state as <code>uint8_t</code>:</p><ul><li><code>uint8_t host_keyboard_leds()</code></li></ul><h2 id="configuration-options" tabindex="-1">Configuration Options <a class="header-anchor" href="#configuration-options" aria-label="Permalink to "Configuration Options""></a></h2><p>To configure the indicators, <code>#define</code> these in your <code>config.h</code>:</p><table><thead><tr><th>Define</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><code>LED_NUM_LOCK_PIN</code></td><td><em>Not defined</em></td><td>The pin that controls the <code>Num Lock</code> LED</td></tr><tr><td><code>LED_CAPS_LOCK_PIN</code></td><td><em>Not defined</em></td><td>The pin that controls the <code>Caps Lock</code> LED</td></tr><tr><td><code>LED_SCROLL_LOCK_PIN</code></td><td><em>Not defined</em></td><td>The pin that controls the <code>Scroll Lock</code> LED</td></tr><tr><td><code>LED_COMPOSE_PIN</code></td><td><em>Not defined</em></td><td>The pin that controls the <code>Compose</code> LED</td></tr><tr><td><code>LED_KANA_PIN</code></td><td><em>Not defined</em></td><td>The pin that controls the <code>Kana</code> LED</td></tr><tr><td><code>LED_PIN_ON_STATE</code></td><td><code>1</code></td><td>The state of the indicator pins when the LED is "on" - <code>1</code> for high, <code>0</code> for low</td></tr></tbody></table><p>Unless you are designing your own keyboard, you generally should not need to change the above config options.</p><h2 id="led-update-function" tabindex="-1">LED update function <a class="header-anchor" href="#led-update-function" aria-label="Permalink to "LED update function""></a></h2><p>When the configuration options do not provide enough flexibility, the following callbacks allow custom control of the LED behavior. These functions will be called when one of those 5 LEDs changes state:</p><ul><li>Keyboard/revision: <code>bool led_update_kb(led_t led_state)</code></li><li>Keymap: <code>bool led_update_user(led_t led_state)</code></li></ul><p>Both receives LED state as a struct parameter. Returning <code>true</code> in <code>led_update_user()</code> will allow the keyboard level code in <code>led_update_kb()</code> to run as well. Returning <code>false</code> will override the keyboard level code, depending on how the keyboard level function is set up.</p><h3 id="example-of-keyboard-led-update-implementation" tabindex="-1">Example of keyboard LED update implementation <a class="header-anchor" href="#example-of-keyboard-led-update-implementation" aria-label="Permalink to "Example of keyboard LED update implementation""></a></h3><p>This is a template indicator function that can be implemented on keyboard level code:</p><div class="language-c vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">c</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">bool</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> led_update_kb</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">led_t</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> led_state</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> bool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> res </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> led_update_user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(led_state);</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(res) {</span></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // gpio_write_pin sets the pin high for 1 and low for 0.</span></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // In this example the pins are inverted, setting</span></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // it low/0 turns it on, and high/1 turns the LED off.</span></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // This behavior depends on whether the LED is between the pin</span></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // and VCC or the pin and GND.</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> gpio_write_pin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(B0, </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">led_state.num_lock);</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> gpio_write_pin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(B1, </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">led_state.caps_lock);</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> gpio_write_pin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(B2, </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">led_state.scroll_lock);</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> gpio_write_pin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(B3, </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">led_state.compose);</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> gpio_write_pin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(B4, </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">led_state.kana);</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> res;</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="example-of-user-led-update-implementation" tabindex="-1">Example of user LED update implementation <a class="header-anchor" href="#example-of-user-led-update-implementation" aria-label="Permalink to "Example of user LED update implementation""></a></h3><p>This is an incomplete example will play a sound if Caps Lock is turned on or off. It returns <code>true</code> to allow keyboard LED function to maintain their state.</p><div class="language-c vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">c</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">#ifdef</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> AUDIO_ENABLE</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> float</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> caps_on</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">[]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> SONG</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(CAPS_LOCK_ON_SOUND);</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> float</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> caps_off</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">[]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> SONG</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(CAPS_LOCK_OFF_SOUND);</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">#endif</span></span>\n<span class="line"></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">bool</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> led_update_user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">led_t</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> led_state</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> #ifdef</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> AUDIO_ENABLE</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> static</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> uint8_t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> caps_state </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 0</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (caps_state </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> led_state.caps_lock) {</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> led_state.caps_lock </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> PLAY_SONG</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(caps_on) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> PLAY_SONG</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(caps_off);</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> caps_state </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> led_state.caps_lock;</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> #endif</span></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h2 id="host-keyboard-led-state" tabindex="-1">Host keyboard LED state <a class="header-anchor" href="#host-keyboard-led-state" aria-label="Permalink to "Host keyboard LED state""></a></h2><p>The <code>host_keyboard_led_state()</code> function will report the LED state returned from the host computer as <code>led_t</code>. This is useful for reading the LED state outside <code>led_update_*</code>. For example, you can get the boolean state of Caps Lock from the host with:</p><div class="language-c vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">c</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">bool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> caps </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> host_keyboard_led_state</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().caps_lock;</span></span></code></pre></div><h2 id="led-update-ports" tabindex="-1"><code>led_update_ports()</code> <a class="header-anchor" href="#led-update-ports" aria-label="Permalink to "`led_update_ports()`""></a></h2><p>This function writes the LED state to the actual hardware. Call it manually from your <code>led_update_*()</code> callbacks to modify the handling of the standard keyboard LEDs. For example when repurposing a standard LED indicator as layer indicator.</p><h2 id="setting-physical-led-state" tabindex="-1">Setting Physical LED State <a class="header-anchor" href="#setting-physical-led-state" aria-label="Permalink to "Setting Physical LED State""></a></h2><p>Some keyboard implementations provide convenient methods for setting the state of the physical LEDs.</p><h3 id="ergodox-boards" tabindex="-1">Ergodox Boards <a class="header-anchor" href="#ergodox-boards" aria-label="Permalink to "Ergodox Boards""></a></h3><p>The Ergodox implementations provide <code>ergodox_right_led_1</code>/<code>2</code>/<code>3_on</code>/<code>off()</code> to turn individual LEDs on or off, as well as <code>ergodox_right_led_on</code>/<code>off(uint8_t led)</code> to turn them on or off by their index.</p><p>In addition, it is possible to specify the brightness level of all LEDs with <code>ergodox_led_all_set(uint8_t n)</code>; of individual LEDs with <code>ergodox_right_led_1</code>/<code>2</code>/<code>3_set(uint8_t n)</code>; or by index with <code>ergodox_right_led_set(uint8_t led, uint8_t n)</code>.</p><p>Ergodox boards also define <code>LED_BRIGHTNESS_LO</code> for the lowest brightness and <code>LED_BRIGHTNESS_HI</code> for the highest brightness (which is the default).</p>', 34);
|
||
const _hoisted_35 = [
|
||
_hoisted_1
|
||
];
|
||
function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
|
||
return openBlock(), createElementBlock("div", null, _hoisted_35);
|
||
}
|
||
const led_indicators = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]);
|
||
export {
|
||
__pageData,
|
||
led_indicators as default
|
||
};
|