feat(docs): add backlight documentation

8 files changed, 175 insertions, 12 deletions

diff --git a/docs/blog/2021-01-27-zmk-sotf-4.md b/docs/blog/2021-01-27-zmk-sotf-4.md
index d902b62..cd84da8 100644
--- a/docs/blog/2021-01-27-zmk-sotf-4.md
+++ b/docs/blog/2021-01-27-zmk-sotf-4.md
@@ -76,7 +76,7 @@ to your keymap will send `ESC` when pressed on its own, but will send `` ` `` wh
 
 #### RGB Underglow Color Selection
 
-[mcrosson] updated the [RGB Underglow behavior](/docs/behaviors/lighting#rgb-underglow) to allow [binding an explicit color selection](/docs/behaviors/lighting#examples) to a key position.
+[mcrosson] updated the [RGB Underglow behavior](/docs/behaviors/underglow) to allow [binding an explicit color selection](/docs/behaviors/underglow#examples) to a key position.
 
 #### Keymap Upgrader
 
diff --git a/docs/docs/behaviors/backlight.md b/docs/docs/behaviors/backlight.md
new file mode 100644
index 0000000..c1a92c9
--- /dev/null
+++ b/docs/docs/behaviors/backlight.md
@@ -0,0 +1,48 @@
+---
+title: Backlight Behavior
+sidebar_label: Backlight
+---
+
+## Summary
+
+This page contains [backlight](../features/backlight.md) behaviors supported by ZMK.
+
+## Backlight Action Defines
+
+Backlight actions defines are provided through the [`dt-bindings/zmk/backlight.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/backlight.h) header,
+which is added at the top of the keymap file:
+
+```
+#include <dt-bindings/zmk/backlight.h>
+```
+
+This will allow you to reference the actions defined in this header such as `BL_TOG`.
+
+Here is a table describing the action for each define:
+
+| Define   | Action                                   |
+| -------- | ---------------------------------------- |
+| `BL_TOG` | Toggles the backlight on and off         |
+| `BL_ON`  | Turn on backlight on and off             |
+| `BL_OFF` | Toggles the backlight feature on and off |
+| `BL_INC` | Increase backlight brightness            |
+| `BL_DEC` | Decrease backlight brightness            |
+
+## Behavior Binding
+
+- Reference: `&bl`
+- Parameter #1: The backlight action define, e.g. `BL_TOG` or `BL_INC`
+
+### Examples
+
+1. Toggle backlight on/off
+
+   ```
+   &bl BL_TOG
+   ```
+
+1. Increase backlight brightness
+
+   ```
+   &bl BL_INC
+   ```
diff --git a/docs/docs/behaviors/lighting.md b/docs/docs/behaviors/underglow.md
index 6e6732b..597c249 100644
--- a/docs/docs/behaviors/lighting.md
+++ b/docs/docs/behaviors/underglow.md
@@ -1,12 +1,11 @@
 ---
-title: Lighting Behavior
-sidebar_label: Lighting
+title: RGB Underglow Behavior
+sidebar_label: RGB Underglow
 ---
 
 ## Summary
 
-Lighting is often used for either aesthetics or for the practical purposes of lighting up keys in the dark.
-Currently ZMK supports RGB underglow, which can be changed and configured using its behavior.
+This page contains [RGB Underglow](../features/underglow.md) behaviors supported by ZMK.
 
 ## RGB Action Defines
 
