Introduction: The World of Android Sensor HALs

In the realm of custom Android Automotive or embedded devices, direct access to physical hardware isn’t always feasible during the early stages of development, or for devices that lack specific sensors. This is where Hardware Abstraction Layers (HALs) become indispensable. A HAL provides a standardized interface that Android’s framework can interact with, abstracting away the underlying hardware specifics. For sensors, the Sensor HAL allows Android’s SensorService to communicate with various physical sensors like accelerometers, gyroscopes, and magnetometers. This article will guide you through the process of creating a virtual accelerometer HAL, enabling you to simulate sensor data for your custom Android Automotive projects without actual hardware.

Emulating sensor behavior is critical for testing applications, developing features that rely on sensor input (e.g., navigation, gesture recognition), and ensuring system stability before hardware integration. By the end of this tutorial, you’ll have a working virtual accelerometer that provides synthetic data to the Android framework.

Understanding the Android Sensor HAL Architecture

The Android Sensor HAL sits between the Android framework’s SensorService and the device’s kernel drivers. Its primary role is to bridge the gap, providing a consistent API for the framework regardless of the hardware vendor or specific sensor implementation.

• SensorService: The central component in the Android framework responsible for managing all sensors. It interacts with the Sensor HAL.
• Sensor HAL: Implements the [email protected] HIDL interface. It’s typically a shared library loaded by the SensorService.
• Sensor Drivers: Kernel-level drivers that directly communicate with the physical sensor hardware. For our virtual HAL, this layer is simulated.

The HIDL (HAL Interface Definition Language) defines the interfaces that HALs must implement. For sensors, this is primarily ISensors.hal, which specifies methods for sensor discovery, activation, data polling, and event injection.

Setting Up Your Android Build Environment

To follow along, you’ll need a complete Android Open Source Project (AOSP) build environment set up. This typically involves downloading the AOSP source code and configuring it for a target device (like an Android Automotive reference board or a generic emulator target). We’ll assume you have a working AOSP build environment and can build Android images.

Deep Dive into Sensor HAL HIDL (ISensors.hal)

The core interface for sensor HALs is defined in hardware/interfaces/sensors/2.0/ISensors.hal (or later versions). Key methods we’ll be interacting with include:

• getSensorsList(): Returns a list of all sensors supported by the HAL.
• activate(sensorHandle, enabled): Enables or disables a specific sensor.
• batch(sensorHandle, samplingPeriodNs, maxReportLatencyNs): Configures sensor parameters like sampling rate and batching.
• poll(): The primary method for the framework to request sensor events.
• injectSensorData(): Allows injecting sensor data directly into the framework (useful for testing or virtual sensors).

Our virtual accelerometer will implement these methods to simulate a basic sensor.

Crafting Our Virtual Accelerometer HAL

We’ll create a new HAL module that implements the ISensors interface. For this example, we’ll place it under a common vendor path, e.g., hardware/google/pixel/sensors/2.0/virtual_accelerometer. You might choose a path specific to your vendor.

1. Project Structure and Android.bp

Create the directory structure and a Android.bp file to define the build rules for our HAL module. This file tells the Android build system how to compile our C++ source code into a shared library.

mkdir -p hardware/google/pixel/sensors/2.0/virtual_accelerometer/default

// hardware/google/pixel/sensors/2.0/virtual_accelerometer/Android.bp
hal_library {
    name: "[email protected]_accelerometer",
    vendor: true,
    relative_install_path: "hw",
    srcs: [
        "default/VirtualAccelerometer.cpp",
    ],
    header_libs: [
        "[email protected]",
    ],
    shared_libs: [
        "libhardware",
        "libhidlbase",
        "libhidltransport",
        "liblog",
        "libutils",
    ],
    export_include_dirs: [
        "default",
    ],
}

2. Implementing VirtualAccelerometer.h

This header file defines our VirtualAccelerometer class, which inherits from ISensors.

// hardware/google/pixel/sensors/2.0/virtual_accelerometer/default/VirtualAccelerometer.h
#pragma once

#include <android/hardware/sensors/2.0/ISensors.h>
#include <hidl/MQDescriptor.h>
#include <hidl/Status.h>
#include <thread>
#include <atomic>
#include <mutex>
#include <condition_variable>

