Introduction: Unlocking Custom Peripherals in Android Things

Android Things, Google’s embedded operating system built on the Android Open Source Project (AOSP), offers a robust platform for IoT devices. While it provides standard APIs for common peripherals, many specialized IoT applications require custom hardware components that aren’t natively supported. This is where Hardware Abstraction Layers (HALs) become crucial. Porting Android Things to a custom board or integrating unique peripherals often necessitates crafting your own HALs to bridge the gap between your specific hardware and the Android framework. This expert-level guide will walk you through the intricacies of designing, implementing, and integrating a custom HAL for your Android Things OS port, ensuring your unique peripherals function seamlessly.

The Android Things Architecture and the Role of HALs

Android Things inherits much of its architecture from AOSP. At its core, the system consists of the Linux kernel, a Hardware Abstraction Layer (HAL), and the Android Framework. The kernel provides basic device drivers, allowing the operating system to interact with hardware. However, the Android Framework, which exposes APIs to app developers, doesn’t directly communicate with kernel drivers. Instead, it relies on HALs.

A HAL acts as a standardized interface between the hardware-specific kernel drivers and the higher-level Android Framework. It typically comprises C/C++ libraries that wrap the kernel driver functionalities into a consistent API that the Android system services can invoke. This abstraction layer allows Google to maintain a consistent API across diverse hardware, while hardware manufacturers can implement their specific drivers underneath without altering the framework.

Why Custom HALs for Android Things?

For standard peripherals like GPIO, I2C, SPI, or UART, Android Things often provides pre-built HAL implementations compatible with common SoC (System-on-Chip) architectures. However, if your custom board features:

• A unique sensor with a non-standard communication protocol.
• A specialized display controller.
• A custom motor driver or actuator.
• Proprietary security hardware.

…then a custom HAL is indispensable. It’s the only way for your Android Things applications to robustly and efficiently interact with these bespoke hardware components.

Anatomy of a Custom HAL: From Interface to Implementation

A custom HAL typically involves several components:

1. Kernel Driver: A low-level driver (often in C) interacting directly with the hardware, exposed via sysfs or a character device.
2. HAL Interface Definition: Defined using Android’s Interface Definition Language (AIDL or HIDL for older Android versions, though AIDL is preferred for newer ones). This specifies the functions the HAL will expose.
3. HAL Implementation: A C++ library that implements the defined interface, making calls to the kernel driver.
4. JNI Layer (Optional but Common): A Java Native Interface layer to bridge the C++ HAL implementation with Java services in the Android framework.
5. Android Framework Service/Manager: A Java class that exposes the HAL’s functionality to applications through a public API.

Step-by-Step: Implementing a Simple Custom GPIO HAL

Let’s assume we have a custom LED connected to a specific GPIO pin on our custom board, and we want to control it from an Android Things app. We’ll outline the steps for a simplified scenario.

1. Kernel Driver (Conceptual)

First, ensure your Linux kernel has a driver for your GPIO controller, and optionally, a simple character device driver that exposes the LED’s state. For brevity, we’ll assume a `myled_gpio` character device at `/dev/myled` that accepts simple write commands (‘1’ for ON, ‘0’ for OFF).

2. Define the HAL Interface (AIDL)

Create an AIDL interface for your custom HAL. This will live within your AOSP tree, for example, at hardware/interfaces/mydevice/aidl/com/example/mydevice/IMyDevice.aidl.

// com/example/mydevice/IMyDevice.aidl
package com.example.mydevice;

interface IMyDevice {
    void setLedState(boolean on);
    boolean getLedState();
}

You’ll also need an Android.bp file in hardware/interfaces/mydevice/aidl to build this AIDL:

// hardware/interfaces/mydevice/aidl/Android.bp
aidl_interface {
    name: "com.example.mydevice",
    srcs: [
        "com/example/mydevice/IMyDevice.aidl",
    ],
    stability: "vintf",
    vndk_version: "current",
}

3. Implement the HAL Service (C++)

Next, create the C++ implementation of your HAL service. This will open and interact with your kernel driver. Place this in a new directory, e.g., hardware/interfaces/mydevice/service/.

Create Android.bp for the service:

// hardware/interfaces/mydevice/service/Android.bp
cc_binary {
    name: "android.hardware.mydevice-service",
    vendor: true,
    relative_install_path: "hw",
    srcs: [
        "MyDevice.cpp",
        "main.cpp",
    ],
    shared_libs: [
        "libbinder",
        "liblog",
        "libcutils",
        "com.example.mydevice-V1-ndk", // Generated AIDL stub
    ],
    header_libs: [
        "com.example.mydevice-V1-ndk_headers",
    ],
}

And the C++ implementation (MyDevice.cpp):

// hardware/interfaces/mydevice/service/MyDevice.cpp
#include "com/example/mydevice/IMyDevice.h"
#include <android/binder_manager.h>
#include <android-base/logging.h>
#include <string>
#include <fstream>
#include <iostream>

namespace com { namespace example { namespace mydevice {

class MyDevice : public IMyDevice {
public:
    binder_status_t setLedState(bool on) override {
        LOG(INFO) << "setLedState: " << (on ? "ON" : "OFF");
        std::ofstream ofs("/dev/myled");
        if (!ofs.is_open()) {
            LOG(ERROR) << "Failed to open /dev/myled";
            return STATUS_UNKNOWN_ERROR;
        }
        ofs << (on ? '1' : '0');
        ofs.close();
        return STATUS_OK;
    }

