Skip to main content

Backlight

Please see lighting feature page for an introduction on the feature.

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, 1, 13)>;
        };
    };
    pwm0_sleep: pwm0_sleep {
        group1 {
            psels = <NRF_PSEL(PWM_OUT0, 1, 13)>;
            low-power-enable;
        };
    };
};

See the documentation page on pin control for detailed information on setting up pins for hardware protocols such as PWM that is used for controlling backlight LEDs.

Pin numbers are handled differently depending on the MCU. On nRF MCUs pins are configured using (PWM_OUTX, Y, Z), where X is the PWM channel used (usually 0), Y is the first part of the hardware port (PY.01) and Z is the second part of the hardware port (P1.Z).

For example, P1.13 would give you (PWM_OUT0, 1, 13) and P0.15 would give you (PWM_OUT0, 0, 15).

Add the PWM device to the <board>.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 add the following lines to the same <board>.overlay file, but inside the root devicetree node:

/ {
    backlight: pwmleds {
        compatible = "pwm-leds";
        pwm_led_0 {
            pwms = <&pwm0 0 PWM_MSEC(10) PWM_POLARITY_NORMAL>;
        };
    };
};

In this example, PWM_MSEC(10) is the period of the PWM waveform. This period can be altered if your drive circuitry requires different values or the 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.

The value inside pwm_led_0 after &pwm0 must be the channel number. Since PWM_OUT0 is defined in the pinctrl node, the channel in this example is 0.

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 configure PWM for each pin in the pinctrl node:

&pinctrl {
    // Other Pinctrl definitions go here
    pwm0_default: pwm0_default {
        group1 {
            psels = <NRF_PSEL(PWM_OUT0, 0, 20)>, // LED 0
                    <NRF_PSEL(PWM_OUT1, 0, 22)>, // LED 1
                    <NRF_PSEL(PWM_OUT2, 0, 24)>; // LED 2
        };
    };
    pwm0_sleep: pwm0_sleep {
        group1 {
            psels = <NRF_PSEL(PWM_OUT0, 0, 20)>, // LED 0
                    <NRF_PSEL(PWM_OUT1, 0, 22)>, // LED 1
                    <NRF_PSEL(PWM_OUT2, 0, 24)>; // LED 2
            low-power-enable;
        };
    };
};

This part will vary based on your MCU as different MCUs have a different number of modules, channels and configuration options.

Add each of your LEDs to the backlight node in the same manner as for one LED, using the channel number definitions in the pinctrl node:

backlight: pwmleds {
    compatible = "pwm-leds";
    pwm_led_0: pwm_led_0 {
        pwms = <&pwm0 0 PWM_MSEC(10) PWM_POLARITY_NORMAL>;
    };
    pwm_led_1: pwm_led_1 {
        pwms = <&pwm0 1 PWM_MSEC(10) PWM_POLARITY_NORMAL>;
    };
    pwm_led_2: pwm_led_2 {
        pwms = <&pwm0 2 PWM_MSEC(10) PWM_POLARITY_NORMAL>;
    };
};