How to work with Devicetree Visual Editor

The nRF Connect for VS Code extension comes with the Devicetree Visual Editor, which provides a visual representation of the devicetree file structure and simplifies the editing process of devicetree files by reducing the time needed to manually convert a hardware schematic to devicetree language.

This page provides information about the most common ways you can interact with the editor. For a detailed description of all the interface options, see the Devicetree Visual Editor interface page in the UI and reference section.

Changes in the editor are propagated to the devicetree file in real time (and the other way around), and you can save your changes in either of them. This is different from the Kconfig GUI, which requires saving changes using one of the dedicated options in the GUI. If you still prefer to manually edit the devicetree files, see the How to manually edit devicetree files page.

Note

The hardware limitations for pins and nodes also apply when using the editor. For example, you can only add a number of different pins for the adc node. Other restrictions are inherited from the devicetree language and Zephyr.

How to access the Devicetree Visual Editor

You can only have one Device Visual Editor instance open for each compiled devicetree output.

To open the Devicetree Visual Editor:

1. Select the .dts or .overlay file you want to work with in the Devicetree View.
   See How to create devicetree files for detailed steps.

   Important

   Make sure you edit a .dts or an .overlay file that you created. Directly editing .dts or .overlay files that come with the nRF Connect SDK installation may have unintended consequences to other boards or to applications that use the same board.

2. In the Actions View, click Devicetree.

   

This opens the main screen of the Devicetree Visual Editor in a separate tab in the Editor.

How to create devicetree files in the editor

The Devicetree Visual Editor is meant to be used with existing .dts and .overlay files. For this reason, it does not offer the option to create these files from scratch.

Make sure to create devicetree files before you use the editor.

How to work with the Schematic Preview

The Schematic Preview is the part of the UI that displays the hardware circuit preview, including the Pin Overview.

You can interact with the Schematic Preview in different ways. The following sections describe steps for the most common actions. For the full list of interaction options available in this part of the editor, see the Devicetree Visual Editor interface page.

How to assign nodes to pins in the Pin Overview

To assign a node to a pin, complete the following steps:

1. Open the Pin Overview screen of the editor.
2. Click the pin to which you want to assign a node.
   The Pin Management widget appears.
   
3. If you are assigning a node to a pin that has already nodes assigned, the Existing Assignment tab opens and you must go to the Add Assignment tab.
   If you are assigning a node to a pin without node assignments, the Add Assignment tab opens first.
4. Select the options for the node from the available menu fields.
5. Click Assign.
6. Save your changes either in the editor or in the devicetree file.

The node is assigned to the chosen pin and the change is mirrored in the devicetree code file. You can hover over the pin to see the tooltip with the list of available assignments, including the respective node, function, and state.

How to reassign nodes in the Pin Overview

To reassign an already assigned node to a different pin:

1. Open the Pin Overview screen of the editor.
2. Click the pin to which you want to reassign the node.
   The Pin Management widget appears.
3. Go to the Add Assignment tab if the widget does not show it already.
4. Provide the information of the node you want to reassign and select the options for the node from the available menu fields.
5. Click Assign.
6. Save your changes either in the editor or in the devicetree file.

The node is reassigned to the chosen pin and any previous assignment of the node is automatically deleted.

How to unassign nodes in the Pin Overview

To unassign a node from a pin, complete the following steps:

1. Open the Pin Overview screen of the editor.
2. Click the pin from which you want to unassign a node.
   The Pin Management widget appears with the Existing Assignment tab open.
3. Select the node you want to unassign from the drop-down menu.
4. Click Delete Assignment.
5. Save your changes either in the editor or in the devicetree file.

The node is unassigned from the pin and the change is mirrored in the devicetree code file.

Tip

You can also use the Clear Pin context menu action to delete all node assignments at once from a pin.

Note

If there are multiple nodes assigned to the pin, as indicated by additional chevrons next to the assigned pin entry in the Pin Overview, you can either unassign them one by one or unassign a specific pin in the Node Inspector.

How to work with the Node Tree and the Node Inspector

You can interact with the Node Tree and the Node Inspector panels in different ways. The following sections describe steps for the most common actions. For the full list of options available in this part of the editor, see the Devicetree Visual Editor interface page.

How to add new nodes

To add a new node, complete the following steps:

1. Hover over the Node Tree area.
   The Add Node button appears at the top of the area (the plus icon).

   

2. Click the Add Node button.
   A window appears.

   

3. In the window, select the parent node of the new node and the type of the new node. The drop-down lists are populated from the Zephyr and nRF Connect SDK devicetree type YAML files.

4. Write the name of the new node. The name can only contain letters, numbers, and the following symbols: -, @, and _.
5. Save your changes either in the editor or in the devicetree file.

The node is added to the tree under the provided parent with an icon assigned automatically based on the node type.

