Clay Murphy | d01c551 | 2014-09-18 18:28:04 -0700 | [diff] [blame] | 1 | page.title=Sensors |
Clay Murphy | 4ea104f | 2013-10-28 17:44:33 -0700 | [diff] [blame] | 2 | @jd:body |
| 3 | |
| 4 | <!-- |
Clay Murphy | d01c551 | 2014-09-18 18:28:04 -0700 | [diff] [blame] | 5 | Copyright 2014 The Android Open Source Project |
Clay Murphy | 4ea104f | 2013-10-28 17:44:33 -0700 | [diff] [blame] | 6 | |
| 7 | Licensed under the Apache License, Version 2.0 (the "License"); |
| 8 | you may not use this file except in compliance with the License. |
| 9 | You may obtain a copy of the License at |
| 10 | |
| 11 | http://www.apache.org/licenses/LICENSE-2.0 |
| 12 | |
| 13 | Unless required by applicable law or agreed to in writing, software |
| 14 | distributed under the License is distributed on an "AS IS" BASIS, |
| 15 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 16 | See the License for the specific language governing permissions and |
| 17 | limitations under the License. |
| 18 | --> |
| 19 | <div id="qv-wrapper"> |
| 20 | <div id="qv"> |
| 21 | <h2>In this document</h2> |
| 22 | <ol id="auto-toc"> |
| 23 | </ol> |
| 24 | </div> |
| 25 | </div> |
| 26 | |
Clay Murphy | d01c551 | 2014-09-18 18:28:04 -0700 | [diff] [blame] | 27 | <h2 id="what_are_“android_sensors”">What are Android sensors?</h2> |
| 28 | <p>Android sensors give applications access to a mobile device's underlying |
| 29 | physical sensors. They are data-providing virtual devices defined by the |
| 30 | implementation of <a |
| 31 | href="{@docRoot}devices/reference/sensors_8h.html">sensors.h</a>, |
| 32 | the sensor Hardware Abstraction Layer (HAL).</p> |
| 33 | <ul> |
| 34 | <li> Those virtual devices provide data coming from a set of physical sensors: |
| 35 | accelerometers, gyroscopes, magnetometers, barometer, humidity, pressure, |
| 36 | light, proximity and heart rate sensors… </li> |
| 37 | <li> Notably, camera, fingerprint sensor, microphone and touch screen are currently |
| 38 | not in the list of physical devices providing data through “Android sensors.” |
| 39 | They have their own reporting mechanism. </li> |
| 40 | <li> The separation is arbitrary, but in general, Android sensors provide lower |
| 41 | bandwidth data. For example, “100hz x 3 channels” for an accelerometer versus |
| 42 | “25hz x 8 MP x 3 channels” for a camera or “44kHz x 1 channel” for a |
| 43 | microphone. </li> |
| 44 | </ul> |
| 45 | <p>How the different physical sensors are connected to the system on chip |
| 46 | (SoC) is not defined by Android.</p> |
| 47 | <ul> |
| 48 | <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> |
| 49 | <li> Often, Inter-Integrated Circuit (I2C) or Serial Peripheral Interface |
| 50 | (SPI) is used as the transport mechanism. </li> |
| 51 | <li> To reduce power consumption, some architectures are hierarchical, with some |
| 52 | minimal processing being done in the application-specific integrated |
| 53 | circuit (ASIC - like motion detection on the accelerometer chip), and |
| 54 | more is done in a microcontroller (like step detection |
| 55 | in a sensor hub). </li> |
| 56 | <li> It is up to the device manufacturer to choose an architecture based on |
| 57 | accuracy, power, price and package-size characteristics. See <a |
| 58 | href="sensor-stack.html">Sensor stack</a> for more information. </li> |
| 59 | <li> Batching capabilities are an important consideration for power optimization. |
| 60 | See <a href="batching.html">Batching</a> for more information. </li> |
| 61 | </ul> |
| 62 | <p>Each Android sensor has a “type” representing how the sensor behaves and what |
| 63 | data it provides.</p> |
| 64 | <ul> |
| 65 | <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_… |
| 66 | <ul> |
| 67 | <li> The vast majority of sensors have an official sensor type. </li> |
| 68 | <li> Those types are documented in the Android SDK. </li> |
| 69 | <li> Behavior of sensors with those types are tested in the Android |
| 70 | Compatibility Test Suite (CTS). </li> |
| 71 | </ul> |
| 72 | </li> |
| 73 | <li> If a manufacturer integrates a new kind of sensor on an Android device, the |
| 74 | manufacturer can define its own temporary type to refer to it. |
| 75 | <ul> |
| 76 | <li> Those types are undocumented, so application developers are unlikely to use |
| 77 | them, either because they don’t know about them, or know that they are rarely |
| 78 | present (only on some devices from this specific manufacturer). </li> |
| 79 | <li> They are not tested by CTS. </li> |
| 80 | <li> Once Android defines an official sensor type for this kind of |
| 81 | sensor, manufacturers must stop using their own temporary type |
| 82 | and use the official type instead. This way, the sensor will be |
| 83 | used by more application developers. </li> |
| 84 | </ul> |
| 85 | </li> |
| 86 | <li> The list of all sensors present on the device is reported by the HAL |
| 87 | implementation. |
| 88 | <ul> |
| 89 | <li> There can be several sensors of the same type. For example, two proximity |
| 90 | sensors or two accelerometers. </li> |
| 91 | <li> The vast majority of applications request only a single sensor of a given type. |
| 92 | For example, an application requesting the default accelerometer will get the |
| 93 | first accelerometer in the list. </li> |
| 94 | <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 |
| 95 | characteristic. </li> |
| 96 | </ul> |
| 97 | </li> |
| 98 | </ul> |
| 99 | <p>Android sensors provide data as a series of sensor events.</p> |
| 100 | <p> Each <a href="hal-interface.html#sensors_event_t">event</a> contains:</p> |
| 101 | <ul> |
| 102 | <li> a handle to the sensor that generated it </li> |
| 103 | <li> the timestamp at which the event was detected or measured </li> |
| 104 | <li> and some data </li> |
| 105 | </ul> |
| 106 | <p>The interpretation of the reported data depends on the sensor type. |
| 107 | See the <a href="sensor-types.html">sensor type</a> definitions for details on |
| 108 | what data is reported for each sensor type.</p> |
| 109 | |
| 110 | <h2 id="existing_documentation2">Existing documentation</h2> |
| 111 | <h3 id="targeted_at_developers">Targeted at developers</h3> |
| 112 | <ul> |
| 113 | <li> Overview |
| 114 | <ul> |
| 115 | <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> |
| 116 | </ul> |
| 117 | </li> |
| 118 | <li> SDK reference |
| 119 | <ul> |
| 120 | <li> <a href="https://developer.android.com/reference/android/hardware/SensorManager.html">https://developer.android.com/reference/android/hardware/SensorManager.html</a></li> |
| 121 | <li><a href="https://developer.android.com/reference/android/hardware/SensorEventListener.html"> https://developer.android.com/reference/android/hardware/SensorEventListener.html</a></li> |
| 122 | <li> <a href="https://developer.android.com/reference/android/hardware/SensorEvent.html">https://developer.android.com/reference/android/hardware/SensorEvent.html</a></li> |
| 123 | <li><a href="https://developer.android.com/reference/android/hardware/Sensor.html"> https://developer.android.com/reference/android/hardware/Sensor.html</a></li> |
| 124 | </ul> |
| 125 | </li> |
| 126 | <li> StackOverflow and tutorial websites |
| 127 | <ul> |
| 128 | <li> Because sensors documentation was sometimes lacking, developers resorted to Q&A |
| 129 | websites like StackOverflow to find answers. </li> |
| 130 | <li> Some tutorial websites exist as well, but do not cover the latest features like |
| 131 | batching, significant motion and game rotation vectors. </li> |
| 132 | <li> The answers over there are not always right, and show where more documentation |
| 133 | is needed. </li> |
| 134 | </ul> |
| 135 | </li> |
| 136 | </ul> |
| 137 | <h3 id="targeted_at_manufacturers_public">Targeted at manufacturers</h3> |
| 138 | <ul> |
| 139 | <li> Overview |
| 140 | <ul> |
| 141 | <li>This <a href="{@docRoot}devices/sensors/index.html">Sensors</a> |
| 142 | page and its sub-pages. </li> |
| 143 | </ul> |
| 144 | </li> |
| 145 | <li> Hardware abstraction layer (HAL) |
| 146 | <ul> |
| 147 | <li> <a href="{@docRoot}devices/reference/sensors_8h_source.html">https://source.android.com/devices/reference/sensors_8h_source.html</a></li> |
| 148 | <li> Also known as “sensors.h” </li> |
| 149 | <li> The source of truth. First document to be updated when new features are |
| 150 | developed. </li> |
| 151 | </ul> |
| 152 | </li> |
| 153 | <li> Android CDD (Compatibility Definition Document) |
| 154 | <ul> |
| 155 | <li><a href="{@docRoot}compatibility/android-cdd.pdf">https://source.android.com/compatibility/android-cdd.pdf</a></li> |
| 156 | <li> See sections relative to sensors. </li> |
| 157 | <li> The CDD is lenient, so satisfying the CDD requirements is not enough to ensure |
| 158 | high quality sensors. </li> |
| 159 | </ul> |
| 160 | </li> |
| 161 | </ul> |