docs(backlight): improve documentation
This commit is contained in:
Alessandro Bortolin
Pete Johanson
parent
13a4515300
commit
be94e04963
|
|
@ -3,19 +3,20 @@ title: Backlight
|
|||
sidebar_label: Backlight
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
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, add the following lines to your `.conf` file of your user config directory as such:
|
||||
To enable backlight on your board or shield, add the following line to your `.conf` file of your user config directory as such:
|
||||
|
||||
```
|
||||
CONFIG_PWM=y
|
||||
CONFIG_LED_PWM=y
|
||||
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).
|
||||
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
|
||||
|
||||
|
|
@ -29,13 +30,31 @@ There are various Kconfig options used to configure the backlight feature. These
|
|||
| `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
|
||||
## Adding Backlight to a board or a shield
|
||||
|
||||
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.
|
||||
<Tabs
|
||||
defaultValue="shield"
|
||||
values={[
|
||||
{label: 'Adding to a board', value: 'board'},
|
||||
{label: 'Adding to a shield', value: 'shield'},
|
||||
]}>
|
||||
<TabItem value="board">
|
||||
|
||||
First, you need to enable PWM by adding the following lines to your `.overlay` file:
|
||||
First, you must enable PWM by adding the following lines to your `Kconfig.defconfig` file:
|
||||
|
||||
```
|
||||
if ZMK_BACKLIGHT
|
||||
|
||||
config PWM
|
||||
default y
|
||||
|
||||
config LED_PWM
|
||||
default y
|
||||
|
||||
endif # ZMK_BACKLIGHT
|
||||
```
|
||||
|
||||
Then you have to add the following lines to your `.dts` file:
|
||||
|
||||
```
|
||||
&pwm0 {
|
||||
|
|
@ -52,14 +71,17 @@ For example, _P1.13_ would give you _32 \* 1 + 13_ = `<45>` and _P0.15_ would gi
|
|||
|
||||
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:
|
||||
Then you have to add the following lines inside the root devicetree node on the same file as before:
|
||||
|
||||
```
|
||||
backlight: pwmleds {
|
||||
compatible = "pwm-leds";
|
||||
label = "Backlight LEDs";
|
||||
pwm_led_0 {
|
||||
pwms = <&pwm0 45>;
|
||||
/ {
|
||||
backlight: pwmleds {
|
||||
compatible = "pwm-leds";
|
||||
label = "Backlight LEDs";
|
||||
pwm_led_0 {
|
||||
pwms = <&pwm0 45>;
|
||||
label = "Backlight LED 0";
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
|
@ -73,12 +95,100 @@ Note that every LED inside of the backlight node will be treated as a backlight
|
|||
Finally you need to add backlight to the `chosen` element of the root devicetree node:
|
||||
|
||||
```
|
||||
chosen {
|
||||
...
|
||||
zmk,backlight = &backlight;
|
||||
/ {
|
||||
chosen {
|
||||
zmk,backlight = &backlight;
|
||||
};
|
||||
}:
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="shield">
|
||||
|
||||
You must first add a `boards/` directory within your shield folder. For each board that supports the shield you must create a `<board>.defconfig` file and a `<board>.overlay` file inside the `boards/` folder.
|
||||
|
||||
Inside your `<board>.defconfig` file, add the following lines:
|
||||
|
||||
```
|
||||
if ZMK_BACKLIGHT
|
||||
|
||||
config PWM
|
||||
default y
|
||||
|
||||
config LED_PWM
|
||||
default y
|
||||
|
||||
endif # ZMK_BACKLIGHT
|
||||
```
|
||||
|
||||
Then add 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. With nRF52 boards, you can calculate the value to use in the following way: 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 shield 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 inside the root devicetree node on the same file:
|
||||
|
||||
```
|
||||
/ {
|
||||
backlight: pwmleds {
|
||||
compatible = "pwm-leds";
|
||||
label = "Backlight LEDs";
|
||||
pwm_led_0 {
|
||||
pwms = <&pwm0 45>;
|
||||
label = "Backlight LED 0";
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
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;
|
||||
};
|
||||
}:
|
||||
```
|
||||
|
||||
Optionally, on Pro Micro compatible shields you can add a LED GPIO node to your devicetree, this could be useful if you want your shield to be compatible with newer or untested boards. To do that you have to enable `CONFIG_LED_GPIO` in your `.conf` file and then add the following lines inside the root devicetree node of your `.dtsi` or `.dts` file:
|
||||
|
||||
```
|
||||
/ {
|
||||
backlight: gpioleds {
|
||||
compatible = "gpio-leds";
|
||||
label = "Backlight LEDs";
|
||||
gpio_led_0 {
|
||||
gpios = <&pro_micro 20 GPIO_ACTIVE_HIGH>;
|
||||
label = "Backlight LED 0";
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
If no suitable `<board>.overlay` file is found, this node will act as a fallback, however, without PWM, backlight has limited functionality.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### 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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue