Merge PR#999 (LED indicators)

app/CMakeLists.txt

@@ -37,6 +37,8 @@ target_sources(app PRIVATE src/behaviors/behavior_reset.c)
 target_sources_ifdef(CONFIG_ZMK_EXT_POWER app PRIVATE src/behaviors/behavior_ext_power.c)
 if ((NOT CONFIG_ZMK_SPLIT) OR CONFIG_ZMK_SPLIT_ROLE_CENTRAL)
   target_sources(app PRIVATE src/hid.c)
+  target_sources_ifdef(CONFIG_ZMK_USB app PRIVATE src/usb_hid.c)
+  
   target_sources(app PRIVATE src/behaviors/behavior_key_press.c)
   target_sources_ifdef(CONFIG_ZMK_BEHAVIOR_KEY_TOGGLE app PRIVATE src/behaviors/behavior_key_toggle.c)
   target_sources(app PRIVATE src/behaviors/behavior_hold_tap.c)
@@ -63,6 +65,7 @@ if ((NOT CONFIG_ZMK_SPLIT) OR CONFIG_ZMK_SPLIT_ROLE_CENTRAL)
   target_sources(app PRIVATE src/events/layer_state_changed.c)
   target_sources(app PRIVATE src/events/modifiers_state_changed.c)
   target_sources(app PRIVATE src/events/keycode_state_changed.c)
+  target_sources(app PRIVATE src/led_indicators_generic.c)
 
   if (CONFIG_ZMK_BLE)
     target_sources(app PRIVATE src/events/ble_active_profile_changed.c)
@@ -85,11 +88,13 @@ target_sources_ifdef(CONFIG_ZMK_BACKLIGHT app PRIVATE src/behaviors/behavior_bac
 
 target_sources_ifdef(CONFIG_ZMK_BLE app PRIVATE src/events/battery_state_changed.c)
 
+target_sources(app PRIVATE src/events/led_indicator_changed.c)
+target_sources_ifdef(CONFIG_ZMK_LED_INDICATORS app PRIVATE src/led_indicators.c)
+
 target_sources_ifdef(CONFIG_ZMK_SPLIT app PRIVATE src/events/split_peripheral_status_changed.c)
 add_subdirectory(src/split)
 
 target_sources_ifdef(CONFIG_USB_DEVICE_STACK app PRIVATE src/usb.c)
-target_sources_ifdef(CONFIG_ZMK_USB app PRIVATE src/usb_hid.c)
 target_sources_ifdef(CONFIG_ZMK_RGB_UNDERGLOW app PRIVATE src/rgb_underglow.c)
 target_sources_ifdef(CONFIG_ZMK_BACKLIGHT app PRIVATE src/backlight.c)
 target_sources(app PRIVATE src/main.c)

app/Kconfig

@@ -294,6 +294,20 @@ config ZMK_BACKLIGHT_AUTO_OFF_USB
 #ZMK_BACKLIGHT
 endif
 
+menuconfig ZMK_LED_INDICATORS
+	bool "LED indicators"
+	select LED
+
+if ZMK_LED_INDICATORS
+
+config ZMK_LED_INDICATORS_BRT
+	int "Brightness in percent"
+	range 1 100
+	default 80
+
+#ZMK_LED_INDICATORS
+endif
+
 #Display/LED Options
 endmenu
 

app/include/zmk/ble.h

@@ -26,6 +26,7 @@ int zmk_ble_prof_prev();
 int zmk_ble_prof_select(uint8_t index);
 
 int zmk_ble_active_profile_index();
+int zmk_ble_profile_index(const bt_addr_le_t *addr);
 bt_addr_le_t *zmk_ble_active_profile_addr();
 bool zmk_ble_active_profile_is_open();
 bool zmk_ble_active_profile_is_connected();

app/include/zmk/events/led_indicator_changed.h

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) 2022 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#pragma once
+
+#include <zmk/led_indicators_types.h>
+#include <zmk/event_manager.h>
+
+struct zmk_led_changed {
+    zmk_leds_flags_t leds;
+};
+
+ZMK_EVENT_DECLARE(zmk_led_changed);

app/include/zmk/hid.h

