Jacob/zmk
1
0
Fork 0
forked from kofal.net/zmk
Code Pull Requests Activity

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

Browse Source 
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
This commit is contained in:
Cem Aksoylar
2025-01-13 21:14:25 -08:00
committed by GitHub
parent 8dddb1d9d7
commit 700e9b264f
17 changed files with 244 additions and 171 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
docs/docs/config/backlight.md
View File

@@ -1,40 +0,0 @@
---
title: Backlight Configuration
sidebar_label: Backlight
---
See the [backlight feature page](../features/backlight.mdx) for more details, including instructions 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 feature page](../features/backlight.mdx) for examples of the properties that must be set to enable backlighting.

54
docs/docs/config/underglow.md → docs/docs/config/lighting.md
View File

@@ -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.

30
docs/docs/development/hardware-integration/battery.md Normal file
View File

@@ -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";
};
}
```

42
docs/docs/features/backlight.mdx → docs/docs/development/hardware-integration/lighting/backlight.mdx
View File

@@ -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)`.

17
docs/docs/development/hardware-integration/lighting/index.mdx Normal file
View File

@@ -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 />

57
docs/docs/features/underglow.md → docs/docs/development/hardware-integration/lighting/underglow.md
View File

@@ -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.

24
docs/docs/features/battery.md
View File

@@ -15,25 +15,5 @@ Windows may not properly ask the keyboard to notify it of changes in battery lev
## Adding a Battery Sensor to a 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";
};
}
```
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.
If you are using a custom board, see [battery sensing hardware integration page](../development/hardware-integration/battery.md) to add support.

105
docs/docs/features/lighting.md Normal file
View File

@@ -0,0 +1,105 @@
---
title: Lighting
sidebar_label: Lighting
---
ZMK supports two distinct systems in order to control lighting hardware integrated into keyboards.
Your keyboard likely uses only one type, depending on the type of LED hardware it supports:
- [RGB underglow](#rgb-underglow) system controls LED strips composed of addressable RGB LEDs.
Most keyboards that have multi-color lighting utilizes these.
- [Backlight](#backlight) system controls parallel-connected, non-addressable, single color LEDs.
These are found on keyboards that have a single color backlight that only allows for brightness control.
:::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, as described above.
:::
## RGB Underglow
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 section below](#backlight).
:::
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](../config/index.md) for more instructions on how to use Kconfig.
If your board or shield does not have RGB underglow configured, refer to the [Adding RGB Underglow Support to a Keyboard](#adding-rgb-underglow-support-to-a-keyboard) section.
#### 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](../config/lighting.md#rgb-underglow).
### Adding RGB Underglow Support to a Keyboard
See [RGB underglow hardware integration page](../development/hardware-integration/lighting/underglow.md) on adding underglow support to a ZMK keyboard.
## Backlight
Backlight is a feature used to control an array of LEDs, usually placed through or under switches.
:::info
Unlike [RGB underglow](#rgb-underglow), 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.
See [backlight configuration](../config/lighting.md#backlight) for details.
### Adding Backlight to a Board or a Shield
See [backlight hardware integration page](../development/hardware-integration/lighting/backlight.mdx) for information on adding backlight support to a ZMK keyboard.

3
docs/docs/intro.md
View File

@@ -28,8 +28,7 @@ ZMK is currently missing some features found in other popular firmware. This tab
| [Media](keymaps/list-of-keycodes.mdx#media-controls) & [Consumer](keymaps/list-of-keycodes.mdx#consumer-controls) Codes | ✅ | ✅ | ✅ |
| [Encoders](features/encoders.md) | ✅ | ✅ | ✅ |
| [Display Support](features/displays.md)[^1] | 🚧 | 🚧 | ✅ |
| [RGB Underglow](features/underglow.md) | ✅ | ✅ | ✅ |
| [Backlight](features/backlight.mdx) | ✅ | ✅ | ✅ |
| [LED-based Lighting](features/lighting.md) | ✅ | ✅ | ✅ |
| One Shot Keys | ✅ | ✅ | ✅ |
| [Combo Keys](keymaps/combos.md) | ✅ | | ✅ |
| [Macros](keymaps/behaviors/macros.md) | ✅ | ✅ | ✅ |

4
docs/docs/keymaps/behaviors/backlight.md
View File

@@ -5,7 +5,7 @@ sidebar_label: Backlight
## Summary
This page contains [backlight](../../features/backlight.mdx) behaviors supported by ZMK.
This page contains [backlight](../../features/lighting.md#backlight) behaviors supported by ZMK.
## Backlight Action Defines
@@ -38,7 +38,7 @@ Here is a table describing the action for each define:
:::note[Backlight settings persistence]
The backlight settings that are changed via the `&bl` behavior will be saved to flash storage and hence persist across restarts and firmware flashes.
They will also override the start values set by [`CONFIG_ZMK_BACKLIGHT_*_START` settings](../../config/backlight.md#kconfig).
They will also override the start values set by [`CONFIG_ZMK_BACKLIGHT_*_START` settings](../../config/lighting.md#kconfig-1).
However the settings will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE`](../../config/system.md#general) milliseconds in order to reduce potential wear on the flash memory.
:::

4
docs/docs/keymaps/behaviors/underglow.md
View File

@@ -5,7 +5,7 @@ sidebar_label: RGB Underglow
## Summary
This page contains [RGB Underglow](../../features/underglow.md) behaviors supported by ZMK.
This page contains [RGB Underglow](../../features/lighting.md#rgb-underglow) behaviors supported by ZMK.
## RGB Action Defines
@@ -57,7 +57,7 @@ Value Limits:
:::note[RGB settings persistence]
The RGB settings that are changed via the `&rgb_ug` behavior will be saved to flash storage and hence persist across restarts and firmware flashes.
They will also override the start values set by [`CONFIG_ZMK_RGB_*_START` settings](../../config/underglow.md#kconfig).
They will also override the start values set by [`CONFIG_ZMK_RGB_*_START` settings](../../config/lighting.md#kconfig).
However the settings will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE`](../../config/system.md#general) milliseconds in order to reduce potential wear on the flash memory.
:::