Getting Started Guide

Handbook

DTSh - A Devicetre Shell

DTSh is a Devicetree Source (DTS) files viewer with a shell-like command line interface:

• navigate and visualize the devicetree
• search for devices, bindings, buses or interrupts with flexible criteria
• redirect command output to files (text, HTML, SVG) to document hardware configurations or illustrate notes
• rich Textual User Interface, command line auto-completion, command history, user themes

You can use it with:

• all DTS files generated by Zephyr at build-time (aka build/zephyr/zephyr.dts)
• arbitrary DTS files with bindings compatible with Zephyr's Devicetre bindings syntax

Status

This project started as a Proof of Concept of a simple tool that could open and understand the famous zephyr.dts file generated at built-time. Source code and documentation for this prototype (DTSh 0.1.x) are still available from the main branch of this repository.

This branch (dtsh-next) mirrors and packages the new code base which serves as a proposal to upstream DTSh as a Zephyr extension to West (would be west dtsh): RFC - DTSh, shell-like interface with Devicetree

This is the branch that shall be installed, used and commented on: it is now the default branch of this repository.

Latest release: DTSh 0.2.2 (PyPI).

Note

Although this branch reflects the state of the PR's content, it's not an actual mirror:

• while the implementation in the RFC can find the python-devicetree library the same way other Zepyhr's devicetree tool do, DTSh has to re-distribute snapshots of this library when published on PyPI (see Possible multiple different versions of python-devicetree)
• this code base does not include the West integration which we couldn't install from PyPI
• changes may happen here first, and be backported to the RFC, or vice versa

DTSh in a Nutshell

Here are some one-liner steps for the very impatient:

• install DTSh in your Zephyr development environment
• generate the DTS for the board you're interested in
• open this devicetree in DTSh

Please refer to the project's documentation, where you'll find:

• a Getting Started Guide: install, configure and run DTSh
• the DTSh Handbook: the shell and its rich Textual User Interface, reference manual of built-in commands, numerous usage examples

There's also a beginners friendly blog post at golioth: DTSh – A Devicetree viewer for Zephyr

Install DTSh

This method installs the latest DTSh version in the Python virtual environment that belongs to your West workspace.

From the same prompt where you usually enter west commands:

$ pip install -U dtsh
$ dtsh -h
usage: dtsh [-h] [-b DIR] [-u] [--preferences FILE] [--theme FILE] [DTS]

shell-like interface with Devicetree

optional arguments:
  -h, --help            show this help message and exit

open a DTS file:
  -b DIR, --bindings DIR
                        directory to search for binding files
  DTS                   path to the DTS file

user files:
  -u, --user-files      initialize per-user configuration files and exit
  --preferences FILE    load additional preferences file
  --theme FILE          load additional styles file

Generate the DTS

$ cd zephyr/samples/sensor/bme680
$ west build -b nrf52840dk_nrf52840

Tip

• Actually building the sample is not necessary, the configuration phase is sufficient: cmake -B build -DBOARD=nrf52840dk_nrf52840
• Replace nrf52840dk_nrf52840 with the name of the board you're interested in.
• Replace sensor/bme680 with any sample supported by your board.

Open the devicetree

$ cd zephyr/samples/sensor/bme680
$ dtsh
dtsh (0.2.2): A Devicetree Shell
How to exit: q, or quit, or exit, or press Ctrl-D

/
> ls -l
 Name              Labels          Binding
 ───────────────────────────────────────────────────────
 chosen
 aliases
 soc
 pin-controller    pinctrl         nordic,nrf-pinctrl
 entropy_bt_hci    rng_hci         zephyr,bt-hci-entropy
 sw-pwm            sw_pwm          nordic,nrf-sw-pwm
 cpus
 leds                              gpio-leds
 pwmleds                           pwm-leds
 buttons                           gpio-keys
 connector         arduino_header  arduino-header-r3
 analog-connector  arduino_adc     arduino,uno-adc