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 18 package android.hardware; 19 20 import android.annotation.SystemApi; 21 import android.os.Build; 22 23 /** 24 * Class representing a sensor. Use {@link SensorManager#getSensorList} to get 25 * the list of available Sensors. 26 * 27 * @see SensorManager 28 * @see SensorEventListener 29 * @see SensorEvent 30 * 31 */ 32 public final class Sensor { 33 34 /** 35 * A constant describing an accelerometer sensor type. 36 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 37 * for more details. 38 */ 39 public static final int TYPE_ACCELEROMETER = 1; 40 41 /** 42 * A constant string describing an accelerometer sensor type. 43 * 44 * @see #TYPE_ACCELEROMETER 45 */ 46 public static final String STRING_TYPE_ACCELEROMETER = "android.sensor.accelerometer"; 47 48 /** 49 * A constant describing a magnetic field sensor type. 50 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 51 * for more details. 52 */ 53 public static final int TYPE_MAGNETIC_FIELD = 2; 54 55 /** 56 * A constant string describing a magnetic field sensor type. 57 * 58 * @see #TYPE_MAGNETIC_FIELD 59 */ 60 public static final String STRING_TYPE_MAGNETIC_FIELD = "android.sensor.magnetic_field"; 61 62 /** 63 * A constant describing an orientation sensor type. 64 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 65 * for more details. 66 * 67 * @deprecated use {@link android.hardware.SensorManager#getOrientation 68 * SensorManager.getOrientation()} instead. 69 */ 70 @Deprecated 71 public static final int TYPE_ORIENTATION = 3; 72 73 /** 74 * A constant string describing an orientation sensor type. 75 * 76 * @see #TYPE_ORIENTATION 77 * @deprecated use {@link android.hardware.SensorManager#getOrientation 78 * SensorManager.getOrientation()} instead. 79 */ 80 @Deprecated 81 public static final String STRING_TYPE_ORIENTATION = "android.sensor.orientation"; 82 83 /** 84 * A constant describing a gyroscope sensor type. 85 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 86 * for more details. */ 87 public static final int TYPE_GYROSCOPE = 4; 88 89 /** 90 * A constant string describing a gyroscope sensor type. 91 * 92 * @see #TYPE_GYROSCOPE 93 */ 94 public static final String STRING_TYPE_GYROSCOPE = "android.sensor.gyroscope"; 95 96 /** 97 * A constant describing a light sensor type. 98 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 99 * for more details. 100 */ 101 public static final int TYPE_LIGHT = 5; 102 103 /** 104 * A constant string describing a light sensor type. 105 * 106 * @see #TYPE_LIGHT 107 */ 108 public static final String STRING_TYPE_LIGHT = "android.sensor.light"; 109 110 /** 111 * A constant describing a pressure sensor type. 112 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 113 * for more details. 114 */ 115 public static final int TYPE_PRESSURE = 6; 116 117 /** 118 * A constant string describing a pressure sensor type. 119 * 120 * @see #TYPE_PRESSURE 121 */ 122 public static final String STRING_TYPE_PRESSURE = "android.sensor.pressure"; 123 124 /** 125 * A constant describing a temperature sensor type 126 * 127 * @deprecated use 128 * {@link android.hardware.Sensor#TYPE_AMBIENT_TEMPERATURE 129 * Sensor.TYPE_AMBIENT_TEMPERATURE} instead. 130 */ 131 @Deprecated 132 public static final int TYPE_TEMPERATURE = 7; 133 134 /** 135 * A constant string describing a temperature sensor type 136 * 137 * @see #TYPE_TEMPERATURE 138 * @deprecated use 139 * {@link android.hardware.Sensor#STRING_TYPE_AMBIENT_TEMPERATURE 140 * Sensor.STRING_TYPE_AMBIENT_TEMPERATURE} instead. 141 */ 142 @Deprecated 143 public static final String STRING_TYPE_TEMPERATURE = "android.sensor.temperature"; 144 145 /** 146 * A constant describing a proximity sensor type. This is a wake up sensor. 147 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 148 * for more details. 149 * @see #isWakeUpSensor() 150 */ 151 public static final int TYPE_PROXIMITY = 8; 152 153 /** 154 * A constant string describing a proximity sensor type. 155 * 156 * @see #TYPE_PROXIMITY 157 */ 158 public static final String STRING_TYPE_PROXIMITY = "android.sensor.proximity"; 159 160 /** 161 * A constant describing a gravity sensor type. 162 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 163 * for more details. 164 */ 165 public static final int TYPE_GRAVITY = 9; 166 167 /** 168 * A constant string describing a gravity sensor type. 169 * 170 * @see #TYPE_GRAVITY 171 */ 172 public static final String STRING_TYPE_GRAVITY = "android.sensor.gravity"; 173 174 /** 175 * A constant describing a linear acceleration sensor type. 176 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 177 * for more details. 178 */ 179 public static final int TYPE_LINEAR_ACCELERATION = 10; 180 181 /** 182 * A constant string describing a linear acceleration sensor type. 183 * 184 * @see #TYPE_LINEAR_ACCELERATION 185 */ 186 public static final String STRING_TYPE_LINEAR_ACCELERATION = 187 "android.sensor.linear_acceleration"; 188 189 /** 190 * A constant describing a rotation vector sensor type. 191 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 192 * for more details. 193 */ 194 public static final int TYPE_ROTATION_VECTOR = 11; 195 196 /** 197 * A constant string describing a rotation vector sensor type. 198 * 199 * @see #TYPE_ROTATION_VECTOR 200 */ 201 public static final String STRING_TYPE_ROTATION_VECTOR = "android.sensor.rotation_vector"; 202 203 /** 204 * A constant describing a relative humidity sensor type. 205 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 206 * for more details. 207 */ 208 public static final int TYPE_RELATIVE_HUMIDITY = 12; 209 210 /** 211 * A constant string describing a relative humidity sensor type 212 * 213 * @see #TYPE_RELATIVE_HUMIDITY 214 */ 215 public static final String STRING_TYPE_RELATIVE_HUMIDITY = "android.sensor.relative_humidity"; 216 217 /** 218 * A constant describing an ambient temperature sensor type. 219 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 220 * for more details. 221 */ 222 public static final int TYPE_AMBIENT_TEMPERATURE = 13; 223 224 /** 225 * A constant string describing an ambient temperature sensor type. 226 * 227 * @see #TYPE_AMBIENT_TEMPERATURE 228 */ 229 public static final String STRING_TYPE_AMBIENT_TEMPERATURE = 230 "android.sensor.ambient_temperature"; 231 232 /** 233 * A constant describing an uncalibrated magnetic field sensor type. 234 * <p> 235 * Similar to {@link #TYPE_MAGNETIC_FIELD} but the hard iron calibration (device calibration 236 * due to distortions that arise from magnetized iron, steel or permanent magnets on the 237 * device) is not considered in the given sensor values. However, such hard iron bias values 238 * are returned to you separately in the result {@link android.hardware.SensorEvent#values} 239 * so you may use them for custom calibrations. 240 * <p>Also, no periodic calibration is performed 241 * (i.e. there are no discontinuities in the data stream while using this sensor) and 242 * assumptions that the magnetic field is due to the Earth's poles is avoided, but 243 * factory calibration and temperature compensation have been performed. 244 * </p> 245 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} for more 246 * details. 247 */ 248 public static final int TYPE_MAGNETIC_FIELD_UNCALIBRATED = 14; 249 /** 250 * A constant string describing an uncalibrated magnetic field sensor type. 251 * 252 * @see #TYPE_MAGNETIC_FIELD_UNCALIBRATED 253 */ 254 public static final String STRING_TYPE_MAGNETIC_FIELD_UNCALIBRATED = 255 "android.sensor.magnetic_field_uncalibrated"; 256 257 /** 258 * A constant describing an uncalibrated rotation vector sensor type. 259 * <p>Identical to {@link #TYPE_ROTATION_VECTOR} except that it doesn't 260 * use the geomagnetic field. Therefore the Y axis doesn't 261 * point north, but instead to some other reference, that reference is 262 * allowed to drift by the same order of magnitude as the gyroscope 263 * drift around the Z axis. 264 * <p> 265 * In the ideal case, a phone rotated and returning to the same real-world 266 * orientation should report the same game rotation vector 267 * (without using the earth's geomagnetic field). However, the orientation 268 * may drift somewhat over time. 269 * </p> 270 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} for more 271 * details. 272 */ 273 public static final int TYPE_GAME_ROTATION_VECTOR = 15; 274 275 /** 276 * A constant string describing an uncalibrated rotation vector sensor type. 277 * 278 * @see #TYPE_GAME_ROTATION_VECTOR 279 */ 280 public static final String STRING_TYPE_GAME_ROTATION_VECTOR = 281 "android.sensor.game_rotation_vector"; 282 283 /** 284 * A constant describing an uncalibrated gyroscope sensor type. 285 * <p>Similar to {@link #TYPE_GYROSCOPE} but no gyro-drift compensation has been performed 286 * to adjust the given sensor values. However, such gyro-drift bias values 287 * are returned to you separately in the result {@link android.hardware.SensorEvent#values} 288 * so you may use them for custom calibrations. 289 * <p>Factory calibration and temperature compensation is still applied 290 * to the rate of rotation (angular speeds). 291 * </p> 292 * <p> See {@link android.hardware.SensorEvent#values SensorEvent.values} for more 293 * details. 294 */ 295 public static final int TYPE_GYROSCOPE_UNCALIBRATED = 16; 296 297 /** 298 * A constant string describing an uncalibrated gyroscope sensor type. 299 * 300 * @see #TYPE_GYROSCOPE_UNCALIBRATED 301 */ 302 public static final String STRING_TYPE_GYROSCOPE_UNCALIBRATED = 303 "android.sensor.gyroscope_uncalibrated"; 304 305 /** 306 * A constant describing a significant motion trigger sensor. 307 * <p> 308 * It triggers when an event occurs and then automatically disables 309 * itself. The sensor continues to operate while the device is asleep 310 * and will automatically wake the device to notify when significant 311 * motion is detected. The application does not need to hold any wake 312 * locks for this sensor to trigger. This is a wake up sensor. 313 * <p>See {@link TriggerEvent} for more details. 314 * 315 * @see #isWakeUpSensor() 316 */ 317 public static final int TYPE_SIGNIFICANT_MOTION = 17; 318 319 /** 320 * A constant string describing a significant motion trigger sensor. 321 * 322 * @see #TYPE_SIGNIFICANT_MOTION 323 */ 324 public static final String STRING_TYPE_SIGNIFICANT_MOTION = 325 "android.sensor.significant_motion"; 326 327 /** 328 * A constant describing a step detector sensor. 329 * <p> 330 * A sensor of this type triggers an event each time a step is taken by the user. The only 331 * allowed value to return is 1.0 and an event is generated for each step. Like with any other 332 * event, the timestamp indicates when the event (here the step) occurred, this corresponds to 333 * when the foot hit the ground, generating a high variation in acceleration. This sensor is 334 * only for detecting every individual step as soon as it is taken, for example to perform dead 335 * reckoning. If you only need aggregate number of steps taken over a period of time, register 336 * for {@link #TYPE_STEP_COUNTER} instead. It is defined as a 337 * {@link Sensor#REPORTING_MODE_SPECIAL_TRIGGER} sensor. 338 * <p> 339 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 340 */ 341 public static final int TYPE_STEP_DETECTOR = 18; 342 343 /** 344 * A constant string describing a step detector sensor. 345 * 346 * @see #TYPE_STEP_DETECTOR 347 */ 348 public static final String STRING_TYPE_STEP_DETECTOR = "android.sensor.step_detector"; 349 350 /** 351 * A constant describing a step counter sensor. 352 * <p> 353 * A sensor of this type returns the number of steps taken by the user since the last reboot 354 * while activated. The value is returned as a float (with the fractional part set to zero) and 355 * is reset to zero only on a system reboot. The timestamp of the event is set to the time when 356 * the last step for that event was taken. This sensor is implemented in hardware and is 357 * expected to be low power. If you want to continuously track the number of steps over a long 358 * period of time, do NOT unregister for this sensor, so that it keeps counting steps in the 359 * background even when the AP is in suspend mode and report the aggregate count when the AP 360 * is awake. Application needs to stay registered for this sensor because step counter does not 361 * count steps if it is not activated. This sensor is ideal for fitness tracking applications. 362 * It is defined as an {@link Sensor#REPORTING_MODE_ON_CHANGE} sensor. 363 * <p> 364 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 365 */ 366 public static final int TYPE_STEP_COUNTER = 19; 367 368 /** 369 * A constant string describing a step counter sensor. 370 * 371 * @see #TYPE_STEP_COUNTER 372 */ 373 public static final String STRING_TYPE_STEP_COUNTER = "android.sensor.step_counter"; 374 375 /** 376 * A constant describing a geo-magnetic rotation vector. 377 * <p> 378 * Similar to {@link #TYPE_ROTATION_VECTOR}, but using a magnetometer instead of using a 379 * gyroscope. This sensor uses lower power than the other rotation vectors, because it doesn't 380 * use the gyroscope. However, it is more noisy and will work best outdoors. 381 * <p> 382 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 383 */ 384 public static final int TYPE_GEOMAGNETIC_ROTATION_VECTOR = 20; 385 386 /** 387 * A constant string describing a geo-magnetic rotation vector. 388 * 389 * @see #TYPE_GEOMAGNETIC_ROTATION_VECTOR 390 */ 391 public static final String STRING_TYPE_GEOMAGNETIC_ROTATION_VECTOR = 392 "android.sensor.geomagnetic_rotation_vector"; 393 394 /** 395 * A constant describing a heart rate monitor. 396 * <p> 397 * The reported value is the heart rate in beats per minute. 398 * <p> 399 * The reported accuracy represents the status of the monitor during the reading. See the 400 * {@code SENSOR_STATUS_*} constants in {@link android.hardware.SensorManager SensorManager} 401 * for more details on accuracy/status values. In particular, when the accuracy is 402 * {@code SENSOR_STATUS_UNRELIABLE} or {@code SENSOR_STATUS_NO_CONTACT}, the heart rate 403 * value should be discarded. 404 * <p> 405 * This sensor requires permission {@code android.permission.BODY_SENSORS}. 406 * It will not be returned by {@code SensorManager.getSensorsList} nor 407 * {@code SensorManager.getDefaultSensor} if the application doesn't have this permission. 408 */ 409 public static final int TYPE_HEART_RATE = 21; 410 411 /** 412 * A constant string describing a heart rate monitor. 413 * 414 * @see #TYPE_HEART_RATE 415 */ 416 public static final String STRING_TYPE_HEART_RATE = "android.sensor.heart_rate"; 417 418 /** 419 * A sensor of this type generates an event each time a tilt event is detected. A tilt event 420 * is generated if the direction of the 2-seconds window average gravity changed by at 421 * least 35 degrees since the activation of the sensor. It is a wake up sensor. 422 * 423 * @hide 424 * @see #isWakeUpSensor() 425 */ 426 public static final int TYPE_TILT_DETECTOR = 22; 427 428 /** 429 * A constant string describing a wake up tilt detector sensor type. 430 * 431 * @hide 432 * @see #TYPE_TILT_DETECTOR 433 */ 434 public static final String SENSOR_STRING_TYPE_TILT_DETECTOR = 435 "android.sensor.tilt_detector"; 436 437 /** 438 * A constant describing a wake gesture sensor. 439 * <p> 440 * Wake gesture sensors enable waking up the device based on a device specific motion. 441 * <p> 442 * When this sensor triggers, the device behaves as if the power button was pressed, turning the 443 * screen on. This behavior (turning on the screen when this sensor triggers) might be 444 * deactivated by the user in the device settings. Changes in settings do not impact the 445 * behavior of the sensor: only whether the framework turns the screen on when it triggers. 446 * <p> 447 * The actual gesture to be detected is not specified, and can be chosen by the manufacturer of 448 * the device. This sensor must be low power, as it is likely to be activated 24/7. 449 * Values of events created by this sensors should not be used. 450 * 451 * @see #isWakeUpSensor() 452 * @hide This sensor is expected to only be used by the system ui 453 */ 454 public static final int TYPE_WAKE_GESTURE = 23; 455 456 /** 457 * A constant string describing a wake gesture sensor. 458 * 459 * @hide This sensor is expected to only be used by the system ui 460 * @see #TYPE_WAKE_GESTURE 461 */ 462 public static final String STRING_TYPE_WAKE_GESTURE = "android.sensor.wake_gesture"; 463 464 /** 465 * A constant describing a wake gesture sensor. 466 * <p> 467 * A sensor enabling briefly turning the screen on to enable the user to 468 * glance content on screen based on a specific motion. The device should 469 * turn the screen off after a few moments. 470 * <p> 471 * When this sensor triggers, the device turns the screen on momentarily 472 * to allow the user to glance notifications or other content while the 473 * device remains locked in a non-interactive state (dozing). This behavior 474 * (briefly turning on the screen when this sensor triggers) might be deactivated 475 * by the user in the device settings. Changes in settings do not impact the 476 * behavior of the sensor: only whether the framework briefly turns the screen on 477 * when it triggers. 478 * <p> 479 * The actual gesture to be detected is not specified, and can be chosen by the manufacturer of 480 * the device. This sensor must be low power, as it is likely to be activated 24/7. 481 * Values of events created by this sensors should not be used. 482 * 483 * @see #isWakeUpSensor() 484 * @hide This sensor is expected to only be used by the system ui 485 */ 486 public static final int TYPE_GLANCE_GESTURE = 24; 487 488 /** 489 * A constant string describing a wake gesture sensor. 490 * 491 * @hide This sensor is expected to only be used by the system ui 492 * @see #TYPE_GLANCE_GESTURE 493 */ 494 public static final String STRING_TYPE_GLANCE_GESTURE = "android.sensor.glance_gesture"; 495 496 /** 497 * A constant describing a pick up sensor. 498 * 499 * A sensor of this type triggers when the device is picked up regardless of wherever it was 500 * before (desk, pocket, bag). The only allowed return value is 1.0. This sensor deactivates 501 * itself immediately after it triggers. 502 * 503 * @hide Expected to be used internally for always on display. 504 */ 505 public static final int TYPE_PICK_UP_GESTURE = 25; 506 507 /** 508 * A constant string describing a pick up sensor. 509 * 510 * @hide This sensor is expected to be used internally for always on display. 511 * @see #TYPE_PICK_UP_GESTURE 512 */ 513 public static final String STRING_TYPE_PICK_UP_GESTURE = "android.sensor.pick_up_gesture"; 514 515 /** 516 * A constant describing a wrist tilt gesture sensor. 517 * 518 * A sensor of this type triggers when the device face is tilted towards the user. 519 * The only allowed return value is 1.0. 520 * This sensor remains active until disabled. 521 * 522 * @hide This sensor is expected to only be used by the system ui 523 */ 524 @SystemApi 525 public static final int TYPE_WRIST_TILT_GESTURE = 26; 526 527 /** 528 * A constant string describing a wrist tilt gesture sensor. 529 * 530 * @hide This sensor is expected to only be used by the system ui 531 * @see #TYPE_WRIST_TILT_GESTURE 532 */ 533 @SystemApi 534 public static final String STRING_TYPE_WRIST_TILT_GESTURE = "android.sensor.wrist_tilt_gesture"; 535 536 /** 537 * The current orientation of the device. 538 * <p> 539 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 540 * 541 * @hide Expected to be used internally for auto-rotate and speaker rotation. 542 * 543 */ 544 public static final int TYPE_DEVICE_ORIENTATION = 27; 545 546 /** 547 * A constant string describing a device orientation sensor type. 548 * 549 * @hide 550 * @see #TYPE_DEVICE_ORIENTATION 551 */ 552 public static final String STRING_TYPE_DEVICE_ORIENTATION = "android.sensor.device_orientation"; 553 554 /** 555 * A constant describing a pose sensor with 6 degrees of freedom. 556 * 557 * Similar to {@link #TYPE_ROTATION_VECTOR}, with additional delta 558 * translation from an arbitrary reference point. 559 * 560 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 561 * 562 * Can use camera, depth sensor etc to compute output value. 563 * 564 * This is expected to be a high power sensor and expected only to be 565 * used when the screen is on. 566 * 567 * Expected to be more accurate than the rotation vector alone. 568 * 569 */ 570 public static final int TYPE_POSE_6DOF = 28; 571 572 /** 573 * A constant string describing a pose sensor with 6 degrees of freedom. 574 * 575 * @see #TYPE_POSE_6DOF 576 */ 577 public static final String STRING_TYPE_POSE_6DOF = "android.sensor.pose_6dof"; 578 579 /** 580 * A constant describing a stationary detect sensor. 581 * 582 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 583 * 584 */ 585 public static final int TYPE_STATIONARY_DETECT = 29; 586 587 /** 588 * A constant string describing a stationary detection sensor. 589 * 590 * @see #TYPE_STATIONARY_DETECT 591 */ 592 public static final String STRING_TYPE_STATIONARY_DETECT = "android.sensor.stationary_detect"; 593 594 /** 595 * A constant describing a motion detect sensor. 596 * 597 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 598 * 599 */ 600 public static final int TYPE_MOTION_DETECT = 30; 601 602 /** 603 * A constant string describing a motion detection sensor. 604 * 605 * @see #TYPE_MOTION_DETECT 606 */ 607 public static final String STRING_TYPE_MOTION_DETECT = "android.sensor.motion_detect"; 608 609 /** 610 * A constant describing a motion detect sensor. 611 * 612 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 613 * 614 */ 615 public static final int TYPE_HEART_BEAT = 31; 616 617 /** 618 * A constant string describing a heart beat sensor. 619 * 620 * @see #TYPE_HEART_BEAT 621 */ 622 623 public static final String STRING_TYPE_HEART_BEAT = "android.sensor.heart_beat"; 624 /** 625 * A constant describing a dynamic sensor meta event sensor. 626 * 627 * A sensor event of this type is received when a dynamic sensor is added to or removed from 628 * the system. This sensor type should always use special trigger report mode ({@code 629 * SensorManager.REPORTING_MODE_SPECIAL_TRIGGER}). 630 * 631 * @hide This sensor is expected to be used only by system services. 632 */ 633 @SystemApi 634 public static final int TYPE_DYNAMIC_SENSOR_META = 32; 635 636 /** 637 * A constant string describing a dynamic sensor meta event sensor. 638 * 639 * @see #TYPE_DYNAMIC_SENSOR_META 640 * 641 * @hide This sensor is expected to only be used by the system service 642 */ 643 @SystemApi 644 public static final String STRING_TYPE_DYNAMIC_SENSOR_META = 645 "android.sensor.dynamic_sensor_meta"; 646 647 /** 648 * A constant describing all sensor types. 649 */ 650 651 public static final int TYPE_ALL = -1; 652 653 /** 654 * The lowest sensor type vendor defined sensors can use. 655 * 656 * All vendor sensor types are greater than or equal to this constant. 657 * 658 */ 659 public static final int TYPE_DEVICE_PRIVATE_BASE = 0x10000; 660 661 // If this flag is set, the sensor defined as a wake up sensor. This field and REPORTING_MODE_* 662 // constants are defined as flags in sensors.h. Modify at both places if needed. 663 private static final int SENSOR_FLAG_WAKE_UP_SENSOR = 1; 664 665 /** 666 * Events are reported at a constant rate which is set by the rate parameter of 667 * {@link SensorManager#registerListener(SensorEventListener, Sensor, int)}. Note: If other 668 * applications are requesting a higher rate, the sensor data might be delivered at faster rates 669 * than requested. 670 */ 671 public static final int REPORTING_MODE_CONTINUOUS = 0; 672 673 /** 674 * Events are reported only when the value changes. Event delivery rate can be limited by 675 * setting appropriate value for rate parameter of 676 * {@link SensorManager#registerListener(SensorEventListener, Sensor, int)} Note: If other 677 * applications are requesting a higher rate, the sensor data might be delivered at faster rates 678 * than requested. 679 */ 680 public static final int REPORTING_MODE_ON_CHANGE = 1; 681 682 /** 683 * Events are reported in one-shot mode. Upon detection of an event, the sensor deactivates 684 * itself and then sends a single event. Sensors of this reporting mode must be registered to 685 * using {@link SensorManager#requestTriggerSensor(TriggerEventListener, Sensor)}. 686 */ 687 public static final int REPORTING_MODE_ONE_SHOT = 2; 688 689 /** 690 * Events are reported as described in the description of the sensor. The rate passed to 691 * registerListener might not have an impact on the rate of event delivery. See the sensor 692 * definition for more information on when and how frequently the events are reported. For 693 * example, step detectors report events when a step is detected. 694 * 695 * @see SensorManager#registerListener(SensorEventListener, Sensor, int, int) 696 */ 697 public static final int REPORTING_MODE_SPECIAL_TRIGGER = 3; 698 699 // Mask for the LSB 2nd, 3rd and fourth bits. 700 private static final int REPORTING_MODE_MASK = 0xE; 701 private static final int REPORTING_MODE_SHIFT = 1; 702 703 // MASK for LSB fifth bit. Used to know whether the sensor supports data injection or not. 704 private static final int DATA_INJECTION_MASK = 0x10; 705 private static final int DATA_INJECTION_SHIFT = 4; 706 707 // MASK for dynamic sensor (sensor that added during runtime), bit 6. 708 private static final int DYNAMIC_SENSOR_MASK = 0x20; 709 private static final int DYNAMIC_SENSOR_SHIFT = 5; 710 711 // MASK for indication bit of sensor additional information support (bit 7). 712 private static final int ADDITIONAL_INFO_MASK = 0x40; 713 private static final int ADDITIONAL_INFO_SHIFT = 6; 714 715 // TODO(): The following arrays are fragile and error-prone. This needs to be refactored. 716 717 // Note: This needs to be updated, whenever a new sensor is added. 718 // Holds the reporting mode and maximum length of the values array 719 // associated with 720 // {@link SensorEvent} or {@link TriggerEvent} for the Sensor 721 private static final int[] sSensorReportingModes = { 722 0, // padding because sensor types start at 1 723 3, // SENSOR_TYPE_ACCELEROMETER 724 3, // SENSOR_TYPE_GEOMAGNETIC_FIELD 725 3, // SENSOR_TYPE_ORIENTATION 726 3, // SENSOR_TYPE_GYROSCOPE 727 3, // SENSOR_TYPE_LIGHT 728 3, // SENSOR_TYPE_PRESSURE 729 3, // SENSOR_TYPE_TEMPERATURE 730 3, // SENSOR_TYPE_PROXIMITY 731 3, // SENSOR_TYPE_GRAVITY 732 3, // SENSOR_TYPE_LINEAR_ACCELERATION 733 5, // SENSOR_TYPE_ROTATION_VECTOR 734 3, // SENSOR_TYPE_RELATIVE_HUMIDITY 735 3, // SENSOR_TYPE_AMBIENT_TEMPERATURE 736 6, // SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED 737 4, // SENSOR_TYPE_GAME_ROTATION_VECTOR 738 6, // SENSOR_TYPE_GYROSCOPE_UNCALIBRATED 739 1, // SENSOR_TYPE_SIGNIFICANT_MOTION 740 1, // SENSOR_TYPE_STEP_DETECTOR 741 1, // SENSOR_TYPE_STEP_COUNTER 742 5, // SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR 743 1, // SENSOR_TYPE_HEART_RATE_MONITOR 744 1, // SENSOR_TYPE_WAKE_UP_TILT_DETECTOR 745 1, // SENSOR_TYPE_WAKE_GESTURE 746 1, // SENSOR_TYPE_GLANCE_GESTURE 747 1, // SENSOR_TYPE_PICK_UP_GESTURE 748 1, // SENSOR_TYPE_WRIST_TILT_GESTURE 749 1, // SENSOR_TYPE_DEVICE_ORIENTATION 750 16,// SENSOR_TYPE_POSE_6DOF 751 1, // SENSOR_TYPE_STATIONARY_DETECT 752 1, // SENSOR_TYPE_MOTION_DETECT 753 1, // SENSOR_TYPE_HEART_BEAT 754 2, // SENSOR_TYPE_DYNAMIC_SENSOR_META 755 }; 756 757 /** 758 * Each sensor has exactly one reporting mode associated with it. This method returns the 759 * reporting mode constant for this sensor type. 760 * 761 * @return Reporting mode for the input sensor, one of REPORTING_MODE_* constants. 762 * @see #REPORTING_MODE_CONTINUOUS 763 * @see #REPORTING_MODE_ON_CHANGE 764 * @see #REPORTING_MODE_ONE_SHOT 765 * @see #REPORTING_MODE_SPECIAL_TRIGGER 766 */ getReportingMode()767 public int getReportingMode() { 768 return ((mFlags & REPORTING_MODE_MASK) >> REPORTING_MODE_SHIFT); 769 } 770 getMaxLengthValuesArray(Sensor sensor, int sdkLevel)771 static int getMaxLengthValuesArray(Sensor sensor, int sdkLevel) { 772 // RotationVector length has changed to 3 to 5 for API level 18 773 // Set it to 3 for backward compatibility. 774 if (sensor.mType == Sensor.TYPE_ROTATION_VECTOR && 775 sdkLevel <= Build.VERSION_CODES.JELLY_BEAN_MR1) { 776 return 3; 777 } 778 int offset = sensor.mType; 779 if (offset >= sSensorReportingModes.length) { 780 // we don't know about this sensor, so this is probably a vendor-defined sensor, in that 781 // case, we don't know how many value it has so we return the maximum and assume the app 782 // will know. 783 // FIXME: sensor HAL should advertise how much data is returned per sensor 784 return 16; 785 } 786 return sSensorReportingModes[offset]; 787 } 788 789 /* Some of these fields are set only by the native bindings in 790 * SensorManager. 791 */ 792 private String mName; 793 private String mVendor; 794 private int mVersion; 795 private int mHandle; 796 private int mType; 797 private float mMaxRange; 798 private float mResolution; 799 private float mPower; 800 private int mMinDelay; 801 private int mFifoReservedEventCount; 802 private int mFifoMaxEventCount; 803 private String mStringType; 804 private String mRequiredPermission; 805 private int mMaxDelay; 806 private int mFlags; 807 private int mId; 808 Sensor()809 Sensor() { 810 } 811 812 /** 813 * @return name string of the sensor. 814 */ getName()815 public String getName() { 816 return mName; 817 } 818 819 /** 820 * @return vendor string of this sensor. 821 */ getVendor()822 public String getVendor() { 823 return mVendor; 824 } 825 826 /** 827 * @return generic type of this sensor. 828 */ getType()829 public int getType() { 830 return mType; 831 } 832 833 /** 834 * @return version of the sensor's module. 835 */ getVersion()836 public int getVersion() { 837 return mVersion; 838 } 839 840 /** 841 * @return maximum range of the sensor in the sensor's unit. 842 */ getMaximumRange()843 public float getMaximumRange() { 844 return mMaxRange; 845 } 846 847 /** 848 * @return resolution of the sensor in the sensor's unit. 849 */ getResolution()850 public float getResolution() { 851 return mResolution; 852 } 853 854 /** 855 * @return the power in mA used by this sensor while in use 856 */ getPower()857 public float getPower() { 858 return mPower; 859 } 860 861 /** 862 * @return the minimum delay allowed between two events in microsecond 863 * or zero if this sensor only returns a value when the data it's measuring 864 * changes. 865 */ getMinDelay()866 public int getMinDelay() { 867 return mMinDelay; 868 } 869 870 /** 871 * @return Number of events reserved for this sensor in the batch mode FIFO. This gives a 872 * guarantee on the minimum number of events that can be batched. 873 */ getFifoReservedEventCount()874 public int getFifoReservedEventCount() { 875 return mFifoReservedEventCount; 876 } 877 878 /** 879 * @return Maximum number of events of this sensor that could be batched. If this value is zero 880 * it indicates that batch mode is not supported for this sensor. If other applications 881 * registered to batched sensors, the actual number of events that can be batched might be 882 * smaller because the hardware FiFo will be partially used to batch the other sensors. 883 */ getFifoMaxEventCount()884 public int getFifoMaxEventCount() { 885 return mFifoMaxEventCount; 886 } 887 888 /** 889 * @return The type of this sensor as a string. 890 */ getStringType()891 public String getStringType() { 892 return mStringType; 893 } 894 895 /** 896 * Do not use. 897 * 898 * This method throws an UnsupportedOperationException. 899 * 900 * Use getId() if you want a unique ID. 901 * 902 * @see getId 903 * 904 * @hide 905 */ 906 @SystemApi getUuid()907 public java.util.UUID getUuid() { 908 throw new UnsupportedOperationException(); 909 } 910 911 /** 912 * @return The sensor id that will be unique for the same app unless the device is factory 913 * reset. Return value of 0 means this sensor does not support this function; return value of -1 914 * means this sensor can be uniquely identified in system by combination of its type and name. 915 */ getId()916 public int getId() { 917 return mId; 918 } 919 920 /** 921 * @hide 922 * @return The permission required to access this sensor. If empty, no permission is required. 923 */ getRequiredPermission()924 public String getRequiredPermission() { 925 return mRequiredPermission; 926 } 927 928 /** @hide */ getHandle()929 public int getHandle() { 930 return mHandle; 931 } 932 933 /** 934 * This value is defined only for continuous and on-change sensors. It is the delay between two 935 * sensor events corresponding to the lowest frequency that this sensor supports. When lower 936 * frequencies are requested through registerListener() the events will be generated at this 937 * frequency instead. It can be used to estimate when the batch FIFO may be full. Older devices 938 * may set this value to zero. Ignore this value in case it is negative or zero. 939 * 940 * @return The max delay for this sensor in microseconds. 941 */ getMaxDelay()942 public int getMaxDelay() { 943 return mMaxDelay; 944 } 945 946 /** 947 * Returns true if the sensor is a wake-up sensor. 948 * <p> 949 * <b>Application Processor Power modes</b> <p> 950 * Application Processor(AP), is the processor on which applications run. When no wake lock is held 951 * and the user is not interacting with the device, this processor can enter a “Suspend” mode, 952 * reducing the power consumption by 10 times or more. 953 * </p> 954 * <p> 955 * <b>Non-wake-up sensors</b> <p> 956 * Non-wake-up sensors are sensors that do not wake the AP out of suspend to report data. While 957 * the AP is in suspend mode, the sensors continue to function and generate events, which are 958 * put in a hardware FIFO. The events in the FIFO are delivered to the application when the AP 959 * wakes up. If the FIFO was too small to store all events generated while the AP was in 960 * suspend mode, the older events are lost: the oldest data is dropped to accommodate the newer 961 * data. In the extreme case where the FIFO is non-existent {@code maxFifoEventCount() == 0}, 962 * all events generated while the AP was in suspend mode are lost. Applications using 963 * non-wake-up sensors should usually: 964 * <ul> 965 * <li>Either unregister from the sensors when they do not need them, usually in the activity’s 966 * {@code onPause} method. This is the most common case. 967 * <li>Or realize that the sensors are consuming some power while the AP is in suspend mode and 968 * that even then, some events might be lost. 969 * </ul> 970 * </p> 971 * <p> 972 * <b>Wake-up sensors</b> <p> 973 * In opposition to non-wake-up sensors, wake-up sensors ensure that their data is delivered 974 * independently of the state of the AP. While the AP is awake, the wake-up sensors behave 975 * like non-wake-up-sensors. When the AP is asleep, wake-up sensors wake up the AP to deliver 976 * events. That is, the AP will wake up and the sensor will deliver the events before the 977 * maximum reporting latency is elapsed or the hardware FIFO gets full. See {@link 978 * SensorManager#registerListener(SensorEventListener, Sensor, int, int)} for more details. 979 * </p> 980 * 981 * @return <code>true</code> if this is a wake-up sensor, <code>false</code> otherwise. 982 */ isWakeUpSensor()983 public boolean isWakeUpSensor() { 984 return (mFlags & SENSOR_FLAG_WAKE_UP_SENSOR) != 0; 985 } 986 987 /** 988 * Returns true if the sensor is a dynamic sensor. 989 * 990 * @return <code>true</code> if the sensor is a dynamic sensor (sensor added at runtime). 991 * @see SensorManager.DynamicSensorCallback 992 */ isDynamicSensor()993 public boolean isDynamicSensor() { 994 return (mFlags & DYNAMIC_SENSOR_MASK) != 0; 995 } 996 997 /** 998 * Returns true if the sensor supports sensor additional information API 999 * 1000 * @return <code>true</code> if the sensor supports sensor additional information API 1001 * @see SensorAdditionalInfo 1002 */ isAdditionalInfoSupported()1003 public boolean isAdditionalInfoSupported() { 1004 return (mFlags & ADDITIONAL_INFO_MASK) != 0; 1005 } 1006 1007 /** 1008 * Returns true if the sensor supports data injection when the 1009 * HAL is set to data injection mode. 1010 * 1011 * @return <code>true</code> if the sensor supports data 1012 * injection when the HAL is set in injection mode, 1013 * false otherwise. 1014 * @hide 1015 */ 1016 @SystemApi isDataInjectionSupported()1017 public boolean isDataInjectionSupported() { 1018 return (((mFlags & DATA_INJECTION_MASK) >> DATA_INJECTION_SHIFT)) != 0; 1019 } 1020 setRange(float max, float res)1021 void setRange(float max, float res) { 1022 mMaxRange = max; 1023 mResolution = res; 1024 } 1025 1026 @Override toString()1027 public String toString() { 1028 return "{Sensor name=\"" + mName + "\", vendor=\"" + mVendor + "\", version=" + mVersion 1029 + ", type=" + mType + ", maxRange=" + mMaxRange + ", resolution=" + mResolution 1030 + ", power=" + mPower + ", minDelay=" + mMinDelay + "}"; 1031 } 1032 1033 /** 1034 * Sets the Type associated with the sensor. 1035 * NOTE: to be used only by native bindings in SensorManager. 1036 * 1037 * This allows interned static strings to be used across all representations of the Sensor. If 1038 * a sensor type is not referenced here, it will still be interned by the native SensorManager. 1039 * 1040 * @return {@code true} if the StringType was successfully set, {@code false} otherwise. 1041 */ setType(int value)1042 private boolean setType(int value) { 1043 mType = value; 1044 switch (mType) { 1045 case TYPE_ACCELEROMETER: 1046 mStringType = STRING_TYPE_ACCELEROMETER; 1047 return true; 1048 case TYPE_AMBIENT_TEMPERATURE: 1049 mStringType = STRING_TYPE_AMBIENT_TEMPERATURE; 1050 return true; 1051 case TYPE_GAME_ROTATION_VECTOR: 1052 mStringType = STRING_TYPE_GAME_ROTATION_VECTOR; 1053 return true; 1054 case TYPE_GEOMAGNETIC_ROTATION_VECTOR: 1055 mStringType = STRING_TYPE_GEOMAGNETIC_ROTATION_VECTOR; 1056 return true; 1057 case TYPE_GLANCE_GESTURE: 1058 mStringType = STRING_TYPE_GLANCE_GESTURE; 1059 return true; 1060 case TYPE_GRAVITY: 1061 mStringType = STRING_TYPE_GRAVITY; 1062 return true; 1063 case TYPE_GYROSCOPE: 1064 mStringType = STRING_TYPE_GYROSCOPE; 1065 return true; 1066 case TYPE_GYROSCOPE_UNCALIBRATED: 1067 mStringType = STRING_TYPE_GYROSCOPE_UNCALIBRATED; 1068 return true; 1069 case TYPE_HEART_RATE: 1070 mStringType = STRING_TYPE_HEART_RATE; 1071 return true; 1072 case TYPE_LIGHT: 1073 mStringType = STRING_TYPE_LIGHT; 1074 return true; 1075 case TYPE_LINEAR_ACCELERATION: 1076 mStringType = STRING_TYPE_LINEAR_ACCELERATION; 1077 return true; 1078 case TYPE_MAGNETIC_FIELD: 1079 mStringType = STRING_TYPE_MAGNETIC_FIELD; 1080 return true; 1081 case TYPE_MAGNETIC_FIELD_UNCALIBRATED: 1082 mStringType = STRING_TYPE_MAGNETIC_FIELD_UNCALIBRATED; 1083 return true; 1084 case TYPE_PICK_UP_GESTURE: 1085 mStringType = STRING_TYPE_PICK_UP_GESTURE; 1086 return true; 1087 case TYPE_PRESSURE: 1088 mStringType = STRING_TYPE_PRESSURE; 1089 return true; 1090 case TYPE_PROXIMITY: 1091 mStringType = STRING_TYPE_PROXIMITY; 1092 return true; 1093 case TYPE_RELATIVE_HUMIDITY: 1094 mStringType = STRING_TYPE_RELATIVE_HUMIDITY; 1095 return true; 1096 case TYPE_ROTATION_VECTOR: 1097 mStringType = STRING_TYPE_ROTATION_VECTOR; 1098 return true; 1099 case TYPE_SIGNIFICANT_MOTION: 1100 mStringType = STRING_TYPE_SIGNIFICANT_MOTION; 1101 return true; 1102 case TYPE_STEP_COUNTER: 1103 mStringType = STRING_TYPE_STEP_COUNTER; 1104 return true; 1105 case TYPE_STEP_DETECTOR: 1106 mStringType = STRING_TYPE_STEP_DETECTOR; 1107 return true; 1108 case TYPE_TILT_DETECTOR: 1109 mStringType = SENSOR_STRING_TYPE_TILT_DETECTOR; 1110 return true; 1111 case TYPE_WAKE_GESTURE: 1112 mStringType = STRING_TYPE_WAKE_GESTURE; 1113 return true; 1114 case TYPE_ORIENTATION: 1115 mStringType = STRING_TYPE_ORIENTATION; 1116 return true; 1117 case TYPE_TEMPERATURE: 1118 mStringType = STRING_TYPE_TEMPERATURE; 1119 return true; 1120 case TYPE_DEVICE_ORIENTATION: 1121 mStringType = STRING_TYPE_DEVICE_ORIENTATION; 1122 return true; 1123 case TYPE_DYNAMIC_SENSOR_META: 1124 mStringType = STRING_TYPE_DYNAMIC_SENSOR_META; 1125 return true; 1126 default: 1127 return false; 1128 } 1129 } 1130 1131 /** 1132 * Sets the ID associated with the sensor. 1133 * 1134 * The method name is misleading; while this ID is based on the UUID, 1135 * we do not pass in the actual UUID. 1136 * 1137 * NOTE: to be used only by native bindings in SensorManager. 1138 * 1139 * @see #getId 1140 */ setUuid(long msb, long lsb)1141 private void setUuid(long msb, long lsb) { 1142 // TODO(b/29547335): Rename this method to setId. 1143 mId = (int)msb; 1144 } 1145 } 1146