    binder_status_t getLedState() override {
        LOG(INFO) << "getLedState called";
        // In a real scenario, read from /dev/myled or sysfs
        // For simplicity, always return true for now
        return STATUS_OK;
    }
};

} } } // namespace com::example::mydevice

And a main.cpp to register the service:

// hardware/interfaces/mydevice/service/main.cpp
#include "com/example/mydevice/MyDevice.h"
#include <android/binder_manager.h>
#include <android/binder_process.h>
#include <android-base/logging.h>

using com::example::mydevice::MyDevice;

int main() {
    ABinderProcess_setThreadPoolMaxThreadCount(0);
    std::shared_ptr<MyDevice> service = ndk::SharedRefBase::make<MyDevice>();
    const std::string instance = std::string() + MyDevice::descriptor + "/default";
    binder_status_t status = AServiceManager_addService(service->asBinder().get(), instance.c_str());
    CHECK_EQ(status, STATUS_OK) << "Failed to register IMyDevice service";

    LOG(INFO) << "MyDevice HAL service ready.";
    ABinderProcess_joinThreadPool();
    return 0;
}

4. Integrate into Android Things Build System

To include your new HAL in your Android Things OS build, you need to modify your device’s product configuration. Edit your device’s device/<vendor>/<board>/<board>.mk file (or a similar product definition file) and add your HAL service to PRODUCT_PACKAGES:

# device/<vendor>/<board>/<board>.mk

PRODUCT_PACKAGES += 
    android.hardware.mydevice-service 
    # ... other packages

You also need to ensure the AIDL interface is part of the system image. This should be handled automatically by the aidl_interface definition, but sometimes explicit inclusion is necessary if you’re building a minimal system. The AIDL stubs (Java and C++) are automatically generated and linked by the build system.

5. Building and Flashing the Custom OS

Navigate to your AOSP root directory and build your Android Things image:

source build/envsetup.sh
lunch aosp_<board>-userdebug
m build

Once the build completes, flash the image to your custom board:

adb reboot bootloader
fastboot flashall -w

6. Create an Android Framework Service (Java – Optional but Recommended)

For applications to easily interact with your HAL, create a Java wrapper service. This service can live in the Android framework (e.g., frameworks/base/services/core/java/com/android/server/mydevice/MyDeviceService.java) and provide a system service like Context.getSystemService(MY_DEVICE_SERVICE).

// frameworks/base/services/core/java/com/android/server/mydevice/MyDeviceService.java
package com.android.server.mydevice;

import android.content.Context;
import android.os.ServiceManager;
import android.os.RemoteException;
import android.util.Slog;

import com.example.mydevice.IMyDevice;

public class MyDeviceService extends IMyDevice.Stub {
    private static final String TAG = "MyDeviceService";
    private IMyDevice mHalService;

    public MyDeviceService(Context context) {
        // Get the HAL service instance
        mHalService = IMyDevice.Stub.asInterface(ServiceManager.getService("com.example.mydevice.IMyDevice/default"));
        if (mHalService == null) {
            Slog.e(TAG, "Failed to get IMyDevice HAL service");
        }
    }

    @Override
    public void setLedState(boolean on) throws RemoteException {
        if (mHalService != null) {
            mHalService.setLedState(on);
        } else {
            Slog.e(TAG, "HAL service not available");
        }
    }

    @Override
    public boolean getLedState() throws RemoteException {
        if (mHalService != null) {
            return mHalService.getLedState();
        }
        Slog.e(TAG, "HAL service not available");
        return false;
    }
    // Implement other methods from IMyDevice.aidl
}

You’ll need to register this service in frameworks/base/services/java/com/android/server/SystemServer.java.

7. Application Integration

Finally, your Android Things application can now interact with your custom peripheral through the new framework service (or directly via AIDL if you bypass the framework service layer, though less common).

// Example Android App Code
import com.example.mydevice.IMyDevice;
import android.os.ServiceManager;
import android.os.RemoteException;

// ... in an Activity or Service

private IMyDevice myDeviceService;

private void initMyDevice() {
    myDeviceService = IMyDevice.Stub.asInterface(ServiceManager.getService("com.example.mydevice.IMyDevice/default"));
    if (myDeviceService != null) {
        try {
            myDeviceService.setLedState(true); // Turn LED ON
            boolean isLedOn = myDeviceService.getLedState();
            Log.d("MY_APP", "LED State: " + isLedOn);
        } catch (RemoteException e) {
            Log.e("MY_APP", "Error interacting with HAL", e);
        }
    } else {
        Log.e("MY_APP", "MyDevice HAL service not found.");
    }
}

Testing and Debugging Your Custom HAL

Debugging HALs can be challenging. Key tools include:

• logcat: Essential for viewing logs from your C++ HAL service (using LOG(INFO), LOG(ERROR)) and Java framework components.
• strace: Can be used on the device to trace system calls made by your HAL service, helping to verify interactions with kernel drivers (e.g., strace -p <pid_of_hal_service>).
• /dev/kmsg: For kernel driver logs.
• AOSP Debugging Features: Utilize debug builds (userdebug or eng) of your Android Things port for better debugging capabilities.
• Unit Tests: Write unit tests for your C++ HAL implementation and Java wrapper classes.

Conclusion

Crafting custom HALs is a cornerstone of advanced Android Things OS porting, enabling specialized IoT devices to leverage the full power of the Android ecosystem. While it involves navigating kernel drivers, AIDL interfaces, C++ implementations, and Android’s build system, the ability to seamlessly integrate unique hardware significantly expands the possibilities for industrial, automotive, and consumer IoT applications. By following these principles, you can confidently extend Android Things to support virtually any peripheral, unlocking new frontiers for your embedded projects.