Introduction to Device Tree Overlays in Android IoT

In the rapidly evolving landscape of Android IoT, automotive, and smart TV customizations, hardware heterogeneity is the norm. Custom boards often integrate unique combinations of sensors, actuators, and communication modules that are not part of the standard Android Open Source Project (AOSP) configurations. To manage this diversity efficiently, the Linux kernel relies on Device Trees (DTs).

Device Trees provide a descriptive language for non-discoverable hardware components, outlining their physical addresses, interrupts, and other crucial properties. However, modifying the base Device Tree for every minor hardware tweak or peripheral addition can necessitate recompiling the entire kernel, which is cumbersome and error-prone. This is where Device Tree Overlays (DTOs) come into play.

DTOs offer a modular and dynamic approach to extending or modifying a base Device Tree at runtime without altering the original. They allow system integrators to add, remove, or change properties of hardware devices by applying ‘overlay’ patches during the boot process. This hands-on guide will walk you through the process of implementing DTOs for a custom peripheral on an Android IoT board, enabling seamless integration of your unique hardware.

Prerequisites and Understanding the Landscape

What You’ll Need

• An Android IoT development board (e.g., a custom i.MX, Rockchip, or Qualcomm board).
• A Linux development host with AOSP source code synced for your target board.
• Basic familiarity with Linux kernel development, embedded systems, and Device Trees.
• The Device Tree Compiler (dtc) tool installed on your host.
• Access to the board’s bootloader (e.g., U-Boot) and fastboot for flashing.

Device Trees: A Quick Recap

At its core, a Device Tree is a data structure describing the hardware of a system. It’s organized as a hierarchy of nodes, where each node represents a hardware component (like a CPU, memory controller, or an I2C bus) and contains properties (key-value pairs) detailing its configuration. For example, a node might define a specific I2C device with its address and compatible driver string.

During boot, the bootloader loads a compiled Device Tree Binary (DTB) blob into memory and passes it to the kernel. The kernel then parses this DTB to enumerate and configure the hardware it needs to interact with, eliminating the need for hardcoded board-specific information within the kernel source itself.

The Power of DTOs

DTOs extend the base DT by allowing you to add new nodes, modify existing node properties, or even remove nodes, all without touching the original DTB. An overlay consists of one or more ‘fragments’, each targeting a specific node in the base DT. When applied, the kernel merges the overlay’s changes with the base DT in memory. This mechanism is incredibly powerful for:

• Adding new peripherals to an existing board design.
• Enabling or disabling specific hardware features dynamically.
• Modifying driver parameters or GPIO configurations.
• Reducing kernel image size and complexity by externalizing hardware descriptions.

Scenario: Adding an I2C Temperature Sensor (TMP102)

For this tutorial, let’s assume we have a custom Android IoT board, and we want to integrate an I2C-based TMP102 temperature sensor. This sensor is connected to I2C Bus 1 of our board and has the standard I2C address of 0x48. Our objective is to define this sensor within the Device Tree using an overlay so that the Linux kernel can recognize it and load the appropriate driver (tmp102 in this case), making it accessible to Android applications.

Step 1: Identifying the Base Device Tree

Before creating an overlay, you need to understand the structure of your board’s existing Device Tree. You can typically find the base DT source file (`.dts`) within your AOSP source tree under arch/arm64/boot/dts/<vendor>/<board-name>.dts (for ARM64) or similar paths for other architectures.

Alternatively, on a running Android system, you can inspect the loaded DT by navigating to /sys/firmware/devicetree/base/. You can explore this directory to understand the hierarchy and properties of your board’s hardware. Specifically, we need to locate the node for I2C Bus 1. It usually looks something like i2c@<address>, where <address> is the physical memory address of the I2C controller.

# Example: Examining the I2C bus in /sys/firmware/devicetree/base/i2c@.../ 

Step 2: Crafting Your Device Tree Overlay Source (`.dts`)

Now, let’s create our DTO source file, typically named with a -overlay.dts suffix, for example, tmp102-overlay.dts. This file will contain the fragments necessary to describe our TMP102 sensor.

/dts-v1/; /plugin/; #include <dt-bindings/gpio/gpio.h> / {    compatible = "your-board-vendor,your-board-model";    /* The __overlay__ keyword signifies this is an overlay */    __overlay__ {        /* Fragment 0 targets the I2C controller at a specific path */        fragment@0 {            target-path = "/soc/i2c@30800000"; /* Example path for I2C1, adjust for your board */            __overlay__ {                /* Add the TMP102 sensor as a child node to the I2C controller */                tmp102@48 {                    compatible = "ti,tmp102";                    reg = <0x48>; /* I2C address of the TMP102 */                    status = "okay";                };            };        };    }; }; 

Targeting the I2C Bus

