Finding Devicetree Overlays
I like the overlay pattern Zephyr recommends for adjusting device hardware settings. In my mind it is clean and extensible. Although sometimes it can get finicky.
For a refresher, overlays are a way to keep the original “board” hardware Devicetree intact and adjust it as needed for a project’s effective Devicetree. This is quite common requirement when you use a development board like a Nordic DK or a third-party board like our MTC2-N9151. These third-party boards can play different roles in projects, overlays let them become the actor for your project’s play.
How Overlays Are Useful…
The nRF9151 has 4 serial devices, each can perform as a SPI, I2C, or UART device. One project may need a SPI and a I2C and two UARTS. A different project may require a UART and 3 I2C. Overlays let your do that.
Overlays let you configure your GPIO pins to different traces on your project’s PCB.
For a more detailed explanation of the devicetree and its implementation see… Nordic Developer Academy/Fundementals-Lesson2
Note: this post, and all posts in this series, assume we are working in Nordic nRF Connect in VS Code. I am using SDK 3.0.2 today, but these tips should work on any SDK version > 2.7.x.
Incorporating an Overlay in Your Project
Most Nordic sample projects with hardware dependencies have a boards folder in the root folder for the sample. The build system looks in this folder for a overlay file matching your build’s Board target with the name <myBoard>.overlay.
As an example, in the Developer Academy Intermediate-Lesson 6, Exercise 1, the boards folder looks like this after you copy the sample. Notice that the sample expects you to rename the .overlay file to a name matching your Board target.
Alternatively, some “samples” will have several overlays for popular Nordic “DK” boards like is shown next. If you Board target (in your build configuration) matches one of the .overlay files it is used. Note that for many boards there are two variants, one ending in “_ns” and one not (a topic for another day… maybe).
Both of the examples above demonstrate the same pattern. They find the overlay by matching the name of your board. Note that the “boards” folder is by convention to be tidy, your overlay can also exist in the root of your project and still be found.
LooUQ’s Preferred Way…
An alternative way is to specify your overlay file in the build configuration. This allows you to name your overlay to indicate its purpose.
Recently I was working on a project were I needed to configure a SPI instance. I created and overlay file named hostExtension.overlay (this is to support LooUQ LQnode SPI-based, host extension interface). As you can see below, this file is in the root of the project.
When you add a new build configuration (Edit Build Configuration) you specify you “Extra” Devicetree overlay as shown below. It is important to choose Extra Devicetree overlays and not Base Devicetree overlays, since you are overriding select Devicetree settings and not providing a complete set of values for the board.
This pattern allows a single overlay file to be applied to any compatible Target board.
Always do a Pristine Build after making changes to your build configuration.
Thanks for following along. I hope this tips makes managing Devicetree overlays a bit easier for you.