Why is hardware peripherals setup / config (e.g. using device tree overlay) hidden from view

I have literally only an hour ago discovered DietPi and have successfully downloaded the latest DietPi version, installed and now have been through the standard config process, also having gone through all the auto apt update/upgrade startup processes.

I am using a Pine SOQUARTZ board.

First impressions. Well, I am highly impressed by the structured process, the clean documentation and what appears to be a smooth installation and getting started process. It’s very good. So well done.

However, I have quickly hit a stumbling block to achieve my specific need.

I cannot find any documentation that provides guidance on how to enable GPIO’s, I2C and SPI.

Is there a reason for this gap in what is really good documentation.

I have been searching through the forum, including community tutorials, and here too is no clear guidance.

My first thought, based on knowledge of ubuntu/debian, was to go to the boot folder and search for device tree overlays - there is usually a separate folder for this.

But nothing was found here.

So I came to the forum for insight. Here, through a quick read through of some forum feedback, I discover another folder /proc/. It looks like this is where the good stuff is, but as nothing is documented on DietPi, so I thought to ask for guidance. There is also a couple of scripts inside the boot folder that appear to handle hardware config too (e.g. dietpi-set_hardware). But there’s no documentation for this either.

Finally, I came across this command in the forum.

find /proc/device-tree/ -name status -exec echo -ne '\n{}: ' \; -exec cat {} \;

It at least confirms that SPI and I2C is disabled.

So I need help and any advice is greatly appreciated.


You are right, that’s a gap we arctually have. Something we are working on but it require time and effort as we support a larger number of SBC and the docs should fit to all of them at the end.

For the current configuration, maybe @MichaIng could have a look.

1 Like

Happy to help on this. Same issue. DietPi works great on the board, but turning SPI and I2C on is puzzling me.

Even if there’s a manual method (editing in a file) that would be ok for the moment. Documentation and a neater method could come later.

I’m wondering how to approach this best, since not all device tree overlays available from the respective Armbian kernel are working on all SBCs which use this kernel + same prefix. Some overlays are even completely broken. So I’m not sure if a generic checkbox menu to (de)select overlays is so great. Better would be probably one for specific features tested on specific devices, which has been tested to work. But of course this means much more efforts for us, also for maintaining/updating the parts as every (major) kernel upgrade can change or break things again.

The Quartz64 kernel build, same as (official) Debian kernel builds and generally builds done with untouched mainline kernel sources, do not have device tree overlays. Armbian adds them with kernel patches and Raspberry Pi use an own vendor kernel.

However, its good to know that those interfaces are disabled by default on Quartz64. We can either add device tree overlays to enable them or enable them just by default. Not sure whether there are other common uses for those pins which would be broken when enabling I2C and SPI?

Based on the little I’ve seen so far, there doesn’t appear to be a working model out there that ticks all the boxes (i.e. works seamlessly).

On a positive note, it appears that you have almost completed a config framework for handling hardware setup (DTO’s) but at the moment you have placed a condition (restriction) in the hardware setup script for just Raspberry Pi boards. A good approach considering the problems as you have described.

Personally, I feel DietPi should try to handle the overlay configuration process like it does when you enable Bluetooth (i.e. it pulls the required files from a repository and installs then purges when you disable) rather than like Armbian which dumps all sorts of DTO’s into an overlay folder and most of those are for the wrong board and you cannot determine if the ones, which are for the right board, have been configured correctly (as they’re binary .dtbo files).

I also think that Radxa (makers of Rock boards) are doing the right thing by have a dedicated overlays repository: GitHub - radxa/overlays: Additional device tree overlays to support different hardwares on Radxa products

This allows you to verify/validate that the overlay you want is correct or add in a pull request to change/create new etc.

So maybe to make life easier with DietPi hardware overlay setup all you need to do is add in the overlay compile command/process into your scripts and have a menu option for the user to either enable/disable standard overlays (which pulls/purges etc.) and possibly allow you to select a local .dts file which will be compiled and placed in the correct folder etc.

Sounds easy, right :grimacing:

Or even just a coherent explanation of a process that could be done manually.

There are dts/dtbo/dtb files in various places for most of the boards/components. But finding them and understanding the process is difficult. Whereas the actual process (once understood) seems to be “not that hard”.


I think you guys have a wrong impression how things do/can work (no offence) :slightly_smiling_face:.

