From adecb24d799e84350763186d76bce554c36ce1d6 Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Tue, 10 Dec 2024 20:45:58 -0800 Subject: [PATCH] docs: Refactor lighting hardware integrations to new category --- docs/blog/2022-04-02-zephyr-3-0.md | 2 +- docs/docs/config/backlight.md | 4 +- docs/docs/config/underglow.md | 4 +- .../lighting}/backlight.mdx | 41 +---- .../hardware-integration/lighting/index.mdx | 17 +++ .../lighting/underglow.md | 141 +++++++++++++++++ docs/docs/features/backlight.md | 29 ++++ docs/docs/features/underglow.md | 144 +----------------- docs/docs/intro.md | 2 +- docs/docs/keymaps/behaviors/backlight.md | 2 +- docs/sidebars.js | 13 ++ 11 files changed, 221 insertions(+), 178 deletions(-) rename docs/docs/{features => development/hardware-integration/lighting}/backlight.mdx (78%) create mode 100644 docs/docs/development/hardware-integration/lighting/index.mdx create mode 100644 docs/docs/development/hardware-integration/lighting/underglow.md create mode 100644 docs/docs/features/backlight.md diff --git a/docs/blog/2022-04-02-zephyr-3-0.md b/docs/blog/2022-04-02-zephyr-3-0.md index 15a79500f61..61cfe2b81fa 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/underglow#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/docs/config/backlight.md b/docs/docs/config/backlight.md index 8fed7ca66a5..9f85bf83833 100644 --- a/docs/docs/config/backlight.md +++ b/docs/docs/config/backlight.md @@ -3,7 +3,7 @@ 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 the [backlight feature page](../features/backlight.md) 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. @@ -37,4 +37,4 @@ 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. +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/config/underglow.md b/docs/docs/config/underglow.md index 952eb12b438..62b55b45566 100644 --- a/docs/docs/config/underglow.md +++ b/docs/docs/config/underglow.md @@ -3,7 +3,7 @@ title: RGB Underglow Configuration sidebar_label: RGB Underglow --- -See the [RGB Underglow feature page](../features/underglow.md) for more details, including instructions for adding underglow support to a board. +See the [RGB Underglow feature page](../features/underglow.md) 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. @@ -48,4 +48,4 @@ The `*_START` settings only determine the initial underglow state. Any changes y 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. 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 5debc375010..67a9d1d8eaa 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 [backlight feature page](../../../features/backlight.md) for an introduction on the feature. @@ -60,7 +33,7 @@ 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. -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 +134,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 00000000000..7642fe06eca --- /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/development/hardware-integration/lighting/underglow.md b/docs/docs/development/hardware-integration/lighting/underglow.md new file mode 100644 index 00000000000..11b172e47b4 --- /dev/null +++ b/docs/docs/development/hardware-integration/lighting/underglow.md @@ -0,0 +1,141 @@ +--- +title: RGB Underglow +sidebar_label: RGB Underglow +description: Lighting system that controls strips of RGB LEDs. +--- + +Please see [RGB underglow feature page](../../../features/underglow.md) 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. + +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. + +For example: the `kyria` shield has a [`boards/nice_nano_v2.overlay`](https://github.com/zmkfirmware/zmk/blob/main/app/boards/shields/kyria/boards/nice_nano_v2.overlay) and a [`boards/nrfmicro_13.overlay`](https://github.com/zmkfirmware/zmk/blob/main/app/boards/shields/kyria/boards/nrfmicro_13.overlay), which configure a WS2812 LED strip for the `nice_nano_v2` and `nrfmicro_13` boards respectively. + +### nRF52-Based Boards + +Using an SPI-based LED strip driver on the `&spi3` interface is the simplest option for nRF52-based boards. If possible, avoid using pins which are limited to low-frequency I/O for this purpose. The resulting interference may result in poor wireless performance. + +:::info + +The list of low frequency I/O pins for the nRF52840 can be found [here](https://docs.nordicsemi.com/bundle/ps_nrf52840/page/pin.html). + +::: + +The following example uses `P0.06` as the "Data In" pin of a WS2812-compatible LED strip: + +```dts +#include + +&pinctrl { + spi3_default: spi3_default { + group1 { + psels = ; + }; + }; + + spi3_sleep: spi3_sleep { + group1 { + psels = ; + low-power-enable; + }; + }; +}; + +&spi3 { + compatible = "nordic,nrf-spim"; + status = "okay"; + + pinctrl-0 = <&spi3_default>; + pinctrl-1 = <&spi3_sleep>; + pinctrl-names = "default", "sleep"; + + led_strip: ws2812@0 { + compatible = "worldsemi,ws2812-spi"; + + /* SPI */ + reg = <0>; /* ignored, but necessary for SPI bindings */ + spi-max-frequency = <4000000>; + + /* WS2812 */ + chain-length = <10>; /* number of LEDs */ + spi-one-frame = <0x70>; + spi-zero-frame = <0x40>; + color-mapping = ; + }; +}; +``` + +:::note + +Standard WS2812 LEDs use a wire protocol where the bits for the colors green, red, and blue values are sent in that order. +If your board/shield uses LEDs that require the data sent in a different order, the `color-mapping` property ordering should be changed to match. + +::: + +### Other Boards + +Be sure to check the Zephyr documentation for the LED strip and necessary hardware bindings. Not every board has an `spi3` node, or configures `pinctrl` the same way. Reconcile this with any hardware restrictions found in the manufacturer's datasheet. Additional hardware interfaces may need to be enabled via Kconfig. + +For example: the `sparkfun_pro_micro_rp2040` board can utilize SPI via PIO to run a WS2812 strip on `GP0`: + +```dts +#include + +&pinctrl { + pio0_spi0_default: pio0_spi0_default { + group1 { + pinmux = ; + }; + }; +}; + +&pio0 { + status = "okay"; + + pio0_spi0: pio0_spi0 { + pinctrl-0 = <&pio0_spi0_default>; + pinctrl-names = "default"; + + compatible = "raspberrypi,pico-spi-pio"; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&system_clk>; + clock-frequency = <4000000>; + + clk-gpios = <&gpio0 10 GPIO_ACTIVE_HIGH>; /* Must be defined. Select a pin that is not used elsewhere. */ + mosi-gpios = <&pro_micro 1 GPIO_ACTIVE_HIGH>; /* Data In pin. */ + miso-gpios = <&pro_micro 1 GPIO_ACTIVE_HIGH>; /* Must be defined. Re-using the DI pin is OK for WS2812. */ + + led_strip: ws2812@0 { + compatible = "worldsemi,ws2812-spi"; + + /* SPI */ + reg = <0>; /* ignored, but necessary for SPI bindings */ + spi-max-frequency = <4000000>; + + /* WS2812 */ + chain-length = <10>; /* number of LEDs */ + spi-one-frame = <0x70>; + spi-zero-frame = <0x40>; + color-mapping = ; + }; + }; +}; +``` + +### Final Steps + +Once the `led_strip` is properly defined, add it to the `chosen` node under the root devicetree node: + +```dts +/ { + chosen { + zmk,underglow = &led_strip; + }; +}; +``` diff --git a/docs/docs/features/backlight.md b/docs/docs/features/backlight.md new file mode 100644 index 00000000000..c2f8aeffc4e --- /dev/null +++ b/docs/docs/features/backlight.md @@ -0,0 +1,29 @@ +--- +title: Backlight +sidebar_label: Backlight +--- + +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. +See [backlight configuration](../config/backlight.md) 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/features/underglow.md b/docs/docs/features/underglow.md index 4802b92bf23..711e0cd15cf 100644 --- a/docs/docs/features/underglow.md +++ b/docs/docs/features/underglow.md @@ -6,7 +6,7 @@ sidebar_label: 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](backlight.mdx). +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.md). ::: ZMK relies on Zephyr's `led-strip` drivers for this feature. The following LEDs/LED families have been implemented: @@ -34,9 +34,9 @@ CONFIG_ZMK_RGB_UNDERGLOW=y CONFIG_WS2812_STRIP=y ``` -See [Configuration Overview](/docs/config) for more instructions on how to use Kconfig. +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 [Adding RGB Underglow to a Board](#adding-rgb-underglow-to-a-board). +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 @@ -54,140 +54,8 @@ For split keyboards, set `chain-length` to the number of LEDs installed on each ## Configuring RGB Underglow -See [RGB underglow configuration](/docs/config/underglow). +See [RGB underglow configuration](../config/underglow.md). -## Adding RGB Underglow to a Board +## Adding RGB Underglow Support to a Keyboard -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. - -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. - -For example: the `kyria` shield has a [`boards/nice_nano_v2.overlay`](https://github.com/zmkfirmware/zmk/blob/main/app/boards/shields/kyria/boards/nice_nano_v2.overlay) and a [`boards/nrfmicro_13.overlay`](https://github.com/zmkfirmware/zmk/blob/main/app/boards/shields/kyria/boards/nrfmicro_13.overlay), which configure a WS2812 LED strip for the `nice_nano_v2` and `nrfmicro_13` boards respectively. - -### nRF52-Based Boards - -Using an SPI-based LED strip driver on the `&spi3` interface is the simplest option for nRF52-based boards. If possible, avoid using pins which are limited to low-frequency I/O for this purpose. The resulting interference may result in poor wireless performance. - -:::info - -The list of low frequency I/O pins for the nRF52840 can be found [here](https://docs.nordicsemi.com/bundle/ps_nrf52840/page/pin.html). - -::: - -The following example uses `P0.06` as the "Data In" pin of a WS2812-compatible LED strip: - -```dts -#include - -&pinctrl { - spi3_default: spi3_default { - group1 { - psels = ; - }; - }; - - spi3_sleep: spi3_sleep { - group1 { - psels = ; - low-power-enable; - }; - }; -}; - -&spi3 { - compatible = "nordic,nrf-spim"; - status = "okay"; - - pinctrl-0 = <&spi3_default>; - pinctrl-1 = <&spi3_sleep>; - pinctrl-names = "default", "sleep"; - - led_strip: ws2812@0 { - compatible = "worldsemi,ws2812-spi"; - - /* SPI */ - reg = <0>; /* ignored, but necessary for SPI bindings */ - spi-max-frequency = <4000000>; - - /* WS2812 */ - chain-length = <10>; /* number of LEDs */ - spi-one-frame = <0x70>; - spi-zero-frame = <0x40>; - color-mapping = ; - }; -}; -``` - -:::note - -Standard WS2812 LEDs use a wire protocol where the bits for the colors green, red, and blue values are sent in that order. -If your board/shield uses LEDs that require the data sent in a different order, the `color-mapping` property ordering should be changed to match. - -::: - -### Other Boards - -Be sure to check the Zephyr documentation for the LED strip and necessary hardware bindings. Not every board has an `spi3` node, or configures `pinctrl` the same way. Reconcile this with any hardware restrictions found in the manufacturer's datasheet. Additional hardware interfaces may need to be enabled via Kconfig. - -For example: the `sparkfun_pro_micro_rp2040` board can utilize SPI via PIO to run a WS2812 strip on `GP0`: - -```dts -#include - -&pinctrl { - pio0_spi0_default: pio0_spi0_default { - group1 { - pinmux = ; - }; - }; -}; - -&pio0 { - status = "okay"; - - pio0_spi0: pio0_spi0 { - pinctrl-0 = <&pio0_spi0_default>; - pinctrl-names = "default"; - - compatible = "raspberrypi,pico-spi-pio"; - #address-cells = <1>; - #size-cells = <0>; - clocks = <&system_clk>; - clock-frequency = <4000000>; - - clk-gpios = <&gpio0 10 GPIO_ACTIVE_HIGH>; /* Must be defined. Select a pin that is not used elsewhere. */ - mosi-gpios = <&pro_micro 1 GPIO_ACTIVE_HIGH>; /* Data In pin. */ - miso-gpios = <&pro_micro 1 GPIO_ACTIVE_HIGH>; /* Must be defined. Re-using the DI pin is OK for WS2812. */ - - led_strip: ws2812@0 { - compatible = "worldsemi,ws2812-spi"; - - /* SPI */ - reg = <0>; /* ignored, but necessary for SPI bindings */ - spi-max-frequency = <4000000>; - - /* WS2812 */ - chain-length = <10>; /* number of LEDs */ - spi-one-frame = <0x70>; - spi-zero-frame = <0x40>; - color-mapping = ; - }; - }; -}; -``` - -### Final Steps - -Once the `led_strip` is properly defined, add it to the `chosen` node under the root devicetree node: - -```dts -/ { - chosen { - zmk,underglow = &led_strip; - }; -}; -``` +See [RGB underglow hardware integration page](../development/hardware-integration/lighting/underglow.md) on adding underglow support to a ZMK keyboard. diff --git a/docs/docs/intro.md b/docs/docs/intro.md index d5bf527ca5d..1f872905e97 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -29,7 +29,7 @@ ZMK is currently missing some features found in other popular firmware. This tab | [Encoders](features/encoders.md) | ✅ | ✅ | ✅ | | [Display Support](features/displays.md)[^1] | 🚧 | 🚧 | ✅ | | [RGB Underglow](features/underglow.md) | ✅ | ✅ | ✅ | -| [Backlight](features/backlight.mdx) | ✅ | ✅ | ✅ | +| [Backlight](features/backlight.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 88445dc9f29..2e2e84f2894 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/backlight.md) behaviors supported by ZMK. ## Backlight Action Defines diff --git a/docs/sidebars.js b/docs/sidebars.js index 28a6b9de7d0..3358b3a3912 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -157,6 +157,19 @@ module.exports = { "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", + ], + }, ], }, {