include/hardware/sensors.h

/*
 * Copyright (C) 2012 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef ANDROID_SENSORS_INTERFACE_H
#define ANDROID_SENSORS_INTERFACE_H

#include <stdint.h>
#include <sys/cdefs.h>
#include <sys/types.h>

#include <hardware/hardware.h>
#include <cutils/native_handle.h>

__BEGIN_DECLS

/*****************************************************************************/

#define SENSORS_HEADER_VERSION          1
#define SENSORS_MODULE_API_VERSION_0_1  HARDWARE_MODULE_API_VERSION(0, 1)
#define SENSORS_DEVICE_API_VERSION_0_1  HARDWARE_DEVICE_API_VERSION_2(0, 1, SENSORS_HEADER_VERSION)
#define SENSORS_DEVICE_API_VERSION_1_0  HARDWARE_DEVICE_API_VERSION_2(1, 0, SENSORS_HEADER_VERSION)

/**
 * The id of this module
 */
#define SENSORS_HARDWARE_MODULE_ID "sensors"

/**
 * Name of the sensors device to open
 */
#define SENSORS_HARDWARE_POLL       "poll"

/**
 * Handles must be higher than SENSORS_HANDLE_BASE and must be unique.
 * A Handle identifies a given sensors. The handle is used to activate
 * and/or deactivate sensors.
 * In this version of the API there can only be 256 handles.
 */
#define SENSORS_HANDLE_BASE             0
#define SENSORS_HANDLE_BITS             8
#define SENSORS_HANDLE_COUNT            (1<<SENSORS_HANDLE_BITS)


/* attributes queriable with query() */
enum {
    /*
     * Availability: SENSORS_DEVICE_API_VERSION_1_0
     * return the maximum number of events that can be returned
     * in a single call to (*poll)(). This value is used by the
     * framework to adequately dimension the buffer passed to
     * (*poll)(), note that (*poll)() still needs to pay attention to
     * the count parameter passed to it, it cannot blindly expect that
     * this value will be used for all calls to (*poll)().
     *
     * Generally this value should be set to match the sum of the internal
     * FIFOs of all available sensors.
     */
    SENSORS_QUERY_MAX_EVENTS_BATCH_COUNT     = 0
};

/*
 * flags for (*batch)()
 * Availability: SENSORS_DEVICE_API_VERSION_1_0
 * see (*batch)() documentation for details
 */
enum {
    SENSORS_BATCH_DRY_RUN               = 0x00000001,
    SENSORS_BATCH_WAKE_UPON_FIFO_FULL   = 0x00000002
};

/**
 * Definition of the axis used by the sensor HAL API
 *
 * This API is relative to the screen of the device in its default orientation,
 * that is, if the device can be used in portrait or landscape, this API
 * is only relative to the NATURAL orientation of the screen. In other words,
 * the axis are not swapped when the device's screen orientation changes.
 * Higher level services /may/ perform this transformation.
 *
 *   x<0         x>0
 *                ^
 *                |
 *    +-----------+-->  y>0
 *    |           |
 *    |           |
 *    |           |
 *    |           |   / z<0
 *    |           |  /
 *    |           | /
 *    O-----------+/
 *    |[]  [ ]  []/
 *    +----------/+     y<0
 *              /
 *             /
 *           |/ z>0 (toward the sky)
 *
 *    O: Origin (x=0,y=0,z=0)
 *
 */

/*
 * Interaction with suspend mode
 *
 * Unless otherwise noted, an enabled sensor shall not prevent the
 * SoC to go into suspend mode. It is the responsibility of applications
 * to keep a partial wake-lock should they wish to receive sensor
 * events while the screen is off. While in suspend mode, and unless
 * otherwise noted, enabled sensors' events are lost.
 *
 * Note that conceptually, the sensor itself is not de-activated while in
 * suspend mode -- it's just that the data it returns are lost. As soon as
 * the SoC gets out of suspend mode, operations resume as usual. Of course,
 * in practice sensors shall be disabled while in suspend mode to
 * save power, unless batch mode is active, in which case they must
 * continue fill their internal FIFO (see the documentation of batch() to
 * learn how suspend interacts with batch mode).
 *
 * In batch mode and only when the flag SENSORS_BATCH_WAKE_UPON_FIFO_FULL is
 * set and supported, the specified sensor must be able to wake-up the SoC and
 * be able to buffer at least 10 seconds worth of the requested sensor events.
 *
 * There are notable exceptions to this behavior, which are sensor-dependent
 * (see sensor types definitions below)
 *
 *
 * The sensor type documentation below specifies the wake-up behavior of
 * each sensor:
 *   wake-up: yes     this sensor must wake-up the SoC to deliver events
 *   wake-up: no      this sensor shall not wake-up the SoC, events are dropped
 *
 */

/*
 * Sensor type
 *
 * Each sensor has a type which defines what this sensor measures and how
 * measures are reported. All types are defined below.
 */

