Device Tree Overlays
Device Tree Overlays
Device tree overlays provide a lightweight way to extend the Jetson reference platform without replacing the full base device tree.
In this workspace, overlays are used to keep board-specific customization inside the project layer while preserving the NVIDIA-provided BSP, machine configuration, and flashing workflow.
The current example demonstrates the complete overlay integration path, from build and deployment to runtime validation on the target platform.
When to Use an Overlay
Device tree overlays are best suited for incremental hardware changes that do not require replacing the full base DTB.
Typical examples include:
- Enabling an additional peripheral
- Adding validation or test nodes
- Wiring GPIO-based devices
- Integrating sensors or simple bus devices
- Validating board features during bring-up
- Adding optional hardware functionality
- Testing incremental hardware enablement during development
Overlays are commonly used when the base NVIDIA board definition remains valid and only smaller hardware additions or modifications are required.
If the hardware changes become large enough that the base device tree no longer accurately represents the platform, the next step is usually:
- A custom
MACHINE - A project-owned DT provider
- A full custom DTB workflow
Additional information about project-owned DTBs is covered in:
Overlay Integration Flow
In this workspace, overlays are integrated through the Tegra plugin manager mechanism.
The overall flow is:
The overlay DTS is compiled into a DTBO artifact during the Yocto build process.
The selected MACHINE configuration determines which overlays are included in the generated deploy artifacts and flash bundle.
This keeps the overlay flow aligned with the standard Yocto build and flashing workflow while preserving separation between project customization and NVIDIA BSP sources.
Overlay Sources
Overlay source:
layers/meta-tegrademo/recipes-bsp/
└── tegrademo-device-tree-overlays/
└── tegra234-p3737-0000+p3701-0000-tegrademo-overlay.dts
Recipe:
layers/meta-tegrademo/recipes-bsp/
└── tegrademo-device-tree-overlays/
└── tegrademo-device-tree-overlays_1.0.bb
Machine-specific enablement:
build/conf/local.conf layers/meta-tegrademo/conf/templates/tegrademo/local.conf.sample
The meta-tegrademo layer contains the project-specific overlay integration separate from the NVIDIA vendor layers.
The overlay recipe builds the DTBO artifact and integrates it into the Yocto deploy workflow.
Machine Configuration
For Jetson AGX Orin, the overlay is enabled through:
TEGRA_PLUGIN_MANAGER_OVERLAYS:append:jetson-agx-orin-devkit = " tegra234-p3737-0000+p3701-0000-tegrademo-overlay.dtbo"
This appends the generated .dtbo to the list of overlays included during deployment.
The Tegra plugin manager applies these overlays during boot as part of the Jetson BSP initialization flow.
Overlay enablement is tied directly to the selected MACHINE, allowing different platforms to use different overlay sets.
What the Demo Overlay Does
The demo overlay creates a small node called:
tegrademo_overlay_demo
The node is added to the live device tree and exposes a few simple properties:
| Property | Purpose |
|---|---|
compatible
|
Driver matching |
label
|
Human-readable identifier |
status
|
Device state |
test-string
|
Validation string |
The objective is not to create a complex hardware example, but to validate that the complete overlay workflow is functioning correctly.
In real projects, overlays commonly add:
- Sensors
- GPIO devices
- Camera modules
- Expansion board peripherals
- Optional hardware interfaces
Build and Deployment
Rebuild the overlay and image:
bitbake tegrademo-device-tree-overlays bitbake demo-image-base
Verify that the generated DTBO exists in the deploy directory:
ls tmp/deploy/images/$MACHINE/*.dtbo
After rebuilding, flash the updated image:
./scripts-setup/flash-demo-image-base
This updates the deploy artifacts and programs the refreshed image onto the target platform.
Validation on Target
After boot, validate that the overlay was applied correctly.
The node should exist under:
/proc/device-tree/tegrademo_overlay_demo
Validate the node contents:
ls /proc/device-tree/tegrademo_overlay_demo tr -d '\0' < /proc/device-tree/tegrademo_overlay_demo/test-string; echo tr -d '\0' < /proc/device-tree/tegrademo_overlay_demo/label; echo
Expected output:
compatible label name status test-string jetson-agx-orin tegrademo overlay demo
Additional validation commands:
dmesg | grep -i overlay
dtc -I fs /proc/device-tree
Successful validation confirms:
- The overlay was built correctly
- The DTBO was included in the flash artifacts
- The overlay was applied at boot
- The live device tree contains the expected node and properties
Troubleshooting
If the overlay does not appear on target, verify:
- The overlay was enabled for the correct
MACHINE - The image was rebuilt after changing
TEGRA_PLUGIN_MANAGER_OVERLAYS - The board was reflashed using the updated deploy artifacts
- The recipe deployed the expected
.dtbo - The generated DTBO exists under
tmp/deploy/images/$MACHINE/
Useful validation commands:
bitbake -e demo-image-base | grep '^TEGRA_PLUGIN_MANAGER_OVERLAYS='
ls tmp/deploy/images/$MACHINE/*.dtbo
dmesg | grep -i overlay
The most common issue is rebuilding the deploy artifacts without reflashing the board afterward.
In some cases, cleaning cached DTBO artifacts before rebuilding may also help ensure the updated overlay is packaged correctly.