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