/*
 * Sensor fusion and virtual sensors
 *
 * Many sensor types are or can be implemented as virtual sensors from
 * physical sensors on the device. For instance the rotation vector sensor,
 * orientation sensor, step-detector, step-counter, etc...
 *
 * From the point of view of this API these virtual sensors MUST appear as
 * real, individual sensors. It is the responsibility of the driver and HAL
 * to make sure this is the case.
 *
 * In particular, all sensors must be able to function concurrently.
 * For example, if defining both an accelerometer and a step counter,
 * then both must be able to work concurrently.
 */

/*
 * Trigger modes
 *
 * Sensors can report events in different ways called trigger modes,
 * each sensor type has one and only one trigger mode associated to it.
 * Currently there are four trigger modes defined:
 *
 * continuous: events are reported at a constant rate defined by setDelay().
 *             eg: accelerometers, gyroscopes.
 * on-change:  events are reported only if the sensor's value has changed.
 *             setDelay() is used to set a lower limit to the reporting
 *             period (minimum time between two events).
 *             The HAL must return an event immediately when an on-change
 *             sensor is activated.
 *             eg: proximity, light sensors
 * one-shot:   upon detection of an event, the sensor deactivates itself and
 *             then sends a single event. Order matters to avoid race
 *             conditions. No other event is sent until the sensor get
 *             reactivated. setDelay() is ignored.
 *             eg: significant motion sensor
 * special:    see details in the sensor type specification below
 *
 */

/*
 * SENSOR_TYPE_ACCELEROMETER
 * trigger-mode: continuous
 * wake-up sensor: no
 *
 *  All values are in SI units (m/s^2) and measure the acceleration of the
 *  device minus the force of gravity.
 *
 *  Acceleration sensors return sensor events for all 3 axes at a constant
 *  rate defined by setDelay().
 *
 *  x: Acceleration on the x-axis
 *  y: Acceleration on the y-axis
 *  z: Acceleration on the z-axis
 *
 * Note that the readings from the accelerometer include the acceleration
 * due to gravity (which is opposite to the direction of the gravity vector).
 *
 *  Examples:
 *    The norm of <x, y, z>  should be close to 0 when in free fall.
 *
 *    When the device lies flat on a table and is pushed on its left side
 *    toward the right, the x acceleration value is positive.
 *
 *    When the device lies flat on a table, the acceleration value is +9.81,
 *    which correspond to the acceleration of the device (0 m/s^2) minus the
 *    force of gravity (-9.81 m/s^2).
 *
 *    When the device lies flat on a table and is pushed toward the sky, the
 *    acceleration value is greater than +9.81, which correspond to the
 *    acceleration of the device (+A m/s^2) minus the force of
 *    gravity (-9.81 m/s^2).
 */
#define SENSOR_TYPE_ACCELEROMETER                    (1)

/*
 * SENSOR_TYPE_GEOMAGNETIC_FIELD
 * trigger-mode: continuous
 * wake-up sensor: no
 *
 *  All values are in micro-Tesla (uT) and measure the geomagnetic
 *  field in the X, Y and Z axis.
 *
 *  Returned values include calibration mechanisms such that the vector is
 *  aligned with the magnetic declination and heading of the earth's
 *  geomagnetic field.
 *
 *  Magnetic Field sensors return sensor events for all 3 axes at a constant
 *  rate defined by setDelay().
 */
#define SENSOR_TYPE_GEOMAGNETIC_FIELD                (2)
#define SENSOR_TYPE_MAGNETIC_FIELD  SENSOR_TYPE_GEOMAGNETIC_FIELD

/*
 * SENSOR_TYPE_ORIENTATION
 * trigger-mode: continuous
 * wake-up sensor: no
 * 
 * All values are angles in degrees.
 * 
 * Orientation sensors return sensor events for all 3 axes at a constant
 * rate defined by setDelay().
 *
 * azimuth: angle between the magnetic north direction and the Y axis, around 
 *  the Z axis (0<=azimuth<360).
 *      0=North, 90=East, 180=South, 270=West
 * 
 * pitch: Rotation around X axis (-180<=pitch<=180), with positive values when
 *  the z-axis moves toward the y-axis.
 *
 * roll: Rotation around Y axis (-90<=roll<=90), with positive values when
 *  the x-axis moves towards the z-axis.
 *
 * Note: For historical reasons the roll angle is positive in the clockwise
 *  direction (mathematically speaking, it should be positive in the
 *  counter-clockwise direction):
 *
 *                Z
 *                ^
 *  (+roll)  .--> |
 *          /     |
 *         |      |  roll: rotation around Y axis
 *     X <-------(.)
 *                 Y
 *       note that +Y == -roll
 *
 *
 *
 * Note: This definition is different from yaw, pitch and roll used in aviation
 *  where the X axis is along the long side of the plane (tail to nose).
 */
#define SENSOR_TYPE_ORIENTATION                      (3)

