mirror of https://github.com/zmkfirmware/zmk.git
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
This commit is contained in:
Cem Aksoylar
GitHub
parent
8dddb1d9d7
commit
700e9b264f
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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 {
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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";
|
||||
};
|
||||
}
|
||||
```
|
||||
|
|
@ -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)`.
|
||||
|
|
@ -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 />
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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) | ✅ | ✅ | ✅ |
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -41,8 +41,7 @@ module.exports = {
|
|||
"features/encoders",
|
||||
"features/pointing",
|
||||
"features/displays",
|
||||
"features/backlight",
|
||||
"features/underglow",
|
||||
"features/lighting",
|
||||
"features/studio",
|
||||
],
|
||||
},
|
||||
|
|
@ -120,19 +119,18 @@ module.exports = {
|
|||
},
|
||||
collapsed: true,
|
||||
items: [
|
||||
"config/backlight",
|
||||
"config/battery",
|
||||
"config/behaviors",
|
||||
"config/bluetooth",
|
||||
"config/combos",
|
||||
"config/displays",
|
||||
"config/encoders",
|
||||
"config/lighting",
|
||||
"config/pointing",
|
||||
"config/keymap",
|
||||
"config/layout",
|
||||
"config/kscan",
|
||||
"config/power",
|
||||
"config/underglow",
|
||||
"config/system",
|
||||
"config/studio",
|
||||
],
|
||||
|
|
@ -157,6 +155,20 @@ module.exports = {
|
|||
"development/hardware-integration/encoders",
|
||||
"development/hardware-integration/soft-off-setup",
|
||||
"development/hardware-integration/pointing",
|
||||
"development/hardware-integration/battery",
|
||||
{
|
||||
type: "category",
|
||||
label: "Lighting",
|
||||
link: {
|
||||
type: "doc",
|
||||
id: "development/hardware-integration/lighting/index",
|
||||
},
|
||||
collapsed: true,
|
||||
items: [
|
||||
"development/hardware-integration/lighting/underglow",
|
||||
"development/hardware-integration/lighting/backlight",
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
|
|
|
|||
|
|
@ -2,9 +2,12 @@
|
|||
/docs/features/keymaps /docs/keymaps 301
|
||||
/docs/features/combos /docs/keymaps/combos 301
|
||||
/docs/features/conditional-layers /docs/keymaps/conditional-layers 301
|
||||
/docs/features/encoders /docs/keymaps/encoders 301
|
||||
/docs/features/underglow /docs/features/lighting#rgb-underglow 301
|
||||
/docs/features/backlight /docs/features/lighting#backlight 301
|
||||
/docs/codes/modifiers /docs/keymaps/modifiers 301
|
||||
/docs/codes/* /docs/keymaps/list-of-keycodes 301
|
||||
/docs/config/backlight /docs/config/lighting#backlight 301
|
||||
/docs/config/underglow /docs/config/lighting#rgb-underglow 301
|
||||
/docs/features/beta-testing /docs/features/modules#beta-testing 301
|
||||
/docs/development/setup /docs/development/local-toolchain/setup 301
|
||||
/docs/development/boards-shields-keymaps /docs/development/hardware-integration/boards-shields-keymaps 301
|
||||
|
|
|
|||
Loading…
Reference in New Issue