docs: Move more sections under hardware integration (#2704)

docs: Move battery sensing hardware integration to new page docs: Refactor lighting hardware integrations to new category docs: Link to pin control page from lighting pages docs: Consolidate lighting feature pages docs: Remove incorrect redirect docs: Consolidate lighting config pages
zmkfirmware · Jan 14, 2025 · 700e9b2 · 700e9b2
1 parent 8dddb1d
commit 700e9b2
Show file tree

Hide file tree

Showing 17 changed files with 244 additions and 171 deletions.
diff --git a/docs/blog/2020-08-12-zmk-sotf-1.md b/docs/blog/2020-08-12-zmk-sotf-1.md
@@ -14,7 +14,7 @@ With interest and Discord activity growing, it seemed important to lay out the p
 
 There's been lots of various activity in ZMK land!
 
-- [Nicell](https://github.com/Nicell) (nice!nano creator) contributed initial [RGB Underglow](/docs/features/underglow) ([#64](https://github.com/zmkfirmware/zmk/pull/64)) support to ZMK.
+- [Nicell](https://github.com/Nicell) (nice!nano creator) contributed initial [RGB Underglow](/docs/features/lighting#rgb-underglow) ([#64](https://github.com/zmkfirmware/zmk/pull/64)) support to ZMK.
 - Tons of [documentation](/docs) work.
 - Refactoring ([#73](https://github.com/zmkfirmware/zmk/pull/73), [#74](https://github.com/zmkfirmware/zmk/pull/74)) of [keymaps](/docs/keymaps) to make them simpler for users.
 - Mod-Tap Behavior (docs coming!) is much improved ([#69](https://github.com/zmkfirmware/zmk/pull/69)) and usable now.

diff --git a/docs/blog/2022-04-02-zephyr-3-0.md b/docs/blog/2022-04-02-zephyr-3-0.md
@@ -73,7 +73,7 @@ The following changes have [already been completed](https://github.com/zmkfirmwa
 
 ### RGB Underglow
 
-Zephyr's WS2812 `led_strip` driver added a new required property. When adding [underglow](/docs/features/underglow#adding-rgb-underglow-to-a-board) to a board, you now must also add the additional include `#include <dt-bindings/led/led.h>` at the top of your devicetree file, and add a `color-mapping` property like:
+Zephyr's WS2812 `led_strip` driver added a new required property. When adding [underglow](/docs/features/lighting#adding-rgb-underglow-support-to-a-keyboard) to a board, you now must also add the additional include `#include <dt-bindings/led/led.h>` at the top of your devicetree file, and add a `color-mapping` property like:
 
 ```dts
 led_strip: ws2812@0 {

diff --git a/docs/blog/2022-04-10-zmk-sotf-5.md b/docs/blog/2022-04-10-zmk-sotf-5.md
@@ -130,7 +130,7 @@ Another persistent bug that Apple users experienced was related to crashes and p
 
 The long awaited locality enhancement was finally merged by [petejohanson] in [#547](https://github.com/zmkfirmware/zmk/pull/547), allowing more fine grained control of where certain behaviors are invoked. Some key improvements thanks to the changes:
 
-- [RGB Underglow](/docs/features/underglow) behaviors now run globally, so enabling/disabling RGB, changing the color, animation, etc. applies to both sides of a split properly.
+- [RGB Underglow](/docs/features/lighting#rgb-underglow) behaviors now run globally, so enabling/disabling RGB, changing the color, animation, etc. applies to both sides of a split properly.
 - [Reset](/docs/keymaps/behaviors/reset#reset)/[Bootloader](/docs/keymaps/behaviors/reset#bootloader-reset) behaviors now run wherever the key was pressed. For example, adding a `&bootloader` reference to the peripheral side of a split will now put that side of the split into the bootloader when pressed.
 
 #### Split Connections
@@ -141,7 +141,7 @@ The long awaited locality enhancement was finally merged by [petejohanson] in [#
 
 #### Backlight
 
-[bortoz](https://github.com/bortoz) added [single color backlight support](/docs/features/backlight) in [#904](https://github.com/zmkfirmware/zmk/pull/904) for those keyboards that have it as an alternative to RGB underglow.
+[bortoz](https://github.com/bortoz) added [single color backlight support](/docs/features/lighting#backlight) in [#904](https://github.com/zmkfirmware/zmk/pull/904) for those keyboards that have it as an alternative to RGB underglow.
 
 #### E-Paper Display (EPD) Driver
 

diff --git a/docs/blog/2023-10-05-zmk-sotf-6.md b/docs/blog/2023-10-05-zmk-sotf-6.md
@@ -130,7 +130,7 @@ This refactor paved way to implementing a long-awaited feature, encoder support
 
 #### Underglow auto-off options
 
-[ReFil] added two [new RGB auto off options](/docs/config/underglow), one using an idle timeout and the other USB status in [#1010](https://github.com/zmkfirmware/zmk/pull/1010).
+[ReFil] added two [new RGB auto off options](/docs/config/lighting#rgb-underglow), one using an idle timeout and the other USB status in [#1010](https://github.com/zmkfirmware/zmk/pull/1010).
 
 #### nice!view support
 

diff --git a/docs/docs/config/backlight.md b/docs/docs/config/backlight.md
diff --git a/docs/docs/config/underglow.md → docs/docs/config/lighting.md b/docs/docs/config/underglow.md → docs/docs/config/lighting.md
@@ -1,13 +1,17 @@
 ---
-title: RGB Underglow Configuration
-sidebar_label: RGB Underglow
+title: Lighting Configuration
+sidebar_label: Lighting
 ---
 
-See the [RGB Underglow feature page](../features/underglow.md) for more details, including instructions for adding underglow support to a board.
+See the [Lighting feature page](../features/lighting.md) for an overview of the available lighting systems in ZMK.
+
+## RGB Underglow
+
+See the [RGB underglow section](../features/lighting.md#rgb-underglow) in the Lighting feature page for more details, and [hardware integration page](../development/hardware-integration/lighting/underglow.md) for adding underglow support to a board.
 
 See [Configuration Overview](index.md) for instructions on how to change these settings.
 
-## Kconfig
+### Kconfig
 
 RGB underglow depends on [Zephyr's LED strip driver](https://github.com/zephyrproject-rtos/zephyr/tree/main/drivers/led_strip), which provides additional Kconfig options.
 
@@ -44,8 +48,46 @@ Values for `CONFIG_ZMK_RGB_UNDERGLOW_EFF_START`:
 The `*_START` settings only determine the initial underglow state. Any changes you make with the [underglow behavior](../keymaps/behaviors/underglow.md) are saved to flash after a one minute delay and will be used after that.
 :::
 
-## Devicetree
+### Devicetree
 
 ZMK does not have any Devicetree properties of its own. See the Devicetree bindings for [Zephyr's LED strip drivers](https://github.com/zephyrproject-rtos/zephyr/tree/main/dts/bindings/led_strip).
 
-See the [RGB underglow feature page](../features/underglow.md) for examples of the properties that must be set to enable underglow.
+See the [RGB underglow hardware integration page](../development/hardware-integration/lighting/underglow.md) for examples of the properties that must be set to enable underglow.
+
+## Backlight
+
+See the [backlight section](../features/lighting.md#backlight) in Lighting feature page for more details, and [hardware integration page](../development/hardware-integration/lighting/backlight.mdx) for adding backlight support to a board.
+
+See [Configuration Overview](index.md) for instructions on how to change these settings.
+
+### Kconfig
+
+Definition file: [zmk/app/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/app/Kconfig)
+
+| Option                               | Type | Description                                           | Default |
+| ------------------------------------ | ---- | ----------------------------------------------------- | ------- |
+| `CONFIG_ZMK_BACKLIGHT`               | bool | Enables LED backlight                                 | n       |
+| `CONFIG_ZMK_BACKLIGHT_BRT_STEP`      | int  | Brightness step in percent                            | 20      |
+| `CONFIG_ZMK_BACKLIGHT_BRT_START`     | int  | Default brightness in percent                         | 40      |
+| `CONFIG_ZMK_BACKLIGHT_ON_START`      | bool | Default backlight state                               | y       |
+| `CONFIG_ZMK_BACKLIGHT_AUTO_OFF_IDLE` | bool | Turn off backlight when keyboard goes into idle state | n       |
+| `CONFIG_ZMK_BACKLIGHT_AUTO_OFF_USB`  | bool | Turn off backlight when USB is disconnected           | n       |
+
+:::note
+The `*_START` settings only determine the initial backlight state. Any changes you make with the [backlight behavior](../keymaps/behaviors/backlight.md) are saved to flash after a one minute delay and will be used after that.
+:::
+
+### Devicetree
+
+Applies to: [`/chosen` node](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes)
+
+| Property        | Type | Description                                  |
+| --------------- | ---- | -------------------------------------------- |
+| `zmk,backlight` | path | The node for the backlight LED driver to use |
+
+See the Zephyr devicetree bindings for LED drivers:
+
+- [gpio-leds](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings/led/gpio-leds.html)
+- [pwm-leds](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings/led/pwm-leds.html)
+
+See the [backlight hardware integration page](../development/hardware-integration/lighting/backlight.mdx) for examples of the properties that must be set to enable backlighting.
diff --git a/docs/docs/development/hardware-integration/battery.md b/docs/docs/development/hardware-integration/battery.md
@@ -0,0 +1,30 @@
+---
+title: Battery Sensing
+sidebar_label: Battery Sensing
+---
+
+If your keyboard is using one of the [boards supported in ZMK](../../hardware.mdx) it will already be configured to [sense and report battery levels](../../features/battery.md).
+Below instructions are only intended for users defining and using a custom board.
+
+To enable a battery sensor on a new board, add the driver for the sensor to your board's `.dts` file. ZMK provides two drivers for estimating the battery level using its voltage:
+
+- `zmk,battery-voltage-divider`: Reads the voltage on an analog input pin.
+- `zmk,battery-nrf-vddh`: Reads the power supply voltage on a Nordic nRF52's VDDH pin.
+
+See the [battery level configuration page](../../config/battery.md) for the configuration supported by each driver provided by ZMK.
+
+Zephyr also provides some drivers for fuel gauge ICs such as the TI bq274xx series and Maxim MAX17xxx series. If you use a battery sensor that does not have an existing driver, you will need to write a new driver that supports the `SENSOR_CHAN_GAUGE_STATE_OF_CHARGE` sensor channel and contribute it to Zephyr or ZMK.
+
+Once you have the sensor driver defined, add a `zmk,battery` property to the `chosen` node and set it to reference the sensor node. For example:
+
+```dts
+/ {
+    chosen {
+      zmk,battery = &vbatt;
+    };
+
+    vbatt: vbatt {
+        compatible = "zmk,battery-nrf-vddh";
+    };
+}
+```
diff --git a/docs/docs/features/backlight.mdx → ...rdware-integration/lighting/backlight.mdx b/docs/docs/features/backlight.mdx → ...rdware-integration/lighting/backlight.mdx
@@ -1,45 +1,18 @@
 ---
 title: Backlight
 sidebar_label: Backlight
+description: Lighting system that controls an array of single-color LEDs.
 ---
 
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-Backlight is a feature used to control an array of LEDs, usually placed through or under switches.
-
-:::info
-Unlike [RGB Underglow](underglow.md), backlight can only control single color LEDs. Additionally, because backlight LEDs all receive the same power, it's not possible to dim individual LEDs.
-:::
-
-## Enabling Backlight
-
-To enable backlight on your board or shield, add the following line to your `.conf` file of your user config directory as such:
-
-```ini
-CONFIG_ZMK_BACKLIGHT=y
-```
-
-If your board or shield does not have backlight configured, refer to [Adding Backlight to a board or a shield](#adding-backlight-to-a-board-or-a-shield).
-
-## Configuring Backlight
-
-There are various Kconfig options used to configure the backlight feature. These can all be set in the `.conf` file.
-
-| Option                               | Description                                           | Default |
-| ------------------------------------ | ----------------------------------------------------- | ------- |
-| `CONFIG_ZMK_BACKLIGHT_BRT_STEP`      | Brightness step in percent                            | 20      |
-| `CONFIG_ZMK_BACKLIGHT_BRT_START`     | Default brightness in percent                         | 40      |
-| `CONFIG_ZMK_BACKLIGHT_ON_START`      | Default backlight state                               | y       |
-| `CONFIG_ZMK_BACKLIGHT_AUTO_OFF_IDLE` | Turn off backlight when keyboard goes into idle state | n       |
-| `CONFIG_ZMK_BACKLIGHT_AUTO_OFF_USB`  | Turn off backlight when USB is disconnected           | n       |
-
-## Adding Backlight to a Board or a Shield
+Please see [lighting feature page](../../../features/lighting.md#backlight) for an introduction on the feature.
 
 <Tabs
-defaultValue="shieldpin"
-values={[
-{label: 'Adding to a board', value: 'boardpin'},{label: 'Adding to a shield', value: 'shieldpin'},
+  defaultValue="shieldpin"
+  values={[
+  {label: 'Adding to a board', value: 'boardpin'},{label: 'Adding to a shield', value: 'shieldpin'},
 ]}>
 
 <TabItem value="boardpin">
@@ -59,8 +32,9 @@ endif # ZMK_BACKLIGHT
 ```
 
 Create a `<board>-pinctrl.dtsi` file if it does not already exist, and include it at the beginning of the `<board>.dts` file. `CONFIG_PINCTRL=y` must be added to `<board>_defconfig` if it isn't already enabled.
+See the documentation page on [pin control](../pinctrl.mdx) for detailed information on setting up pins for hardware protocols such as PWM that is used for controlling backlight LEDs.
 
-The pinctrl file has a `&pinctrl` node that encompasses all pinctrl settings, including I2C or SPI peripherals (e.g. WS2812 LEDs, Battery fuel gauges):
+The pinctrl file has a `&pinctrl` node that encompasses all pinctrl settings, including I2C or SPI peripherals (e.g. WS2812 LEDs, battery fuel gauges):
 
 ```dts
 &pinctrl {
@@ -161,6 +135,8 @@ Then add the following lines to your `.overlay` file:
 };
 ```
 
+See the documentation page on [pin control](../pinctrl.mdx) for detailed information on setting up pins for hardware protocols such as PWM that is used for controlling backlight LEDs.
+
 Pin numbers are handled differently depending on the MCU. On nRF MCUs pins are configured using `(PWM_OUTX, Y, Z)`, where `X` is the PWM channel used (usually 0), `Y` is the first part of the hardware port (_PY.01_) and `Z` is the second part of the hardware port (_P1.Z_).
 
 For example, _P1.13_ would give you `(PWM_OUT0, 1, 13)` and _P0.15_ would give you `(PWM_OUT0, 0, 15)`.

diff --git a/docs/docs/development/hardware-integration/lighting/index.mdx b/docs/docs/development/hardware-integration/lighting/index.mdx
@@ -0,0 +1,17 @@
+---
+title: Lighting
+sidebar_label: Lighting
+---
+
+import DocCardList from "@theme/DocCardList";
+
+The following pages detail adding lighting support to ZMK keyboards, which currently supports two lighting systems: underglow and backlight.
+
+:::warning
+
+Although the naming of the systems might imply it, which system you use typically does _not_ depend on the physical location of the LEDs.
+Instead, you should use the one that supports the LED hardware type that your keyboard has.
+
+:::
+
+<DocCardList />
diff --git a/docs/docs/features/underglow.md → ...ardware-integration/lighting/underglow.md b/docs/docs/features/underglow.md → ...ardware-integration/lighting/underglow.md
@@ -1,64 +1,13 @@
 ---
 title: RGB Underglow
 sidebar_label: RGB Underglow
+description: Lighting system that controls strips of RGB LEDs.
 ---
 
-RGB underglow is a feature used to control "strips" of RGB LEDs. Most of the time this is called underglow and creates a glow underneath the board using a ring of LEDs around the edge, hence the name. However, this can be extended to be used to control anything from a single LED to a long string of LEDs anywhere on the keyboard.
-
-:::info
-RGB underglow can also be used for per-key lighting. If you have RGB LEDs on your keyboard, this is what you want. For PWM/single color LEDs, see [Backlight](backlight.mdx).
-:::
-
-ZMK relies on Zephyr's `led-strip` drivers for this feature. The following LEDs/LED families have been implemented:
-
-- WS2812 (includes WS2812B, WS2813, SK6812, and others)
-- APA102
-- LPD880x (includes LPD8803, LPD8806, and others)
-
-The WS2812 LED family is by far the most popular of these types, so this page will primarily focus on working with it.
-
-Here you can see the RGB underglow feature in action using WS2812 LEDs.
-
-<figure class="video-container">
-  <iframe src="//www.youtube.com/embed/2KJkq8ssDU0" frameborder="0" allowfullscreen width="100%"></iframe>
-</figure>
-
-## Enabling RGB Underglow
-
-To enable RGB underglow on your board or shield, simply enable the `CONFIG_ZMK_RGB_UNDERGLOW` and `CONFIG_*_STRIP` configuration values in the `.conf` file for your board or shield.
-For example:
-
-```ini
-CONFIG_ZMK_RGB_UNDERGLOW=y
-# Use the STRIP config specific to the LEDs you're using
-CONFIG_WS2812_STRIP=y
-```
-
-See [Configuration Overview](/docs/config) for more instructions on how to use Kconfig.
-
-If your board or shield does not have RGB underglow configured, refer to [Adding RGB Underglow to a Board](#adding-rgb-underglow-to-a-board).
-
-### Modifying the Number of LEDs
-
-The number of LEDs specified in the default configuration for your board or shield may not match the number you have installed. For example, the `corne` shield specifies only 10 LEDs per side while supporting up to 27. On a split keyboard, a good sign of this mismatch is if the lit LEDs on each half are symmetrical.
-
-The `chain-length` property of the `led_strip` node controls the number of underglow LEDs. If it is incorrect for your build, [you can change this property](../config/index.md#changing-devicetree-properties) in your `<keyboard>.keymap` file by adding a stanza like this one outside of any other node (i.e. above or below the `/` node):
-
-```dts
-&led_strip {
-    chain-length = <21>;
-};
-```
-
-For split keyboards, set `chain-length` to the number of LEDs installed on each half.
-
-## Configuring RGB Underglow
-
-See [RGB underglow configuration](/docs/config/underglow).
-
-## Adding RGB Underglow to a Board
+Please see [lighting feature page](../../../features/lighting.md#rgb-underglow) for an introduction on the feature.
 
 Support for RGB underglow is always added to a board, not a shield. This is because the LED strip drivers rely on hardware-specific interfaces (e.g. SPI, I2S) and configurations, which shields do not control.
+See the documentation page on [pin control](../pinctrl.mdx) for detailed information on setting up pins for hardware protocols such as SPI or PIO that are used for LED strips.
 
 Shields written for boards which support RGB underglow should add a `boards/` folder underneath the shield folder. Inside this `boards/` folder, create a `<board>.overlay` for any of the boards the shield can be used with. Place all hardware-specific configurations in these `.overlay` files.