From 5966b4e49f1b449da7bc90c5fd8fe6a24a795191 Mon Sep 17 00:00:00 2001 From: Alessandro Bortolin Date: Tue, 6 Sep 2022 12:29:07 +0000 Subject: [PATCH] docs: add LED indicators documentation --- docs/docs/features/led-indicators.md | 183 +++++++++++++++++++++++++++ docs/sidebars.js | 1 + 2 files changed, 184 insertions(+) create mode 100644 docs/docs/features/led-indicators.md diff --git a/docs/docs/features/led-indicators.md b/docs/docs/features/led-indicators.md new file mode 100644 index 00000000..1aa167fd --- /dev/null +++ b/docs/docs/features/led-indicators.md @@ -0,0 +1,183 @@ +--- +title: LED indicators +sidebar_label: LED indicators +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +ZMK supports the following LED indicators: + +- Num Lock +- Caps Lock +- Scroll Lock +- Compose +- Kana + +## Enabling LED indicators + +To enable LED indicators on your board or shield, simply enable the `CONFIG_ZMK_LED_INDICATORS` configuration values in the `.conf` file of your user config directory as such: + +``` +CONFIG_ZMK_LED_INDICATORS=y +``` + +You can also configure the brightness of the LEDs using: + +``` +CONFIG_ZMK_LED_INDICATORS_BRT=80 +``` + +If your board or shield does not have LED indicators configured, refer to [Adding LED indicators to a Board](#adding-led-indicators-to-a-board). + +## Adding LED indicators to a board + +You can use any LED driver supported by ZMK or Zephyr, it is recommended to use either `LED PWM` or `LED GPIO` driver. + + + + +First you have to enable the driver by adding the following lines to your `.conf` file: + +``` +CONFIG_PWM=y +CONFIG_LED_PWM=y +``` + +Next, you need to enable PWM by adding the following lines to your `.overlay` or `.dts` file: + +``` +&pwm0 { + status = "okay"; + ch0-pin = <33>; + /* ch0-inverted; */ + ch1-pin = <35>; + /* ch1-inverted; */ +}; +``` + +You have to declare a channel for each LED. A single PWM module has a fixed number of channels depending on your SoC, if you have many LEDs you may want to use `&pwm1` or ` &pwm2` as well. + +The value `chX-pin` represents the pin that controls the LEDs. With nRF52 boards, you can calculate the value to use in the following way: you need the hardware port and run it through a function. +**32 \* X + Y** = `` where X is first part of the hardware port "PX.01" and Y is the second part of the hardware port "P1.Y". + +For example, _P1.13_ would give you _32 \* 1 + 13_ = `<45>` and _P0.15_ would give you _32 \* 0 + 15_ = `<15>`. + +If you need to invert the signal, you may want to enable `chX-inverted`. + +Then you have to add the following lines to your `.overlay` or `.dts` file inside the root devicetree node: + +``` +/ { + led_indicators { + compatible = "pwm-leds"; + label = "LED indicators"; + led_capslock: led_capslock { + pwms = <&pwm0 33>; + label = "Caps lock LED"; + }; + led_numlock: led_numlock { + pwms = <&pwm0 35>; + label = "Num lock LED"; + }; + }; +}; +``` + +The value inside `pwms` must be the same as you used before. + +Finally you need to add each indicator to the `chosen` element of the root devicetree node: + +``` +chosen { + ... + zmk,led-capslock = &led_capslock; + zmk,led-numlock = &led_numlock; +}; +``` + +Currently, the supported indicators are: + +- Num Lock: `zmk,led-numlock` +- Caps Lock: `zmk,led-capslock` +- Scroll Lock: `zmk,led-scrolllock` +- Compose: `zmk,led-compose` +- Kana: `zmk,led-kana` + + + + +First you have to enable the driver by adding the following lines to your `.conf` file: + +``` +CONFIG_LED_GPIO=y +``` + +Next you have to add the following lines to your `.overlay` or `.dts` file inside the root devicetree node: + +``` +/ { + led_indicators { + compatible = "gpio-leds"; + label = "LED indicators"; + led_capslock: led_capslock { + gpios = <&gpio1 1 GPIO_ACTIVE_HIGH>; + label = "Caps lock LED"; + }; + led_numlock: led_numlock { + gpios = <&gpio1 3 GPIO_ACTIVE_HIGH>; + label = "Num lock LED"; + }; + }; +}; +``` + +Finally you need to add each indicator to the `chosen` element of the root devicetree node: + +``` +chosen { + ... + zmk,led-capslock = &led_capslock; + zmk,led-numlock = &led_numlock; +}; +``` + +Currently, the supported indicators are: + +- Num Lock: `zmk,led-numlock` +- Caps Lock: `zmk,led-capslock` +- Scroll Lock: `zmk,led-scrolllock` +- Compose: `zmk,led-compose` +- Kana: `zmk,led-kana` + + + + +If you have any other driver or you want to implement custom behaviors, such as a display widget, you can write a listener that implements the behavior you want, for example: + +```c +#include + +static int led_indicators_listener(const zmk_event_t *eh) { + const struct zmk_keycode_state_changed *ev = as_zmk_led_indicator_changed(eh); + zmk_led_indicators_flags_t leds = ev->leds; + + if (leds & ZMK_LED_CAPSLOCK_BIT) { + // do something + } + + return ZMK_EV_EVENT_BUBBLE; +} + +static ZMK_LISTENER(led_indicators_listener, led_indicators_listener); +static ZMK_SUBSCRIPTION(led_indicators_listener, zmk_led_indicator_changed); +``` + + + diff --git a/docs/sidebars.js b/docs/sidebars.js index 7b445a29..28a26311 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -17,6 +17,7 @@ module.exports = { "features/encoders", "features/underglow", "features/backlight", + "features/led-indicators", "features/battery", "features/beta-testing", ],