diff --git a/docs/blog/2020-08-12-zmk-sotf-1.md b/docs/blog/2020-08-12-zmk-sotf-1.md index c93566b19..31c6ffc67 100644 --- 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 index 15a79500f..539f6dc79 100644 --- 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 ` 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 ` 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 index 55faeb41c..7abc2205b 100644 --- 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 index b0c8c4d89..0e9f3768e 100644 --- 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 deleted file mode 100644 index 8fed7ca66..000000000 --- a/docs/docs/config/backlight.md +++ /dev/null @@ -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. diff --git a/docs/docs/config/underglow.md b/docs/docs/config/lighting.md similarity index 50% rename from docs/docs/config/underglow.md rename to docs/docs/config/lighting.md index 952eb12b4..8734c70d6 100644 --- a/docs/docs/config/underglow.md +++ b/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 new file mode 100644 index 000000000..d32760690 --- /dev/null +++ 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 b/docs/docs/development/hardware-integration/lighting/backlight.mdx similarity index 78% rename from docs/docs/features/backlight.mdx rename to docs/docs/development/hardware-integration/lighting/backlight.mdx index 5debc3750..9d1d74433 100644 --- a/docs/docs/features/backlight.mdx +++ b/docs/docs/development/hardware-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. @@ -59,8 +32,9 @@ endif # ZMK_BACKLIGHT ``` Create a `-pinctrl.dtsi` file if it does not already exist, and include it at the beginning of the `.dts` file. `CONFIG_PINCTRL=y` must be added to `_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 new file mode 100644 index 000000000..7642fe06e --- /dev/null +++ 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. + +::: + + diff --git a/docs/docs/features/underglow.md b/docs/docs/development/hardware-integration/lighting/underglow.md similarity index 64% rename from docs/docs/features/underglow.md rename to docs/docs/development/hardware-integration/lighting/underglow.md index 4802b92bf..93fe64a7a 100644 --- a/docs/docs/features/underglow.md +++ b/docs/docs/development/hardware-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. - -
- -
- -## 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 `.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 `.overlay` for any of the boards the shield can be used with. Place all hardware-specific configurations in these `.overlay` files. diff --git a/docs/docs/features/battery.md b/docs/docs/features/battery.md index 14dd6661d..4d77d8058 100644 --- a/docs/docs/features/battery.md +++ b/docs/docs/features/battery.md @@ -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. diff --git a/docs/docs/features/lighting.md b/docs/docs/features/lighting.md new file mode 100644 index 000000000..3d64b8701 --- /dev/null +++ b/docs/docs/features/lighting.md @@ -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. + +
+ +
+ +### 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 `.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. diff --git a/docs/docs/intro.md b/docs/docs/intro.md index d5bf527ca..2d0c4c466 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -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) | ✅ | ✅ | ✅ | diff --git a/docs/docs/keymaps/behaviors/backlight.md b/docs/docs/keymaps/behaviors/backlight.md index 88445dc9f..6dbb6e7b2 100644 --- a/docs/docs/keymaps/behaviors/backlight.md +++ b/docs/docs/keymaps/behaviors/backlight.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. ::: diff --git a/docs/docs/keymaps/behaviors/underglow.md b/docs/docs/keymaps/behaviors/underglow.md index 5fda9a1db..ecffca756 100644 --- a/docs/docs/keymaps/behaviors/underglow.md +++ b/docs/docs/keymaps/behaviors/underglow.md @@ -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. ::: diff --git a/docs/sidebars.js b/docs/sidebars.js index 1199858a4..57f07fc30 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -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", + ], + }, ], }, { diff --git a/docs/static/_redirects b/docs/static/_redirects index de769e94b..7f53abb90 100644 --- a/docs/static/_redirects +++ b/docs/static/_redirects @@ -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