namespace android::hardware::sensors::V2_0::implementation {

using ::android::hardware::Return;
using ::android::hardware::Void;
using ::android::hardware::sensors::V2_0::ISensors;
using ::android::hardware::sensors::V2_0::Event;
using ::android::hardware::sensors::V2_0::SensorInfo;
using ::android::hardware::sensors::V2_0::Result;

struct VirtualAccelerometer : public ISensors {
    VirtualAccelerometer();
    ~VirtualAccelerometer() override;

    Return<void> getSensorsList(getSensorsList_cb _hidl_cb) override;
    Return<Result> activate(int32_t sensorHandle, bool enabled) override;
    Return<Result> batch(int32_t sensorHandle, int64_t samplingPeriodNs, int64_t maxReportLatencyNs) override;
    Return<Result> flush(int32_t sensorHandle) override;
    Return<void> poll(int32_t timeoutMillis, poll_cb _hidl_cb) override;
    Return<Result> setOperationMode(OperationMode mode) override;
    Return<Result> injectSensorData(const Event& event) override;
    Return<void> registerDirectChannel(const DirectChannelInfo& channel, registerDirectChannel_cb _hidl_cb) override;
    Return<Result> unregisterDirectChannel(int32_t channelHandle) override;

private:
    std::vector<SensorInfo> mSensors;
    std::atomic<bool> mActive;
    std::thread mSensorThread;
    std::mutex mMutex;
    std::condition_variable mCv;
    int64_t mSamplingPeriodNs;

    void sensorLoop();
};

extern "C" ISensors* HIDL_FETCH_ISensors(const char* name);

} // namespace android::hardware::sensors::V2_0::implementation

3. Implementing VirtualAccelerometer.cpp

This file contains the core logic for our virtual sensor, including initialization, sensor data generation, and HIDL method implementations.

// hardware/google/pixel/sensors/2.0/virtual_accelerometer/default/VirtualAccelerometer.cpp
#include "VirtualAccelerometer.h"
#include <log/log.h>
#include <cinttypes>
#include <chrono>
#include <cmath>
#include <random>

