Devicetree Visual Editor UI

The nRF Connect for VS Code extension features the Devicetree Visual Editor, which provides a visual front-end to the devicetree language.

For information about most common actions that you can do in the editor, see How to work with Devicetree Visual Editor.

Access to the editor

You can access the editor using the following options:

• The Devicetree action in the Actions View

  

• The Show Visual Editor button in the Editor toolbar after opening a devicetree file, for example from the Devicetree View.

• The Reopen Editor With... action, visibile when you right-click the .dts or .overlay file name in the Editor tab.

Either of these options opens the main screen of the Devicetree Visual Editor, from which you can use the Open Text Editor button to jump to the related code location in the .dts or .overlay file.

Tip

You can use the workbench.editorAssociations parameter in the Visual Studio Code Settings to set the Devicetree Visual Editor to show by default instead of the Text Editor when you open .dts or .overlay files. You can do this for example in the following way:

"workbench.editorAssociations": {
    "*.overlay": "devicetree.editor",
    "*.dts": "devicetree.editor"
   },

Editor UI areas

The editor is made of the following UI areas, described in detail in the following sections:

• Node Tree - A list of the nodes in a treeview, where you can control their properties.
• Node Inspector - A panel displaying information about the node selected in the Node Tree.
• Schematic Preview - A simplified graphical representation of the devicetree hardware configuration, which is meant to resemble the hardware schematic.
• Navigation Bar - A list of buttons that let you navigate between different parts of the Devicetree Visual Editor.

The editor uses some of the basic electronic symbols throughout its GUI and assigns an icon to each node based on keywords in the node name or labels (or both). The node type is always set in the first property of the node.

Note

All changes made in the Devicetree Visual Editor are automatically mirrored in the code of the devicetree file.

Node Tree

The Devicetree Visual Editor lists all available nodes for the selected devicetree file in a hierarchical Node Tree. This view is by default located to the left of the Schematic Preview area and it is the main interaction panel of the editor.

Clicking on the node name will display its properties in the Node Inspector and its schematic in the Schematic Preview.

Nodes can be associated with labels, the first of which is displayed next to the node name in the Node Tree. See the description of the Metadata tab in the Node Inspector for more information.

Node Tree actions

The following table lists actions that you can take in the Node Tree. These are contextual and depend on the node and its properties.

UI element/action	Type	Description
Add Node	Toolbar button	Click open the Add Node widget and add a new node to the list.
Enable/disable node checkbox	Checkbox	Check to enable the given node in the devicetree. Uncheck to disable the node. You cannot see or edit children of a disabled node. This option is related to the status property. Checked nodes have status = "enabled" and unchecked nodes have status = "disabled". Nodes without a checkbox don't have the status property.
Click +N label	Context menu action	Left-click on the +N label, if available, to go to the list of labels for the given node in the Metadata tab.
Show in Text Editor	Context menu action	Right-click on the node or property name to access the option and go to the location in the devicetree code file.
Copy Path	Context menu action	Right-click on the node or property name to access the option and copy the path to clipboard.
Delete	Context menu action	Click to remove the node.

Node Inspector

When you select a node in the Node Tree, the Node Inspector panel located under the tree displays properties and information about the currently selected node.

The Node Inspector groups the properties in a series of tabs, described in the following table.

Section	Description
Properties	Includes the list of properties for the selected node. Hovering with the mouse cursor over the property name will display a tooltip with information about the property.
Pins	Includes the list of pins for the selected node. Use the buttons next to the pin drop-down menu to configure the behavior of the chosen pin. These buttons correspond to the ones displayed in the pin assignment widget in the Schematic Preview.
Advanced	Includes the list of advanced properties for the selected node.
Metadata	Includes the list of labels and the help description for the selected node. The labels are unique, human-readable identifiers of the node. You can add custom labels using the Add Label button, located at the heading level. The description is taken automatically from the devicetree source files. You can use the Visit Online Documentation button at the heading level to open and read the source documentation for the node, either in the Zephyr SDK documentation or in the Devicetree specification.

Node Inspector actions

The following table lists UI elements in the node property entries and actions that you can take in the Node Inspector. These are contextual and depend on the node and its properties.

UI element/action	Type	Description
Controller selector	Drop-down on the panel toolbar	Click to select a controller from a drop-down menu. The list of options in the menu is populated from the Zephyr and nRF Connect SDK devicetree type YAML files.
Add Property	Button on the panel toolbar	Click to select a property from a dedicated window. The list of options in the window entries is populated from the Zephyr and nRF Connect SDK devicetree type YAML files.
Add new element	Button	Click to add a new element to a property in the Properties tab.
Show in Text Editor	Context menu action	Go to the location in the devicetree file. Right-click on the node or property name to access this option.
Show Type Binding	Context menu action	Open the devicetree bindings file at the location where the given property is defined. Right-click on the node or property name to access this option.
Copy Path	Context menu action	Copy the path to clipboard. Right-click on the node or property name to access this option.
Delete	Context menu action	Click to remove the current property element.

Schematic Preview

