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(prefix = { "TYPE_" }, value = { 72 TYPE_FRAME_BEGIN, 73 TYPE_FRAME_END, 74 TYPE_UNTRACKED_DELAY, 75 TYPE_INTERNAL_TEMPERATURE, 76 TYPE_VEC3_CALIBRATION, 77 TYPE_SENSOR_PLACEMENT, 78 TYPE_SAMPLING 79 }) 80 @Retention(RetentionPolicy.SOURCE) 81 public @interface AdditionalInfoType {} 82 83 /** 84 * Mark the beginning of a set of additional info frames. 85 */ 86 public static final int TYPE_FRAME_BEGIN = 0; 87 88 /** 89 * Mark the end of a set of additional info frames. 90 */ 91 public static final int TYPE_FRAME_END = 1; 92 93 /** 94 * Untracked delay. Delays that are introduced by data processing, such as filtering, which is 95 * not taken into account by sensor timestamps. 96 * 97 * Payload: 98 * floatValues[0]: delay estimation in seconds 99 * floatValues[1]: delay estimation standard deviation 100 */ 101 public static final int TYPE_UNTRACKED_DELAY = 0x10000; 102 103 /** 104 * Internal temperature. Sensor hardware device internal temperature. 105 * 106 * Payload: 107 * floatValues[0]: internal temperature in Celsius. 108 */ 109 public static final int TYPE_INTERNAL_TEMPERATURE = 0x10001; 110 111 /** 112 * Vector calibration parameter. Calibration applied to a sensor with 3 elements vector output, 113 * such as accelerometer, gyro, etc. 114 * 115 * Payload: 116 * floatValues[0..11]: First 3 rows of a homogeneous matrix in row major order that captures 117 * any linear transformation, including rotation, scaling, shear, shift. 118 */ 119 public static final int TYPE_VEC3_CALIBRATION = 0x10002; 120 121 /** 122 * Sensor placement. 123 * 124 * Provides the orientation and location of the sensor element in terms of the 125 * Android coordinate system. This data is given as a 3x4 matrix consisting of a 3x3 rotation 126 * matrix (R) concatenated with a 3x1 location vector (t). The rotation matrix provides the 127 * orientation of the Android device coordinate frame relative to the local coordinate frame of 128 * the sensor. Note that assuming the axes conventions of the sensor are the same as Android, 129 * this is the inverse of the matrix applied to raw samples read from the sensor to convert them 130 * into the Android representation. The location vector represents the translation from the 131 * origin of the Android sensor coordinate system to the geometric center of the sensor, 132 * specified in millimeters (mm). 133 * <p> 134 * <b>Payload</b>: 135 * <code>floatValues[0..11]</code>: 3x4 matrix in row major order [R; t] 136 * </p> 137 * <p> 138 * <b>Example</b>: 139 * This raw buffer: <code>{0, 1, 0, 0, -1, 0, 0, 10, 0, 0, 1, -2.5}</code><br> 140 * Corresponds to this 3x4 matrix: 141 * <table> 142 * <thead> 143 * <tr><td colspan="3">Orientation</td><td>Location</tr> 144 * </thead> 145 * <tbody> 146 * <tr><td>0</td><td>1</td><td>0</td><td>0</td></tr> 147 * <tr><td>-1</td><td>0</td><td>0</td><td>10</td></tr> 148 * <tr><td>0</td><td>0</td><td>1</td><td>-2.5</td></tr> 149 * </tbody> 150 * </table> 151 * The sensor is oriented such that: 152 * <ul> 153 * <li>The device X axis corresponds to the sensor's local -Y axis 154 * <li>The device Y axis corresponds to the sensor's local X axis 155 * <li>The device Z axis and sensor's local Z axis are equivalent 156 * </ul> 157 * In other words, if viewing the origin of the Android coordinate system from the positive 158 * Z direction, the device coordinate frame is to be rotated 90° counter-clockwise about the 159 * Z axis to align with the sensor's local coordinate frame. Equivalently, a vector in the 160 * Android coordinate frame may be multiplied with R to rotate it 90° clockwise (270° 161 * counter-clockwise), yielding its representation in the sensor's coordinate frame. 162 * Relative to the origin of the Android coordinate system, the physical center of the 163 * sensor is located 10mm in the positive Y direction, and 2.5mm in the negative Z 164 * direction. 165 * </p> 166 */ 167 public static final int TYPE_SENSOR_PLACEMENT = 0x10003; 168 169 /** 170 * Sampling parameter. Describes the raw sample period and estimated jitter of sample time in 171 * terms of standard deviation. 172 * 173 * Payload: 174 * floatValues[0]: raw sample period in seconds. 175 * floatValues[1]: standard deviation of sampling period. 176 */ 177 public static final int TYPE_SAMPLING = 0x10004; 178 179 /** 180 * Local geo-magnetic Field. 181 * 182 * Additional into to sensor hardware. Local geomagnetic field information based on 183 * device geo location. This type is primarily for for magnetic field calibration and rotation 184 * vector sensor fusion. 185 * 186 * float[3]: strength (uT), declination and inclination angle (rad). 187 * @hide 188 */ 189 public static final int TYPE_LOCAL_GEOMAGNETIC_FIELD = 0x30000; 190 191 /** 192 * Local gravity acceleration strength. 193 * 194 * Additional info to sensor hardware for accelerometer calibration. 195 * 196 * float: gravitational acceleration norm in m/s^2. 197 * @hide 198 */ 199 public static final int TYPE_LOCAL_GRAVITY = 0x30001; 200 201 /** 202 * Device dock state. 203 * 204 * Additional info to sensor hardware indicating dock states of device. 205 * 206 * int32_t: dock state following definition of {@link android.content.Intent#EXTRA_DOCK_STATE}. 207 * Undefined values are ignored. 208 * @hide 209 */ 210 public static final int TYPE_DOCK_STATE = 0x30002; 211 212 /** 213 * High performance mode. 214 * 215 * Additional info to sensor hardware. Device is able to use up more power and take more 216 * resources to improve throughput and latency in high performance mode. One possible use case 217 * is virtual reality, when sensor latency need to be carefully controlled. 218 * 219 * int32_t: 1 or 0, denoting device is in or out of high performance mode, respectively. 220 * Other values are ignored. 221 * @hide 222 */ 223 public static final int TYPE_HIGH_PERFORMANCE_MODE = 0x30003; 224 225 /** 226 * Magnetic field calibration hint. 227 * 228 * Additional info to sensor hardware. Device is notified when manually triggered magnetic field 229 * calibration procedure is started or stopped. The calibration procedure is assumed timed out 230 * after 1 minute from start, even if an explicit stop is not received. 231 * 232 * int32_t: 1 for calibration start, 0 for stop, other values are ignored. 233 * @hide 234 */ 235 public static final int TYPE_MAGNETIC_FIELD_CALIBRATION = 0x30004; 236 237 /** 238 * Custom sensor info: array of float values interpreted by sensor based on the type 239 * Any type between TYPE_CUSTOM_INFO <= info_type < TYPE_DEBUG_INFO may be 240 * used to send custom sensor info. 241 * @hide 242 */ 243 public static final int TYPE_CUSTOM_INFO = 0x10000000; 244 /** @hide */ 245 public static final int TYPE_DEBUG_INFO = 0x40000000; 246 SensorAdditionalInfo( Sensor aSensor, int aType, int aSerial, int[] aIntValues, float[] aFloatValues)247 SensorAdditionalInfo( 248 Sensor aSensor, int aType, int aSerial, int[] aIntValues, float[] aFloatValues) { 249 sensor = aSensor; 250 type = aType; 251 serial = aSerial; 252 intValues = aIntValues; 253 floatValues = aFloatValues; 254 } 255 256 /** @hide */ createLocalGeomagneticField( float strength, float declination, float inclination)257 public static SensorAdditionalInfo createLocalGeomagneticField( 258 float strength, float declination, float inclination) { 259 if (strength < 10 || strength > 100 // much beyond extreme values on earth 260 || declination < 0 || declination > Math.PI 261 || inclination < -Math.PI / 2 || inclination > Math.PI / 2) { 262 throw new IllegalArgumentException("Geomagnetic field info out of range"); 263 } 264 265 return new SensorAdditionalInfo( 266 null, TYPE_LOCAL_GEOMAGNETIC_FIELD, 0, 267 null, new float[] { strength, declination, inclination}); 268 } 269 /** @hide */ createCustomInfo(Sensor aSensor, int type, float[] data)270 public static SensorAdditionalInfo createCustomInfo(Sensor aSensor, int type, float[] data) { 271 if (type < TYPE_CUSTOM_INFO || type >= TYPE_DEBUG_INFO || aSensor == null) { 272 throw new IllegalArgumentException( 273 "invalid parameter(s): type: " + type + "; sensor: " + aSensor); 274 } 275 276 return new SensorAdditionalInfo(aSensor, type, 0, null, data); 277 } 278 } 279