From 1ff5ee255fadcd6bfc4defb68ef097d67ebd40ad Mon Sep 17 00:00:00 2001 From: Joel Challis Date: Sun, 8 Nov 2020 22:31:16 +0000 Subject: Indicator LEDs as config (#10816) * First pass * Add config options to docs * Update some wording * Slight tidy up of backlight caps logic * Init pin to correct state * Move init location * Reverse default state --- docs/custom_quantum_functions.md | 102 --------------------------------------- 1 file changed, 102 deletions(-) (limited to 'docs/custom_quantum_functions.md') diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index bf3a60377c..a459042b32 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -88,108 +88,6 @@ keyrecord_t record { } ``` -# LED Control - -QMK provides methods to read 5 of the LEDs defined in the HID spec: - -* Num Lock -* Caps Lock -* Scroll Lock -* Compose -* Kana - -There are two ways to get the lock LED state: - -* by implementing `bool led_update_kb(led_t led_state)` or `_user(led_t led_state)`; or -* by calling `led_t host_keyboard_led_state()` - -!> `host_keyboard_led_state()` may already reflect a new value before `led_update_user()` is called. - -Two more deprecated functions exist that provide the LED state as a `uint8_t`: - -* `uint8_t led_set_kb(uint8_t usb_led)` and `_user(uint8_t usb_led)` -* `uint8_t host_keyboard_leds()` - -## `led_update_user()` - -This function will be called when the state of one of those 5 LEDs changes. It receives the LED state as a struct parameter. - -By convention, return `true` from `led_update_user()` to get the `led_update_kb()` hook to run its code, and -return `false` when you would prefer not to run the code in `led_update_kb()`. - -Some examples include: - - - overriding the LEDs to use them for something else like layer indication - - return `false` because you do not want the `_kb()` function to run, as it would override your layer behavior. - - play a sound when an LED turns on or off. - - return `true` because you want the `_kb` function to run, and this is in addition to the default LED behavior. - -?> Because the `led_set_*` functions return `void` instead of `bool`, they do not allow for overriding the keyboard LED control, and thus it's recommended to use `led_update_*` instead. - -### Example `led_update_kb()` Implementation - -```c -bool led_update_kb(led_t led_state) { - bool res = led_update_user(led_state); - if(res) { - // writePin sets the pin high for 1 and low for 0. - // In this example the pins are inverted, setting - // it low/0 turns it on, and high/1 turns the LED off. - // This behavior depends on whether the LED is between the pin - // and VCC or the pin and GND. - writePin(B0, !led_state.num_lock); - writePin(B1, !led_state.caps_lock); - writePin(B2, !led_state.scroll_lock); - writePin(B3, !led_state.compose); - writePin(B4, !led_state.kana); - } - return res; -} -``` - -### Example `led_update_user()` Implementation - -This incomplete example would play a sound if Caps Lock is turned on or off. It returns `true`, because you also want the LEDs to maintain their state. - -```c -#ifdef AUDIO_ENABLE - float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND); - float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND); -#endif - -bool led_update_user(led_t led_state) { - #ifdef AUDIO_ENABLE - static uint8_t caps_state = 0; - if (caps_state != led_state.caps_lock) { - led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off); - caps_state = led_state.caps_lock; - } - #endif - return true; -} -``` - -### `led_update_*` Function Documentation - -* Keyboard/Revision: `bool led_update_kb(led_t led_state)` -* Keymap: `bool led_update_user(led_t led_state)` - -## `host_keyboard_led_state()` - -Call this function to get the last received LED state as a `led_t`. This is useful for reading the LED state outside `led_update_*`, e.g. in [`matrix_scan_user()`](#matrix-scanning-code). - -## Setting Physical LED State - -Some keyboard implementations provide convenience methods for setting the state of the physical LEDs. - -### Ergodox Boards - -The Ergodox implementations provide `ergodox_right_led_1`/`2`/`3_on`/`off()` to turn individual LEDs on or off, as well as `ergodox_right_led_on`/`off(uint8_t led)` to turn them on or off by their index. - -In addition, it is possible to specify the brightness level of all LEDs with `ergodox_led_all_set(uint8_t n)`; of individual LEDs with `ergodox_right_led_1`/`2`/`3_set(uint8_t n)`; or by index with `ergodox_right_led_set(uint8_t led, uint8_t n)`. - -Ergodox boards also define `LED_BRIGHTNESS_LO` for the lowest brightness and `LED_BRIGHTNESS_HI` for the highest brightness (which is the default). - # Keyboard Initialization Code There are several steps in the keyboard initialization process. Depending on what you want to do, it will influence which function you should use. -- cgit v1.2.3