Skip to content

Commit 700e9b2

Browse files
caksoylarcaksoylar
authored
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
1 parent 8dddb1d commit 700e9b2

17 files changed

+244
-171
lines changed

‎docs/blog/2020-08-12-zmk-sotf-1.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ With interest and Discord activity growing, it seemed important to lay out the p
1414

1515
There's been lots of various activity in ZMK land!
1616

17-
- [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.
17+
- [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.
1818
- Tons of [documentation](/docs) work.
1919
- 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.
2020
- Mod-Tap Behavior (docs coming!) is much improved ([#69](https://github.com/zmkfirmware/zmk/pull/69)) and usable now.

‎docs/blog/2022-04-02-zephyr-3-0.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ The following changes have [already been completed](https://github.com/zmkfirmwa
7373

7474
### RGB Underglow
7575

76-
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:
76+
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:
7777

7878
```dts
7979
led_strip: ws2812@0 {

‎docs/blog/2022-04-10-zmk-sotf-5.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -130,7 +130,7 @@ Another persistent bug that Apple users experienced was related to crashes and p
130130

131131
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:
132132

133-
- [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.
133+
- [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.
134134
- [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.
135135

136136
#### Split Connections
@@ -141,7 +141,7 @@ The long awaited locality enhancement was finally merged by [petejohanson] in [#
141141

142142
#### Backlight
143143

144-
[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.
144+
[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.
145145

146146
#### E-Paper Display (EPD) Driver
147147

‎docs/blog/2023-10-05-zmk-sotf-6.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -130,7 +130,7 @@ This refactor paved way to implementing a long-awaited feature, encoder support
130130

131131
#### Underglow auto-off options
132132

133-
[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).
133+
[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).
134134

135135
#### nice!view support
136136

‎docs/docs/config/backlight.md

-40
This file was deleted.

‎docs/docs/config/underglow.md ‎docs/docs/config/lighting.md

+48-6
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,17 @@
11
---
2-
title: RGB Underglow Configuration
3-
sidebar_label: RGB Underglow
2+
title: Lighting Configuration
3+
sidebar_label: Lighting
44
---
55

6-
See the [RGB Underglow feature page](../features/underglow.md) for more details, including instructions for adding underglow support to a board.
6+
See the [Lighting feature page](../features/lighting.md) for an overview of the available lighting systems in ZMK.
7+
8+
## RGB Underglow
9+
10+
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.
711

812
See [Configuration Overview](index.md) for instructions on how to change these settings.
913

10-
## Kconfig
14+
### Kconfig
1115

1216
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.
1317

@@ -44,8 +48,46 @@ Values for `CONFIG_ZMK_RGB_UNDERGLOW_EFF_START`:
4448
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.
4549
:::
4650

47-
## Devicetree
51+
### Devicetree
4852

4953
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).
5054

51-
See the [RGB underglow feature page](../features/underglow.md) for examples of the properties that must be set to enable underglow.
55+
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.
56+
57+
## Backlight
58+
59+
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.
60+
61+
See [Configuration Overview](index.md) for instructions on how to change these settings.
62+
63+
### Kconfig
64+
65+
Definition file: [zmk/app/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/app/Kconfig)
66+
67+
| Option | Type | Description | Default |
68+
| ------------------------------------ | ---- | ----------------------------------------------------- | ------- |
69+
| `CONFIG_ZMK_BACKLIGHT` | bool | Enables LED backlight | n |
70+
| `CONFIG_ZMK_BACKLIGHT_BRT_STEP` | int | Brightness step in percent | 20 |
71+
| `CONFIG_ZMK_BACKLIGHT_BRT_START` | int | Default brightness in percent | 40 |
72+
| `CONFIG_ZMK_BACKLIGHT_ON_START` | bool | Default backlight state | y |
73+
| `CONFIG_ZMK_BACKLIGHT_AUTO_OFF_IDLE` | bool | Turn off backlight when keyboard goes into idle state | n |
74+
| `CONFIG_ZMK_BACKLIGHT_AUTO_OFF_USB` | bool | Turn off backlight when USB is disconnected | n |
75+
76+
:::note
77+
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.
78+
:::
79+
80+
### Devicetree
81+
82+
Applies to: [`/chosen` node](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes)
83+
84+
| Property | Type | Description |
85+
| --------------- | ---- | -------------------------------------------- |
86+
| `zmk,backlight` | path | The node for the backlight LED driver to use |
87+
88+
See the Zephyr devicetree bindings for LED drivers:
89+
90+
- [gpio-leds](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings/led/gpio-leds.html)
91+
- [pwm-leds](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings/led/pwm-leds.html)
92+
93+
See the [backlight hardware integration page](../development/hardware-integration/lighting/backlight.mdx) for examples of the properties that must be set to enable backlighting.

‎docs/docs/development/hardware-integration/battery.md

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: Battery Sensing
3+
sidebar_label: Battery Sensing
4+
---
5+
6+
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).
7+
Below instructions are only intended for users defining and using a custom board.
8+
9+
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:
10+
11+
- `zmk,battery-voltage-divider`: Reads the voltage on an analog input pin.
12+
- `zmk,battery-nrf-vddh`: Reads the power supply voltage on a Nordic nRF52's VDDH pin.
13+
14+
See the [battery level configuration page](../../config/battery.md) for the configuration supported by each driver provided by ZMK.
15+
16+
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.
17+
18+
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:
19+
20+
```dts
21+
/ {
22+
chosen {
23+
zmk,battery = &vbatt;
24+
};
25+
26+
vbatt: vbatt {
27+
compatible = "zmk,battery-nrf-vddh";
28+
};
29+
}
30+
```

‎docs/docs/features/backlight.mdx ‎docs/docs/development/hardware-integration/lighting/backlight.mdx

+9-33
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,18 @@
11
---
22
title: Backlight
33
sidebar_label: Backlight
4+
description: Lighting system that controls an array of single-color LEDs.
45
---
56

67
import Tabs from "@theme/Tabs";
78
import TabItem from "@theme/TabItem";
89

9-
Backlight is a feature used to control an array of LEDs, usually placed through or under switches.
10-
11-
:::info
12-
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.
13-
:::
14-
15-
## Enabling Backlight
16-
17-
To enable backlight on your board or shield, add the following line to your `.conf` file of your user config directory as such:
18-
19-
```ini
20-
CONFIG_ZMK_BACKLIGHT=y
21-
```
22-
23-
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).
24-
25-
## Configuring Backlight
26-
27-
There are various Kconfig options used to configure the backlight feature. These can all be set in the `.conf` file.
28-
29-
| Option | Description | Default |
30-
| ------------------------------------ | ----------------------------------------------------- | ------- |
31-
| `CONFIG_ZMK_BACKLIGHT_BRT_STEP` | Brightness step in percent | 20 |
32-
| `CONFIG_ZMK_BACKLIGHT_BRT_START` | Default brightness in percent | 40 |
33-
| `CONFIG_ZMK_BACKLIGHT_ON_START` | Default backlight state | y |
34-
| `CONFIG_ZMK_BACKLIGHT_AUTO_OFF_IDLE` | Turn off backlight when keyboard goes into idle state | n |
35-
| `CONFIG_ZMK_BACKLIGHT_AUTO_OFF_USB` | Turn off backlight when USB is disconnected | n |
36-
37-
## Adding Backlight to a Board or a Shield
10+
Please see [lighting feature page](../../../features/lighting.md#backlight) for an introduction on the feature.
3811

3912
<Tabs
40-
defaultValue="shieldpin"
41-
values={[
42-
{label: 'Adding to a board', value: 'boardpin'},{label: 'Adding to a shield', value: 'shieldpin'},
13+
defaultValue="shieldpin"
14+
values={[
15+
{label: 'Adding to a board', value: 'boardpin'},{label: 'Adding to a shield', value: 'shieldpin'},
4316
]}>
4417

4518
<TabItem value="boardpin">
@@ -59,8 +32,9 @@ endif # ZMK_BACKLIGHT
5932
```
6033

6134
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.
35+
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.
6236

63-
The pinctrl file has a `&pinctrl` node that encompasses all pinctrl settings, including I2C or SPI peripherals (e.g. WS2812 LEDs, Battery fuel gauges):
37+
The pinctrl file has a `&pinctrl` node that encompasses all pinctrl settings, including I2C or SPI peripherals (e.g. WS2812 LEDs, battery fuel gauges):
6438

6539
```dts
6640
&pinctrl {
@@ -161,6 +135,8 @@ Then add the following lines to your `.overlay` file:
161135
};
162136
```
163137

138+
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.
139+
164140
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_).
165141

166142
For example, _P1.13_ would give you `(PWM_OUT0, 1, 13)` and _P0.15_ would give you `(PWM_OUT0, 0, 15)`.

‎docs/docs/development/hardware-integration/lighting/index.mdx

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: Lighting
3+
sidebar_label: Lighting
4+
---
5+
6+
import DocCardList from "@theme/DocCardList";
7+
8+
The following pages detail adding lighting support to ZMK keyboards, which currently supports two lighting systems: underglow and backlight.
9+
10+
:::warning
11+
12+
Although the naming of the systems might imply it, which system you use typically does _not_ depend on the physical location of the LEDs.
13+
Instead, you should use the one that supports the LED hardware type that your keyboard has.
14+
15+
:::
16+
17+
<DocCardList />

‎docs/docs/features/underglow.md ‎docs/docs/development/hardware-integration/lighting/underglow.md

+3-54
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,13 @@
11
---
22
title: RGB Underglow
33
sidebar_label: RGB Underglow
4+
description: Lighting system that controls strips of RGB LEDs.
45
---
56

6-
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.
7-
8-
:::info
9-
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).
10-
:::
11-
12-
ZMK relies on Zephyr's `led-strip` drivers for this feature. The following LEDs/LED families have been implemented:
13-
14-
- WS2812 (includes WS2812B, WS2813, SK6812, and others)
15-
- APA102
16-
- LPD880x (includes LPD8803, LPD8806, and others)
17-
18-
The WS2812 LED family is by far the most popular of these types, so this page will primarily focus on working with it.
19-
20-
Here you can see the RGB underglow feature in action using WS2812 LEDs.
21-
22-
<figure class="video-container">
23-
<iframe src="//www.youtube.com/embed/2KJkq8ssDU0" frameborder="0" allowfullscreen width="100%"></iframe>
24-
</figure>
25-
26-
## Enabling RGB Underglow
27-
28-
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.
29-
For example:
30-
31-
```ini
32-
CONFIG_ZMK_RGB_UNDERGLOW=y
33-
# Use the STRIP config specific to the LEDs you're using
34-
CONFIG_WS2812_STRIP=y
35-
```
36-
37-
See [Configuration Overview](/docs/config) for more instructions on how to use Kconfig.
38-
39-
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).
40-
41-
### Modifying the Number of LEDs
42-
43-
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.
44-
45-
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):
46-
47-
```dts
48-
&led_strip {
49-
chain-length = <21>;
50-
};
51-
```
52-
53-
For split keyboards, set `chain-length` to the number of LEDs installed on each half.
54-
55-
## Configuring RGB Underglow
56-
57-
See [RGB underglow configuration](/docs/config/underglow).
58-
59-
## Adding RGB Underglow to a Board
7+
Please see [lighting feature page](../../../features/lighting.md#rgb-underglow) for an introduction on the feature.
608

619
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.
10+
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.
6211

6312
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.
6413

0 commit comments

Comments
 (0)