Sensor.java revision 1f9b32f006f7c506d9df5bf73294710665746397
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. This is a wake up sensor. 146 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 147 * for more details. 148 * @see #isWakeUpSensor() 149 */ 150 public static final int TYPE_PROXIMITY = 8; 151 152 /** 153 * A constant string describing a proximity sensor type. 154 * 155 * @see #TYPE_PROXIMITY 156 */ 157 public static final String STRING_TYPE_PROXIMITY = "android.sensor.proximity"; 158 159 /** 160 * A constant describing a gravity sensor type. 161 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 162 * for more details. 163 */ 164 public static final int TYPE_GRAVITY = 9; 165 166 /** 167 * A constant string describing a gravity sensor type. 168 * 169 * @see #TYPE_GRAVITY 170 */ 171 public static final String STRING_TYPE_GRAVITY = "android.sensor.gravity"; 172 173 /** 174 * A constant describing a linear acceleration sensor type. 175 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 176 * for more details. 177 */ 178 public static final int TYPE_LINEAR_ACCELERATION = 10; 179 180 /** 181 * A constant string describing a linear acceleration sensor type. 182 * 183 * @see #TYPE_LINEAR_ACCELERATION 184 */ 185 public static final String STRING_TYPE_LINEAR_ACCELERATION = 186 "android.sensor.linear_acceleration"; 187 188 /** 189 * A constant describing a rotation vector sensor type. 190 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 191 * for more details. 192 */ 193 public static final int TYPE_ROTATION_VECTOR = 11; 194 195 /** 196 * A constant string describing a rotation vector sensor type. 197 * 198 * @see #TYPE_ROTATION_VECTOR 199 */ 200 public static final String STRING_TYPE_ROTATION_VECTOR = "android.sensor.rotation_vector"; 201 202 /** 203 * A constant describing a relative humidity sensor type. 204 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 205 * for more details. 206 */ 207 public static final int TYPE_RELATIVE_HUMIDITY = 12; 208 209 /** 210 * A constant string describing a relative humidity sensor type 211 * 212 * @see #TYPE_RELATIVE_HUMIDITY 213 */ 214 public static final String STRING_TYPE_RELATIVE_HUMIDITY = "android.sensor.relative_humidity"; 215 216 /** 217 * A constant describing an ambient temperature sensor type. 218 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 219 * for more details. 220 */ 221 public static final int TYPE_AMBIENT_TEMPERATURE = 13; 222 223 /** 224 * A constant string describing an ambient temperature sensor type. 225 * 226 * @see #TYPE_AMBIENT_TEMPERATURE 227 */ 228 public static final String STRING_TYPE_AMBIENT_TEMPERATURE = 229 "android.sensor.ambient_temperature"; 230 231 /** 232 * A constant describing an uncalibrated magnetic field sensor type. 233 * <p> 234 * Similar to {@link #TYPE_MAGNETIC_FIELD} but the hard iron calibration (device calibration 235 * due to distortions that arise from magnetized iron, steel or permanent magnets on the 236 * device) is not considered in the given sensor values. However, such hard iron bias values 237 * are returned to you separately in the result {@link android.hardware.SensorEvent#values} 238 * so you may use them for custom calibrations. 239 * <p>Also, no periodic calibration is performed 240 * (i.e. there are no discontinuities in the data stream while using this sensor) and 241 * assumptions that the magnetic field is due to the Earth's poles is avoided, but 242 * factory calibration and temperature compensation have been performed. 243 * </p> 244 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} for more 245 * details. 246 */ 247 public static final int TYPE_MAGNETIC_FIELD_UNCALIBRATED = 14; 248 /** 249 * A constant string describing an uncalibrated magnetic field sensor type. 250 * 251 * @see #TYPE_MAGNETIC_FIELD_UNCALIBRATED 252 */ 253 public static final String STRING_TYPE_MAGNETIC_FIELD_UNCALIBRATED = 254 "android.sensor.magnetic_field_uncalibrated"; 255 256 /** 257 * A constant describing an uncalibrated rotation vector sensor type. 258 * <p>Identical to {@link #TYPE_ROTATION_VECTOR} except that it doesn't 259 * use the geomagnetic field. Therefore the Y axis doesn't 260 * point north, but instead to some other reference, that reference is 261 * allowed to drift by the same order of magnitude as the gyroscope 262 * drift around the Z axis. 263 * <p> 264 * In the ideal case, a phone rotated and returning to the same real-world 265 * orientation should report the same game rotation vector 266 * (without using the earth's geomagnetic field). However, the orientation 267 * may drift somewhat over time. 268 * </p> 269 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} for more 270 * details. 271 */ 272 public static final int TYPE_GAME_ROTATION_VECTOR = 15; 273 274 /** 275 * A constant string describing an uncalibrated rotation vector sensor type. 276 * 277 * @see #TYPE_GAME_ROTATION_VECTOR 278 */ 279 public static final String STRING_TYPE_GAME_ROTATION_VECTOR = 280 "android.sensor.game_rotation_vector"; 281 282 /** 283 * A constant describing an uncalibrated gyroscope sensor type. 284 * <p>Similar to {@link #TYPE_GYROSCOPE} but no gyro-drift compensation has been performed 285 * to adjust the given sensor values. However, such gyro-drift bias values 286 * are returned to you separately in the result {@link android.hardware.SensorEvent#values} 287 * so you may use them for custom calibrations. 288 * <p>Factory calibration and temperature compensation is still applied 289 * to the rate of rotation (angular speeds). 290 * </p> 291 * <p> See {@link android.hardware.SensorEvent#values SensorEvent.values} for more 292 * details. 293 */ 294 public static final int TYPE_GYROSCOPE_UNCALIBRATED = 16; 295 296 /** 297 * A constant string describing an uncalibrated gyroscope sensor type. 298 * 299 * @see #TYPE_GYROSCOPE_UNCALIBRATED 300 */ 301 public static final String STRING_TYPE_GYROSCOPE_UNCALIBRATED = 302 "android.sensor.gyroscope_uncalibrated"; 303 304 /** 305 * A constant describing a significant motion trigger sensor. 306 * <p> 307 * It triggers when an event occurs and then automatically disables 308 * itself. The sensor continues to operate while the device is asleep 309 * and will automatically wake the device to notify when significant 310 * motion is detected. The application does not need to hold any wake 311 * locks for this sensor to trigger. This is a wake up sensor. 312 * <p>See {@link TriggerEvent} for more details. 313 * 314 * @see #isWakeUpSensor() 315 */ 316 public static final int TYPE_SIGNIFICANT_MOTION = 17; 317 318 /** 319 * A constant string describing a significant motion trigger sensor. 320 * 321 * @see #TYPE_SIGNIFICANT_MOTION 322 */ 323 public static final String STRING_TYPE_SIGNIFICANT_MOTION = 324 "android.sensor.significant_motion"; 325 326 /** 327 * A constant describing a step detector sensor. 328 * <p> 329 * A sensor of this type triggers an event each time a step is taken by the user. The only 330 * allowed value to return is 1.0 and an event is generated for each step. Like with any other 331 * event, the timestamp indicates when the event (here the step) occurred, this corresponds to 332 * when the foot hit the ground, generating a high variation in acceleration. This sensor is 333 * only for detecting every individual step as soon as it is taken, for example to perform dead 334 * reckoning. If you only need aggregate number of steps taken over a period of time, register 335 * for {@link #TYPE_STEP_COUNTER} instead. It is defined as a 336 * {@link Sensor#REPORTING_MODE_SPECIAL_TRIGGER} sensor. 337 * <p> 338 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 339 */ 340 public static final int TYPE_STEP_DETECTOR = 18; 341 342 /** 343 * A constant string describing a step detector sensor. 344 * 345 * @see #TYPE_STEP_DETECTOR 346 */ 347 public static final String STRING_TYPE_STEP_DETECTOR = "android.sensor.step_detector"; 348 349 /** 350 * A constant describing a step counter sensor. 351 * <p> 352 * A sensor of this type returns the number of steps taken by the user since the last reboot 353 * while activated. The value is returned as a float (with the fractional part set to zero) and 354 * is reset to zero only on a system reboot. The timestamp of the event is set to the time when 355 * the last step for that event was taken. This sensor is implemented in hardware and is 356 * expected to be low power. If you want to continuously track the number of steps over a long 357 * period of time, do NOT unregister for this sensor, so that it keeps counting steps in the 358 * background even when the AP is in suspend mode and report the aggregate count when the AP 359 * is awake. Application needs to stay registered for this sensor because step counter does not 360 * count steps if it is not activated. This sensor is ideal for fitness tracking applications. 361 * It is defined as an {@link Sensor#REPORTING_MODE_ON_CHANGE} sensor. 362 * <p> 363 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 364 */ 365 public static final int TYPE_STEP_COUNTER = 19; 366 367 /** 368 * A constant string describing a step counter sensor. 369 * 370 * @see #TYPE_STEP_COUNTER 371 */ 372 public static final String STRING_TYPE_STEP_COUNTER = "android.sensor.step_counter"; 373 374 /** 375 * A constant describing a geo-magnetic rotation vector. 376 * <p> 377 * Similar to {@link #TYPE_ROTATION_VECTOR}, but using a magnetometer instead of using a 378 * gyroscope. This sensor uses lower power than the other rotation vectors, because it doesn't 379 * use the gyroscope. However, it is more noisy and will work best outdoors. 380 * <p> 381 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 382 */ 383 public static final int TYPE_GEOMAGNETIC_ROTATION_VECTOR = 20; 384 385 /** 386 * A constant string describing a geo-magnetic rotation vector. 387 * 388 * @see #TYPE_GEOMAGNETIC_ROTATION_VECTOR 389 */ 390 public static final String STRING_TYPE_GEOMAGNETIC_ROTATION_VECTOR = 391 "android.sensor.geomagnetic_rotation_vector"; 392 393 /** 394 * A constant describing a heart rate monitor. 395 * <p> 396 * The reported value is the heart rate in beats per minute. 397 * <p> 398 * The reported accuracy represents the status of the monitor during the reading. See the 399 * {@code SENSOR_STATUS_*} constants in {@link android.hardware.SensorManager SensorManager} 400 * for more details on accuracy/status values. In particular, when the accuracy is 401 * {@code SENSOR_STATUS_UNRELIABLE} or {@code SENSOR_STATUS_NO_CONTACT}, the heart rate 402 * value should be discarded. 403 * <p> 404 * This sensor requires permission {@code android.permission.BODY_SENSORS}. 405 * It will not be returned by {@code SensorManager.getSensorsList} nor 406 * {@code SensorManager.getDefaultSensor} if the application doesn't have this permission. 407 */ 408 public static final int TYPE_HEART_RATE = 21; 409 410 /** 411 * A constant string describing a heart rate monitor. 412 * 413 * @see #TYPE_HEART_RATE 414 */ 415 public static final String STRING_TYPE_HEART_RATE = "android.sensor.heart_rate"; 416 417 /** 418 * A sensor of this type generates an event each time a tilt event is detected. A tilt event 419 * is generated if the direction of the 2-seconds window average gravity changed by at 420 * least 35 degrees since the activation of the sensor. It is a wake up sensor. 421 * 422 * @hide 423 * @see #isWakeUpSensor() 424 */ 425 public static final int TYPE_TILT_DETECTOR = 22; 426 427 /** 428 * A constant string describing a wake up tilt detector sensor type. 429 * 430 * @hide 431 * @see #TYPE_WAKE_UP_TILT_DETECTOR 432 */ 433 public static final String SENSOR_STRING_TYPE_TILT_DETECTOR = 434 "android.sensor.tilt_detector"; 435 436 /** 437 * A constant describing a wake gesture sensor. 438 * <p> 439 * Wake gesture sensors enable waking up the device based on a device specific motion. 440 * <p> 441 * When this sensor triggers, the device behaves as if the power button was pressed, turning the 442 * screen on. This behavior (turning on the screen when this sensor triggers) might be 443 * deactivated by the user in the device settings. Changes in settings do not impact the 444 * behavior of the sensor: only whether the framework turns the screen on when it triggers. 445 * <p> 446 * The actual gesture to be detected is not specified, and can be chosen by the manufacturer of 447 * the device. This sensor must be low power, as it is likely to be activated 24/7. 448 * Values of events created by this sensors should not be used. 449 * 450 * @see #isWakeUpSensor() 451 * @hide This sensor is expected to only be used by the system ui 452 */ 453 public static final int TYPE_WAKE_GESTURE = 23; 454 455 /** 456 * A constant string describing a wake gesture sensor. 457 * 458 * @hide This sensor is expected to only be used by the system ui 459 * @see #TYPE_WAKE_GESTURE 460 */ 461 public static final String STRING_TYPE_WAKE_GESTURE = "android.sensor.wake_gesture"; 462 463 /** 464 * A constant describing a wake gesture sensor. 465 * <p> 466 * A sensor enabling briefly turning the screen on to enable the user to 467 * glance content on screen based on a specific motion. The device should 468 * turn the screen off after a few moments. 469 * <p> 470 * When this sensor triggers, the device turns the screen on momentarily 471 * to allow the user to glance notifications or other content while the 472 * device remains locked in a non-interactive state (dozing). This behavior 473 * (briefly turning on the screen when this sensor triggers) might be deactivated 474 * by the user in the device settings. Changes in settings do not impact the 475 * behavior of the sensor: only whether the framework briefly turns the screen on 476 * when it triggers. 477 * <p> 478 * The actual gesture to be detected is not specified, and can be chosen by the manufacturer of 479 * the device. This sensor must be low power, as it is likely to be activated 24/7. 480 * Values of events created by this sensors should not be used. 481 * 482 * @see #isWakeUpSensor() 483 * @hide This sensor is expected to only be used by the system ui 484 */ 485 public static final int TYPE_GLANCE_GESTURE = 24; 486 487 /** 488 * A constant string describing a wake gesture sensor. 489 * 490 * @hide This sensor is expected to only be used by the system ui 491 * @see #TYPE_GLANCE_GESTURE 492 */ 493 public static final String STRING_TYPE_GLANCE_GESTURE = "android.sensor.glance_gesture"; 494 495 /** 496 * A constant describing a pick up sensor. 497 * 498 * A sensor of this type triggers when the device is picked up regardless of wherever it was 499 * before (desk, pocket, bag). The only allowed return value is 1.0. This sensor deactivates 500 * itself immediately after it triggers. 501 * 502 * @hide Expected to be used internally for always on display. 503 */ 504 public static final int TYPE_PICK_UP_GESTURE = 25; 505 506 /** 507 * A constant string describing a pick up sensor. 508 * 509 * @hide This sensor is expected to be used internally for always on display. 510 * @see #TYPE_PICK_UP_GESTURE 511 */ 512 public static final String STRING_TYPE_PICK_UP_GESTURE = "android.sensor.pick_up_gesture"; 513 514 /** 515 * A constant describing all sensor types. 516 */ 517 public static final int TYPE_ALL = -1; 518 519 // If this flag is set, the sensor defined as a wake up sensor. This field and REPORTING_MODE_* 520 // constants are defined as flags in sensors.h. Modify at both places if needed. 521 private static final int SENSOR_FLAG_WAKE_UP_SENSOR = 1; 522 523 /** 524 * Events are reported at a constant rate which is set by the rate parameter of 525 * {@link SensorManager#registerListener(SensorEventListener, Sensor, int)}. Note: If other 526 * applications are requesting a higher rate, the sensor data might be delivered at faster rates 527 * than requested. 528 */ 529 public static final int REPORTING_MODE_CONTINUOUS = 0; 530 531 /** 532 * Events are reported only when the value changes. Event delivery rate can be limited by 533 * setting appropriate value for rate parameter of 534 * {@link SensorManager#registerListener(SensorEventListener, Sensor, int)} Note: If other 535 * applications are requesting a higher rate, the sensor data might be delivered at faster rates 536 * than requested. 537 */ 538 public static final int REPORTING_MODE_ON_CHANGE = 1; 539 540 /** 541 * Events are reported in one-shot mode. Upon detection of an event, the sensor deactivates 542 * itself and then sends a single event. Sensors of this reporting mode must be registered to 543 * using {@link SensorManager#requestTriggerSensor(TriggerEventListener, Sensor)}. 544 */ 545 public static final int REPORTING_MODE_ONE_SHOT = 2; 546 547 /** 548 * Events are reported as described in the description of the sensor. The rate passed to 549 * registerListener might not have an impact on the rate of event delivery. See the sensor 550 * definition for more information on when and how frequently the events are reported. For 551 * example, step detectors report events when a step is detected. 552 * 553 * @see SensorManager#registerListener(SensorEventListener, Sensor, int, int) 554 */ 555 public static final int REPORTING_MODE_SPECIAL_TRIGGER = 3; 556 557 // Mask for the LSB 2nd, 3rd and fourth bits. 558 private static final int REPORTING_MODE_MASK = 0xE; 559 private static final int REPORTING_MODE_SHIFT = 1; 560 561 // TODO(): The following arrays are fragile and error-prone. This needs to be refactored. 562 563 // Note: This needs to be updated, whenever a new sensor is added. 564 // Holds the reporting mode and maximum length of the values array 565 // associated with 566 // {@link SensorEvent} or {@link TriggerEvent} for the Sensor 567 private static final int[] sSensorReportingModes = { 568 0, // padding because sensor types start at 1 569 3, // SENSOR_TYPE_ACCELEROMETER 570 3, // SENSOR_TYPE_GEOMAGNETIC_FIELD 571 3, // SENSOR_TYPE_ORIENTATION 572 3, // SENSOR_TYPE_GYROSCOPE 573 3, // SENSOR_TYPE_LIGHT 574 3, // SENSOR_TYPE_PRESSURE 575 3, // SENSOR_TYPE_TEMPERATURE 576 3, // SENSOR_TYPE_PROXIMITY 577 3, // SENSOR_TYPE_GRAVITY 578 3, // SENSOR_TYPE_LINEAR_ACCELERATION 579 5, // SENSOR_TYPE_ROTATION_VECTOR 580 3, // SENSOR_TYPE_RELATIVE_HUMIDITY 581 3, // SENSOR_TYPE_AMBIENT_TEMPERATURE 582 6, // SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED 583 4, // SENSOR_TYPE_GAME_ROTATION_VECTOR 584 6, // SENSOR_TYPE_GYROSCOPE_UNCALIBRATED 585 1, // SENSOR_TYPE_SIGNIFICANT_MOTION 586 1, // SENSOR_TYPE_STEP_DETECTOR 587 1, // SENSOR_TYPE_STEP_COUNTER 588 5, // SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR 589 1, // SENSOR_TYPE_HEART_RATE_MONITOR 590 1, // SENSOR_TYPE_WAKE_UP_TILT_DETECTOR 591 1, // SENSOR_TYPE_WAKE_GESTURE 592 1, // SENSOR_TYPE_GLANCE_GESTURE 593 1, // SENSOR_TYPE_PICK_UP_GESTURE 594 }; 595 596 /** 597 * Each sensor has exactly one reporting mode associated with it. This method returns the 598 * reporting mode constant for this sensor type. 599 * 600 * @return Reporting mode for the input sensor, one of REPORTING_MODE_* constants. 601 * @see #REPORTING_MODE_CONTINUOUS 602 * @see #REPORTING_MODE_ON_CHANGE 603 * @see #REPORTING_MODE_ONE_SHOT 604 * @see #REPORTING_MODE_SPECIAL_TRIGGER 605 */ 606 public int getReportingMode() { 607 return ((mFlags & REPORTING_MODE_MASK) >> REPORTING_MODE_SHIFT); 608 } 609 610 static int getMaxLengthValuesArray(Sensor sensor, int sdkLevel) { 611 // RotationVector length has changed to 3 to 5 for API level 18 612 // Set it to 3 for backward compatibility. 613 if (sensor.mType == Sensor.TYPE_ROTATION_VECTOR && 614 sdkLevel <= Build.VERSION_CODES.JELLY_BEAN_MR1) { 615 return 3; 616 } 617 int offset = sensor.mType; 618 if (offset >= sSensorReportingModes.length) { 619 // we don't know about this sensor, so this is probably a 620 // vendor-defined sensor, in that case, we don't know how many value 621 // it has 622 // so we return the maximum and assume the app will know. 623 // FIXME: sensor HAL should advertise how much data is returned per 624 // sensor 625 return 16; 626 } 627 return sSensorReportingModes[offset]; 628 } 629 630 /* Some of these fields are set only by the native bindings in 631 * SensorManager. 632 */ 633 private String mName; 634 private String mVendor; 635 private int mVersion; 636 private int mHandle; 637 private int mType; 638 private float mMaxRange; 639 private float mResolution; 640 private float mPower; 641 private int mMinDelay; 642 private int mFifoReservedEventCount; 643 private int mFifoMaxEventCount; 644 private String mStringType; 645 private String mRequiredPermission; 646 private int mMaxDelay; 647 private int mFlags; 648 649 Sensor() { 650 } 651 652 /** 653 * @return name string of the sensor. 654 */ 655 public String getName() { 656 return mName; 657 } 658 659 /** 660 * @return vendor string of this sensor. 661 */ 662 public String getVendor() { 663 return mVendor; 664 } 665 666 /** 667 * @return generic type of this sensor. 668 */ 669 public int getType() { 670 return mType; 671 } 672 673 /** 674 * @return version of the sensor's module. 675 */ 676 public int getVersion() { 677 return mVersion; 678 } 679 680 /** 681 * @return maximum range of the sensor in the sensor's unit. 682 */ 683 public float getMaximumRange() { 684 return mMaxRange; 685 } 686 687 /** 688 * @return resolution of the sensor in the sensor's unit. 689 */ 690 public float getResolution() { 691 return mResolution; 692 } 693 694 /** 695 * @return the power in mA used by this sensor while in use 696 */ 697 public float getPower() { 698 return mPower; 699 } 700 701 /** 702 * @return the minimum delay allowed between two events in microsecond 703 * or zero if this sensor only returns a value when the data it's measuring 704 * changes. 705 */ 706 public int getMinDelay() { 707 return mMinDelay; 708 } 709 710 /** 711 * @return Number of events reserved for this sensor in the batch mode FIFO. This gives a 712 * guarantee on the minimum number of events that can be batched. 713 */ 714 public int getFifoReservedEventCount() { 715 return mFifoReservedEventCount; 716 } 717 718 /** 719 * @return Maximum number of events of this sensor that could be batched. If this value is zero 720 * it indicates that batch mode is not supported for this sensor. If other applications 721 * registered to batched sensors, the actual number of events that can be batched might be 722 * smaller because the hardware FiFo will be partially used to batch the other sensors. 723 */ 724 public int getFifoMaxEventCount() { 725 return mFifoMaxEventCount; 726 } 727 728 /** 729 * @return The type of this sensor as a string. 730 */ 731 public String getStringType() { 732 return mStringType; 733 } 734 735 /** 736 * @hide 737 * @return The permission required to access this sensor. If empty, no permission is required. 738 */ 739 public String getRequiredPermission() { 740 return mRequiredPermission; 741 } 742 743 /** @hide */ 744 public int getHandle() { 745 return mHandle; 746 } 747 748 /** 749 * This value is defined only for continuous and on-change sensors. It is the delay between two 750 * sensor events corresponding to the lowest frequency that this sensor supports. When lower 751 * frequencies are requested through registerListener() the events will be generated at this 752 * frequency instead. It can be used to estimate when the batch FIFO may be full. Older devices 753 * may set this value to zero. Ignore this value in case it is negative or zero. 754 * 755 * @return The max delay for this sensor in microseconds. 756 */ 757 public int getMaxDelay() { 758 return mMaxDelay; 759 } 760 761 /** 762 * Returns true if the sensor is a wake-up sensor. 763 * <p> 764 * <b>Application Processor Power modes</b> <p> 765 * Application Processor(AP), is the processor on which applications run. When no wake lock is held 766 * and the user is not interacting with the device, this processor can enter a “Suspend” mode, 767 * reducing the power consumption by 10 times or more. 768 * </p> 769 * <p> 770 * <b>Non-wake-up sensors</b> <p> 771 * Non-wake-up sensors are sensors that do not wake the AP out of suspend to report data. While 772 * the AP is in suspend mode, the sensors continue to function and generate events, which are 773 * put in a hardware FIFO. The events in the FIFO are delivered to the application when the AP 774 * wakes up. If the FIFO was too small to store all events generated while the AP was in 775 * suspend mode, the older events are lost: the oldest data is dropped to accommodate the newer 776 * data. In the extreme case where the FIFO is non-existent {@code maxFifoEventCount() == 0}, 777 * all events generated while the AP was in suspend mode are lost. Applications using 778 * non-wake-up sensors should usually: 779 * <ul> 780 * <li>Either unregister from the sensors when they do not need them, usually in the activity’s 781 * {@code onPause} method. This is the most common case. 782 * <li>Or realize that the sensors are consuming some power while the AP is in suspend mode and 783 * that even then, some events might be lost. 784 * </ul> 785 * </p> 786 * <p> 787 * <b>Wake-up sensors</b> <p> 788 * In opposition to non-wake-up sensors, wake-up sensors ensure that their data is delivered 789 * independently of the state of the AP. While the AP is awake, the wake-up sensors behave 790 * like non-wake-up-sensors. When the AP is asleep, wake-up sensors wake up the AP to deliver 791 * events. That is, the AP will wake up and the sensor will deliver the events before the 792 * maximum reporting latency is elapsed or the hardware FIFO gets full. See {@link 793 * SensorManager#registerListener(SensorEventListener, Sensor, int, int)} for more details. 794 * </p> 795 * 796 * @return <code>true</code> if this is a wake-up sensor, <code>false</code> otherwise. 797 */ 798 public boolean isWakeUpSensor() { 799 return (mFlags & SENSOR_FLAG_WAKE_UP_SENSOR) != 0; 800 } 801 802 void setRange(float max, float res) { 803 mMaxRange = max; 804 mResolution = res; 805 } 806 807 @Override 808 public String toString() { 809 return "{Sensor name=\"" + mName + "\", vendor=\"" + mVendor + "\", version=" + mVersion 810 + ", type=" + mType + ", maxRange=" + mMaxRange + ", resolution=" + mResolution 811 + ", power=" + mPower + ", minDelay=" + mMinDelay + "}"; 812 } 813} 814