kb01/zmk
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

fix(docs): Update backlight docs

Browse source
This commit is contained in:
ReFil 2023-08-08 11:10:35 +01:00
parent d7d9eed317
commit a35b6ec05a
1 changed files with 186 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

200
docs/docs/features/backlight.md
View file

@ -37,12 +37,12 @@ There are various Kconfig options used to configure the backlight feature. These
## Adding Backlight to a board or a shield
<Tabs
defaultValue="shield"
defaultValue="shieldnopin"
values={[
{label: 'Adding to a board', value: 'board'},
{label: 'Adding to a shield', value: 'shield'},
{label: 'Adding to a board without using Pinctrl', value: 'boardnopin'},{label: 'Adding to a board using Pinctrl', value: 'boardpin'},
{label: 'Adding to a shield without using Pinctrl', value: 'shieldnopin'},{label: 'Adding to a shield using Pinctrl', value: 'shieldpin'},
]}>
<TabItem value="board">
<TabItem value="boardnopin">
First, you must enable PWM by adding the following lines to your `Kconfig.defconfig` file:
@ -58,13 +58,14 @@ config LED_PWM
endif # ZMK_BACKLIGHT
```
Then you have to add the following lines to your `.dts` file:
Since the Zephyr 3.2 update the PWM driver has been revised, permitting the use of the pinctrl API to select the pins. For now the old method of pin select is also functional
If you do not want to use pinctrl add the following lines to your `.dts` file:
```dts
&pwm0 {
status = "okay";
ch0-pin = <45>;
/* ch0-inverted; */
};
```
@ -73,8 +74,6 @@ The value `ch0-pin` represents the pin that controls the LEDs. With nRF52 boards
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 inside the root devicetree node on the same file as before:
```dts
@ -83,7 +82,7 @@ Then you have to add the following lines inside the root devicetree node on the
compatible = "pwm-leds";
label = "Backlight LEDs";
pwm_led_0 {
pwms = <&pwm0 45>;
pwms = <&pwm0 45 10000 PWM_POLARITY_NORMAL>;
label = "Backlight LED 0";
};
};
@ -92,6 +91,10 @@ Then you have to add the following lines inside the root devicetree node on the
The value inside `pwm_led_0` must be the same as you used before.
In this example `10000` is the period of the PWM waveform, some drive circuitry might require different values, it could also be altered in the event the drive frequency is audible/
If your board uses a P-channel MOSFET to control backlight instead of a N-channel MOSFET, you may want to change `PWM_POLARITY_NORMAL` for `PWM_POLARITY_INVERTED`.
:::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.
:::
@ -107,7 +110,92 @@ Finally you need to add backlight to the `chosen` element of the root devicetree
```
</TabItem>
<TabItem value="shield">
<TabItem value="boardpin">
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
```
When using the pinctrl API you should create a pinctrl.dtsi file if it's not created already, and include it at the beginning of the `board.dts` file. You also need to add `CONFIG_PINCTRL=y` to board_defconfig if it's not already enabled
A pinctrl file has an `&pinctrl` node that encompasses all pinctrl settings including for I2C or SPI peripherals (e.g. WS2812 LEDs, Battery fuel gauges)
```
&pinctrl {
// Other pinctrl definitions for other hardware
pwm0_default: pwm0_default {
group1 {
psels = <NRF_PSEL(PWM_OUT0, 0, 45)>;
};
};
pwm0_sleep: pwm0_sleep {
group1 {
psels = <NRF_PSEL(PWM_OUT0, 0, 45)>;
low-power-enable;
};
};
}
```
The pin number is calculated in the same way as for the non pinctrl configuration.
The value `45` in the example 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_ = `<PWM_OUT0, 0, 45>` and _P0.15_ would give you _32 \* 0 + 15_ = `<PWM_OUT0, 0, 15>`.
Then you add the PWM device inside the `board.dts` file and assign the pinctrl definitions to it
```
&pwm0 {
status = "okay";
pinctrl-0 = <&pwm0_default>;
pinctrl-1 = <&pwm0_sleep>;
pinctrl-names = "default", "sleep";
};
```
Then you have to add the following lines inside the root devicetree node on the same file as before:
```
/ {
backlight: pwmleds {
compatible = "pwm-leds";
pwm_led_0 {
pwms = <&pwm0 0 10000 PWM_POLARITY_NORMAL>;
};
};
};
```
In this example `10000` is the period of the PWM waveform, some drive circuitry might require different values, it could also be altered in the event the drive frequency is audible/
If your board uses a P-channel MOSFET to control backlight instead of a N-channel MOSFET, you may want to change `PWM_POLARITY_NORMAL` for `PWM_POLARITY_INVERTED`.
Finally you need to add backlight to the `chosen` element of the root devicetree node:
```
/ {
chosen {
zmk,backlight = &backlight;
};
};
```
</TabItem>
<TabItem value="shieldnopin">
Since the Zephyr 3.2 update the PWM driver has been revised, permitting the use of the pinctrl API to select the pins. For now the old method of pin select is also functional
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.
@ -131,7 +219,6 @@ Then add the following lines to your `.overlay` file:
&pwm0 {
status = "okay";
ch0-pin = <45>;
/* ch0-inverted; */
};
```
@ -140,8 +227,6 @@ The value `ch0-pin` represents the pin that controls the LEDs. With nRF52 boards
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:
```dts
@ -150,7 +235,7 @@ Then you have to add the following lines inside the root devicetree node on the
compatible = "pwm-leds";
label = "Backlight LEDs";
pwm_led_0 {
pwms = <&pwm0 45>;
pwms = <&pwm0 45 10000 PWM_POLARITY_NORMAL>;
label = "Backlight LED 0";
};
};
@ -159,6 +244,10 @@ Then you have to add the following lines inside the root devicetree node on the
The value inside `pwm_led_0` must be the same as you used before.
In this example `10000` is the period of the PWM waveform, some drive circuitry might require different values, it could also be altered in the event the drive frequency is audible/
If your board uses a P-channel MOSFET to control backlight instead of a N-channel MOSFET, you may want to change `PWM_POLARITY_NORMAL` for `PWM_POLARITY_INVERTED`.
:::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.
:::
@ -190,6 +279,89 @@ Optionally, on Pro Micro compatible shields you can add a LED GPIO node to your
If no suitable `<board>.overlay` file is found, this node will act as a fallback, however, without PWM, backlight has limited functionality.
</TabItem>
<TabItem value="shieldpin">
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:
```
&pinctrl {
// Other pinctrl definitions for other hardware
pwm0_default: pwm0_default {
group1 {
psels = <NRF_PSEL(PWM_OUT0, 0, 45)>;
};
};
pwm0_sleep: pwm0_sleep {
group1 {
psels = <NRF_PSEL(PWM_OUT0, 0, 45)>;
low-power-enable;
};
};
}
```
The pin number is calculated in the same way as for the non pinctrl configuration.
The value `45` in the example 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_ = `<PWM_OUT0, 0, 45>` and _P0.15_ would give you _32 \* 0 + 15_ = `<PWM_OUT0, 0, 15>`.
Then you add the PWM device inside the `.overlay` file and assign the pinctrl definitions to it
```
&pwm0 {
status = "okay";
pinctrl-0 = <&pwm0_default>;
pinctrl-1 = <&pwm0_sleep>;
pinctrl-names = "default", "sleep";
};
```
Then you have to add the following lines inside the root devicetree node on the same file as before:
```
/ {
backlight: pwmleds {
compatible = "pwm-leds";
pwm_led_0 {
pwms = <&pwm0 0 10000 PWM_POLARITY_NORMAL>;
};
};
};
```
In this example `10000` is the period of the PWM waveform, some drive circuitry might require different values, it could also be altered in the event the drive frequency is audible/
If your board uses a P-channel MOSFET to control backlight instead of a N-channel MOSFET, you may want to change `PWM_POLARITY_NORMAL` for `PWM_POLARITY_INVERTED`.
Finally you need to add backlight to the `chosen` element of the root devicetree node:
```
/ {
chosen {
zmk,backlight = &backlight;
};
};
```
</TabItem>
</Tabs>