# Device Tree

A devicetree is a data structure that is used to *describe* and *configure* hardware. It is extensively used in Zephyr projects.


## Prerequisites

In order to use the provided DEVICE TREE view, it is necessary to have a Zephyr project and the *Devicetree Compiler* (DTC) installed. For more information, refer to [Zephyr](Working-with-Zephyr) and [Dependecies Installation](Dependency-Installation).


## DEVICE TREE view

After compiling the Zephyr Project and refreshing the DEVICE TREE view, it will be populated with a tree-like view of the hardware hierarchy of the project. You can inspect the nodes and their associated values. 

![Devicetree overview](./pictures/nxp-devicetree-overview.png)

Clicking on a node will redirect the user to the source definition of that node. If the node is the merge result of multiple definitions, the one that sets the final value will be opened.


## Devicetree view commands

The node name and value can be copied to the clipboard by opening the *context menu* (right click on a node), and choosing the *Copy Name* command.

![Copy Name](./pictures/nxp-devicetree-copyname.png)

Node values can be referenced programmatically in source code, using specific macros. These can be generated for most of the nodes by opening the *context menu* and choosing the *Copy C Identifier* command.

![Copy C Identifier](./pictures/nxp-devicetree-copyidentifier.png)

This will copy the associated macro to the clipboard. For more information, refer to [Devicetree bindings](https://docs.zephyrproject.org/latest/build/dts/bindings.html).


## Devicetree overlay files

There are multiple ways to override nodes and properties found in the device tree. The most convenient one is to create an overlay file with the required changes. The DEVICE TREE view keeps track of the overlay files used during compilation under the *Overlay files* category. 

If there are no overlay files created for the current project, one can easily be added by clicking the prompt under overlay files.

![Create overlay prompt](./pictures/nxp-devicetree-createoverlay.png)

After creating the overlay file, the view will be refreshed and display the currently available overlay files. Clicking on an overlay file will open a new tab in order to edit it.

If there are multiple overlay files, the one used during the build process will have a *check* next to it.

![Multiple overlay files](./pictures/nxp-devicetree-multipleoverlays.png)

After modifying an overlay file, it is necessary to rebuild the project and refresh the view for it to update.

## Working with devicetree overlay files using CMakePresets

Additional overlay files can be specified by using CMake variables.

In order to set CMake variables, you need to navigate to the `CMakePresets.json` file, located source directory folder of the project (same folder as `CMakeLists.txt`). CMake variables are specified under the `cacheVariables` property of the used build configuration.

In the case of overlays, they can be specified under 2 variables: `DTC_OVERLAY_FILE` and `EXTRA_DTC_OVERLAY_FILE`. Each entry can contain more than one file, by separating the paths using either a semicolon or a space.

![Overlay files using CMake variables](pictures/nxp-device-tree-cmake-variables.png)

After setting the variables, it is necessary to **rebuild** the Zephyr project and refresh the DEVICE TREE view for the changes to take effect. 

![Overlay files included in build will be checked](pictures/nxp-cmake-overlay-files.png)

The overlay files specified under CMake variables will take precedence over the project ones defined. Each entry will also specify where it has been declared, either `DTC_OVERLAY_FILE` or `EXTRA_DTC_OVERLAY_FILE`.

For more information on how to use overlay files, refer to [Devicetree HOWTOs](https://docs.zephyrproject.org/latest/build/dts/howtos.html#use-devicetree-overlays).