Sensor.java revision 3c9c0918635143f373817fff1ce5131b995282cf
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 describing a magnetic field sensor type. 42 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 43 * for more details. 44 */ 45 public static final int TYPE_MAGNETIC_FIELD = 2; 46 47 /** 48 * A constant describing an orientation sensor type. 49 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 50 * for more details. 51 * 52 * @deprecated use {@link android.hardware.SensorManager#getOrientation 53 * SensorManager.getOrientation()} instead. 54 */ 55 @Deprecated 56 public static final int TYPE_ORIENTATION = 3; 57 58 /** A constant describing a gyroscope sensor type. 59 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 60 * for more details. */ 61 public static final int TYPE_GYROSCOPE = 4; 62 63 /** 64 * A constant describing a light sensor type. 65 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 66 * for more details. 67 */ 68 public static final int TYPE_LIGHT = 5; 69 70 /** A constant describing a pressure sensor type. 71 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 72 * for more details. */ 73 public static final int TYPE_PRESSURE = 6; 74 75 /** 76 * A constant describing a temperature sensor type 77 * 78 * @deprecated use 79 * {@link android.hardware.Sensor#TYPE_AMBIENT_TEMPERATURE 80 * Sensor.TYPE_AMBIENT_TEMPERATURE} instead. 81 */ 82 @Deprecated 83 public static final int TYPE_TEMPERATURE = 7; 84 85 /** 86 * A constant describing a proximity sensor type. 87 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 88 * for more details. 89 */ 90 public static final int TYPE_PROXIMITY = 8; 91 92 /** 93 * A constant describing a gravity sensor type. 94 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 95 * for more details. 96 */ 97 public static final int TYPE_GRAVITY = 9; 98 99 /** 100 * A constant describing a linear acceleration sensor type. 101 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 102 * for more details. 103 */ 104 public static final int TYPE_LINEAR_ACCELERATION = 10; 105 106 /** 107 * A constant describing a rotation vector sensor type. 108 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 109 * for more details. 110 */ 111 public static final int TYPE_ROTATION_VECTOR = 11; 112 113 /** 114 * A constant describing a relative humidity sensor type. 115 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 116 * for more details. 117 */ 118 public static final int TYPE_RELATIVE_HUMIDITY = 12; 119 120 /** A constant describing an ambient temperature sensor type. 121 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} 122 * for more details. */ 123 public static final int TYPE_AMBIENT_TEMPERATURE = 13; 124 125 /** 126 * A constant describing an uncalibrated magnetic field sensor type. 127 * <p> 128 * Similar to {@link #TYPE_MAGNETIC_FIELD} but the hard iron calibration (device calibration 129 * due to distortions that arise from magnetized iron, steel or permanent magnets on the 130 * device) is not considered in the given sensor values. However, such hard iron bias values 131 * are returned to you separately in the result {@link android.hardware.SensorEvent#values} 132 * so you may use them for custom calibrations. 133 * <p>Also, no periodic calibration is performed 134 * (i.e. there are no discontinuities in the data stream while using this sensor) and 135 * assumptions that the magnetic field is due to the Earth's poles is avoided, but 136 * factory calibration and temperature compensation have been performed. 137 * </p> 138 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} for more 139 * details. 140 */ 141 public static final int TYPE_MAGNETIC_FIELD_UNCALIBRATED = 14; 142 143 /** 144 * A constant describing an uncalibrated rotation vector sensor type. 145 * <p>Identical to {@link #TYPE_ROTATION_VECTOR} except that it doesn't 146 * use the geomagnetic field. Therefore the Y axis doesn't 147 * point north, but instead to some other reference, that reference is 148 * allowed to drift by the same order of magnitude as the gyroscope 149 * drift around the Z axis. 150 * <p> 151 * In the ideal case, a phone rotated and returning to the same real-world 152 * orientation should report the same game rotation vector 153 * (without using the earth's geomagnetic field). However, the orientation 154 * may drift somewhat over time. 155 * </p> 156 * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} for more 157 * details. 158 */ 159 160 public static final int TYPE_GAME_ROTATION_VECTOR = 15; 161 162 /** 163 * A constant describing an uncalibrated gyroscope sensor type. 164 * <p>Similar to {@link #TYPE_GYROSCOPE} but no gyro-drift compensation has been performed 165 * to adjust the given sensor values. However, such gyro-drift bias values 166 * are returned to you separately in the result {@link android.hardware.SensorEvent#values} 167 * so you may use them for custom calibrations. 168 * <p>Factory calibration and temperature compensation is still applied 169 * to the rate of rotation (angular speeds). 170 * </p> 171 * <p> See {@link android.hardware.SensorEvent#values SensorEvent.values} for more 172 * details. 173 */ 174 public static final int TYPE_GYROSCOPE_UNCALIBRATED = 16; 175 176 /** 177 * A constant describing the significant motion trigger sensor. 178 * <p> 179 * It triggers when an event occurs and then automatically disables 180 * itself. The sensor continues to operate while the device is asleep 181 * and will automatically wake the device to notify when significant 182 * motion is detected. The application does not need to hold any wake 183 * locks for this sensor to trigger. 184 * <p>See {@link TriggerEvent} for more details. 185 */ 186 public static final int TYPE_SIGNIFICANT_MOTION = 17; 187 188 /** 189 * A constant describing all sensor types. 190 */ 191 public static final int TYPE_ALL = -1; 192 193 /* Reporting mode constants for sensors. Each sensor will have exactly one 194 reporting mode associated with it. */ 195 // Events are reported at a constant rate. 196 static int REPORTING_MODE_CONTINUOUS = 1; 197 198 // Events are reported only when the value changes. 199 static int REPORTING_MODE_ON_CHANGE = 2; 200 201 // Upon detection of an event, the sensor deactivates itself and then sends a single event. 202 static int REPORTING_MODE_ONE_SHOT = 3; 203 204 // TODO(): The following arrays are fragile and error-prone. This needs to be refactored. 205 206 // Note: This needs to be updated, whenever a new sensor is added. 207 // Holds the reporting mode and maximum length of the values array 208 // associated with 209 // {@link SensorEvent} or {@link TriggerEvent} for the Sensor 210 private static final int[] sSensorReportingModes = { 211 0, 0, // padding because sensor types start at 1 212 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_ACCELEROMETER 213 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_GEOMAGNETIC_FIELD 214 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_ORIENTATION 215 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_GYROSCOPE 216 REPORTING_MODE_ON_CHANGE, 3, // SENSOR_TYPE_LIGHT 217 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_PRESSURE 218 REPORTING_MODE_ON_CHANGE, 3, // SENSOR_TYPE_TEMPERATURE 219 REPORTING_MODE_ON_CHANGE, 3, // SENSOR_TYPE_PROXIMITY 220 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_GRAVITY 221 REPORTING_MODE_CONTINUOUS, 3, // SENSOR_TYPE_LINEAR_ACCELERATION 222 REPORTING_MODE_CONTINUOUS, 5, // SENSOR_TYPE_ROTATION_VECTOR 223 REPORTING_MODE_ON_CHANGE, 3, // SENSOR_TYPE_RELATIVE_HUMIDITY 224 REPORTING_MODE_ON_CHANGE, 3, // SENSOR_TYPE_AMBIENT_TEMPERATURE 225 REPORTING_MODE_CONTINUOUS, 6, // SENSOR_TYPE_MAGNETIC_FIELD_UNCALIBRATED 226 REPORTING_MODE_CONTINUOUS, 4, // SENSOR_TYPE_GAME_ROTATION_VECTOR 227 REPORTING_MODE_CONTINUOUS, 6, // SENSOR_TYPE_GYROSCOPE_UNCALIBRATED 228 REPORTING_MODE_ONE_SHOT, 1, // SENSOR_TYPE_SIGNIFICANT_MOTION 229 // added post 4.3 230 REPORTING_MODE_ON_CHANGE, 1, // SENSOR_TYPE_STEP_DETECTOR 231 REPORTING_MODE_ON_CHANGE, 1, // SENSOR_TYPE_STEP_COUNTER 232 REPORTING_MODE_CONTINUOUS, 5 // SENSOR_TYPE_GEOMAGNETIC_ROTATION_VECTOR 233 }; 234 235 static int getReportingMode(Sensor sensor) { 236 int offset = sensor.mType * 2; 237 if (offset >= sSensorReportingModes.length) { 238 // we don't know about this sensor, so this is probably a 239 // vendor-defined sensor, in that case, we figure out the reporting 240 // mode from the sensor meta-data. 241 int minDelay = sensor.mMinDelay; 242 if (minDelay == 0) { 243 return REPORTING_MODE_ON_CHANGE; 244 } else if (minDelay < 0) { 245 return REPORTING_MODE_ONE_SHOT; 246 } else { 247 return REPORTING_MODE_CONTINUOUS; 248 } 249 } 250 return sSensorReportingModes[offset]; 251 } 252 253 static int getMaxLengthValuesArray(Sensor sensor, int sdkLevel) { 254 int type = sensor.mType; 255 // RotationVector length has changed to 3 to 5 for API level 18 256 // Set it to 3 for backward compatibility. 257 if (type == Sensor.TYPE_ROTATION_VECTOR && 258 sdkLevel <= Build.VERSION_CODES.JELLY_BEAN_MR1) { 259 return 3; 260 } 261 int offset = type * 2 + 1; 262 if (offset >= sSensorReportingModes.length) { 263 // we don't know about this sensor, so this is probably a 264 // vendor-defined sensor, in that case, we don't know how many value 265 // it has 266 // so we return the maximum and assume the app will know. 267 // FIXME: sensor HAL should advertise how much data is returned per 268 // sensor 269 return 16; 270 } 271 return sSensorReportingModes[offset]; 272 } 273 274 /* Some of these fields are set only by the native bindings in 275 * SensorManager. 276 */ 277 private String mName; 278 private String mVendor; 279 private int mVersion; 280 private int mHandle; 281 private int mType; 282 private float mMaxRange; 283 private float mResolution; 284 private float mPower; 285 private int mMinDelay; 286 287 Sensor() { 288 } 289 290 /** 291 * @return name string of the sensor. 292 */ 293 public String getName() { 294 return mName; 295 } 296 297 /** 298 * @return vendor string of this sensor. 299 */ 300 public String getVendor() { 301 return mVendor; 302 } 303 304 /** 305 * @return generic type of this sensor. 306 */ 307 public int getType() { 308 return mType; 309 } 310 311 /** 312 * @return version of the sensor's module. 313 */ 314 public int getVersion() { 315 return mVersion; 316 } 317 318 /** 319 * @return maximum range of the sensor in the sensor's unit. 320 */ 321 public float getMaximumRange() { 322 return mMaxRange; 323 } 324 325 /** 326 * @return resolution of the sensor in the sensor's unit. 327 */ 328 public float getResolution() { 329 return mResolution; 330 } 331 332 /** 333 * @return the power in mA used by this sensor while in use 334 */ 335 public float getPower() { 336 return mPower; 337 } 338 339 /** 340 * @return the minimum delay allowed between two events in microsecond 341 * or zero if this sensor only returns a value when the data it's measuring 342 * changes. 343 */ 344 public int getMinDelay() { 345 return mMinDelay; 346 } 347 348 /** @hide */ 349 public int getHandle() { 350 return mHandle; 351 } 352 353 void setRange(float max, float res) { 354 mMaxRange = max; 355 mResolution = res; 356 } 357 358 @Override 359 public String toString() { 360 return "{Sensor name=\"" + mName + "\", vendor=\"" + mVendor + "\", version=" + mVersion 361 + ", type=" + mType + ", maxRange=" + mMaxRange + ", resolution=" + mResolution 362 + ", power=" + mPower + ", minDelay=" + mMinDelay + "}"; 363 } 364} 365