Browse Source

feat(docs): add backlight documentation

xmkb
Alessandro Bortolin 3 years ago committed by Pete Johanson
parent
commit
da41391b1f
  1. 2
      docs/blog/2021-01-27-zmk-sotf-4.md
  2. 48
      docs/docs/behaviors/backlight.md
  3. 15
      docs/docs/behaviors/underglow.md
  4. 1
      docs/docs/development/hardware-metadata-files.md
  5. 115
      docs/docs/features/backlight.md
  6. 1
      docs/docs/hardware.mdx
  7. 1
      docs/docs/intro.md
  8. 4
      docs/sidebars.js

2
docs/blog/2021-01-27-zmk-sotf-4.md

@ -76,7 +76,7 @@ to your keymap will send `ESC` when pressed on its own, but will send `` ` `` wh @@ -76,7 +76,7 @@ to your keymap will send `ESC` when pressed on its own, but will send `` ` `` wh
#### RGB Underglow Color Selection
[mcrosson] updated the [RGB Underglow behavior](/docs/behaviors/lighting#rgb-underglow) to allow [binding an explicit color selection](/docs/behaviors/lighting#examples) to a key position.
[mcrosson] updated the [RGB Underglow behavior](/docs/behaviors/underglow) to allow [binding an explicit color selection](/docs/behaviors/underglow#examples) to a key position.
#### Keymap Upgrader

48
docs/docs/behaviors/backlight.md

@ -0,0 +1,48 @@ @@ -0,0 +1,48 @@
---
title: Backlight Behavior
sidebar_label: Backlight
---
## Summary
This page contains [backlight](../features/backlight.md) behaviors supported by ZMK.
## Backlight Action Defines
Backlight actions defines are provided through the [`dt-bindings/zmk/backlight.h`](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/backlight.h) header,
which is added at the top of the keymap file:
```
#include <dt-bindings/zmk/backlight.h>
```
This will allow you to reference the actions defined in this header such as `BL_TOG`.
Here is a table describing the action for each define:
| Define | Action |
| -------- | ---------------------------------------- |
| `BL_TOG` | Toggles the backlight on and off |
| `BL_ON` | Turn on backlight on and off |
| `BL_OFF` | Toggles the backlight feature on and off |
| `BL_INC` | Increase backlight brightness |
| `BL_DEC` | Decrease backlight brightness |
## Behavior Binding
- Reference: `&bl`
- Parameter #1: The backlight action define, e.g. `BL_TOG` or `BL_INC`
### Examples
1. Toggle backlight on/off
```
&bl BL_TOG
```
1. Increase backlight brightness
```
&bl BL_INC
```

15
docs/docs/behaviors/lighting.md → docs/docs/behaviors/underglow.md

@ -1,12 +1,11 @@ @@ -1,12 +1,11 @@
---
title: Lighting Behavior
sidebar_label: Lighting
title: RGB Underglow Behavior
sidebar_label: RGB Underglow
---
## 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.
This page contains [RGB Underglow](../features/underglow.md) behaviors supported by ZMK.
## RGB Action Defines
@ -36,11 +35,7 @@ Here is a table describing the action for each define: @@ -36,11 +35,7 @@ Here is a table describing the action for each define:
| `RGB_EFR` | Cycles the RGB feature's effect reverse |
| `RGB_COLOR_HSB` | Sets a specific [HSB (HSV)](https://en.wikipedia.org/wiki/HSL_and_HSV) value for the underglow |
## RGB Underglow
The "RGB underglow" behavior completes an RGB action given on press.
### Behavior Binding
## Behavior Binding
- Reference: `&rgb_ug`
- Parameter #1: The RGB action define, e.g. `RGB_TOG` or `RGB_BRI`
@ -58,7 +53,7 @@ Value Limits: @@ -58,7 +53,7 @@ Value Limits:
:::
### Examples
## Examples
1. Toggle underglow on/off

1
docs/docs/development/hardware-metadata-files.md

@ -94,6 +94,7 @@ Boards and shields should document the sets of hardware features found on them u @@ -94,6 +94,7 @@ Boards and shields should document the sets of hardware features found on them u
- `display` - Indicates the hardware includes a display for use with the ZMK display functionality.
- `encoder` - Indicates the hardware contains one or more rotary encoders.
- `underglow` - Indicates the hardware includes underglow LEDs.
- `backlight` - Indicates the hardware includes backlight LEDs.
- `pointer` (future) - Used to indicate the hardware includes one or more pointer inputs, e.g. joystick, touchpad, or trackpoint.
### Siblings

115
docs/docs/features/backlight.md

@ -0,0 +1,115 @@ @@ -0,0 +1,115 @@
---
title: Backlight
sidebar_label: Backlight
---
Backlight is a feature used to control array of LEDs, usually placed through or under switches. Unlike [RGB Underglow](underglow.md), backlight currently allows only one color per LED, also LEDs are not addressable, so you can't control individual LEDs.
## Enabling Backlight
To enable backlight on your board or shield, simply enable the `CONFIG_ZMK_BACKLIGHT` configuration values in the `.conf` file of your user config directory as such:
```
CONFIG_ZMK_BACKLIGHT=y
```
If your board or shield does not have backlight configured, refer to [Adding Backlight to a Board](#adding-backlight-to-a-board).
## 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 | y |
| `CONFIG_ZMK_BACKLIGHT_AUTO_OFF_USB` | Turn off backlight when USB is disconnected | n |
## Adding Backlight to a Board
Backlight is always added to a board, not a shield.
If you have a shield with backlight, you must add a `boards/` directory within your shield folder to define the backlight individually for each board that supports the shield.
Inside the `boards/` folder, you define a `<board>.overlay` for each different board.
First, you need to enable PWM by adding the following lines to your `.overlay` file:
```
&pwm0 {
status = "okay";
ch0-pin = <45>;
/* ch0-inverted; */
};
```
The value `ch0-pin` represents the pin that controls the LEDs. To calculate the value to use, you need a bit of math. You need the hardware port and run it through a function.
**32 \* X + Y** = `<Pin number>` where X is first part of the hardware port "PX.01" and Y is the second part of the hardware port "P1.Y".
For example, _P1.13_ would give you _32 \* 1 + 13_ = `<45>` and _P0.15_ would give you _32 \* 0 + 15_ = `<15>`.
If your board uses a P-channel MOSFET to control backlight instead of a N-channel MOSFET, you may want to enable `ch0-inverted`.
Then you have to add the following lines to your `.dtsi` file inside the root devicetree node:
```
backlight: pwmleds {
compatible = "pwm-leds";
label = "Backlight LEDs";
pwm_led_0 {
pwms = <&pwm0 45>;
};
};
```
The value inside `pwm_led_0` must be the same as you used before.
:::info
Note that every LED inside of the backlight node will be treated as a backlight LED, so if you have other PWM LEDs you need to declare them in a separate node. Refer to [Multiple backlight LEDs](#multiple-backlight-leds) if you have multiple backlight LEDs.
:::
Finally you need to add backlight to the `chosen` element of the root devicetree node:
```
chosen {
...
zmk,backlight = &backlight;
};
```
### Multiple backlight LEDs
It is possible to control multiple backlight LEDs at the same time. This is useful if, for example, you have a Caps Lock LED connected to a different pin and you want it to be part of the backlight.
In order to do that, first you need to enable PWM for each pin:
```
&pwm0 {
status = "okay";
ch0-pin = <45>; /* LED 0 */
ch1-pin = <46>; /* LED 1 */
ch2-pin = <47>; /* LED 2 */
...
};
```
This part may vary based on your MCU as different MCUs may have a different number of modules and channels.
Then you can simply add each of your LED to the backlight node:
```
backlight: pwmleds {
compatible = "pwm-leds";
label = "Backlight LEDs";
pwm_led_0 {
pwms = <&pwm0 45>; /* LED 0 */
};
pwm_led_1 {
pwms = <&pwm0 46>; /* LED 1 */
};
pwm_led_2 {
pwms = <&pwm0 47>; /* LED 2 */
};
...
};
```

1
docs/docs/hardware.mdx

@ -18,6 +18,7 @@ In addition to the basic keyboard functionality, there is some initial support f @@ -18,6 +18,7 @@ In addition to the basic keyboard functionality, there is some initial support f
- Encoders
- Displays
- RGB Underglow
- Backlight
Until detailed documentation is available, feel free to ask questions about how these are supported in the [Discord server](https://zmk.dev/community/discord/invite).

1
docs/docs/intro.md

@ -28,6 +28,7 @@ ZMK is currently missing some features found in other popular firmware. This tab @@ -28,6 +28,7 @@ ZMK is currently missing some features found in other popular firmware. This tab
| [Encoders](features/encoders.md)[^1] | ✅ | ✅ | ✅ |
| [Display Support](features/displays.md)[^2] | 🚧 | 🚧 | ✅ |
| [RGB Underglow](features/underglow.md) | ✅ | ✅ | ✅ |
| [Backlight](features/backlight.md) | ✅ | ✅ | ✅ |
| One Shot Keys | ✅ | ✅ | ✅ |
| [Combo Keys](features/combos.md) | ✅ | | ✅ |
| Macros | 🚧 | ✅ | ✅ |

4
docs/sidebars.js

@ -16,6 +16,7 @@ module.exports = { @@ -16,6 +16,7 @@ module.exports = {
"features/displays",
"features/encoders",
"features/underglow",
"features/backlight",
"features/beta-testing",
],
Behaviors: [
@ -31,7 +32,8 @@ module.exports = { @@ -31,7 +32,8 @@ module.exports = {
"behaviors/reset",
"behaviors/bluetooth",
"behaviors/outputs",
"behaviors/lighting",
"behaviors/underglow",
"behaviors/backlight",
"behaviors/power",
],
Codes: [

Loading…
Cancel
Save