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
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.
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
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
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
$ 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/nrf52840with the name of the board you're interested in. - Replace
sensor/bme680with any sample supported by your board.
$ cd zephyr/samples/sensor/bme680
$ dtsh
dtsh (0.2.4): 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