Introduction

The Android Sensor Hardware Abstraction Layer (HAL) is a critical component that bridges the Android framework with a device’s physical sensors. For developers working with virtualized Android environments like emulators, Anbox, or Waydroid, accurately simulating sensor behavior is paramount for testing and development. This guide provides a detailed, expert-level walkthrough on building and integrating a custom Android Sensor HAL for virtual devices, enabling precise control over sensor data and behavior.

Understanding the Android Sensor HAL Architecture

The Sensor HAL defines the interface that the Android framework uses to communicate with hardware sensors. It’s a collection of C/C++ modules implemented by device manufacturers. Key structures and functions defined in hardware/libhardware/include/hardware/sensors.h and hardware/libhardware/include/hardware/hardware.h dictate this interface.

Key HAL Structures:

• hw_module_t: Represents the HAL module, providing methods to open a device.
• hw_device_t: Represents a specific hardware device (in this case, the sensor device), defining operations like activating sensors, setting delays, and polling for events.
• sensors_poll_device_t: Extends hw_device_t with sensor-specific functions for polling events, getting sensor lists, and batching.
• sensor_t: Describes an individual sensor, including its name, type, vendor, resolution, and power consumption.

When the Android framework needs sensor data, it loads the appropriate HAL module (typically sensors.<device>.so) and uses its interface to interact with the underlying sensor drivers or, in our case, an emulation layer.

Setting Up Your Android Build Environment

To build a custom Sensor HAL, you’ll need an Android Open Source Project (AOSP) build environment. This involves syncing the AOSP source code and setting up your build tools. For this tutorial, we assume you have a working AOSP tree (e.g., Android 11 or 12) and are familiar with basic AOSP compilation.

Prerequisites:

