Docs: Porting new sensors content to site.
Bug: 17410055
Change-Id: Ice1a842e90f1c644b1bc94727383ad7c095cc650
diff --git a/src/devices/sensors/index.jd b/src/devices/sensors/index.jd
index e5fa438..6f21488 100644
--- a/src/devices/sensors/index.jd
+++ b/src/devices/sensors/index.jd
@@ -1,8 +1,8 @@
-page.title=Sensors HAL overview
+page.title=Sensors
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2014 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.
@@ -24,238 +24,138 @@
</div>
</div>
-<h2 id="intro">Introduction</h2>
-<p><a href="http://developer.android.com/guide/topics/sensors/sensors_overview.html">Android
- sensors</a> give applications access to a mobile device's underlying base sensor(s):
- accelerometer, gyroscope, and magnetometer. Manufacturers develop the drivers
- that define additional composite sensor types from those base sensors. For
- instance, Android offers both calibrated and uncalibrated gyroscopes, a
- geomagnetic rotation vector and a game rotation vector. This variety gives
- developers some flexibility in tuning applications for battery life optimization
- and accuracy.</p>
-<p>The <a href="{@docRoot}devices/reference/sensors_8h_source.html">Sensors
-Hardware Abstraction Layer (HAL) API</a> is the interface between the hardware drivers
-and the Android framework; the <a href="http://developer.android.com/reference/android/hardware/Sensor.html">Sensors Software Development Kit (SDK)
- API</a> is the interface between the Android framework and the Java applications. Please note,
- the Sensors HAL API described in this documentation is not identical to the
- Sensors SDK API described on <a href="http://developer.android.com/reference/android/hardware/Sensor.html">developer.android.com</a>.
- For example, some sensors that are deprecated in the SDK may still exist in the
- HAL, and vice versa.</p>
-<p>Similarly, audio recorders, Global Positioning System (GPS) devices, and
- accessory (pluggable) sensors are not supported by the Android Sensors HAL API
- described here. This API covers sensors that are physically part of the device
- only. Please see the <a href="{@docRoot}devices/audio.html">Audio</a>, <a href="{@docRoot}devices/reference/gps_8h.html">Location </a><a href="{@docRoot}devices/reference/gps_8h.html">Strategies</a>,
- and the <a href="{@docRoot}accessories/index.html">Accessories</a> section
- for information on those devices.</p>
-<p>Application framework<br/>
- At the application framework level is the app code, which utilizes the <a href="http://developer.android.com/reference/android/hardware/package-summary.html">android.hardware</a> APIs to interact with the sensors hardware. Internally, this code calls
- corresponding JNI glue classes to access the native code that interacts with the
- sensors hardware.</p>
-<p>JNI<br/>
- The JNI code associated with <a href="http://developer.android.com/reference/android/hardware/package-summary.html">android.hardware</a> is located in the frameworks/base/core/jni/ directory. This code calls the lower
- level native code to obtain access to the sensor hardware.</p>
-<p>Native framework<br/>
- The native framework is defined in <code>frameworks/native/</code> and provides a native
- equivalent to the <a href="http://developer.android.com/reference/android/hardware/package-summary.html">android.hardware</a> package. The native framework calls the Binder IPC proxies to obtain access to
- sensor-specific services.</p>
-<p>Binder IPC<br/>
- The Binder IPC proxies facilitate communication over process boundaries.</p>
-<p>HAL<br/>
- The Hardware Abstraction Layer (HAL) defines the standard interface that sensor
- services call into and that you must implement to have your sensor hardware
- function correctly. The sensor HAL interfaces are located in
- <code>hardware/libhardware/include/hardware</code>. See <a
-href="http://source.android.com/devices/reference/sensors_8h.html">sensors.h</a> for
-additional details.</p>
-<p>Kernel Driver<br/>
- The sensors driver interacts with the hardware and your implementation of the
- HAL. The HAL is driver-agnostic.</p>
-<h3 id="axis-def">Sensor axis definition</h3>
-<p>The sensor event values are expressed in a specific frame that is static
- relative to the phone. This API is relative only to the NATURAL orientation of
- the screen. In other words:</p>
-<ul>
- <li>the axes are not swapped when the device's screen orientation changes.</li>
- <li>higher level services <em>may</em> perform this transformation.</li>
-</ul>
-<div class="figure" style="width:269px"> <img src="http://developer.android.com/images/axis_device.png" alt="Coordinate system relative to device for Sensor
- API" height="225" />
- <p class="img-caption"> <strong>Figure 1.</strong> Coordinate system (relative to a device) that's used by the Sensor
- API. </p>
-</div>
-<h3 id="accuracy">Accuracy</h3>
-<p>The sensors included by the manufacturer must be accurate and precise to meet
-the expectations of application developers. The sensors included in Android devices are
- tested for sensor interaction and accuracy as part of the <a href="{@docRoot}compatibility/index.html">Android Compatibility
- program</a> starting in the
- Android 4.4 release. Testing will continue to be improved in future releases.
- See the <em>Sensors</em> section of the Android Compatibility Definition Document (CDD)
- for the exact requirements.</p>
-<h3 id="power">Power consumption</h3>
-<p>Some defined sensor are higher power than others. Others are lower power by
- design and should be implemented as such with their processing done in the
- hardware. This means they should not require the application processor to be
- running. Here are the low-power sensors:</p>
-<ul>
- <li><a href="{@docRoot}devices/sensors/composite_sensors.html#Magnetometer">Geomagnetic rotation vector</a></li>
- <li><a href="{@docRoot}devices/sensors/composite_sensors.html#Significant">Significant motion</a></li>
- <li><a href="{@docRoot}devices/sensors/composite_sensors.html#counter">Step counter</a></li>
- <li><a href="{@docRoot}devices/sensors/composite_sensors.html#detector">Step detector</a></li>
-</ul>
-<p>They are accompanied by a low-power <img src="images/battery_icon.png"
-alt="low-power sensors"/>
- icon in the <a href="{@docRoot}devices/sensors/composite_sensors.html#summary">Sensor summary</a> table. </p>
-<p>These sensor types cannot be implemented at high power as their primary benefit
- is low battery use. It is better to not implement a low-power sensor at all
- rather than implement it as high power.</p>
-<p>Composite low-power sensor types, such as the step detector, must have their
- processing conducted in the hardware; power use is much lower than if done in
- the software. Power use is low on small microprocessors and even lower still on
- application-specific integrated circuits (ASICs). A hardware implementation of
- composite sensor types can also make use of more raw sensor data and a better
- synchronization between sensors.</p>
-<h3 id="release">HAL release cycle</h3>
-<p>Functionality is tied to versions of the API. Android maintains two versions of
- the Sensors HAL API per release. For instance, if version 1 was the latest and
- version 1.1 is released, the version prior to 1 will no longer be supported upon
- that release. Only the two latest versions of the Sensors HAL API are supported.</p>
-<h2 id="interaction">Interaction</h2>
-<h3 id="concurrent">Concurrent running</h3>
-<p>Android sensors must work independently of one another. Activating one sensor
- shall not deactivate another sensor. Activating one shall not reduce the rate of
- another. This is a key element of compatibility testing.</p>
-<h3 id="suspend">Interaction with suspend mode</h3>
-<p>Unless otherwise noted, an enabled sensor shall not prevent the system on a chip
- (SoC) from going into suspend mode. It is the responsibility of applications to keep a
- partial <a href="http://developer.android.com/reference/android/os/PowerManager.WakeLock.html">wake
- lock</a> should they wish to receive sensor events while the screen is off. While in
- suspend mode, and unless otherwise noted (<a
-href="{@docRoot}devices/sensors/batching.html">batch</a> mode
- and sensor particularities), enabled sensors' events are lost.</p>
-<p>Note that conceptually, the sensor itself is not deactivated while in suspend
- mode. Instead, the data it returns is missing. The oldest data is dropped to
- accommodate the latest data. As soon as the SoC gets out of suspend mode,
- operations resume as normal.</p>
-<p>Most applications should either hold a wake lock to ensure the system doesn't go
- to suspend, or unregister from the sensors when they do not need them, unless
- batch mode is active. When batching, sensors must continue to fill their
- internal FIFO. (See the documentation of <a
-href="{@docRoot}devices/sensors/batching.html">batch</a> mode
- to learn how suspend interacts with batch mode.)</p>
-<p>Wake-up sensors are a notable exception to the above. Wake-up sensors must
-wake up the SoC to deliver events. They must still let the SoC go into suspend
-mode, but must also wake it up when an event is triggered.</p>
-<h3 id="fusion">Sensor fusion and virtual sensors</h3>
-<p>Many composite sensor types are or can be implemented as virtual sensors from
- underlying base sensors on the device. Examples of composite sensors types
- include the rotation vector sensor, orientation sensor, step detector and step
- counter.</p>
-<p>From the point of view of this API, these virtual sensors <strong>must</strong> appear as
- real, individual sensors. It is the responsibility of the driver and HAL to make
- sure this is the case.</p>
-<p>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.</p>
-<h3 id="hal">HAL interface</h3>
-<p>These are the common sensor calls expected at the HAL level:</p>
-<ol>
- <li><em>getSensorList()</em> - Gets the list of all sensors.</li>
- <li><em>activate()</em> - Starts or stops the specified sensor.</li>
- <li><em>batch()</em> - Sets parameters to group event data collection and optimize power use.</li>
- <li><em>setDelay()</em> - Sets the event's period in
- nanoseconds for a given sensor.</li>
- <li><em>flush()</em> - Flush adds an event to the end of the
- "batch mode" FIFO for the specified sensor and flushes the FIFO.</li>
- <li><em>poll()</em> - Returns an array of sensor data. </li>
-</ol>
-<p>Please note, the implementation must be thread safe and allow these values to be
- called from different threads.</p>
-<h4 id="getSensorList">getSensorList(sensor_type)</h4>
-<p>Provide the list of sensors implemented by the HAL for the given sensor type. </p>
-<p>Developers may then make multiple calls to get sensors of different types or use
- <code>Sensor.TYPE_ALL</code> to get all the sensors. See getSensorList() defined on
- developer.android.com for more details.</p>
-<h4 id="activate">activate(sensor, true/false)</h4>
-<pre>
- int (*activate)(struct sensors_poll_device_t *dev,
- int handle, int enabled);</pre>
-<p>Activates or deactivates the sensor with the specified handle. Handles must be
- higher than <code>SENSORS_HANDLE_BASE</code> and must be unique. A handle identifies a given
- sensor. The handle is used to activate and/or deactivate sensors. In this
- version of the API, there can only be 256 handles.</p>
-<p>The handle is the handle of the sensor to change. The enabled argument is set to
- 1 to enable or 0 to disable the sensor.</p>
-<p>Unless otherwise noted in the individual sensor type descriptions, an activated
- sensor never prevents the SoC from going into suspend mode; that is, the HAL
- shall not hold a partial wake lock on behalf of applications.<br/>
- <br/>
- One-shot sensors deactivate themselves automatically upon receiving an event,
- and they must still accept to be deactivated through a call to activate(...,
- ..., 0).<br/>
- <br/>
- If "enabled" is 1 and the sensor is already activated, this function is a no-op
- and succeeds. If "enabled" is 0 and the sensor is already deactivated, this
- function is a no-op and succeeds. This returns 0 on success and a negative errno
- code otherwise.</p>
-<h4 id="batch">batch(sensor, batching parameters)</h4>
-<pre>
- int (*batch)(struct sensors_poll_device_1* dev,
- int handle, int flags, int64_t period_ns, int64_t timeout);
-</pre>
-<p>Sets parameters to group event data collection and reduce power use. Batching
- can enable significant power savings by allowing the application processor to
- sleep rather than awake for each notification. Instead, these notifications can
- be grouped and processed together. See the <a
-href="{@docRoot}devices/sensors/batching.html">Batching</a> section for details.</p>
-<h4 id="setDelay">setDelay(sensor, delay)</h4>
-<pre>
- int (*setDelay)(struct sensors_poll_device_t *dev,
- int handle, int64_t period_ns);
-</pre>
-<p>Sets the event's period in nanoseconds for a given sensor. What the
-<code>period_ns</code> parameter means depends on the specified sensor's trigger mode:</p>
-<ul>
- <li>Continuous: setDelay() sets the sampling rate.</li>
- <li>On-change: setDelay() limits the delivery rate of events.</li>
- <li>One-shot: setDelay() is ignored. It has no effect.</li>
- <li>Special: See specific sensor type descriptions.</li>
-</ul>
-<p>For continuous and on-change sensors, if the requested value is less than
-<code>sensor_t::minDelay</code>, then it's silently clamped to
-<code>sensor_t::minDelay</code> unless <code>sensor_t::minDelay</code> is 0,
-in which case it is clamped to >= 1ms. setDelay will not be called when the sensor is
-in batching mode. In this case, batch() will be called with the new period. Return 0 if successful,
-< 0 on error.</p>
-<p>When calculating the sampling period T in setDelay (or batch), the actual period
-should be smaller than T and no smaller than T/2. Finer granularity is not
-necessary.</p>
-<h4 id="flush">flush()</h4>
-<pre>
- int (*flush)(struct sensors_poll_device_1* dev, int handle);
-</pre>
-<p>Flush adds a <code>META_DATA_FLUSH_COMPLETE</code> event
-(<code>sensors_event_meta_data_t</code>) to the
- end of the "batch mode" FIFO for the specified sensor and flushes the FIFO;
- those events are delivered as usual (i.e.: as if the batch timeout had expired)
- and removed from the FIFO.<br/>
- <br/>
- The flush happens asynchronously (i.e.: this function must return immediately).
- If the implementation uses a single FIFO for several sensors, that FIFO is
- flushed and the <code>META_DATA_FLUSH_COMPLETE</code> event is added only for the specified
- sensor.<br/>
- <br/>
- If the specified sensor wasn't in batch mode, flush succeeds and promptly sends
- a <code>META_DATA_FLUSH_COMPLETE</code> event for that sensor.</p>
-<p>If the FIFO was empty at the time of the call, flush returns 0 (success) and
- promptly sends a <code>META_DATA_FLUSH_COMPLETE</code> event for that sensor.<br/>
- <br/>
- If the specified sensor wasn't enabled, flush returns -EINVAL. return 0 on
- success, negative errno code otherwise.</p>
-<h4 id="poll">poll()</h4>
-<pre> int (*poll)(struct sensors_poll_device_t *dev,
- sensors_event_t* data, int count);</pre>
-<p>Returns an array of sensor data. This function must block until events are
- available. It will return the number of events read on success, or -errno in
- case of an error.</p>
-<p>The number of events returned in data must be less or equal to the "count"
- argument. This function shall never return 0 (no event).</p>
+ <h2 id="what_are_“android_sensors”">What are Android sensors?</h2>
+ <p>Android sensors give applications access to a mobile device's underlying
+ physical sensors. They are data-providing virtual devices defined by the
+ implementation of <a
+ href="{@docRoot}devices/reference/sensors_8h.html">sensors.h</a>,
+ the sensor Hardware Abstraction Layer (HAL).</p>
+ <ul>
+ <li> Those virtual devices provide data coming from a set of physical sensors:
+ accelerometers, gyroscopes, magnetometers, barometer, humidity, pressure,
+ light, proximity and heart rate sensors… </li>
+ <li> Notably, camera, fingerprint sensor, microphone and touch screen are currently
+ not in the list of physical devices providing data through “Android sensors.”
+ They have their own reporting mechanism. </li>
+ <li> The separation is arbitrary, but in general, Android sensors provide lower
+ bandwidth data. For example, “100hz x 3 channels” for an accelerometer versus
+ “25hz x 8 MP x 3 channels” for a camera or “44kHz x 1 channel” for a
+ microphone. </li>
+ </ul>
+ <p>How the different physical sensors are connected to the system on chip
+ (SoC) is not defined by Android.</p>
+ <ul>
+ <li> Often, sensor chips are connected to the SoC through a <a href="sensor-stack.html#sensor_hub">sensor hub</a>, allowing some low-power monitoring and processing of the data. </li>
+ <li> Often, Inter-Integrated Circuit (I2C) or Serial Peripheral Interface
+ (SPI) is used as the transport mechanism. </li>
+ <li> To reduce power consumption, some architectures are hierarchical, with some
+ minimal processing being done in the application-specific integrated
+ circuit (ASIC - like motion detection on the accelerometer chip), and
+ more is done in a microcontroller (like step detection
+ in a sensor hub). </li>
+ <li> It is up to the device manufacturer to choose an architecture based on
+ accuracy, power, price and package-size characteristics. See <a
+ href="sensor-stack.html">Sensor stack</a> for more information. </li>
+ <li> Batching capabilities are an important consideration for power optimization.
+ See <a href="batching.html">Batching</a> for more information. </li>
+ </ul>
+ <p>Each Android sensor has a “type” representing how the sensor behaves and what
+ data it provides.</p>
+ <ul>
+ <li> The official Android <a href="sensor-types.html">Sensor types</a> are defined in <a href="{@docRoot}devices/reference/sensors_8h.html">sensors.h</a> under the names SENSOR_TYPE_…
+ <ul>
+ <li> The vast majority of sensors have an official sensor type. </li>
+ <li> Those types are documented in the Android SDK. </li>
+ <li> Behavior of sensors with those types are tested in the Android
+ Compatibility Test Suite (CTS). </li>
+ </ul>
+ </li>
+ <li> If a manufacturer integrates a new kind of sensor on an Android device, the
+ manufacturer can define its own temporary type to refer to it.
+ <ul>
+ <li> Those types are undocumented, so application developers are unlikely to use
+ them, either because they don’t know about them, or know that they are rarely
+ present (only on some devices from this specific manufacturer). </li>
+ <li> They are not tested by CTS. </li>
+ <li> Once Android defines an official sensor type for this kind of
+ sensor, manufacturers must stop using their own temporary type
+ and use the official type instead. This way, the sensor will be
+ used by more application developers. </li>
+ </ul>
+ </li>
+ <li> The list of all sensors present on the device is reported by the HAL
+ implementation.
+ <ul>
+ <li> There can be several sensors of the same type. For example, two proximity
+ sensors or two accelerometers. </li>
+ <li> The vast majority of applications request only a single sensor of a given type.
+ For example, an application requesting the default accelerometer will get the
+ first accelerometer in the list. </li>
+ <li> Sensors are often defined by <a href="suspend-mode.html#wake-up_sensors">wake-up</a> and <a href="suspend-mode.html#non-wake-up_sensors">non-wake-up</a> pairs, both sensors sharing the same type, but differing by their wake-up
+ characteristic. </li>
+ </ul>
+ </li>
+ </ul>
+<p>Android sensors provide data as a series of sensor events.</p>
+ <p> Each <a href="hal-interface.html#sensors_event_t">event</a> contains:</p>
+ <ul>
+ <li> a handle to the sensor that generated it </li>
+ <li> the timestamp at which the event was detected or measured </li>
+ <li> and some data </li>
+ </ul>
+ <p>The interpretation of the reported data depends on the sensor type.
+ See the <a href="sensor-types.html">sensor type</a> definitions for details on
+ what data is reported for each sensor type.</p>
+
+<h2 id="existing_documentation2">Existing documentation</h2>
+ <h3 id="targeted_at_developers">Targeted at developers</h3>
+ <ul>
+ <li> Overview
+ <ul>
+ <li><a href="https://developer.android.com/guide/topics/sensors/sensors_overview.html"> https://developer.android.com/guide/topics/sensors/sensors_overview.html </a></li>
+ </ul>
+ </li>
+ <li> SDK reference
+ <ul>
+ <li> <a href="https://developer.android.com/reference/android/hardware/SensorManager.html">https://developer.android.com/reference/android/hardware/SensorManager.html</a></li>
+ <li><a href="https://developer.android.com/reference/android/hardware/SensorEventListener.html"> https://developer.android.com/reference/android/hardware/SensorEventListener.html</a></li>
+ <li> <a href="https://developer.android.com/reference/android/hardware/SensorEvent.html">https://developer.android.com/reference/android/hardware/SensorEvent.html</a></li>
+ <li><a href="https://developer.android.com/reference/android/hardware/Sensor.html"> https://developer.android.com/reference/android/hardware/Sensor.html</a></li>
+ </ul>
+ </li>
+ <li> StackOverflow and tutorial websites
+ <ul>
+ <li> Because sensors documentation was sometimes lacking, developers resorted to Q&A
+ websites like StackOverflow to find answers. </li>
+ <li> Some tutorial websites exist as well, but do not cover the latest features like
+ batching, significant motion and game rotation vectors. </li>
+ <li> The answers over there are not always right, and show where more documentation
+ is needed. </li>
+ </ul>
+ </li>
+ </ul>
+<h3 id="targeted_at_manufacturers_public">Targeted at manufacturers</h3>
+ <ul>
+ <li> Overview
+ <ul>
+ <li>This <a href="{@docRoot}devices/sensors/index.html">Sensors</a>
+ page and its sub-pages. </li>
+ </ul>
+ </li>
+ <li> Hardware abstraction layer (HAL)
+ <ul>
+ <li> <a href="{@docRoot}devices/reference/sensors_8h_source.html">https://source.android.com/devices/reference/sensors_8h_source.html</a></li>
+ <li> Also known as “sensors.h” </li>
+ <li> The source of truth. First document to be updated when new features are
+ developed. </li>
+ </ul>
+ </li>
+ <li> Android CDD (Compatibility Definition Document)
+ <ul>
+ <li><a href="{@docRoot}compatibility/android-cdd.pdf">https://source.android.com/compatibility/android-cdd.pdf</a></li>
+ <li> See sections relative to sensors. </li>
+ <li> The CDD is lenient, so satisfying the CDD requirements is not enough to ensure
+ high quality sensors. </li>
+ </ul>
+ </li>
+ </ul>