You can also add nodes by clicking the Add Node button that appears when hovering over valid parent nodes.

Note

You can expand a node to see its children only if the node is enabled. For this reason, you cannot edit children of a disabled node.

How to add new properties

To add a new property, complete the following steps:

1. Select the node in the node tree.
   The Schematic Preview view focuses on the selected node and the Node Inspector panel is populated with the information about the node.
   This panel also includes the Add Property button.

   

2. Click the Add Property button.
   A window appears.

3. Select the property type and fill in or select the values for other fields.
   Some of these fields might be optional and some are mandatory (marked with an asterisk).
4. Click on Add.
   The property is added to the node, with its location defined by the property type.
5. Save your changes either in the editor or in the devicetree file.

How to edit node and property values

To edit nodes or properties, complete the following steps:

1. Select the node you want to edit in one of the following ways:

   • In the Node Tree, expand the list to the desired node and click its name.
   • Left-click an assigned pin in the Pin Overview to open the Pin Assignment widget, where you can click the Show Node button.
   • Click the node in the Schematic Preview.

2. After the node is selected, update the value of the node property you want to edit.
   The editor fields and the devicetree code file are both updated automatically at the same time.

3. Save your changes either in the editor or in the devicetree file.

Depending on the field and its type, editing node and property values can require additional steps. The following sections include examples of editing some particular node types.

How to edit GPIO pin element values

To edit GPIO pin element values, complete the following steps:

1. Select a node that can have GPIOs assigned.
   For example, one of the nodes of the buttons or leds drivers.

2. In the Node Inspector, open the Pins tab to display the information about the node.

   

3. Expand the menu next to the assigned pin entry by clicking the chevron.
   The buttons of the GPIO editor expand into a list of options, corresponding to additional properties.

4. Select the desired value for each of the options.

   Note

   Some of the options and values are interdependent. Moreover, in the nRF Connect SDK versions earlier than v1.6.0 you can only set the Active low or high flag for the pins.

5. Save your changes either in the editor or in the devicetree file.

How to remap elements

Remapping allows you to use compatible peripherals by matching the pins on peripherals to pins on Nordic boards. With devicetree, you can use so called nexus nodes, for example GPIO nexus nodes, to remap values for an Arduino shield. The editor simplifies the remapping process.

To remap elements for nodes that allow this, complete the following steps:

1. Select a node that uses properties organized into a map.
   For example, this can be the arduino_header node.

   

2. Edit the values in the map.
   If you need to add a new entry to the table, use the Add new entry action at the bottom of the table.

3. Save your changes either in the editor or in the devicetree file.

How to edit partition memory ranges

To edit flash partition memory ranges, complete the following steps:

1. Select a flash node or a partition node under the parent soc/flash-controller node.
   The memory layout of the flash memory appears in the Schematic Preview.

   

2. Edit the memory partition layout values in the Node Inspector.
   For example, you can change the reg register space property, so that the partition either begins at a different address (first field) or has more memory space available (second fields), or both. Changes are automatically mirrored in the memory layout in the Schematic Preview.

3. Save your changes either in the editor or in the devicetree file.

How to unassign nodes in the Node Inspector

There might be several nodes assigned to a pin. Instead of removing them one by one from the Pin Overview, you can remove specific nodes from a pin in the Node Inspector.

Complete the following steps:

1. Identify the node you want to unassign.

2. Select the node in one of the following ways:

   • In the Node Tree, expand the list to the desired node and click its name.
   • Left-click an assigned pin in the Pin Overview to open the Pin Assignment widget, where you can click the Show Node button.
   • Click the node in the Schematic Preview.

   The Schematic Preview displays the circuit with the list of nodes assigned to the given pin.

   

3. Click the node box in the Schematic Preview to select it in the Node Tree.
   In the example above, you could select either &pwm_led0 or &pwm_led1.

4. Go to the Properties tab in the node's Node Inspector view.

5. Remove the assignment for the node.
   In the example above, this would be the pwms assignment.

   

6. Save your changes either in the editor or in the devicetree file.

The devicetree structure is updated in both the Node Tree and the Pin Overview.

How to delete nodes

To delete any node in the Node Tree, complete the following steps:

1. Hover with your mouse cursor over the node name in the tree.
   The More actions... button appears.
2. Click the More actions... button to open the drop-down menu.
3. Click Delete to remove the element from the tree.
4. Save your changes either in the editor or in the devicetree file.

How to delete properties

To delete properties in the Node Inspector, complete the following steps:

1. Go to the property you want to delete.
2. Click Delete from the More actions... menu that appears after hovering over the property field. This is similar to the method for deleting nodes.
3. Save your changes either in the editor or in the devicetree file.

How to revert changes

To revert changes, you can use the Undo action from VS Code. The Undo action is also available from the context menu in the Schematic Preview, the Node Tree, and the Node Inspector.