feat(docs): add backlight documentation
This commit is contained in:
Alessandro Bortolin
Pete Johanson
parent
85b2d30bd5
commit
da41391b1f
8 changed files with 175 additions and 12 deletions
docs
|
|
@ -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
Normal file
48
docs/docs/behaviors/backlight.md
Normal file
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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:
|
|||
| `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:
|
|||
|
||||
:::
|
||||
|
||||
### Examples
|
||||
## Examples
|
||||
|
||||
1. Toggle underglow on/off
|
||||
|
||||
|
|
@ -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
Normal file
115
docs/docs/features/backlight.md
Normal file
|
|
@ -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 */
|
||||
};
|
||||
...
|
||||
};
|
||||
```
|
||||
|
|
@ -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).
|
||||
|
||||
|
|
|
|||
|
|
@ -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 | 🚧 | ✅ | ✅ |
|
||||
|
|
|
|||
|
|
@ -16,6 +16,7 @@ module.exports = {
|
|||
"features/displays",
|
||||
"features/encoders",
|
||||
"features/underglow",
|
||||
"features/backlight",
|
||||
"features/beta-testing",
|
||||
],
|
||||
Behaviors: [
|
||||
|
|
@ -31,7 +32,8 @@ module.exports = {
|
|||
"behaviors/reset",
|
||||
"behaviors/bluetooth",
|
||||
"behaviors/outputs",
|
||||
"behaviors/lighting",
|
||||
"behaviors/underglow",
|
||||
"behaviors/backlight",
|
||||
"behaviors/power",
|
||||
],
|
||||
Codes: [
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue