On Orange Pi's own Debian/Ubuntu images, interfaces such as extra I2C buses, SPI or UARTs on the header are switched on with device-tree overlays. The switch is a text file, not the boot script.
The file that matters
The RK3588 boot script shipped by orangepi-build starts with a clear instruction: don't edit the boot script, edit /boot/orangepiEnv.txt. The script loads that file and then applies two lists of overlays:
Variable in /boot/orangepiEnv.txt |
Loaded from | Use for |
|---|---|---|
overlays= |
/boot/dtb/rockchip/overlay/<prefix>-<name>.dtbo |
overlays shipped with the kernel |
user_overlays= |
/boot/overlay-user/<name>.dtbo |
your own overlays |
The <prefix> is set per SoC family in orangepi-build (for RK3588 it is rk3588, and some kernel branches use a different prefix), so look in /boot/dtb/rockchip/overlay/ on your image for the exact names available.
Enable a kernel-provided overlay
ls /boot/dtb/rockchip/overlay/ | grep -i -E 'i2c|spi|uart' # what exists for this kernel
sudo nano /boot/orangepiEnv.txt
# overlays=<name1> <name2> (names without prefix and .dtbo, space-separated)
sudo reboot
Names go space-separated on one overlays= line; write the part after <prefix>-, without .dtbo. Which header pins a bus uses depends on the board model: check the model's pin definition (for example with gpio readall from wiringOP).
Add your own overlay
sudo orangepi-add-overlay my-sensor.dts
sudo reboot
The tool compiles the .dts with dtc, copies the .dtbo to /boot/overlay-user/, and appends the name to user_overlays= in /boot/orangepiEnv.txt. It needs root, an Orange Pi image (it checks for /etc/orangepi-release and /boot/orangepiEnv.txt), and a dtc that can compile overlays; install the kernel headers package if it complains.
Troubleshooting
- Nothing changed after reboot: compare the spelling with the files in the overlay directory, and watch the serial console: the boot script prints "Applying kernel provided DT overlay …" for each overlay it loads.
- Board doesn't boot after adding an overlay: remove the entry from
/boot/orangepiEnv.txtby mounting the SD card's boot partition on another machine. - Armbian images use their own environment file and tools; this procedure is for Orange Pi's images built with orangepi-build.