diff options
Diffstat (limited to 'docs/custom_quantum_functions.md')
| -rw-r--r-- | docs/custom_quantum_functions.md | 45 | 
1 files changed, 37 insertions, 8 deletions
| diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index 5b95450f26..d44786e2d5 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -90,7 +90,7 @@ keyrecord_t record {  # LED Control -This allows you to control the 5 LED's defined as part of the USB Keyboard spec. It will be called when the state of one of those 5 LEDs changes. +QMK provides methods to read the 5 LEDs defined as part of the HID spec:  * `USB_LED_NUM_LOCK`  * `USB_LED_CAPS_LOCK` @@ -98,31 +98,44 @@ This allows you to control the 5 LED's defined as part of the USB Keyboard spec.  * `USB_LED_COMPOSE`  * `USB_LED_KANA` +These five constants correspond to the positional bits of the host LED state. +There are two ways to get the host LED state: + +* by implementing `led_set_user()` +* by calling `host_keyboard_leds()` + +## `led_set_user()` + +This function will be called when the state of one of those 5 LEDs changes. It receives the LED state as a parameter. +Use the `IS_LED_ON(usb_led, led_name)` and `IS_LED_OFF(usb_led, led_name)` macros to check the LED status. + +!> `host_keyboard_leds()` may already reflect a new value before `led_set_user()` is called. +  ### Example `led_set_user()` Implementation  ```c  void led_set_user(uint8_t usb_led) { -    if (usb_led & (1<<USB_LED_NUM_LOCK)) { +    if (IS_LED_ON(usb_led, USB_LED_NUM_LOCK)) {          PORTB |= (1<<0);      } else {          PORTB &= ~(1<<0);      } -    if (usb_led & (1<<USB_LED_CAPS_LOCK)) { +    if (IS_LED_ON(usb_led, USB_LED_CAPS_LOCK)) {          PORTB |= (1<<1);      } else {          PORTB &= ~(1<<1);      } -    if (usb_led & (1<<USB_LED_SCROLL_LOCK)) { +    if (IS_LED_ON(usb_led, USB_LED_SCROLL_LOCK)) {          PORTB |= (1<<2);      } else {          PORTB &= ~(1<<2);      } -    if (usb_led & (1<<USB_LED_COMPOSE)) { +    if (IS_LED_ON(usb_led, USB_LED_COMPOSE)) {          PORTB |= (1<<3);      } else {          PORTB &= ~(1<<3);      } -    if (usb_led & (1<<USB_LED_KANA)) { +    if (IS_LED_ON(usb_led, USB_LED_KANA)) {          PORTB |= (1<<4);      } else {          PORTB &= ~(1<<4); @@ -135,10 +148,26 @@ void led_set_user(uint8_t usb_led) {  * Keyboard/Revision: `void led_set_kb(uint8_t usb_led)`  * Keymap: `void led_set_user(uint8_t usb_led)` +## `host_keyboard_leds()` + +Call this function to get the last received LED state. This is useful for reading the LED state outside `led_set_*`, e.g. in [`matrix_scan_user()`](#matrix-scanning-code). +For convenience, you can use the `IS_HOST_LED_ON(led_name)` and `IS_HOST_LED_OFF(led_name)` macros instead of calling and checking `host_keyboard_leds()` directly. + +## 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).  # Matrix Initialization Code -Before a keyboard can be used the hardware must be initialized. QMK handles initialization of the keyboard matrix itself, but if you have other hardware like LED's or i²c controllers you will need to set up that hardware before it can be used. +Before a keyboard can be used the hardware must be initialized. QMK handles initialization of the keyboard matrix itself, but if you have other hardware like LEDs or i²c controllers you will need to set up that hardware before it can be used.  ### Example `matrix_init_user()` Implementation @@ -176,7 +205,7 @@ This example has been deliberately omitted. You should understand enough about Q  This function gets called at every matrix scan, which is basically as often as the MCU can handle. Be careful what you put here, as it will get run a lot. -You should use this function if you need custom matrix scanning code. It can also be used for custom status output (such as LED's or a display) or other functionality that you want to trigger regularly even when the user isn't typing. +You should use this function if you need custom matrix scanning code. It can also be used for custom status output (such as LEDs or a display) or other functionality that you want to trigger regularly even when the user isn't typing.  # Keyboard Idling/Wake Code | 
