-
-
Notifications
You must be signed in to change notification settings - Fork 2.9k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: Refactor lighting hardware integrations to new section
- Loading branch information
Showing
9 changed files
with
219 additions
and
176 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
17 changes: 17 additions & 0 deletions
17
docs/docs/development/hardware-integration/lighting/index.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 /> |
141 changes: 141 additions & 0 deletions
141
docs/docs/development/hardware-integration/lighting/underglow.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 `<board>.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 <dt-bindings/led/led.h> | ||
| &pinctrl { | ||
| spi3_default: spi3_default { | ||
| group1 { | ||
| psels = <NRF_PSEL(SPIM_MOSI, 0, 6)>; | ||
| }; | ||
| }; | ||
| spi3_sleep: spi3_sleep { | ||
| group1 { | ||
| psels = <NRF_PSEL(SPIM_MOSI, 0, 6)>; | ||
| 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 = <LED_COLOR_ID_GREEN | ||
| LED_COLOR_ID_RED | ||
| LED_COLOR_ID_BLUE>; | ||
| }; | ||
| }; | ||
| ``` | ||
|
|
||
| :::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 <dt-bindings/led/led.h> | ||
| &pinctrl { | ||
| pio0_spi0_default: pio0_spi0_default { | ||
| group1 { | ||
| pinmux = <PIO0_P0>; | ||
| }; | ||
| }; | ||
| }; | ||
| &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 = <LED_COLOR_ID_GREEN | ||
| LED_COLOR_ID_RED | ||
| LED_COLOR_ID_BLUE>; | ||
| }; | ||
| }; | ||
| }; | ||
| ``` | ||
|
|
||
| ### 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; | ||
| }; | ||
| }; | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
Oops, something went wrong.