sensors.h revision 74279e3c23bd62c70d53098be91db85df5a68ece
1f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project/* 2a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * Copyright (C) 2012 The Android Open Source Project 3f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * 4f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * Licensed under the Apache License, Version 2.0 (the "License"); 5f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * you may not use this file except in compliance with the License. 6f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * You may obtain a copy of the License at 7f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * 8f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * http://www.apache.org/licenses/LICENSE-2.0 9f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * 10f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * Unless required by applicable law or agreed to in writing, software 11f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * distributed under the License is distributed on an "AS IS" BASIS, 12f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * See the License for the specific language governing permissions and 14f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * limitations under the License. 15f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project */ 16f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 17f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project#ifndef ANDROID_SENSORS_INTERFACE_H 18f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project#define ANDROID_SENSORS_INTERFACE_H 19f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 20f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project#include <stdint.h> 21f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project#include <sys/cdefs.h> 22f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project#include <sys/types.h> 23f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 24f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project#include <hardware/hardware.h> 2521b652f933b21aa37bd73364b486347fcc333d5cMike Lockwood#include <cutils/native_handle.h> 26f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 27f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project__BEGIN_DECLS 28f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 2956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/*****************************************************************************/ 3056f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 3156f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSORS_HEADER_VERSION 1 3256f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSORS_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) 3356f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSORS_DEVICE_API_VERSION_0_1 HARDWARE_DEVICE_API_VERSION_2(0, 1, SENSORS_HEADER_VERSION) 34a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian#define SENSORS_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION_2(1, 0, SENSORS_HEADER_VERSION) 3516671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian#define SENSORS_DEVICE_API_VERSION_1_1 HARDWARE_DEVICE_API_VERSION_2(1, 1, SENSORS_HEADER_VERSION) 36b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSORS_DEVICE_API_VERSION_1_2 HARDWARE_DEVICE_API_VERSION_2(1, 2, SENSORS_HEADER_VERSION) 3756f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 38f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project/** 39f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * The id of this module 40f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project */ 41f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project#define SENSORS_HARDWARE_MODULE_ID "sensors" 42f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 43f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project/** 44f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * Name of the sensors device to open 45f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project */ 46b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopian#define SENSORS_HARDWARE_POLL "poll" 47f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 48f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project/** 49f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * Handles must be higher than SENSORS_HANDLE_BASE and must be unique. 50f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * A Handle identifies a given sensors. The handle is used to activate 51f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * and/or deactivate sensors. 52f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * In this version of the API there can only be 256 handles. 53f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project */ 54f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project#define SENSORS_HANDLE_BASE 0 55f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project#define SENSORS_HANDLE_BITS 8 56f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project#define SENSORS_HANDLE_COUNT (1<<SENSORS_HANDLE_BITS) 57f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 58f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 59a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian/* 60a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * flags for (*batch)() 61a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * Availability: SENSORS_DEVICE_API_VERSION_1_0 62a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * see (*batch)() documentation for details 63a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian */ 64a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopianenum { 65a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian SENSORS_BATCH_DRY_RUN = 0x00000001, 66a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian SENSORS_BATCH_WAKE_UPON_FIFO_FULL = 0x00000002 67a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian}; 68a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 6916671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian/* 7016671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * what field for meta_data_event_t 7116671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian */ 7216671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopianenum { 7316671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian /* a previous flush operation has completed */ 74af32a8d59463ddf67154cb432da232cfb185e6bcMathias Agopian META_DATA_FLUSH_COMPLETE = 1, 75af32a8d59463ddf67154cb432da232cfb185e6bcMathias Agopian META_DATA_VERSION /* always last, leave auto-assigned */ 7616671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian}; 7716671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian 78b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella/* 79b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * The permission to use for body sensors (like heart rate monitors). 80b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * See sensor types for more details on what sensors should require this 81b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * permission. 82b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella */ 83b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_PERMISSION_BODY_SENSORS "android.permission.BODY_SENSORS" 84b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella 85f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project/** 8656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * Definition of the axis used by the sensor HAL API 87f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * 88f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * This API is relative to the screen of the device in its default orientation, 89f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * that is, if the device can be used in portrait or landscape, this API 90f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * is only relative to the NATURAL orientation of the screen. In other words, 91f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * the axis are not swapped when the device's screen orientation changes. 92f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * Higher level services /may/ perform this transformation. 93f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * 94f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * x<0 x>0 95f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * ^ 96f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * | 97f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * +-----------+--> y>0 98f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * | | 99f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * | | 100f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * | | 101f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * | | / z<0 102f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * | | / 103f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * | | / 104f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * O-----------+/ 105f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * |[] [ ] []/ 106f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * +----------/+ y<0 107f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * / 108f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * / 109f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * |/ z>0 (toward the sky) 110f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * 111f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * O: Origin (x=0,y=0,z=0) 112f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * 11356f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian */ 11456f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 115a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian/* 116a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * Interaction with suspend mode 117a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 118a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * Unless otherwise noted, an enabled sensor shall not prevent the 119a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * SoC to go into suspend mode. It is the responsibility of applications 120a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * to keep a partial wake-lock should they wish to receive sensor 121a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * events while the screen is off. While in suspend mode, and unless 12228f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * otherwise noted (batch mode, sensor particularities, ...), enabled sensors' 12328f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * events are lost. 124a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 125a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * Note that conceptually, the sensor itself is not de-activated while in 126a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * suspend mode -- it's just that the data it returns are lost. As soon as 127a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * the SoC gets out of suspend mode, operations resume as usual. Of course, 128a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * in practice sensors shall be disabled while in suspend mode to 129a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * save power, unless batch mode is active, in which case they must 130a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * continue fill their internal FIFO (see the documentation of batch() to 131a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * learn how suspend interacts with batch mode). 132a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 13328f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * In batch mode, and only when the flag SENSORS_BATCH_WAKE_UPON_FIFO_FULL is 1341144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * set and supported, the specified sensor must be able to wake-up the SoC and 1351144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * be able to buffer at least 10 seconds worth of the requested sensor events. 136a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 137a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * There are notable exceptions to this behavior, which are sensor-dependent 138a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * (see sensor types definitions below) 139a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 140a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 141a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * The sensor type documentation below specifies the wake-up behavior of 142a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * each sensor: 143a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up: yes this sensor must wake-up the SoC to deliver events 144a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up: no this sensor shall not wake-up the SoC, events are dropped 145a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 146a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian */ 147a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 148a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian/* 149a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * Sensor type 150a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 151a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * Each sensor has a type which defines what this sensor measures and how 152a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * measures are reported. All types are defined below. 1531599ec675579eaf8f8e7f79fc03648b9d838f475Mathias Agopian * 1541599ec675579eaf8f8e7f79fc03648b9d838f475Mathias Agopian * Device manufacturers (OEMs) can define their own sensor types, for 1551599ec675579eaf8f8e7f79fc03648b9d838f475Mathias Agopian * their private use by applications or services provided by them. Such 1561599ec675579eaf8f8e7f79fc03648b9d838f475Mathias Agopian * sensor types are specific to an OEM and can't be exposed in the SDK. 1571599ec675579eaf8f8e7f79fc03648b9d838f475Mathias Agopian * These types must start at SENSOR_TYPE_DEVICE_PRIVATE_BASE. 158b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * 159b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * All sensors defined outside of the device private range must correspond to 160b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * a type defined in this file, and must satisfy the characteristics listed in 161b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * the description of the sensor type. 162b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * 163b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * Starting with version SENSORS_DEVICE_API_VERSION_1_2, each sensor also 164b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * has a stringType. 165b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * - StringType of sensors inside of the device private range MUST be prefixed 166b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * by the sensor provider's or OEM reverse domain name. In particular, they 167b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * cannot use the "android.sensor" prefix. 168b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * - StringType of sensors outside of the device private range MUST correspond 169b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * to the one defined in this file (starting with "android.sensor"). 170b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * For example, accelerometers must have 171b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * type=SENSOR_TYPE_ACCELEROMETER and 172b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * stringType=SENSOR_STRING_TYPE_ACCELEROMETER 173b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * 174b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * When android introduces a new sensor type that can replace an OEM-defined 175b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * sensor type, the OEM must use the official sensor type and stringType on 176b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * versions of the HAL that support this new official sensor type. 177b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * 178b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * Example (made up): Suppose Google's Glass team wants to surface a sensor 179b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * detecting that Glass is on a head. 180b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * - Such a sensor is not officially supported in android KitKat 181b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * - Glass devices launching on KitKat can implement a sensor with 182b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * type = 0x10001 and stringType = "com.google.glass.onheaddetector" 183b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * - In L android release, if android decides to define 184b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * SENSOR_TYPE_ON_HEAD_DETECTOR and STRING_SENSOR_TYPE_ON_HEAD_DETECTOR, 185b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * those types should replace the Glass-team-specific types in all future 186b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * launches. 187b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * - When launching glass on the L release, Google should now use the official 188b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * type (SENSOR_TYPE_ON_HEAD_DETECTOR) and stringType. 189b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * - This way, all applications can now use this sensor. 1901599ec675579eaf8f8e7f79fc03648b9d838f475Mathias Agopian */ 1911599ec675579eaf8f8e7f79fc03648b9d838f475Mathias Agopian 1921599ec675579eaf8f8e7f79fc03648b9d838f475Mathias Agopian/* 1931599ec675579eaf8f8e7f79fc03648b9d838f475Mathias Agopian * Base for device manufacturers private sensor types. 1941599ec675579eaf8f8e7f79fc03648b9d838f475Mathias Agopian * These sensor types can't be exposed in the SDK. 195a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian */ 1961599ec675579eaf8f8e7f79fc03648b9d838f475Mathias Agopian#define SENSOR_TYPE_DEVICE_PRIVATE_BASE 0x10000 197a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 198a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian/* 199a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * Sensor fusion and virtual sensors 200a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 201a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * Many sensor types are or can be implemented as virtual sensors from 202a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * physical sensors on the device. For instance the rotation vector sensor, 2032f276f555064a77fa449a3ac21aa06ea3c1b45caMathias Agopian * orientation sensor, step-detector, step-counter, etc... 204a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 205a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * From the point of view of this API these virtual sensors MUST appear as 206a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * real, individual sensors. It is the responsibility of the driver and HAL 207a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * to make sure this is the case. 208a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 209a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * In particular, all sensors must be able to function concurrently. 210a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * For example, if defining both an accelerometer and a step counter, 211a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * then both must be able to work concurrently. 212a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian */ 213a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 214a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian/* 215a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * Trigger modes 216a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 217a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * Sensors can report events in different ways called trigger modes, 218a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * each sensor type has one and only one trigger mode associated to it. 219a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * Currently there are four trigger modes defined: 220a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 221a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * continuous: events are reported at a constant rate defined by setDelay(). 222a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * eg: accelerometers, gyroscopes. 223a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * on-change: events are reported only if the sensor's value has changed. 224a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * setDelay() is used to set a lower limit to the reporting 225a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * period (minimum time between two events). 226a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * The HAL must return an event immediately when an on-change 227a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * sensor is activated. 228a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * eg: proximity, light sensors 229ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * one-shot: upon detection of an event, the sensor deactivates itself and 230ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * then sends a single event. Order matters to avoid race 231ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * conditions. No other event is sent until the sensor get 232ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * reactivated. setDelay() is ignored. 233a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * eg: significant motion sensor 234a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * special: see details in the sensor type specification below 235a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 236a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian */ 23756f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 23816671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian 23916671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian/* 24016671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * SENSOR_TYPE_META_DATA 24116671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * trigger-mode: n/a 24216671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * wake-up sensor: n/a 24316671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * 24416671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * NO SENSOR OF THAT TYPE MUST BE RETURNED (*get_sensors_list)() 24516671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * 24616671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * SENSOR_TYPE_META_DATA is a special token used to populate the 24716671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * sensors_meta_data_event structure. It doesn't correspond to a physical 24816671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * sensor. sensors_meta_data_event are special, they exist only inside 24916671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * the HAL and are generated spontaneously, as opposed to be related to 25016671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * a physical sensor. 25116671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * 252af32a8d59463ddf67154cb432da232cfb185e6bcMathias Agopian * sensors_meta_data_event_t.version must be META_DATA_VERSION 253af32a8d59463ddf67154cb432da232cfb185e6bcMathias Agopian * sensors_meta_data_event_t.sensor must be 0 254af32a8d59463ddf67154cb432da232cfb185e6bcMathias Agopian * sensors_meta_data_event_t.type must be SENSOR_TYPE_META_DATA 255af32a8d59463ddf67154cb432da232cfb185e6bcMathias Agopian * sensors_meta_data_event_t.reserved must be 0 256af32a8d59463ddf67154cb432da232cfb185e6bcMathias Agopian * sensors_meta_data_event_t.timestamp must be 0 25716671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * 25816671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * The payload is a meta_data_event_t, where: 25916671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * meta_data_event_t.what can take the following values: 26016671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * 26116671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * META_DATA_FLUSH_COMPLETE 26216671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * This event indicates that a previous (*flush)() call has completed for the sensor 26316671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * handle specified in meta_data_event_t.sensor. 26416671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * see (*flush)() for more details 26516671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * 26616671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * All other values for meta_data_event_t.what are reserved and 26716671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * must not be used. 26816671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * 26916671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian */ 270b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_TYPE_META_DATA (0) 27116671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian 27256f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/* 27356f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * SENSOR_TYPE_ACCELEROMETER 274a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger-mode: continuous 275a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up sensor: no 27656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * 27756f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * All values are in SI units (m/s^2) and measure the acceleration of the 27856f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * device minus the force of gravity. 27956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * 28056f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * Acceleration sensors return sensor events for all 3 axes at a constant 28156f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * rate defined by setDelay(). 28256f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * 28356f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * x: Acceleration on the x-axis 28456f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * y: Acceleration on the y-axis 28556f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * z: Acceleration on the z-axis 28656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * 28756f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * Note that the readings from the accelerometer include the acceleration 28856f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * due to gravity (which is opposite to the direction of the gravity vector). 28956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * 29056f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * Examples: 29156f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * The norm of <x, y, z> should be close to 0 when in free fall. 29256f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * 29356f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * When the device lies flat on a table and is pushed on its left side 29456f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * toward the right, the x acceleration value is positive. 29556f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * 29656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * When the device lies flat on a table, the acceleration value is +9.81, 29756f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * which correspond to the acceleration of the device (0 m/s^2) minus the 29856f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * force of gravity (-9.81 m/s^2). 29956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * 30056f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * When the device lies flat on a table and is pushed toward the sky, the 30156f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * acceleration value is greater than +9.81, which correspond to the 30256f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * acceleration of the device (+A m/s^2) minus the force of 30356f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * gravity (-9.81 m/s^2). 30456f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian */ 30556f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_TYPE_ACCELEROMETER (1) 306b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_ACCELEROMETER "android.sensor.accelerometer" 30756f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 30856f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/* 30956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * SENSOR_TYPE_GEOMAGNETIC_FIELD 310a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger-mode: continuous 311a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up sensor: no 312f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * 31356f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * All values are in micro-Tesla (uT) and measure the geomagnetic 31456f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * field in the X, Y and Z axis. 31556f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * 31656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * Returned values include calibration mechanisms such that the vector is 31756f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * aligned with the magnetic declination and heading of the earth's 31856f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * geomagnetic field. 31956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * 32056f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * Magnetic Field sensors return sensor events for all 3 axes at a constant 32156f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * rate defined by setDelay(). 32256f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian */ 32356f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_TYPE_GEOMAGNETIC_FIELD (2) 32456f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_TYPE_MAGNETIC_FIELD SENSOR_TYPE_GEOMAGNETIC_FIELD 325b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_MAGNETIC_FIELD "android.sensor.magnetic_field" 32656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 32756f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/* 328e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * SENSOR_TYPE_ORIENTATION 329a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger-mode: continuous 330a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up sensor: no 331f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * 332f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * All values are angles in degrees. 333f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * 33466a4095ca0ecfe89b10abe5402617450f57759cdMathias Agopian * Orientation sensors return sensor events for all 3 axes at a constant 33566a4095ca0ecfe89b10abe5402617450f57759cdMathias Agopian * rate defined by setDelay(). 33666a4095ca0ecfe89b10abe5402617450f57759cdMathias Agopian * 337f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * azimuth: angle between the magnetic north direction and the Y axis, around 338f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * the Z axis (0<=azimuth<360). 339f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * 0=North, 90=East, 180=South, 270=West 340f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * 341f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * pitch: Rotation around X axis (-180<=pitch<=180), with positive values when 342f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * the z-axis moves toward the y-axis. 343f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * 344f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * roll: Rotation around Y axis (-90<=roll<=90), with positive values when 34519ea59f86521c1b3ef72999e3cccc47b48c445adMathias Agopian * the x-axis moves towards the z-axis. 34619ea59f86521c1b3ef72999e3cccc47b48c445adMathias Agopian * 34719ea59f86521c1b3ef72999e3cccc47b48c445adMathias Agopian * Note: For historical reasons the roll angle is positive in the clockwise 34819ea59f86521c1b3ef72999e3cccc47b48c445adMathias Agopian * direction (mathematically speaking, it should be positive in the 34919ea59f86521c1b3ef72999e3cccc47b48c445adMathias Agopian * counter-clockwise direction): 35019ea59f86521c1b3ef72999e3cccc47b48c445adMathias Agopian * 35119ea59f86521c1b3ef72999e3cccc47b48c445adMathias Agopian * Z 35219ea59f86521c1b3ef72999e3cccc47b48c445adMathias Agopian * ^ 35319ea59f86521c1b3ef72999e3cccc47b48c445adMathias Agopian * (+roll) .--> | 35419ea59f86521c1b3ef72999e3cccc47b48c445adMathias Agopian * / | 35519ea59f86521c1b3ef72999e3cccc47b48c445adMathias Agopian * | | roll: rotation around Y axis 35619ea59f86521c1b3ef72999e3cccc47b48c445adMathias Agopian * X <-------(.) 35719ea59f86521c1b3ef72999e3cccc47b48c445adMathias Agopian * Y 35819ea59f86521c1b3ef72999e3cccc47b48c445adMathias Agopian * note that +Y == -roll 35919ea59f86521c1b3ef72999e3cccc47b48c445adMathias Agopian * 36019ea59f86521c1b3ef72999e3cccc47b48c445adMathias Agopian * 36119ea59f86521c1b3ef72999e3cccc47b48c445adMathias Agopian * 362f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * Note: This definition is different from yaw, pitch and roll used in aviation 363f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * where the X axis is along the long side of the plane (tail to nose). 36456f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian */ 36556f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_TYPE_ORIENTATION (3) 366b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_ORIENTATION "android.sensor.orientation" 36756f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 36856f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/* 369e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * SENSOR_TYPE_GYROSCOPE 370a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger-mode: continuous 371a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up sensor: no 372e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * 373b01a043df41e987321f6c01930ac306befb1d3dcKevin Powell * All values are in radians/second and measure the rate of rotation 374b01a043df41e987321f6c01930ac306befb1d3dcKevin Powell * around the X, Y and Z axis. The coordinate system is the same as is 375c04e5f68905127ae4c1a0c17d225db9cebe66a07Mathias Agopian * used for the acceleration sensor. Rotation is positive in the 376c04e5f68905127ae4c1a0c17d225db9cebe66a07Mathias Agopian * counter-clockwise direction (right-hand rule). That is, an observer 377c04e5f68905127ae4c1a0c17d225db9cebe66a07Mathias Agopian * looking from some positive location on the x, y or z axis at a device 378c04e5f68905127ae4c1a0c17d225db9cebe66a07Mathias Agopian * positioned on the origin would report positive rotation if the device 379c04e5f68905127ae4c1a0c17d225db9cebe66a07Mathias Agopian * appeared to be rotating counter clockwise. Note that this is the 380c04e5f68905127ae4c1a0c17d225db9cebe66a07Mathias Agopian * standard mathematical definition of positive rotation and does not agree 381c04e5f68905127ae4c1a0c17d225db9cebe66a07Mathias Agopian * with the definition of roll given earlier. 382c04e5f68905127ae4c1a0c17d225db9cebe66a07Mathias Agopian * The range should at least be 17.45 rad/s (ie: ~1000 deg/s). 383b01a043df41e987321f6c01930ac306befb1d3dcKevin Powell * 38456f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * automatic gyro-drift compensation is allowed but not required. 38556f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian */ 38656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_TYPE_GYROSCOPE (4) 387b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_GYROSCOPE "android.sensor.gyroscope" 38856f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 38956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/* 390e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * SENSOR_TYPE_LIGHT 391a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger-mode: on-change 392a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up sensor: no 393a2414316075dde4ca5c1393c662f224b36dd3fdcMike Lockwood * 394a2414316075dde4ca5c1393c662f224b36dd3fdcMike Lockwood * The light sensor value is returned in SI lux units. 39556f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian */ 39656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_TYPE_LIGHT (5) 397b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_LIGHT "android.sensor.light" 39856f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 39956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/* 400e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * SENSOR_TYPE_PRESSURE 401a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger-mode: continuous 402a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up sensor: no 4031832f55760fff86d00b5d808b3da8f1e55a889e5Mathias Agopian * 404e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * The pressure sensor return the athmospheric pressure in hectopascal (hPa) 40556f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian */ 40656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_TYPE_PRESSURE (6) 407b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_PRESSURE "android.sensor.pressure" 40856f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 40956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/* SENSOR_TYPE_TEMPERATURE is deprecated in the HAL */ 41056f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_TYPE_TEMPERATURE (7) 411b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_TEMPERATURE "android.sensor.temperature" 41256f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 41356f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/* 41456f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * SENSOR_TYPE_PROXIMITY 415a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger-mode: on-change 416a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up sensor: yes 4171832f55760fff86d00b5d808b3da8f1e55a889e5Mathias Agopian * 41856f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * The distance value is measured in centimeters. Note that some proximity 41956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * sensors only support a binary "close" or "far" measurement. In this case, 42056f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * the sensor should report its maxRange value in the "far" state and a value 42156f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * less than maxRange in the "near" state. 42256f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian */ 42356f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_TYPE_PROXIMITY (8) 424b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_PROXIMITY "android.sensor.proximity" 42556f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 42656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/* 427e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * SENSOR_TYPE_GRAVITY 428a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger-mode: continuous 429a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up sensor: no 4303120b58768ff6aad5ad169b9c18f962ef6abb3c5Makarand Karvekar * 431e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * A gravity output indicates the direction of and magnitude of gravity in 432e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * the devices's coordinates. On Earth, the magnitude is 9.8 m/s^2. 433e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * Units are m/s^2. The coordinate system is the same as is used for the 434e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * acceleration sensor. When the device is at rest, the output of the 435e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * gravity sensor should be identical to that of the accelerometer. 43656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian */ 43756f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_TYPE_GRAVITY (9) 438b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_GRAVITY "android.sensor.gravity" 43956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 44056f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/* 441e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * SENSOR_TYPE_LINEAR_ACCELERATION 442a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger-mode: continuous 443a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up sensor: no 4443120b58768ff6aad5ad169b9c18f962ef6abb3c5Makarand Karvekar * 445e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * Indicates the linear acceleration of the device in device coordinates, 446e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * not including gravity. 447b01a043df41e987321f6c01930ac306befb1d3dcKevin Powell * 44856f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * The output is conceptually: 44956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * output of TYPE_ACCELERATION - output of TYPE_GRAVITY 45042b743c85597e982ff1122b972862396f131db34Mathias Agopian * 45156f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * Readings on all axes should be close to 0 when device lies on a table. 45256f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * Units are m/s^2. 45356f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * The coordinate system is the same as is used for the acceleration sensor. 45456f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian */ 45556f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_TYPE_LINEAR_ACCELERATION (10) 456b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_LINEAR_ACCELERATION "android.sensor.linear_acceleration" 45756f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 45856f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 45956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/* 460e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * SENSOR_TYPE_ROTATION_VECTOR 461a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger-mode: continuous 462a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up sensor: no 46342b743c85597e982ff1122b972862396f131db34Mathias Agopian * 46428f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * The rotation vector symbolizes the orientation of the device relative to the 46528f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * East-North-Up coordinates frame. It is usually obtained by integration of 46628f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * accelerometer, gyroscope and magnetometer readings. 467d93ff971bd507e92ac81c149079906d2123795afMathias Agopian * 46828f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * The East-North-Up coordinate system is defined as a direct orthonormal basis 46928f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * where: 47028f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * - X points east and is tangential to the ground. 47128f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * - Y points north and is tangential to the ground. 472d93ff971bd507e92ac81c149079906d2123795afMathias Agopian * - Z points towards the sky and is perpendicular to the ground. 473d93ff971bd507e92ac81c149079906d2123795afMathias Agopian * 47428f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * The orientation of the phone is represented by the rotation necessary to 47528f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * align the East-North-Up coordinates with the phone's coordinates. That is, 47628f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * applying the rotation to the world frame (X,Y,Z) would align them with the 47728f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * phone coordinates (x,y,z). 478d93ff971bd507e92ac81c149079906d2123795afMathias Agopian * 47928f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * The rotation can be seen as rotating the phone by an angle theta around 48028f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * an axis rot_axis to go from the reference (East-North-Up aligned) device 48128f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * orientation to the current device orientation. 48242b743c85597e982ff1122b972862396f131db34Mathias Agopian * 48328f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * The rotation is encoded as the 4 (reordered) components of a unit quaternion: 48428f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * sensors_event_t.data[0] = rot_axis.x*sin(theta/2) 48528f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * sensors_event_t.data[1] = rot_axis.y*sin(theta/2) 48628f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * sensors_event_t.data[2] = rot_axis.z*sin(theta/2) 48728f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * sensors_event_t.data[3] = cos(theta/2) 48828f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * where 48928f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * - rot_axis.x,y,z are the North-East-Up coordinates of a unit length vector 49028f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * representing the rotation axis 49128f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * - theta is the rotation angle 49228f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * 49328f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * The quaternion must be of norm 1 (it is a unit quaternion). Failure to ensure 49428f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * this will cause erratic client behaviour. 495ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * 496ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * In addition, this sensor reports an estimated heading accuracy. 49728f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * sensors_event_t.data[4] = estimated_accuracy (in radians) 498ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * The heading error must be less than estimated_accuracy 95% of the time 499ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * 500ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * This sensor must use a gyroscope and an accelerometer as main orientation 501ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * change input. 502ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * 503ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * This sensor can also include magnetometer input to make up for gyro drift, 504ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * but it cannot be implemented using only a magnetometer. 50556f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian */ 50656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_TYPE_ROTATION_VECTOR (11) 507b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_ROTATION_VECTOR "android.sensor.rotation_vector" 50856f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 50956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/* 510e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * SENSOR_TYPE_RELATIVE_HUMIDITY 511a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger-mode: on-change 512a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up sensor: no 513d2ed15a6b81a9a2fd95c1a565f72796869545115Urs Fleisch * 514d2ed15a6b81a9a2fd95c1a565f72796869545115Urs Fleisch * A relative humidity sensor measures relative ambient air humidity and 515d2ed15a6b81a9a2fd95c1a565f72796869545115Urs Fleisch * returns a value in percent. 51656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian */ 51756f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_TYPE_RELATIVE_HUMIDITY (12) 518b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_RELATIVE_HUMIDITY "android.sensor.relative_humidity" 51956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 52056f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/* 521e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * SENSOR_TYPE_AMBIENT_TEMPERATURE 522a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger-mode: on-change 523a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up sensor: no 52454f9dd032dfbd336ca90e3b44047373f0297c3a5Mathias Agopian * 52554f9dd032dfbd336ca90e3b44047373f0297c3a5Mathias Agopian * The ambient (room) temperature in degree Celsius. 52656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian */ 52756f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_TYPE_AMBIENT_TEMPERATURE (13) 528b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_AMBIENT_TEMPERATURE "android.sensor.ambient_temperature" 52956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 53056f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/* 53156f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED 532a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger-mode: continuous 533a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up sensor: no 53456f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * 535ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Similar to SENSOR_TYPE_MAGNETIC_FIELD, but the hard iron calibration is 536ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * reported separately instead of being included in the measurement. 537ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Factory calibration and temperature compensation should still be applied to 538ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * the "uncalibrated" measurement. 539ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Separating away the hard iron calibration estimation allows the system to 540ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * better recover from bad hard iron estimation. 54154f9dd032dfbd336ca90e3b44047373f0297c3a5Mathias Agopian * 542ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * All values are in micro-Tesla (uT) and measure the ambient magnetic 543ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * field in the X, Y and Z axis. Assumptions that the the magnetic field 544ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * is due to the Earth's poles should be avoided. 545ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * 546ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * The uncalibrated_magnetic event contains 547ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * - 3 fields for uncalibrated measurement: x_uncalib, y_uncalib, z_uncalib. 548ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Each is a component of the measured magnetic field, with soft iron 549ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * and temperature compensation applied, but not hard iron calibration. 550ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * These values should be continuous (no re-calibration should cause a jump). 551ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * - 3 fields for hard iron bias estimates: x_bias, y_bias, z_bias. 552ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Each field is a component of the estimated hard iron calibration. 5537a813e844252612cd8f7fa4e391825477d8b63d0Etienne Le Grand * They represent the offsets to apply to the calibrated readings to obtain 5547a813e844252612cd8f7fa4e391825477d8b63d0Etienne Le Grand * uncalibrated readings (x_uncalib ~= x_calibrated + x_bias) 555ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * These values are expected to jump as soon as the estimate of the hard iron 5567a813e844252612cd8f7fa4e391825477d8b63d0Etienne Le Grand * changes, and they should be stable the rest of the time. 5571144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * 5581144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * If this sensor is present, then the corresponding 5591144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * SENSOR_TYPE_MAGNETIC_FIELD must be present and both must return the 5601144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * same sensor_t::name and sensor_t::vendor. 561ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * 562f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * Minimum filtering should be applied to this sensor. In particular, low pass 563f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * filters should be avoided. 564f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * 565ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * See SENSOR_TYPE_MAGNETIC_FIELD for more information 566f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project */ 56756f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED (14) 568b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_MAGNETIC_FIELD_UNCALIBRATED "android.sensor.magnetic_field_uncalibrated" 569b01a043df41e987321f6c01930ac306befb1d3dcKevin Powell 57056f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/* 57156f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * SENSOR_TYPE_GAME_ROTATION_VECTOR 572a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger-mode: continuous 573a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up sensor: no 57456f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * 575ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Similar to SENSOR_TYPE_ROTATION_VECTOR, but not using the geomagnetic 576ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * field. Therefore the Y axis doesn't point north, but instead to some other 577ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * reference. That reference is allowed to drift by the same order of 578ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * magnitude than the gyroscope drift around the Z axis. 57956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * 580ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * This sensor does not report an estimated heading accuracy: 58128f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * sensors_event_t.data[4] is reserved and should be set to 0 582ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * 583ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * In the ideal case, a phone rotated and returning to the same real-world 584ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * orientation should report the same game rotation vector 585ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * (without using the earth's geomagnetic field). 586ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * 587ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * This sensor must be based on a gyroscope. It cannot be implemented using 588ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * a magnetometer. 58956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * 59056f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * see SENSOR_TYPE_ROTATION_VECTOR for more details 59156f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian */ 59256f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_TYPE_GAME_ROTATION_VECTOR (15) 593b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_GAME_ROTATION_VECTOR "android.sensor.game_rotation_vector" 59456f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 59556f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/* 59656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * SENSOR_TYPE_GYROSCOPE_UNCALIBRATED 597a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger-mode: continuous 598a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up sensor: no 59956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * 60056f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * All values are in radians/second and measure the rate of rotation 6011144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * around the X, Y and Z axis. An estimation of the drift on each axis is 6021144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * reported as well. 6031144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * 6041144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * No gyro-drift compensation shall be performed. 6051144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * Factory calibration and temperature compensation should still be applied 6061144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * to the rate of rotation (angular speeds). 6071144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * 6081144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * The coordinate system is the same as is 60956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * used for the acceleration sensor. Rotation is positive in the 61056f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * counter-clockwise direction (right-hand rule). That is, an observer 61156f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * looking from some positive location on the x, y or z axis at a device 61256f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * positioned on the origin would report positive rotation if the device 61356f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * appeared to be rotating counter clockwise. Note that this is the 61456f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * standard mathematical definition of positive rotation and does not agree 61556f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * with the definition of roll given earlier. 61656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * The range should at least be 17.45 rad/s (ie: ~1000 deg/s). 61756f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * 618ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Content of an uncalibrated_gyro event: (units are rad/sec) 619ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * x_uncalib : angular speed (w/o drift compensation) around the X axis 620ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * y_uncalib : angular speed (w/o drift compensation) around the Y axis 621ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * z_uncalib : angular speed (w/o drift compensation) around the Z axis 622ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * x_bias : estimated drift around X axis in rad/s 623ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * y_bias : estimated drift around Y axis in rad/s 624ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * z_bias : estimated drift around Z axis in rad/s 6251144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * 6261144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * IMPLEMENTATION NOTES: 6271144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * 6281144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * If the implementation is not able to estimate the drift, then this 6291144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * sensor MUST NOT be reported by this HAL. Instead, the regular 6301144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * SENSOR_TYPE_GYROSCOPE is used without drift compensation. 6311144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * 6321144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * If this sensor is present, then the corresponding 6331144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * SENSOR_TYPE_GYROSCOPE must be present and both must return the 6341144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * same sensor_t::name and sensor_t::vendor. 63556f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian */ 63656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_TYPE_GYROSCOPE_UNCALIBRATED (16) 637b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_GYROSCOPE_UNCALIBRATED "android.sensor.gyroscope_uncalibrated" 63856f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 639a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 640a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian/* 641a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * SENSOR_TYPE_SIGNIFICANT_MOTION 642a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger-mode: one-shot 643a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up sensor: yes 644a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 645a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * A sensor of this type triggers an event each time significant motion 646a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * is detected and automatically disables itself. 647a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * The only allowed value to return is 1.0. 648a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 6491461f28f503d75c6eda29ec9bbd5db33b44f65feEtienne Le Grand * A significant motion is a motion that might lead to a change in the user 6501461f28f503d75c6eda29ec9bbd5db33b44f65feEtienne Le Grand * location. 6511461f28f503d75c6eda29ec9bbd5db33b44f65feEtienne Le Grand * Examples of such motions are: 6521461f28f503d75c6eda29ec9bbd5db33b44f65feEtienne Le Grand * walking, biking, sitting in a moving car, coach or train. 6531461f28f503d75c6eda29ec9bbd5db33b44f65feEtienne Le Grand * Examples of situations that should not trigger significant motion: 6541461f28f503d75c6eda29ec9bbd5db33b44f65feEtienne Le Grand * - phone in pocket and person is not moving 6551461f28f503d75c6eda29ec9bbd5db33b44f65feEtienne Le Grand * - phone is on a table, even if the table shakes a bit due to nearby traffic 6561461f28f503d75c6eda29ec9bbd5db33b44f65feEtienne Le Grand * or washing machine 6571461f28f503d75c6eda29ec9bbd5db33b44f65feEtienne Le Grand * 6581461f28f503d75c6eda29ec9bbd5db33b44f65feEtienne Le Grand * A note on false positive / false negative / power consumption tradeoff 6591461f28f503d75c6eda29ec9bbd5db33b44f65feEtienne Le Grand * - The goal of this sensor is to save power. 6601461f28f503d75c6eda29ec9bbd5db33b44f65feEtienne Le Grand * - Triggering an event when the user is not moving (false positive) is costly 6611461f28f503d75c6eda29ec9bbd5db33b44f65feEtienne Le Grand * in terms of power, so it should be avoided. 6621461f28f503d75c6eda29ec9bbd5db33b44f65feEtienne Le Grand * - Not triggering an event when the user is moving (false negative) is 6632e7d3cd8a8bc6c4d1b977d7b08da605da36c181bEtienne Le Grand * acceptable as long as it is not done repeatedly. If the user has been 6641461f28f503d75c6eda29ec9bbd5db33b44f65feEtienne Le Grand * walking for 10 seconds, not triggering an event within those 10 seconds 6651461f28f503d75c6eda29ec9bbd5db33b44f65feEtienne Le Grand * is not acceptable. 666a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 667a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * IMPORTANT NOTE: this sensor type is very different from other types 668a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * in that it must work when the screen is off without the need of 669a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * holding a partial wake-lock and MUST allow the SoC to go into suspend. 670a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * When significant motion is detected, the sensor must awaken the SoC and 671a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * the event be reported. 672a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 673a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * If a particular hardware cannot support this mode of operation then this 674a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * sensor type MUST NOT be reported by the HAL. ie: it is not acceptable 675a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * to "emulate" this sensor in the HAL. 676a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 677a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * The whole point of this sensor type is to save power by keeping the 678a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * SoC in suspend mode when the device is at rest. 679a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 680a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * When the sensor is not activated, it must also be deactivated in the 681a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * hardware: it must not wake up the SoC anymore, even in case of 682a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * significant motion. 683a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 684a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * setDelay() has no effect and is ignored. 685a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * Once a "significant motion" event is returned, a sensor of this type 686a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * must disables itself automatically, as if activate(..., 0) had been called. 687a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian */ 688a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 689a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian#define SENSOR_TYPE_SIGNIFICANT_MOTION (17) 690b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_SIGNIFICANT_MOTION "android.sensor.significant_motion" 691a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 692a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian/* 6932f276f555064a77fa449a3ac21aa06ea3c1b45caMathias Agopian * SENSOR_TYPE_STEP_DETECTOR 694a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger-mode: special 695a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up sensor: no 696a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 697a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * A sensor of this type triggers an event each time a step is taken 698a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * by the user. The only allowed value to return is 1.0 and an event is 699a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * generated for each step. Like with any other event, the timestamp 700a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * indicates when the event (here the step) occurred, this corresponds to when 701a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * the foot hit the ground, generating a high variation in acceleration. 702a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 703a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * While this sensor operates, it shall not disrupt any other sensors, in 704a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * particular, but not limited to, the accelerometer; which might very well 705a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * be in use as well. 706a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 707a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * This sensor must be low power. That is, if the step detection cannot be 708a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * done in hardware, this sensor should not be defined. Also, when the 7092f276f555064a77fa449a3ac21aa06ea3c1b45caMathias Agopian * step detector is activated and the accelerometer is not, only steps should 710a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger interrupts (not accelerometer data). 711a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 712a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * setDelay() has no impact on this sensor type 713a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian */ 714a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 7152f276f555064a77fa449a3ac21aa06ea3c1b45caMathias Agopian#define SENSOR_TYPE_STEP_DETECTOR (18) 716b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_STEP_DETECTOR "android.sensor.step_detector" 717a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 718a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 719a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian/* 720a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * SENSOR_TYPE_STEP_COUNTER 721a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger-mode: on-change 722a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * wake-up sensor: no 723a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 724a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * A sensor of this type returns the number of steps taken by the user since 7251144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * the last reboot while activated. The value is returned as a uint64_t and is 726f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * reset to zero only on a system / android reboot. 727a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 728a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * The timestamp of the event is set to the time when the first step 729a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * for that event was taken. 7302f276f555064a77fa449a3ac21aa06ea3c1b45caMathias Agopian * See SENSOR_TYPE_STEP_DETECTOR for the signification of the time of a step. 731a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 732a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * The minimum size of the hardware's internal counter shall be 16 bits 733a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * (this restriction is here to avoid too frequent wake-ups when the 734a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * delay is very large). 735a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 736a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * IMPORTANT NOTE: this sensor type is different from other types 737a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * in that it must work when the screen is off without the need of 738a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * holding a partial wake-lock and MUST allow the SoC to go into suspend. 739a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * Unlike other sensors, while in suspend mode this sensor must stay active, 740a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * no events are reported during that time but, steps continue to be 741a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * accounted for; an event will be reported as soon as the SoC resumes if 742a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * the timeout has expired. 743a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 744a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * In other words, when the screen is off and the device allowed to 745a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * go into suspend mode, we don't want to be woken up, regardless of the 746a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * setDelay() value, but the steps shall continue to be counted. 747a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 748a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * The driver must however ensure that the internal step count never 749a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * overflows. It is allowed in this situation to wake the SoC up so the 750a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * driver can do the counter maintenance. 751a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 752a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * While this sensor operates, it shall not disrupt any other sensors, in 753a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * particular, but not limited to, the accelerometer; which might very well 754a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * be in use as well. 755a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 756a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * If a particular hardware cannot support these modes of operation then this 757a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * sensor type MUST NOT be reported by the HAL. ie: it is not acceptable 758a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * to "emulate" this sensor in the HAL. 759a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 760a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * This sensor must be low power. That is, if the step detection cannot be 761a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * done in hardware, this sensor should not be defined. Also, when the 762a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * step counter is activated and the accelerometer is not, only steps should 763a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * trigger interrupts (not accelerometer data). 764a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 765a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * The whole point of this sensor type is to save power by keeping the 766a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * SoC in suspend mode when the device is at rest. 767a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian */ 768a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 769a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian#define SENSOR_TYPE_STEP_COUNTER (19) 770b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_STEP_COUNTER "android.sensor.step_counter" 771a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 772ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand/* 773ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR 774ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * trigger-mode: continuous 775ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * wake-up sensor: no 776ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * 777ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Similar to SENSOR_TYPE_ROTATION_VECTOR, but using a magnetometer instead 778ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * of using a gyroscope. 779ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * 780ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * This sensor must be based on a magnetometer. It cannot be implemented using 781f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * a gyroscope, and gyroscope input cannot be used by this sensor, as the 782f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * goal of this sensor is to be low power. 783f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * The accelerometer can be (and usually is) used. 784ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * 785ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Just like SENSOR_TYPE_ROTATION_VECTOR, this sensor reports an estimated 786ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * heading accuracy: 78728f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * sensors_event_t.data[4] = estimated_accuracy (in radians) 788ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * The heading error must be less than estimated_accuracy 95% of the time 789ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * 790ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * see SENSOR_TYPE_ROTATION_VECTOR for more details 791ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand */ 792b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR (20) 793b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_GEOMAGNETIC_ROTATION_VECTOR "android.sensor.geomagnetic_rotation_vector" 794b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella 795b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella/* 796b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * SENSOR_TYPE_HEART_RATE 797b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * trigger-mode: on-change 798b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * wake-up sensor: no 799b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * 8007b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand * A sensor of this type returns the current heart rate. 8017b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand * The events contain the current heart rate in beats per minute (BPM) and the 8027b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand * status of the sensor during the measurement. See heart_rate_event_t for more 8037b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand * details. 8047b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand * 8057b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand * Because this sensor is on-change, events must be generated when and only 8067b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand * when heart_rate.bpm or heart_rate.status have changed since the last 80774279e3c23bd62c70d53098be91db85df5a68eceVinod Krishnan * event. In particular, upon the first activation, unless the device is known 80874279e3c23bd62c70d53098be91db85df5a68eceVinod Krishnan * to not be on the body, the status field of the first event must be set to 80974279e3c23bd62c70d53098be91db85df5a68eceVinod Krishnan * SENSOR_STATUS_UNRELIABLE. The event should be generated no faster than every 81074279e3c23bd62c70d53098be91db85df5a68eceVinod Krishnan * period_ns passed to setDelay() or to batch(). 81174279e3c23bd62c70d53098be91db85df5a68eceVinod Krishnan * See the definition of the on-change trigger mode for more information. 8127b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand * 813b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * sensor_t.requiredPermission must be set to SENSOR_PERMISSION_BODY_SENSORS. 814b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella */ 815b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_TYPE_HEART_RATE (21) 816b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella#define SENSOR_STRING_TYPE_HEART_RATE "android.sensor.heart_rate" 817a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 81856f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/** 81956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * Values returned by the accelerometer in various locations in the universe. 82056f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * all values are in SI units (m/s^2) 82156f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian */ 82256f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define GRAVITY_SUN (275.0f) 82356f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define GRAVITY_EARTH (9.80665f) 82456f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 82556f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/** Maximum magnetic field on Earth's surface */ 82656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define MAGNETIC_FIELD_EARTH_MAX (60.0f) 82756f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 82856f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/** Minimum magnetic field on Earth's surface */ 82956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define MAGNETIC_FIELD_EARTH_MIN (30.0f) 83056f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 83156f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/** 8327b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand * Possible values of the status field of sensor events. 83356f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian */ 8347b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand#define SENSOR_STATUS_NO_CONTACT -1 83556f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_STATUS_UNRELIABLE 0 83656f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_STATUS_ACCURACY_LOW 1 83756f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_STATUS_ACCURACY_MEDIUM 2 83856f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian#define SENSOR_STATUS_ACCURACY_HIGH 3 83956f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian 84056f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian/** 84156f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian * sensor event data 84256f66ccfb4915b03da4b470916bb2c59bed97216Mathias Agopian */ 843f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Projecttypedef struct { 844f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project union { 845f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project float v[3]; 846f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project struct { 847f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project float x; 848f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project float y; 849f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project float z; 850f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project }; 851f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project struct { 852f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project float azimuth; 853f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project float pitch; 854f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project float roll; 855f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project }; 856f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project }; 857f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project int8_t status; 858f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project uint8_t reserved[3]; 859f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project} sensors_vec_t; 860f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 861f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project/** 862ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * uncalibrated gyroscope and magnetometer event data 863ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand */ 864ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grandtypedef struct { 86528f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand union { 86628f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand float uncalib[3]; 86728f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand struct { 86828f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand float x_uncalib; 86928f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand float y_uncalib; 87028f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand float z_uncalib; 87128f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand }; 87228f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand }; 87328f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand union { 87428f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand float bias[3]; 87528f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand struct { 87628f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand float x_bias; 87728f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand float y_bias; 87828f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand float z_bias; 87928f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand }; 88028f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand }; 881ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand} uncalibrated_event_t; 882ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand 88316671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopiantypedef struct meta_data_event { 88416671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian int32_t what; 88516671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian int32_t sensor; 88616671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian} meta_data_event_t; 88716671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian 888ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand/** 8897b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand * Heart rate event data 8907b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand */ 8917b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grandtypedef struct { 8927b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand // Heart rate in beats per minute. 8937b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand // Set to 0 when status is SENSOR_STATUS_UNRELIABLE or ..._NO_CONTACT 8947b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand float bpm; 8957b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand // Status of the sensor for this reading. Set to one SENSOR_STATUS_... 8967b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand int8_t status; 8977b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand} heart_rate_event_t; 8987b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand 8997b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand/** 900f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * Union of the various types of sensor data 901f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * that can be returned. 902f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project */ 903cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopiantypedef struct sensors_event_t { 904cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian /* must be sizeof(struct sensors_event_t) */ 905cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian int32_t version; 906cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian 907cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian /* sensor identifier */ 908cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian int32_t sensor; 909cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian 910cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian /* sensor type */ 911cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian int32_t type; 912cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian 913cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian /* reserved */ 914cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian int32_t reserved0; 915cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian 916cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian /* time is in nanosecond */ 917cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian int64_t timestamp; 918cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian 919cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian union { 92027e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian union { 92127e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian float data[16]; 922cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian 92327e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian /* acceleration values are in meter per second per second (m/s^2) */ 92427e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian sensors_vec_t acceleration; 925cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian 92627e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian /* magnetic vector values are in micro-Tesla (uT) */ 92727e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian sensors_vec_t magnetic; 928cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian 92927e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian /* orientation values are in degrees */ 93027e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian sensors_vec_t orientation; 931cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian 93227e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian /* gyroscope values are in rad/s */ 93327e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian sensors_vec_t gyro; 9343120b58768ff6aad5ad169b9c18f962ef6abb3c5Makarand Karvekar 93527e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian /* temperature is in degrees centigrade (Celsius) */ 93627e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian float temperature; 937cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian 93827e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian /* distance in centimeters */ 93927e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian float distance; 940cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian 94127e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian /* light in SI lux units */ 94227e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian float light; 9431832f55760fff86d00b5d808b3da8f1e55a889e5Mathias Agopian 94427e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian /* pressure in hectopascal (hPa) */ 94527e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian float pressure; 946d2ed15a6b81a9a2fd95c1a565f72796869545115Urs Fleisch 94727e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian /* relative humidity in percent */ 94827e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian float relative_humidity; 949a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 95027e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian /* uncalibrated gyroscope values are in rad/s */ 95127e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian uncalibrated_event_t uncalibrated_gyro; 952ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand 95327e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian /* uncalibrated magnetometer values are in micro-Teslas */ 95427e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian uncalibrated_event_t uncalibrated_magnetic; 95516671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian 9567b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand /* heart rate data containing value in bpm and status */ 9577b36158da7d87d4b87be24c13c7607f6460bc3bbEtienne Le Grand heart_rate_event_t heart_rate; 958b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella 95916671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian /* this is a special event. see SENSOR_TYPE_META_DATA above. 96016671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * sensors_meta_data_event_t events are all reported with a type of 96116671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * SENSOR_TYPE_META_DATA. The handle is ignored and must be zero. 96216671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian */ 96316671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian meta_data_event_t meta_data; 96427e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian }; 96527e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian 96627e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian union { 96727e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian uint64_t data[8]; 968ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand 96927e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian /* step-counter */ 97027e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian uint64_t step_counter; 97127e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian } u64; 972cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian }; 97327e16688ec7496e72304d093a24d9c1d4fd37be5Mathias Agopian uint32_t reserved1[4]; 974cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian} sensors_event_t; 975cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian 976cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian 97716671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian/* see SENSOR_TYPE_META_DATA */ 97816671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopiantypedef sensors_event_t sensors_meta_data_event_t; 97916671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian 980cdefccdba52337df41f577d9ebfcfd67c05708cfMathias Agopian 981f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Projectstruct sensor_t; 982f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 983f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project/** 984f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM 985f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * and the fields of this data structure must begin with hw_module_t 986f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * followed by module specific information. 987f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project */ 988f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Projectstruct sensors_module_t { 989f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project struct hw_module_t common; 990f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 991f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project /** 992f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * Enumerate all available sensors. The list is returned in "list". 993f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project * @return number of sensors in the list 994f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project */ 995f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project int (*get_sensors_list)(struct sensors_module_t* module, 996f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project struct sensor_t const** list); 997f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project}; 998f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 999f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Projectstruct sensor_t { 10001144bea332fb24789712062bb35fe762f2f17505Mathias Agopian 10011144bea332fb24789712062bb35fe762f2f17505Mathias Agopian /* Name of this sensor. 10021144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * All sensors of the same "type" must have a different "name". 10031144bea332fb24789712062bb35fe762f2f17505Mathias Agopian */ 1004f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project const char* name; 1005a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 1006f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project /* vendor of the hardware part */ 1007f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project const char* vendor; 1008a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 1009e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian /* version of the hardware part + driver. The value of this field 1010e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * must increase when the driver is updated in a way that changes the 1011e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * output of this sensor. This is important for fused sensors when the 1012e9eaf3721dd715901d669df6488b1ecd63b1e634Mathias Agopian * fusion algorithm is updated. 1013f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project */ 1014f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project int version; 1015a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 1016a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian /* handle that identifies this sensors. This handle is used to reference 1017a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * this sensor throughout the HAL API. 1018f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project */ 1019f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project int handle; 1020a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 1021f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project /* this sensor's type. */ 1022f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project int type; 1023a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 1024a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian /* maximum range of this sensor's value in SI units */ 1025f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project float maxRange; 1026a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 1027f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project /* smallest difference between two values reported by this sensor */ 1028f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project float resolution; 1029a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 1030f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project /* rough estimate of this sensor's power consumption in mA */ 1031f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project float power; 1032a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 1033a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian /* this value depends on the trigger mode: 1034a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1035a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * continuous: minimum sample period allowed in microseconds 1036a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * on-change : 0 1037a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * one-shot :-1 1038a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * special : 0, unless otherwise noted 1039a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian */ 10401511e20fbbdfe7bf30b9de73f06fc981eb494f09Mathias Agopian int32_t minDelay; 1041a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 104216671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian /* number of events reserved for this sensor in the batch mode FIFO. 104316671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * If there is a dedicated FIFO for this sensor, then this is the 104416671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * size of this FIFO. If the FIFO is shared with other sensors, 104516671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * this is the size reserved for that sensor and it can be zero. 104616671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian */ 104716671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian uint32_t fifoReservedEventCount; 104816671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian 104916671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian /* maximum number of events of this sensor that could be batched. 105016671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * This is especially relevant when the FIFO is shared between 105116671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * several sensors; this value is then set to the size of that FIFO. 105216671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian */ 105316671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian uint32_t fifoMaxEventCount; 105416671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian 1055b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella /* type of this sensor as a string. Set to corresponding 1056b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * SENSOR_STRING_TYPE_*. 1057b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * When defining an OEM specific sensor or sensor manufacturer specific 1058b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * sensor, use your reserve domain name as a prefix. 1059b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * ex: com.google.glass.onheaddetector 1060b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * For sensors of known type, the android framework might overwrite this 1061b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * string automatically. 1062b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella */ 1063b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella const char* stringType; 1064b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella 1065b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella /* permission required to see this sensor, register to it and receive data. 1066b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * Set to "" if no permission is required. Some sensor types like the 1067b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * heart rate monitor have a mandatory require_permission. 1068b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * For sensors that always require a specific permission, like the heart 1069b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * rate monitor, the android framework might overwrite this string 1070b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella * automatically. 1071b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella */ 1072b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella const char* requiredPermission; 1073b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella 1074f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project /* reserved fields, must be zero */ 1075b20f1a3eafc2408bbcb56d1ecac07bd9bffd306bAravind Akella void* reserved[4]; 1076f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project}; 1077f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 1078f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 1079a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian/* 1080a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * sensors_poll_device_t is used with SENSORS_DEVICE_API_VERSION_0_1 1081a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * and is present for backward binary and source compatibility. 1082a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * (see documentation of the hooks in struct sensors_poll_device_1 below) 1083f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project */ 1084b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopianstruct sensors_poll_device_t { 1085b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopian struct hw_device_t common; 1086b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopian int (*activate)(struct sensors_poll_device_t *dev, 1087b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopian int handle, int enabled); 1088a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian int (*setDelay)(struct sensors_poll_device_t *dev, 1089a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian int handle, int64_t ns); 1090a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian int (*poll)(struct sensors_poll_device_t *dev, 1091a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian sensors_event_t* data, int count); 1092a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian}; 1093b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopian 1094a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian/* 1095a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * struct sensors_poll_device_1 is used with SENSORS_DEVICE_API_VERSION_1_0 1096a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian */ 1097a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopiantypedef struct sensors_poll_device_1 { 1098a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian union { 1099a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian /* sensors_poll_device_1 is compatible with sensors_poll_device_t, 1100a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * and can be down-cast to it 1101a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian */ 11021082c0b54c21c220e975f1c714e41f9183b366d1Andrew Hsieh struct sensors_poll_device_t v0; 1103a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 1104a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian struct { 1105a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian struct hw_device_t common; 1106a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 1107a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian /* Activate/de-activate one sensor. 1108a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1109a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * handle is the handle of the sensor to change. 1110a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * enabled set to 1 to enable, or 0 to disable the sensor. 1111a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1112f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * if enabled is set to 1, the sensor is activated even if 1113f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * setDelay() wasn't called before. In this case, a default rate 1114f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * should be used. 1115f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * 1116a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * unless otherwise noted in the sensor types definitions, an 1117a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * activated sensor never prevents the SoC to go into suspend 1118a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * mode; that is, the HAL shall not hold a partial wake-lock on 1119a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * behalf of applications. 1120a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1121a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * one-shot sensors de-activate themselves automatically upon 1122a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * receiving an event and they must still accept to be deactivated 1123a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * through a call to activate(..., ..., 0). 1124a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1125f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * if "enabled" is 1 and the sensor is already activated, this 1126a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * function is a no-op and succeeds. 1127a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1128f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * if "enabled" is 0 and the sensor is already de-activated, 1129a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * this function is a no-op and succeeds. 1130a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1131a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * return 0 on success, negative errno code otherwise 1132a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian */ 1133a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian int (*activate)(struct sensors_poll_device_t *dev, 1134a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian int handle, int enabled); 1135a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 1136a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian /** 11371144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * Set the events's period in nanoseconds for a given sensor. 1138a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 11391144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * What the period_ns parameter means depends on the specified 1140a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * sensor's trigger mode: 1141a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1142a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * continuous: setDelay() sets the sampling rate. 1143a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * on-change: setDelay() limits the delivery rate of events 1144a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * one-shot: setDelay() is ignored. it has no effect. 1145a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * special: see specific sensor type definitions 1146a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1147a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * For continuous and on-change sensors, if the requested value is 1148a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * less than sensor_t::minDelay, then it's silently clamped to 1149a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * sensor_t::minDelay unless sensor_t::minDelay is 0, in which 1150a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * case it is clamped to >= 1ms. 1151a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1152f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * setDelay will not be called when the sensor is in batching mode. 1153f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * In this case, batch() will be called with the new period. 1154f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * 1155a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * @return 0 if successful, < 0 on error 1156a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian */ 1157a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian int (*setDelay)(struct sensors_poll_device_t *dev, 11581144bea332fb24789712062bb35fe762f2f17505Mathias Agopian int handle, int64_t period_ns); 1159a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 1160a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian /** 1161a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * Returns an array of sensor data. 1162a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * This function must block until events are available. 1163a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1164a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * return the number of events read on success, or -errno in case 1165a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * of an error. 1166a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1167a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * The number of events returned in data must be less or equal 116828f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * to the "count" argument. 1169a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1170a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * This function shall never return 0 (no event). 1171a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian */ 1172a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian int (*poll)(struct sensors_poll_device_t *dev, 1173a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian sensors_event_t* data, int count); 1174a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian }; 1175a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian }; 1176a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 1177a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 1178a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian /* 11791144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * Enables batch mode for the given sensor and sets the delay between events 1180a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1181a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * A timeout value of zero disables batch mode for the given sensor. 1182a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 11831144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * The period_ns parameter is equivalent to calling setDelay() -- this 11841144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * function both enables or disables the batch mode AND sets the events's 11851144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * period in nanosecond. See setDelay() above for a detailed explanation of 11861144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * the period_ns parameter. 11871144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * 118828f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * BATCH MODE: 118928f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * ----------- 119028f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * In non-batch mode, all sensor events must be reported as soon as they 119128f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * are detected. For example, an accelerometer activated at 50Hz will 119228f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * trigger interrupts 50 times per second. 119328f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * While in batch mode, sensor events do not need to be reported as soon 119428f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * as they are detected. They can be temporarily stored in batches and 119528f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * reported in batches, as long as no event is delayed by more than 119628f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * "timeout" nanoseconds. That is, all events since the previous batch 119728f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * are recorded and returned all at once. This allows to reduce the amount 119828f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * of interrupts sent to the SoC, and allow the SoC to switch to a lower 119928f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * power state (Idle) while the sensor is capturing and batching data. 1200a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1201a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * setDelay() is not affected and it behaves as usual. 1202a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1203a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * Each event has a timestamp associated with it, the timestamp 1204a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * must be accurate and correspond to the time at which the event 1205a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * physically happened. 1206a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 120728f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * Batching does not modify the behavior of poll(): batches from different 120828f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * sensors can be interleaved and split. As usual, all events from the same 120928f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * sensor are time-ordered. 121028f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * 121128f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * BEHAVIOUR OUTSIDE OF SUSPEND MODE: 121228f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * ---------------------------------- 121328f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * 121428f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * When the SoC is awake (not in suspend mode), events must be reported in 121528f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * batches at least every "timeout". No event shall be dropped or lost. 1216a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * If internal h/w FIFOs fill-up before the timeout, then events are 121728f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * reported at that point to ensure no event is lost. 12181144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * 12191144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * 122028f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * NORMAL BEHAVIOR IN SUSPEND MODE: 122128f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * --------------------------------- 1222a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 122328f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * By default, batch mode doesn't significantly change the interaction with 122428f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * suspend mode. That is, sensors must continue to allow the SoC to 1225a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * go into suspend mode and sensors must stay active to fill their 122628f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * internal FIFO. In this mode, when the FIFO fills up, it shall wrap 1227a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * around (basically behave like a circular buffer, overwriting events). 1228a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * As soon as the SoC comes out of suspend mode, a batch is produced with 1229a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * as much as the recent history as possible, and batch operation 1230a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * resumes as usual. 1231a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1232a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * The behavior described above allows applications to record the recent 1233a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * history of a set of sensor while keeping the SoC into suspend. It 1234a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * also allows the hardware to not have to rely on a wake-up interrupt line. 1235a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 123628f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * WAKE_UPON_FIFO_FULL BEHAVIOR IN SUSPEND MODE: 123728f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * ---------------------------------------------- 1238a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 123928f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * There are cases, however, where an application cannot afford to lose 124028f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * any events, even when the device goes into suspend mode. 124128f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * For a given rate, if a sensor has the capability to store at least 10 124228f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * seconds worth of events in its FIFO and is able to wake up the Soc, it 124328f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * can implement an optional secondary mode: the WAKE_UPON_FIFO_FULL mode. 124428f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * 124528f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * The caller will set the SENSORS_BATCH_WAKE_UPON_FIFO_FULL flag to 124628f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * activate this mode. If the sensor does not support this mode, batch() 124728f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * will fail when the flag is set. 124828f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * 124928f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * When running with the WAKE_UPON_FIFO_FULL flag set, no events can be 125028f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * lost. When the FIFO is getting full, the sensor must wake up the SoC from 125128f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * suspend and return a batch before the FIFO fills-up. 125228f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * Depending on the device, it might take a few miliseconds for the SoC to 125328f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * entirely come out of suspend and start flushing the FIFO. Enough head 125428f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * room must be allocated in the FIFO to allow the device to entirely come 125528f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * out of suspend without the FIFO overflowing (no events shall be lost). 125628f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * 125728f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * Implementing the WAKE_UPON_FIFO_FULL mode is optional. 125828f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * If the hardware cannot support this mode, or if the physical 1259a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * FIFO is so small that the device would never be allowed to go into 12601144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * suspend for at least 10 seconds, then this function MUST fail when 12611144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * the flag SENSORS_BATCH_WAKE_UPON_FIFO_FULL is set, regardless of 12621144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * the value of the timeout parameter. 1263a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 126428f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * 12651144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * DRY RUN: 12661144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * -------- 1267a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1268a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * If the flag SENSORS_BATCH_DRY_RUN is set, this function returns 12691144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * without modifying the batch mode or the event period and has no side 12701144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * effects, but returns errors as usual (as it would if this flag was 12711144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * not set). This flag is used to check if batch mode is available for a 12721144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * given configuration -- in particular for a given sensor at a given rate. 12731144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * 1274a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1275a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * Return values: 12761144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * -------------- 12771144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * 12781144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * Because sensors must be independent, the return value must not depend 12791144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * on the state of the system (whether another sensor is on or not), 12801144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * nor on whether the flag SENSORS_BATCH_DRY_RUN is set (in other words, 12811144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * if a batch call with SENSORS_BATCH_DRY_RUN is successful, 12821144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * the same call without SENSORS_BATCH_DRY_RUN must succeed as well). 1283a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1284f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * When timeout is not 0: 1285f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * If successful, 0 is returned. 1286f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * If the specified sensor doesn't support batch mode, return -EINVAL. 1287f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * If the specified sensor's trigger-mode is one-shot, return -EINVAL. 1288f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * If WAKE_UPON_FIFO_FULL is specified and the specified sensor's internal 1289f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * FIFO is too small to store at least 10 seconds worth of data at the 1290f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * given rate, -EINVAL is returned. Note that as stated above, this has to 1291f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * be determined at compile time, and not based on the state of the 1292f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * system. 1293f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * If some other constraints above cannot be satisfied, return -EINVAL. 1294a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 12951144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * Note: the timeout parameter, when > 0, has no impact on whether this 12961144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * function succeeds or fails. 12971144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * 1298f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * When timeout is 0: 1299f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * The caller will never set the wake_upon_fifo_full flag. 1300f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * The function must succeed, and batch mode must be deactivated. 1301f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * 1302f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * Independently of whether DRY_RUN is specified, When the call to batch() 1303f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * fails, no state should be changed. In particular, a failed call to 1304f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * batch() should not change the rate of the sensor. Example: 1305f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * setDelay(..., 10ms) 1306f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * batch(..., 20ms, ...) fails 1307f770b7a9b9315fa924de224af188c314a474eb10Etienne Le Grand * rate should stay 10ms. 1308a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1309a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 1310a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * IMPLEMENTATION NOTES: 13111144bea332fb24789712062bb35fe762f2f17505Mathias Agopian * --------------------- 1312b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopian * 131328f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * Batch mode, if supported, should happen at the hardware level, 1314a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * typically using hardware FIFOs. In particular, it SHALL NOT be 1315a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * implemented in the HAL, as this would be counter productive. 1316a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * The goal here is to save significant amounts of power. 1317a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * 131828f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * In some implementations, events from several sensors can share the 131928f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * same physical FIFO. In that case, all events in the FIFO can be sent and 132028f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * processed by the HAL as soon as one batch must be reported. 132128f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * For example, if the following sensors are activated: 132228f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * - accelerometer batched with timeout = 20s 132328f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * - gyroscope batched with timeout = 5s 132428f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * then the accelerometer batches can be reported at the same time the 132528f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * gyroscope batches are reported (every 5 seconds) 132628f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * 132728f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * Batch mode can be enabled or disabled at any time, in particular 132828f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * while the specified sensor is already enabled, and this shall not 1329a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian * result in the loss of events. 1330b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopian * 1331ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * COMPARATIVE IMPORTANCE OF BATCHING FOR DIFFERENT SENSORS: 1332ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * --------------------------------------------------------- 1333ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * 1334ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * On platforms on which hardware fifo size is limited, the system designers 1335ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * might have to choose how much fifo to reserve for each sensor. To help 133628f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * with this choice, here is a list of applications made possible when 1337ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * batching is implemented on the different sensors. 1338ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * 1339ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * High value: Low power pedestrian dead reckoning 1340ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Target batching time: 20 seconds to 1 minute 1341ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Sensors to batch: 1342ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * - Step detector 1343ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * - Rotation vector or game rotation vector at 5Hz 134428f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * Gives us step and heading while letting the SoC go to Suspend. 1345ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * 1346ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * High value: Medium power activity/gesture recognition 1347ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Target batching time: 3 seconds 1348ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Sensors to batch: accelerometer between 20Hz and 50Hz 1349ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Allows recognizing arbitrary activities and gestures without having 135028f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * to keep the SoC fully awake while the data is collected. 1351ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * 1352ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Medium-high value: Interrupt load reduction 1353ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Target batching time: < 1 second 1354ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Sensors to batch: any high frequency sensor. 1355ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * If the gyroscope is set at 800Hz, even batching just 10 gyro events can 1356ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * reduce the number of interrupts from 800/second to 80/second. 1357ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * 1358ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Medium value: Continuous low frequency data collection 1359ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Target batching time: > 1 minute 1360ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Sensors to batch: barometer, humidity sensor, other low frequency 1361ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * sensors. 1362ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Allows creating monitoring applications at low power. 1363ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * 1364ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Medium value: Continuous full-sensors collection 1365ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Target batching time: > 1 minute 1366ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * Sensors to batch: all, at high frequencies 136728f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * Allows full collection of sensor data while leaving the SoC in 1368ca8581433b778c60b074839baa6c3f2233c09614Etienne Le Grand * suspend mode. Only to consider if fifo space is not an issue. 136928f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * 137028f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * In each of the cases above, if WAKE_UPON_FIFO_FULL is implemented, the 137128f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * applications might decide to let the SoC go to suspend, allowing for even 137228f04113f56a05560fc6074579ab5a4fcd424a0fEtienne Le Grand * more power savings. 1373b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopian */ 1374a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian int (*batch)(struct sensors_poll_device_1* dev, 13751144bea332fb24789712062bb35fe762f2f17505Mathias Agopian int handle, int flags, int64_t period_ns, int64_t timeout); 1376a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 137716671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian /* 137816671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * Flush adds a META_DATA_FLUSH_COMPLETE event (sensors_event_meta_data_t) 137916671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * to the end of the "batch mode" FIFO for the specified sensor and flushes 138016671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * the FIFO; those events are delivered as usual (i.e.: as if the batch 138116671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * timeout had expired) and removed from the FIFO. 138216671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * 138316671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * See the META_DATA_FLUSH_COMPLETE section for details about the 138416671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * META_DATA_FLUSH_COMPLETE event. 138516671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * 138616671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * The flush happens asynchronously (i.e.: this function must return 138716671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * immediately). 138816671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * 138916671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * If the implementation uses a single FIFO for several sensors, that 139016671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * FIFO is flushed and the META_DATA_FLUSH_COMPLETE event is added only 139116671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * for the specified sensor. 139216671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * 139316671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * If the specified sensor wasn't in batch mode, flush succeeds and 139416671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * promptly sends a META_DATA_FLUSH_COMPLETE event for that sensor. 139516671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * 139616671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * If the FIFO was empty at the time of the call, flush returns 139716671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * 0 (success) and promptly sends a META_DATA_FLUSH_COMPLETE event 139816671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * for that sensor. 139916671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * 140016671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * If the specified sensor wasn't enabled, flush returns -EINVAL. 140116671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * 140216671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian * return 0 on success, negative errno code otherwise. 140316671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian */ 140416671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian int (*flush)(struct sensors_poll_device_1* dev, int handle); 140516671c5519003d3be0eab34a8a78fecac9e941a3Mathias Agopian 1406a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian void (*reserved_procs[8])(void); 1407a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 1408a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian} sensors_poll_device_1_t; 1409a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 1410a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 1411b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopian 1412f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project/** convenience API for opening and closing a device */ 1413f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 1414b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopianstatic inline int sensors_open(const struct hw_module_t* module, 1415b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopian struct sensors_poll_device_t** device) { 1416b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopian return module->methods->open(module, 1417b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopian SENSORS_HARDWARE_POLL, (struct hw_device_t**)device); 1418b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopian} 1419b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopian 1420b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopianstatic inline int sensors_close(struct sensors_poll_device_t* device) { 1421b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopian return device->common.close(&device->common); 1422b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopian} 1423b1e212e7b6fce2bc5c743b05853129e19760d7a4Mathias Agopian 1424a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopianstatic inline int sensors_open_1(const struct hw_module_t* module, 14251082c0b54c21c220e975f1c714e41f9183b366d1Andrew Hsieh sensors_poll_device_1_t** device) { 1426a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian return module->methods->open(module, 1427a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian SENSORS_HARDWARE_POLL, (struct hw_device_t**)device); 1428a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian} 1429a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 14301082c0b54c21c220e975f1c714e41f9183b366d1Andrew Hsiehstatic inline int sensors_close_1(sensors_poll_device_1_t* device) { 1431a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian return device->common.close(&device->common); 1432a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian} 1433a455772cb30cb8fed26b12f61a6d78c9b689e640Mathias Agopian 1434f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project__END_DECLS 1435f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project 1436f53ebec38718ff5d6b2aff2fa62b92a75d007ca5The Android Open Source Project#endif // ANDROID_SENSORS_INTERFACE_H 1437