We do not “restrict” anything, but only the Raspberry Pi kernel and bootloader, maintained by RPi developers and distributed via official RPi package repository, provide reliable device tree overlays and a way to toggle Bluetooth that way. If it’s about Bluetooth, on all other SBCs I’m aware of it is enabled OOTB (we just install Bluez tools on top). The method of how things are/can be done on RPi is unique and cannot be just “revealed” on other SBCs, but a completely new method would need to be added.

Note that mainline Linux is not designed to compile for a single SBC only (which would be highly inefficient anyway), but the configuration flags/options always define an architecture and SoC family. You can basically see it here in the official Linux sources: dts « boot « arm64 « arch - kernel/git/stable/linux.git - Linux kernel stable tree

So you enable flags for 64-bit ARM + Rockchip, and with this the compiled kernel does natively support all 64-bit Rockchip ARM SBCs (which have mainline Linux support). Armbian just follows this instead of patching the sources in a way to build an own kernel for each and every SBC (impossible to maintain). You can also see that there are no device tree overlays at all in Linux sources. Those are all added by Armbian developers or community members who have time and mood to figure things our and test them etc. And since there is naturally one kernel for an SoC family, logically it contains all overlays for this SoC family. Armbian solves this partly by using prefixes, i.e. rk3399- for the beginning of the overlay file name to define it being compatible with the Rockchip RK3399 SoC only, which works well in all cases where it is not a specific peripheral which requires PCB support from a specific SBC instead (but Armbian usually does not ship such kind of overlays anyway).

Now since overlays are not maintained within the Linux kernel, there is no guarantee that they are still functional after a major kernel upgrade and Armbian does not have the capabilities to test each overlay with each Linux version on each SBC and in case update them. This leads to this unpleasant situation where they may or may not work or break things, or break after any next kernel upgrade. But who do you want to blame for since those overlays are developed/maintained in peoples spare time?

So it is not at all about our scripts, but about the fact that overlays are badly maintained and cannot be relied on. If we do now just add a GUI to enable them easily, people will start reporting issues if they do not work, even that it is outside of our responsibility, scope and abilities to deal with those issues. So based on this it seems not wrong to me to keep this somewhat a hidden and hence unsupported (users own responsibility) feature.

So based on this, I thought a little more and we talked a bid about it in our weekly meeting yesterday. Since there is no way we can maintain a per-SBC menu with overlays known to work, as we do not own all SBCs and even then had no capacities to test them with every kernel upgrade (as Armbian doesn’t have either), a generic menu to just list all overlays with the right prefix is the only way (just like Armbian does with their armbian-config tool). But we must make it clear that there is zero guarantee that they work and that they can break the board/booting, so it is each users full own responsibility and one must have a plan how to access the /boot/dietpiEnv.txt to manually remove the overlay in case the board does not work.

How is it better when you have to download and compile overlays first, compared to just adding them to a config file to enable them? Again, it is not at all about the way how overlays are provided, but only about the question whether they are working reliably or not. Of course Radxa (hopefully) does test them on their SBCs with their own kernel when providing them. They also do not need to test them on new Linux upgrades, because they never upgrade their Linux builds for a specific SBC, which is a much larger problem IMO.

I hope I made it clear now that there are no “standard” overlays, but that those are all written by developers or community members in their spare time, so the problem is the source of reliable overlays, not the question how to provide/compile/enable them.


@MichaIng thanks for detailed feedback. There is plenty to think about.

I decided to go back to basics and this guide concurs with what you are saying. There is plenty to digest here… Device Tree Usage - eLinux.org

I think this is where the “compatible” property plays a role, not only for the board or device but also for the driver (e.g. spi, i2c, pwm etc), to ensure that breaking changes in a new release are handled correctly by an overlay.

Hence the dislike for just seeing the compiled .dtbo files in a local folder, without at least a readme file pointing you back to a repository with the script file itself. Otherwise, if and when they do not work, you have no way of determining what the problem is. Anyway, these driver script files are pretty small (<1kB) so they can readily co-exist on a SBC device without causing much bloat.

Quite right, but actually I was asking a more basic question on setup, on the assumption that all things will just work reliably. Of course, in the real world that is not always the case.

Agree, but in this post my version of standard overlays simply meant those overlays without requiring additional parameter settings, other than say switching an i2c overlay (e.g. i2c3) status property from it’s default “disabled” to “okay”.

EDIT: Just to clarify here. The way I see it, is that the “.dtb” file, which is the binary created from one of these overlays is the “template” rockchip « dts « boot « arm64 « arch - kernel/git/stable/linux.git - Linux kernel stable tree