/*
 * SENSOR_TYPE_GYROSCOPE
 * trigger-mode: continuous
 * wake-up sensor: no
 *
 *  All values are in radians/second and measure the rate of rotation
 *  around the X, Y and Z axis.  The coordinate system is the same as is
 *  used for the acceleration sensor. Rotation is positive in the
 *  counter-clockwise direction (right-hand rule). That is, an observer
 *  looking from some positive location on the x, y or z axis at a device
 *  positioned on the origin would report positive rotation if the device
 *  appeared to be rotating counter clockwise. Note that this is the
 *  standard mathematical definition of positive rotation and does not agree
 *  with the definition of roll given earlier.
 *  The range should at least be 17.45 rad/s (ie: ~1000 deg/s).
 *
 *  automatic gyro-drift compensation is allowed but not required.
 */
#define SENSOR_TYPE_GYROSCOPE                        (4)

/*
 * SENSOR_TYPE_LIGHT
 * trigger-mode: on-change
 * wake-up sensor: no
 *
 * The light sensor value is returned in SI lux units.
 */
#define SENSOR_TYPE_LIGHT                            (5)

/*
 * SENSOR_TYPE_PRESSURE
 * trigger-mode: continuous
 * wake-up sensor: no
 *
 * The pressure sensor return the athmospheric pressure in hectopascal (hPa)
 */
#define SENSOR_TYPE_PRESSURE                         (6)

/* SENSOR_TYPE_TEMPERATURE is deprecated in the HAL */
#define SENSOR_TYPE_TEMPERATURE                      (7)

/*
 * SENSOR_TYPE_PROXIMITY
 * trigger-mode: on-change
 * wake-up sensor: yes
 *
 * The distance value is measured in centimeters.  Note that some proximity
 * sensors only support a binary "close" or "far" measurement.  In this case,
 * the sensor should report its maxRange value in the "far" state and a value
 * less than maxRange in the "near" state.
 */
#define SENSOR_TYPE_PROXIMITY                        (8)

/*
 * SENSOR_TYPE_GRAVITY
 * trigger-mode: continuous
 * wake-up sensor: no
 *
 * A gravity output indicates the direction of and magnitude of gravity in
 * the devices's coordinates.  On Earth, the magnitude is 9.8 m/s^2.
 * Units are m/s^2.  The coordinate system is the same as is used for the
 * acceleration sensor. When the device is at rest, the output of the
 * gravity sensor should be identical to that of the accelerometer.
 */
#define SENSOR_TYPE_GRAVITY                          (9)

/*
 * SENSOR_TYPE_LINEAR_ACCELERATION
 * trigger-mode: continuous
 * wake-up sensor: no
 *
 * Indicates the linear acceleration of the device in device coordinates,
 * not including gravity.
 *
 * The output is conceptually:
 *    output of TYPE_ACCELERATION - output of TYPE_GRAVITY
 *
 * Readings on all axes should be close to 0 when device lies on a table.
 * Units are m/s^2.
 * The coordinate system is the same as is used for the acceleration sensor.
 */
#define SENSOR_TYPE_LINEAR_ACCELERATION             (10)


/*
 * SENSOR_TYPE_ROTATION_VECTOR
 * trigger-mode: continuous
 * wake-up sensor: no
 *
 * A rotation vector represents the orientation of the device as a combination
 * of an angle and an axis, in which the device has rotated through an angle
 * theta around an axis <x, y, z>. The three elements of the rotation vector
 * are <x*sin(theta/2), y*sin(theta/2), z*sin(theta/2)>, such that the magnitude
 * of the rotation vector is equal to sin(theta/2), and the direction of the
 * rotation vector is equal to the direction of the axis of rotation. The three
 * elements of the rotation vector are equal to the last three components of a
 * unit quaternion
 *   <cos(theta/2), x*sin(theta/2), y*sin(theta/2), z*sin(theta/2)>.
 * Elements of the rotation vector are unitless.  The x, y, and z axis are
 * defined in the same way as for the acceleration sensor.
 *
 * The reference coordinate system is defined as a direct orthonormal basis,
 * where:
 *
 * - X is defined as the vector product Y.Z (It is tangential to
 * the ground at the device's current location and roughly points East).
 *
 * - Y is tangential to the ground at the device's current location and
 * points towards the magnetic North Pole.
 *
 * - Z points towards the sky and is perpendicular to the ground.
 *
 *
 * The rotation-vector is stored as:
 *
 *   sensors_event_t.data[0] = x*sin(theta/2)
 *   sensors_event_t.data[1] = y*sin(theta/2)
 *   sensors_event_t.data[2] = z*sin(theta/2)
 *
 * In addition, this sensor reports an estimated heading accuracy.
 *   sensors_event_t.data[3] = estimated_accuracy (in radians)
 * The heading error must be less than estimated_accuracy 95% of the time
 *
 * This sensor must use a gyroscope and an accelerometer as main orientation
 * change input.
 *
 * This sensor can also include magnetometer input to make up for gyro drift,
 * but it cannot be implemented using only a magnetometer.
 */
#define SENSOR_TYPE_ROTATION_VECTOR                 (11)

