RK3588 Device Tree Configuration

Last Update: 2024-03-13

The following guide or recipe requires shell access to your FydeOS installation, therefore developer mode is assumed to be enabled. If altering system file is required, you will also need to disable root file system verification.

Introduction

The RK3588 SOC supports the loading of both FydeOS’s built-in device tree overlay files and user-defined dtbo files during startup.

The Importance of Loading Device Tree Overlays

Loading device tree overlays primarily enhances hardware configuration flexibility, reduces system maintenance costs, and facilitates user customization of hardware configurations. It also simplifies troubleshooting and debugging.

By leveraging device tree overlays, users can configure hardware to suit their needs without modifying the kernel code. This approach also simplifies the process of identifying and resolving potential issues. For example, users can enable or disable specific peripherals, such as PWM fans or I2C devices, based on their project requirements.

Prerequisites

To proceed, you should understand the basic concepts of device tree overlays and basic Linux command-line operations.

Step-by-Step Procedure

Step 2: Enter the bash shell environment

To customize the loading of device tree overlays, sign in to any FydeOS account and enter the desktop. Access administrator privileges by navigating through crosh (Control + Alt + T) or tty and typing sudo su.

Note: From FydeOS v17 and openFyde r114 onwards, sudo su will no longer work. Please use sudo -i instead. This change does not impact older versions.

Step 3: View the built-in `device tree overlays`

The built-in device tree overlays are located in the /boot/rockchip/overlay/ directory. After entering the ls /boot/rockchip/overlay/*dtbo command, you will see the file list, as shown below (using rock5b-fydeos as an example):

localhost ~ # ls  /boot/rockchip/overlay/
pwm-fan.dtbo                       rk3588-i2c8-m4.dtbo   rk3588-pwm15-m0.dtbo  rk3588-pwm6-m2.dtbo             rk3588-spi1-m1-cs1-spidev.dtbo  rk3588-uart7-m1.dtbo              rock-5b-hdmi2-8k.dtbo
rk3588-add-hdptxphy_hdmi_clk.dtbo  rk3588-pwm12-m0.dtbo  rk3588-pwm15-m1.dtbo  rk3588-pwm7-m3.dtbo             rk3588-uart2-m0.dtbo            rk3588-uart7-m2.dtbo              rock-5b-radxa-display-10fhd.dtbo
rk3588-i2c0-m1.dtbo                rk3588-pwm13-m0.dtbo  rk3588-pwm15-m3.dtbo  rk3588-pwm8-m0.dtbo             rk3588-uart2-m2.dtbo            rk3588-unlock-opps.dtbo           rock-5b-sata.dtbo
rk3588-i2c1-m0.dtbo                rk3588-pwm13-m2.dtbo  rk3588-pwm2-m1.dtbo   rk3588-spi0-m2-cs0-spidev.dtbo  rk3588-uart3-m1.dtbo            rock-5a-radxa-display-10fhd.dtbo
rk3588-i2c3-m1.dtbo                rk3588-pwm14-m0.dtbo  rk3588-pwm3-m1.dtbo   rk3588-spi0-m2-cs1-spidev.dtbo  rk3588-uart4-m2.dtbo            rock-5ab-camera-imx415.dtbo
rk3588-i2c7-m3.dtbo                rk3588-pwm14-m1.dtbo  rk3588-pwm5-m2.dtbo   rk3588-spi1-m1-cs0-spidev.dtbo  rk3588-uart7-m1-ctsn-rtsn.dtbo  rock-5b-hdmi1-8k.dtbo

Step 4: Load the built-in `device tree overlays`

FydeOS for RK3588 SOC series, like Armbian’s uEnv.txt, supports Env.txt, located in /mnt/stateful_partition/fyde/Env.txt. For first-time users, you may need to manually create the /mnt/stateful_partition/fyde/ directory and /mnt/stateful_partition/fyde/Env.txt file. Here’s an example using rock5b’s pwm-fan fan control overlay:

For first-time use, create the fyde folder
Terminal window
```
mkdir -p /mnt/stateful_partition/fyde/
```
Use nano/vim to edit the Env.txt file, add the dtbo file name to overlays=, separate multiple overlays with a space
Terminal window
```
overlays=pwm-fan
```
Save the changes

Step 5: Restart the system

After making the changes, restart the system to apply them.

Step 6: Add custom `device tree overlays` files

FydeOS requires user-defined device tree overlays, or .dtbo files, to be placed in the /mnt/stateful_partition/fyde/user_overlay/ folder. If you’re a first-time user and the folder doesn’t exist, create it. Then, copy the relevant .dtbo files into this folder.

Step 7: Load custom `device tree overlays` files

Loading custom device tree overlays is similar to loading built-in ones. You need to modify the /mnt/stateful_partition/fyde/Env.txt file.

Use nano/vim to edit the Env.txt file, add the dtbo file name to user_overlays=, separate multiple overlays with a space

user_overlays=foo bar

Step 8: Restart the system

Restart the system to apply the changes.

Troubleshooting

The overlays or user_overlays defined for loading the overlay do not work.

Check the case in the Env.txt file is correct, and separate multiple overlays with an English blank line. For custom overlays, ensure that the dtbo files in /mnt/stateful_partition/fyde/overlay are valid.

Why did changing the overlays or user_overlays cause the system to fail to boot?

Before making changes, ensure that the overlay you’re loading has been verified; otherwise, it may cause the system to fail to boot. If this happens, you can undo your changes by manually mounting the /fyde/Env.txt file corresponding to the first partition of the system’s disk.