Android IIO sensors HAL

http://github.com/01org/android-iio-sensors-hal

Daniel BALUTA <daniel.baluta@intel.com>

Android sensor stack

https://source.android.com/devices/sensors/sensor-stack.html

IIO architecture overview

IIO interface overview

sysfs path

buffer handling

/dev/iio:device0
/sys/bus/iio/devices/iio:device0/scan_elements

trigger setup

/sys/bus/iio/devices/iio:device0

/sys/bus/iio/triggers/trigger0

events handling

/sys/bus/iio/devices/iio:device0/events/
/dev/iio:device0
ioctl IIO_GET_EVENT_FD_IOCTL

Standard HAL structure

interface defined in hardware/libhardware/include/hardware/hardware.h

built into modules (.so) files
dynamically loaded by Android
module (hw_module_t)
module version, author and name
hw_module_methods_t

open(), initiates communication with hardware

device (hw_device_t)

abstracts the actual hardware

close()
module struct must be named HAL_MODULE_INFO_SYM

Sensors HAL interface

declared in hardware/libhardware/include/hardware/sensors.h
interface must be thread safe
main data types

sensors_module_t
sensors_poll_device_t
sensor_t
sensor_event_t

main functions

get_sensors_list()
activate()
setDelay()
poll()
batch()

Intel Android sensors HAL

https://01.org/android-iio-sensors-hal

small, simple, quick sensor enabling on new hardware

dynamically discovers available sensors by parsing /sysfs files

can be used as a standalone library on Linux

8K lines of code

uses Industrial I/O interface for sensors

open source
used on IRDA for Baytrail and Sofia

simple sens tool for loading and interacting with HAL

supported sensors

accel, gyro, magnetometer

ambient light, proximity, temperature
step detector, step counter

Intel Android sensors HAL overview

IIO sensors HAL - entry point

/* entry.c: This is the IIO Sensors HAL module entry point file */
static struct hw_module_methods_t module_methods = {
.open = initialize_module
};
/* Externally visible module descriptor */
struct sensors_module_t __attribute__ ((visibility ("default")))
HAL_MODULE_INFO_SYM = {
.common = {
.tag = HARDWARE_MODULE_TAG,
.version_major = 1,
.version_minor = 3,
.id = SENSORS_HARDWARE_MODULE_ID,
.name = "IIO sensors HAL",
.author = "Intel",
.methods = &module_methods,
},
.get_sensors_list = get_sensors_list
};

IIO sensors HAL - initialize_module()

struct sensor_poll_device
hw_device_t
activate()

setDelay()

poll()

batch()

allocate_control_data()

create poll_fd, flush_event_fd and resets device and events fd

enumerate_sensors()

discover supported sensors and save them into an array of sensor_t items
we can have up to MAX_SENSORS (at this moment 12)

10

Discover available sensors

match against a catalog of supported sensors

assumptions

/dev/iio:deviceX, X = 0..MAX_DEVICES

multiple sensors can rely on a single IIO device

cannot have multiple sensors of the same type on the same IIO device
discovery done by iterating over /sys/bus/iio/devices

setup trigger names

default: <device_name>-dev<X> (e.g: kxcjk1013-dev0)

discover how does the data looks like in the buffer

/sys/bus/iio/devices/iio:device0/scan_elements

11

sensor_info_t

device name

trigger name

drdy trigger
any motion trigger
hrtimer trigger

device index
array with channel_info

internal (accel_3d)
friendly (accelerometer)

offset, scale
path (raw, input)

mode

poll
trigger buffer
event

12

IIO sensors HAL data flow

13

IIO sensors HAL - activate()

int activate(sensors_poll_device_t, handle, enabled)

trigger mode

enable buffer
setup trigger
add fd associated with /dev/iio:deviceX to poll_fd

poll mode

enable sensor
start acquisition thread

event mode

enable event
get fd associated with event and add it to poll_fd
reverse operations for deactivate (enabled = false)

14

IIO sensors HAL - setDelay()

int setDelay (struct sensors_poll_device_t* dev, int handle, int64_t ns)

use first higher or equal available rate

per device sampling rate

/sys/bus/iio/devices/iio:device0/in_accel_sampling_frequency

in buffer mode

/sys/bus/iio/devices/iio:device0/sampling_frequency

per sensor sampling rate

/sys/bus/iio/devices/iio:device0/available_sampling_frequency

disable buffer, set frequency, enable buffer

when using hrtimer triggers

sync hrtimer trigger frequency with requested frequency

15

IIO sensors HAL - batch()

int batch(struct sensors_poll_device_1* dev, int sensor_handle,
int flags, int64_t sampling_period_ns,
int64_t max_report_latency_ns);

set a sensors parameters

flags not used
max_report_latency_ns not used

no support for batch mode

calls in set_delay()

16

IIO sensors HAL - poll()

int poll struct sensors_poll_device_t* dev, sensors_event_t* data, int count)

reads an array of maximum count samples and stores them in data

waits for data on poll_fd and reads data when available
data can be read from

anonymous fd, for event data

acquisition thread (reads sysfs attributes)

synthetize duplicate samples

/dev/iio:device0, for buffered data

duplicates last data got from driver

handles flush requests

17

sensors_event_t
data passed from HAL layer to Android framework
struct sensors_event_t {
/* sensor type */
int32_t type;
/* time is in nanosecond */
int64_t timestamp;
union {
union {
float
data[16];
/* acceleration values are in (m/s^2) */
sensors_vec_t
acceleration;
/* other sensors */
union {
uint64_t
data[8];
/* step-counter */
uint64_t
step_counter;
}
}
};

18

Use IIO sensors HAL in Linux

sens tool
sens start <hal name>

sens ls

loads HAL with specified name

sends list command to HAL

sens <activate|deactivate> sensor_id

sens set_delay sensor_id delay
sens poll

gets data from HAL and displays them on standard output

19

Q&A

Sensor reporting modes

continuous

on change

events generated at constant rate defined by sampling_period_ns

e.g accelerometer
events generated only if measured values have changed
e.g ambient temperature

one shot

event deactivates itself and sends single event through HAL

e.g significant motion

21

IIO sensors HAL misc features

filtering

calibration
quirks

no-trigger, no-event, no-poll

unit conversions

remove noise (median, moving average)

Gauss (IIO) -> Tesla (Android)

android properties

min_freq, max_freq
ro.iio.accel.kxcjk1013.min_freq = 50

22