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. ![]() |
Pins | Includes the list of pins for the selected node. ![]() |
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. |
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. |