• Linux distribution (Ubuntu is common)
• ~250GB free disk space
• ~16GB RAM
• AOSP source code synced (repo init -u https://android.googlesource.com/platform/manifest -b android-12.0.0_rXX --depth=1; repo sync -j8)
• Build dependencies installed (refer to AOSP documentation)

Implementing Your Custom Sensor HAL Module

We’ll create a new HAL module that mimics a set of common sensors. This module will reside in hardware/qcom/display/hal/sensors/ (or a similar custom path like hardware/google/pixel/hal/sensors, adjust as needed).

1. Define the Module and Device Structures

First, create a new directory for your HAL (e.g., aosp/hardware/custom/sensors/). Inside, create custom_sensors.cpp and custom_sensors.h.

// custom_sensors.h
#include <hardware/sensors.h>
#include <hardware/hardware.h>

struct custom_sensor_context_t {
    struct sensors_poll_device_t device;
    // Add any custom state here
    int current_delay_ms;
    std::vector<sensor_event_t> event_queue;
    std::mutex queue_mutex;
};

static int open_sensors(const struct hw_module_t* module, const char* name, struct hw_device_t** device);
static int custom_sensors_get_sensors_list(struct sensors_poll_device_t *dev, struct sensor_t const **list);
static int custom_sensors_set_delay(struct sensors_poll_device_t *dev, int handle, int64_t ns);
static int custom_sensors_activate(struct sensors_poll_device_t *dev, int handle, int enabled);
static int custom_sensors_poll(struct sensors_poll_device_t *dev, sensors_event_t* data, int count);
static int custom_sensors_close(struct hw_device_t *dev);

2. Implement the Module Open Function

This function initializes your custom sensor device.

// custom_sensors.cpp
#include "custom_sensors.h"
#include <log/log.h> // For ALOGx
#include <vector>
#include <mutex>

// ... (sensor_t definitions for ACCELEROMETER, GYROSCOPE, etc.) ...

static int custom_sensors_close(struct hw_device_t *dev) {
    custom_sensor_context_t* ctx = (custom_sensor_context_t*)dev;
    if (ctx) {
        // Clean up resources if necessary
        delete ctx;
    }
    return 0;
}

static int open_sensors(const struct hw_module_t* module, const char* name, struct hw_device_t** device) {
    custom_sensor_context_t *ctx = new custom_sensor_context_t();
    if (!ctx) {
        ALOGE("Failed to allocate custom_sensor_context_t");
        return -ENOMEM;
    }

    memset(ctx, 0, sizeof(custom_sensor_context_t));
    ctx->device.common.tag = HARDWARE_DEVICE_TAG;
    ctx->device.common.version = SENSORS_DEVICE_API_VERSION_1_4; // Or appropriate version
    ctx->device.common.module = const_cast<hw_module_t*>(module);
    ctx->device.common.close = custom_sensors_close;
    ctx->device.get_sensors_list = custom_sensors_get_sensors_list;
    ctx->device.set_delay = custom_sensors_set_delay;
    ctx->device.activate = custom_sensors_activate;
    ctx->device.poll = custom_sensors_poll;
    // ... initialize other functions if needed for batching, flush, etc.

    *device = &ctx->device.common;
    ALOGI("Opened custom sensor device");
    return 0;
}

static hw_module_methods_t custom_sensor_module_methods = {
    .open = open_sensors
};

extern "C" const hw_module_t HAL_MODULE_INFO_SYM = {
    .tag = HARDWARE_MODULE_TAG,
    .version_major = 1,
    .version_minor = 0,
    .id = SENSORS_HARDWARE_MODULE_ID,
    .name = "Custom Virtual Sensors",
    .author = "Your Name",
    .methods = &custom_sensor_module_methods,
    .dso = NULL,
    .reserved = {0},
};

3. Implement `get_sensors_list`

This function provides the Android framework with a list of all sensors your HAL supports.

static const struct sensor_t sSensorList[] = {
    {
        .name = "Custom Virtual Accelerometer",
        .vendor = "YourCompany",
        .version = 1,
        .handle = 0,
        .type = SENSOR_TYPE_ACCELEROMETER,
        .maxRange = 10.0f,
        .resolution = 0.01f,
        .power = 0.5f,
        .minDelay = 10000, // microseconds
        .fifoReservedEventCount = 0,
        .fifoMaxEventCount = 0,
        .stringType = NULL,
        .requiredPermission = NULL,
        .maxDelay = 0,
        .flags = SENSOR_FLAG_CONTINUOUS_MODE,
        .reserved = {0}
    },
    {
        .name = "Custom Virtual Gyroscope",
        .vendor = "YourCompany",
        .version = 1,
        .handle = 1,
        .type = SENSOR_TYPE_GYROSCOPE,
        .maxRange = 2000.0f,
        .resolution = 0.01f,
        .power = 0.5f,
        .minDelay = 10000,
        .fifoReservedEventCount = 0,
        .fifoMaxEventCount = 0,
        .stringType = NULL,
        .requiredPermission = NULL,
        .maxDelay = 0,
        .flags = SENSOR_FLAG_CONTINUOUS_MODE,
        .reserved = {0}
    }
    // Add more sensors as needed (light, proximity, etc.)
};

static int custom_sensors_get_sensors_list(struct sensors_poll_device_t *dev, struct sensor_t const **list) {
    *list = sSensorList;
    return ARRAY_SIZE(sSensorList);
}

4. Implement `activate`, `set_delay`, and `poll`

These functions control sensor state and deliver events. For emulation, `poll` is where you’ll inject your simulated data.

static int custom_sensors_activate(struct sensors_poll_device_t *dev, int handle, int enabled) {
    ALOGI("Sensor activate handle=%d, enabled=%d", handle, enabled);
    // In a real HAL, this would enable/disable the physical sensor.
    // For emulation, you might toggle a flag to start/stop data generation.
    return 0;
}

static int custom_sensors_set_delay(struct sensors_poll_device_t *dev, int handle, int64_t ns) {
    custom_sensor_context_t* ctx = (custom_sensor_context_t*)dev;
    ctx->current_delay_ms = ns / 1000000; // Store delay in milliseconds
    ALOGI("Sensor set_delay handle=%d, ns=%lld (ms=%d)", handle, ns, ctx->current_delay_ms);
    return 0;
}

static int custom_sensors_poll(struct sensors_poll_device_t *dev, sensors_event_t* data, int count) {
    custom_sensor_context_t* ctx = (custom_sensor_context_t*)dev;
    std::unique_lock<std::mutex> lock(ctx->queue_mutex);

    // This is where you would push simulated data.
    // For a basic emulation, you could generate data periodically or
    // read from a FIFO/shared memory populated by an external emulator process.
    
    // Example: Pushing a single accelerometer event
    if (ctx->event_queue.empty()) {
        // Generate a dummy event if the queue is empty for demonstration
        sensors_event_t accel_event;
        memset(&accel_event, 0, sizeof(accel_event));
        accel_event.version = sizeof(sensors_event_t);
        accel_event.sensor = 0; // handle for accelerometer
        accel_event.type = SENSOR_TYPE_ACCELEROMETER;
        accel_event.timestamp = get_wall_clock_ns(); // Current time
        accel_event.acceleration.x = 0.1f + ((float)rand()/RAND_MAX * 0.1f);
        accel_event.acceleration.y = 9.81f + ((float)rand()/RAND_MAX * 0.1f);
        accel_event.acceleration.z = 0.2f + ((float)rand()/RAND_MAX * 0.1f);
        ctx->event_queue.push_back(accel_event);
    }

    int num_events_to_copy = std::min(count, (int)ctx->event_queue.size());
    for (int i = 0; i < num_events_to_copy; ++i) {
        data[i] = ctx->event_queue[i];
    }
    ctx->event_queue.erase(ctx->event_queue.begin(), ctx->event_queue.begin() + num_events_to_copy);

    return num_events_to_copy;
}

Building Your HAL Module

You need to create an Android.bp (for Android.mk if using older AOSP) file in your custom HAL directory to build it as a shared library.

// hardware/custom/sensors/Android.bp
cc_library_shared {
    name: "sensors.custom",
    vendor_available: true,
    relative_install_path: "hw",
    srcs: [
        "custom_sensors.cpp",
    ],
    shared_libs: [
        "liblog",
        "libhardware",
    ],
    header_libs: [
        "libhardware_headers",
    ],
    cflags: [
        "-Wall",
        "-Werror",
    ],
}

After placing this, you can build your module using `m sensors.custom` from the AOSP root.

Integrating with the Android Emulator (or other virtual devices)

For the Android Emulator, the HAL is typically loaded based on the `ro.hardware` property or device-specific configurations. You need to ensure your custom HAL is discoverable. The HAL search path is usually `/vendor/lib64/hw`, `/system/lib64/hw`, etc. Your `sensors.custom.so` needs to be in one of these locations.

Emulator Integration Steps:

1. Add to Device Manifest: Modify your device’s `device.mk` or `BoardConfig.mk` to include your HAL. For example, in `device/google/emu/aosp_x86/device.mk`:

PRODUCT_PACKAGES += 
    sensors.custom

This ensures your `sensors.custom.so` is packaged into the vendor image.

<ol start=