/*
 * SENSOR_TYPE_RELATIVE_HUMIDITY
 * trigger-mode: on-change
 * wake-up sensor: no
 *
 * A relative humidity sensor measures relative ambient air humidity and
 * returns a value in percent.
 */
#define SENSOR_TYPE_RELATIVE_HUMIDITY               (12)

/*
 * SENSOR_TYPE_AMBIENT_TEMPERATURE
 * trigger-mode: on-change
 * wake-up sensor: no
 *
 * The ambient (room) temperature in degree Celsius.
 */
#define SENSOR_TYPE_AMBIENT_TEMPERATURE             (13)

/*
 * SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED
 * trigger-mode: continuous
 * wake-up sensor: no
 *
 *  Similar to SENSOR_TYPE_MAGNETIC_FIELD, but the hard iron calibration is
 *  reported separately instead of being included in the measurement.
 *  Factory calibration and temperature compensation should still be applied to
 *  the "uncalibrated" measurement.
 *  Separating away the hard iron calibration estimation allows the system to
 *  better recover from bad hard iron estimation.
 *
 *  All values are in micro-Tesla (uT) and measure the ambient magnetic
 *  field in the X, Y and Z axis. Assumptions that the the magnetic field
 *  is due to the Earth's poles should be avoided.
 *
 *  The uncalibrated_magnetic event contains
 *  - 3 fields for uncalibrated measurement: x_uncalib, y_uncalib, z_uncalib.
 *    Each is a component of the measured magnetic field, with soft iron
 *    and temperature compensation applied, but not hard iron calibration.
 *    These values should be continuous (no re-calibration should cause a jump).
 *  - 3 fields for hard iron bias estimates: x_bias, y_bias, z_bias.
 *    Each field is a component of the estimated hard iron calibration.
 *    They represent the offsets to apply to the uncalibrated readings to obtain
 *    calibrated readings (x_calibrated = x_uncalib + x_bias)
 *    These values are expected to jump as soon as the estimate of the hard iron
 *    changes.
 *
 *  If this sensor is present, then the corresponding
 *  SENSOR_TYPE_MAGNETIC_FIELD must be present and both must return the
 *  same sensor_t::name and sensor_t::vendor.
 *
 * See SENSOR_TYPE_MAGNETIC_FIELD for more information
 */
#define SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED     (14)

/*
 * SENSOR_TYPE_GAME_ROTATION_VECTOR
 * trigger-mode: continuous
 * wake-up sensor: no
 *
 *  Similar to SENSOR_TYPE_ROTATION_VECTOR, but not using the geomagnetic
 *  field. Therefore the Y axis doesn't point north, but instead to some other
 *  reference. That reference is allowed to drift by the same order of
 *  magnitude than the gyroscope drift around the Z axis.
 *
 *  This sensor does not report an estimated heading accuracy:
 *    sensors_event_t.data[3] is reserved and should be set to 0
 *
 *  In the ideal case, a phone rotated and returning to the same real-world
 *  orientation should report the same game rotation vector
 *  (without using the earth's geomagnetic field).
 *
 *  This sensor must be based on a gyroscope. It cannot be implemented using
 *  a magnetometer.
 *
 * see SENSOR_TYPE_ROTATION_VECTOR for more details
 */
#define SENSOR_TYPE_GAME_ROTATION_VECTOR            (15)

/*
 * SENSOR_TYPE_GYROSCOPE_UNCALIBRATED
 * trigger-mode: continuous
 * wake-up sensor: no
 *
 *  All values are in radians/second and measure the rate of rotation
 *  around the X, Y and Z axis. An estimation of the drift on each axis is
 *  reported as well.
 *
 *  No gyro-drift compensation shall be performed.
 *  Factory calibration and temperature compensation should still be applied
 *  to the rate of rotation (angular speeds).
 *
 *  The coordinate system is the same as is
 *  used for the acceleration sensor. Rotation is positive in the
 *  counter-clockwise direction (right-hand rule). That is, an observer
 *  looking from some positive location on the x, y or z axis at a device
 *  positioned on the origin would report positive rotation if the device
 *  appeared to be rotating counter clockwise. Note that this is the
 *  standard mathematical definition of positive rotation and does not agree
 *  with the definition of roll given earlier.
 *  The range should at least be 17.45 rad/s (ie: ~1000 deg/s).
 *
 *  Content of an uncalibrated_gyro event: (units are rad/sec)
 *   x_uncalib : angular speed (w/o drift compensation) around the X axis
 *   y_uncalib : angular speed (w/o drift compensation) around the Y axis
 *   z_uncalib : angular speed (w/o drift compensation) around the Z axis
 *   x_bias : estimated drift around X axis in rad/s
 *   y_bias : estimated drift around Y axis in rad/s
 *   z_bias : estimated drift around Z axis in rad/s
 *
 *  IMPLEMENTATION NOTES:
 *
 *  If the implementation is not able to estimate the drift, then this
 *  sensor MUST NOT be reported by this HAL. Instead, the regular
 *  SENSOR_TYPE_GYROSCOPE is used without drift compensation.
 *
 *  If this sensor is present, then the corresponding
 *  SENSOR_TYPE_GYROSCOPE must be present and both must return the
 *  same sensor_t::name and sensor_t::vendor.
 */