What I am really referring to in this post, and also regarding what I referred to as standard overlays, is the “.dtbo” for a specific peripheral.

Anyhow, for now all I’m looking for is guidance on setup.

Nope, this is only a meta attribute for the kernel to decide whether to apply an overlay or not, based on hardware identifiers, not based on the kernel version/build/available nodes etc. It does not guarantee that the actual content of the overlay is valid/works/breaks. If the alias or path or a node changes, or if attribute names or values change, the overlay is broken.

If you are able to fix a device tree, you should be also able to convert the dtbo to dts as you’d need to do the other way round for compiling them:

dtc -I dtb -O dts /path/to/overlay.dtbo

But most users won’t be able to fix the sources and benefit more from pre-compiled overlays so that dtc does not need to be called. Again

the problem is the source of reliable overlays, not the question how to provide/compile/enable them.

Those are no “overlay” templates, but device tree sources. But yes, dts is the source format, dtb is the binary format. Overlays are meant as a way to adjust parts of the device tree based on user needs. But it’s the very same file type in the end, just applied on top of an existing loaded device tree.

You mean you call those overlays which do only switch one status property from disabled to okay and nothing else “standard overlays”? Okay understood. Often it is really nothing more than that and then it is usually also simple to create/fix them. But often it gets more complicated if e.g. the default device attributes are rubbish and need to be fixed as well.

However, let’s see whether it is simple here. Can you show the output of

find /proc/device-tree/ -name status -exec echo -ne '\n{}: ' \; -exec cat {} \;

Let’s create and test device tree overlays to enable each disabled node. If those work, I can add them to our Quartz64 build script to have them shipped with our firmware packages. Or I adjust the device tree source itself to have them enabled OOTB. Still not sure whether there is much downside when doing this, i.e. if there are other common uses for the affected GPIO pins.

1 Like

Sure. Here is one I very recently created on Debian (Plebian) for SPI3, which enables CS0 and CS1.

I discovered that with Plebian (Debian), I was able to amend extlinex.conf myself as it allows me to add in my own dtbo folder and filename details in a “u-boot” config file, found in /etc/default, and then use a u-boot-update utility to update extlinux.conf. This seems to work well enough.

But I then discovered that you had to then manually bind spidev to spi bus + cs pin reference. I was able to automate this on bootup, by using a rc.local bash script, which is stored in /etc/


/ {
        fragment@0 {
                target = <&spi3>;

                __overlay__ {
                        status = "okay";
                        #address-cells = <1>;
                        #size-cells = <0>;
                        cs-gpio = <0>,<0>;
			spidev@0 {
				compatible = "spidev";
				status = "okay";
				reg = <0>;

                        spidev@1 {
                                compatible = "spidev";
                                status = "okay";
                                reg = <1>;


I discovered that I needed this line, where <0> represents native allocations, to get both cs0 and cs1 enabled. Apparently you can also add in your own cs pin by specifying a GPIO pin reference here too. So you can have more than 2 cs pins for example.

cs-gpio = <0>,<0>;

To bind the spidev you need to add the following in rc.local


echo spidev > /sys/bus/spi/devices/spi3.0/driver_override
echo spi3.0 > /sys/bus/spi/drivers/spidev/bind

echo spidev > /sys/bus/spi/devices/spi3.1/driver_override
echo spi3.1 > /sys/bus/spi/drivers/spidev/bind

exit 0

I am still working on an i2c overlay as that too (I think) requires a binding to a driver, although it’s not clear which one to use as there are multiple in /sys/bus/i2c/drivers$

drwxr-xr-x 2 root root 0 Jan  1  1970 dummy
drwxr-xr-x 2 root root 0 Apr  7 18:58 fan53555-regulator
drwxr-xr-x 2 root root 0 Jan  1  1970 max77620
drwxr-xr-x 2 root root 0 Jan  1  1970 pca953x
drwxr-xr-x 2 root root 0 Jan  1  1970 rk808
drwxr-xr-x 2 root root 0 Jan  1  1970 rtc-ds1307
drwxr-xr-x 2 root root 0 Jan  1  1970 rtc-pcf85063
drwxr-xr-x 2 root root 0 Jan  1  1970 rtc-pcf8563
drwxr-xr-x 2 root root 0 Jan  1  1970 si5341
drwxr-xr-x 2 root root 0 Jan  1  1970 simple-mfd-i2c
1 Like