Adding custom overlays to Yocto image

I started researching Yocto recently. I followed Toradex documentation and successfully added new packages to reference image, created and added new layers, but Im having problems adding new overlays to an image. This is how my layer currently looks like:



SRC_URI += "\
    file://aunit_tcm_overlay.dts \
    file://can-overlay.dts \

    aunit_tcm_overlay.dtbo \
    can-overlay.dtbo \

    aunit_tcm_overlay.dtbo \
    can-overlay.dtbo \

do_collect_overlays:prepend() {
    cp ${WORKDIR}/aunit_tcm_overlay.dts ${S}
    cp ${WORKDIR}/can-overlay.dts ${S}

After running bitbake device-tree-overlays it returns warning but no custom .dtbo are located in deploy folder:

This document didn’t help me much.

Hi @spasoye,

I recommend using this name: device-tree-overlays_git.bbappend. A bbappend file has to have the name identical with the original recipe name, the only difference can be the version number (can be replaced with %).
You can use command bitbake-layers show-appends | grep <recipe-name> to verify your changes will be applied.

1 Like

I had to add two custom DST files to support my displays, so I did this in device-tree-overlays_git.bbappend:

FILESEXTRAPATHS:prepend := "${THISDIR}/linux-toradex-5.15-2.2.x/dts:"

TEZI_EXTERNAL_KERNEL_DEVICETREE_BOOT:colibri-imx8x = "colibri-imx8x-custom-rgb_overlay.dtbo"

SRC_URI += " \
    file://colibri-imx8x-custom-rgb_overlay.dts;subdir=git/overlays \
    file://colibri-imx8x-custom-rgb-lvds_overlay.dts;subdir=git/overlays \
    file://display-97G084S3N2F2_overlay.dtsi;subdir=git/overlays \
    file://display-fg050720dsswdgt1_overlay.dtsi;subdir=git/overlays \
    file://Makefile;subdir=git/overlays \

Not sure if this is 100% correct way, but in the end, all requested dtbo files are created and deployed. The original Makefile was updated with those two *.dts files. Not sure if this step is necessary.

Thank @John1 this solved my problem.

Hi @spasoye ,

Glad your problem was solved. Thank you for your help @John1 !

Your initial overlay looks mostly correct @spasoye . Apart from using % instead of * for the bbappend version you should put an override in TEZI_EXTERNAL_KERNEL_DEVICETREE_BOOT as @John1 did e.g.


For reference, here’s how you can add overlays with mainline images (iMX6 and iMX7 SoMs):

FILESEXTRAPATHS:prepend := "${THISDIR}/device-tree-overlays-mainline:"

    <custom_overlay1>.dts \
    <custom_overlay2>.dts \

    <custom_overlay1>.dtbo \
    <custom_overlay2>.dtbo \

SRC_URI += " \
    file://<custom_overlay1>.dts \
    file://<custom_overlay2>.dts \


do_collect_overlays:prepend() {

        cp ${WORKDIR}/${DTS} ${S}


Best regards,
Lucas Akira

Where is the original device-tree-overlays recipe name defined ?

Hi @spasoye ,

You can find the device-tree-overlays recipe defined in meta-toradex-nxp:

The overlays above are for the downstream kernel from NXP currently used in BSP 6 for our iMX8 SoMs.

For the upstream kernel we provide a different DT overlay recipe found in meta-toradex-bsp-common:

And for the Verdin AM62 the overlays recipe is in meta-toradex-ti:

Hope this helps.

Best regards,
Lucas Akira

Thanks @lucas_a.tx

Hi, I have one a question. How did you build binary file (.dtbo) ?

Hi @facundo.n.r ,

There are a couple of ways to build a device tree overlay:

  • You can use a build system like Yocto to build it for you as detailed in this thread;
  • If you’re using Torizon OS you can use TorizonCore Builder to build it for you;
  • You can manually build it with the kernel sources using Makefile or directly invoking dtc, the Device Tree Compiler.

The last two ways are explained in more detail in our developer site:

Best regards,
Lucas Akira

after vacation was over, I continued on this issue of customizing torizoncore image.
After flashing Verdin SoM with built Yocto image (i decided to build torizon-upstream-rt docker image) and connecting it to custom board no additional CAN interface (defined in my overlay) was visible in Linux. Same overlay .dtbo works fine when running on Torizoncore images pulled from Toradex artifactory built with torizoncore builder.
Serial console outputs:

mcp251xfd spi0.0 (unnamed net_device) (uninitialized): Failed to read Oscillator Configuration Register (osc=0xffffffff).

I decided to list files in /proc/device-tree/soc@0/bus@30800000/, this are the files listed on image built using torizoncore builder:

#address-cells   dma-controller@30bd0000  i2c@30a40000  mmc@30b60000  ranges           serial@30a60000  spi@30bb0000
#size-cells      ethernet@30be0000        i2c@30a50000  mu@30aa0000   serial@30860000  spi@30820000
compatible       i2c@30a20000             mmc@30b40000  name          serial@30880000  spi@30830000
crypto@30900000  i2c@30a30000             mmc@30b50000  phandle       serial@30890000  spi@30840000

And this are files listed on my Yocto built image:

'#address-cells'   dma-controller@30bd0000   i2c@30a40000       mmc@30b50000   ranges              spi@30bb0000
'#size-cells'      ethernet@30be0000         i2c@30a50000       mmc@30b60000   reg
 compatible        i2c@30a20000              mailbox@30aa0000   name           serial@30a60000
 crypto@30900000   i2c@30a30000              mmc@30b40000       phandle        spba-bus@30800000

Lots of node that are defined in .dts are missing in Yocto build among which is also spi@30820000 node used in additional CAN. What am I missing ?

Hi @spasoye ,

You are using a custom version of Torizon OS on a Verdin iMX8M Mini, is this correct?

I see that you’re building Torizon OS with the torizon-upstream-rt distro. Is there a specific reason you’re using the upstream version?

Currently for all our iMX8 SoMs by default we use the downstream kernel (torizon distro), and using the upstream distros for the iMX8M SoMs is considered experimental.

Can you check if the .dtbo file is actually present in your custom Torizon OS build? If the bbappend file is including your overlay in the downstream kernel, this could explain why you’re not seeing the overlay changes, since your custom image uses the upstream one.

Can you try building with a downstream distro e.g. torizon/torizon-rt and see if that works?

Best regards,
Lucas Akira

Sorry for the late reply, but I had some issues when trying to built new distro, I finally managed to build booth torizon_rt and torizon and I faced the same issue, /proc/device-tree is incomplete.

Booth *.dtbo’s * are present in /boot/ostree/torizon-e###/dtb/overlays.

Good news is that CAN overlay that was built by Yocto in my custom image, works when copied to official Toradex image.

Hi @spasoye !

What do you mean by /proc/device-tree is incomplete? Could you please specify?

That’s good. Have you checked the contents of overlays.txt?

So your overlay (.dtbo) works on a Reference Image from Toradex BSP but doesn’t work on the image you built yourself? That’s strange.

This fact makes me believe that you are performing some modification on your image (when compared to the Reference Image) that is making the overlay not work.

Could you please share the output of tdx-info -dt (reference: Getting Device Information with Tdx-Info | Toradex Developer Center) from your image and from the Reference Image with your overlay?

Best regards,

This is something that I mentioned in previous post when I built torizon-upstream-rt distro, in short lots of device tree nodes that are defined in /proc/device-tree when I run official image (for example spi@30820000 used for MCP25xxFD IC interface, in my case) are missing when running my Yocto custom image.

Booth of the overlays are defined in overlays.txt and gets loaded in U-Boot.

Sure, here it is:

torizon@verdin-imx8mm-07213973:~$ sudo tdx-info -dt

Device tree
Device tree enabled:      imx8mm-verdin-nonwifi-dev.dtb
Compatible string:        toradex,verdin-imx8mm-nonwifi-devtoradex,verdin-imx8mm-nonwifitoradex,verdin-imx8mmfsl,imx8mm
Device trees available:

Device tree overlays
Overlays enabled:         fdt_overlays=aunit_tcm_overlay.dtbo can-overlay.dtbo
Overlays available:

Hi @spasoye!

Did you continue to investigate your issue? Do you have any news?

One thing that I could recommend you is to build your Torizon OS with only one specific change, which is your SPI/CAN overlay.

It really seems like some other change you might have done is causing the issue. The fact that the very same overlay works on a default Torizon OS from Toradex, but doesn’t work on your Yocto built Torizon OS is strange.

Also, a question from my side: for Torizon OS, we have Torizon Core Builder that allows you to deal with device tree [overlay] customization. Why would you need to use Yocto? Does your use case really require Yocto? I am asking this because, as you already saw, you have your device working with Torizon OS, so you wouldn’t need to spend time on Yocto :slight_smile:

Best regards,

Hey @henrique.tx , I haven’t done any research since I posted this.
I’ve already implemented use of Torizon Core Builder in our development and releases, but we would like to implement some other tools in Torizon Core image we use in our robots, so other teams could do quick setup and testing of our hardware without the need of fiddling with containers.
We realized that we miss some basic tools like git, wget, can-utils, netcat, netstat and other tools that people on the field expect are installed without running the Docker.


Hi @spasoye !

Thanks for sharing your use case.

I would like to share one idea that might release you from dealing with Yocto.

You could set up a user that when it performs the login via SSH, it drops inside a container that has all the setup done to access the necessary hardware and has all the software tools needed. This way it is even easier to maintain the OS and you would not need to deal with Yocto.

Wouldn’t such a method be suitable (and easier) for your use case?

Best regards,