#define SENSOR_TYPE_GYROSCOPE_UNCALIBRATED          (16)


/*
 * SENSOR_TYPE_SIGNIFICANT_MOTION
 * trigger-mode: one-shot
 * wake-up sensor: yes
 *
 * A sensor of this type triggers an event each time significant motion
 * is detected and automatically disables itself.
 * The only allowed value to return is 1.0.
 *
 *
 * TODO: give more details about what constitute significant motion
 *       and/or what algorithm is to be used
 *
 *
 *  IMPORTANT NOTE: this sensor type is very different from other types
 *  in that it must work when the screen is off without the need of
 *  holding a partial wake-lock and MUST allow the SoC to go into suspend.
 *  When significant motion is detected, the sensor must awaken the SoC and
 *  the event be reported.
 *
 *  If a particular hardware cannot support this mode of operation then this
 *  sensor type MUST NOT be reported by the HAL. ie: it is not acceptable
 *  to "emulate" this sensor in the HAL.
 *
 *  The whole point of this sensor type is to save power by keeping the
 *  SoC in suspend mode when the device is at rest.
 *
 *  When the sensor is not activated, it must also be deactivated in the
 *  hardware: it must not wake up the SoC anymore, even in case of
 *  significant motion.
 *
 *  setDelay() has no effect and is ignored.
 *  Once a "significant motion" event is returned, a sensor of this type
 *  must disables itself automatically, as if activate(..., 0) had been called.
 */

#define SENSOR_TYPE_SIGNIFICANT_MOTION              (17)


/*
 * SENSOR_TYPE_STEP_DETECTOR
 * trigger-mode: special
 * wake-up sensor: no
 *
 * A sensor of this type triggers an event each time a step is taken
 * by the user. The only allowed value to return is 1.0 and an event is
 * generated for each step. Like with any other event, the timestamp
 * indicates when the event (here the step) occurred, this corresponds to when
 * the foot hit the ground, generating a high variation in acceleration.
 *
 * While this sensor operates, it shall not disrupt any other sensors, in
 * particular, but not limited to, the accelerometer; which might very well
 * be in use as well.
 *
 * This sensor must be low power. That is, if the step detection cannot be
 * done in hardware, this sensor should not be defined. Also, when the
 * step detector is activated and the accelerometer is not, only steps should
 * trigger interrupts (not accelerometer data).
 *
 * setDelay() has no impact on this sensor type
 */

#define SENSOR_TYPE_STEP_DETECTOR                   (18)


/*
 * SENSOR_TYPE_STEP_COUNTER
 * trigger-mode: on-change
 * wake-up sensor: no
 *
 * A sensor of this type returns the number of steps taken by the user since
 * the last reboot while activated. The value is returned as a uint64_t and is
 * reset to zero only on a system reboot.
 *
 * The timestamp of the event is set to the time when the first step
 * for that event was taken.
 * See SENSOR_TYPE_STEP_DETECTOR for the signification of the time of a step.
 *
 *  The minimum size of the hardware's internal counter shall be 16 bits
 *  (this restriction is here to avoid too frequent wake-ups when the
 *  delay is very large).
 *
 *  IMPORTANT NOTE: this sensor type is different from other types
 *  in that it must work when the screen is off without the need of
 *  holding a partial wake-lock and MUST allow the SoC to go into suspend.
 *  Unlike other sensors, while in suspend mode this sensor must stay active,
 *  no events are reported during that time but, steps continue to be
 *  accounted for; an event will be reported as soon as the SoC resumes if
 *  the timeout has expired.
 *
 *    In other words, when the screen is off and the device allowed to
 *    go into suspend mode, we don't want to be woken up, regardless of the
 *    setDelay() value, but the steps shall continue to be counted.
 *
 *    The driver must however ensure that the internal step count never
 *    overflows. It is allowed in this situation to wake the SoC up so the
 *    driver can do the counter maintenance.
 *
 *  While this sensor operates, it shall not disrupt any other sensors, in
 *  particular, but not limited to, the accelerometer; which might very well
 *  be in use as well.
 *
 *  If a particular hardware cannot support these modes of operation then this
 *  sensor type MUST NOT be reported by the HAL. ie: it is not acceptable
 *  to "emulate" this sensor in the HAL.
 *
 * This sensor must be low power. That is, if the step detection cannot be
 * done in hardware, this sensor should not be defined. Also, when the
 * step counter is activated and the accelerometer is not, only steps should
 * trigger interrupts (not accelerometer data).
 *
 *  The whole point of this sensor type is to save power by keeping the
 *  SoC in suspend mode when the device is at rest.
 */

#define SENSOR_TYPE_STEP_COUNTER                    (19)