@@ -36,11 +35,7 @@ Here is a table describing the action for each define:
 | `RGB_EFR`       | Cycles the RGB feature's effect reverse                                                        |
 | `RGB_COLOR_HSB` | Sets a specific [HSB (HSV)](https://en.wikipedia.org/wiki/HSL_and_HSV) value for the underglow |
 
-## RGB Underglow
-
-The "RGB underglow" behavior completes an RGB action given on press.
-
-### Behavior Binding
+## Behavior Binding
 
 - Reference: `&rgb_ug`
 - Parameter #1: The RGB action define, e.g. `RGB_TOG` or `RGB_BRI`
@@ -58,7 +53,7 @@ Value Limits:
 
 :::
 
-### Examples
+## Examples
 
 1. Toggle underglow on/off
 
diff --git a/docs/docs/development/hardware-metadata-files.md b/docs/docs/development/hardware-metadata-files.md
index 5d4902d..46fad41 100644
--- a/docs/docs/development/hardware-metadata-files.md
+++ b/docs/docs/development/hardware-metadata-files.md
@@ -94,6 +94,7 @@ Boards and shields should document the sets of hardware features found on them u
 - `display` - Indicates the hardware includes a display for use with the ZMK display functionality.
 - `encoder` - Indicates the hardware contains one or more rotary encoders.
 - `underglow` - Indicates the hardware includes underglow LEDs.
+- `backlight` - Indicates the hardware includes backlight LEDs.
 - `pointer` (future) - Used to indicate the hardware includes one or more pointer inputs, e.g. joystick, touchpad, or trackpoint.
 
 ### Siblings
diff --git a/docs/docs/features/backlight.md b/docs/docs/features/backlight.md
new file mode 100644
index 0000000..a917b16
--- /dev/null
+++ b/docs/docs/features/backlight.md
@@ -0,0 +1,115 @@
+---
+title: Backlight
+sidebar_label: Backlight
+---
+
+Backlight is a feature used to control array of LEDs, usually placed through or under switches. Unlike [RGB Underglow](underglow.md), backlight currently allows only one color per LED, also LEDs are not addressable, so you can't control individual LEDs.
+
+## Enabling Backlight
+
+To enable backlight on your board or shield, simply enable the `CONFIG_ZMK_BACKLIGHT` configuration values in the `.conf` file of your user config directory as such:
+
+```
+CONFIG_ZMK_BACKLIGHT=y
+```
+
+If your board or shield does not have backlight configured, refer to [Adding Backlight to a Board](#adding-backlight-to-a-board).
+
+## 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 | y       |
+| `CONFIG_ZMK_BACKLIGHT_AUTO_OFF_USB`  | Turn off backlight when USB is disconnected           | n       |
+
+## Adding Backlight to a Board
+
+Backlight is always added to a board, not a shield.
+If you have a shield with backlight, you must add a `boards/` directory within your shield folder to define the backlight individually for each board that supports the shield.
+Inside the `boards/` folder, you define a `<board>.overlay` for each different board.
+
+First, you need to enable PWM by adding the following lines to your `.overlay` file:
+
+```
+&pwm0 {
+	status = "okay";
+	ch0-pin = <45>;
+	/* ch0-inverted; */
+};
+```
+
+The value `ch0-pin` represents the pin that controls the LEDs. To calculate the value to use, you need a bit of math. 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 your board uses a P-channel MOSFET to control backlight instead of a N-channel MOSFET, you may want to enable `ch0-inverted`.
+
+Then you have to add the following lines to your `.dtsi` file inside the root devicetree node:
+
+```
+backlight: pwmleds {
+    compatible = "pwm-leds";
+    label = "Backlight LEDs";
+    pwm_led_0 {
+        pwms = <&pwm0 45>;
+    };
+};
+```
+
+The value inside `pwm_led_0` must be the same as you used before.
+
+:::info
+Note that every LED inside of the backlight node will be treated as a backlight LED, so if you have other PWM LEDs you need to declare them in a separate node. Refer to [Multiple backlight LEDs](#multiple-backlight-leds) if you have multiple backlight LEDs.
+:::
+
+Finally you need to add backlight to the `chosen` element of the root devicetree node:
+
+```
+chosen {
+    ...
+    zmk,backlight = &backlight;
+};
+```
+
+### Multiple backlight LEDs
+
+It is possible to control multiple backlight LEDs at the same time. This is useful if, for example, you have a Caps Lock LED connected to a different pin and you want it to be part of the backlight.
+
+In order to do that, first you need to enable PWM for each pin:
+
+```
+&pwm0 {
+	status = "okay";
+	ch0-pin = <45>; /* LED 0 */
+	ch1-pin = <46>; /* LED 1 */
+	ch2-pin = <47>; /* LED 2 */
+    ...
+};
+```
+
+This part may vary based on your MCU as different MCUs may have a different number of modules and channels.
+
+Then you can simply add each of your LED to the backlight node:
+
+```
+backlight: pwmleds {
+    compatible = "pwm-leds";
+    label = "Backlight LEDs";
+    pwm_led_0 {
+        pwms = <&pwm0 45>; /* LED 0 */
+    };
+    pwm_led_1 {
+        pwms = <&pwm0 46>; /* LED 1 */
+    };
+    pwm_led_2 {
+        pwms = <&pwm0 47>; /* LED 2 */
+    };
+    ...
+};
+```
diff --git a/docs/docs/hardware.mdx b/docs/docs/hardware.mdx
index ccdd063..76a0a3c 100644
--- a/docs/docs/hardware.mdx
+++ b/docs/docs/hardware.mdx
@@ -18,6 +18,7 @@ In addition to the basic keyboard functionality, there is some initial support f
 - Encoders
 - Displays
 - RGB Underglow
+- Backlight
 
 Until detailed documentation is available, feel free to ask questions about how these are supported in the [Discord server](https://zmk.dev/community/discord/invite).
 
diff --git a/docs/docs/intro.md b/docs/docs/intro.md
index 39a52c6..b8a6316 100644
--- a/docs/docs/intro.md
+++ b/docs/docs/intro.md
@@ -28,6 +28,7 @@ ZMK is currently missing some features found in other popular firmware. This tab
 | [Encoders](features/encoders.md)[^1]                                                                                               | ✅  |    ✅     | ✅  |
 | [Display Support](features/displays.md)[^2]                                                                                        | 🚧  |    🚧     | ✅  |
 | [RGB Underglow](features/underglow.md)                                                                                             | ✅  |    ✅     | ✅  |
+| [Backlight](features/backlight.md)                                                                                                 | ✅  |    ✅     | ✅  |
 | One Shot Keys                                                                                                                      | ✅  |    ✅     | ✅  |
 | [Combo Keys](features/combos.md)                                                                                                   | ✅  |           | ✅  |
 | Macros                                                                                                                             | 🚧  |    ✅     | ✅  |
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 3825621..090dcb0 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -16,6 +16,7 @@ module.exports = {
       "features/displays",
       "features/encoders",
       "features/underglow",
+      "features/backlight",
       "features/beta-testing",
     ],
     Behaviors: [
@@ -31,7 +32,8 @@ module.exports = {
       "behaviors/reset",
       "behaviors/bluetooth",
       "behaviors/outputs",
-      "behaviors/lighting",
+      "behaviors/underglow",
+      "behaviors/backlight",
       "behaviors/power",
     ],
     Codes: [