Devicetree Visual Editor UI - nRF Connect for VS Code
Skip to content

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

    Actions View

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

  • 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.

Switching from the Devicetree Visual Editor to Text Editor

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.

Main screen of the Devicetree Visual Editor with UI areas highlighted

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.

Devicetree Visual Editor Node Tree

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.

An example of a property in the Node Inspector

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.
Properties tab of the Node Inspector
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.
Pins tab of the Node Inspector
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.
Advanced tab of the Node Inspector
Metadata Includes the list of labels and the help description for the selected node.
Description tab of the Node Inspector
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.
Controller selector
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 Property
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.

Pin Overview

Note

If the node assignments for a pin have conflicts, the additional chevrons next to the pin entry are marked red. An example of a pin with conflicting assignments

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:

Pin Management widget: Add Assignment tab

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

Pin Management widget: 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.

Example of a schematic for a buttons node

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.

Propagation of changes to the code file and vice-versa

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.

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.

Selecting nodes in the Navigation Bar

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

Devicetree Visual Editor Navigation Bar

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.