/*
 * SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR
 * trigger-mode: continuous
 * wake-up sensor: no
 *
 *  Similar to SENSOR_TYPE_ROTATION_VECTOR, but using a magnetometer instead
 *  of using a gyroscope.
 *
 *  This sensor must be based on a magnetometer. It cannot be implemented using
 *  a gyroscope, and gyroscope input cannot be used by this sensor.
 *
 *  Just like SENSOR_TYPE_ROTATION_VECTOR, this sensor reports an estimated
 *  heading accuracy:
 *    sensors_event_t.data[3] = estimated_accuracy (in radians)
 *  The heading error must be less than estimated_accuracy 95% of the time
 *
 * see SENSOR_TYPE_ROTATION_VECTOR for more details
 */
#define SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR            (20)

/**
 * Values returned by the accelerometer in various locations in the universe.
 * all values are in SI units (m/s^2)
 */
#define GRAVITY_SUN             (275.0f)
#define GRAVITY_EARTH           (9.80665f)

/** Maximum magnetic field on Earth's surface */
#define MAGNETIC_FIELD_EARTH_MAX    (60.0f)

/** Minimum magnetic field on Earth's surface */
#define MAGNETIC_FIELD_EARTH_MIN    (30.0f)


/**
 * status of orientation sensor
 */

#define SENSOR_STATUS_UNRELIABLE        0
#define SENSOR_STATUS_ACCURACY_LOW      1
#define SENSOR_STATUS_ACCURACY_MEDIUM   2
#define SENSOR_STATUS_ACCURACY_HIGH     3


/**
 * sensor event data
 */
typedef struct {
    union {
        float v[3];
        struct {
            float x;
            float y;
            float z;
        };
        struct {
            float azimuth;
            float pitch;
            float roll;
        };
    };
    int8_t status;
    uint8_t reserved[3];
} sensors_vec_t;

/**
 * uncalibrated gyroscope and magnetometer event data
 */
typedef struct {
  float x_uncalib;
  float y_uncalib;
  float z_uncalib;
  float x_bias;
  float y_bias;
  float z_bias;
} uncalibrated_event_t;

/**
 * Union of the various types of sensor data
 * that can be returned.
 */
typedef struct sensors_event_t {
    /* must be sizeof(struct sensors_event_t) */
    int32_t version;

    /* sensor identifier */
    int32_t sensor;

    /* sensor type */
    int32_t type;

    /* reserved */
    int32_t reserved0;

    /* time is in nanosecond */
    int64_t timestamp;

    union {
        float           data[16];

        /* acceleration values are in meter per second per second (m/s^2) */
        sensors_vec_t   acceleration;

        /* magnetic vector values are in micro-Tesla (uT) */
        sensors_vec_t   magnetic;

        /* orientation values are in degrees */
        sensors_vec_t   orientation;

        /* gyroscope values are in rad/s */
        sensors_vec_t   gyro;

        /* temperature is in degrees centigrade (Celsius) */
        float           temperature;

        /* distance in centimeters */
        float           distance;

        /* light in SI lux units */
        float           light;

        /* pressure in hectopascal (hPa) */
        float           pressure;

        /* relative humidity in percent */
        float           relative_humidity;

        /* step-counter */
        uint64_t        step_counter;

        /* uncalibrated gyroscope values are in rad/s */
        uncalibrated_event_t uncalibrated_gyro;

        /* uncalibrated magnetometer values are in micro-Teslas */
        uncalibrated_event_t uncalibrated_magnetic;
    };
    uint32_t        reserved1[4];
} sensors_event_t;



struct sensor_t;

/**
 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
 * and the fields of this data structure must begin with hw_module_t
 * followed by module specific information.
 */
struct sensors_module_t {
    struct hw_module_t common;

    /**
     * Enumerate all available sensors. The list is returned in "list".
     * @return number of sensors in the list
     */
    int (*get_sensors_list)(struct sensors_module_t* module,
            struct sensor_t const** list);
};

struct sensor_t {

    /* Name of this sensor.
     * All sensors of the same "type" must have a different "name".
     */
    const char*     name;

    /* vendor of the hardware part */
    const char*     vendor;

    /* version of the hardware part + driver. The value of this field
     * must increase when the driver is updated in a way that changes the
     * output of this sensor. This is important for fused sensors when the
     * fusion algorithm is updated.
     */    
    int             version;

    /* handle that identifies this sensors. This handle is used to reference
     * this sensor throughout the HAL API.
     */
    int             handle;

    /* this sensor's type. */
    int             type;

    /* maximum range of this sensor's value in SI units */
    float           maxRange;

    /* smallest difference between two values reported by this sensor */
    float           resolution;

    /* rough estimate of this sensor's power consumption in mA */
    float           power;

    /* this value depends on the trigger mode:
     *
     *   continuous: minimum sample period allowed in microseconds
     *   on-change : 0
     *   one-shot  :-1
     *   special   : 0, unless otherwise noted
     */
    int32_t         minDelay;

    /* reserved fields, must be zero */
    void*           reserved[8];
};


/*
 * sensors_poll_device_t is used with SENSORS_DEVICE_API_VERSION_0_1
 * and is present for backward binary and source compatibility.
 * (see documentation of the hooks in struct sensors_poll_device_1 below)
 */
