Sensor.java revision 92053f8b28ce0d035d292fa73622200990682511
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 private static int[] sSensorReportingModes = { 208 REPORTING_MODE_CONTINUOUS, REPORTING_MODE_CONTINUOUS, REPORTING_MODE_CONTINUOUS, 209 REPORTING_MODE_CONTINUOUS, REPORTING_MODE_ON_CHANGE, REPORTING_MODE_CONTINUOUS, 210 REPORTING_MODE_ON_CHANGE, REPORTING_MODE_ON_CHANGE, REPORTING_MODE_CONTINUOUS, 211 REPORTING_MODE_CONTINUOUS, REPORTING_MODE_CONTINUOUS, REPORTING_MODE_ON_CHANGE, 212 REPORTING_MODE_ON_CHANGE, REPORTING_MODE_CONTINUOUS, REPORTING_MODE_CONTINUOUS, 213 REPORTING_MODE_CONTINUOUS, REPORTING_MODE_ONE_SHOT }; 214 215 // Note: This needs to be updated, whenever a new sensor is added. 216 // Holds the maximum length of the values array associated with {@link SensorEvent} or 217 // {@link TriggerEvent} for the Sensor 218 private static int[] sMaxLengthValuesArray = { 219 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 5, 3, 3, 220 6, 4, 6, 1 }; 221 222 static int getReportingMode(Sensor sensor) { 223 // mType starts from offset 1. 224 return sSensorReportingModes[sensor.mType - 1]; 225 } 226 227 static int getMaxLengthValuesArray(Sensor sensor, int sdkLevel) { 228 // mType starts from offset 1. 229 int len = sMaxLengthValuesArray[sensor.mType - 1]; 230 231 // RotationVector length has changed to 3 to 5 for API level 18 232 // Set it to 3 for backward compatibility. 233 if (sensor.getType() == Sensor.TYPE_ROTATION_VECTOR && 234 sdkLevel <= Build.VERSION_CODES.JELLY_BEAN_MR1) { 235 len = 3; 236 } 237 return len; 238 } 239 240 /* Some of these fields are set only by the native bindings in 241 * SensorManager. 242 */ 243 private String mName; 244 private String mVendor; 245 private int mVersion; 246 private int mHandle; 247 private int mType; 248 private float mMaxRange; 249 private float mResolution; 250 private float mPower; 251 private int mMinDelay; 252 253 Sensor() { 254 } 255 256 /** 257 * @return name string of the sensor. 258 */ 259 public String getName() { 260 return mName; 261 } 262 263 /** 264 * @return vendor string of this sensor. 265 */ 266 public String getVendor() { 267 return mVendor; 268 } 269 270 /** 271 * @return generic type of this sensor. 272 */ 273 public int getType() { 274 return mType; 275 } 276 277 /** 278 * @return version of the sensor's module. 279 */ 280 public int getVersion() { 281 return mVersion; 282 } 283 284 /** 285 * @return maximum range of the sensor in the sensor's unit. 286 */ 287 public float getMaximumRange() { 288 return mMaxRange; 289 } 290 291 /** 292 * @return resolution of the sensor in the sensor's unit. 293 */ 294 public float getResolution() { 295 return mResolution; 296 } 297 298 /** 299 * @return the power in mA used by this sensor while in use 300 */ 301 public float getPower() { 302 return mPower; 303 } 304 305 /** 306 * @return the minimum delay allowed between two events in microsecond 307 * or zero if this sensor only returns a value when the data it's measuring 308 * changes. 309 */ 310 public int getMinDelay() { 311 return mMinDelay; 312 } 313 314 /** @hide */ 315 public int getHandle() { 316 return mHandle; 317 } 318 319 void setRange(float max, float res) { 320 mMaxRange = max; 321 mResolution = res; 322 } 323 324 @Override 325 public String toString() { 326 return "{Sensor name=\"" + mName + "\", vendor=\"" + mVendor + "\", version=" + mVersion 327 + ", type=" + mType + ", maxRange=" + mMaxRange + ", resolution=" + mResolution 328 + ", power=" + mPower + ", minDelay=" + mMinDelay + "}"; 329 } 330} 331