{"id":9655,"library":"devicetree","title":"Python Devicetree Library","description":"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.","status":"active","version":"0.0.2","language":"en","source_language":"en","source_url":"https://github.com/zephyrproject-rtos/python-devicetree","tags":["embedded","devicetree","hardware","parsing","zephyr","firmware"],"install":[{"cmd":"pip install devicetree","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for parsing YAML-formatted device tree bindings or related configuration files.","package":"pyyaml","optional":false},{"reason":"Used for parsing ELF files, which may contain embedded device tree blobs or related symbol information.","package":"pyelftools","optional":false}],"imports":[{"note":"The main class for loading and manipulating device trees. It resides in the `dtlib` submodule, not directly under the top-level `devicetree` package.","wrong":"from devicetree import DT","symbol":"DT","correct":"from devicetree.dtlib import DT"},{"note":"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.","symbol":"DTSource","correct":"from devicetree.dtlib import DTSource"}],"quickstart":{"code":"import os\nimport devicetree\n\n# Create a dummy DTS file for demonstration\ndts_content = \"\"\"\n/dts-v1/;\n\n/ {\n    compatible = \"acme,board-v1\";\n    cpus {\n        cpu@0 {\n            compatible = \"arm,cortex-m4\";\n            reg = <0>;\n        };\n    };\n    gpio@10000 {\n        compatible = \"gpio-controller\";\n        reg = <0x10000 0x100>;\n        #gpio-cells = <2>;\n    };\n};\n\"\"\"\ndts_path = \"example.dts\"\nwith open(dts_path, \"w\") as f:\n    f.write(dts_content)\n\ntry:\n    # Load the device tree from the DTS file\n    dt = devicetree.dtlib.DT(dts_path)\n    print(f\"\\n--- Device Tree Content ---\")\n    print(f\"Root node name: {dt.name}\")\n    \n    # Accessing properties of the root node\n    compatible_prop = dt.get_prop('compatible')\n    if compatible_prop: # get_prop returns DTProperty or None\n        print(f\"Root compatible: {compatible_prop.value}\")\n    \n    # Finding a specific node by path\n    cpu_node = dt.get_node(\"/cpus/cpu@0\")\n    if cpu_node:\n        print(f\"CPU Node path: {cpu_node.path}\")\n        cpu_compatible = cpu_node.get_prop('compatible')\n        if cpu_compatible:\n            print(f\"CPU Node compatible: {cpu_compatible.value}\")\n    \n    # Finding a node by compatible string\n    gpio_node = dt.get_node_by_compatible(\"gpio-controller\")\n    if gpio_node:\n        print(f\"GPIO Controller found at: {gpio_node.path}\")\n\nexcept Exception as e:\n    print(f\"An error occurred during device tree processing: {e}\")\nfinally:\n    # Clean up the dummy file\n    if os.path.exists(dts_path):\n        os.remove(dts_path)\n    print(f\"\\nCleaned up {dts_path}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.0.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure you are importing specific symbols from the `devicetree.dtlib` submodule, e.g., `from devicetree.dtlib import DT`.","cause":"Attempting to import `dtlib` directly, or misimporting symbols like `DT` from the `devicetree` top-level package instead of its submodule.","error":"ModuleNotFoundError: No module named 'devicetree.dtlib'"},{"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.","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.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'your_device_tree.dts'"},{"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.","cause":"The provided device tree file is syntactically malformed, corrupted, or uses an unsupported format/feature that the parser cannot handle.","error":"devicetree.dtlib.DTError: failed to load DT from 'malformed.dts'"}]}