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