1/* 2 * Copyright (C) 2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 18package android.hardware; 19 20import android.os.Build; 21 22/** 23 * Class representing a sensor. Use {@link SensorManager#getSensorList} to get 24 * the list of available Sensors. 25 * 26 * @see SensorManager 27 * @see SensorEventListener 28 * @see SensorEvent 29 * 30 */ 31public final class Sensor { 32 33 /** 34 * A constant describing an accelerometer sensor type. 35 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 36 * for more details. 37 */ 38 public static final int TYPE_ACCELEROMETER = 1; 39 40 /** 41 * A constant describing a magnetic field sensor type. 42 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 43 * for more details. 44 */ 45 public static final int TYPE_MAGNETIC_FIELD = 2; 46 47 /** 48 * A constant describing an orientation sensor type. 49 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 50 * for more details. 51 * 52 * @deprecated use {@link android.hardware.SensorManager#getOrientation 53 * SensorManager.getOrientation()} instead. 54 */ 55 @Deprecated 56 public static final int TYPE_ORIENTATION = 3; 57 58 /** A constant describing a gyroscope sensor type. 59 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 60 * for more details. */ 61 public static final int TYPE_GYROSCOPE = 4; 62 63 /** 64 * A constant describing a light sensor type. 65 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 66 * for more details. 67 */ 68 public static final int TYPE_LIGHT = 5; 69 70 /** A constant describing a pressure sensor type. 71 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 72 * for more details. */ 73 public static final int TYPE_PRESSURE = 6; 74 75 /** 76 * A constant describing a temperature sensor type 77 * 78 * @deprecated use 79 * {@link android.hardware.Sensor#TYPE_AMBIENT_TEMPERATURE 80 * Sensor.TYPE_AMBIENT_TEMPERATURE} instead. 81 */ 82 @Deprecated 83 public static final int TYPE_TEMPERATURE = 7; 84 85 /** 86 * A constant describing a proximity sensor type. 87 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 88 * for more details. 89 */ 90 public static final int TYPE_PROXIMITY = 8; 91 92 /** 93 * A constant describing a gravity sensor type. 94 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 95 * for more details. 96 */ 97 public static final int TYPE_GRAVITY = 9; 98 99 /** 100 * A constant describing a linear acceleration sensor type. 101 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 102 * for more details. 103 */ 104 public static final int TYPE_LINEAR_ACCELERATION = 10; 105 106 /** 107 * A constant describing a rotation vector sensor type. 108 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 109 * for more details. 110 */ 111 public static final int TYPE_ROTATION_VECTOR = 11; 112 113 /** 114 * A constant describing a relative humidity sensor type. 115 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 116 * for more details. 117 */ 118 public static final int TYPE_RELATIVE_HUMIDITY = 12; 119 120 /** A constant describing an ambient temperature sensor type. 121 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 122 * for more details. */ 123 public static final int TYPE_AMBIENT_TEMPERATURE = 13; 124 125 /** 126 * A constant describing an uncalibrated magnetic field sensor type. 127 * <p> 128 * Similar to {@link #TYPE_MAGNETIC_FIELD} but the hard iron calibration (device calibration 129 * due to distortions that arise from magnetized iron, steel or permanent magnets on the 130 * device) is not considered in the given sensor values. However, such hard iron bias values 131 * are returned to you separately in the result {@link android.hardware.SensorEvent#values} 132 * so you may use them for custom calibrations. 133 * <p>Also, no periodic calibration is performed 134 * (i.e. there are no discontinuities in the data stream while using this sensor) and 135 * assumptions that the magnetic field is due to the Earth's poles is avoided, but 136 * factory calibration and temperature compensation have been performed. 137 * </p> 138 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} for more 139 * details. 140 */ 141 public static final int TYPE_MAGNETIC_FIELD_UNCALIBRATED = 14; 142 143 /** 144 * A constant describing an uncalibrated rotation vector sensor type. 145 * <p>Identical to {@link #TYPE_ROTATION_VECTOR} except that it doesn't 146 * use the geomagnetic field. Therefore the Y axis doesn't 147 * point north, but instead to some other reference, that reference is 148 * allowed to drift by the same order of magnitude as the gyroscope 149 * drift around the Z axis. 150 * <p> 151 * In the ideal case, a phone rotated and returning to the same real-world 152 * orientation should report the same game rotation vector 153 * (without using the earth's geomagnetic field). However, the orientation 154 * may drift somewhat over time. 155 * </p> 156 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} for more 157 * details. 158 */ 159 160 public static final int TYPE_GAME_ROTATION_VECTOR = 15; 161 162 /** 163 * A constant describing an uncalibrated gyroscope sensor type. 164 * <p>Similar to {@link #TYPE_GYROSCOPE} but no gyro-drift compensation has been performed 165 * to adjust the given sensor values. However, such gyro-drift bias values 166 * are returned to you separately in the result {@link android.hardware.SensorEvent#values} 167 * so you may use them for custom calibrations. 168 * <p>Factory calibration and temperature compensation is still applied 169 * to the rate of rotation (angular speeds). 170 * </p> 171 * <p> See {@link android.hardware.SensorEvent#values SensorEvent.values} for more 172 * details. 173 */ 174 public static final int TYPE_GYROSCOPE_UNCALIBRATED = 16; 175 176 /** 177 * A constant describing a significant motion trigger sensor. 178 * <p> 179 * It triggers when an event occurs and then automatically disables 180 * itself. The sensor continues to operate while the device is asleep 181 * and will automatically wake the device to notify when significant 182 * motion is detected. The application does not need to hold any wake 183 * locks for this sensor to trigger. 184 * <p>See {@link TriggerEvent} for more details. 185 */ 186 public static final int TYPE_SIGNIFICANT_MOTION = 17; 187 188 /** 189 * A constant describing a step detector sensor. 190 * <p> 191 * A sensor of this type triggers an event each time a step is taken by the user. The only 192 * allowed value to return is 1.0 and an event is generated for each step. Like with any other 193 * event, the timestamp indicates when the event (here the step) occurred, this corresponds to 194 * when the foot hit the ground, generating a high variation in acceleration. 195 * <p> 196 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 197 */ 198 public static final int TYPE_STEP_DETECTOR = 18; 199 200 /** 201 * A constant describing a step counter sensor. 202 * <p> 203 * A sensor of this type returns the number of steps taken by the user since the last reboot 204 * while activated. The value is returned as a float (with the fractional part set to zero) and 205 * is reset to zero only on a system reboot. The timestamp of the event is set to the time when 206 * the first step for that event was taken. This sensor is implemented in hardware and is 207 * expected to be low power. 208 * <p> 209 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 210 */ 211 public static final int TYPE_STEP_COUNTER = 19; 212 213 /** 214 * A constant describing the geo-magnetic rotation vector. 215 * <p> 216 * Similar to {@link #TYPE_ROTATION_VECTOR}, but using a magnetometer instead of using a 217 * gyroscope. This sensor uses lower power than the other rotation vectors, because it doesn't 218 * use the gyroscope. However, it is more noisy and will work best outdoors. 219 * <p> 220 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 221 */ 222 public static final int TYPE_GEOMAGNETIC_ROTATION_VECTOR = 20; 223 224 /** 225 * A constant describing all sensor types. 226 */ 227 public static final int TYPE_ALL = -1; 228 229 /* Reporting mode constants for sensors. Each sensor will have exactly one 230 reporting mode associated with it. */ 231 // Events are reported at a constant rate. 232 static int REPORTING_MODE_CONTINUOUS = 1; 233 234 // Events are reported only when the value changes. 235 static int REPORTING_MODE_ON_CHANGE = 2; 236 237 // Upon detection of an event, the sensor deactivates itself and then sends a single event. 238 static int REPORTING_MODE_ONE_SHOT = 3; 239 240 // TODO(): The following arrays are fragile and error-prone. This needs to be refactored. 241 242 // Note: This needs to be updated, whenever a new sensor is added. 243 // Holds the reporting mode and maximum length of the values array 244 // associated with 245 // {@link SensorEvent} or {@link TriggerEvent} for the Sensor 246 private static final int[] sSensorReportingModes = { 247 0, 0, // padding because sensor types start at 1 248 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_ACCELEROMETER 249 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_GEOMAGNETIC_FIELD 250 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_ORIENTATION 251 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_GYROSCOPE 252 REPORTING_MODE_ON_CHANGE, 3, // SENSOR_TYPE_LIGHT 253 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_PRESSURE 254 REPORTING_MODE_ON_CHANGE, 3, // SENSOR_TYPE_TEMPERATURE 255 REPORTING_MODE_ON_CHANGE, 3, // SENSOR_TYPE_PROXIMITY 256 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_GRAVITY 257 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_LINEAR_ACCELERATION 258 REPORTING_MODE_CONTINUOUS, 5, // SENSOR_TYPE_ROTATION_VECTOR 259 REPORTING_MODE_ON_CHANGE, 3, // SENSOR_TYPE_RELATIVE_HUMIDITY 260 REPORTING_MODE_ON_CHANGE, 3, // SENSOR_TYPE_AMBIENT_TEMPERATURE 261 REPORTING_MODE_CONTINUOUS, 6, // SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED 262 REPORTING_MODE_CONTINUOUS, 4, // SENSOR_TYPE_GAME_ROTATION_VECTOR 263 REPORTING_MODE_CONTINUOUS, 6, // SENSOR_TYPE_GYROSCOPE_UNCALIBRATED 264 REPORTING_MODE_ONE_SHOT, 1, // SENSOR_TYPE_SIGNIFICANT_MOTION 265 // added post 4.3 266 REPORTING_MODE_ON_CHANGE, 1, // SENSOR_TYPE_STEP_DETECTOR 267 REPORTING_MODE_ON_CHANGE, 1, // SENSOR_TYPE_STEP_COUNTER 268 REPORTING_MODE_CONTINUOUS, 5 // SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR 269 }; 270 271 static int getReportingMode(Sensor sensor) { 272 int offset = sensor.mType * 2; 273 if (offset >= sSensorReportingModes.length) { 274 // we don't know about this sensor, so this is probably a 275 // vendor-defined sensor, in that case, we figure out the reporting 276 // mode from the sensor meta-data. 277 int minDelay = sensor.mMinDelay; 278 if (minDelay == 0) { 279 return REPORTING_MODE_ON_CHANGE; 280 } else if (minDelay < 0) { 281 return REPORTING_MODE_ONE_SHOT; 282 } else { 283 return REPORTING_MODE_CONTINUOUS; 284 } 285 } 286 return sSensorReportingModes[offset]; 287 } 288 289 static int getMaxLengthValuesArray(Sensor sensor, int sdkLevel) { 290 int type = sensor.mType; 291 // RotationVector length has changed to 3 to 5 for API level 18 292 // Set it to 3 for backward compatibility. 293 if (type == Sensor.TYPE_ROTATION_VECTOR && 294 sdkLevel <= Build.VERSION_CODES.JELLY_BEAN_MR1) { 295 return 3; 296 } 297 int offset = type * 2 + 1; 298 if (offset >= sSensorReportingModes.length) { 299 // we don't know about this sensor, so this is probably a 300 // vendor-defined sensor, in that case, we don't know how many value 301 // it has 302 // so we return the maximum and assume the app will know. 303 // FIXME: sensor HAL should advertise how much data is returned per 304 // sensor 305 return 16; 306 } 307 return sSensorReportingModes[offset]; 308 } 309 310 /* Some of these fields are set only by the native bindings in 311 * SensorManager. 312 */ 313 private String mName; 314 private String mVendor; 315 private int mVersion; 316 private int mHandle; 317 private int mType; 318 private float mMaxRange; 319 private float mResolution; 320 private float mPower; 321 private int mMinDelay; 322 private int mFifoReservedEventCount; 323 private int mFifoMaxEventCount; 324 325 Sensor() { 326 } 327 328 /** 329 * @return name string of the sensor. 330 */ 331 public String getName() { 332 return mName; 333 } 334 335 /** 336 * @return vendor string of this sensor. 337 */ 338 public String getVendor() { 339 return mVendor; 340 } 341 342 /** 343 * @return generic type of this sensor. 344 */ 345 public int getType() { 346 return mType; 347 } 348 349 /** 350 * @return version of the sensor's module. 351 */ 352 public int getVersion() { 353 return mVersion; 354 } 355 356 /** 357 * @return maximum range of the sensor in the sensor's unit. 358 */ 359 public float getMaximumRange() { 360 return mMaxRange; 361 } 362 363 /** 364 * @return resolution of the sensor in the sensor's unit. 365 */ 366 public float getResolution() { 367 return mResolution; 368 } 369 370 /** 371 * @return the power in mA used by this sensor while in use 372 */ 373 public float getPower() { 374 return mPower; 375 } 376 377 /** 378 * @return the minimum delay allowed between two events in microsecond 379 * or zero if this sensor only returns a value when the data it's measuring 380 * changes. 381 */ 382 public int getMinDelay() { 383 return mMinDelay; 384 } 385 386 /** 387 * @return Number of events reserved for this sensor in the batch mode FIFO. This gives a 388 * guarantee on the minimum number of events that can be batched. 389 */ 390 public int getFifoReservedEventCount() { 391 return mFifoReservedEventCount; 392 } 393 394 /** 395 * @return Maximum number of events of this sensor that could be batched. If this value is zero 396 * it indicates that batch mode is not supported for this sensor. If other applications 397 * registered to batched sensors, the actual number of events that can be batched might be 398 * smaller because the hardware FiFo will be partially used to batch the other sensors. 399 */ 400 public int getFifoMaxEventCount() { 401 return mFifoMaxEventCount; 402 } 403 404 /** @hide */ 405 public int getHandle() { 406 return mHandle; 407 } 408 409 void setRange(float max, float res) { 410 mMaxRange = max; 411 mResolution = res; 412 } 413 414 @Override 415 public String toString() { 416 return "{Sensor name=\"" + mName + "\", vendor=\"" + mVendor + "\", version=" + mVersion 417 + ", type=" + mType + ", maxRange=" + mMaxRange + ", resolution=" + mResolution 418 + ", power=" + mPower + ", minDelay=" + mMinDelay + "}"; 419 } 420} 421