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.annotation.SystemApi; 21import 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 */ 32public 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 /* TYPE_ADDITIONAL_INFO - defined as type 33 in the HAL is not exposed to 648 * applications. There are parts of the framework that require the sensors 649 * to be in the same order as the HAL. Skipping this sensor 650 */ 651 652 /** 653 * A constant describing a low latency off-body detect sensor. 654 * 655 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 656 * 657 */ 658 public static final int TYPE_LOW_LATENCY_OFFBODY_DETECT = 34; 659 660 661 /** 662 * A constant string describing a low-latency offbody detector sensor. 663 * 664 * @see #TYPE_LOW_LATENCY_OFFBODY_DETECT 665 */ 666 public static final String STRING_TYPE_LOW_LATENCY_OFFBODY_DETECT = 667 "android.sensor.low_latency_offbody_detect"; 668 669 /** 670 * A constant describing an uncalibrated accelerometer sensor. 671 * 672 * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details. 673 * 674 */ 675 public static final int TYPE_ACCELEROMETER_UNCALIBRATED = 35; 676 677 /** 678 * A constant string describing an uncalibrated accelerometer sensor. 679 * 680 * @see #TYPE_ACCELEROMETER_UNCALIBRATED 681 * 682 */ 683 public static final String STRING_TYPE_ACCELEROMETER_UNCALIBRATED = 684 "android.sensor.accelerometer_uncalibrated"; 685 686 /** 687 * A constant describing all sensor types. 688 */ 689 690 public static final int TYPE_ALL = -1; 691 692 /** 693 * The lowest sensor type vendor defined sensors can use. 694 * 695 * All vendor sensor types are greater than or equal to this constant. 696 * 697 */ 698 public static final int TYPE_DEVICE_PRIVATE_BASE = 0x10000; 699 700 // If this flag is set, the sensor defined as a wake up sensor. This field and REPORTING_MODE_* 701 // constants are defined as flags in sensors.h. Modify at both places if needed. 702 private static final int SENSOR_FLAG_WAKE_UP_SENSOR = 1; 703 704 /** 705 * Events are reported at a constant rate which is set by the rate parameter of 706 * {@link SensorManager#registerListener(SensorEventListener, Sensor, int)}. Note: If other 707 * applications are requesting a higher rate, the sensor data might be delivered at faster rates 708 * than requested. 709 */ 710 public static final int REPORTING_MODE_CONTINUOUS = 0; 711 712 /** 713 * Events are reported only when the value changes. Event delivery rate can be limited by 714 * setting appropriate value for rate parameter of 715 * {@link SensorManager#registerListener(SensorEventListener, Sensor, int)} Note: If other 716 * applications are requesting a higher rate, the sensor data might be delivered at faster rates 717 * than requested. 718 */ 719 public static final int REPORTING_MODE_ON_CHANGE = 1; 720 721 /** 722 * Events are reported in one-shot mode. Upon detection of an event, the sensor deactivates 723 * itself and then sends a single event. Sensors of this reporting mode must be registered to 724 * using {@link SensorManager#requestTriggerSensor(TriggerEventListener, Sensor)}. 725 */ 726 public static final int REPORTING_MODE_ONE_SHOT = 2; 727 728 /** 729 * Events are reported as described in the description of the sensor. The rate passed to 730 * registerListener might not have an impact on the rate of event delivery. See the sensor 731 * definition for more information on when and how frequently the events are reported. For 732 * example, step detectors report events when a step is detected. 733 * 734 * @see SensorManager#registerListener(SensorEventListener, Sensor, int, int) 735 */ 736 public static final int REPORTING_MODE_SPECIAL_TRIGGER = 3; 737 738 // Mask for the LSB 2nd, 3rd and fourth bits. 739 private static final int REPORTING_MODE_MASK = 0xE; 740 private static final int REPORTING_MODE_SHIFT = 1; 741 742 // MASK for LSB fifth bit. Used to know whether the sensor supports data injection or not. 743 private static final int DATA_INJECTION_MASK = 0x10; 744 private static final int DATA_INJECTION_SHIFT = 4; 745 746 // MASK for dynamic sensor (sensor that added during runtime), bit 5. 747 private static final int DYNAMIC_SENSOR_MASK = 0x20; 748 private static final int DYNAMIC_SENSOR_SHIFT = 5; 749 750 // MASK for indication bit of sensor additional information support, bit 6. 751 private static final int ADDITIONAL_INFO_MASK = 0x40; 752 private static final int ADDITIONAL_INFO_SHIFT = 6; 753 754 // Mask for direct mode highest rate level, bit 7, 8, 9. 755 private static final int DIRECT_REPORT_MASK = 0x380; 756 private static final int DIRECT_REPORT_SHIFT = 7; 757 758 // Mask for supported direct channel, bit 10, 11 759 private static final int DIRECT_CHANNEL_MASK = 0xC00; 760 private static final int DIRECT_CHANNEL_SHIFT = 10; 761 762 // TODO(): The following arrays are fragile and error-prone. This needs to be refactored. 763 764 // Note: This needs to be updated, whenever a new sensor is added. 765 // Holds the reporting mode and maximum length of the values array 766 // associated with 767 // {@link SensorEvent} or {@link TriggerEvent} for the Sensor 768 private static final int[] sSensorReportingModes = { 769 0, // padding because sensor types start at 1 770 3, // SENSOR_TYPE_ACCELEROMETER 771 3, // SENSOR_TYPE_GEOMAGNETIC_FIELD 772 3, // SENSOR_TYPE_ORIENTATION 773 3, // SENSOR_TYPE_GYROSCOPE 774 1, // SENSOR_TYPE_LIGHT 775 1, // SENSOR_TYPE_PRESSURE 776 1, // SENSOR_TYPE_TEMPERATURE 777 1, // SENSOR_TYPE_PROXIMITY 778 3, // SENSOR_TYPE_GRAVITY 779 3, // SENSOR_TYPE_LINEAR_ACCELERATION 780 5, // SENSOR_TYPE_ROTATION_VECTOR 781 1, // SENSOR_TYPE_RELATIVE_HUMIDITY 782 1, // SENSOR_TYPE_AMBIENT_TEMPERATURE 783 6, // SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED 784 4, // SENSOR_TYPE_GAME_ROTATION_VECTOR 785 6, // SENSOR_TYPE_GYROSCOPE_UNCALIBRATED 786 1, // SENSOR_TYPE_SIGNIFICANT_MOTION 787 1, // SENSOR_TYPE_STEP_DETECTOR 788 1, // SENSOR_TYPE_STEP_COUNTER 789 5, // SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR 790 1, // SENSOR_TYPE_HEART_RATE_MONITOR 791 1, // SENSOR_TYPE_WAKE_UP_TILT_DETECTOR 792 1, // SENSOR_TYPE_WAKE_GESTURE 793 1, // SENSOR_TYPE_GLANCE_GESTURE 794 1, // SENSOR_TYPE_PICK_UP_GESTURE 795 1, // SENSOR_TYPE_WRIST_TILT_GESTURE 796 1, // SENSOR_TYPE_DEVICE_ORIENTATION 797 16,// SENSOR_TYPE_POSE_6DOF 798 1, // SENSOR_TYPE_STATIONARY_DETECT 799 1, // SENSOR_TYPE_MOTION_DETECT 800 1, // SENSOR_TYPE_HEART_BEAT 801 2, // SENSOR_TYPE_DYNAMIC_SENSOR_META 802 16,// skip over additional sensor info type 803 1, // SENSOR_TYPE_LOW_LATENCY_OFFBODY_DETECT 804 6, // SENSOR_TYPE_ACCELEROMETER_UNCALIBRATED 805 }; 806 807 /** 808 * Each sensor has exactly one reporting mode associated with it. This method returns the 809 * reporting mode constant for this sensor type. 810 * 811 * @return Reporting mode for the input sensor, one of REPORTING_MODE_* constants. 812 * @see #REPORTING_MODE_CONTINUOUS 813 * @see #REPORTING_MODE_ON_CHANGE 814 * @see #REPORTING_MODE_ONE_SHOT 815 * @see #REPORTING_MODE_SPECIAL_TRIGGER 816 */ 817 public int getReportingMode() { 818 return ((mFlags & REPORTING_MODE_MASK) >> REPORTING_MODE_SHIFT); 819 } 820 821 /** 822 * Get the highest supported direct report mode rate level of the sensor. 823 * 824 * @return Highest direct report rate level of this sensor. If the sensor does not support 825 * direct report mode, this returns {@link SensorDirectChannel#RATE_STOP}. 826 * @see SensorDirectChannel#RATE_STOP 827 * @see SensorDirectChannel#RATE_NORMAL 828 * @see SensorDirectChannel#RATE_FAST 829 * @see SensorDirectChannel#RATE_VERY_FAST 830 */ 831 @SensorDirectChannel.RateLevel 832 public int getHighestDirectReportRateLevel() { 833 int rateLevel = ((mFlags & DIRECT_REPORT_MASK) >> DIRECT_REPORT_SHIFT); 834 return rateLevel <= SensorDirectChannel.RATE_VERY_FAST 835 ? rateLevel : SensorDirectChannel.RATE_VERY_FAST; 836 } 837 838 /** 839 * Test if a sensor supports a specified direct channel type. 840 * 841 * @param sharedMemType type of shared memory used by direct channel. 842 * @return <code>true</code> if the specified shared memory type is supported. 843 * @see SensorDirectChannel#TYPE_MEMORY_FILE 844 * @see SensorDirectChannel#TYPE_HARDWARE_BUFFER 845 */ 846 public boolean isDirectChannelTypeSupported(@SensorDirectChannel.MemoryType int sharedMemType) { 847 switch (sharedMemType) { 848 case SensorDirectChannel.TYPE_MEMORY_FILE: 849 return (mFlags & (1 << DIRECT_CHANNEL_SHIFT)) > 0; 850 case SensorDirectChannel.TYPE_HARDWARE_BUFFER: 851 return (mFlags & (1 << DIRECT_CHANNEL_SHIFT + 1)) > 0; 852 default: 853 return false; 854 } 855 } 856 857 static int getMaxLengthValuesArray(Sensor sensor, int sdkLevel) { 858 // RotationVector length has changed to 3 to 5 for API level 18 859 // Set it to 3 for backward compatibility. 860 if (sensor.mType == Sensor.TYPE_ROTATION_VECTOR && 861 sdkLevel <= Build.VERSION_CODES.JELLY_BEAN_MR1) { 862 return 3; 863 } 864 int offset = sensor.mType; 865 if (offset >= sSensorReportingModes.length) { 866 // we don't know about this sensor, so this is probably a vendor-defined sensor, in that 867 // case, we don't know how many value it has so we return the maximum and assume the app 868 // will know. 869 // FIXME: sensor HAL should advertise how much data is returned per sensor 870 return 16; 871 } 872 return sSensorReportingModes[offset]; 873 } 874 875 /* Some of these fields are set only by the native bindings in 876 * SensorManager. 877 */ 878 private String mName; 879 private String mVendor; 880 private int mVersion; 881 private int mHandle; 882 private int mType; 883 private float mMaxRange; 884 private float mResolution; 885 private float mPower; 886 private int mMinDelay; 887 private int mFifoReservedEventCount; 888 private int mFifoMaxEventCount; 889 private String mStringType; 890 private String mRequiredPermission; 891 private int mMaxDelay; 892 private int mFlags; 893 private int mId; 894 895 Sensor() { 896 } 897 898 /** 899 * @return name string of the sensor. 900 */ 901 public String getName() { 902 return mName; 903 } 904 905 /** 906 * @return vendor string of this sensor. 907 */ 908 public String getVendor() { 909 return mVendor; 910 } 911 912 /** 913 * @return generic type of this sensor. 914 */ 915 public int getType() { 916 return mType; 917 } 918 919 /** 920 * @return version of the sensor's module. 921 */ 922 public int getVersion() { 923 return mVersion; 924 } 925 926 /** 927 * @return maximum range of the sensor in the sensor's unit. 928 */ 929 public float getMaximumRange() { 930 return mMaxRange; 931 } 932 933 /** 934 * @return resolution of the sensor in the sensor's unit. 935 */ 936 public float getResolution() { 937 return mResolution; 938 } 939 940 /** 941 * @return the power in mA used by this sensor while in use 942 */ 943 public float getPower() { 944 return mPower; 945 } 946 947 /** 948 * @return the minimum delay allowed between two events in microsecond 949 * or zero if this sensor only returns a value when the data it's measuring 950 * changes. 951 */ 952 public int getMinDelay() { 953 return mMinDelay; 954 } 955 956 /** 957 * @return Number of events reserved for this sensor in the batch mode FIFO. This gives a 958 * guarantee on the minimum number of events that can be batched. 959 */ 960 public int getFifoReservedEventCount() { 961 return mFifoReservedEventCount; 962 } 963 964 /** 965 * @return Maximum number of events of this sensor that could be batched. If this value is zero 966 * it indicates that batch mode is not supported for this sensor. If other applications 967 * registered to batched sensors, the actual number of events that can be batched might be 968 * smaller because the hardware FiFo will be partially used to batch the other sensors. 969 */ 970 public int getFifoMaxEventCount() { 971 return mFifoMaxEventCount; 972 } 973 974 /** 975 * @return The type of this sensor as a string. 976 */ 977 public String getStringType() { 978 return mStringType; 979 } 980 981 /** 982 * Do not use. 983 * 984 * This method throws an UnsupportedOperationException. 985 * 986 * Use getId() if you want a unique ID. 987 * 988 * @see getId 989 * 990 * @hide 991 */ 992 @SystemApi 993 public java.util.UUID getUuid() { 994 throw new UnsupportedOperationException(); 995 } 996 997 /** 998 * @return The sensor id that will be unique for the same app unless the device is factory 999 * reset. Return value of 0 means this sensor does not support this function; return value of -1 1000 * means this sensor can be uniquely identified in system by combination of its type and name. 1001 */ 1002 public int getId() { 1003 return mId; 1004 } 1005 1006 /** 1007 * @hide 1008 * @return The permission required to access this sensor. If empty, no permission is required. 1009 */ 1010 public String getRequiredPermission() { 1011 return mRequiredPermission; 1012 } 1013 1014 /** @hide */ 1015 public int getHandle() { 1016 return mHandle; 1017 } 1018 1019 /** 1020 * This value is defined only for continuous and on-change sensors. It is the delay between two 1021 * sensor events corresponding to the lowest frequency that this sensor supports. When lower 1022 * frequencies are requested through registerListener() the events will be generated at this 1023 * frequency instead. It can be used to estimate when the batch FIFO may be full. Older devices 1024 * may set this value to zero. Ignore this value in case it is negative or zero. 1025 * 1026 * @return The max delay for this sensor in microseconds. 1027 */ 1028 public int getMaxDelay() { 1029 return mMaxDelay; 1030 } 1031 1032 /** 1033 * Returns true if the sensor is a wake-up sensor. 1034 * <p> 1035 * <b>Application Processor Power modes</b> <p> 1036 * Application Processor(AP), is the processor on which applications run. When no wake lock is held 1037 * and the user is not interacting with the device, this processor can enter a “Suspend” mode, 1038 * reducing the power consumption by 10 times or more. 1039 * </p> 1040 * <p> 1041 * <b>Non-wake-up sensors</b> <p> 1042 * Non-wake-up sensors are sensors that do not wake the AP out of suspend to report data. While 1043 * the AP is in suspend mode, the sensors continue to function and generate events, which are 1044 * put in a hardware FIFO. The events in the FIFO are delivered to the application when the AP 1045 * wakes up. If the FIFO was too small to store all events generated while the AP was in 1046 * suspend mode, the older events are lost: the oldest data is dropped to accommodate the newer 1047 * data. In the extreme case where the FIFO is non-existent {@code maxFifoEventCount() == 0}, 1048 * all events generated while the AP was in suspend mode are lost. Applications using 1049 * non-wake-up sensors should usually: 1050 * <ul> 1051 * <li>Either unregister from the sensors when they do not need them, usually in the activity’s 1052 * {@code onPause} method. This is the most common case. 1053 * <li>Or realize that the sensors are consuming some power while the AP is in suspend mode and 1054 * that even then, some events might be lost. 1055 * </ul> 1056 * </p> 1057 * <p> 1058 * <b>Wake-up sensors</b> <p> 1059 * In opposition to non-wake-up sensors, wake-up sensors ensure that their data is delivered 1060 * independently of the state of the AP. While the AP is awake, the wake-up sensors behave 1061 * like non-wake-up-sensors. When the AP is asleep, wake-up sensors wake up the AP to deliver 1062 * events. That is, the AP will wake up and the sensor will deliver the events before the 1063 * maximum reporting latency is elapsed or the hardware FIFO gets full. See {@link 1064 * SensorManager#registerListener(SensorEventListener, Sensor, int, int)} for more details. 1065 * </p> 1066 * 1067 * @return <code>true</code> if this is a wake-up sensor, <code>false</code> otherwise. 1068 */ 1069 public boolean isWakeUpSensor() { 1070 return (mFlags & SENSOR_FLAG_WAKE_UP_SENSOR) != 0; 1071 } 1072 1073 /** 1074 * Returns true if the sensor is a dynamic sensor. 1075 * 1076 * @return <code>true</code> if the sensor is a dynamic sensor (sensor added at runtime). 1077 * @see SensorManager.DynamicSensorCallback 1078 */ 1079 public boolean isDynamicSensor() { 1080 return (mFlags & DYNAMIC_SENSOR_MASK) != 0; 1081 } 1082 1083 /** 1084 * Returns true if the sensor supports sensor additional information API 1085 * 1086 * @return <code>true</code> if the sensor supports sensor additional information API 1087 * @see SensorAdditionalInfo 1088 */ 1089 public boolean isAdditionalInfoSupported() { 1090 return (mFlags & ADDITIONAL_INFO_MASK) != 0; 1091 } 1092 1093 /** 1094 * Returns true if the sensor supports data injection when the 1095 * HAL is set to data injection mode. 1096 * 1097 * @return <code>true</code> if the sensor supports data 1098 * injection when the HAL is set in injection mode, 1099 * false otherwise. 1100 * @hide 1101 */ 1102 @SystemApi 1103 public boolean isDataInjectionSupported() { 1104 return (((mFlags & DATA_INJECTION_MASK) >> DATA_INJECTION_SHIFT)) != 0; 1105 } 1106 1107 void setRange(float max, float res) { 1108 mMaxRange = max; 1109 mResolution = res; 1110 } 1111 1112 @Override 1113 public String toString() { 1114 return "{Sensor name=\"" + mName + "\", vendor=\"" + mVendor + "\", version=" + mVersion 1115 + ", type=" + mType + ", maxRange=" + mMaxRange + ", resolution=" + mResolution 1116 + ", power=" + mPower + ", minDelay=" + mMinDelay + "}"; 1117 } 1118 1119 /** 1120 * Sets the Type associated with the sensor. 1121 * NOTE: to be used only by native bindings in SensorManager. 1122 * 1123 * This allows interned static strings to be used across all representations of the Sensor. If 1124 * a sensor type is not referenced here, it will still be interned by the native SensorManager. 1125 * 1126 * @return {@code true} if the StringType was successfully set, {@code false} otherwise. 1127 */ 1128 private boolean setType(int value) { 1129 mType = value; 1130 switch (mType) { 1131 case TYPE_ACCELEROMETER: 1132 mStringType = STRING_TYPE_ACCELEROMETER; 1133 return true; 1134 case TYPE_AMBIENT_TEMPERATURE: 1135 mStringType = STRING_TYPE_AMBIENT_TEMPERATURE; 1136 return true; 1137 case TYPE_GAME_ROTATION_VECTOR: 1138 mStringType = STRING_TYPE_GAME_ROTATION_VECTOR; 1139 return true; 1140 case TYPE_GEOMAGNETIC_ROTATION_VECTOR: 1141 mStringType = STRING_TYPE_GEOMAGNETIC_ROTATION_VECTOR; 1142 return true; 1143 case TYPE_GLANCE_GESTURE: 1144 mStringType = STRING_TYPE_GLANCE_GESTURE; 1145 return true; 1146 case TYPE_GRAVITY: 1147 mStringType = STRING_TYPE_GRAVITY; 1148 return true; 1149 case TYPE_GYROSCOPE: 1150 mStringType = STRING_TYPE_GYROSCOPE; 1151 return true; 1152 case TYPE_GYROSCOPE_UNCALIBRATED: 1153 mStringType = STRING_TYPE_GYROSCOPE_UNCALIBRATED; 1154 return true; 1155 case TYPE_HEART_RATE: 1156 mStringType = STRING_TYPE_HEART_RATE; 1157 return true; 1158 case TYPE_LIGHT: 1159 mStringType = STRING_TYPE_LIGHT; 1160 return true; 1161 case TYPE_LINEAR_ACCELERATION: 1162 mStringType = STRING_TYPE_LINEAR_ACCELERATION; 1163 return true; 1164 case TYPE_MAGNETIC_FIELD: 1165 mStringType = STRING_TYPE_MAGNETIC_FIELD; 1166 return true; 1167 case TYPE_MAGNETIC_FIELD_UNCALIBRATED: 1168 mStringType = STRING_TYPE_MAGNETIC_FIELD_UNCALIBRATED; 1169 return true; 1170 case TYPE_PICK_UP_GESTURE: 1171 mStringType = STRING_TYPE_PICK_UP_GESTURE; 1172 return true; 1173 case TYPE_PRESSURE: 1174 mStringType = STRING_TYPE_PRESSURE; 1175 return true; 1176 case TYPE_PROXIMITY: 1177 mStringType = STRING_TYPE_PROXIMITY; 1178 return true; 1179 case TYPE_RELATIVE_HUMIDITY: 1180 mStringType = STRING_TYPE_RELATIVE_HUMIDITY; 1181 return true; 1182 case TYPE_ROTATION_VECTOR: 1183 mStringType = STRING_TYPE_ROTATION_VECTOR; 1184 return true; 1185 case TYPE_SIGNIFICANT_MOTION: 1186 mStringType = STRING_TYPE_SIGNIFICANT_MOTION; 1187 return true; 1188 case TYPE_STEP_COUNTER: 1189 mStringType = STRING_TYPE_STEP_COUNTER; 1190 return true; 1191 case TYPE_STEP_DETECTOR: 1192 mStringType = STRING_TYPE_STEP_DETECTOR; 1193 return true; 1194 case TYPE_TILT_DETECTOR: 1195 mStringType = SENSOR_STRING_TYPE_TILT_DETECTOR; 1196 return true; 1197 case TYPE_WAKE_GESTURE: 1198 mStringType = STRING_TYPE_WAKE_GESTURE; 1199 return true; 1200 case TYPE_ORIENTATION: 1201 mStringType = STRING_TYPE_ORIENTATION; 1202 return true; 1203 case TYPE_TEMPERATURE: 1204 mStringType = STRING_TYPE_TEMPERATURE; 1205 return true; 1206 case TYPE_DEVICE_ORIENTATION: 1207 mStringType = STRING_TYPE_DEVICE_ORIENTATION; 1208 return true; 1209 case TYPE_DYNAMIC_SENSOR_META: 1210 mStringType = STRING_TYPE_DYNAMIC_SENSOR_META; 1211 return true; 1212 case TYPE_LOW_LATENCY_OFFBODY_DETECT: 1213 mStringType = STRING_TYPE_LOW_LATENCY_OFFBODY_DETECT; 1214 return true; 1215 case TYPE_ACCELEROMETER_UNCALIBRATED: 1216 mStringType = STRING_TYPE_ACCELEROMETER_UNCALIBRATED; 1217 return true; 1218 default: 1219 return false; 1220 } 1221 } 1222 1223 /** 1224 * Sets the ID associated with the sensor. 1225 * 1226 * The method name is misleading; while this ID is based on the UUID, 1227 * we do not pass in the actual UUID. 1228 * 1229 * NOTE: to be used only by native bindings in SensorManager. 1230 * 1231 * @see #getId 1232 */ 1233 private void setUuid(long msb, long lsb) { 1234 // TODO(b/29547335): Rename this method to setId. 1235 mId = (int)msb; 1236 } 1237} 1238