1 <html devsite> 2 <head> 3 <title>Sensor stack</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 26 <p>The figure below represents the Android sensor stack. Each component 27 communicates only with the components directly above and below it, though some 28 sensors can bypass the sensor hub when it is present. Control flows from the 29 applications down to the sensors, and data flows from the sensors up to the 30 applications.</p> 31 <img src="images/ape_fwk_sensors.png" alt="Layers and owners of the Android sensor stack" /> 32 <p class="img-caption"><strong>Figure 1.</strong> Layers of the Android sensor stack and their respective owners</p> 33 34 <h2 id="sdk">SDK</h2> 35 <p>Applications access sensors through the <a href="http://developer.android.com/reference/android/hardware/SensorManager.html">Sensors SDK (Software Development Kit) API</a>. The SDK contains functions to list available sensors and to register to a 36 sensor.</p> 37 <p>When registering to a sensor, the application specifies its preferred sampling 38 frequency and its latency requirements.</p> 39 <ul> 40 <li> For example, an application might register to the default accelerometer, 41 requesting events at 100Hz, and allowing events to be reported with a 1-second 42 latency. </li> 43 <li> The application will receive events from the accelerometer at a rate of at 44 least 100Hz, and possibly delayed up to 1 second. </li> 45 </ul> 46 <p>See the <a href="index.html#targeted_at_developers">developer documentation</a> for more information on the SDK.</p> 47 <h2 id="framework">Framework</h2> 48 <p>The framework is in charge of linking the several applications to the <a href="hal-interface.html">HAL</a>. The HAL itself is single-client. Without this multiplexing happening at the 49 framework level, only a single application could access each sensor at any 50 given time.</p> 51 <ul> 52 <li> When a first application registers to a sensor, the framework sends a request 53 to the HAL to activate the sensor. </li> 54 <li> When additional applications register to the same sensor, the framework takes 55 into account requirements from each application and sends the updated requested 56 parameters to the HAL. 57 <ul> 58 <li> The <a href="hal-interface.html#sampling_period_ns">sampling frequency</a> will be the maximum of the requested sampling frequencies, meaning some 59 applications will receive events at a frequency higher than the one they 60 requested. </li> 61 <li> The <a href="hal-interface.html#max_report_latency_ns">maximum reporting latency</a> will be the minimum of the requested ones. If one application requests one 62 sensor with a maximum reporting latency of 0, all applications will receive the 63 events from this sensor in continuous mode even if some requested the sensor 64 with a non-zero maximum reporting latency. See <a href="batching.html">Batching</a> for more details. </li> 65 </ul> 66 </li> 67 <li> When the last application registered to one sensor unregisters from it, the 68 frameworks sends a request to the HAL to deactivate the sensor so power is not 69 consumed unnecessarily. </li> 70 </ul> 71 <h3 id="impact_of_multiplexing">Impact of multiplexing</h3> 72 <p>This need for a multiplexing layer in the framework explains some design 73 decisions.</p> 74 <ul> 75 <li> When an application requests a specific sampling frequency, there is no 76 guarantee that events wont arrive at a faster rate. If another application 77 requested the same sensor at a faster rate, the first application will also 78 receive them at the fast rate. </li> 79 <li> The same lack of guarantee applies to the requested maximum reporting latency: 80 applications might receive events with much less latency than they requested. </li> 81 <li> Besides sampling frequency and maximum reporting latency, applications cannot 82 configure sensor parameters. 83 <ul> 84 <li> For example, imagine a physical sensor that can function both in high 85 accuracy and low power modes. </li> 86 <li> Only one of those two modes can be used on an Android device, because 87 otherwise, an application could request the high accuracy mode, and another one 88 a low power mode; there would be no way for the framework to satisfy both 89 applications. The framework must always be able to satisfy all its clients, so 90 this is not an option. </li> 91 </ul> 92 </li> 93 <li> There is no mechanism to send data down from the applications to the sensors or 94 their drivers. This ensures one application cannot modify the behavior of the 95 sensors, breaking other applications. </li> 96 </ul> 97 <h3 id="sensor_fusion">Sensor fusion</h3> 98 <p>The Android framework provides a default implementation for some composite 99 sensors. When a <a href="sensor-types.html#gyroscope">gyroscope</a>, an <a href="sensor-types.html#accelerometer">accelerometer</a> and a <a href="sensor-types.html#magnetic_field_sensor">magnetometer</a> are present on a device, but no <a href="sensor-types.html#rotation_vector">rotation vector</a>, <a href="sensor-types.html#gravity">gravity</a> and <a href="sensor-types.html#linear_acceleration">linear acceleration</a> sensors are present, the framework implements those sensors so applications 100 can still use them.</p> 101 <p>The default implementation does not have access to all the data that other 102 implementations have access to, and it must run on the SoC, so it is not as 103 accurate nor as power efficient as other implementations can be. As much as 104 possible, device manufacturers should define their own fused sensors (rotation 105 vector, gravity and linear acceleration, as well as newer composite sensors like 106 the <a href="sensor-types.html#game_rotation_vector">game rotation vector</a>) rather than rely on this default implementation. Device manufacturers can 107 also request sensor chip vendors to provide them with an implementation.</p> 108 <p>The default sensor fusion implementation is not being maintained and 109 might cause devices relying on it to fail CTS.</p> 110 <h3 id="under_the_hood">Under the Hood</h3> 111 <p>This section is provided as background information for those maintaining the 112 Android Open Source Project (AOSP) framework code. It is not relevant for 113 hardware manufacturers.</p> 114 <h4 id="jni">JNI</h4> 115 <p>The framework uses a Java Native Interface (JNI) associated with <a href="http://developer.android.com/reference/android/hardware/package-summary.html">android.hardware</a> and located in the <code>frameworks/base/core/jni/</code> directory. This code calls the 116 lower level native code to obtain access to the sensor hardware.</p> 117 <h4 id="native_framework">Native framework</h4> 118 <p>The native framework is defined in <code>frameworks/native/</code> and provides a native 119 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 120 sensor-specific services.</p> 121 <h4 id="binder_ipc">Binder IPC</h4> 122 <p>The Binder IPC proxies facilitate communication over process boundaries.</p> 123 <h2 id="hal">HAL</h2> 124 <p>The Sensors Hardware Abstraction Layer (HAL) API is the interface between the 125 hardware drivers and the Android framework. It consists of one HAL interface 126 sensors.h and one HAL implementation we refer to as sensors.cpp.</p> 127 <p>The interface is defined by Android and AOSP contributors, and the 128 implementation is provided by the manufacturer of the device.</p> 129 <p>The sensor HAL interface is located in <code>hardware/libhardware/include/hardware</code>. 130 See <a 131 href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/sensors.h">sensors.h</a> 132 for additional details.</p> 133 <h3 id="release_cycle">Release cycle</h3> 134 <p>The HAL implementation specifies what version of the HAL interface it 135 implements by setting <code>your_poll_device.common.version</code>. The existing HAL 136 interface versions are defined in sensors.h, and functionality is tied to those 137 versions.</p> 138 <p>The Android framework currently supports versions 1.0 and 1.3, but 1.0 will 139 soon not be supported anymore. This documentation describes the behavior of version 140 1.3, to which all devices should upgrade. For details on how to upgrade to 141 1.3, see <a href="versioning.html">HAL version deprecation</a>.</p> 142 <h2 id="kernel_driver">Kernel driver</h2> 143 <p>The sensor drivers interact with the physical devices. In some cases, the HAL 144 implementation and the drivers are the same software entity. In other cases, 145 the hardware integrator requests sensor chip manufacturers to provide the 146 drivers, but they are the ones writing the HAL implementation.</p> 147 <p>In all cases, HAL implementation and kernel drivers are the responsibility of 148 the hardware manufacturers, and Android does not provide preferred approaches to 149 write them.</p> 150 <h2 id="sensor_hub">Sensor hub</h2> 151 <p>The sensor stack of a device can optionally include a sensor hub, useful to 152 perform some low-level computation at low power while the SoC can be in a 153 suspend mode. For example, step counting or sensor fusion can be performed on 154 those chips. It is also a good place to implement sensor batching, adding 155 hardware FIFOs for the sensor events. See <a 156 href="batching.html">Batching</a> for more information.</p> 157 <p>How the sensor hub is materialized depends on the architecture. It is sometimes 158 a separate chip, and sometimes included on the same chip as the SoC. Important 159 characteristics of the sensor hub is that it should contain sufficient memory 160 for batching and consume very little power to enable implementation of the low 161 power Android sensors. Some sensor hubs contain a microcontroller for generic 162 computation, and hardware accelerators to enable very low power computation for 163 low power sensors.</p> 164 <p>How the sensor hub is architectured and how it communicates with the sensors 165 and the SoC (I2C bus, SPI bus, ) is not specified by Android, but it should aim 166 at minimizing overall power use.</p> 167 <p>One option that appears to have a significant impact on implementation 168 simplicity is having two interrupt lines going from the sensor hub to the SoC: 169 one for wake-up interrupts (for wake-up sensors), and the other for non-wake-up 170 interrupts (for non-wake-up sensors).</p> 171 <h2 id="sensors">Sensors</h2> 172 <p>Those are the physical MEMs chips making the measurements. In many cases, 173 several physical sensors are present on the same chip. For example, some chips 174 include an accelerometer, a gyroscope and a magnetometer. (Such chips are often 175 called 9-axis chips, as each sensor provides data over 3 axes.)</p> 176 <p>Some of those chips also contain some logic to perform usual computations such 177 as motion detection, step detection and 9-axis sensor fusion.</p> 178 <p>Although the CDD power and accuracy requirements and recommendations target the 179 Android sensor and not the physical sensors, those requirements impact the 180 choice of physical sensors. For example, the accuracy requirement on the game 181 rotation vector has implications on the required accuracy for the physical 182 gyroscope. It is up to the device manufacturer to derive the requirements for 183 physical sensors.</p> 184 185 </body> 186 </html> 187
