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