Creating an overlay file

Applications can use overlays to provide additional board functionality such as enabling a peripheral that is disabled by default, or selecting a sensor on the board for an application specific purpose. Along with the Configuration System (Kconfig), this makes it possible to reconfigure the kernel and device drivers without modifying the source code.

A devicetree overlay adds application-specific modifications to the base devicetree, defined by the <board>.dts file. Overlay files use the .overlay extension naming convention to make their purpose clear. The build system concatenates the changes from the overlay files with the base devicetree file.

Creating an overlay file

1. From the application's build View, click on the Input files. It will say "No overlay files. Click to create one".

2. Click on Click to create one. A progress bar will display in the bottom right corner of the screen.

   

3. When the process is complete, the .overlay file appears under the application Input files.

4. When creating or removing an overlay file, a pristine build must be run for CMake to include the overlay file in the configuration. A notification appears and prompts you to do this. Click the Run Pristine Build button.

Adding a node

With the overlay file created, we can start adding nodes to the board.

1. Press Ctrl+Space to start the auto-completion feature and see a list of available nodes.

   For detailed information about writing property values, see the nRF Connect SDK documentation.

Adding a dimmable LED

In this example, we will add a dimmable LED to the board. Zephyr provides a generic binding for PWM LED controllers, named pwm-leds. Bindings are type definitions for devicetree nodes, defining which properties the node supports and what values they expect.

Bindings are specified by setting the compatible property for the node. Within the PWM LED controller node (pwmleds), we can add nodes for each LED. The pwm-leds binding defines the properties of its child nodes as well, so the LED node properties can also be auto-completed.

1. LEDs must be added under the root node in devicetree. This requires a pwm-leds node, which is what the driver will pick up. The LEDs are defined as child nodes on the pwm-leds node, and require a pwms and a label property.

2. The pwms property is a phandle that must point to a PWM instance. The PWM instance takes the pin number as its only parameter. In this example we are using pin 6 on GPIO port 0.

   Dimmable LEDS in .dts

   / {
       // ...
       pwmleds { /* (1) */
               compatible = "pwm-leds";
               led_pwm_1 {
                       pwms = <&pwm0 33>; /* (2) */
                       label = "PWM LED 1";
               };
   
   
               led_pwm_2 {
                       pwms = <&pwm0 34>;
                       label = "PWM LED 2";
               };
       };
   };
   

   1. This is the pwm-leds node that the driver will pick up.
   2. Specify the pin number as the parameter here.

3. Additionally, the referenced PWM0 node must be enabled with setting status = "okay" and its channels configured. For this, we use the &pwm0 node label reference on the root of the file:

   Enabling PWM0

   &pwm0 {
       status = "okay"; /* (1) */
       ch0-pin = <33>;
       ch1-pin = <34>; /* (2) */
   };
   

   1. The status must be enabled with "okay".
   2. Assigning the PWM channel used for controlling each pin.

4. Enable the LED PWM driver in Kconfig by adding CONFIG_LED_PWM=y in the board's prj.conf file.

Validating a node

The nRF DeviceTree extension comes with built-in linting for the .overlay file, which validates if a node has been correctly added or if it is already assigned. Review any linting errors to see information about how to fix them.