@@ -17,11 +17,15 @@
 
 #define COLLECTION_REPORT 0x03
 
+#define HID_REPORT_ID_KEYBOARD 0x01
+#define HID_REPORT_ID_LEDS 0x01
+#define HID_REPORT_ID_CONSUMER 0x02
+
 static const uint8_t zmk_hid_report_desc[] = {
     HID_USAGE_PAGE(HID_USAGE_GEN_DESKTOP),
     HID_USAGE(HID_USAGE_GD_KEYBOARD),
     HID_COLLECTION(HID_COLLECTION_APPLICATION),
-    HID_REPORT_ID(0x01),
+    HID_REPORT_ID(HID_REPORT_ID_KEYBOARD),
     HID_USAGE_PAGE(HID_USAGE_KEY),
     HID_USAGE_MIN8(HID_USAGE_KEY_KEYBOARD_LEFTCONTROL),
     HID_USAGE_MAX8(HID_USAGE_KEY_KEYBOARD_RIGHT_GUI),
@@ -39,6 +43,20 @@ static const uint8_t zmk_hid_report_desc[] = {
     /* INPUT (Cnst,Var,Abs) */
     HID_INPUT(0x03),
 
+    HID_USAGE_PAGE(HID_USAGE_LED),
+    HID_USAGE_MIN8(HID_USAGE_LED_NUM_LOCK),
+    HID_USAGE_MAX8(HID_USAGE_LED_KANA),
+    HID_REPORT_SIZE(0x01),
+    HID_REPORT_COUNT(0x05),
+    /* OUTPUT (Data,Var,Abs) */
+    HID_OUTPUT(0x02),
+
+    HID_USAGE_PAGE(HID_USAGE_LED),
+    HID_REPORT_SIZE(0x03),
+    HID_REPORT_COUNT(0x01),
+    /* OUTPUT (Cnst,Var,Abs) */
+    HID_OUTPUT(0x03),
+
     HID_USAGE_PAGE(HID_USAGE_KEY),
 
 #if IS_ENABLED(CONFIG_ZMK_HID_REPORT_TYPE_NKRO)
@@ -67,7 +85,7 @@ static const uint8_t zmk_hid_report_desc[] = {
     HID_USAGE_PAGE(HID_USAGE_CONSUMER),
     HID_USAGE(HID_USAGE_CONSUMER_CONSUMER_CONTROL),
     HID_COLLECTION(HID_COLLECTION_APPLICATION),
-    HID_REPORT_ID(0x02),
+    HID_REPORT_ID(HID_REPORT_ID_CONSUMER),
     HID_USAGE_PAGE(HID_USAGE_CONSUMER),
 
 #if IS_ENABLED(CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_BASIC)
@@ -113,6 +131,15 @@ struct zmk_hid_keyboard_report {
     struct zmk_hid_keyboard_report_body body;
 } __packed;
 
+struct zmk_hid_led_report_body {
+    uint8_t leds;
+} __packed;
+
+struct zmk_hid_led_report {
+    uint8_t report_id;
+    struct zmk_hid_led_report_body body;
+} __packed;
+
 struct zmk_hid_consumer_report_body {
 #if IS_ENABLED(CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_BASIC)
     uint8_t keys[CONFIG_ZMK_HID_CONSUMER_REPORT_SIZE];

app/include/zmk/led_indicators.h

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2022 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#pragma once
+
+#include <zmk/endpoints_types.h>
+#include <zmk/hid.h>
+#include <zmk/led_indicators_types.h>
+
+#define ZMK_LED_NUMLOCK_BIT BIT(0)
+#define ZMK_LED_CAPSLOCK_BIT BIT(1)
+#define ZMK_LED_SCROLLLOCK_BIT BIT(2)
+#define ZMK_LED_COMPOSE_BIT BIT(3)
+#define ZMK_LED_KANA_BIT BIT(4)
+
+zmk_leds_flags_t zmk_leds_get_current_flags();
+zmk_leds_flags_t zmk_leds_get_flags(enum zmk_endpoint endpoint, uint8_t profile);
+void zmk_leds_update_flags(zmk_leds_flags_t leds, enum zmk_endpoint endpoint, uint8_t profile);
+
+void zmk_leds_process_report(struct zmk_hid_led_report_body *report, enum zmk_endpoint endpoint,
+                             uint8_t profile);

app/include/zmk/led_indicators_types.h

@@ -0,0 +1,9 @@
+/*
+ * Copyright (c) 2022 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#pragma once
+
+typedef uint8_t zmk_leds_flags_t;

app/src/ble.c

@@ -227,6 +227,15 @@ int zmk_ble_clear_bonds() {
 
 int zmk_ble_active_profile_index() { return active_profile; }
 
+int zmk_ble_profile_index(const bt_addr_le_t *addr) {
+    for (int i = 0; i < ZMK_BLE_PROFILE_COUNT; i++) {
+        if (bt_addr_le_cmp(addr, &profiles[i].peer) == 0) {
+            return i;
+        }
+    }
+    return -ENODEV;
+}
+
 #if IS_ENABLED(CONFIG_SETTINGS)
 static void ble_save_profile_work(struct k_work *work) {
     settings_save_one("ble/active_profile", &active_profile, sizeof(active_profile));

app/src/events/led_indicator_changed.c

@@ -0,0 +1,10 @@
+/*
+ * Copyright (c) 2022 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#include <kernel.h>
+#include <zmk/events/led_indicator_changed.h>
+
+ZMK_EVENT_IMPL(zmk_led_changed);

app/src/hid.c

@@ -12,9 +12,10 @@ LOG_MODULE_DECLARE(zmk, CONFIG_ZMK_LOG_LEVEL);
 #include <dt-bindings/zmk/modifiers.h>
 
 static struct zmk_hid_keyboard_report keyboard_report = {
-    .report_id = 1, .body = {.modifiers = 0, ._reserved = 0, .keys = {0}}};
+    .report_id = HID_REPORT_ID_KEYBOARD, .body = {.modifiers = 0, ._reserved = 0, .keys = {0}}};
 
-static struct zmk_hid_consumer_report consumer_report = {.report_id = 2, .body = {.keys = {0}}};
+static struct zmk_hid_consumer_report consumer_report = {.report_id = HID_REPORT_ID_CONSUMER,
+                                                         .body = {.keys = {0}}};
 
 // Keep track of how often a modifier was pressed.
 // Only release the modifier if the count is 0.

app/src/hog.c

@@ -15,8 +15,10 @@ LOG_MODULE_DECLARE(zmk, CONFIG_ZMK_LOG_LEVEL);
 #include <bluetooth/gatt.h>
 
 #include <zmk/ble.h>
+#include <zmk/endpoints_types.h>
 #include <zmk/hog.h>
 #include <zmk/hid.h>
+#include <zmk/led_indicators.h>
 
 enum {
     HIDS_REMOTE_WAKE = BIT(0),
@@ -47,12 +49,17 @@ enum {
 };
 
 static struct hids_report input = {
-    .id = 0x01,
+    .id = HID_REPORT_ID_KEYBOARD,
     .type = HIDS_INPUT,
 };
 
+static struct hids_report led_indicators = {
+    .id = HID_REPORT_ID_LEDS,
+    .type = HIDS_OUTPUT,
+};
+
 static struct hids_report consumer_input = {
-    .id = 0x02,
+    .id = HID_REPORT_ID_CONSUMER,
     .type = HIDS_INPUT,
 };
 
@@ -85,6 +92,27 @@ static ssize_t read_hids_input_report(struct bt_conn *conn, const struct bt_gatt
                              sizeof(struct zmk_hid_keyboard_report_body));
 }
 
+static ssize_t write_hids_leds_report(struct bt_conn *conn, const struct bt_gatt_attr *attr,
+                                      const void *buf, uint16_t len, uint16_t offset,
+                                      uint8_t flags) {
+    if (flags & BT_GATT_WRITE_FLAG_PREPARE) {
+        return 0;
+    }
+
+    if (len != sizeof(struct zmk_hid_led_report_body)) {
+        LOG_ERR("LED report is malformed: length=%d", len);
+        return BT_GATT_ERR(BT_ATT_ERR_INVALID_ATTRIBUTE_LEN);
+    }
+
+    struct zmk_hid_led_report_body *report =
+        (struct zmk_hid_led_report_body *)((uint8_t *)buf + offset);
+    uint8_t profile = zmk_ble_profile_index(bt_conn_get_dst(conn));
+
+    zmk_leds_process_report(report, ZMK_ENDPOINT_BLE, profile);
+
+    return len;
+}
+
 static ssize_t read_hids_consumer_input_report(struct bt_conn *conn,
                                                const struct bt_gatt_attr *attr, void *buf,
                                                uint16_t len, uint16_t offset) {
@@ -134,6 +162,13 @@ BT_GATT_SERVICE_DEFINE(
     BT_GATT_CCC(input_ccc_changed, BT_GATT_PERM_READ_ENCRYPT | BT_GATT_PERM_WRITE_ENCRYPT),
     BT_GATT_DESCRIPTOR(BT_UUID_HIDS_REPORT_REF, BT_GATT_PERM_READ_ENCRYPT, read_hids_report_ref,
                        NULL, &input),
+
+    BT_GATT_CHARACTERISTIC(BT_UUID_HIDS_REPORT,
+                           BT_GATT_CHRC_WRITE | BT_GATT_CHRC_WRITE_WITHOUT_RESP,
+                           BT_GATT_PERM_WRITE_ENCRYPT, NULL, write_hids_leds_report, NULL),
+    BT_GATT_DESCRIPTOR(BT_UUID_HIDS_REPORT_REF, BT_GATT_PERM_READ_ENCRYPT, read_hids_report_ref,
+                       NULL, &led_indicators),
+
     BT_GATT_CHARACTERISTIC(BT_UUID_HIDS_REPORT, BT_GATT_CHRC_READ | BT_GATT_CHRC_NOTIFY,
                            BT_GATT_PERM_READ_ENCRYPT, read_hids_consumer_input_report, NULL, NULL),
     BT_GATT_CCC(input_ccc_changed, BT_GATT_PERM_READ_ENCRYPT | BT_GATT_PERM_WRITE_ENCRYPT),
@@ -224,7 +259,7 @@ void send_consumer_report_callback(struct k_work *work) {
         }
 
         struct bt_gatt_notify_params notify_params = {
-            .attr = &hog_svc.attrs[10],
+            .attr = &hog_svc.attrs[12],
             .data = &report,
             .len = sizeof(report),
         };

app/src/led_indicators.c

@@ -0,0 +1,79 @@
+/*
+ * Copyright (c) 2022 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#include <kernel.h>
+#include <device.h>
+#include <init.h>
+
+#include <logging/log.h>
+#include <drivers/led.h>
+
+#include <zmk/event_manager.h>
+#include <zmk/led_indicators.h>
+#include <zmk/events/led_indicator_changed.h>
+
+LOG_MODULE_DECLARE(zmk, CONFIG_ZMK_LOG_LEVEL);
+
+#ifndef DT_NODE_CHILD_IDX
+
+#define CHILD_IDX(idx, child_id, node_id) (DT_SAME_NODE(child_id, node_id) ? idx : 0)
+#define ADD_COMMA(node_id) node_id,
+#define DT_NODE_CHILD_IDX(node_id)                                                                 \
+    (FOR_EACH_IDX_FIXED_ARG(CHILD_IDX, (+), node_id,                                               \
+                            DT_FOREACH_CHILD(DT_PARENT(node_id), ADD_COMMA) DT_ROOT))
+
+#endif
+
+struct zmk_led_cfg {
+    const struct device *dev;
+    int index;
+    int indicator;
+};
+
+#define LED_CFG_IMPL(node_id, indicator_bit)                                                       \
+    (struct zmk_led_cfg) {                                                                         \
+        .dev = DEVICE_DT_GET(DT_PARENT(node_id)), .index = DT_NODE_CHILD_IDX(node_id),             \
+        .indicator = indicator_bit,                                                                \
+    }
+
+#define LED_CFG(chosen, indicator_bit)                                                             \
+    IF_ENABLED(DT_HAS_CHOSEN(chosen), (LED_CFG_IMPL(DT_CHOSEN(chosen), indicator_bit)))
+
+static const struct zmk_led_cfg led_indicators[] = {LIST_DROP_EMPTY(
+    LED_CFG(zmk_led_numlock, ZMK_LED_NUMLOCK_BIT), LED_CFG(zmk_led_capslock, ZMK_LED_CAPSLOCK_BIT),
+    LED_CFG(zmk_led_scrolllock, ZMK_LED_SCROLLLOCK_BIT),
+    LED_CFG(zmk_led_compose, ZMK_LED_COMPOSE_BIT), LED_CFG(zmk_led_kana, ZMK_LED_KANA_BIT))};
+
+static int leds_init(const struct device *_arg) {
+    for (int i = 0; i < ARRAY_SIZE(led_indicators); i++) {
+        if (!device_is_ready(led_indicators[i].dev)) {
+            LOG_ERR("LED device \"%s\" is not ready", led_indicators[i].dev->name);
+            return -ENODEV;
+        }
+    }
+
+    return 0;
+}
+
+static int leds_listener(const zmk_event_t *eh) {
+    const struct zmk_led_changed *ev = as_zmk_led_changed(eh);
+    zmk_leds_flags_t leds = ev->leds;
+
+    for (int i = 0; i < ARRAY_SIZE(led_indicators); i++) {
+        uint8_t value = (leds & led_indicators[i].indicator) ? CONFIG_ZMK_LED_INDICATORS_BRT : 0;
+        int rc = led_set_brightness(led_indicators[i].dev, led_indicators[i].index, value);
+        if (rc != 0) {
+            LOG_ERR("Failed to set LED indicator %d: %d", i, rc);
+        }
+    }
+
+    return ZMK_EV_EVENT_BUBBLE;
+}
+
+ZMK_LISTENER(leds_listener, leds_listener);
+ZMK_SUBSCRIPTION(leds_listener, zmk_led_changed);
+
+SYS_INIT(leds_init, APPLICATION, CONFIG_APPLICATION_INIT_PRIORITY);

app/src/led_indicators_generic.c

@@ -0,0 +1,81 @@
+/*
+ * Copyright (c) 2022 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#include <kernel.h>
+#include <logging/log.h>
+
+#include <zmk/ble.h>
+#include <zmk/endpoints.h>
+#include <zmk/led_indicators.h>
+#include <zmk/events/led_indicator_changed.h>
+#include <zmk/events/endpoint_selection_changed.h>
+
+LOG_MODULE_DECLARE(zmk, CONFIG_ZMK_LOG_LEVEL);
+
+#define NUM_USB_PROFILES (COND_CODE_1(IS_ENABLED(CONFIG_ZMK_USB), (1), (0)))
+#define NUM_BLE_PROFILES (COND_CODE_1(IS_ENABLED(CONFIG_ZMK_BLE), (ZMK_BLE_PROFILE_COUNT), (0)))
+#define NUM_PROFILES (NUM_USB_PROFILES + NUM_BLE_PROFILES)
+
+static zmk_leds_flags_t led_flags[NUM_PROFILES];
+
+static size_t profile_index(enum zmk_endpoint endpoint, uint8_t profile) {
+    switch (endpoint) {
+    case ZMK_ENDPOINT_USB:
+        return 0;
+    case ZMK_ENDPOINT_BLE:
+        return NUM_USB_PROFILES + profile;
+    }
+
+    CODE_UNREACHABLE;
+}
+
+zmk_leds_flags_t zmk_leds_get_current_flags() {
+    enum zmk_endpoint endpoint = zmk_endpoints_selected();
+    uint8_t profile = 0;
+
+#if IS_ENABLED(CONFIG_ZMK_BLE)
+    if (endpoint == ZMK_ENDPOINT_BLE) {
+        profile = zmk_ble_active_profile_index();
+    }
+#endif
+
+    return zmk_leds_get_flags(endpoint, profile);
+}
+
+zmk_leds_flags_t zmk_leds_get_flags(enum zmk_endpoint endpoint, uint8_t profile) {
+    size_t index = profile_index(endpoint, profile);
+    return led_flags[index];
+}
+
+static void raise_led_changed_event(struct k_work *_work) {
+    ZMK_EVENT_RAISE(
+        new_zmk_led_changed((struct zmk_led_changed){.leds = zmk_leds_get_current_flags()}));
+}
+
+static K_WORK_DEFINE(led_changed_work, raise_led_changed_event);
+
+void zmk_leds_update_flags(zmk_leds_flags_t leds, enum zmk_endpoint endpoint, uint8_t profile) {
+    size_t index = profile_index(endpoint, profile);
+    led_flags[index] = leds;
+
+    k_work_submit(&led_changed_work);
+}
+
+void zmk_leds_process_report(struct zmk_hid_led_report_body *report, enum zmk_endpoint endpoint,
+                             uint8_t profile) {
+    zmk_leds_flags_t leds = report->leds;
+    zmk_leds_update_flags(leds, endpoint, profile);
+
+    LOG_DBG("Update LED indicators: endpoint=%d, profile=%d, flags=%x", endpoint, profile, leds);
+}
+
+static int endpoint_listener(const zmk_event_t *eh) {
+    raise_led_changed_event(NULL);
+    return 0;
+}
+
+static ZMK_LISTENER(endpoint_listener, endpoint_listener);
+static ZMK_SUBSCRIPTION(endpoint_listener, zmk_endpoint_selection_changed);

app/src/usb_hid.c

@@ -13,6 +13,7 @@
 #include <zmk/usb.h>
 #include <zmk/hid.h>
 #include <zmk/keymap.h>
+#include <zmk/led_indicators.h>
 #include <zmk/event_manager.h>
 
 LOG_MODULE_DECLARE(zmk, CONFIG_ZMK_LOG_LEVEL);
@@ -23,8 +24,41 @@ static K_SEM_DEFINE(hid_sem, 1, 1);
 
 static void in_ready_cb(const struct device *dev) { k_sem_give(&hid_sem); }
 
+#define HID_GET_REPORT_TYPE_MASK 0xff00
+#define HID_GET_REPORT_ID_MASK 0x00ff
+
+#define HID_REPORT_TYPE_INPUT 0x100
+#define HID_REPORT_TYPE_OUTPUT 0x200
+#define HID_REPORT_TYPE_FEATURE 0x300
+
+static int set_report_cb(const struct device *dev, struct usb_setup_packet *setup, int32_t *len,
+                         uint8_t **data) {
+    if ((setup->wValue & HID_GET_REPORT_TYPE_MASK) != HID_REPORT_TYPE_OUTPUT) {
+        LOG_ERR("Unsupported report type %d requested",
+                (setup->wValue & HID_GET_REPORT_TYPE_MASK) >> 8);
+        return -ENOTSUP;
+    }
+
+    switch (setup->wValue & HID_GET_REPORT_ID_MASK) {
+    case HID_REPORT_ID_LEDS:
+        if (*len != sizeof(struct zmk_hid_led_report)) {
+            LOG_ERR("LED set report is malformed: length=%d", *len);
+        } else {
+            struct zmk_hid_led_report *report = (struct zmk_hid_led_report *)*data;
+            zmk_leds_process_report(&report->body, ZMK_ENDPOINT_USB, 0);
+        }
+        break;
+    default:
+        LOG_ERR("Invalid report ID %d requested", setup->wValue & HID_GET_REPORT_ID_MASK);
+        return -EINVAL;
+    }
+
+    return 0;
+}
+
 static const struct hid_ops ops = {
     .int_in_ready = in_ready_cb,
+    .set_report = set_report_cb,
 };
 
 int zmk_usb_hid_send_report(const uint8_t *report, size_t len) {

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.
+
+<Tabs
+defaultValue="pwm"
+values={[
+{label: 'LED PWM driver', value: 'pwm'},
+{label: 'LED GPIO driver', value: 'gpio'},
+{label: 'Others', value: 'other'},
+]}>
+<TabItem value="pwm">
+
+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** = `<Pin number>` 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`
+
+</TabItem>
+<TabItem value="gpio">
+
+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`
+
+</TabItem>
+<TabItem value="other">
+
+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 <zmk/led_indicators.h>
+
+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);
+```
+
+</TabItem>
+</Tabs>

docs/sidebars.js

@@ -17,6 +17,7 @@ module.exports = {
       "features/encoders",
       "features/underglow",
       "features/backlight",
+      "features/led-indicators",
       "features/battery",
       "features/beta-testing",
     ],