improve sensor HAL documentation
Change-Id: If2c1613902de6ed0e6cae8fe4755948c0f623bda
diff --git a/include/hardware/sensors.h b/include/hardware/sensors.h
index 4a8ce3e..af6bced 100644
--- a/include/hardware/sensors.h
+++ b/include/hardware/sensors.h
@@ -118,8 +118,8 @@
* O: Origin (x=0,y=0,z=0)
*
*
- * Orientation
- * -----------
+ * SENSOR_TYPE_ORIENTATION
+ * -----------------------
*
* All values are angles in degrees.
*
@@ -155,8 +155,8 @@
* where the X axis is along the long side of the plane (tail to nose).
*
*
- * Acceleration
- * ------------
+ * SENSOR_TYPE_ACCELEROMETER
+ * -------------------------
*
* All values are in SI units (m/s^2) and measure the acceleration of the
* device minus the force of gravity.
@@ -182,8 +182,8 @@
* gravity (-9.81 m/s^2).
*
*
- * Magnetic Field
- * --------------
+ * SENSOR_TYPE_MAGNETIC_FIELD
+ * --------------------------
*
* All values are in micro-Tesla (uT) and measure the ambient magnetic
* field in the X, Y and Z axis.
@@ -191,8 +191,9 @@
* Magnetic Field sensors return sensor events for all 3 axes at a constant
* rate defined by setDelay().
*
- * Gyroscope
- * ---------
+ * SENSOR_TYPE_GYROSCOPE
+ * ---------------------
+ *
* 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
@@ -204,8 +205,8 @@
* with the definition of roll given earlier.
* The range should at least be 17.45 rad/s (ie: ~1000 deg/s).
*
- * Proximity
- * ---------
+ * SENSOR_TYPE_PROXIMITY
+ * ----------------------
*
* The distance value is measured in centimeters. Note that some proximity
* sensors only support a binary "close" or "far" measurement. In this case,
@@ -215,49 +216,42 @@
* Proximity sensors report a value only when it changes and each time the
* sensor is enabled.
*
- * Light
- * -----
+ * SENSOR_TYPE_LIGHT
+ * -----------------
*
* The light sensor value is returned in SI lux units.
*
* Light sensors report a value only when it changes and each time the
* sensor is enabled.
*
- * Pressure
- * --------
+ * SENSOR_TYPE_PRESSURE
+ * --------------------
*
- * The pressure sensor value is returned in hectopascal (hPa)
+ * The pressure sensor return the athmospheric pressure in hectopascal (hPa)
*
* Pressure sensors report events at a constant rate defined by setDelay().
*
- * Gyro
- * --------
- *
- * The gyroscope sensor values are returned in degrees per second (dps)
- *
- * Gyroscope sensor report events at a constant rate defined by setDelay().
- *
- * Gravity
- * -------
- * A gravity output indicates the direction of and magnitude of gravity in the devices's
- * coordinates. On Earth, the magnitude is 9.8. 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.
- *
- * Linear Acceleration
+ * SENSOR_TYPE_GRAVITY
* -------------------
- * Indicates the linear acceleration of the device in device coordinates, not including gravity.
- * This output is essentially Acceleration - Gravity. Units are m/s^2. The coordinate system is
- * the same as is used for the acceleration sensor.
- * The output of the accelerometer, gravity and linear-acceleration sensors must obey the
- * following relation:
*
- * acceleration = gravity + linear-acceleration
+ * 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.
+ *
+ * SENSOR_TYPE_LINEAR_ACCELERATION
+ * --------------------------------
+ *
+ * Indicates the linear acceleration of the device in device coordinates,
+ * not including gravity.
+ * This output is essentially Acceleration - Gravity. Units are m/s^2.
+ * The coordinate system is the same as is used for the acceleration sensor.
*
*
- * Rotation Vector
- * ---------------
+ * SENSOR_TYPE_ROTATION_VECTOR
+ * ---------------------------
+ *
* 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
@@ -289,8 +283,8 @@
* sensors_event_t.data[3] = cos(theta/2)
*
*
- * Relative Humidity
- * -----------------
+ * SENSOR_TYPE_RELATIVE_HUMIDITY
+ * ------------------------------
*
* A relative humidity sensor measures relative ambient air humidity and
* returns a value in percent.
@@ -299,8 +293,8 @@
* time the sensor is enabled.
*
*
- * Ambient Temperature
- * -------------------
+ * SENSOR_TYPE_AMBIENT_TEMPERATURE
+ * -------------------------------
*
* The ambient (room) temperature in degree Celsius.
*
@@ -405,9 +399,10 @@
const char* name;
/* vendor of the hardware part */
const char* vendor;
- /* version of the hardware part + driver. The value of this field is
- * left to the implementation and doesn't have to be monotonically
- * increasing.
+ /* 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 activate
@@ -452,11 +447,9 @@
/**
* Set the delay between sensor events in nanoseconds for a given sensor.
*
- * It is an error to set a delay inferior to the value defined by
- * sensor_t::minDelay.
- *
- * If sensor_t::minDelay is zero, setDelay() returns an error if the
- * requested delay is inferior to 1ms.
+ * 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
*/