namespace android::hardware::sensors::V2_0::implementation {

namespace {

constexpr int32_t kVirtualAccelerometerHandle = 1;
constexpr int32_t kVirtualAccelerometerType = SensorType::ACCELEROMETER;

} // anonymous namespace

VirtualAccelerometer::VirtualAccelerometer()
    : mActive(false), mSamplingPeriodNs(0) {

    SensorInfo accelerometerInfo;
    accelerometerInfo.sensorHandle = kVirtualAccelerometerHandle;
    accelerometerInfo.name = "Virtual Accelerometer";
    accelerometerInfo.vendor = "Virtual Corp";
    accelerometerInfo.version = 1;
    accelerometerInfo.type = kVirtualAccelerometerType;
    accelerometerInfo.maxRange = 20.0f;
    accelerometerInfo.resolution = 0.001f;
    accelerometerInfo.power = 0.5f; // mA
    accelerometerInfo.minDelay = 10000; // ns (100 Hz)
    accelerometerInfo.fifoReservedEventCount = 0;
    accelerometerInfo.fifoMaxEventCount = 0;
    accelerometerInfo.maxDelay = 1000000000; // ns (1 Hz)
    accelerometerInfo.flags = SensorFlagBits::DATA_INJECTION_SUPPORTED;
    mSensors.push_back(accelerometerInfo);

    ALOGI("Virtual Accelerometer HAL initialized.");
}

VirtualAccelerometer::~VirtualAccelerometer() {
    if (mActive) {
        activate(kVirtualAccelerometerHandle, false);
    }
    if (mSensorThread.joinable()) {
        mSensorThread.join();
    }
    ALOGI("Virtual Accelerometer HAL destroyed.");
}

Return<void> VirtualAccelerometer::getSensorsList(getSensorsList_cb _hidl_cb) {
    _hidl_cb(mSensors);
    return Void();
}

Return<Result> VirtualAccelerometer::activate(int32_t sensorHandle, bool enabled) {
    if (sensorHandle != kVirtualAccelerometerHandle) {
        return Result::BAD_VALUE;
    }

    if (mActive == enabled) {
        return Result::OK;
    }

    mActive = enabled;
    if (enabled) {
        ALOGI("Virtual Accelerometer activated.");
        // Start a new thread for sensor data generation
        mSensorThread = std::thread(&VirtualAccelerometer::sensorLoop, this);
    } else {
        ALOGI("Virtual Accelerometer deactivated.");
        mCv.notify_all(); // Wake up the sensor thread to terminate
        if (mSensorThread.joinable()) {
            mSensorThread.join();
        }
    }
    return Result::OK;
}

Return<Result> VirtualAccelerometer::batch(int32_t sensorHandle, int64_t samplingPeriodNs, int64_t maxReportLatencyNs) {
    if (sensorHandle != kVirtualAccelerometerHandle) {
        return Result::BAD_VALUE;
    }
    mSamplingPeriodNs = samplingPeriodNs;
    ALOGI("Virtual Accelerometer batch configured: samplingPeriodNs=%" PRId64 ", maxReportLatencyNs=%" PRId64,
          samplingPeriodNs, maxReportLatencyNs);
    return Result::OK;
}

Return<Result> VirtualAccelerometer::flush(int32_t sensorHandle) {
    if (sensorHandle != kVirtualAccelerometerHandle) {
        return Result::BAD_VALUE;
    }
    // For a virtual sensor, flushing might just mean sending the last known value immediately.
    // Or, for simplicity, we can just return OK.
    return Result::OK;
}

Return<void> VirtualAccelerometer::poll(int32_t timeoutMillis, poll_cb _hidl_cb) {
    // In current Android Sensor HAL versions (2.0+), poll() is typically not used for continuous events.
    // Instead, events are pushed asynchronously to the framework via a HIDL event queue.
    // For simplicity in this virtual HAL, we'll demonstrate a basic poll() implementation.
    // A real asynchronous HAL would register an event queue and push events via it.
    // For now, this will return an empty list as we're not using poll() for event generation.
    std::vector<Event> events;
    _hidl_cb(events, Result::OK);
    return Void();
}

Return<Result> VirtualAccelerometer::setOperationMode(OperationMode mode) {
    // Not fully implemented for this basic example.
    // Can be used to switch between normal and data injection modes.
    return Result::OK;
}

Return<Result> VirtualAccelerometer::injectSensorData(const Event& event) {
    // This method is for injecting data into the framework, typically for testing.
    // Our virtual sensor generates its own data, so this is not used for internal data generation.
    return Result::OK;
}

Return<void> VirtualAccelerometer::registerDirectChannel(const DirectChannelInfo& channel, registerDirectChannel_cb _hidl_cb) {
    _hidl_cb(Result::BAD_VALUE, -1); // Direct channels not supported in this example
    return Void();
}

Return<Result> VirtualAccelerometer::unregisterDirectChannel(int32_t channelHandle) {
    return Result::BAD_VALUE; // Direct channels not supported
}

void VirtualAccelerometer::sensorLoop() {
    ALOGI("Virtual Accelerometer sensor loop started.");
    std::random_device rd;
    std::mt19937 gen(rd());
    std::uniform_real_distribution<float> dist(-0.1f, 0.1f);

    int64_t timestampOffset = std::chrono::nanoseconds(std::chrono::high_resolution_clock::now().time_since_epoch()).count();
    float t = 0.0f;

    while (mActive) {
        if (mSamplingPeriodNs == 0) {
            std::unique_lock<std::mutex> lock(mMutex);
            mCv.wait(lock); // Wait until activated or sampling period set
            continue;
        }

        std::this_thread::sleep_for(std::chrono::nanoseconds(mSamplingPeriodNs));
        if (!mActive) break; // Check again after sleep

        Event event;
        event.sensorHandle = kVirtualAccelerometerHandle;
        event.sensorType = kVirtualAccelerometerType;
        event.timestamp = std::chrono::nanoseconds(std::chrono::high_resolution_clock::now().time_since_epoch()).count() - timestampOffset;

        // Simulate a simple accelerometer movement: gravity + slight sinusoidal motion + noise
        float ax = sin(t * 2.5f) * 0.8f + dist(gen);
        float ay = cos(t * 1.8f) * 0.7f + dist(gen);
        float az = 9.81f + sin(t * 1.2f) * 0.2f + dist(gen); // Z-axis dominated by gravity

        event.u.vec3.x = ax;
        event.u.vec3.y = ay;
        event.u.vec3.z = az;
        event.u.vec3.status = SensorStatus::ACCURACY_HIGH;

        // In a real HAL, you would push this event to an event queue.
        // For this example, we log it to demonstrate generation.
        ALOGV("Virtual Accel: x=%.2f, y=%.2f, z=%.2f at timestamp %" PRId64, ax, ay, az, event.timestamp);

        t += static_cast<float>(mSamplingPeriodNs) / 1000000000.0f;
    }
    ALOGI("Virtual Accelerometer sensor loop stopped.");
}

ISensors* HIDL_FETCH_ISensors(const char* name) {
    if (std::string("default") == name) {
        return new VirtualAccelerometer();
    }
    return nullptr;
}

} // namespace android::hardware::sensors::V2_0::implementation