The target-path property in the fragment is crucial. It tells the kernel which node in the base Device Tree this fragment intends to modify or extend. You must accurately determine the path to your I2C Bus 1 controller from your board’s base DTS or by inspecting /sys/firmware/devicetree/base/. Common paths might include /soc/i2c@... or /i2c@....

Defining the TMP102 Sensor Node

Inside the __overlay__ section of the fragment, we define the tmp102@48 node. The @48 indicates its I2C slave address. The compatible = "ti,tmp102" property is essential; it tells the kernel which driver (`tmp102.c` in this case) should bind to this device. The reg = <0x48> property explicitly defines its I2C address, and status = "okay" ensures the device is enabled.

Step 3: Compiling the Device Tree Overlay Binary (`.dtbo`)

Once your `.dts` overlay file is ready, you need to compile it into a binary format (`.dtbo`). This is done using the Device Tree Compiler (dtc) tool. Ensure dtc is installed on your Linux host (`sudo apt install device-tree-compiler` on Debian/Ubuntu).

dtc -@ -I dts -O dtb -o tmp102-overlay.dtbo tmp102-overlay.dts 

The -@ flag includes a symbol table, which can be useful for debugging. -I dts specifies the input format (DTS source), and -O dtb specifies the output format (DTB/DTBO binary). The output will be tmp102-overlay.dtbo.

Step 4: Integrating the DTO into the Android Build System

For Android, DTOs are typically packaged into a dedicated dtbo.img partition or sometimes appended to the boot.img. The process involves modifying your board’s Android build configuration.

1. Place your `.dts` and `.dtbo` files: Create a directory for your overlays within your device tree, e.g., device/<vendor>/<board-name>/dtb/overlays/, and place both tmp102-overlay.dts and the compiled tmp102-overlay.dtbo there.

2. Modify `BoardConfig.mk` or `device.mk`: Locate your board’s configuration file, usually device/<vendor>/<board-name>/BoardConfig.mk or a file included by it. You need to tell the Android build system about your new overlay.

   # Example for a custom board, ensure these paths match your setup BOARD_KERNEL_DTBO_OVERLAYS += device/<vendor>/<board-name>/dtb/overlays/tmp102-overlay.dtbo # If your board uses a different mechanism, like appending to boot.img, # you might need to adjust based on your bootloader's requirements. 

   The build system will typically use mkdtimg (a tool from AOSP) to package all specified `.dtbo` files into a single dtbo.img.

3. Rebuild the Android images: After modifying the build configuration, you need to rebuild at least the boot.img and dtbo.img. A full rebuild ensures all dependencies are met.

   source build/envsetup.sh lunch <your_target_product> make bootimage dtboimage -j$(nproc) # Or just `make -j$(nproc)` for a full rebuild 

Step 5: Flashing and Verifying the DTO

With the new boot.img and dtbo.img ready, it’s time to flash them to your Android IoT board.

fastboot flash boot boot.img fastboot flash dtbo dtbo.img fastboot reboot 

Verification

After the board reboots, you can verify if the DTO was successfully applied and if the sensor device node exists.

1. Check kernel boot log: Look for messages indicating DTO application.

   adb shell dmesg | grep -i "overlay" 

   You should see messages similar to “DT overlay was applied” or entries related to the I2C device being probed.

2. Verify device node existence: Check for the TMP102 device in the I2C bus directory.

   adb shell ls /sys/bus/i2c/devices/1-0048 

   If the directory exists, it indicates the kernel has recognized the device. You can further inspect its properties:

   adb shell cat /sys/bus/i2c/devices/1-0048/name # Should output: tmp102 adb shell cat /sys/bus/i2c/devices/1-0048/modalias # Should show i2c:tmp102 

Troubleshooting Common Issues

• `dtc` compilation errors: Double-check your `.dts` syntax, especially semicolons, braces, and property formats.
• Incorrect `target-path`: If the overlay doesn’t apply, the `target-path` might be wrong. Inspect your base DT (e.g., from `/sys/firmware/devicetree/base`) to confirm the correct path.
• DTO not loaded: Ensure `dtbo.img` was flashed correctly and your bootloader supports DTO loading. Check bootloader logs (e.g., via serial console) for messages related to DTBO.
• Driver not binding: If the device node appears but the driver doesn’t load, verify the `compatible` string in your overlay matches the one expected by the kernel driver.
• Conflicting properties: If your overlay modifies existing properties, be aware of the overlay application order and potential conflicts.

Conclusion

Device Tree Overlays are an indispensable tool for developing and maintaining custom Android IoT boards. They provide a flexible, modular, and robust mechanism for describing and integrating custom hardware peripherals without the need for constant kernel recompilations or modifications to the base Device Tree. By following this hands-on guide, you now have the knowledge to effectively implement DTOs, enabling your custom Android IoT solutions to adapt and thrive in diverse hardware environments. This approach fosters cleaner code, easier updates, and a more streamlined development workflow for your embedded projects.