The Devicetree Visual Editor generates a simplified visual representation of a node in the Schematic Preview. The preview is based on the hardware circuit schematic for the given node type and it is available for most of the devicetree file nodes. The preview is automatically updated when you make changes to the nodes in the code file, the Node Tree, or in the Node Inspector.

The Schematic Preview also includes an area with basic information about the schematic file, such as the author of the file, the file name, and the date of the last edit.

Pin Overview

When started, the Devicetree Visual Editor displays the general Pin Overview of the SoC with all its available pins, including pins that have already nodes assigned. If there is more than one assignment, the pin features additional chevrons next to its entry, one for each additional assignment, and the tooltip provides information about all node assignments for the pin.

Note

If the node assignments for a pin have conflicts, the additional chevrons next to the pin entry are marked red.

Pin Management widget

The Pin Management widget lets you add new pin assignments and manage existing pin assignments directly from the Pin Overview screen.

The widget opens whenever you left-click a pin entry. If the pin has no assignment, the widget will open on the Add Assignment tab, which lets you assign a node to the pin and set some of its properties:

After you add one or more assignments to a pin, left-clicking the pin entry will open the widget on the Existing Assignments tab:

This tab always includes information about the pin assignment, such as node, function, and state. You can interact with it in the following ways:

Action	Description
Drop-down menu	Use it to select a different existing assignment for the given pin.
Wrap Text	Wraps the text in the description field.
Description field	Displays the hardcoded description for the given pin from the related pinctrl file.
Show Node	Closes the widget, selects the node in the Node Tree and the Node Inspector, and displays its circuit schematic.
Delete Assignment	Delete the currently displayed assignment from the pin.

Circuit schematics

The Schematic Preview focuses on the selected node when you use one of the following actions:

• Click Show Node in the Pin Management widget.
• Select a node in the Node Tree.

How the circuit schematic looks depends on the node type. Not all available node types display a circuit schematic.

As an example, the following image shows the hardware GPIO schematic for the gpio-keys driver node. This is the most common layout of the circuit schematics.

The schematic is divided into two areas, separated by a big vertical line in the middle:

• The area to the left of the line is meant to represent the SoC itself (in this case nRF52840). The gpio-keys driver is located under the /buttons/ node section of the devicetree file.
• The area to the right shows the pin connections.

The circuit schematics support several types of interactions.

External GPIO controllers

Both the circuit schematics and the Pin Overview can also display information about external GPIO controllers. These are listed separately with their pins, but only if the overlay file is configured to include them, for example using the sx1509b node available for some boards.

Schematic Preview actions

The Schematic Preview is interactive, with changes made in the preview automatically mirrored in the code file and the other way around.

Read the following sections for information about actions you can take in different areas of the Schematic Preview.

Interactions (general)

You can interact with the Schematic Preview for any node in the following manners:

Action	Type	Description
Click and hold RMB + drag cursor	Mouse action	Move the schematic in the preview area.
Use scroll wheel	Mouse action	Zoom the schematic preview in or out.
Click electronic symbol	Mouse action	Change them to the opposite one if they have two or more possible values.
Click the driver area in the schematic	Mouse action	Select the parent node in the Node Tree if you earlier selected a child node of the driver node.
Click the pin connection	Mouse action	Jump to the Pin Overview and open the Pin Management widget for the pin.
Recenter Viewport	Context menu action	Right-click in the schematic preview area to access the option. Use the option to recenter the schematic in the schematic preview.
Disable Automatic Viewport Recentering	Context menu action	Right-click in the schematic preview area to access the option. Once disabled, the schematic moves in relation to the node treeview.
Enable Automatic Viewport Recentering	Context menu action	Right-click in the schematic preview area to access the option. Once enabled, the schematic is recentered in the schematic view whenever the editor size changes.

Interactions (Pin Overview)

In addition to the general interactions, you can interact with the Pin Overview in the following ways:

Action	Type	Description
Left-click an assigned pin	Mouse action	Open the Pin Management widget that lists the current assignments and lets you change some of its properties.
Right-click an assigned pin	Mouse action	Open the context menu with several options valid for the pin, including Assign to Pin and Clear Pin.
Left-click an unassigned pin	Mouse action	Open the Pin Management widget that lets you assign a node to the pin and set some of its properties.
Assign to Pin	Context menu action	Right-click an assigned pin or unassigned pin to access the option. Use the option to open the pin assignment widget and assign or reassign a node to a pin.
Clear Pin	Context menu action	Right-click an assigned pin to access the option. Use the option to delete all node assignments from a pin.
Show in Text Editor	Context menu action	Right-click on the node or property name to access the option and go to the location in the devicetree code file.
Copy Node Path	Context menu action	Right-click on the node or property name to access the option and copy the path to clipboard.

Navigation Bar

The Navigation Bar includes buttons that let you move back and forth between the inspected elements. It also features the path field that displays the devicetree file structure and from where you can also select nodes or type in their names.

See the following table for the description of different UI elements.

UI element	Description
Left arrow	Go back to the previous node.
Right arrow	Go forward to the next nodes (after previously navigating back).
Home button	Click to return to the Pin Overview.
Path field	Click to navigate the devicetree file structure. Type to filter the node names.