struct sensors_poll_device_t {
    struct hw_device_t common;
    int (*activate)(struct sensors_poll_device_t *dev,
            int handle, int enabled);
    int (*setDelay)(struct sensors_poll_device_t *dev,
            int handle, int64_t ns);
    int (*poll)(struct sensors_poll_device_t *dev,
            sensors_event_t* data, int count);
};

/*
 * struct sensors_poll_device_1 is used with SENSORS_DEVICE_API_VERSION_1_0
 */
typedef struct sensors_poll_device_1 {
    union {
        /* sensors_poll_device_1 is compatible with sensors_poll_device_t,
         * and can be down-cast to it
         */
        struct sensors_poll_device_t v0;

        struct {
            struct hw_device_t common;

            /* Activate/de-activate one sensor.
             *
             * handle is the handle of the sensor to change.
             * enabled set to 1 to enable, or 0 to disable the sensor.
             *
             * unless otherwise noted in the sensor types definitions, an
             * activated sensor never prevents the SoC to go into suspend
             * mode; that is, the HAL shall not hold a partial wake-lock on
             * behalf of applications.
             *
             * one-shot sensors de-activate themselves automatically upon
             * receiving an event and they must still accept to be deactivated
             * through a call to activate(..., ..., 0).
             *
             * if "enabled" is true and the sensor is already activated, this
             * function is a no-op and succeeds.
             *
             * if "enabled" is false and the sensor is already de-activated,
             * this function is a no-op and succeeds.
             *
             * return 0 on success, negative errno code otherwise
             */
            int (*activate)(struct sensors_poll_device_t *dev,
                    int handle, int enabled);

            /**
             * Set the events's period in nanoseconds for a given sensor.
             *
             * What the period_ns parameter means depends on the specified
             * sensor's trigger mode:
             *
             * continuous: setDelay() sets the sampling rate.
             * on-change: setDelay() limits the delivery rate of events
             * one-shot: setDelay() is ignored. it has no effect.
             * special: see specific sensor type definitions
             *
             * For continuous and on-change sensors, if the requested value is
             * less than sensor_t::minDelay, then it's silently clamped to
             * sensor_t::minDelay unless sensor_t::minDelay is 0, in which
             * case it is clamped to >= 1ms.
             *
             * @return 0 if successful, < 0 on error
             */
            int (*setDelay)(struct sensors_poll_device_t *dev,
                    int handle, int64_t period_ns);

            /**
             * Returns an array of sensor data.
             * This function must block until events are available.
             *
             * return the number of events read on success, or -errno in case
             * of an error.
             *
             * The number of events returned in data must be less or equal
             * to SENSORS_QUERY_MAX_EVENTS_BATCH_COUNT.
             *
             * This function shall never return 0 (no event).
             */
            int (*poll)(struct sensors_poll_device_t *dev,
                    sensors_event_t* data, int count);
        };
    };

    /*
     * Used to retrieve information about the sensor HAL
     *
     * Returns 0 on success or -errno on error.
     */
    int (*query)(struct sensors_poll_device_1* dev, int what, int* value);


    /*
     * Enables batch mode for the given sensor and sets the delay between events
     *
     * A timeout value of zero disables batch mode for the given sensor.
     *
     * The period_ns parameter is equivalent to calling setDelay() -- this
     * function both enables or disables the batch mode AND sets the events's
     * period in nanosecond. See setDelay() above for a detailed explanation of
     * the period_ns parameter.
     *
     * While in batch mode sensor events are reported in batches at least
     * every "timeout" nanosecond; that is all events since the previous batch
     * are recorded and returned all at once. Batches can be interleaved and
     * split, and as usual events of the same sensor type are time-ordered.
     *
     * setDelay() is not affected and it behaves as usual.
     *
     * Each event has a timestamp associated with it, the timestamp
     * must be accurate and correspond to the time at which the event
     * physically happened.
     *
     * If internal h/w FIFOs fill-up before the timeout, then events are
     * reported at that point. No event shall be dropped or lost.
     *
     *
     * INTERACTION WITH SUSPEND MODE:
     * ------------------------------
     *
     * By default batch mode doesn't significantly change the interaction with
     * suspend mode, that is, sensors must continue to allow the SoC to
     * go into suspend mode and sensors must stay active to fill their
     * internal FIFO, in this mode, when the FIFO fills-up, it shall wrap
     * around (basically behave like a circular buffer, overwriting events).
     * As soon as the SoC comes out of suspend mode, a batch is produced with
     * as much as the recent history as possible, and batch operation
     * resumes as usual.
     *
     * The behavior described above allows applications to record the recent
     * history of a set of sensor while keeping the SoC into suspend. It
     * also allows the hardware to not have to rely on a wake-up interrupt line.
     *
     * There are cases however where an application cannot afford to lose
     * any events, even when the device goes into suspend mode. The behavior
     * specified above can be altered by setting the
     * SENSORS_BATCH_WAKE_UPON_FIFO_FULL flag. If this flag is set, the SoC
     * must be woken up from suspend and a batch must be returned before
     * the FIFO fills-up. Enough head room must be allocated in the FIFO to allow
     * the device to entirely come out of suspend (which might take a while and
     * is device dependent) such that no event are lost.
     *
     *   If the hardware cannot support this mode, or, if the physical
     *   FIFO is so small that the device would never be allowed to go into
     *   suspend for at least 10 seconds, then this function MUST fail when
     *   the flag SENSORS_BATCH_WAKE_UPON_FIFO_FULL is set, regardless of
     *   the value of the timeout parameter.
     *
     * DRY RUN:
     * --------
     *
     * If the flag SENSORS_BATCH_DRY_RUN is set, this function returns
     * without modifying the batch mode or the event period and has no side
     * effects, but returns errors as usual (as it would if this flag was
     * not set). This flag is used to check if batch mode is available for a
     * given configuration -- in particular for a given sensor at a given rate.
     *
     *
     * Return values:
     * --------------
     *
     * Because sensors must be independent, the return value must not depend
     * on the state of the system (whether another sensor is on or not),
     * nor on whether the flag SENSORS_BATCH_DRY_RUN is set (in other words,
     * if a batch call with SENSORS_BATCH_DRY_RUN is successful,
     * the same call without SENSORS_BATCH_DRY_RUN must succeed as well).
     *
     * If successful, 0 is returned.
     * If the specified sensor doesn't support batch mode, -EINVAL is returned.
     * If the specified sensor's trigger-mode is one-shot, -EINVAL is returned.
     * If any of the constraint above cannot be satisfied, -EINVAL is returned.
     *
     * Note: the timeout parameter, when > 0, has no impact on whether this
     *       function succeeds or fails.
     *
     * If timeout is set to 0, this function must succeed.
     *
     *
     * IMPLEMENTATION NOTES:
     * ---------------------
     *
     * batch mode, if supported, should happen at the hardware level,
     * typically using hardware FIFOs. In particular, it SHALL NOT be
     * implemented in the HAL, as this would be counter productive.
     * The goal here is to save significant amounts of power.
     *
     * batch mode can be enabled or disabled at any time, in particular
     * while the specified sensor is already enabled and this shall not
     * result in the loss of events.
     *
     * COMPARATIVE IMPORTANCE OF BATCHING FOR DIFFERENT SENSORS:
     * ---------------------------------------------------------
     *
     * On platforms on which hardware fifo size is limited, the system designers
     * might have to choose how much fifo to reserve for each sensor. To help
     * with this choice, Here is a list of applications made possible when
     * batching is implemented on the different sensors.
     *
     * High value: Low power pedestrian dead reckoning
     *   Target batching time: 20 seconds to 1 minute
     *   Sensors to batch:
     *    - Step detector
     *    - Rotation vector or game rotation vector at 5Hz
     *   Gives us step and heading while letting the AP go to Suspend.
     *
     * High value: Medium power activity/gesture recognition
     *   Target batching time: 3 seconds
     *   Sensors to batch: accelerometer between 20Hz and 50Hz
     *   Allows recognizing arbitrary activities and gestures without having
     *   to keep the AP fully awake while the data is collected.
     *
     * Medium-high value: Interrupt load reduction
     *   Target batching time: < 1 second
     *   Sensors to batch: any high frequency sensor.
     *   If the gyroscope is set at 800Hz, even batching just 10 gyro events can
     *   reduce the number of interrupts from 800/second to 80/second.
     *
     * Medium value: Continuous low frequency data collection
     *   Target batching time: > 1 minute
     *   Sensors to batch: barometer, humidity sensor, other low frequency
     *     sensors.
     *   Allows creating monitoring applications at low power.
     *
     * Medium value: Continuous full-sensors collection
     *   Target batching time: > 1 minute
     *   Sensors to batch: all, at high frequencies
     *   Allows full collection of sensor data while leaving the AP in
     *   suspend mode. Only to consider if fifo space is not an issue.
     */
    int (*batch)(struct sensors_poll_device_1* dev,
            int handle, int flags, int64_t period_ns, int64_t timeout);

    void (*reserved_procs[8])(void);

} sensors_poll_device_1_t;



/** convenience API for opening and closing a device */

static inline int sensors_open(const struct hw_module_t* module,
        struct sensors_poll_device_t** device) {
    return module->methods->open(module,
            SENSORS_HARDWARE_POLL, (struct hw_device_t**)device);
}

static inline int sensors_close(struct sensors_poll_device_t* device) {
    return device->common.close(&device->common);
}

static inline int sensors_open_1(const struct hw_module_t* module,
        sensors_poll_device_1_t** device) {
    return module->methods->open(module,
            SENSORS_HARDWARE_POLL, (struct hw_device_t**)device);
}

static inline int sensors_close_1(sensors_poll_device_1_t* device) {
    return device->common.close(&device->common);
}

__END_DECLS

#endif  // ANDROID_SENSORS_INTERFACE_H