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