From da41391b1f1649d5ed24cb6411927c085268a70b Mon Sep 17 00:00:00 2001 From: Alessandro Bortolin Date: Sat, 9 Oct 2021 18:25:00 +0200 Subject: feat(docs): add backlight documentation --- docs/blog/2021-01-27-zmk-sotf-4.md | 2 +- docs/docs/behaviors/backlight.md | 48 ++++++++++ docs/docs/behaviors/lighting.md | 73 -------------- docs/docs/behaviors/underglow.md | 68 ++++++++++++++ docs/docs/development/hardware-metadata-files.md | 1 + docs/docs/features/backlight.md | 115 +++++++++++++++++++++++ docs/docs/hardware.mdx | 1 + docs/docs/intro.md | 1 + docs/sidebars.js | 4 +- 9 files changed, 238 insertions(+), 75 deletions(-) create mode 100644 docs/docs/behaviors/backlight.md delete mode 100644 docs/docs/behaviors/lighting.md create mode 100644 docs/docs/behaviors/underglow.md create mode 100644 docs/docs/features/backlight.md (limited to 'docs') diff --git a/docs/blog/2021-01-27-zmk-sotf-4.md b/docs/blog/2021-01-27-zmk-sotf-4.md index d902b62..cd84da8 100644 --- a/docs/blog/2021-01-27-zmk-sotf-4.md +++ b/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 #### 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 diff --git a/docs/docs/behaviors/backlight.md b/docs/docs/behaviors/backlight.md new file mode 100644 index 0000000..c1a92c9 --- /dev/null +++ b/docs/docs/behaviors/backlight.md @@ -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 +``` + +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 + ``` diff --git a/docs/docs/behaviors/lighting.md b/docs/docs/behaviors/lighting.md deleted file mode 100644 index 6e6732b..0000000 --- a/docs/docs/behaviors/lighting.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Lighting Behavior -sidebar_label: 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 -``` - -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_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 - -- Reference: `&rgb_ug` -- Parameter #1: The RGB action define, e.g. `RGB_TOG` or `RGB_BRI` -- Parameter #2: Only applies to `RGB_COLOR_HSB` and is the HSB values of the color to set within parenthesis and separated by a common (see below for an example) - -:::note HSB Values - -When specifying HSB values you'll need to use `RGB_COLOR_HSB(h, s, b)` in your keymap file. See below for an example. - -Value Limits: - -- Hue values can _not_ exceed 360 (degrees) -- Saturation values can _not_ exceed 100 (percent) -- Brightness values can _not_ exceed 100 (percent) - -::: - -### Examples - -1. Toggle underglow on/off - - ``` - &rgb_ug RGB_TOG - ``` - -1. Set a specific HSB color (green) - - ``` - &rgb_ug RGB_COLOR_HSB(128,100,100) - ``` diff --git a/docs/docs/behaviors/underglow.md b/docs/docs/behaviors/underglow.md new file mode 100644 index 0000000..597c249 --- /dev/null +++ b/docs/docs/behaviors/underglow.md @@ -0,0 +1,68 @@ +--- +title: RGB Underglow Behavior +sidebar_label: RGB Underglow +--- + +## Summary + +This page contains [RGB Underglow](../features/underglow.md) behaviors supported by ZMK. + +## 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 +``` + +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_COLOR_HSB` | Sets a specific [HSB (HSV)](https://en.wikipedia.org/wiki/HSL_and_HSV) value for the underglow | + +## Behavior Binding + +- Reference: `&rgb_ug` +- Parameter #1: The RGB action define, e.g. `RGB_TOG` or `RGB_BRI` +- Parameter #2: Only applies to `RGB_COLOR_HSB` and is the HSB values of the color to set within parenthesis and separated by a common (see below for an example) + +:::note HSB Values + +When specifying HSB values you'll need to use `RGB_COLOR_HSB(h, s, b)` in your keymap file. See below for an example. + +Value Limits: + +- Hue values can _not_ exceed 360 (degrees) +- Saturation values can _not_ exceed 100 (percent) +- Brightness values can _not_ exceed 100 (percent) + +::: + +## Examples + +1. Toggle underglow on/off + + ``` + &rgb_ug RGB_TOG + ``` + +1. Set a specific HSB color (green) + + ``` + &rgb_ug RGB_COLOR_HSB(128,100,100) + ``` diff --git a/docs/docs/development/hardware-metadata-files.md b/docs/docs/development/hardware-metadata-files.md index 5d4902d..46fad41 100644 --- a/docs/docs/development/hardware-metadata-files.md +++ b/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 - `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 diff --git a/docs/docs/features/backlight.md b/docs/docs/features/backlight.md new file mode 100644 index 0000000..a917b16 --- /dev/null +++ b/docs/docs/features/backlight.md @@ -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 `.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** = `` 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 */ + }; + ... +}; +``` diff --git a/docs/docs/hardware.mdx b/docs/docs/hardware.mdx index ccdd063..76a0a3c 100644 --- a/docs/docs/hardware.mdx +++ b/docs/docs/hardware.mdx @@ -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). diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 39a52c6..b8a6316 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -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 | 🚧 | ✅ | ✅ | diff --git a/docs/sidebars.js b/docs/sidebars.js index 3825621..090dcb0 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -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: [ -- cgit v1.2.3