1/*
2 * Copyright (C) 2016 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
17package android.hardware;
18
19import android.annotation.IntDef;
20
21import java.lang.annotation.Retention;
22import java.lang.annotation.RetentionPolicy;
23
24/**
25 * This class represents a {@link android.hardware.Sensor Sensor} additional information frame,
26 * which is reported through listener callback {@link
27 * android.hardware.SensorEventCallback#onSensorAdditionalInfo onSensorAdditionalInfo}.
28 *
29 * @see SensorManager
30 * @see SensorEventCallback
31 * @see Sensor
32 *
33 */
34
35public class SensorAdditionalInfo {
36
37    /**
38     * The sensor that generated this event. See
39     * {@link android.hardware.SensorManager SensorManager} for details.
40     */
41    public final Sensor sensor;
42
43    /**
44     * Type of this additional info frame.
45     */
46    public final int type;
47
48    /**
49     * Sequence number of frame for a certain type.
50     */
51    public final int serial;
52
53    /**
54     * Additional info payload data represented in float values. Depending on the type of
55     * information, this may be null.
56     */
57    public final float[] floatValues;
58
59    /**
60     * Additional info payload data represented in int values. Depending on the type of information,
61     * this may be null.
62     */
63    public final int[] intValues;
64
65    /**
66     * Typical values of additional infomation type. The set of values is subject to extension in
67     * newer versions and vendors have the freedom of define their own custom values.
68     *
69     * @hide
70     */
71    @IntDef({TYPE_FRAME_BEGIN, TYPE_FRAME_END, TYPE_UNTRACKED_DELAY, TYPE_INTERNAL_TEMPERATURE,
72             TYPE_VEC3_CALIBRATION, TYPE_SENSOR_PLACEMENT, TYPE_SAMPLING})
73    @Retention(RetentionPolicy.SOURCE)
74    public @interface AdditionalInfoType {}
75
76    /**
77     * Mark the beginning of a set of additional info frames.
78     */
79    public static final int TYPE_FRAME_BEGIN = 0;
80
81    /**
82     * Mark the end of a set of additional info frames.
83     */
84    public static final int TYPE_FRAME_END = 1;
85
86    /**
87     * Untracked delay. Delays that are introduced by data processing, such as filtering, which is
88     * not taken into account by sensor timestamps.
89     *
90     * Payload:
91     *     floatValues[0]: delay estimation in seconds
92     *     floatValues[1]: delay estimation standard deviation
93     */
94    public static final int TYPE_UNTRACKED_DELAY = 0x10000;
95
96    /**
97     * Internal temperature. Sensor hardware device internal temperature.
98     *
99     * Payload:
100     *     floatValues[0]: internal temperature in Celsius.
101     */
102    public static final int TYPE_INTERNAL_TEMPERATURE = 0x10001;
103
104    /**
105     * Vector calibration parameter. Calibration applied to a sensor with 3 elements vector output,
106     * such as accelerometer, gyro, etc.
107     *
108     * Payload:
109     *     floatValues[0..11]: First 3 rows of a homogeneous matrix in row major order that captures
110     *     any linear transformation, including rotation, scaling, shear, shift.
111     */
112    public static final int TYPE_VEC3_CALIBRATION = 0x10002;
113
114    /**
115     * Sensor placement. Describes location and installation angle of the sensor device.
116     *
117     * Payload:
118     *     floatValues[0..11]: First 3 rows of homogeneous matrix in row major order that describes
119     *     the location and orientation of the sensor. Origin of reference will be the mobile device
120     *     geometric sensor. Reference frame is defined as the same as Android sensor frame.
121     */
122    public static final int TYPE_SENSOR_PLACEMENT = 0x10003;
123
124    /**
125     * Sampling parameter. Describes the raw sample period and estimated jitter of sample time in
126     * terms of standard deviation.
127     *
128     * Payload:
129     *     floatValues[0]: raw sample period in seconds.
130     *     floatValues[1]: standard deviation of sampling period.
131     */
132    public static final int TYPE_SAMPLING = 0x10004;
133
134    /**
135     * Local geo-magnetic Field.
136     *
137     * Additional into to sensor hardware.  Local geomagnetic field information based on
138     * device geo location. This type is primarily for for magnetic field calibration and rotation
139     * vector sensor fusion.
140     *
141     * float[3]: strength (uT), declination and inclination angle (rad).
142     * @hide
143     */
144    public static final int TYPE_LOCAL_GEOMAGNETIC_FIELD = 0x30000;
145
146    /**
147     * Local gravity acceleration strength.
148     *
149     * Additional info to sensor hardware for accelerometer calibration.
150     *
151     * float: gravitational acceleration norm in m/s^2.
152     * @hide
153     */
154    public static final int TYPE_LOCAL_GRAVITY = 0x30001;
155
156    /**
157     * Device dock state.
158     *
159     * Additional info to sensor hardware indicating dock states of device.
160     *
161     * int32_t: dock state following definition of {@link android.content.Intent#EXTRA_DOCK_STATE}.
162     *          Undefined values are ignored.
163     * @hide
164     */
165    public static final int TYPE_DOCK_STATE = 0x30002;
166
167    /**
168     * High performance mode.
169     *
170     * Additional info to sensor hardware. Device is able to use up more power and take more
171     * resources to improve throughput and latency in high performance mode. One possible use case
172     * is virtual reality, when sensor latency need to be carefully controlled.
173     *
174     * int32_t: 1 or 0, denoting device is in or out of high performance mode, respectively.
175     *          Other values are ignored.
176     * @hide
177     */
178    public static final int TYPE_HIGH_PERFORMANCE_MODE = 0x30003;
179
180    /**
181     * Magnetic field calibration hint.
182     *
183     * Additional info to sensor hardware. Device is notified when manually triggered magnetic field
184     * calibration procedure is started or stopped. The calibration procedure is assumed timed out
185     * after 1 minute from start, even if an explicit stop is not received.
186     *
187     * int32_t: 1 for calibration start, 0 for stop, other values are ignored.
188     * @hide
189     */
190    public static final int TYPE_MAGNETIC_FIELD_CALIBRATION = 0x30004;
191
192    SensorAdditionalInfo(
193            Sensor aSensor, int aType, int aSerial, int [] aIntValues, float [] aFloatValues) {
194        sensor = aSensor;
195        type = aType;
196        serial = aSerial;
197        intValues = aIntValues;
198        floatValues = aFloatValues;
199    }
200
201    /** @hide */
202    public static SensorAdditionalInfo createLocalGeomagneticField(
203            float strength, float declination, float inclination) {
204        if (strength < 10 || strength > 100 // much beyond extreme values on earth
205                || declination < 0 || declination > Math.PI
206                || inclination < -Math.PI / 2 || inclination > Math.PI / 2) {
207            throw new IllegalArgumentException("Geomagnetic field info out of range");
208        }
209
210        return new SensorAdditionalInfo(
211                null, TYPE_LOCAL_GEOMAGNETIC_FIELD, 0,
212                null, new float[] { strength, declination, inclination});
213    }
214}
215