Browse Source

Merge pull request #78 from Nicell/docs/rgb

Add RGB documentation
xmkb
Pete Johanson 4 years ago committed by GitHub
parent
commit
bc6b11eb02
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
  1. 1
      app/boards/shields/kyria/boards/nice_nano.overlay
  2. 3
      app/boards/shields/kyria/kyria.conf
  3. 50
      docs/docs/behavior/lighting.md
  4. 118
      docs/docs/feature/underglow.md
  5. 6
      docs/sidebars.js
  6. 18
      docs/src/css/custom.css

1
app/boards/shields/kyria/boards/nice_nano.overlay

@ -1,6 +1,5 @@ @@ -1,6 +1,5 @@
&spi1 {
compatible = "nordic,nrf-spi";
/* Cannot be used together with i2c0. */
status = "okay";
mosi-pin = <6>;
// Unused pins, needed for SPI definition, but not used by the ws2812 driver itself.

3
app/boards/shields/kyria/kyria.conf

@ -4,3 +4,6 @@ @@ -4,3 +4,6 @@
# Uncomment the following line to enable the Kyria OLED Display
# CONFIG_ZMK_DISPLAY=y
# Uncomment the following line to enable RGB underglow
# CONFIG_ZMK_RGB_UNDERGLOW=y

50
docs/docs/behavior/lighting.md

@ -0,0 +1,50 @@ @@ -0,0 +1,50 @@
---
title: Lighting
---
## Summary
Lighting is often used for either aesthetics or for the practical purposes of lighting up keys in the dark.
Currently ZMK supports RGB underglow, which can be changed and configured using its behavior.
## RGB Action Defines
RGB actions defines are provided through the [`dt-bindings/zmk/rgb.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/rgb.h) header,
which is added at the top of the keymap file:
```
#include <dt-bindings/zmk/rgb.h>
```
This will allow you to reference the actions defined in this header such as `RGB_TOG`.
Here is a table describing the action for each define:
| Define | Action |
|-----------|-----------------------------------------------------------|
| `RGB_TOG` | Toggles the RGB feature on and off |
| `RGB_HUI` | Increases the hue of the RGB feature |
| `RGB_HUD` | Decreases the hue of the RGB feature |
| `RGB_SAI` | Increases the saturation of the RGB feature |
| `RGB_SAD` | Decreases the saturation of the RGB feature |
| `RGB_BRI` | Increases the brightness of the RGB feature |
| `RGB_BRD` | Decreases the brightness of the RGB feature |
| `RGB_SPI` | Increases the speed of the RGB feature effect's animation |
| `RGB_SPD` | Decreases the speed of the RGB feature effect's animation |
| `RGB_EFF` | Cycles the RGB feature's effect forwards |
| `RGB_EFR` | Cycles the RGB feature's effect reverse |
## RGB Underglow
The "RGB underglow" behavior completes an RGB action given on press.
### Behavior Binding
- Reference: `&rgb_ug`
- Parameter: The RGB action define, e.g. `RGB_TOG` or `RGB_BRI`
Example:
```
&rgb_ug RGB_TOG
```

118
docs/docs/feature/underglow.md

@ -1,5 +1,121 @@ @@ -1,5 +1,121 @@
---
title: RGB Underglow
sidebar_label: RGB Underglow
---
TODO: Documentation on 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.
ZMK supports all the RGB LEDs supported by Zephyr. Here's the current list supported:
- WS2812-ish (WS2812B, WS2813, SK6812, or compatible)
- APA102
- LPD880x (LPD8803, LPD8806, or compatible)
Of the compatible types, the WS2812 LED family is by far the most popular type. Currently each of these types of LEDs are expected to be run using SPI with a couple of exceptions.
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 `ZMK_RGB_UNDERGLOW` configuration value in the `.conf` file of your user config directory as such:
```
CONFIG_ZMK_RGB_UNDERGLOW=y
```
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).
## Configuring RGB Underglow
There are various Kconfig options used to configure the RGB underglow feature. These can all be set in the `.conf` file.
| Option | Description | Default |
| ---------------------------- | ---------------------------------------------- | ------- |
| `ZMK_RGB_UNDERGLOW_HUE_STEP` | Hue step in degrees of 360 used by RGB actions | `10` |
| `ZMK_RGB_UNDERGLOW_SAT_STEP` | Saturation step in percent used by RGB actions | `10` |
| `ZMK_RGB_UNDERGLOW_BRT_STEP` | Brightness step in percent used by RGB actions | `10` |
## Adding RGB Underglow to a Board
RGB underglow is always added to a board, not a shield. This is a consequence of needing to configure SPI to control the LEDs.
If you have a shield with RGB underglow, you must add a `boards/` directory within your shield folder to define the RGB underglow individually for each board that supports the shield.
Inside the `boards/` folder, you define a `<board>.overlay` for each different board.
For example, the Kyria shield has a `boards/nice_nano.overlay` file that defines the RGB underglow for the `nice_nano` board specifically.
The first step to adding support for underglow is to select you SPI output. With nRF52 boards, you can just use `&spi1` and define the pins you want to use.
For other boards, you must select an SPI definition that has the `MOSI` pin as your data pin going to your LED strip.
Here's an example of an nRF52 SPI definition:
```
&spi1 {
compatible = "nordic,nrf-spi";
status = "okay";
mosi-pin = <6>;
// Unused pins, needed for SPI definition, but not used by the ws2812 driver itself.
sck-pin = <5>;
miso-pin = <7>;
led_strip: ws2812@0 {
compatible = "worldsemi,ws2812-spi";
label = "WS2812";
/* 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>;
};
};
```
:::info
If you are configuring SPI for an nRF52840 (or other nRF52) based board, double check that you are using pins that aren't restricted to low frequency I/O.
Ignoring these restrictions may result in poor wireless performance. You can find the list of low frequency I/O pins [here](https://infocenter.nordicsemi.com/index.jsp?topic=%2Fps_nrf52840%2Fpin.html&cp=4_0_0_6_0).
:::
Here's another example for a non-nRF52 board on `spi1`:
```
&spi1 {
led_strip: ws2812@0 {
compatible = "worldsemi,ws2812-spi";
label = "WS2812";
/* SPI */
reg = <0>;
spi-max-frequency = <5250000>;
/* WS2812 */
chain-length = <10>; /* number of LEDs */
spi-one-frame = <0x70>; /* make sure to configure this properly for your SOC */
spi-zero-frame = <0x40>; /* make sure to configure this properly for your SOC */
};
};
```
Once you have your `led_strip` properly defined you need to add it to the root devicetree node `chosen` element:
```
/ {
chosen {
zmk,underglow = &led_strip;
};
};
```
Finally you need to enable the `ZMK_RGB_UNDERGLOW` configuration value in the `.conf` file of your board (or set a default in the `Kconfig.defconfig`):
```
CONFIG_ZMK_RGB_UNDERGLOW=y
```

6
docs/sidebars.js

@ -7,7 +7,11 @@ module.exports = { @@ -7,7 +7,11 @@ module.exports = {
"feature/encoders",
"feature/underglow",
],
Behaviors: ["behavior/key-press", "behavior/layers"],
Behaviors: [
"behavior/key-press",
"behavior/layers",
"behavior/lighting",
],
Development: [
"dev-clean-room",
"dev-setup",

18
docs/src/css/custom.css

@ -23,3 +23,21 @@ @@ -23,3 +23,21 @@
margin: 0 calc(-1 * var(--ifm-pre-padding));
padding: 0 var(--ifm-pre-padding);
}
.video-container {
height: 0;
margin: 0;
margin-bottom: 30px;
overflow: hidden;
padding-bottom: 56.25%;
padding-top: 30px;
position: relative;
}
.video-container iframe {
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 100%;
}

Loading…
Cancel
Save