Python Devicetree Library

0.0.2 · active · verified Fri Apr 17

The `devicetree` library provides Python tools for parsing and manipulating devicetree files, commonly used in embedded systems. It supports both binary (.dtb) and source (.dts) formats. The current version is 0.0.2, indicating early development, and releases are not on a fixed cadence.

Common errors

```
ModuleNotFoundError: No module named 'devicetree.dtlib'
```
cause Attempting to import `dtlib` directly, or misimporting symbols like `DT` from the `devicetree` top-level package instead of its submodule.

fix Ensure you are importing specific symbols from the `devicetree.dtlib` submodule, e.g., `from devicetree.dtlib import DT`.
```
FileNotFoundError: [Errno 2] No such file or directory: 'your_device_tree.dts'
```
cause The path provided to the `DT` constructor (for a DTB or DTS file) does not exist, is misspelled, or is inaccessible from where the Python script is executed.

fix Double-check the file path and ensure the device tree file (`.dtb` or `.dts`) is present at the specified location and has correct read permissions.
```
devicetree.dtlib.DTError: failed to load DT from 'malformed.dts'
```
cause The provided device tree file is syntactically malformed, corrupted, or uses an unsupported format/feature that the parser cannot handle.

fix Verify the integrity and correctness of your `.dts` or `.dtb` file. Use standard devicetree compilers (`dtc`) or validators to check its syntax and structure. Ensure it complies with the Devicetree Specification.

Warnings

gotcha The library is currently at version 0.0.2, indicating early development. The API surface may be unstable and subject to breaking changes in minor releases.
Fix: Always pin to exact versions (e.g., `devicetree==0.0.2`) and review release notes carefully when upgrading. For new projects, consider using the latest available version.
gotcha When parsing DTS files that use `#include` directives (e.g., to include `.dtsi` files), ensure that the include paths are correctly configured or that included files are accessible relative to the primary DTS file.
Fix: Verify that all `.dtsi` files are in the same directory as the main `.dts` file or explicitly manage include paths if the library offers such options (check `DT` or `DTSource` constructor arguments).

Install

pip install devicetree Install stable version

Imports

DT
wrong:
```
from devicetree import DT
```
correct:
```
from devicetree.dtlib import DT
```
The main class for loading and manipulating device trees. It resides in the `dtlib` submodule, not directly under the top-level `devicetree` package.
DTSource
```
from devicetree.dtlib import DTSource
```
A specialized class for loading device trees specifically from .dts (source) files, offering more source-level details. The `DT` class can also handle .dts files.

Quickstart

This quickstart demonstrates how to load a device tree from a temporary .dts file, access its root node, retrieve properties, and find specific child nodes by path or compatible string. It includes cleanup of the temporary file.

import os
import devicetree

# Create a dummy DTS file for demonstration
dts_content = """
/dts-v1/;

/ {
    compatible = "acme,board-v1";
    cpus {
        cpu@0 {
            compatible = "arm,cortex-m4";
            reg = <0>;
        };
    };
    gpio@10000 {
        compatible = "gpio-controller";
        reg = <0x10000 0x100>;
        #gpio-cells = <2>;
    };
};
"""
dts_path = "example.dts"
with open(dts_path, "w") as f:
    f.write(dts_content)

try:
    # Load the device tree from the DTS file
    dt = devicetree.dtlib.DT(dts_path)
    print(f"\n--- Device Tree Content ---")
    print(f"Root node name: {dt.name}")
    
    # Accessing properties of the root node
    compatible_prop = dt.get_prop('compatible')
    if compatible_prop: # get_prop returns DTProperty or None
        print(f"Root compatible: {compatible_prop.value}")
    
    # Finding a specific node by path
    cpu_node = dt.get_node("/cpus/cpu@0")
    if cpu_node:
        print(f"CPU Node path: {cpu_node.path}")
        cpu_compatible = cpu_node.get_prop('compatible')
        if cpu_compatible:
            print(f"CPU Node compatible: {cpu_compatible.value}")
    
    # Finding a node by compatible string
    gpio_node = dt.get_node_by_compatible("gpio-controller")
    if gpio_node:
        print(f"GPIO Controller found at: {gpio_node.path}")

except Exception as e:
    print(f"An error occurred during device tree processing: {e}")
finally:
    # Clean up the dummy file
    if os.path.exists(dts_path):
        os.remove(dts_path)
    print(f"\nCleaned up {dts_path}")

view raw JSON →