Sensor.java revision fd53d8352a4617941b0a0449390aa562a01ea1d3
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 string describing an accelerometer sensor type. 42 * 43 * @see #TYPE_ACCELEROMETER 44 */ 45 public static final String STRING_TYPE_ACCELEROMETER = "android.sensor.accelerometer"; 46 47 /** 48 * A constant describing a magnetic field sensor type. 49 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 50 * for more details. 51 */ 52 public static final int TYPE_MAGNETIC_FIELD = 2; 53 54 /** 55 * A constant string describing a magnetic field sensor type. 56 * 57 * @see #TYPE_MAGNETIC_FIELD 58 */ 59 public static final String STRING_TYPE_MAGNETIC_FIELD = "android.sensor.magnetic_field"; 60 61 /** 62 * A constant describing an orientation sensor type. 63 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 64 * for more details. 65 * 66 * @deprecated use {@link android.hardware.SensorManager#getOrientation 67 * SensorManager.getOrientation()} instead. 68 */ 69 @Deprecated 70 public static final int TYPE_ORIENTATION = 3; 71 72 /** 73 * A constant string describing an orientation sensor type. 74 * 75 * @see #TYPE_ORIENTATION 76 * @deprecated use {@link android.hardware.SensorManager#getOrientation 77 * SensorManager.getOrientation()} instead. 78 */ 79 @Deprecated 80 public static final String STRING_TYPE_ORIENTATION = "android.sensor.orientation"; 81 82 /** 83 * A constant describing a gyroscope sensor type. 84 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 85 * for more details. */ 86 public static final int TYPE_GYROSCOPE = 4; 87 88 /** 89 * A constant string describing a gyroscope sensor type. 90 * 91 * @see #TYPE_GYROSCOPE 92 */ 93 public static final String STRING_TYPE_GYROSCOPE = "android.sensor.gyroscope"; 94 95 /** 96 * A constant describing a light sensor type. 97 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 98 * for more details. 99 */ 100 public static final int TYPE_LIGHT = 5; 101 102 /** 103 * A constant string describing a light sensor type. 104 * 105 * @see #TYPE_LIGHT 106 */ 107 public static final String STRING_TYPE_LIGHT = "android.sensor.light"; 108 109 /** 110 * A constant describing a pressure sensor type. 111 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 112 * for more details. 113 */ 114 public static final int TYPE_PRESSURE = 6; 115 116 /** 117 * A constant string describing a pressure sensor type. 118 * 119 * @see #TYPE_PRESSURE 120 */ 121 public static final String STRING_TYPE_PRESSURE = "android.sensor.pressure"; 122 123 /** 124 * A constant describing a temperature sensor type 125 * 126 * @deprecated use 127 * {@link android.hardware.Sensor#TYPE_AMBIENT_TEMPERATURE 128 * Sensor.TYPE_AMBIENT_TEMPERATURE} instead. 129 */ 130 @Deprecated 131 public static final int TYPE_TEMPERATURE = 7; 132 133 /** 134 * A constant string describing a temperature sensor type 135 * 136 * @see #TYPE_TEMPERATURE 137 * @deprecated use 138 * {@link android.hardware.Sensor#STRING_TYPE_AMBIENT_TEMPERATURE 139 * Sensor.STRING_TYPE_AMBIENT_TEMPERATURE} instead. 140 */ 141 @Deprecated 142 public static final String STRING_TYPE_TEMPERATURE = "android.sensor.temperature"; 143 144 /** 145 * A constant describing a proximity sensor type. 146 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 147 * for more details. 148 */ 149 public static final int TYPE_PROXIMITY = 8; 150 151 /** 152 * A constant string describing a proximity sensor type. 153 * 154 * @see #TYPE_PROXIMITY 155 */ 156 public static final String STRING_TYPE_PROXIMITY = "android.sensor.proximity"; 157 158 /** 159 * A constant describing a gravity sensor type. 160 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 161 * for more details. 162 */ 163 public static final int TYPE_GRAVITY = 9; 164 165 /** 166 * A constant string describing a gravity sensor type. 167 * 168 * @see #TYPE_GRAVITY 169 */ 170 public static final String STRING_TYPE_GRAVITY = "android.sensor.gravity"; 171 172 /** 173 * A constant describing a linear acceleration sensor type. 174 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 175 * for more details. 176 */ 177 public static final int TYPE_LINEAR_ACCELERATION = 10; 178 179 /** 180 * A constant string describing a linear acceleration sensor type. 181 * 182 * @see #TYPE_LINEAR_ACCELERATION 183 */ 184 public static final String STRING_TYPE_LINEAR_ACCELERATION = 185 "android.sensor.linear_acceleration"; 186 187 /** 188 * A constant describing a rotation vector sensor type. 189 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 190 * for more details. 191 */ 192 public static final int TYPE_ROTATION_VECTOR = 11; 193 194 /** 195 * A constant string describing a rotation vector sensor type. 196 * 197 * @see #TYPE_ROTATION_VECTOR 198 */ 199 public static final String STRING_TYPE_ROTATION_VECTOR = "android.sensor.rotation_vector"; 200 201 /** 202 * A constant describing a relative humidity sensor type. 203 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 204 * for more details. 205 */ 206 public static final int TYPE_RELATIVE_HUMIDITY = 12; 207 208 /** 209 * A constant string describing a relative humidity sensor type 210 * 211 * @see #TYPE_RELATIVE_HUMIDITY 212 */ 213 public static final String STRING_TYPE_RELATIVE_HUMIDITY = "android.sensor.relative_humidity"; 214 215 /** 216 * A constant describing an ambient temperature sensor type. 217 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 218 * for more details. 219 */ 220 public static final int TYPE_AMBIENT_TEMPERATURE = 13; 221 222 /** 223 * A constant string describing an ambient temperature sensor type. 224 * 225 * @see #TYPE_AMBIENT_TEMPERATURE 226 */ 227 public static final String STRING_TYPE_AMBIENT_TEMPERATURE = 228 "android.sensor.ambient_temperature"; 229 230 /** 231 * A constant describing an uncalibrated magnetic field sensor type. 232 * <p> 233 * Similar to {@link #TYPE_MAGNETIC_FIELD} but the hard iron calibration (device calibration 234 * due to distortions that arise from magnetized iron, steel or permanent magnets on the 235 * device) is not considered in the given sensor values. However, such hard iron bias values 236 * are returned to you separately in the result {@link android.hardware.SensorEvent#values} 237 * so you may use them for custom calibrations. 238 * <p>Also, no periodic calibration is performed 239 * (i.e. there are no discontinuities in the data stream while using this sensor) and 240 * assumptions that the magnetic field is due to the Earth's poles is avoided, but 241 * factory calibration and temperature compensation have been performed. 242 * </p> 243 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} for more 244 * details. 245 */ 246 public static final int TYPE_MAGNETIC_FIELD_UNCALIBRATED = 14; 247 /** 248 * A constant string describing an uncalibrated magnetic field sensor type. 249 * 250 * @see #TYPE_MAGNETIC_FIELD_UNCALIBRATED 251 */ 252 public static final String STRING_TYPE_MAGNETIC_FIELD_UNCALIBRATED = 253 "android.sensor.magnetic_field_uncalibrated"; 254 255 /** 256 * A constant describing an uncalibrated rotation vector sensor type. 257 * <p>Identical to {@link #TYPE_ROTATION_VECTOR} except that it doesn't 258 * use the geomagnetic field. Therefore the Y axis doesn't 259 * point north, but instead to some other reference, that reference is 260 * allowed to drift by the same order of magnitude as the gyroscope 261 * drift around the Z axis. 262 * <p> 263 * In the ideal case, a phone rotated and returning to the same real-world 264 * orientation should report the same game rotation vector 265 * (without using the earth's geomagnetic field). However, the orientation 266 * may drift somewhat over time. 267 * </p> 268 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} for more 269 * details. 270 */ 271 public static final int TYPE_GAME_ROTATION_VECTOR = 15; 272 273 /** 274 * A constant string describing an uncalibrated rotation vector sensor type. 275 * 276 * @see #TYPE_GAME_ROTATION_VECTOR 277 */ 278 public static final String STRING_TYPE_GAME_ROTATION_VECTOR = 279 "android.sensor.game_rotation_vector"; 280 281 /** 282 * A constant describing an uncalibrated gyroscope sensor type. 283 * <p>Similar to {@link #TYPE_GYROSCOPE} but no gyro-drift compensation has been performed 284 * to adjust the given sensor values. However, such gyro-drift bias values 285 * are returned to you separately in the result {@link android.hardware.SensorEvent#values} 286 * so you may use them for custom calibrations. 287 * <p>Factory calibration and temperature compensation is still applied 288 * to the rate of rotation (angular speeds). 289 * </p> 290 * <p> See {@link android.hardware.SensorEvent#values SensorEvent.values} for more 291 * details. 292 */ 293 public static final int TYPE_GYROSCOPE_UNCALIBRATED = 16; 294 295 /** 296 * A constant string describing an uncalibrated gyroscope sensor type. 297 * 298 * @see #TYPE_GYROSCOPE_UNCALIBRATED 299 */ 300 public static final String STRING_TYPE_GYROSCOPE_UNCALIBRATED = 301 "android.sensor.gyroscope_uncalibrated"; 302 303 /** 304 * A constant describing a significant motion trigger sensor. 305 * <p> 306 * It triggers when an event occurs and then automatically disables 307 * itself. The sensor continues to operate while the device is asleep 308 * and will automatically wake the device to notify when significant 309 * motion is detected. The application does not need to hold any wake 310 * locks for this sensor to trigger. 311 * <p>See {@link TriggerEvent} for more details. 312 */ 313 public static final int TYPE_SIGNIFICANT_MOTION = 17; 314 315 /** 316 * A constant string describing a significant motion trigger sensor. 317 * 318 * @see #TYPE_SIGNIFICANT_MOTION 319 */ 320 public static final String STRING_TYPE_SIGNIFICANT_MOTION = 321 "android.sensor.significant_motion"; 322 323 /** 324 * A constant describing a step detector sensor. 325 * <p> 326 * A sensor of this type triggers an event each time a step is taken by the user. The only 327 * allowed value to return is 1.0 and an event is generated for each step. Like with any other 328 * event, the timestamp indicates when the event (here the step) occurred, this corresponds to 329 * when the foot hit the ground, generating a high variation in acceleration. 330 * <p> 331 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 332 */ 333 public static final int TYPE_STEP_DETECTOR = 18; 334 335 /** 336 * A constant string describing a step detector sensor. 337 * 338 * @see #TYPE_STEP_DETECTOR 339 */ 340 public static final String STRING_TYPE_STEP_DETECTOR = "android.sensor.step_detector"; 341 342 /** 343 * A constant describing a step counter sensor. 344 * <p> 345 * A sensor of this type returns the number of steps taken by the user since the last reboot 346 * while activated. The value is returned as a float (with the fractional part set to zero) and 347 * is reset to zero only on a system reboot. The timestamp of the event is set to the time when 348 * the first step for that event was taken. This sensor is implemented in hardware and is 349 * expected to be low power. 350 * <p> 351 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 352 */ 353 public static final int TYPE_STEP_COUNTER = 19; 354 355 /** 356 * A constant string describing a step counter sensor. 357 * 358 * @see #TYPE_STEP_COUNTER 359 */ 360 public static final String STRING_TYPE_STEP_COUNTER = "android.sensor.step_counter"; 361 362 /** 363 * A constant describing a geo-magnetic rotation vector. 364 * <p> 365 * Similar to {@link #TYPE_ROTATION_VECTOR}, but using a magnetometer instead of using a 366 * gyroscope. This sensor uses lower power than the other rotation vectors, because it doesn't 367 * use the gyroscope. However, it is more noisy and will work best outdoors. 368 * <p> 369 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 370 */ 371 public static final int TYPE_GEOMAGNETIC_ROTATION_VECTOR = 20; 372 373 /** 374 * A constant string describing a geo-magnetic rotation vector. 375 * 376 * @see #TYPE_GEOMAGNETIC_ROTATION_VECTOR 377 */ 378 public static final String STRING_TYPE_GEOMAGNETIC_ROTATION_VECTOR = 379 "android.sensor.geomagnetic_rotation_vector"; 380 381 /** 382 * A constant describing a heart rate monitor. 383 * <p> 384 * A sensor that measures the heart rate in beats per minute. 385 * <p> 386 * value[0] represents the beats per minute when the measurement was taken. 387 * value[0] is 0 if the heart rate monitor could not measure the rate or the 388 * rate is 0 beat per minute. 389 */ 390 public static final int TYPE_HEART_RATE = 21; 391 392 /** 393 * A constant string describing a heart rate monitor. 394 * 395 * @see #TYPE_HEART_RATE 396 */ 397 public static final String STRING_TYPE_HEART_RATE = "android.sensor.heart_rate"; 398 399 /** 400 * A constant describing all sensor types. 401 */ 402 public static final int TYPE_ALL = -1; 403 404 /* Reporting mode constants for sensors. Each sensor will have exactly one 405 reporting mode associated with it. */ 406 // Events are reported at a constant rate. 407 static int REPORTING_MODE_CONTINUOUS = 1; 408 409 // Events are reported only when the value changes. 410 static int REPORTING_MODE_ON_CHANGE = 2; 411 412 // Upon detection of an event, the sensor deactivates itself and then sends a single event. 413 static int REPORTING_MODE_ONE_SHOT = 3; 414 415 // TODO(): The following arrays are fragile and error-prone. This needs to be refactored. 416 417 // Note: This needs to be updated, whenever a new sensor is added. 418 // Holds the reporting mode and maximum length of the values array 419 // associated with 420 // {@link SensorEvent} or {@link TriggerEvent} for the Sensor 421 private static final int[] sSensorReportingModes = { 422 0, 0, // padding because sensor types start at 1 423 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_ACCELEROMETER 424 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_GEOMAGNETIC_FIELD 425 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_ORIENTATION 426 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_GYROSCOPE 427 REPORTING_MODE_ON_CHANGE, 3, // SENSOR_TYPE_LIGHT 428 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_PRESSURE 429 REPORTING_MODE_ON_CHANGE, 3, // SENSOR_TYPE_TEMPERATURE 430 REPORTING_MODE_ON_CHANGE, 3, // SENSOR_TYPE_PROXIMITY 431 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_GRAVITY 432 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_LINEAR_ACCELERATION 433 REPORTING_MODE_CONTINUOUS, 5, // SENSOR_TYPE_ROTATION_VECTOR 434 REPORTING_MODE_ON_CHANGE, 3, // SENSOR_TYPE_RELATIVE_HUMIDITY 435 REPORTING_MODE_ON_CHANGE, 3, // SENSOR_TYPE_AMBIENT_TEMPERATURE 436 REPORTING_MODE_CONTINUOUS, 6, // SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED 437 REPORTING_MODE_CONTINUOUS, 4, // SENSOR_TYPE_GAME_ROTATION_VECTOR 438 REPORTING_MODE_CONTINUOUS, 6, // SENSOR_TYPE_GYROSCOPE_UNCALIBRATED 439 REPORTING_MODE_ONE_SHOT, 1, // SENSOR_TYPE_SIGNIFICANT_MOTION 440 // added post 4.3 441 REPORTING_MODE_ON_CHANGE, 1, // SENSOR_TYPE_STEP_DETECTOR 442 REPORTING_MODE_ON_CHANGE, 1, // SENSOR_TYPE_STEP_COUNTER 443 REPORTING_MODE_CONTINUOUS, 5, // SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR 444 REPORTING_MODE_ON_CHANGE, 1 // SENSOR_TYPE_HEART_RATE_MONITOR 445 }; 446 447 static int getReportingMode(Sensor sensor) { 448 int offset = sensor.mType * 2; 449 if (offset >= sSensorReportingModes.length) { 450 // we don't know about this sensor, so this is probably a 451 // vendor-defined sensor, in that case, we figure out the reporting 452 // mode from the sensor meta-data. 453 int minDelay = sensor.mMinDelay; 454 if (minDelay == 0) { 455 return REPORTING_MODE_ON_CHANGE; 456 } else if (minDelay < 0) { 457 return REPORTING_MODE_ONE_SHOT; 458 } else { 459 return REPORTING_MODE_CONTINUOUS; 460 } 461 } 462 return sSensorReportingModes[offset]; 463 } 464 465 static int getMaxLengthValuesArray(Sensor sensor, int sdkLevel) { 466 int type = sensor.mType; 467 // RotationVector length has changed to 3 to 5 for API level 18 468 // Set it to 3 for backward compatibility. 469 if (type == Sensor.TYPE_ROTATION_VECTOR && 470 sdkLevel <= Build.VERSION_CODES.JELLY_BEAN_MR1) { 471 return 3; 472 } 473 int offset = type * 2 + 1; 474 if (offset >= sSensorReportingModes.length) { 475 // we don't know about this sensor, so this is probably a 476 // vendor-defined sensor, in that case, we don't know how many value 477 // it has 478 // so we return the maximum and assume the app will know. 479 // FIXME: sensor HAL should advertise how much data is returned per 480 // sensor 481 return 16; 482 } 483 return sSensorReportingModes[offset]; 484 } 485 486 /* Some of these fields are set only by the native bindings in 487 * SensorManager. 488 */ 489 private String mName; 490 private String mVendor; 491 private int mVersion; 492 private int mHandle; 493 private int mType; 494 private float mMaxRange; 495 private float mResolution; 496 private float mPower; 497 private int mMinDelay; 498 private int mFifoReservedEventCount; 499 private int mFifoMaxEventCount; 500 private String mStringType; 501 private String mRequiredPermission; 502 503 Sensor() { 504 } 505 506 /** 507 * @return name string of the sensor. 508 */ 509 public String getName() { 510 return mName; 511 } 512 513 /** 514 * @return vendor string of this sensor. 515 */ 516 public String getVendor() { 517 return mVendor; 518 } 519 520 /** 521 * @return generic type of this sensor. 522 */ 523 public int getType() { 524 return mType; 525 } 526 527 /** 528 * @return version of the sensor's module. 529 */ 530 public int getVersion() { 531 return mVersion; 532 } 533 534 /** 535 * @return maximum range of the sensor in the sensor's unit. 536 */ 537 public float getMaximumRange() { 538 return mMaxRange; 539 } 540 541 /** 542 * @return resolution of the sensor in the sensor's unit. 543 */ 544 public float getResolution() { 545 return mResolution; 546 } 547 548 /** 549 * @return the power in mA used by this sensor while in use 550 */ 551 public float getPower() { 552 return mPower; 553 } 554 555 /** 556 * @return the minimum delay allowed between two events in microsecond 557 * or zero if this sensor only returns a value when the data it's measuring 558 * changes. 559 */ 560 public int getMinDelay() { 561 return mMinDelay; 562 } 563 564 /** 565 * @return Number of events reserved for this sensor in the batch mode FIFO. This gives a 566 * guarantee on the minimum number of events that can be batched. 567 */ 568 public int getFifoReservedEventCount() { 569 return mFifoReservedEventCount; 570 } 571 572 /** 573 * @return Maximum number of events of this sensor that could be batched. If this value is zero 574 * it indicates that batch mode is not supported for this sensor. If other applications 575 * registered to batched sensors, the actual number of events that can be batched might be 576 * smaller because the hardware FiFo will be partially used to batch the other sensors. 577 */ 578 public int getFifoMaxEventCount() { 579 return mFifoMaxEventCount; 580 } 581 582 /** 583 * @return The type of this sensor as a string. 584 */ 585 public String getStringType() { 586 return mStringType; 587 } 588 589 /** 590 * @return The permission required to access this sensor. If empty, no permission is required. 591 */ 592 public String getRequiredPermission() { 593 return mRequiredPermission; 594 } 595 596 /** @hide */ 597 public int getHandle() { 598 return mHandle; 599 } 600 601 void setRange(float max, float res) { 602 mMaxRange = max; 603 mResolution = res; 604 } 605 606 @Override 607 public String toString() { 608 return "{Sensor name=\"" + mName + "\", vendor=\"" + mVendor + "\", version=" + mVersion 609 + ", type=" + mType + ", maxRange=" + mMaxRange + ", resolution=" + mResolution 610 + ", power=" + mPower + ", minDelay=" + mMinDelay + "}"; 611 } 612} 613