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 17 package android.hardware; 18 19 import android.annotation.IntDef; 20 21 import java.lang.annotation.Retention; 22 import 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 35 public 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
