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