In the sensorLoop() function, we simulate accelerometer data using sine waves to create continuous, varying motion along the X, Y, and Z axes, with the Z-axis having a baseline of 9.81 m/s² to represent gravity. A small amount of random noise is added for realism. The sleep_for ensures data is generated at the configured sampling rate.

4. Integrating with AOSP Build

To ensure your new HAL is included in the Android build and the system framework can find it, you need to declare it in your device’s manifest.xml and ensure it’s built into the system image.

a. Add to manifest.xml

Locate your device’s device/<vendor>/<device>/manifest.xml file (or create one if it doesn’t exist) and add the following entry:

<manifest version="2.0" type="device">
    <hal format="hidl">
        <name>android.hardware.sensors</name>
        <transport>hwbinder</transport>
        <version>2.0</version>
        <interface>
            <name>ISensors</name>
            <instance>default</instance>
        </interface>
        <fqname>@2.0::ISensors/default</fqname>
    </hal>
    <!-- Other HALs -->
</manifest>

b. Include in Device Build

In your device’s device/<vendor>/<device>/device.mk, add your HAL as a product package:

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

# ... other product packages
PRODUCT_PACKAGES += 
    [email protected]_accelerometer

Now, rebuild your AOSP image:

source build/envsetup.sh
lunch <your_device_target>-userdebug
m clean && m -j$(nproc)

Testing and Validation

Once your Android system is up and running with the new HAL, you can verify its presence and functionality.

1. Using dumpsys sensorservice

Connect to your device via ADB and inspect the SensorService:

adb shell dumpsys sensorservice

You should see “Virtual Accelerometer” listed among the available sensors, along with its properties.

2. Developing a Simple Android App

Create a basic Android application that uses the SensorManager to access the accelerometer. Listen for sensor events and display the X, Y, Z values. You should observe the simulated data streams from your virtual HAL.

// Android App Snippet
SensorManager sensorManager = (SensorManager) getSystemService(Context.SENSOR_SERVICE);
Sensor accelerometer = sensorManager.getDefaultSensor(Sensor.TYPE_ACCELEROMETER);

if (accelerometer != null) {
    sensorManager.registerListener(new SensorEventListener() {
        @Override
        public void onSensorChanged(SensorEvent event) {
            if (event.sensor.getType() == Sensor.TYPE_ACCELEROMETER) {
                float x = event.values[0];
                float y = event.values[1];
                float z = event.values[2];
                Log.d("VirtualAccel", "X: " + x + ", Y: " + y + ", Z: " + z);
                // Update UI or process data
            }
        }

        @Override
        public void onAccuracyChanged(Sensor sensor, int accuracy) {
            // Do nothing
        }
    }, accelerometer, SensorManager.SENSOR_DELAY_NORMAL);
} else {
    Log.e("VirtualAccel", "Accelerometer not found!");
}

Conclusion

You’ve successfully crafted a virtual accelerometer HAL for your custom Android Automotive project! This process provides a powerful mechanism for simulating hardware, accelerating development, and thoroughly testing sensor-dependent applications without the immediate need for physical hardware. While this example focuses on a basic accelerometer, the principles can be extended to implement more complex virtual sensors or even interact with actual hardware devices. This foundational knowledge empowers you to build robust and testable Android systems for specialized embedded applications.