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