diff options
Diffstat (limited to 'docs/custom_quantum_functions.md')
| -rw-r--r-- | docs/custom_quantum_functions.md | 102 |
1 files changed, 0 insertions, 102 deletions
diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index bf3a60377..a459042b3 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md | |||
| @@ -88,108 +88,6 @@ keyrecord_t record { | |||
| 88 | } | 88 | } |
| 89 | ``` | 89 | ``` |
| 90 | 90 | ||
| 91 | # LED Control | ||
| 92 | |||
| 93 | QMK provides methods to read 5 of the LEDs defined in the HID spec: | ||
| 94 | |||
| 95 | * Num Lock | ||
| 96 | * Caps Lock | ||
| 97 | * Scroll Lock | ||
| 98 | * Compose | ||
| 99 | * Kana | ||
| 100 | |||
| 101 | There are two ways to get the lock LED state: | ||
| 102 | |||
| 103 | * by implementing `bool led_update_kb(led_t led_state)` or `_user(led_t led_state)`; or | ||
| 104 | * by calling `led_t host_keyboard_led_state()` | ||
| 105 | |||
| 106 | !> `host_keyboard_led_state()` may already reflect a new value before `led_update_user()` is called. | ||
| 107 | |||
| 108 | Two more deprecated functions exist that provide the LED state as a `uint8_t`: | ||
| 109 | |||
| 110 | * `uint8_t led_set_kb(uint8_t usb_led)` and `_user(uint8_t usb_led)` | ||
| 111 | * `uint8_t host_keyboard_leds()` | ||
| 112 | |||
| 113 | ## `led_update_user()` | ||
| 114 | |||
| 115 | This function will be called when the state of one of those 5 LEDs changes. It receives the LED state as a struct parameter. | ||
| 116 | |||
| 117 | By convention, return `true` from `led_update_user()` to get the `led_update_kb()` hook to run its code, and | ||
| 118 | return `false` when you would prefer not to run the code in `led_update_kb()`. | ||
| 119 | |||
| 120 | Some examples include: | ||
| 121 | |||
| 122 | - overriding the LEDs to use them for something else like layer indication | ||
| 123 | - return `false` because you do not want the `_kb()` function to run, as it would override your layer behavior. | ||
| 124 | - play a sound when an LED turns on or off. | ||
| 125 | - return `true` because you want the `_kb` function to run, and this is in addition to the default LED behavior. | ||
| 126 | |||
| 127 | ?> 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. | ||
| 128 | |||
| 129 | ### Example `led_update_kb()` Implementation | ||
| 130 | |||
| 131 | ```c | ||
| 132 | bool led_update_kb(led_t led_state) { | ||
| 133 | bool res = led_update_user(led_state); | ||
| 134 | if(res) { | ||
| 135 | // writePin sets the pin high for 1 and low for 0. | ||
| 136 | // In this example the pins are inverted, setting | ||
| 137 | // it low/0 turns it on, and high/1 turns the LED off. | ||
| 138 | // This behavior depends on whether the LED is between the pin | ||
| 139 | // and VCC or the pin and GND. | ||
| 140 | writePin(B0, !led_state.num_lock); | ||
| 141 | writePin(B1, !led_state.caps_lock); | ||
| 142 | writePin(B2, !led_state.scroll_lock); | ||
| 143 | writePin(B3, !led_state.compose); | ||
| 144 | writePin(B4, !led_state.kana); | ||
| 145 | } | ||
| 146 | return res; | ||
| 147 | } | ||
| 148 | ``` | ||
| 149 | |||
| 150 | ### Example `led_update_user()` Implementation | ||
| 151 | |||
| 152 | 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. | ||
| 153 | |||
| 154 | ```c | ||
| 155 | #ifdef AUDIO_ENABLE | ||
| 156 | float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND); | ||
| 157 | float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND); | ||
| 158 | #endif | ||
| 159 | |||
| 160 | bool led_update_user(led_t led_state) { | ||
| 161 | #ifdef AUDIO_ENABLE | ||
| 162 | static uint8_t caps_state = 0; | ||
| 163 | if (caps_state != led_state.caps_lock) { | ||
| 164 | led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off); | ||
| 165 | caps_state = led_state.caps_lock; | ||
| 166 | } | ||
| 167 | #endif | ||
| 168 | return true; | ||
| 169 | } | ||
| 170 | ``` | ||
| 171 | |||
| 172 | ### `led_update_*` Function Documentation | ||
| 173 | |||
| 174 | * Keyboard/Revision: `bool led_update_kb(led_t led_state)` | ||
| 175 | * Keymap: `bool led_update_user(led_t led_state)` | ||
| 176 | |||
| 177 | ## `host_keyboard_led_state()` | ||
| 178 | |||
| 179 | 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). | ||
| 180 | |||
| 181 | ## Setting Physical LED State | ||
| 182 | |||
| 183 | Some keyboard implementations provide convenience methods for setting the state of the physical LEDs. | ||
| 184 | |||
| 185 | ### Ergodox Boards | ||
| 186 | |||
| 187 | 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. | ||
| 188 | |||
| 189 | 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)`. | ||
| 190 | |||
| 191 | Ergodox boards also define `LED_BRIGHTNESS_LO` for the lowest brightness and `LED_BRIGHTNESS_HI` for the highest brightness (which is the default). | ||
| 192 | |||
| 193 | # Keyboard Initialization Code | 91 | # Keyboard Initialization Code |
| 194 | 92 | ||
| 195 | There are several steps in the keyboard initialization process. Depending on what you want to do, it will influence which function you should use. | 93 | There are several steps in the keyboard initialization process. Depending on what you want to do, it will influence which function you should use. |
